---
title: document_create_upload
description: Reserve a file against a brand and get a short-lived URL to upload the bytes to.
---

Reserves a **document** against a brand and returns a short-lived URL to `PUT` the bytes to. **The bytes never pass through AdCrunch** — your client uploads them directly to storage, which is why a large file is possible at all.

Three steps, always in this order:

1. `document_create_upload` — reserve, and get an `uploadUrl`.
2. `PUT` the file to that URL yourself.
3. [`document_finalize`](/mcp/tools/document-finalize) — tell us it landed.

## Input

| Field          | Type     | Required | Description                          |
| -------------- | -------- | -------- | ------------------------------------ |
| `brand_name`   | `string` | yes      | The brand slug this file belongs to. |
| `filename`     | `string` | yes      | The original filename, for display.  |
| `content_type` | `string` | yes      | What you're about to upload.         |

Accepted types are PDFs and images: `application/pdf`, `image/png`, `image/jpeg`, `image/gif`, `image/webp`. SVG is **not** accepted — it can carry script, and these files are served from an adcrunch.dev host.

What you declare here is only a declaration. The real check happens at [`document_finalize`](/mcp/tools/document-finalize), against the file that actually arrived.

## Output

`{ documentId, uploadUrl, expiresInSeconds }`.

## Example

```ts
const { documentId, uploadUrl } = document_create_upload({
  brand_name: 'acme-running',
  filename: 'brand-guidelines.pdf',
  content_type: 'application/pdf',
});
// then: PUT the file to uploadUrl, then document_finalize({ document_id: documentId })
```

:::warning[The URL expires]

The upload URL is valid for 15 minutes and grants exactly one write. If it expires before you finish, reserve again — the abandoned reservation is cleaned up automatically.

:::

Requires the `brand:write` scope.