Zum Inhalt springen
Sursa Developers

GET/v1/cards

Karten auflisten

list_cards

Gibt Karten mit Filtern, Sortierung und Paginierung zurück. Mit preview=1 (für die Kachelansicht) enthält jede Karte zusätzlich preview (die ersten 200 Zeichen des Textes) und preview_tables (Tabellenblätter mit ihrer Zeilenanzahl), im Rahmen Ihres Datenprofils.

Authentifizierung

Senden Sie einen API-Schlüssel im Header Authorization: Authorization: Bearer <Schlüssel>.

Query-Parameter

  • collectionstring | null
  • folderstring | null

    <folder ID> gibt die Karten des Ordners und aller seiner Unterordner zurück. none gibt die Karten der Sammlung zurück, die in keinem Ordner liegen, und erfordert collection (sonst 400 cards.invalid_folder_filter). Existiert der Ordner nicht oder ist er für Sie nicht sichtbar, ergibt die Anfrage 404 folders.not_found.

    length ≤ 64

  • statusstring | null

    Zulässige Werte: processingreadyerrorarchivedall

  • ownerstring | null

    me, none oder eine Benutzer-ID.

  • owner_idinteger | null
  • verificationstring | null

    Zulässige Werte: verifiedneeds_verificationstale

  • kindCardKind
  • typestring | null

    table gibt Karten mit Faktentabellen zurück, text Karten ohne solche.

    Zulässige Werte: tabletext

  • tagsstring | null

    Durch Kommas getrennte Tags (eine Karte muss alle haben).

  • idsstring | null

    Durch Kommas getrennte Karten-IDs.

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

    Standard: "created_at"

  • orderstring

    Zulässige Werte: ascdesc

    Standard: "desc"

  • limitinteger

    Standard: 200

  • offsetinteger

    Standard: 0

  • previewboolean

    true fügt preview (die ersten 200 Zeichen) und preview_tables für die Kachelansicht hinzu.

    Standard: false

  • updated_sincestring (date-time)

    Nur Karten mit updated_at ab diesem Zeitpunkt (einschließlich; RFC 3339 mit Offset), zur Synchronisierung. Ohne explizite Angabe von sort und order wird die Liste aufsteigend nach updated_at und dann nach id sortiert. Gelöschte Karten werden nicht aufgeführt: Löschungen werden als Ereignisse gemeldet.

  • metadatamap of string

    Filter nach metadata: metadata[<key>]=<value> prüft auf exakte Übereinstimmung. Bis zu 3 Bedingungen, die alle erfüllt sein müssen (?metadata[team]=support&metadata[crm_id]=A-1042). Mehr als 3 Bedingungen oder ein ungültiger Schlüssel ergeben 400 api.metadata_invalid.

  • collection_idinteger

    Sammlung nach ID. Wird zusätzlich collection übergeben, hat collection_id Vorrang. Eine Sammlung, die in der Organisation nicht existiert oder nicht sichtbar ist, ergibt 404 collections.not_found.

  • external_idstring

    Nur die Karte mit dieser external_id.

  • cursorstring

    Cursor der nächsten Seite aus X-Next-Cursor oder next_cursor der vorherigen Antwort mit denselben Filtern; er enthält die Seitengröße. Zusammen mit offset: 422 validation.failed; ein Cursor einer anderen Liste, mit anderen Filtern oder ein fehlerhafter Cursor: 400 api.cursor_invalid.

    length ≤ 512

  • expand[]array of string

    Verknüpfte Objekte, die in die Antwort aufgenommen werden (seit 1.62.0): ein Pfad aus der Liste x-expandable der Operation. Wiederholen Sie den Parameter bis zu 10-mal. Ein Pfad hat bis zu 2 durch einen Punkt getrennte Segmente (collection.default_owner). In einer Liste beginnt der Pfad mit data. und gilt für jedes Element der Seite (expand[]=data.owner). Ein erweitertes Objekt kommt in das Objekt expanded des Elements, und das ID-Feld bleibt erhalten. Ein Objekt, das der Aufrufer nach den Zugriffsprüfungen seiner eigenen Leseoperation nicht sehen darf, wird als null erweitert. Ein unbekannter Pfad, mehr als 10 Pfade oder ein Pfad mit mehr als 2 Segmenten ergibt 400 api.expand_invalid.

    items ≤ 10

