본문으로 건너뛰기
Sursa Developers

GET/v1/cards

카드 목록 조회

list_cards

필터, 정렬, 페이지네이션을 적용해 카드를 반환해요. preview=1(타일 보기용)을 보내면 데이터 프로필 범위 안에서 각 카드에 preview(텍스트의 처음 200자)와 preview_tables(시트와 시트별 행 수)도 포함돼요.

인증

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

쿼리 파라미터

  • collectionstring | null
  • folderstring | null

    <folder ID> 값은 폴더와 모든 하위 폴더의 카드를 반환해요. none 값은 어느 폴더에도 들어 있지 않은 컬렉션의 카드를 반환하며 collection 파라미터가 필요해요(없으면 400 cards.invalid_folder_filter 오류). 폴더가 없거나 볼 수 없으면 404 folders.not_found 오류를 반환해요.

    length ≤ 64

  • statusstring | null

    허용 값: processingreadyerrorarchivedall

  • ownerstring | null

    me, none 또는 사용자 ID.

  • owner_idinteger | null
  • verificationstring | null

    허용 값: verifiedneeds_verificationstale

  • kindCardKind
  • typestring | null

    table 값은 팩트 테이블이 있는 카드를, text 값은 팩트 테이블이 없는 카드를 반환해요.

    허용 값: tabletext

  • tagsstring | null

    쉼표로 구분한 태그(카드에 모든 태그가 있어야 해요).

  • idsstring | null

    쉼표로 구분한 카드 ID.

  • searchstring | null
  • categorystring | null
  • sensitiveboolean | null
  • sortCardSort

    기본값: "created_at"

  • orderstring

    허용 값: ascdesc

    기본값: "desc"

  • limitinteger

    기본값: 200

  • offsetinteger

    기본값: 0

  • previewboolean

    true이면 타일 보기용 preview(처음 200자)와 preview_tables 필드를 추가해요.

    기본값: false

  • updated_sincestring (date-time)

    updated_at 값이 이 시각(오프셋을 포함한 RFC 3339)과 같거나 그 이후인 카드만 반환해요. 동기화에 써요. sort, order 파라미터를 명시하지 않으면 목록은 updated_at 오름차순, 그다음 id 순으로 정렬돼요. 삭제된 카드는 목록에 나오지 않아요. 삭제는 이벤트로 전달돼요.

  • metadatamap of string

    metadata 필드로 필터링해요. metadata[<key>]=<value> 조건은 정확히 일치하는 값을 찾아요. 조건은 최대 3개이며 모두 일치해야 해요(?metadata[team]=support&metadata[crm_id]=A-1042). 조건이 3개를 넘거나 키가 잘못되면 400 api.metadata_invalid 오류를 반환해요.

  • collection_idinteger

    ID로 지정한 컬렉션. collection 파라미터도 함께 보내면 collection_id 값이 우선해요. 조직에 없거나 볼 수 없는 컬렉션이면 404 collections.not_found 오류를 반환해요.

  • external_idstring

    이 external_id 값을 가진 카드만.

  • cursorstring

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

    length ≤ 512

  • expand[]array of string

    응답에 함께 담을 관련 객체(1.62.0부터): 오퍼레이션의 x-expandable 목록에 있는 경로. 파라미터는 최대 10번까지 반복할 수 있어요. 경로는 점으로 구분한 부분이 최대 2개예요(collection.default_owner). 목록에서는 경로가 data.로 시작하며 페이지의 모든 항목에 적용돼요(expand[]=data.owner). 확장된 객체는 항목의 expanded 객체에 담기고, ID 필드는 그대로 남아요. 그 객체를 읽는 오퍼레이션의 확인 기준으로 호출자가 볼 수 없는 객체는 null로 확장돼요. 알 수 없는 경로, 10개를 넘는 경로, 부분이 2개보다 많은 경로는 400 api.expand_invalid 오류를 반환해요.

    items ≤ 10

헤더 파라미터

  • X-View-Asstring

    admin 역할의 API 키만 쓸 수 있어요. <profile>[:viewer|verifier|editor] 형식의 데이터 프로필로 요청을 보내요(예: employee:viewer). 설치 키는 이 헤더를 쓸 수 없어요(403).

쿠키 파라미터

  • kb_view_asstring

    세션의 “View as” 모드(다른 사용자로 보기) 쿠키. POST /auth/view-as 요청으로 설정하고 DELETE /auth/view-as 요청으로 지워요.

응답

200성공 응답

응답 헤더

  • Link

    다음 페이지의 주소(<…>; rel="next"). 헤더가 없으면 마지막 페이지예요.

  • X-Next-Cursor

    cursor 파라미터에 넣을 다음 페이지 커서. 헤더가 없으면 마지막 페이지예요.

  • 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

객체: CardList

