POST/v1/uploads/{upload_id}/complete

Upload abschließen

complete_upload

Wenn alle Teile empfangen sind, setzt Sursa die Datei zusammen, vergleicht den SHA-256 der gesamten Datei mit sha256 im Body und führt dieselben Prüfungen aus wie bei einem Upload in einer einzigen Anfrage: das Format anhand der Signatur des Inhalts und die Virenprüfung. Das Ergebnis ist ready oder rejected mit reject_reason (checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content). Jede Ablehnung durch die Format- oder Virenprüfung wird im Audit-Log als file.rejected festgehalten.

Eine Antwort 200 bedeutet, dass das Ergebnis bereitsteht; 202 bedeutet, dass die Datei noch geprüft wird (processing), und das Ergebnis liefert GET /v1/uploads/{upload_id}. Kehrt der Status zu pending zurück (ein Neustart einer API-Instanz hat die Prüfung unterbrochen), senden Sie complete erneut. Eine Wiederholung von complete nach dem Ergebnis liefert dasselbe Ergebnis. Fehlende Teile ergeben 409 uploads.incomplete (details.missing). Ein sha256, der von dem bei der Erstellung angegebenen abweicht, oder ein parts[].etag, das von einem empfangenen Teil abweicht, ergibt 422 uploads.checksum_mismatch. Ein bereiter, nicht verwendeter Upload bleibt 24 Stunden lang bestehen. Hinzugefügt in 1.62.0.

Authentifizierung

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

Pfadparameter

upload_idstringerforderlich
Die Upload-ID (upl_ gefolgt von 32 Hex-Zeichen).
length ≤ 64

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: UploadComplete

sha256stringerforderlich
Der SHA-256 der gesamten Datei.
partsarray of UploadPartRef
Optionale Prüfung der Teile: das ETag jedes Teils, wie von PUT …/parts/{n} zurückgegeben.
items ≤ 1000

Antworten

200Das Ergebnis steht bereit: `ready` oder `rejected`.

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: Upload

idstringerforderlich
Die Upload-ID (upl_ gefolgt von 32 Hex-Zeichen).
purposeUploadPurposeerforderlich
filenamestringerforderlich
Der Dateiname (ohne Ordner).
content_typestringerforderlich
Der deklarierte Inhaltstyp; leer, wenn nicht deklariert.
sizeinteger (int64)erforderlich
Die Dateigröße in Bytes.
sha256string | nullerforderlich
Der SHA-256 der Datei, angegeben bei der Erstellung oder bei complete; null, wenn noch nicht bekannt.
statusUploadStatuserforderlich
part_sizeinteger (int64)erforderlich
Die Größe jedes Teils außer dem letzten (5 bis 100 MiB).
part_countintegererforderlich
Die Anzahl der Teile.
≥ 1, ≤ 1000
parts_receivedintegererforderlich
Die Anzahl der empfangenen Teile.
≥ 0
partsarray of UploadParterforderlich
Die empfangenen Teile nach Nummer (leer in der Antwort von POST /v1/uploads).
reject_reasonstring | nullerforderlich
Der Grund der Ablehnung (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. Die Aufzählung kann wachsen; null, wenn nicht abgelehnt.
reject_detailsobject | nullerforderlich
Details der Ablehnung (die Erweiterung, das deklarierte und das erkannte Format, Prüfsummen); null, wenn nicht abgelehnt.
created_atstring (date-time)erforderlich
Zeitpunkt der Erstellung des Uploads.
expires_atstring (date-time)erforderlich
Die Frist, um den Upload abzuschließen und ihn, sobald er bereit ist, zu verwenden.
completed_atstring (date-time) | nullerforderlich
Zeitpunkt, zu dem die Prüfung abgeschlossen wurde (ready oder rejected).
consumed_atstring (date-time) | nullerforderlich
Zeitpunkt, zu dem der Upload verwendet wurde (von einer Karte, einem Archiv oder einem Import).

202Die Datei wird noch geprüft (`processing`).

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: Upload

idstringerforderlich
Die Upload-ID (upl_ gefolgt von 32 Hex-Zeichen).
purposeUploadPurposeerforderlich
filenamestringerforderlich
Der Dateiname (ohne Ordner).
content_typestringerforderlich
Der deklarierte Inhaltstyp; leer, wenn nicht deklariert.
sizeinteger (int64)erforderlich
Die Dateigröße in Bytes.
sha256string | nullerforderlich
Der SHA-256 der Datei, angegeben bei der Erstellung oder bei complete; null, wenn noch nicht bekannt.
statusUploadStatuserforderlich
part_sizeinteger (int64)erforderlich
Die Größe jedes Teils außer dem letzten (5 bis 100 MiB).
part_countintegererforderlich
Die Anzahl der Teile.
≥ 1, ≤ 1000
parts_receivedintegererforderlich
Die Anzahl der empfangenen Teile.
≥ 0
partsarray of UploadParterforderlich
Die empfangenen Teile nach Nummer (leer in der Antwort von POST /v1/uploads).
reject_reasonstring | nullerforderlich
Der Grund der Ablehnung (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. Die Aufzählung kann wachsen; null, wenn nicht abgelehnt.
reject_detailsobject | nullerforderlich
Details der Ablehnung (die Erweiterung, das deklarierte und das erkannte Format, Prüfsummen); null, wenn nicht abgelehnt.
created_atstring (date-time)erforderlich
Zeitpunkt der Erstellung des Uploads.
expires_atstring (date-time)erforderlich
Die Frist, um den Upload abzuschließen und ihn, sobald er bereit ist, zu verwenden.
completed_atstring (date-time) | nullerforderlich
Zeitpunkt, zu dem die Prüfung abgeschlossen wurde (ready oder rejected).
consumed_atstring (date-time) | nullerforderlich
Zeitpunkt, zu dem der Upload verwendet wurde (von einer Karte, einem Archiv oder einem Import).

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

410Das Objekt existierte, ist aber nicht mehr verfügbar: Der Link wurde bereits verwendet oder ist abgelaufen, oder die Datei wurde am Ende ihrer Aufbewahrungsfrist gelöscht.

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.

← uploads · API-Referenz

curl -X POST 'https://api.sursa.com/v1/uploads/UPLOAD_ID/complete' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"sha256":"0123456789abcdefABCDEF0123456789abcdefABCDEF0123456789abcdefABCD"}' \
  -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

upload_id path *

Idempotency-Key

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

Anfragetext (JSON)