Header-Parameter

  • X-View-Asstring

    Nur für API-Schlüssel mit der Rolle admin. Führt die Anfrage mit dem Datenprofil <profile>[:viewer|verifier|editor] aus, zum Beispiel employee:viewer. Der Installationsschlüssel kann diesen Header nicht verwenden (403).

Cookie-Parameter

  • kb_view_asstring

    Cookie des Modus „Ansicht als“ für eine Sitzung. POST /auth/view-as setzt es, DELETE /auth/view-as entfernt es.

Antworten

200Erfolgreiche Antwort

Antwort-Header

  • Link

    Adresse der nächsten Seite, <…>; rel="next". Fehlt der Header, ist dies die letzte Seite.

  • X-Next-Cursor

    Cursor der nächsten Seite für den Parameter cursor. Fehlt der Header, ist dies die letzte Seite.

  • RateLimit-Policy

    Geltende Limits im Format des IETF-Entwurfs draft-ietf-httpapi-ratelimit-headers: durch Kommas getrennte Einträge "<name>";q=<quota>;w=<window in seconds>. key ist die Anfragerate des API-Schlüssels (das Kontingent ist der Burst, das Fenster die Zeit bis zum vollständigen Auffüllen; für eine Sitzung heißt der Eintrag user, ohne Anmeldedaten ip); minute, day und month sind die Kontingente der Organisation für die Kalenderminute, den Kalendertag und den Kalendermonat in UTC.

  • RateLimit

    Was von jedem Limit in RateLimit-Policy übrig ist: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit des strengsten Eintrags in RateLimit-Policy (des Eintrags mit den wenigsten verbleibenden Anfragen).

  • X-RateLimit-Remaining

    Verbleibende Anfragen unter dem strengsten Limit.

  • X-RateLimit-Reset

    Sekunden bis zum Zurücksetzen des strengsten Limits.

application/json

Objekt: CardList

