---
search:
  tags:
    - Assets
    - POST
seo:
  description: >-
    Reserves an Asset and returns a presigned PUT URL to upload the bytes to.
    The… Reference for the POST /library/assets/uploads endpoint in the AdCrunch
    API.
sidebar:
  label: Reserve an Asset and mint an upload URL
  badge: POST
title: Reserve an Asset and mint an upload URL
type: openapi-operation
---
Reserves an Asset and returns a presigned `PUT` URL to upload the bytes to. The URL is valid for one hour, and `expiresAt` says when it stops being accepted.

The client uploads **directly** to storage — the bytes never pass through this worker, because Cloudflare rejects over-limit request bodies at the proxy before any code runs. Read `GET /library/assets/{id}` once the upload completes.

Send the `PUT` with the header `If-None-Match: *`. A `PUT` without it answers `403`. The URL can create the object once, and never replace it: a second `PUT` answers `412`. A `412` means that the bytes are already stored, so continue and read the Asset. To use a different file, reserve a new Asset.

The URL is the credential: anyone holding it can create that one object until it expires. Nothing is known about the file until a read inspects what actually landed, so size and type cannot be enforced here.

The reserved Asset stays `pending` until a read finds the object. That read completes the Asset and answers it `ready` or `failed`. A read before the `PUT` answers `pending`. A list does not answer a `pending` Asset. The daily sweep finalizes a reservation that nobody read when its object exists, and deletes a reservation with no object, one day after the reservation.

`POST /library/assets/uploads`

**Request body** (`application/json`, required)

- `filename` (string, required) — The name of the file you are about to send. Shown until somebody renames the Asset, and never used to look one up.

Request body example:

```json
{
  "filename": "spring-sale.mp4"
}
```

**Responses**

- `200` — The reservation. Send the bytes to \`uploadUrl\`, then read \`assetId\`.
- `400` — The request does not match the schema of this operation: a field is missing or has the wrong type, or the body is not valid JSON. \`error\` is \`invalid\_request\`, and \`issues\` names each field. Nothing was changed.
- `401` — No API key, or one that does not resolve. See the security scheme. \`error\` is \`unauthorized\`.
- `402` — The organization has no active subscription. An owner subscribes at \`paywallUrl\`. \`error\` is \`organization\_unentitled\`.
- `403` — The caller does not hold \`library:write\`. \`error\` is \`forbidden\`.
- `500` — AdCrunch could not write the reservation. \`error\` is \`reservation\_failed\`. Nothing was reserved, so send the request again.

Response example, 200:

```json
{
  "assetId": "ast_7c1e9a",
  "expiresAt": 1790003600000,
  "uploadUrl": "https://b7f3c81a29d64e0fa5c3d1e8b0947265.r2.cloudflarestorage.com/assets/org_3a7f10/ast_7c1e9a?X-Amz-Expires=3600&X-Amz-Date=20260921T141320Z&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=4f8e2a6c1b9d7e3f5a0c2b4d6e8f1a3c%2F20260921%2Fauto%2Fs3%2Faws4_request&X-Amz-SignedHeaders=host&X-Amz-Signature=7d1c4a9f2e8b0536c1a7e94d2b6f038a5c1e9b7d3f6a2c805d4e1b93a7f0c625"
}
```
