본문으로 건너뛰기

페이지네이션

리스트 엔드포인트는 cursor 기반 pagination을 사용합니다.

파라미터​

  • limit — 페이지 크기 (기본 50, 최대 100)
  • cursor — 이전 응답의 meta.next_cursor 값 (opaque, 직접 파싱하지 마세요)

응답 meta​

{ "has_more": true, "next_cursor": "eyJ..." }

meta는 forward-only입니다 — next_cursor만 제공하며 이전 페이지로 돌아가는 cursor는 없습니다. has_more가 false이면 마지막 페이지이고 next_cursor는 생략됩니다.

# 첫 페이지
curl "https://api.talk.zeroworks.ai/api/public/v1/contacts?limit=50" -H "Authorization: Bearer ztpat_..."
# 응답의 meta.next_cursor로 다음 페이지
curl "https://api.talk.zeroworks.ai/api/public/v1/contacts?limit=50&cursor=eyJ..." -H "Authorization: Bearer ztpat_..."

Cursor 만료​

cursor 만료 정책은 종류에 따라 다릅니다.

  • 연락처 등 keyset cursor: 발급 후 24시간 유효합니다. 만료된 cursor를 쓰면 400 INVALID_QUERY가 반환되며, 첫 페이지부터 다시 조회해야 합니다.
  • 메시지 cursor: 내부 저장소(DynamoDB) 네이티브 토큰이라 만료가 없습니다.

메시지 전용 제약​

메시지 목록(GET /channels/{id}/messages)은 시간 범위가 필수입니다.

  • since (RFC3339) — 필수
  • until (RFC3339) — 선택, 기본값은 현재 시각
  • until - since는 30일 이내여야 합니다 (초과 시 400 INVALID_QUERY)

검색​

검색(GET /search)은 cursor가 없으며 단일 페이지(최대 100건)만 반환합니다.