array of Card
  • expandedCardExpanded
  • permissionsObjectPermissionList
  • accessstring

    Zulässige Werte: wholepartial

  • access_contactstring

    An wen Sie sich wegen des Zugriffs wenden können (nur bei access=partial).

  • aclobject
    Felder
    • verifybooleanerforderlich
    • writebooleanerforderlich
  • categorystringerforderlich
  • category_confidencenumber | nullerforderlich
  • category_lockedbooleanerforderlich
  • category_reviewbooleanerforderlich
  • category_sourceCategorySource | nullerforderlich
  • collectionstringerforderlich
  • collection_idintegererforderlich
  • collection_titlestring
  • commentsarray of CardComment
  • content_jsonContentJSON | null

    Editorinhalt der neuesten veröffentlichten Version. Das Feld kann fehlen; in diesem Fall erhalten Sie den Editorinhalt aus einem Entwurf (POST /v1/drafts mit card_id).

  • editing_lockEditingLock | null

    Aktive Bearbeitungssperre. Das Feld kann fehlen; in diesem Fall erfährt der Editor über 409 cards.locked bei POST /v1/cards/{card_id}/lock, wer die Sperre hält.

  • created_atstring (date-time)erforderlich
  • days_since_verifiedintegererforderlich
  • errorstring | nullerforderlich
  • eventsarray of CardEvent
  • feedback_negintegererforderlich
  • feedback_posintegererforderlich
  • foldersarray of CardFolderRef

    Nur in der Kartenliste: die Ordner, die die Karte enthalten (die für den Benutzer sichtbaren), mit ihren Pfaden ab der obersten Ebene der Sammlung. Eine leere Liste bedeutet, dass die Karte in keinem Ordner liegt.

  • has_tablesboolean

    Nur in der Kartenliste.

  • hidden_partsboolean
  • idstringerforderlich
  • jobJob | null
  • kindCardKinderforderlich
  • org_idintegererforderlich
  • owner_activeboolean | null
  • owner_idinteger | nullerforderlich
  • owner_namestring | nullerforderlich
  • pagesinteger | nullerforderlich
  • parserstring | nullerforderlich

    Dokumentparser als neutraler Code: document (vollständige Struktur: Seiten, Überschriften, Tabellen, gescannte Seiten), pdf (die Textebene des PDF), docx, xlsx, csv, markdown, html, text. Die Liste kann wachsen.

  • partsarray of CardParterforderlich
  • sensitivebooleanerforderlich
  • sha256string | nullerforderlich
  • sizeintegererforderlich
  • snoozed_atstring (date-time) | null
  • snoozed_byinteger | null
  • snoozed_untilstring | null
  • source_changedbooleanerforderlich
  • source_pathstring | nullerforderlich
  • source_urlstring | nullerforderlich
  • statusstringerforderlich

    Zulässige Werte: processingreadyerrorarchived

  • tablesarray of CardTable
  • tagsarray of stringerforderlich
  • titlestringerforderlich
  • trustnumbererforderlich
  • trust_if_verifiednumber
  • trust_partsTrustPartserforderlich
  • updated_atstring (date-time)erforderlich
  • verificationVerificationerforderlich
  • verified_atstring (date-time) | nullerforderlich
  • verified_byinteger | nullerforderlich
  • verified_by_namestring | null
  • verifier_idsarray of integererforderlich
  • verifiersarray of object
    Felder
    • activebooleanerforderlich
    • idintegererforderlich
    • namestringerforderlich
  • verify_interval_daysintegererforderlich
  • versionintegererforderlich
  • versionsarray of CardVersion
  • source_archiveArchiveSource
  • created_byinteger | null
  • manual_optionsobject

    Manuelle Einstellungen für das Parsing (Vorschau).

  • doc_kindDocKind | null

    Dokumenttyp. null, wenn der Typ nicht bestimmt ist (zum Beispiel bei Karten, die vor Einführung der Dokumenttypen indexiert wurden).

  • doc_kind_confidencenumber | null

    Konfidenz des Dokumenttyps, von 0 bis 1.

  • doc_kind_sourcestring | null

    Was den Typ bestimmt hat: Regeln (rules), ein Benutzer (manual) oder die automatische Klassifizierung. Die Liste kann wachsen: Behandeln Sie einen unbekannten Wert als automatische Klassifizierung.

    Zulässige Werte: rulesmanualnull

  • invoiceDocInvoiceExtraction | null

    Felder einer Rechnung, Gutschrift oder eines Belegs (nur bei diesen Typen und nur in der Karte, nicht in der Liste). null, wenn Sie keinen Zugriff auf das gesamte Dokument haben, da die Felder aus dem gesamten Dokument extrahiert werden.

  • warningsarray of ReviewWarning

    Warnungen beim Parsing des Dokuments (ReviewWarning; nur in der Karte, nicht in der Liste).

  • enrichmentCardEnrichmentStatus | null

    Status der Anreicherung (nur in der Karte, nicht in der Liste). Dokumenttyp, Rechnungsfelder und Finanzeinträge werden nach der Indexierung im Hintergrund hinzugefügt und können später neu berechnet werden; sie erscheinen in der Karte, sobald sie bereit sind. null bedeutet, dass kein Status verfügbar ist (die Karte wurde ohne Hintergrundanreicherung indexiert).

  • external_idstring | null

    ID der Karte im System des Integrators. Die ID ist in der Organisation unter den Karten, die nicht aus Quellen stammen, eindeutig; null bedeutet, dass sie nicht gesetzt ist. /v1/cards-by-external-id/{external_id} liest und ersetzt die Karte anhand dieser ID.

    length ≤ 512

  • metadataMetadata
400Die Anfrage ist ungültig: Ein Parameterwert oder der Zustand des Objekts lässt die Aktion nicht zu (`detail` ist eine Meldung).

