Direct naar de inhoud
Sursa Developers

POST/v1/uploads/{upload_id}/complete

Upload afronden

complete_upload

Als alle delen zijn ontvangen, voegt Sursa het bestand samen, vergelijkt de SHA-256 van het hele bestand met sha256 in de body en voert dezelfde controles uit als bij een upload in één request: het formaat op signatuur van de inhoud en de virusscan. Het resultaat is ready, of rejected met reject_reason (checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content). Elke weigering door de controle op formaat of virussen wordt in het auditlog vastgelegd als file.rejected.

Een response 200 betekent dat het resultaat klaar is; 202 betekent dat het bestand nog wordt gecontroleerd (processing), en het resultaat komt van GET /v1/uploads/{upload_id}. Als de status terugkeert naar pending (een herstart van een API-instantie heeft de controle onderbroken), stuur dan opnieuw complete. complete herhalen na het resultaat geeft hetzelfde resultaat. Ontbrekende delen geven 409 uploads.incomplete (details.missing). Een sha256 die afwijkt van de waarde die bij het aanmaken is opgegeven, of een parts[].etag die afwijkt van een ontvangen deel, geeft 422 uploads.checksum_mismatch. Een klare upload die niet wordt gebruikt, blijft 24 uur bestaan. Toegevoegd in 1.62.0.

Authenticatie

Stuur een API-sleutel mee in de header Authorization: Authorization: Bearer <sleutel>.

Padparameters

  • upload_idstringverplicht

    De ID van de upload (upl_ gevolgd door 32 hexadecimale tekens).

    length ≤ 64

Headerparameters

  • Idempotency-Keystring

    Sleutel om een schrijfactie veilig opnieuw te proberen: 1 tot 255 afdrukbare ASCII-tekens; een UUID v4 per logische bewerking wordt aanbevolen. Een nieuwe poging met dezelfde sleutel binnen 24 uur voert de bewerking niet opnieuw uit: Sursa geeft de opgeslagen response terug (status, headers en body) met de header Idempotency-Replayed: true. Dezelfde sleutel met een andere methode, een ander pad, een andere Content-Type of een andere body geeft 409 api.idempotency_mismatch; zolang het eerste request nog loopt, 409 api.idempotency_in_progress met Retry-After: 1. Na een 5xx- of 429-response wordt de sleutel vrijgegeven en voert een nieuwe poging de bewerking opnieuw uit. De sleutel geldt per organisatie en per aanroeper (API-sleutel, gebruiker of bronsleutel).

    length ≥ 1, length ≤ 255

Request-body

application/json

Object: UploadComplete

  • sha256stringverplicht

    De SHA-256 van het hele bestand.

  • partsarray of UploadPartRef

    Optionele controle van de delen: de ETag van elk deel zoals PUT …/parts/{n} die teruggeeft.

    items ≤ 1000

Responses

200Het resultaat is klaar: `ready` of `rejected`.

Responseheaders

  • RateLimit-Policy

    Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.

  • RateLimit

    Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).

  • X-RateLimit-Remaining

    Resterende requests onder de strengste limiet.

  • X-RateLimit-Reset

    Seconden tot de strengste limiet wordt teruggezet.

  • Idempotency-Replayed

    true: de response is opnieuw afgespeeld uit de opgeslagen response voor deze Idempotency-Key; de bewerking is niet opnieuw uitgevoerd.

application/json

Object: Upload

  • idstringverplicht

    De ID van de upload (upl_ gevolgd door 32 hexadecimale tekens).

  • purposeUploadPurposeverplicht
  • filenamestringverplicht

    De bestandsnaam (zonder mappen).

  • content_typestringverplicht

    Het opgegeven inhoudstype; leeg als het niet is opgegeven.

  • sizeinteger (int64)verplicht

    De bestandsgrootte in bytes.

  • sha256string | nullverplicht

    De SHA-256 van het bestand, opgegeven bij het aanmaken of bij complete; null als die nog niet bekend is.

  • statusUploadStatusverplicht
  • part_sizeinteger (int64)verplicht

    De grootte van elk deel behalve het laatste (van 5 tot 100 MiB).

  • part_countintegerverplicht

    Het aantal delen.

    ≥ 1, ≤ 1000

  • parts_receivedintegerverplicht

    Het aantal ontvangen delen.

    ≥ 0

  • partsarray of UploadPartverplicht

    De ontvangen delen per nummer (leeg in de response van POST /v1/uploads).

  • reject_reasonstring | nullverplicht

    De reden van de afwijzing (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. De enumeratie kan groeien; null als de upload niet is afgewezen.

  • reject_detailsobject | nullverplicht

    Details van de afwijzing (de extensie, het opgegeven en het herkende formaat, de controlesommen); null als de upload niet is afgewezen.

  • created_atstring (date-time)verplicht

    Wanneer de upload is aangemaakt.

  • expires_atstring (date-time)verplicht

    De uiterste termijn om de upload af te ronden en, zodra die klaar is, te gebruiken.

  • completed_atstring (date-time) | nullverplicht

    Wanneer de controle klaar was (ready of rejected).

  • consumed_atstring (date-time) | nullverplicht

    Wanneer de upload is gebruikt (door een kaart, een archief of een import).

202Het bestand wordt nog gecontroleerd (`processing`).

Responseheaders

  • RateLimit-Policy

    Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.

  • RateLimit

    Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).

  • X-RateLimit-Remaining

    Resterende requests onder de strengste limiet.

  • X-RateLimit-Reset

    Seconden tot de strengste limiet wordt teruggezet.

  • Idempotency-Replayed

    true: de response is opnieuw afgespeeld uit de opgeslagen response voor deze Idempotency-Key; de bewerking is niet opnieuw uitgevoerd.

