Uploads

Two-step presigned upload flow. `init` returns a short-lived URL the client PUTs the file bytes to directly; `confirm` finalises the upload and returns the canonical CDN URL.

POST /api/v1/uploads/init

Reserve an upload slot. Honours Idempotency-Key; replaying the same key returns the original upload_url instead of provisioning a new one.

Body

Field	Type	Description
`filename`	string	Original filename, max 500 chars.
`content_type`	string	MIME type, max 255 chars.
`size_bytes`	integer	Declared file size in bytes.

Request

cURL

curl -X POST https://api.cimplify.io/api/v1/uploads/init \
  -H "X-Public-Key: pk_test_your_publishable_key" \
  -H "Idempotency-Key: 5b1f9d80-2c70-4f2c-bf61-a0e6fa6b02a1" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "receipt.pdf",
    "content_type": "application/pdf",
    "size_bytes": 184321
  }'

Response

{
  "data": {
    "upload_id": "up_01H…",
    "upload_url": "https://uploads.cimplify.io/p/01H…?signature=…",
    "expires_in_secs": 600
  }
}

PUT the file bytes to upload_url with the same Content-Type declared above. The URL is single-use and expires.

Step 2: PUT the bytes

cURL

curl -X PUT "https://uploads.cimplify.io/p/01H…?signature=…" \
  -H "Content-Type: application/pdf" \
  --data-binary @receipt.pdf

POST /api/v1/uploads/confirm

Finalise the upload. The server checks that the bytes landed and returns the canonical record.

Request

cURL

curl -X POST https://api.cimplify.io/api/v1/uploads/confirm \
  -H "X-Public-Key: pk_test_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{"upload_id": "up_01H…"}'

Response

{
  "data": {
    "id": "up_01H…",
    "url": "https://cdn.cimplify.io/up/01H…/receipt.pdf",
    "filename": "receipt.pdf",
    "content_type": "application/pdf",
    "size_bytes": 184321
  }
}

Errors

400 VALIDATION_ERROR: filename or content_type exceeds limits, size_bytes negative.
400 BAD_REQUEST: confirm called before the bytes arrived.
404 NOT_FOUND: upload_id doesn’t exist or has expired.
Support Reference uploaded file URLs in chat messages.

Uploads

On this page