array of Card
  • expandedCardExpanded
  • permissionsObjectPermissionList
  • accessstring

    허용 값: wholepartial

  • access_contactstring

    접근 권한을 문의할 사람(access=partial일 때만).

  • aclobject
    필드
    • verifyboolean필수
    • writeboolean필수
  • categorystring필수
  • category_confidencenumber | null필수
  • category_lockedboolean필수
  • category_reviewboolean필수
  • category_sourceCategorySource | null필수
  • collectionstring필수
  • collection_idinteger필수
  • collection_titlestring
  • commentsarray of CardComment
  • content_jsonContentJSON | null

    최근 게시된 버전의 편집기 콘텐츠. 이 필드는 없을 수 있으며, 그럴 때는 초안에서 편집기 콘텐츠를 가져오세요(card_id 값을 넣은 POST /v1/drafts).

  • editing_lockEditingLock | null

    활성 편집 잠금. 이 필드는 없을 수 있으며, 그럴 때 편집기는 POST /v1/cards/{card_id}/lock 요청의 409 cards.locked 오류로 잠금을 가진 사람을 알 수 있어요.

  • created_atstring (date-time)필수
  • days_since_verifiedinteger필수
  • errorstring | null필수
  • eventsarray of CardEvent
  • feedback_neginteger필수
  • feedback_posinteger필수
  • foldersarray of CardFolderRef

    카드 목록에만 있어요: 카드가 들어 있는 폴더(사용자가 볼 수 있는 폴더)와 컬렉션 최상위부터의 경로. 빈 목록이면 카드가 어떤 폴더에도 없다는 뜻이에요.

  • has_tablesboolean

    카드 목록에만 있어요.

  • hidden_partsboolean
  • idstring필수
  • jobJob | null
  • kindCardKind필수
  • org_idinteger필수
  • owner_activeboolean | null
  • owner_idinteger | null필수
  • owner_namestring | null필수
  • pagesinteger | null필수
  • parserstring | null필수

    중립 코드로 나타낸 문서 파서: document(전체 구조: 페이지, 제목, 표, 스캔한 페이지), pdf(PDF 텍스트 레이어), docx, xlsx, csv, markdown, html, text. 목록은 늘어날 수 있어요.

  • partsarray of CardPart필수
  • sensitiveboolean필수
  • sha256string | null필수
  • sizeinteger필수
  • snoozed_atstring (date-time) | null
  • snoozed_byinteger | null
  • snoozed_untilstring | null
  • source_changedboolean필수
  • source_pathstring | null필수
  • source_urlstring | null필수
  • statusstring필수

    허용 값: processingreadyerrorarchived

  • tablesarray of CardTable
  • tagsarray of string필수
  • titlestring필수
  • trustnumber필수
  • trust_if_verifiednumber
  • trust_partsTrustParts필수
  • updated_atstring (date-time)필수
  • verificationVerification필수
  • verified_atstring (date-time) | null필수
  • verified_byinteger | null필수
  • verified_by_namestring | null
  • verifier_idsarray of integer필수
  • verifiersarray of object
    필드
    • activeboolean필수
    • idinteger필수
    • namestring필수
  • verify_interval_daysinteger필수
  • versioninteger필수
  • versionsarray of CardVersion
  • source_archiveArchiveSource
  • created_byinteger | null
  • manual_optionsobject

    수동 파싱 설정(미리 보기).

  • doc_kindDocKind | null

    문서 유형. 유형이 정해지지 않았으면 null이에요(예: 문서 유형이 도입되기 전에 인덱싱된 카드).

  • doc_kind_confidencenumber | null

    문서 유형의 확신도(0부터 1까지).

  • doc_kind_sourcestring | null

    유형을 정한 주체: 규칙(rules), 사용자(manual) 또는 자동 분류. 목록은 늘어날 수 있으므로 알 수 없는 값은 자동 분류로 처리하세요.

    허용 값: rulesmanualnull

  • invoiceDocInvoiceExtraction | null

    청구서, 크레딧 노트 또는 영수증의 필드(이 유형에만, 그리고 목록이 아닌 카드에만 있어요). 필드는 문서 전체에서 추출하므로 문서 전체에 접근할 수 없으면 null이에요.

  • warningsarray of ReviewWarning

    문서 파싱 경고(ReviewWarning. 목록이 아닌 카드에만 있어요).

  • enrichmentCardEnrichmentStatus | null

    정보 보강 상태(목록이 아닌 카드에만 있어요). 문서 유형, 청구서 필드, 재무 기록은 인덱싱 후 백그라운드에서 추가되며 나중에 다시 계산될 수 있어요. 준비되면 카드에 나타나요. null이면 상태를 알 수 없어요(백그라운드 정보 보강 없이 인덱싱된 카드).

  • external_idstring | null

    연동 개발자 시스템에서 쓰는 카드 ID. 소스에서 오지 않은 카드 사이에서 조직 내 고유해요. null이면 설정되지 않은 상태예요. /v1/cards-by-external-id/{external_id} 경로는 이 값으로 카드를 읽고 교체해요.

    length ≤ 512

  • metadataMetadata
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

403이 동작은 허용되지 않아요. 역할이 부족하거나, 컬렉션이나 카드에 접근할 수 없거나, 요청이 “View as” 모드로 실행 중이거나, 조직이 정지 또는 삭제된 경우예요(`detail` 필드는 `code: org_suspended | org_deleted` 값을 가진 객체예요).

응답 헤더

  • 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

404객체가 없거나 접근할 수 없어요. 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 헤더가 있어요. 그만큼 기다린 뒤 재시도하세요.

← cards · API 레퍼런스