Antwort-Header

  • RateLimit-Policy

    Geltende Limits im Format des IETF-Entwurfs draft-ietf-httpapi-ratelimit-headers: durch Kommas getrennte Einträge "<name>";q=<quota>;w=<window in seconds>. key ist die Anfragerate des API-Schlüssels (das Kontingent ist der Burst, das Fenster die Zeit bis zum vollständigen Auffüllen; für eine Sitzung heißt der Eintrag user, ohne Anmeldedaten ip); minute, day und month sind die Kontingente der Organisation für die Kalenderminute, den Kalendertag und den Kalendermonat in UTC.

  • RateLimit

    Was von jedem Limit in RateLimit-Policy übrig ist: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit des strengsten Eintrags in RateLimit-Policy (des Eintrags mit den wenigsten verbleibenden Anfragen).

  • X-RateLimit-Remaining

    Verbleibende Anfragen unter dem strengsten Limit.

  • X-RateLimit-Reset

    Sekunden bis zum Zurücksetzen des strengsten Limits.

application/json

Objekt: Error

401Es wurden keine Anmeldedaten gesendet (weder ein Sitzungscookie noch ein API-Schlüssel), oder der Schlüssel wurde nicht gefunden.

Antwort-Header

  • RateLimit-Policy

    Geltende Limits im Format des IETF-Entwurfs draft-ietf-httpapi-ratelimit-headers: durch Kommas getrennte Einträge "<name>";q=<quota>;w=<window in seconds>. key ist die Anfragerate des API-Schlüssels (das Kontingent ist der Burst, das Fenster die Zeit bis zum vollständigen Auffüllen; für eine Sitzung heißt der Eintrag user, ohne Anmeldedaten ip); minute, day und month sind die Kontingente der Organisation für die Kalenderminute, den Kalendertag und den Kalendermonat in UTC.

  • RateLimit

    Was von jedem Limit in RateLimit-Policy übrig ist: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit des strengsten Eintrags in RateLimit-Policy (des Eintrags mit den wenigsten verbleibenden Anfragen).

  • X-RateLimit-Remaining

    Verbleibende Anfragen unter dem strengsten Limit.

  • X-RateLimit-Reset

    Sekunden bis zum Zurücksetzen des strengsten Limits.

application/json

Objekt: Error

403Die Aktion ist nicht erlaubt: Die Rolle reicht nicht aus, es besteht kein Zugriff auf die Sammlung oder Karte, die Anfrage läuft im Modus „Ansicht als“, oder die Organisation ist gesperrt oder gelöscht (`detail` ist ein Objekt mit `code: org_suspended | org_deleted`).

Antwort-Header

  • RateLimit-Policy

    Geltende Limits im Format des IETF-Entwurfs draft-ietf-httpapi-ratelimit-headers: durch Kommas getrennte Einträge "<name>";q=<quota>;w=<window in seconds>. key ist die Anfragerate des API-Schlüssels (das Kontingent ist der Burst, das Fenster die Zeit bis zum vollständigen Auffüllen; für eine Sitzung heißt der Eintrag user, ohne Anmeldedaten ip); minute, day und month sind die Kontingente der Organisation für die Kalenderminute, den Kalendertag und den Kalendermonat in UTC.

  • RateLimit

    Was von jedem Limit in RateLimit-Policy übrig ist: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit des strengsten Eintrags in RateLimit-Policy (des Eintrags mit den wenigsten verbleibenden Anfragen).

  • X-RateLimit-Remaining

    Verbleibende Anfragen unter dem strengsten Limit.

  • X-RateLimit-Reset

    Sekunden bis zum Zurücksetzen des strengsten Limits.

application/json

Objekt: Error

404Das Objekt existiert nicht oder ist für Sie nicht verfügbar. Die API bestätigt nicht, dass ein eingeschränktes Objekt existiert.

