search_notes

概要

search_notes は、キーワードに一致したノートを主要ドキュメント（ワンページャー、カスタム）とともに返します。決定事項やアクションアイテムなど、ノートの内容まで確認したいときに使用してください。軽量なメタデータのみの一覧表示（例: 「フォルダ X にはどのノートがありますか」）には、代わりに list_notes を使用してください。 使用する場面

「OKR Q2 についてチームは何を決めたのか?」
「この決定のソースノートはどこか?」
「네이버 に言及しているノートを見せて。」

動作

キーワード必須。結果は全文検索の関連度（同点の場合は createdAt の降順）で並べ替えられます。
一致した各ノートには、主要ドキュメント（ワンページャー、カスタム）がインラインで付きます。
ドキュメントのコンテンツから HTML を除去します。5,000 文字を超えるドキュメントは打ち切られ、フラグが付きます。
検索インデックスが利用できない場合は、通常のレスポンスに degraded: true、空の notes、degradedReason を含めて返します。

workspace-scoped key で呼び出すと、キーワードが一致していても個人フォルダのノートは結果から外れます（システムAPIキーが読み取るノートの範囲）。

list_notes より重い。 各結果にはドキュメントのコンテンツが含まれます（ノートあたり ~1,500 トークン）。デフォルトのページサイズは 10、最大 30 です。メタデータのみが必要な場合は list_notes を使用してください。

パラメータ

Parameter	Type	Required	Description
`keyword`	string	Yes	検索キーワード（1 文字以上）。タイトルと段落のコンテンツに対して全文一致します。
`pagination.cursor`	string	Optional	将来の使用のために予約。深い検索 endpoint は現在 `null` を返します。
`pagination.size`	number	Optional	1 ページあたりの結果数（デフォルト `10`、最大 `30`）。
`workspaceGuid`	string	Optional	ワークスペース GUID（`list_workspaces` から取得）。省略するとアクセスできるすべてのワークスペースを横断して検索します。workspace-scoped API key は接続されたワークスペースのみを検索します。
`filter.folderId`	string	Optional	フォルダに限定（子孫フォルダを含みます）。
`filter.createdAtFrom`	string	Optional	末尾が `Z` の ISO 8601 UTC 日時。`createdAt` の下限（その値を含む）。
`filter.createdAtTo`	string	Optional	末尾が `Z` の ISO 8601 UTC 日時。`createdAt` の上限（その値を含まない）。

keyword (required)

検索語です。サーバー側でトークン化され、韓国語テキストは形態素解析されます（例: 네이버 → [네, 버]）。空または空白のみのキーワードは 400 を返します。キーワード検索は、user-scoped と workspace-scoped のどちらの API key も受け付けます。workspaceGuid を省略するとアクセスできるすべてのワークスペースを横断して検索します。workspace-scoped API key は接続されたワークスペースのみを検索します。特定のワークスペースに限定するには workspaceGuid を渡してください。

filter.folderId (optional)

list_notes と同じ意味です。再帰的なフォルダ範囲で、サーバー側で認可されます。

filter.createdAtFrom / filter.createdAtTo (optional)

createdAt に対する半開区間 [from, to) の範囲フィルタです。どちらも末尾が Z の ISO 8601 UTC 日時を受け付けます。関連度順の検索結果件数が制限される前に適用されます。年・月・日の条件は、ユーザーのタイムゾーンの境界を UTC に変換してください。たとえば韓国標準時の 2025 年 7〜8 月は、createdAtFrom: "2025-06-30T15:00:00Z"、createdAtTo: "2025-08-31T15:00:00Z" です。

pagination (optional)

{ cursor, size }。デフォルト size: 10、最大 30。この上限は、結果あたりのコストが高いこと（各ノートがドキュメントを伴うこと）を反映しています。

レスポンス形式

成功レスポンス

