메인 콘텐츠로 건너뛰기

​
개요

list_notes는 노트 디스커버리의 가벼운 단계예요. 제목, 참가자, 날짜, 소스 유형 등 메타데이터만 반환하며, 내용을 읽지 않고 어떤 노트가 있는지 알아야 할 때 알맞은 도구예요. query.keyword가 제공되면 결과 집합은 recordingStartAt 내림차순 대신 전문 검색(full-text) 관련도(동점 시 createdAt 내림차순)로 재정렬돼요. 주요 사용 사례:
  • “폴더 X에 어떤 노트가 있지?”
  • “어떤 노트가 keyword Y에 매칭되지?”(존재 여부만 확인)
  • 날짜 범위로 필터링해 큰 워크스페이스 좁히기.
핵심 기능:
  • search_notes(심층, 문서 반환), get_note_transcript(원본 transcript)와 함께 3단계 모델을 이뤄요.
  • 목록 경로에서 cursor 기반 페이지네이션.
  • 미완성 노트는 자동으로 제외해요. 녹음이 시작된 적 없고 제목이 기본 placeholder인 노트는 MCP 레이어에서 필터링돼요.
토큰 효율. list_notes 페이지는 노트당 약 50 토큰을 반환해요. search_notes로 문서를 불러오거나(노트당 ~1,500 토큰) get_note_transcript로 transcript를 불러오는 것(노트당 ~3,000–5,000 토큰)과 비교하면, 가진 것을 찾는 가장 저렴한 방법이에요.

​
파라미터

ParameterTypeRequiredDescription
query.keywordstringOptional선택적 keyword. 있으면 전문 검색 관련도로 재정렬해요.
pagination.cursorstringOptional이전 nextCursor에서 받은 cursor.
pagination.sizenumberOptional페이지당 결과 수(기본값 20, 최대 100).
filter.folderIdstringOptional폴더로 제한(재귀적 — 하위 폴더 포함).
filter.createdAtFromstringOptionalISO 8601 datetime, createdAt의 포함 하한.
filter.createdAtTostringOptionalISO 8601 datetime, createdAt의 배제 상한.

​
query.keyword (선택)

목록을 관련도 모드로 전환해요. 매칭은 서버의 전문 검색 인덱스가 노트 제목과 단락 내용을 기준으로 점수를 매겨요. keyword가 있으면 nextCursor는 null이에요(심층 검색 인덱스에는 안정적인 목록 cursor가 없어요). keyword 검색은 현재 사용자 범위 API key가 필요해요. keyword가 설정된 팀 전용 API key는 400 Bad Request를 반환해요.

​
filter.folderId (선택)

제공되면 목록은 해당 폴더와 모든 하위 폴더로 재귀적으로 범위가 좁혀져요. 폴더 접근은 서버 측에서 인가돼요. 접근 권한이 없는 folderId를 전달하면 404를 반환해요.

​
filter.createdAtFrom / filter.createdAtTo (선택)

createdAt에 대한 반열린 [from, to) 범위 필터예요. 둘 다 시간대가 포함된 ISO 8601 datetime을 받아요(예: 2026-04-01T00:00:00Z).

​
pagination (선택)

{ cursor, size }. 기본값 size: 20, 최대 100. 이전 응답의 nextCursor를 사용해 페이지를 넘기세요.

​
응답 형식

​
성공 응답

{
  "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=="
}
응답은 각 노트를 content(권장)와 notes(레거시 별칭) 양쪽에 담아요. 클라이언트가 선호하는 쪽을 고르고 다른 쪽은 무시하세요.
필드 설명:
FieldTypeDescription
content[]array노트(선호 필드).
content[].noteGuidstring고유 노트 식별자 — search_notes, get_note_transcript 등에 전달해요.
content[].titlestring노트 제목.
content[].webUrlstringTiro 웹 앱에서 노트로 바로 가는 링크.
content[].createdAtstringISO 8601 생성 타임스탬프.
content[].updatedAtstringISO 8601 마지막 수정 타임스탬프.
content[].recordingDurationSecondsnumber녹음 길이(초)(녹음이 아닌 소스는 0).
content[].sourceTypestringlive-voice, recording, text, video, webpage, offline-mode, onboarding 중 하나.
content[].participants[]array참가자별 { name, email }. 둘 중 어느 쪽이든 null일 수 있어요.
totalnumber백엔드의 필터 전 개수.
totalSizenumberMCP 측 미완성 노트 필터 적용 후 개수(total보다 작을 수 있어요).
nextCursorstring | null다음 페이지를 위한 cursor. 더 이상 결과가 없거나 keyword 검색이 활성화되면 null.
페이지네이션 팁. total과 totalSize는 다를 수 있어요. total이 센 미완성 노트가 totalSize 전에 필터링돼요. while (totalSize < total)로 반복하지 말고 nextCursor로 페이지를 넘기세요.

​
사용 예시

​
예시 1: 특정 폴더의 노트

요청: 
{
  "filter": {
    "folderId": "455765"
  }
}
폴더 455765와 그 하위 폴더에서 가장 최근의 완성 노트 20개를 반환해요.

​
예시 2: 날짜 범위로 최근 노트

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

​
예시 3: keyword 목록 (관련도 순위)

요청: 
{
  "query": {
    "keyword": "OKR"
  },
  "pagination": {
    "size": 30
  }
}
제목이나 단락이 OKR에 매칭되는 노트를 관련도 순으로 반환해요. 응답의 nextCursor는 null이에요. 더 필요하면 같은 keyword와 더 큰 size로 다시 호출하세요.

​
예시 4: 페이지네이션 탐색

첫 페이지: 
{
  "pagination": { "size": 50 }
}
다음 페이지 (이전 응답의 nextCursor 사용): 
{
  "pagination": {
    "size": 50,
    "cursor": "eyJvZmZzZXQiOjUwfQ=="
  }
}

​
어떤 단계를 언제 쓸지

폴더, 날짜, keyword 존재 여부로 어떤 노트가 있는지 알아야 할 때예요. 메타데이터만 반환하고 노트당 약 50 토큰이에요. 가장 저렴한 디스커버리 도구예요.
주제 이면의 결정, action item, 팀의 결론 등 맥락을 이해해야 할 때예요. 매칭된 노트와 그 주요 문서(one-pager, custom)를 반환해요. 노트당 약 1,500 토큰이에요.LLM이 사용자 질문에 답하기 위해 문서 내용이 필요할 때 list_notes에서 search_notes로 전환하세요.
대화에서 정확한 발화를 인용해야 할 때예요. 타임스탬프가 있는 전체 transcript를 반환해요. 회의 시간당 ~3,000–5,000 토큰으로, 최후의 수단이에요.get_note_transcript를 참고하세요.

​
자주 발생하는 오류

​
팀 전용 API key로 keyword 검색

해결 방법: keyword 검색에는 사용자 범위 API key를 사용하세요. keyword 없는 팀 폴더 목록 조회는 팀 API key로도 여전히 동작해요.

​
유효하지 않은 datetime

해결 방법: 시간대가 포함된 ISO 8601 datetime을 사용하세요(예: 2026-04-01T00:00:00Z).

​
토큰 사용량

ModeTokens per note
list_notes (메타데이터만)~50
search_notes (문서 포함)~1,500
get_note_transcript (전체 transcript)회의 시간당 ~3,000–5,000
디스커버리 흐름. list_notes로 관심 있는 noteGuid를 먼저 찾으세요. 문서 내용이 필요할 때만 search_notes로 전환하세요. 그대로 인용해야 할 때만 get_note_transcript를 사용하세요.