Přejít na obsah
Sursa Developers

GET/v1/cards

Vypsat karty

list_cards

Vrací karty s filtry, řazením a stránkováním. S preview=1 (pro zobrazení dlaždic) má každá karta navíc preview (prvních 200 znaků textu) a preview_tables (listy s počty řádků), v mezích vašeho datového profilu.

Autentizace

Odešlete klíč API v hlavičce Authorization: Authorization: Bearer <klíč>.

Parametry dotazu

  • collectionstring | null
  • folderstring | null

    <folder ID> vrací karty složky a všech jejích podsložek. none vrací karty kolekce, které nejsou v žádné složce, a vyžaduje collection (jinak 400 cards.invalid_folder_filter). Pokud složka neexistuje nebo pro vás není viditelná, požadavek vrací 404 folders.not_found.

    length ≤ 64

  • statusstring | null

    Povolené hodnoty: processingreadyerrorarchivedall

  • ownerstring | null

    me, none nebo ID uživatele.

  • owner_idinteger | null
  • verificationstring | null

    Povolené hodnoty: verifiedneeds_verificationstale

  • kindCardKind
  • typestring | null

    table vrací karty s tabulkami faktů, text karty bez nich.

    Povolené hodnoty: tabletext

  • tagsstring | null

    Štítky oddělené čárkou (karta musí mít všechny).

  • idsstring | null

    ID karet oddělená čárkou.

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

    Výchozí: "created_at"

  • orderstring

    Povolené hodnoty: ascdesc

    Výchozí: "desc"

  • limitinteger

    Výchozí: 200

  • offsetinteger

    Výchozí: 0

  • previewboolean

    true přidá preview (prvních 200 znaků) a preview_tables pro zobrazení dlaždic.

    Výchozí: false

  • updated_sincestring (date-time)

    Jen karty s updated_at v tento okamžik nebo později (RFC 3339 s časovým posunem), pro synchronizaci. Bez explicitních sort a order je seznam seřazen podle updated_at vzestupně, poté podle id. Smazané karty se nevypisují: smazání přicházejí jako události.

  • metadatamap of string

    Filtr podle metadata: metadata[<key>]=<value> vyhovuje při přesné shodě. Nejvýše 3 podmínky a všechny musí platit (?metadata[team]=support&metadata[crm_id]=A-1042). Více než 3 podmínky nebo neplatný klíč vrací 400 api.metadata_invalid.

  • collection_idinteger

    Kolekce podle ID. Je-li předán i collection, má přednost collection_id. Kolekce, která v organizaci neexistuje nebo není viditelná, vrací 404 collections.not_found.

  • external_idstring

    Jen karta s tímto external_id.

  • cursorstring

    Kurzor další stránky z X-Next-Cursor nebo z next_cursor předchozí odpovědi se stejnými filtry; nese i velikost stránky. Společně s offset: 422 validation.failed; kurzor jiného seznamu, jiných filtrů nebo poškozený kurzor: 400 api.cursor_invalid.

    length ≤ 512

  • expand[]array of string

    Související objekty, které se mají zahrnout do odpovědi (od verze 1.62.0): cesta ze seznamu x-expandable operace. Parametr lze opakovat až 10krát. Cesta má nejvýše 2 segmenty oddělené tečkou (collection.default_owner). V seznamu cesta začíná prefixem data. a platí pro každou položku stránky (expand[]=data.owner). Rozbalený objekt se vloží do objektu expanded položky a pole s ID zůstává. Objekt, který volající podle kontrol jeho vlastní operace čtení nesmí vidět, se rozbalí jako null. Neznámá cesta, více než 10 cest nebo cesta delší než 2 segmenty vrací 400 api.expand_invalid.

    items ≤ 10

Parametry hlavičky

  • X-View-Asstring

    Jen pro klíče API s rolí admin. Provede požadavek jako datový profil <profile>[:viewer|verifier|editor], například employee:viewer. Instalační klíč tuto hlavičku použít nemůže (403).

Parametry cookie

  • kb_view_asstring

    Cookie režimu „View as“ pro relaci. POST /auth/view-as ji nastaví a DELETE /auth/view-as ji smaže.

Odpovědi

200Úspěšná odpověď

Hlavičky odpovědi

  • Link

    Adresa další stránky, <…>; rel="next". Chybí-li hlavička, jde o poslední stránku.

  • X-Next-Cursor

    Kurzor další stránky pro parametr cursor. Chybí-li hlavička, jde o poslední stránku.

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: CardList

