Cancel an upload
/uploads/{upload_id}Cancels an open upload session. Set status to cancelled; no other change is supported.
Sessions that are already completed, cancelled, failed, or expired cannot be cancelled and return state_conflict. To remove a file produced by a completed upload, use the delete file operation.
Credential: the API credential secret, sent as a bearer token. Credential secrets are identified by a fixed prefix.
In: header
Path Parameters
Public ID of the upload, prefixed with upl_.
Header Parameters
Client-generated key that makes the request safe to retry. Must be 1 to 128 characters from [A-Za-z0-9._:-]. Optional on this operation; when sent, a malformed key returns idempotency_key_invalid, and repeating the request with the same key and the same body returns the stored result with Idempotent-Replayed: true.
Optional client-generated identifier of the request, up to 64 characters from [A-Za-z0-9._-]. Echoed back in the response and recorded in the request log; it never replaces the server-generated X-Request-Id.
length <= 64Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://example.com/uploads/string" \ -H "Content-Type: application/json" \ -d '{ "status": "cancelled" }'{ "data": { "expires_at": "2019-08-24T14:15:22Z", "failure_reason": "string", "file": { "checksum": { "md5": "string", "sha256": "string" }, "content_type": "string", "created_at": "2019-08-24T14:15:22Z", "expires_at": "2019-08-24T14:15:22Z", "extension": "string", "filename": "string", "id": "string", "object": "file", "purpose": "string", "size_bytes": 0, "status": "ready" }, "filename": "string", "id": "string", "object": "upload", "part_size": 0, "parts_total": 0, "purpose": "string", "size_bytes": 0, "status": "open" }}Retrieve an upload GET
Retrieves an upload session by its public ID, including its current status and expiration time. When the session is `completed`, the response includes the resulting `file`. To see which parts the storage service has already received, use the list upload parts operation.
Complete an upload POST
Completes a multipart upload after all parts have been sent to the storage service. Provide every part number together with the `ETag` returned by the storage service for that part. The storage service verifies the integrity of the assembled content. On success, the session moves to `completed` and the response includes the resulting `file`. The file must be used by a resource within 24 hours (for example as a lesson attachment, an image, an import source or a link in lesson, FAQ, legal term or question reply content). Otherwise it is deleted; `file.expires_at` shows the deadline. If the content does not match the declared size, checksum, or content type, the API returns `upload_integrity_mismatch` with the exact cause in `details[].reason`. The session is then permanently marked as `failed`, and a new upload session is required. The actual size of the assembled file is checked again against the limit of the session `purpose`. A file above the limit is removed, the session is marked as `failed` with `failure_reason` set to `too_large`, and the API returns `422 validation_failed` on `size_bytes`. A session whose `filename` extension is outside the list of its `purpose` fails the same way, with `extension_not_allowed` and `422 validation_failed` on `filename`. The actual size is also checked against the storage quota of the account. A file that would take the storage in use above the quota is removed, the session is marked as `failed` with `failure_reason` set to `storage_quota`, and the API returns `409 quota_exceeded` with `reason`, `used_bytes`, and `quota_bytes` in `details[0]`.