POST/v1/push/sources/{source_id}/documents

Dokument senden (erstellen oder ersetzen)

push_upsert_document

Erstellt oder ersetzt ein Dokument anhand von external_id. Bei JSON senden Sie den Inhalt in content (content_type: html, markdown oder text, bis zu 5 MB). Bei multipart/form-data senden Sie die Datei im Teil file (bis zu 100 MB, dieselben Formate wie bei einem Upload in die Wissensbasis) und die Metadaten im Teil document (JSON derselben Form ohne content) oder als separate Felder external_id, title, url, path, tags. sync_number ist die Nummer der offenen Synchronisierung. Ohne sie wird das Dokument sofort geschrieben (direktes Upsert), aber die nächste vollständige Synchronisierung löscht es, sofern es nicht erneut gesendet wird. Ein erneutes Senden desselben Dokuments ergibt unchanged (idempotent). Das Dokument wird bei der nächsten Synchronisierung der Quelle zu einer Karte (innerhalb einer Minute; innerhalb einer offenen Synchronisierung nach deren Schließen). Seit 1.62.0: Kartenfelder (metadata, category, verifiers, verify_interval_days), eine Datei aus einem Multipart-Upload (upload_id) und Anhänge (attachments); die Antwort enthält status und card_id (das Ergebnis des Dokuments). Das Dokumentlimit einer Quelle hängt vom Tarif ab.

Authentifizierung

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

Pfadparameter

source_idintegererforderlich

Query-Parameter

sync_numberinteger

Header-Parameter

Idempotency-Keystring
Schlüssel für die sichere Wiederholung eines Schreibvorgangs: 1 bis 255 druckbare ASCII-Zeichen; empfohlen wird eine UUID v4 pro logischer Operation. Eine Wiederholung mit demselben Schlüssel innerhalb von 24 Stunden führt die Operation nicht erneut aus, sondern liefert die gespeicherte Antwort (Status, Header und Body) mit dem Header Idempotency-Replayed: true. Derselbe Schlüssel mit einer anderen Methode, einem anderen Pfad, Content-Type oder Body ergibt 409 api.idempotency_mismatch; solange die erste Anfrage noch läuft, 409 api.idempotency_in_progress mit Retry-After: 1. Nach einer 5xx- oder 429-Antwort wird der Schlüssel freigegeben, und eine Wiederholung führt die Operation erneut aus. Der Schlüssel gilt pro Organisation und Aufrufer (API-Schlüssel, Benutzer oder Schlüssel einer benutzerdefinierten Quelle).
length ≥ 1, length ≤ 255

Anfragetext

application/json

Objekt: PushDocument

external_idstringerforderlich
Ihre stabile Dokument-ID. Das Senden derselben ID ersetzt das Dokument.
length ≤ 512
titlestringerforderlich
length ≤ 500
urlstring
Link zum Dokument in Ihrem System (http oder https).
contentstring
Inhalt (bis zu 5 MB).
content_typestring
Zulässige Werte: htmlmarkdowntext
Standard: "html"
patharray of string | string
Ordner des Dokuments: ein Array von Namen oder eine durch „/“ getrennte Zeichenkette (bis zu 10 Ebenen).
permissionsPushPermissions
tagsarray of string
items ≤ 50
author_emailstring
Autor. Wird zur verantwortlichen Person der Karte, wenn es sich um einen Benutzer von Sursa handelt.
updated_atstring (date-time)
Änderungszeitpunkt in Ihrem System (Teil der Dokumentversion).
metadataMetadataPatch
metadata der Karte des Dokuments (seit 1.62.0): Das Objekt ersetzt das bisherige der Karte, {} entfernt alle Paare; ohne das Feld metadata ändern sich die Metadaten der Karte nicht.
categorystring
Kategorie der Karte: der Schlüssel einer Kategorie der Organisation (GET /v1/categories), seit 1.62.0.
length ≤ 64
verifiersPushVerifiers
verify_interval_daysinteger
Prüfintervall der Karte in Tagen (seit 1.62.0); ohne Angabe das Intervall der Quelle.
≥ 1, ≤ 3650
upload_idstring
Datei des Dokuments aus einem Multipart-Upload (upl_…, seit 1.62.0) statt content. Ein Upload wird einmal verwendet; ein erneutes Senden desselben Dokuments mit derselben upload_id verbraucht ihn nicht. Solange Multipart-Uploads in der Installation nicht verfügbar sind, wird das Dokument mit dem Grund file_rejected abgelehnt.
length ≤ 64
attachmentsarray of string
Anhänge des Dokuments als Multipart-Uploads (upl_…, seit 1.62.0): Jeder Anhang wird zu einer eigenen Karte der Quelle mit demselben Ordner, denselben Berechtigungen und Kartenfeldern. Ein Anhang, der in einer neuen Version des Dokuments fehlt, wird archiviert.
items ≤ 20

multipart/form-data

filestring (binary)erforderlich
documentstring
JSON-Metadaten des Dokuments (die Felder von PushDocument ohne content).
external_idstring
titlestring
urlstring
pathstring
tagsstring

Antworten

200Geschrieben

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.
Idempotency-Replayed
true bedeutet, dass die für diesen Idempotency-Key gespeicherte Antwort erneut geliefert wurde: Die Operation wurde nicht noch einmal ausgeführt.

application/json

Objekt: PushDocumentResult

external_idstringerforderlich
resultstringerforderlich
skipped: Ein Dokument eines Batches mit atomic wurde nicht angewendet, weil ein anderes Dokument abgelehnt wurde (seit 1.62.0).
Zulässige Werte: createdupdatedunchangeddeletednot_founderrorskipped
versionstring
Dokumentversion (SHA-256 des Inhalts und der Metadaten).
errorstring
Grund (bei result = error).
statusPushDocumentStatusValue
card_idstring | null
Karte des Dokuments, falls bereits geschrieben (seit 1.62.0).
reasonPushDocumentReason

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

409Der Zustand des Objekts lässt die Aktion nicht zu, zum Beispiel bei einem Duplikat, einer laufenden Indexierung oder einem bereits verarbeiteten Job.

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

413Der Anfragetext überschreitet die zulässige Größe.

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

415Das Dateiformat wird nicht unterstützt.

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.

Sichere Wiederholungen

Senden Sie bei jedem POST und PATCH einen Header Idempotency-Key (zum Beispiel eine UUID). Eine Wiederholung mit demselben Schlüssel innerhalb von 24 Stunden gibt die gespeicherte Antwort zurück, statt die Anfrage erneut auszuführen.

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.

← sources · API-Referenz

curl -X POST 'https://api.sursa.com/v1/push/sources/1/documents' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"crm-1042","title":"Refund policy"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Ausprobieren

API-Schlüssel

Der Schlüssel bleibt im Speicher dieses Tabs und wird nur an https://api.sursa.com gesendet.

Anfragen wirken auf die echten Daten Ihrer Organisation.

Idempotency-Key header

source_id path *

sync_number query

Idempotency-Key

Ist das Feld leer, wird für jede Anfrage ein neuer Schlüssel erzeugt.

Anfragetext (JSON)