GET/v1/folders
모든 컬렉션의 폴더 트리 조회
folder_trees
사용자가 객체를 하나 이상 볼 수 있는 모든 컬렉션의 폴더 트리를 한 번의 응답으로 반환해요. 공개 범위 규칙은 GET /v1/collections/{name}/folders 요청과 같고, 순서는 GET /v1/collections 응답과 같아요. 볼 수 있는 객체가 없는 컬렉션은 빠져요. 각 폴더에는 cards 외에 하위 트리 합계 cards_total, sensitive_total, top_category도 있어요. updated_since나 metadata[<key>]=를 쓰면 각 컬렉션의 folders에는 조건과 일치하는 폴더가 평면 목록으로 담겨요(children은 비어 있고, 트리에서의 위치는 parent_id 값으로 알 수 있어요). updated_since를 쓰면 updated_at 오름차순, 그다음 id 순으로, 쓰지 않으면 sort_key 순서로 정렬돼요. 일치하는 폴더가 없는 컬렉션은 빠져요.
인증
Authorization 헤더로 API 키를 보내세요: Authorization: Bearer <키>.
쿼리 파라미터
limitinteger페이지 크기.
limit값과cursor값이 없으면 목록 전체를 반환해요. 지정하면 최대limit개 항목을 반환하고, 다음 페이지는Link(rel="next") 헤더와X-Next-Cursor헤더로 알려 줘요.≥ 1, ≤ 200
cursorstring같은 필터로 보낸 이전 응답의
X-Next-Cursor헤더나next_cursor값에서 얻은 다음 페이지 커서예요. 커서에는 페이지 크기가 담겨 있어요.offset파라미터와 함께 보내면422 validation.failed오류를, 다른 목록이나 다른 필터의 커서 또는 형식이 잘못된 커서를 보내면400 api.cursor_invalid오류를 반환해요.length ≤ 512
updated_sincestring (date-time)updated_at값이 이 시각(오프셋을 포함한 RFC 3339)과 같거나 그 이후인 객체만 반환해요. 동기화에 써요. 이 파라미터를 쓰면 목록은updated_at오름차순, 그다음id순으로 정렬되며, 커서도 그 순서대로 이어져요. 삭제된 객체는 목록에 나오지 않아요. 삭제는 이벤트로 전달돼요.length ≤ 512
metadatamap of stringmetadata필드로 필터링해요.metadata[<key>]=<value>조건은 정확히 일치하는 값을 찾아요. 조건은 최대 3개이며 모두 일치해야 해요(?metadata[team]=support&metadata[crm_id]=A-1042). 조건이 3개를 넘거나 키가 잘못되면400 api.metadata_invalid오류를 반환해요.
응답
200성공 응답
응답 헤더
Link다음 페이지의 주소(
<…>; rel="next"). 헤더가 없으면 마지막 페이지예요.X-Next-Cursorcursor파라미터에 넣을 다음 페이지 커서. 헤더가 없으면 마지막 페이지예요.RateLimit-Policy적용 중인 한도. IETF 초안
draft-ietf-httpapi-ratelimit-headers형식이며, 쉼표로 구분한"<name>";q=<quota>;w=<window in seconds>항목으로 이루어져요.key항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는user, 자격 증명이 없으면ip예요).minute,day,month항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.RateLimitRateLimit-Policy헤더의 각 한도에서 남은 양:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitRateLimit-Policy헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.X-RateLimit-Remaining가장 엄격한 한도에서 남은 요청 수.
X-RateLimit-Reset가장 엄격한 한도가 초기화될 때까지 남은 초.
application/json
collection_idinteger필수collection_namestring필수collection_titlestring필수표시용 컬렉션 이름.
permissionsarray of string필수컬렉션에 대한 사용자의 유효 권한.
unfiledinteger필수사용자가 볼 수 있는 컬렉션 카드 중 어느 폴더에도 없는 카드. 기본 카드 목록처럼 보관된 카드는 세지 않아요.
401자격 증명(세션 쿠키나 API 키)을 보내지 않았거나 키를 찾을 수 없어요.
응답 헤더
RateLimit-Policy적용 중인 한도. IETF 초안
draft-ietf-httpapi-ratelimit-headers형식이며, 쉼표로 구분한"<name>";q=<quota>;w=<window in seconds>항목으로 이루어져요.key항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는user, 자격 증명이 없으면ip예요).minute,day,month항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.RateLimitRateLimit-Policy헤더의 각 한도에서 남은 양:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitRateLimit-Policy헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.X-RateLimit-Remaining가장 엄격한 한도에서 남은 요청 수.
X-RateLimit-Reset가장 엄격한 한도가 초기화될 때까지 남은 초.
application/json
429요청이 너무 많거나(`api.rate_limited`), 조직의 분·일·월 할당량을 다 썼거나(`api.quota_exceeded`, `error.details` 필드에 `quota`, `limit`, `reset_at` 값이 있어요), 조직의 한도에 도달했거나, 답변 서비스가 바쁜 상태예요(`answers.engine_busy`). `Retry-After` 헤더에 적힌 시간만큼 기다리세요.
응답 헤더
Retry-After요청을 다시 시도하기 전에 기다릴 초.
RateLimit-Policy적용 중인 한도. IETF 초안
draft-ietf-httpapi-ratelimit-headers형식이며, 쉼표로 구분한"<name>";q=<quota>;w=<window in seconds>항목으로 이루어져요.key항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는user, 자격 증명이 없으면ip예요).minute,day,month항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.RateLimitRateLimit-Policy헤더의 각 한도에서 남은 양:"<name>";r=<remaining>;t=<seconds until reset>.X-RateLimit-LimitRateLimit-Policy헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.X-RateLimit-Remaining가장 엄격한 한도에서 남은 요청 수.
X-RateLimit-Reset가장 엄격한 한도가 초기화될 때까지 남은 초.
application/json
오류 코드
모든 요청에 공통으로 쓰이는 코드 외에 이 엔드포인트가 error.code로 반환할 수 있는 코드예요.
호출 한도
응답에는 RateLimit, RateLimit-Policy 헤더와 이전 헤더인 X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset이 담겨요. 429 응답에는 초 단위의 Retry-After 헤더가 있어요. 그만큼 기다린 뒤 재시도하세요.