search_notes

Overview

search_notes is the deep tier of note discovery. It takes a required keyword and returns matching notes hydrated with their primary documents (one-pager, custom). Use this when the LLM needs to understand the context behind a topic — its decisions, action items, or conclusions — not just see which notes match. For lightweight metadata-only listing (e.g., “which notes are in folder X”), use list_notes instead. Primary Use Cases:

“What did the team decide about OKR Q2?” — search by topic, read documents inline.
“Where is the source note for this decision?” — keyword finds the note, documents give the context.
“Show me everything we wrote about 네이버” — Korean keyword search with content.

Key Features:

Keyword required; results ordered by full-text relevance with createdAt desc as tiebreaker.
Each matched note carries its primary documents inline (one-pager, custom).
HTML stripped from document content; documents larger than 5,000 chars are truncated and flagged.
Graceful degradation when the search index is unavailable.

A workspace-scoped API key narrows the results. A workspace-scoped key searches only notes in folders shared with all members, so a note in a private folder drops out of the results even when your keyword matches it. Use a user-scoped key if you need to search notes in private folders too (What notes a system key reads).

Heavier than list_notes. Each result includes document content (~1,500 tokens per note). Default page size is 50, max 200. If you only need metadata, use list_notes.

Parameters

Parameter	Type	Required	Description
`keyword`	string	Yes	Search keyword (≥1 char). Full-text matched against title and paragraph content.
`pagination.cursor`	string	Optional	Reserved for future use; the deep-search endpoint currently emits `null`.
`pagination.size`	number	Optional	Results per page (default `50`, max `200`).
`workspaceGuid`	string	Optional	Workspace GUID (from `list_workspaces`). Omit to search across every workspace you can access — a workspace-scoped key automatically searches its own workspace; pass one to scope the search to a single workspace.
`filter.folderId`	string	Optional	Restrict to a folder (recursive — includes descendant folders).
`filter.createdAtFrom`	string	Optional	ISO 8601 datetime, inclusive lower bound on `createdAt`.
`filter.createdAtTo`	string	Optional	ISO 8601 datetime, exclusive upper bound on `createdAt`.

keyword (required)

The search term. Tokenized server-side; Korean text is morphologically analyzed (e.g., 네이버 → [네, 버]). Empty or whitespace-only keywords return 400. Keyword search accepts both user-scoped and workspace-scoped API keys. Omit workspaceGuid to search across every workspace you can access — a workspace-scoped key automatically searches its own workspace. Pass an explicit workspaceGuid (see Parameters) to scope the search to a specific workspace.

filter.folderId (optional)

Same semantics as list_notes — recursive folder scope, authorized server-side.

pagination (optional)

{ cursor, size }. Default size: 50, max 200. The cap reflects the higher per-result cost (each note carries its documents).

Response Format

Success Response

{
  "notes": [
    {
      "noteGuid": "abc-123-def",
      "title": "OKR Q2 Planning",
      "webUrl": "https://platform.tiro.ooo/notes/abc-123-def",
      "createdAt": "2026-04-15T10:00:00Z",
      "updatedAt": "2026-04-15T11:30:00Z",
      "recordingDurationSeconds": 3625,
      "sourceType": "live-voice",
      "participants": [
        { "name": "Alice Kim", "email": "alice@example.com" }
      ],
      "matchedSnippets": null,
      "documents": [
        {
          "documentGuid": "7821",
          "templateId": 12,
          "templateTitle": "One Pager",
          "content": "## 결정 사항\n- 자동 ingest 우선...\n## Action Items\n- ...",
          "truncated": false,
          "updatedAt": "2026-04-15T11:30:00Z"
        }
      ]
    }
  ],
  "nextCursor": null,
  "degraded": false,
  "degradedReason": null
}

Field Descriptions:

