---
title: "Start a reference upload (Idempotency-Key required): returns a signed PUT URL and the headers to send"
method: POST
path: "/v1/uploads"
tags: ["platform-api"]
---

# Start a reference upload (Idempotency-Key required): returns a signed PUT URL and the headers to send

`POST /v1/uploads`

## Request

- Base URL: `https://api.cuddler.ai`
- URL: `https://api.cuddler.ai/v1/uploads`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string, required: Required. One key per logical request (e.g. `ep03-shot042-take1`), never reusable: the same key and body answer with the original object and `Idempotent-Replayed: true`; the same key with a different body is 409.

## Request body

- object
  - `kind` 'image' | 'video' | 'audio', required
  - `content_type` string, required
  - `bytes` integer, required
  - `filename` string

## Response `200`

Replay: this Idempotency-Key already started this upload

- object
  - `object` 'upload', required
  - `id` string, required
  - `kind` 'image' | 'video' | 'audio', required
  - `status` 'pending' | 'ready' | 'rejected' | 'expired', required
  - `content_type` string, required
  - `bytes` integer, required
  - `upload_url` string, uri
  - `upload_headers` object
  - `expires_at` string, required
  - `rejection_reason` string
  - `created_at` string, required

## Other responses

- `201`: PUT the bytes to upload_url with exactly upload_headers before expires_at, then complete
- `400`: invalid_request — unsupported content type, too large, or a missing Idempotency-Key
- `401`: unauthorized — no key, or an unknown or revoked one (WWW-Authenticate: Bearer)
- `403`: organization_suspended — the organization is not active; forbidden — a test key on a live-only route
- `404`: not_found — the Platform API is switched off, or the object does not exist
- `409`: idempotency_conflict — the key was already used with a different body
- `429`: rate_limited — this key's requests per minute, or the organization's pending / ready upload limit (details.reason upload_limit_reached; Retry-After)
- `500`: internal_error — quote request_id when contacting support
- `503`: unavailable — uploads are temporarily unavailable (Retry-After)

---

[API](https://skmtc.dev/cuddler/apis/cuddler-platform-api.md) · [All operations](https://skmtc.dev/cuddler/apis/cuddler-platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cuddler/apis/cuddler-platform-api/revisions/f03943ceadff?raw)