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

{
  "notes": [
    {
      "guid": "note-abc123-def456",
      "workspaceGuid": "ws_a1b2c3d4",
      "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 Workspace Notes (Deep)

Deep keyword search scoped to one workspace, named in the path by workspaceGuid. Returns notes hydrated with their primary documents (one-pager, custom) so an MCP/LLM client can read content alongside metadata in a single call. This is the workspace-scoped successor to the deprecated POST /v1/external/notes/search.

When to use this vs `GET /v1/external/workspaces/{workspaceGuid}/notes?keyword=...`

GET …/notes?keyword=… — lightweight: returns matched note metadata only. Cheaper.
POST …/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.

Which API keys work

Unlike the deprecated POST /v1/external/notes/search (user-scoped keys only), this endpoint accepts user, workspace-system, and legacy team API keys. A key bound to a workspace must match the workspaceGuid in the path, otherwise the call returns 403. A user-scoped key must belong to a member of the workspace, otherwise the call returns 403.

Behavior

Results stay inside the path workspace. Both note matching and document hydration are workspace-bounded, so cross-workspace notes never leak.
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

workspaces

{workspaceGuid}

notes

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

{
  "notes": [
    {
      "guid": "note-abc123-def456",
      "workspaceGuid": "ws_a1b2c3d4",
      "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}

경로 매개변수

workspaceGuid

string

필수

Workspace GUID. Obtain it from GET /v1/external/workspaces.

본문

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 Workspace Notes

Search Notes (Deep)