# Create an upload

`POST https://api.cademi.com.br/api/v3/uploads`

Operation ID: `uploads.create` · API v3

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.

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

Required permissions: `files.write`.

## Request body

Content type: `application/json`, required.

| Field | Type | Required | Description |
|---|---|---|---|
| `content_type` | string or null | no |  |
| `filename` | string | yes |  |
| `purpose` | string | yes |  |
| `sha256` | string or null | no |  |
| `size_bytes` | integer | yes |  |

## Responses

### 201

Returns the newly created upload session.

Body: `data`: Upload.

Fields of Upload:

| Field | Type | Required | Description |
|---|---|---|---|
| `expires_at` | string (date-time) | yes |  |
| `failure_reason` | string or null | yes |  |
| `file` | File or null | yes |  |
| `filename` | string | yes |  |
| `id` | string | yes | Public ID, with the upl_ prefix. |
| `object` | string, one of `upload` | yes |  |
| `part_size` | integer or null | yes |  |
| `parts_total` | integer or null | yes |  |
| `purpose` | string | yes |  |
| `size_bytes` | integer | yes |  |
| `status` | string, one of `open`, `completed`, `cancelled`, `expired`, `failed` | yes |  |

### 401

The credential is missing, malformed, expired, or revoked.

Body: Error.

### 403

The current credentials do not have the permission required by this operation.

Body: Error.

### 422

The request body or query parameters failed validation.

Body: ValidationFailed.

### 503

The storage service is temporarily unavailable. Retry the request with backoff.

Body: Error.

Full schema: https://cademi.dev/openapi/v3.json