curl --request POST \
  --url https://api.tiro.ooo/v1/external/notes/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "keyword": "OKR"
}
'

{
  "notes": [
    {
      "guid": "note-abc123-def456",
      "title": "OKR Q2 Planning",
      "createdAt": "2026-04-15T10:00:00Z",
      "updatedAt": "2026-04-15T11:30:00Z",
      "sourceType": "live-voice",
      "recordingStartAt": "2026-04-15T10:00:05Z",
      "recordingEndAt": "2026-04-15T11:00:30Z",
      "recordingDurationSeconds": 3625,
      "transcribeLocale": "ko_KR",
      "translateLocale": null,
      "webUrl": "https://tiro.ooo/n/abc123def456",
      "collaborators": [],
      "participants": [
        {
          "name": "Alice Kim",
          "email": "alice@example.com"
        }
      ],
      "matchedSnippets": null,
      "documents": []
    }
  ],
  "nextCursor": null,
  "degraded": false
}

Search Notes (Deep)

Keyword-required deep search. Returns notes hydrated with their primary documents (one-pager, custom) so an MCP/LLM client can read content alongside metadata in a single call.

When to use this vs `GET /v1/external/notes?keyword=...`

GET /v1/external/notes?keyword=... — lightweight: returns matched note metadata only. Cheaper.
POST /v1/external/notes/search (this) — heavy: also returns the matched notes’ documents. Use when you need to understand the context behind a topic, not just see which notes match.

Behavior

Requires a user-scoped API key (team-only API keys return 400).
When the search index is unavailable or fails, the response sets degraded=true and degradedReason to one of search_index_unavailable / search_index_degraded and returns an empty notes array — clients should surface this to the user/LLM.
Document content is structured (sections); each document carries a truncated flag when the combined section text exceeded the 5,000 char search budget.
nextCursor is reserved for future use and is currently always null.

POST

external

notes

curl --request POST \
  --url https://api.tiro.ooo/v1/external/notes/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "keyword": "OKR"
}
'

{
  "notes": [
    {
      "guid": "note-abc123-def456",
      "title": "OKR Q2 Planning",
      "createdAt": "2026-04-15T10:00:00Z",
      "updatedAt": "2026-04-15T11:30:00Z",
      "sourceType": "live-voice",
      "recordingStartAt": "2026-04-15T10:00:05Z",
      "recordingEndAt": "2026-04-15T11:00:30Z",
      "recordingDurationSeconds": 3625,
      "transcribeLocale": "ko_KR",
      "translateLocale": null,
      "webUrl": "https://tiro.ooo/n/abc123def456",
      "collaborators": [],
      "participants": [
        {
          "name": "Alice Kim",
          "email": "alice@example.com"
        }
      ],
      "matchedSnippets": null,
      "documents": []
    }
  ],
  "nextCursor": null,
  "degraded": false
}

인증

Authorization

string

header

필수

API key in format {id}.{secret}

본문

application/json

keyword

string

필수

Search keyword. Full-text matched against note title and paragraph content.

Minimum string length: 1

예시:

"OKR"

filter

object

Show child attributes

pagination

object

Show child attributes

응답

Matched notes with their documents.

notes

object[]

필수

Matched notes, ordered by full-text relevance with createdAt desc as tiebreaker.

Show child attributes

nextCursor

string | null

degraded

boolean

기본값:false

true when the response was produced via a fallback path (e.g., search index unavailable). When degraded, notes may be empty and quality is reduced.

degradedReason

enum<string> | null

Machine-readable reason when degraded=true. null otherwise.

사용 가능한 옵션:

search_index_unavailable,

search_index_degraded,

null

List Notes

Reserve Note GUID