Developers
Uploads6

Create an upload

POST/uploads

Opens 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.

Files with purpose set to import must be Excel spreadsheets in the .xlsx format. Other formats, such as .csv or .xls, are rejected with 422 validation_failed.

This operation requires an Idempotency-Key header. The Location header points to the created upload session.

Authorization

AuthorizationBearer <token>

Autonomous mode: the API credential secret, sent as a bearer token. Credential secrets are identified by a fixed prefix.

In: header

Header Parameters

Idempotency-Key*string

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.

X-Client-Request-Id?string

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.

Lengthlength <= 64

Request 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",      "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.