Antwort-Header

  • RateLimit-Policy

    Geltende Limits im Format des IETF-Entwurfs draft-ietf-httpapi-ratelimit-headers: durch Kommas getrennte Einträge "<name>";q=<quota>;w=<window in seconds>. key ist die Anfragerate des API-Schlüssels (das Kontingent ist der Burst, das Fenster die Zeit bis zum vollständigen Auffüllen; für eine Sitzung heißt der Eintrag user, ohne Anmeldedaten ip); minute, day und month sind die Kontingente der Organisation für die Kalenderminute, den Kalendertag und den Kalendermonat in UTC.

  • RateLimit

    Was von jedem Limit in RateLimit-Policy übrig ist: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit des strengsten Eintrags in RateLimit-Policy (des Eintrags mit den wenigsten verbleibenden Anfragen).

  • X-RateLimit-Remaining

    Verbleibende Anfragen unter dem strengsten Limit.

  • X-RateLimit-Reset

    Sekunden bis zum Zurücksetzen des strengsten Limits.

application/json

Objekt: Error

422Validierungsfehler: Der Body oder die Parameter entsprechen nicht dem Schema (`detail` ist eine Liste von Validierungsfehlern), oder ein Parameterwert liegt außerhalb des zulässigen Bereichs (`detail` ist eine Meldung).

Antwort-Header

  • RateLimit-Policy

    Geltende Limits im Format des IETF-Entwurfs draft-ietf-httpapi-ratelimit-headers: durch Kommas getrennte Einträge "<name>";q=<quota>;w=<window in seconds>. key ist die Anfragerate des API-Schlüssels (das Kontingent ist der Burst, das Fenster die Zeit bis zum vollständigen Auffüllen; für eine Sitzung heißt der Eintrag user, ohne Anmeldedaten ip); minute, day und month sind die Kontingente der Organisation für die Kalenderminute, den Kalendertag und den Kalendermonat in UTC.

  • RateLimit

    Was von jedem Limit in RateLimit-Policy übrig ist: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit des strengsten Eintrags in RateLimit-Policy (des Eintrags mit den wenigsten verbleibenden Anfragen).

  • X-RateLimit-Remaining

    Verbleibende Anfragen unter dem strengsten Limit.

  • X-RateLimit-Reset

    Sekunden bis zum Zurücksetzen des strengsten Limits.

application/json

Objekt: Error

429Zu viele Anfragen (`api.rate_limited`), das Kontingent der Organisation für die Minute, den Tag oder den Monat ist aufgebraucht (`api.quota_exceeded`; `error.details` enthält `quota`, `limit` und `reset_at`), das Limit der Organisation ist erreicht, oder der Antwortdienst ist ausgelastet (`answers.engine_busy`). Warten Sie die im Header `Retry-After` angegebene Zeit ab.

Antwort-Header

  • Retry-After

    Anzahl der Sekunden, die Sie warten sollten, bevor Sie die Anfrage wiederholen.

  • RateLimit-Policy

    Geltende Limits im Format des IETF-Entwurfs draft-ietf-httpapi-ratelimit-headers: durch Kommas getrennte Einträge "<name>";q=<quota>;w=<window in seconds>. key ist die Anfragerate des API-Schlüssels (das Kontingent ist der Burst, das Fenster die Zeit bis zum vollständigen Auffüllen; für eine Sitzung heißt der Eintrag user, ohne Anmeldedaten ip); minute, day und month sind die Kontingente der Organisation für die Kalenderminute, den Kalendertag und den Kalendermonat in UTC.

  • RateLimit

    Was von jedem Limit in RateLimit-Policy übrig ist: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit des strengsten Eintrags in RateLimit-Policy (des Eintrags mit den wenigsten verbleibenden Anfragen).

  • X-RateLimit-Remaining

    Verbleibende Anfragen unter dem strengsten Limit.

  • X-RateLimit-Reset

    Sekunden bis zum Zurücksetzen des strengsten Limits.

application/json

Objekt: Error

Fehlercodes

Codes, die dieser Endpunkt in error.code zurückgeben kann, zusätzlich zu den allgemeinen Codes jeder Anfrage.

Ratenlimits

Antworten enthalten die Header RateLimit und RateLimit-Policy sowie die älteren X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset. Eine Antwort 429 enthält Retry-After in Sekunden: Warten Sie und versuchen Sie es dann erneut.

← cards · API-Referenz