Initiate a resumable file upload

Creates a GCS resumable upload session behind our domain. The caller PUTs file chunks to the returned uploadUrl with Content-Range headers.

POST /v1/uploads

Initiate a resumable file upload

cURL

curl --request POST \
  --url https://api.example.com/v1/uploads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "fileName": "<string>",
  "fileSize": 123,
  "contentType": "<string>"
}
'

201

{
  "uploadId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "uploadUrl": "<string>",
  "maxChunkSize": 123,
  "correlationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

Authorizations

Authorization · string · header · required

Clerk session JWT or Unkey API key passed as Bearer token

Headers

x-adclear-workspace-id · string<uuid>

Workspace ID fallback. Required when authenticating with a Bearer token in environments where cookies cannot be shared (e.g. preview). Not needed for API key auth (workspace is embedded in the key metadata) or when the workspace cookie is present.

Example:

"43dc2a1c-3384-41b5-a6e9-3b2d607d0fae"

x-external-user-id · string

Required when authenticating with an API key. Identifies the end-user making the request. Ignored when authenticating with a Bearer token (the user ID is extracted from the token).

Example:

"user_abc123"

x-external-user-email · string<email>

Optional. Email of the external user, used for audit logging. Only applicable when authenticating with an API key.

Example:

"[e-mail]"

Body

application/json

fileName · string · required

Original file name including extension

Minimum string length: 1

fileSize · integer · required

Total file size in bytes. Must not exceed the format-specific limit (e.g. 30 MB for PDF/images, 2 GB for video/audio, 10 MB for documents)

contentType · string · required

MIME type (e.g. application/pdf, image/png)

Minimum string length: 1

Response

201

application/json

Upload initiated — use uploadUrl to PUT file chunks

uploadId · string<uuid> · required

Server-generated upload identifier

uploadUrl · string · required

Relative URL for chunk uploads: PUT /v1/uploads/{uploadId}

maxChunkSize · integer · required

Maximum bytes per PUT chunk request (default 50 MB). Final chunk may be smaller.

correlationId · string<uuid> · required

Correlation ID for request tracing. Include in support requests.