application/json

Object: Upload

  • idstringverplicht

    De ID van de upload (upl_ gevolgd door 32 hexadecimale tekens).

  • purposeUploadPurposeverplicht
  • filenamestringverplicht

    De bestandsnaam (zonder mappen).

  • content_typestringverplicht

    Het opgegeven inhoudstype; leeg als het niet is opgegeven.

  • sizeinteger (int64)verplicht

    De bestandsgrootte in bytes.

  • sha256string | nullverplicht

    De SHA-256 van het bestand, opgegeven bij het aanmaken of bij complete; null als die nog niet bekend is.

  • statusUploadStatusverplicht
  • part_sizeinteger (int64)verplicht

    De grootte van elk deel behalve het laatste (van 5 tot 100 MiB).

  • part_countintegerverplicht

    Het aantal delen.

    ≥ 1, ≤ 1000

  • parts_receivedintegerverplicht

    Het aantal ontvangen delen.

    ≥ 0

  • partsarray of UploadPartverplicht

    De ontvangen delen per nummer (leeg in de response van POST /v1/uploads).

  • reject_reasonstring | nullverplicht

    De reden van de afwijzing (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. De enumeratie kan groeien; null als de upload niet is afgewezen.

  • reject_detailsobject | nullverplicht

    Details van de afwijzing (de extensie, het opgegeven en het herkende formaat, de controlesommen); null als de upload niet is afgewezen.

  • created_atstring (date-time)verplicht

    Wanneer de upload is aangemaakt.

  • expires_atstring (date-time)verplicht

    De uiterste termijn om de upload af te ronden en, zodra die klaar is, te gebruiken.

  • completed_atstring (date-time) | nullverplicht

    Wanneer de controle klaar was (ready of rejected).

  • consumed_atstring (date-time) | nullverplicht

    Wanneer de upload is gebruikt (door een kaart, een archief of een import).

401Er zijn geen authenticatiegegevens meegestuurd (geen sessiecookie en geen API-sleutel), of de sleutel is niet gevonden.

Responseheaders

  • RateLimit-Policy

    Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.

  • RateLimit

    Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).

  • X-RateLimit-Remaining

    Resterende requests onder de strengste limiet.

  • X-RateLimit-Reset

    Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

403De actie is niet toegestaan: de rol volstaat niet, er is geen toegang tot de collectie of kaart, het request draait in de modus “View as”, of de organisatie is opgeschort of verwijderd (`detail` is een object met `code: org_suspended | org_deleted`).

Responseheaders

  • RateLimit-Policy

    Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.

  • RateLimit

    Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).

  • X-RateLimit-Remaining

    Resterende requests onder de strengste limiet.

  • X-RateLimit-Reset

    Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

404Het object bestaat niet of is niet voor jou beschikbaar. De API bevestigt niet dat een afgeschermd object bestaat.

Responseheaders

  • RateLimit-Policy

    Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.

  • RateLimit

    Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).

  • X-RateLimit-Remaining

    Resterende requests onder de strengste limiet.

  • X-RateLimit-Reset

    Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

409De toestand van het object staat de actie niet toe, bijvoorbeeld een duplicaat, een lopende indexering of een job die al is verwerkt.

Responseheaders

  • RateLimit-Policy

    Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.

  • RateLimit

    Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).

  • X-RateLimit-Remaining

    Resterende requests onder de strengste limiet.

  • X-RateLimit-Reset

    Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

410Het object bestond, maar is niet meer beschikbaar: de link is al gebruikt of verlopen, of het bestand is aan het einde van de bewaartermijn verwijderd.

Responseheaders

  • RateLimit-Policy

    Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.

  • RateLimit

    Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).

  • X-RateLimit-Remaining

    Resterende requests onder de strengste limiet.

  • X-RateLimit-Reset

    Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

422Validatiefout: de body of de parameters komen niet overeen met het schema (`detail` is een lijst met validatiefouten), of een parameterwaarde valt buiten het bereik (`detail` is een melding).

Responseheaders

  • RateLimit-Policy

    Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.

  • RateLimit

    Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).

  • X-RateLimit-Remaining

    Resterende requests onder de strengste limiet.

  • X-RateLimit-Reset

    Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

429Te veel requests (`api.rate_limited`), het quotum van de organisatie voor de minuut, dag of maand is op (`api.quota_exceeded`; `error.details` bevat `quota`, `limit` en `reset_at`), de limiet van de organisatie is bereikt, of de antwoorddienst is bezet (`answers.engine_busy`). Wacht de tijd af die in de header `Retry-After` staat.

Responseheaders

  • Retry-After

    Aantal seconden dat je moet wachten voordat je het request opnieuw probeert.

  • RateLimit-Policy

    Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.

  • RateLimit

    Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).

  • X-RateLimit-Remaining

    Resterende requests onder de strengste limiet.

  • X-RateLimit-Reset

    Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

Foutcodes

Codes die dit endpoint in error.code kan teruggeven, naast de algemene codes van elk request.

Veilig opnieuw proberen

Stuur bij elke POST en PATCH een header Idempotency-Key mee (bijvoorbeeld een UUID). Een nieuwe poging met dezelfde sleutel binnen 24 uur geeft de opgeslagen response terug, zonder het request opnieuw uit te voeren.

Snelheidslimieten

Responses bevatten de headers RateLimit en RateLimit-Policy en de eerdere X-RateLimit-Limit, X-RateLimit-Remaining en X-RateLimit-Reset. Een response met status 429 bevat Retry-After in seconden: wacht en probeer het daarna opnieuw.

← uploads · API-referentie