가이드

페이지네이션

v1의 모든 목록 엔드포인트는 동일한 방식으로 페이지네이션됩니다. 페이지 번호가 아닌 커서를 사용합니다.

목록 엔벨로프

모든 목록 응답에는 동일한 세 가지 최상위 필드가 있습니다.

{
  "data": [ /* ... */ ],
  "has_more": true,
  "next_page_token": "eyJpZCI6IDQyfQ"
}
  • data — 현재 페이지의 결과 배열입니다.
  • has_more — 이 페이지 이후에 다른 페이지가 존재하는지 여부입니다.
  • next_page_token — 다음 페이지를 가져오기 위해 다음 요청에서 ?page_token=으로 전달합니다. has_more가 false일 때는 항상 null입니다. 두 필드는 서로 모순되지 않습니다.

페이지 번호 대신 커서를 사용하는 이유

v1에는 ?page=2 스타일의 페이지네이션이나 offset 매개변수가 없습니다. 배치나 사용 기록과 같은 목록은 지속적으로 변경됩니다. 새 배치가 완료되고 새 사용 행이 기록됩니다. 따라서 오프셋 기반의 "2페이지"는 요청 사이에 항목이 삽입되면 행을 조용히 건너뛰거나 중복할 수 있습니다. 커서는 이러한 문제를 방지합니다. 각 토큰은 변경되는 숫자 오프셋이 아닌 기본 순서의 정확한 위치를 가리킵니다.

토큰은 불투명합니다

next_page_token은 페이지 번호가 아니며, 내부 인코딩 방식은 계약의 일부가 아닙니다. 엄격히 불투명한 문자열로 취급하세요. 받은 그대로 정확히 전달하고, 디코딩하거나 직접 생성하지 말며, API 버전 간에 형식이 안정적이라고 가정하지 마세요. 유일한 보장은 다음과 같습니다: 받은 토큰을 전달하면 다음 페이지를 얻을 수 있습니다.

예시: 배치 페이지 넘기기

첫 번째 요청, 아직 토큰 없음:

curl "https://imagetotable.ai/api/v1/batches?limit=20" \
  -H "Authorization: Bearer $API_KEY"
{
  "data": [ { "batch_name": "260716-4K9P", "status": "succeeded", "document_count": 3, "created_at": "2026-07-16T09:12:03Z" } ],
  "has_more": true,
  "next_page_token": "eyJpZCI6IDQyfQ"
}

다음 요청, 이전 응답의 토큰 사용:

curl "https://imagetotable.ai/api/v1/batches?limit=20&page_token=eyJpZCI6IDQyfQ" \
  -H "Authorization: Bearer $API_KEY"

has_more가 false로 반환될 때까지 각 응답의 next_page_token으로 이 과정을 반복하세요. 잘못된 형식이거나 만료된 토큰은 첫 페이지를 다시 조용히 반환하는 대신 invalid_parameter 오류(오류 처리 참조)를 반환하므로, 손상된 토큰이 루프를 조용히 재시작하지 않고 즉시 드러납니다.

limit 매개변수

모든 목록 엔드포인트는 선택적 limit 쿼리 매개변수를 받아 페이지 크기를 제어하며, 각각 고유한 기본값과 최대값이 있습니다(정확한 범위는 API 참조의 개별 엔드포인트 페이지 참조). 허용 범위를 벗어난 limit을 요청하면 invalid_parameter가 반환됩니다.

📮 contact email: [email protected]