Skip to main content

Documentation Index

Fetch the complete documentation index at: https://api-docs.tiro.ooo/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

list_notes is the lightweight tier of note discovery: it returns metadata only — title, participants, dates, source type — and is the right tool when you need to know which notes exist without reading their content. When query.keyword is provided the result set is reordered by OpenSearch relevance (_score desc) instead of createdAt desc. Primary Use Cases:
  • “Which notes are in folder X?”
  • “Which notes match keyword Y?” (just to confirm existence)
  • Filtering by date range to narrow a large workspace.
Key Features:
  • 3-tier model with search_notes (deep, returns documents) and get_note_transcript (raw transcript).
  • Cursor-based pagination on the list path.
  • Excludes incomplete notes automatically — notes whose recording never started and whose title is the default placeholder are filtered out at the MCP layer.
Token efficiency. A list_notes page returns ~50 tokens per note. Compared to loading documents via search_notes (~1,500 tokens per note) or transcripts via get_note_transcript (~3,000–5,000 tokens per note), this is the cheapest way to find what you have.

​
Parameters

ParameterTypeRequiredDescription
query.keywordstringOptionalOptional keyword. When present, reorders by OpenSearch relevance.
pagination.cursorstringOptionalCursor from a previous nextCursor.
pagination.sizenumberOptionalResults per page (default 20, max 100).
filter.folderIdstringOptionalRestrict to a folder (recursive — includes descendant folders).
filter.createdAtFromstringOptionalISO 8601 datetime, inclusive lower bound on createdAt.
filter.createdAtTostringOptionalISO 8601 datetime, exclusive upper bound on createdAt.

​
query.keyword (optional)

Switches the listing into relevance mode. Hits are scored by OpenSearch against the note title and paragraph content. With keyword present, nextCursor is null (the deep search index doesn’t carry a stable list cursor). Keyword search currently requires a user-scoped API key. Team-only API keys with keyword set return 400 Bad Request.

​
filter.folderId (optional)

When provided, the listing is recursively scoped to the folder and all of its descendants. Folder access is authorized server-side; passing a folderId you don’t have access to returns 404.

​
filter.createdAtFrom / filter.createdAtTo (optional)

Half-open [from, to) range filter on createdAt. Both accept ISO 8601 datetime with timezone (e.g., 2026-04-01T00:00:00Z).

​
pagination (optional)

{ cursor, size }. Default size: 20, max 100. Use the nextCursor from the previous response to walk pages.

​
Response Format

​
Success Response

{
  "content": [
    {
      "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" },
        { "name": "Bob Park", "email": null }
      ]
    }
  ],
  "notes": [],
  "total": 137,
  "totalSize": 1,
  "nextCursor": "eyJvZmZzZXQiOjUwfQ=="
}
The response carries each note both under content (recommended) and notes (legacy alias). Pick whichever your client prefers and ignore the other.
Field Descriptions:
FieldTypeDescription
content[]arrayNotes (preferred field).
content[].noteGuidstringUnique note identifier — pass to search_notes, get_note_transcript, etc.
content[].titlestringNote title.
content[].webUrlstringDirect link to the note in the Tiro web app.
content[].createdAtstringISO 8601 creation timestamp.
content[].updatedAtstringISO 8601 last-update timestamp.
content[].recordingDurationSecondsnumberRecording length in seconds (0 for non-recording sources).
content[].sourceTypestringOne of live-voice, recording, text, video, webpage, offline-mode, onboarding.
content[].participants[]array{ name, email } per participant. Either may be null.
totalnumberBackend’s pre-filter count.
totalSizenumberCount after the MCP-side incomplete-note filter (may be smaller than total).
nextCursorstring | nullCursor for the next page; null when no more results or when keyword search is active.
Pagination tip. total and totalSize may diverge — incomplete notes counted by total are filtered out before totalSize. Don’t loop with while (totalSize < total); walk pages with nextCursor instead.

​
Usage Examples

​
Example 1: Notes in a specific folder

Request: 
{
  "filter": {
    "folderId": "455765"
  }
}
Returns the most recent 20 complete notes in folder 455765 and its descendants.

​
Example 2: Recent notes by date range

Request: 
{
  "filter": {
    "createdAtFrom": "2026-04-01T00:00:00Z",
    "createdAtTo": "2026-05-01T00:00:00Z"
  },
  "pagination": {
    "size": 50
  }
}

​
Example 3: Keyword listing (relevance-ranked)

Request: 
{
  "query": {
    "keyword": "OKR"
  },
  "pagination": {
    "size": 30
  }
}
Returns notes whose title or paragraphs match OKR, ordered by relevance. The response’s nextCursor is null — re-call with the same keyword and a larger size if you need more.

​
Example 4: Paginated browse

First page: 
{
  "pagination": { "size": 50 }
}
Next page (using nextCursor from previous response): 
{
  "pagination": {
    "size": 50,
    "cursor": "eyJvZmZzZXQiOjUwfQ=="
  }
}

​
When to use which tier

You need to know which notes exist — by folder, by date, or by keyword presence. Returns metadata only, ~50 tokens per note. Cheapest discovery tool.
You need to understand the context behind a topic — its decisions, action items, or the team’s conclusions. Returns matched notes plus their primary documents (one-pager, custom). ~1,500 tokens per note.Switch from list_notes to search_notes when the LLM needs document content to answer the user’s question.
You need to quote exact spoken words from the conversation. Returns the full transcript with timestamps. ~3,000–5,000 tokens per hour of meeting — last resort.See get_note_transcript.

​
Common Errors

​
Keyword search with team-only API key

Solution: Use a user-scoped API key for keyword search. Team folder listing without a keyword still works on team API keys.

​
Invalid datetime

Solution: Use ISO 8601 datetime with timezone (e.g., 2026-04-01T00:00:00Z).

​
Token Usage

ModeTokens per note
list_notes (metadata only)~50
search_notes (with documents)~1,500
get_note_transcript (full transcript)~3,000–5,000 per hour of meeting
Discovery flow. Start with list_notes to find the noteGuids you care about. Switch to search_notes only when you need document content. Reach for get_note_transcript only when verbatim quoting is required.