Field	Type	Description
`notes[]`	array	Matched notes, ordered by full-text relevance with `createdAt` desc as tiebreaker.
`notes[].matchedSnippets`	string[] \| null	Reserved for highlight snippets. Currently `null` — distinguishes “highlights not yet implemented” from “searched, no highlights matched”.
`notes[].documents[]`	array	Note’s primary documents. Empty array when the note has no documents.
`notes[].documents[].documentGuid`	string	Stable document identifier.
`notes[].documents[].templateId`	number \| null	Numeric template id — the only stable discriminator.
`notes[].documents[].templateTitle`	string	Display label (e.g., `"One Pager"`, `"회의록"`). Locale-sensitive and user-editable for custom templates — do NOT discriminate on this string.
`notes[].documents[].content`	string	HTML-stripped, markdown-friendly text. Capped at 5,000 chars; see `truncated`.
`notes[].documents[].truncated`	boolean	`true` when content was truncated. Fetch the full document via `get_note(include: ['documents'])` if you need the rest.
`nextCursor`	string \| null	Reserved for future use; currently always `null`.
`degraded`	boolean	`true` when the search index was unavailable or failed.
`degradedReason`	string \| null	When `degraded=true`: `"search_index_unavailable"` or `"search_index_degraded"`.

Don’t discriminate on templateTitle. It’s a display label, not an enum. For boolean checks (“is this a one-pager?”) use templateId against a known managed-template id, or surface both fields and let your UI choose by label.

Degraded Response

When the search index is unavailable, the response sets degraded=true and returns an empty notes array:

{
  "notes": [],
  "nextCursor": null,
  "degraded": true,
  "degradedReason": "search_index_unavailable"
}

degradedReason is one of:

search_index_unavailable — the search index is disabled in this environment.
search_index_degraded — the search index threw an error mid-query.

Surface this to the LLM/user so retries can be deferred or the result interpreted appropriately.

Usage Examples

Example 1: Topical search

Request:

{
  "keyword": "OKR"
}

Returns the 10 most relevant notes mentioning OKR, each with its primary documents inline.

Example 2: Folder-scoped Korean keyword

Request:

{
  "keyword": "네이버",
  "filter": {
    "folderId": "455765"
  },
  "pagination": {
    "size": 5
  }
}

Searches 네이버 only inside folder 455765 (and descendants). Korean morphological analysis runs server-side.

Example 3: Date-bounded deep search

Request:

{
  "keyword": "release",
  "filter": {
    "createdAtFrom": "2026-04-01T00:00:00Z",
    "createdAtTo": "2026-05-01T00:00:00Z"
  }
}

Best Practices

Start with list_notes, switch to search_notes when content is needed

Use list_notes first to find which notes match. If the LLM still needs document content to answer, switch to search_notes for the same keyword. This is the cheapest progressive-disclosure path.

Use folderId to narrow the search universe

A folder-scoped search is faster and returns better-ranked results because the relevance space is smaller. Pair with list_notes(filter.folderId) to find folder candidates first.

Don't loop on `nextCursor`

The deep-search endpoint currently emits nextCursor: null. If 30 results aren’t enough, refine the keyword (more specific) or scope by folderId/dateRange instead of paginating.

Watch the `degraded` flag

A degraded=true response is honest — the search index couldn’t run. Don’t treat the empty notes array as “no matches”; instead, surface the degradation to the user/LLM so retries can be timed appropriately.

Common Errors

Empty keyword

Token Usage

Per Note (with documents): ~1,500 tokens average. Truncated documents cap at ~1,500 tokens regardless of source size.

Compared to get_note_transcript (~3,000–5,000 tokens per hour of meeting), search_notes returns curated documents that are typically 10× more compact and cover the same key decisions. Reach for transcripts only when you need exact spoken words.

Home

Getting Started

API

Webhooks

MCP

CLI

Developer Resources

Overview

Parameters

keyword (required)

filter.folderId (optional)

Response Format

Success Response

Degraded Response

Usage Examples

Example 1: Topical search

Example 2: Folder-scoped Korean keyword

Example 3: Date-bounded deep search

Best Practices

Common Errors

Empty keyword

Token Usage

​Overview

​Parameters

​keyword (required)

​filter.folderId (optional)

​pagination (optional)

​Response Format

​Success Response

​Degraded Response

​Usage Examples

​Example 1: Topical search

​Example 2: Folder-scoped Korean keyword

​Example 3: Date-bounded deep search

​Best Practices

​Common Errors

​Empty keyword

​Token Usage

Overview

Parameters

keyword (required)

filter.folderId (optional)

pagination (optional)

Response Format

Success Response

Degraded Response

Usage Examples

Example 1: Topical search

Example 2: Folder-scoped Korean keyword

Example 3: Date-bounded deep search

Best Practices

Common Errors

Empty keyword

Token Usage