{
  "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	Type	Description
`notes[]`	array	一致したノート。全文検索の関連度（同点の場合は `createdAt` の降順）で並べ替えられます。
`notes[].matchedSnippets`	string[] \| null	ハイライトスニペット用に予約。現在は `null` で、「ハイライトが未実装」と「検索したがハイライトが一致しなかった」を区別します。
`notes[].documents[]`	array	ノートの主要ドキュメント。ノートにドキュメントがない場合は空配列。
`notes[].documents[].documentGuid`	string	安定したドキュメント識別子。
`notes[].documents[].templateId`	number \| null	数値のテンプレート ID。唯一の安定した判別子です。
`notes[].documents[].templateTitle`	string	表示用ラベル（例: `"One Pager"`、`"회의록"`）。ロケール依存で、カスタムテンプレートではユーザーが編集可能です。この文字列で判別しないでください。
`notes[].documents[].content`	string	HTML 除去済み、Markdown 対応のテキスト。5,000 文字で打ち切り。`truncated` を参照。
`notes[].documents[].truncated`	boolean	コンテンツが打ち切られた場合は `true`。残りが必要な場合は `get_note(include: ['documents'])` でドキュメント全文を取得してください。
`nextCursor`	string \| null	将来の使用のために予約。現在は常に `null`。
`degraded`	boolean	検索インデックスが利用できなかった、または失敗した場合は `true`。
`degradedReason`	string \| null	`degraded=true` の場合: `"search_index_unavailable"` または `"search_index_degraded"`。

templateTitle で判別しないでください。 これは表示用ラベルであり、enum ではありません。ブール値のチェック（「これはワンページャーか?」）には、既知の管理済みテンプレート ID に対して templateId を使用するか、両方のフィールドを提示して UI にラベルで選ばせてください。

縮退レスポンス

検索インデックスが利用できない場合、レスポンスは degraded=true を設定し、空の notes 配列を返します。

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

degradedReason は次のいずれかです。

search_index_unavailable — この環境では検索インデックスが無効になっています。
search_index_degraded — クエリの途中で検索インデックスがエラーを投げました。

リトライを延期したり結果を適切に解釈したりできるよう、これを LLM／ユーザーに提示してください。

使用例

例 1: トピック検索

リクエスト:

{
  "keyword": "OKR"
}

OKR に言及する最も関連度の高いノート 10 件を、それぞれの主要ドキュメントをインラインで付けて返します。

例 2: フォルダ限定の韓国語キーワード

リクエスト:

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

フォルダ 455765（とその子孫）の中だけで 네이버 を検索します。韓国語の形態素解析はサーバー側で実行されます。

例 3: 日付で区切った深い検索

リクエスト:

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

ベストプラクティス

Start with list_notes, switch to search_notes when content is needed

まず list_notes を使って、どのノートが一致するかを見つけてください。LLM が答えるためにドキュメントの内容をなお必要とする場合は、同じキーワードで search_notes に切り替えます。これが最も安価な段階的開示のパスです。

Use folderId to narrow the search universe

フォルダ限定の検索は、関連度の空間が小さくなるため、より高速で、より良くランク付けされた結果を返します。まず list_notes(filter.folderId) と組み合わせてフォルダ候補を見つけてください。

Don't loop on nextCursor

深い検索 endpoint は現在 nextCursor: null を返します。30 件の結果で足りない場合は、ページネーションするのではなく、キーワードを絞り込む（より具体的に）か、folderId／dateRange で範囲を限定してください。

Watch the degraded flag

degraded=true のレスポンスは正直です。検索インデックスが実行できなかったのです。空の notes 配列を「一致なし」と扱わないでください。代わりに、リトライのタイミングを適切に計れるよう、縮退をユーザー／LLM に提示してください。

よくあるエラー

空のキーワード

keyword は最低 1 文字以上である必要があります（zod min(1)）。空のキーワードは、カスタムエラーコードではなく MCP 標準の validation エラーで拒否されます。

トークン使用量

ノートあたり（ドキュメント付き）: 平均 ~1,500 トークン。打ち切られたドキュメントは、元のサイズにかかわらず ~1,500 トークンで頭打ちになります。

get_note_transcript（会議 1 時間あたり ~3,000–5,000 トークン）と比べて、search_notes は通常 10 倍コンパクトで、同じ重要な決定事項をカバーする、整理されたドキュメントを返します。話された言葉そのものが必要なときにのみトランスクリプトを使ってください。

ホーム

はじめに

API

音声ファイル

Webhook

MCP

CLI

開発者リソース

概要

パラメータ

keyword (required)

filter.folderId (optional)

filter.createdAtFrom / filter.createdAtTo (optional)

レスポンス形式

成功レスポンス

縮退レスポンス

使用例

例 1: トピック検索

例 2: フォルダ限定の韓国語キーワード

例 3: 日付で区切った深い検索

ベストプラクティス

よくあるエラー

空のキーワード

トークン使用量

​概要

​パラメータ

​keyword (required)

​filter.folderId (optional)

​filter.createdAtFrom / filter.createdAtTo (optional)

​pagination (optional)

​レスポンス形式

​成功レスポンス

​縮退レスポンス

​使用例

​例 1: トピック検索

​例 2: フォルダ限定の韓国語キーワード

​例 3: 日付で区切った深い検索

​ベストプラクティス

​よくあるエラー

​空のキーワード

​トークン使用量

概要

パラメータ

keyword (required)

filter.folderId (optional)

filter.createdAtFrom / filter.createdAtTo (optional)

pagination (optional)

レスポンス形式

成功レスポンス

縮退レスポンス

使用例

例 1: トピック検索

例 2: フォルダ限定の韓国語キーワード

例 3: 日付で区切った深い検索

ベストプラクティス

よくあるエラー

空のキーワード

トークン使用量