본문으로 건너뛰기
Sursa Developers

GET/v1/verification/queue

검증 대기열 조회

verification_queue

사용자가 검증자(직접, 그룹을 통해, 또는 담당자로서)인 미검증 카드를 반환해요. ORG_MANAGE_ALL_COLLECTIONS 권한이 있는 사용자는 조직의 전체 대기열을 받아요.
mode=up_first이면 가장 중요한 카드 다섯 장을 한 묶음으로 반환하며, 순위는 다음 식으로 정해요.
0.45·ln(1+uv+2·uc) + 0.30·min(days/90,1) + 0.15·ln(1+views30d) + 0.10·pending_archive
(“show more”(더 보기)는 offset 값을 넣은 같은 요청이에요). mode=all이면 정렬을 적용한 전체 대기열을 반환해요(sort: relevancy, title, next_verification_date, unverified_usage, pending_auto_archive, 그리고 order). X-Total-Count 헤더에 대기열 크기가 있어요. 목록을 보면 UNSEEN_VERIFICATION 할 일이 완료돼요.

인증

Authorization 헤더로 API 키를 보내세요: Authorization: Bearer <키>.

쿼리 파라미터

  • modestring

    허용 값: up_firstall

    기본값: "up_first"

  • sortstring
  • orderstring

    허용 값: ascdesc

  • pending_archiveboolean
  • limitinteger

    기본값: 50≥ 1, ≤ 200

  • offsetinteger

    기본값: 0≥ 0

  • cursorstring

    같은 필터로 보낸 이전 응답의 X-Next-Cursor 헤더나 next_cursor 값에서 얻은 다음 페이지 커서예요. 커서에는 페이지 크기가 담겨 있어요. offset 파라미터와 함께 보내면 422 validation.failed 오류를, 다른 목록이나 다른 필터의 커서 또는 형식이 잘못된 커서를 보내면 400 api.cursor_invalid 오류를 반환해요.

    length ≤ 512

응답

200성공 응답

응답 헤더

  • X-Total-Count

    전체 대기열의 크기.

  • RateLimit-Policy

    적용 중인 한도. IETF 초안 draft-ietf-httpapi-ratelimit-headers 형식이며, 쉼표로 구분한 "<name>";q=<quota>;w=<window in seconds> 항목으로 이루어져요. key 항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는 user, 자격 증명이 없으면 ip예요). minute, day, month 항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.

  • RateLimit

    RateLimit-Policy 헤더의 각 한도에서 남은 양: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy 헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.

  • X-RateLimit-Remaining

    가장 엄격한 한도에서 남은 요청 수.

  • X-RateLimit-Reset

    가장 엄격한 한도가 초기화될 때까지 남은 초.

application/json

객체: VerificationQueue

  • itemsarray of VerificationQueueItem필수
  • totalinteger필수
  • modestring필수
  • next_cursorstring | null

    cursor 파라미터에 넘길 다음 페이지의 커서. null이면 마지막 페이지예요. 요청에 limit 또는 cursor 값을 전달하면 포함돼요.

    length ≤ 512

  • has_moreboolean

    다음 페이지가 있는지 여부. 요청에 limit 또는 cursor 값을 전달하면 포함돼요.

400잘못된 요청이에요. 파라미터 값이나 객체의 상태 때문에 이 동작을 할 수 없어요(`detail` 필드에 메시지가 있어요).

응답 헤더

  • RateLimit-Policy

    적용 중인 한도. IETF 초안 draft-ietf-httpapi-ratelimit-headers 형식이며, 쉼표로 구분한 "<name>";q=<quota>;w=<window in seconds> 항목으로 이루어져요. key 항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는 user, 자격 증명이 없으면 ip예요). minute, day, month 항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.

  • RateLimit

    RateLimit-Policy 헤더의 각 한도에서 남은 양: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy 헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.

  • X-RateLimit-Remaining

    가장 엄격한 한도에서 남은 요청 수.

  • X-RateLimit-Reset

    가장 엄격한 한도가 초기화될 때까지 남은 초.

application/json

객체: Error

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 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.

  • RateLimit

    RateLimit-Policy 헤더의 각 한도에서 남은 양: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy 헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.

  • X-RateLimit-Remaining

    가장 엄격한 한도에서 남은 요청 수.

  • X-RateLimit-Reset

    가장 엄격한 한도가 초기화될 때까지 남은 초.

application/json

객체: Error

422유효성 검사 오류예요. 본문이나 파라미터가 스키마와 맞지 않거나(`detail` 필드는 유효성 검사 오류 목록), 파라미터 값이 허용 범위를 벗어났어요(`detail` 필드는 메시지).

응답 헤더

  • RateLimit-Policy

    적용 중인 한도. IETF 초안 draft-ietf-httpapi-ratelimit-headers 형식이며, 쉼표로 구분한 "<name>";q=<quota>;w=<window in seconds> 항목으로 이루어져요. key 항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는 user, 자격 증명이 없으면 ip예요). minute, day, month 항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.

  • RateLimit

    RateLimit-Policy 헤더의 각 한도에서 남은 양: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy 헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.

  • X-RateLimit-Remaining

    가장 엄격한 한도에서 남은 요청 수.

  • X-RateLimit-Reset

    가장 엄격한 한도가 초기화될 때까지 남은 초.

application/json

객체: Error

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 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.

  • RateLimit

    RateLimit-Policy 헤더의 각 한도에서 남은 양: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy 헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.

  • X-RateLimit-Remaining

    가장 엄격한 한도에서 남은 요청 수.

  • X-RateLimit-Reset

    가장 엄격한 한도가 초기화될 때까지 남은 초.

application/json

객체: Error

오류 코드

모든 요청에 공통으로 쓰이는 코드 외에 이 엔드포인트가 error.code로 반환할 수 있는 코드예요.

호출 한도

응답에는 RateLimit, RateLimit-Policy 헤더와 이전 헤더인 X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset이 담겨요. 429 응답에는 초 단위의 Retry-After 헤더가 있어요. 그만큼 기다린 뒤 재시도하세요.

← verification · API 레퍼런스