array of Card
  • expandedCardExpanded
  • permissionsObjectPermissionList
  • accessstring

    Povolené hodnoty: wholepartial

  • access_contactstring

    Na koho se obrátit kvůli přístupu (jen když access=partial).

  • aclobject
    Pole
    • verifybooleanpovinné
    • writebooleanpovinné
  • categorystringpovinné
  • category_confidencenumber | nullpovinné
  • category_lockedbooleanpovinné
  • category_reviewbooleanpovinné
  • category_sourceCategorySource | nullpovinné
  • collectionstringpovinné
  • collection_idintegerpovinné
  • collection_titlestring
  • commentsarray of CardComment
  • content_jsonContentJSON | null

    Obsah editoru poslední publikované verze. Pole může chybět; v takovém případě získejte obsah editoru z konceptu (POST /v1/drafts s card_id).

  • editing_lockEditingLock | null

    Aktivní zámek úprav. Pole může chybět; v takovém případě editor zjistí, kdo zámek drží, z 409 cards.locked při POST /v1/cards/{card_id}/lock.

  • created_atstring (date-time)povinné
  • days_since_verifiedintegerpovinné
  • errorstring | nullpovinné
  • eventsarray of CardEvent
  • feedback_negintegerpovinné
  • feedback_posintegerpovinné
  • foldersarray of CardFolderRef

    Jen seznam karet: složky, které kartu obsahují (ty, které uživatel vidí), s cestami od kořene kolekce. Prázdný seznam znamená, že karta není v žádné složce.

  • has_tablesboolean

    Jen seznam karet.

  • hidden_partsboolean
  • idstringpovinné
  • jobJob | null
  • kindCardKindpovinné
  • org_idintegerpovinné
  • owner_activeboolean | null
  • owner_idinteger | nullpovinné
  • owner_namestring | nullpovinné
  • pagesinteger | nullpovinné
  • parserstring | nullpovinné

    Parser dokumentu jako neutrální kód: document (úplná struktura: stránky, nadpisy, tabulky, naskenované stránky), pdf (textová vrstva PDF), docx, xlsx, csv, markdown, html, text. Seznam se může rozšířit.

  • partsarray of CardPartpovinné
  • sensitivebooleanpovinné
  • sha256string | nullpovinné
  • sizeintegerpovinné
  • snoozed_atstring (date-time) | null
  • snoozed_byinteger | null
  • snoozed_untilstring | null
  • source_changedbooleanpovinné
  • source_pathstring | nullpovinné
  • source_urlstring | nullpovinné
  • statusstringpovinné

    Povolené hodnoty: processingreadyerrorarchived

  • tablesarray of CardTable
  • tagsarray of stringpovinné
  • titlestringpovinné
  • trustnumberpovinné
  • trust_if_verifiednumber
  • trust_partsTrustPartspovinné
  • updated_atstring (date-time)povinné
  • verificationVerificationpovinné
  • verified_atstring (date-time) | nullpovinné
  • verified_byinteger | nullpovinné
  • verified_by_namestring | null
  • verifier_idsarray of integerpovinné
  • verifiersarray of object
    Pole
    • activebooleanpovinné
    • idintegerpovinné
    • namestringpovinné
  • verify_interval_daysintegerpovinné
  • versionintegerpovinné
  • versionsarray of CardVersion
  • source_archiveArchiveSource
  • created_byinteger | null
  • manual_optionsobject

    Ruční nastavení parsování (náhled).

  • doc_kindDocKind | null

    Typ dokumentu. null, pokud typ není určen (například u karet zaindexovaných před zavedením typů dokumentů).

  • doc_kind_confidencenumber | null

    Míra jistoty typu dokumentu, od 0 do 1.

  • doc_kind_sourcestring | null

    Co typ určilo: pravidla (rules), uživatel (manual), nebo automatická klasifikace. Seznam se může rozšířit: neznámou hodnotu považujte za automatickou klasifikaci.

    Povolené hodnoty: rulesmanualnull

  • invoiceDocInvoiceExtraction | null

    Pole faktury, dobropisu nebo účtenky (jen u těchto typů a jen v kartě, ne v seznamu). null, pokud nemáte přístup k celému dokumentu, protože pole se vytěžují z celého dokumentu.

  • warningsarray of ReviewWarning

    Upozornění k parsování dokumentu (ReviewWarning; jen v kartě, ne v seznamu).

  • enrichmentCardEnrichmentStatus | null

    Stav obohacení (jen v kartě, ne v seznamu). Typ dokumentu, pole faktury a finanční záznamy se doplňují na pozadí po indexování a později je lze přepočítat; v kartě se objeví, jakmile jsou připravené. null znamená, že stav není k dispozici (karta byla zaindexována bez obohacení na pozadí).

  • external_idstring | null

    ID karty v systému integrátora. V organizaci je jedinečné mezi kartami, které nepocházejí ze zdrojů; null znamená, že není nastaveno. /v1/cards-by-external-id/{external_id} podle něj kartu čte a nahrazuje.

    length ≤ 512

  • metadataMetadata
400Požadavek je neplatný: hodnota parametru nebo stav objektu akci neumožňuje (`detail` je zpráva).

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

401Nebyly odeslány žádné přihlašovací údaje (ani cookie relace, ani klíč API), nebo klíč nebyl nalezen.

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

403Akce není povolena: role nestačí, chybí přístup ke kolekci nebo kartě, požadavek běží v režimu „View as“, nebo je organizace pozastavená či smazaná (`detail` je objekt s `code: org_suspended | org_deleted`).

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

404Objekt neexistuje nebo vám není dostupný. API nepotvrzuje, že objekt s omezeným přístupem existuje.

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

422Chyba validace: tělo nebo parametry neodpovídají schématu (`detail` je seznam chyb validace), nebo je hodnota parametru mimo povolený rozsah (`detail` je zpráva).

Hlavičky odpovědi

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

429Příliš mnoho požadavků (`api.rate_limited`), kvóta organizace na minutu, den nebo měsíc je vyčerpána (`api.quota_exceeded`; `error.details` obsahuje `quota`, `limit` a `reset_at`), organizace dosáhla svého limitu nebo je služba odpovědí vytížená (`answers.engine_busy`). Počkejte dobu uvedenou v hlavičce `Retry-After`.

Hlavičky odpovědi

  • Retry-After

    Počet sekund, které je třeba počkat před opakováním požadavku.

  • RateLimit-Policy

    Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.

  • RateLimit

    Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).

  • X-RateLimit-Remaining

    Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.

  • X-RateLimit-Reset

    Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

Chybové kódy

Kódy, které tato operace může vrátit v error.code, kromě obecných kódů každého požadavku.

Limity četnosti

Odpovědi obsahují hlavičky RateLimit a RateLimit-Policy a starší X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset. Odpověď 429 má hlavičku Retry-After v sekundách: počkejte a požadavek zopakujte.

← cards · Reference API