Create an upload
/uploadsOpens a multipart upload session and returns the upload plan: the part size (part_size) and the number of parts (parts_total).
The API never receives file content. Request presigned URLs through the upload parts operation and send each part directly to the storage service, then complete the upload to obtain the file.
Each purpose accepts a fixed list of file extensions (the last suffix of filename, case-insensitive) and a maximum size:
image:.jpg,.jpeg,.png,.gif,.webp; up to 10 MiB.pdf:.pdf; up to 100 MiB.import:.xls,.xlsx; up to 20 MiB.editoranddocument:.pdf,.doc,.docx,.xls,.xlsx,.xlsm,.ppt,.pptx,.pps,.ppsx,.odt,.ods,.odp,.txt,.csv,.rtf,.md,.epub,.jpg,.jpeg,.png,.gif,.webp,.svg,.mp3,.m4a,.wav,.ogg,.aac,.opus,.zip,.rar,.7z; up to 100 MiB, or less when the account sets a lower attachment limit.
Video files are not accepted for any purpose: host videos through the integrated video players. A filename without an extension or with an extension outside the list is rejected with 422 validation_failed on filename; a size_bytes above the limit is rejected with 422 validation_failed on size_bytes. Neither case opens an upload session.
Each account has a storage quota (50 GiB unless a different quota was agreed), which also covers the accounts billed with it, such as its replicas. Files attached to student questions do not count toward it. An upload whose size_bytes would take the storage in use above the quota is rejected with 409 quota_exceeded before any session is opened; details[0] carries reason set to storage_quota, used_bytes, and quota_bytes. Current usage and quota are available from the account usage operation. Files are never deleted or hidden because of the quota.
This operation requires an Idempotency-Key header. The Location header points to the created upload session.
Credential: the API credential secret, sent as a bearer token. Credential secrets are identified by a fixed prefix.
In: header
Header Parameters
Client-generated key that makes the request safe to retry. Must be 1 to 128 characters from [A-Za-z0-9._:-]. Required by this operation: a missing key returns idempotency_key_required, and a malformed key returns idempotency_key_invalid. 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
curl -X POST "https://example.com/uploads" \ -H "Idempotency-Key: string" \ -H "Content-Type: application/json" \ -d '{ "filename": "string", "purpose": "image", "size_bytes": 0 }'{ "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" }}Uploads6
Uploads in API v3: create an upload, retrieve an upload, cancel an upload, complete an upload, list upload parts, create upload part urls.
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.