search_notes

Overview

search_notes returns notes matching a keyword together with their primary documents (one-pager, custom). Use it when you need the content of the notes, such as decisions or action items. For lightweight metadata-only listing (e.g., “which notes are in folder X”), use list_notes instead. When to use

“What did the team decide about OKR Q2?”
“Where is the source note for this decision?”
“Show me the notes that mention 네이버.”

How it works

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.
When the search index is unavailable, a normal response is returned with degraded: true, an empty notes array, and degradedReason.

A workspace-scoped API key drops notes in private folders from the results even when the keyword matches (What notes a system API key reads).

Heavier than list_notes. Each result includes document content (~1,500 tokens per note). Default page size is 10, max 30. 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 `10`, max `30`).
`workspaceGuid`	string	Optional	Workspace GUID (from `list_workspaces`). Omit to search across every workspace you can access. A workspace-scoped API key searches only the workspace it is connected to.
`filter.folderId`	string	Optional	Restrict to a folder (includes descendant folders).
`filter.createdAtFrom`	string	Optional	ISO 8601 UTC datetime ending in `Z`, inclusive lower bound on `createdAt`.
`filter.createdAtTo`	string	Optional	ISO 8601 UTC datetime ending in `Z`, 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 API key searches only the workspace it is connected to. To scope the search to a specific workspace, pass a workspaceGuid.

filter.folderId (optional)

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

filter.createdAtFrom / filter.createdAtTo (optional)

Half-open [from, to) range filter on createdAt. Both accept ISO 8601 UTC datetime ending in Z. It is applied before the relevance-ranked result limit. For calendar years, months, or days, convert the boundaries from the user’s timezone to UTC. For example, July–August 2025 in Korea Standard Time is createdAtFrom: "2025-06-30T15:00:00Z", createdAtTo: "2025-08-31T15:00:00Z".

pagination (optional)

{ cursor, size }. Default size: 10, max 30. 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

keyword must be at least 1 character (zod min(1)). An empty keyword is rejected as a standard MCP validation error, not a custom error code.

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

Voice File

Webhooks

MCP

CLI

Developer Resources

Overview

Parameters

keyword (required)

filter.folderId (optional)

filter.createdAtFrom / filter.createdAtTo (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)

​filter.createdAtFrom / filter.createdAtTo (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)

filter.createdAtFrom / filter.createdAtTo (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