---
search:
  tags:
    - Documents
    - POST
seo:
  description: >-
    Reserves a document on a Brand, and is the first of the three steps of…
    Reference for the POST /context/brands/{slug}/documents endpoint in the
    AdCrunch API.
sidebar:
  label: Start a document upload
  badge: POST
title: Start a document upload
type: openapi-operation
---
Reserves a document on a Brand, and is the first of the three steps of an upload. The answer gives a URL with a short life. `PUT` the bytes to that URL with their `Content-Type`, then call finalize. The bytes do not go through this API. AdCrunch accepts PDF, GIF, JPEG, PNG and WebP. It refuses SVG, because a stored document is served from an adcrunch.dev host and an SVG carries script.

`POST /context/brands/{slug}/documents`

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

- `content_type` (string, required) — The type you are about to upload. Re-checked against the stored object at finalize — this is only a declaration.
- `filename` (string, required)

Request body example:

```json
{
  "content_type": "application/pdf",
  "filename": "acme-brand-guidelines.pdf"
}
```

**Responses**

- `201` — A reserved destination, valid for \`expiresInSeconds\`. PUT the bytes to \`uploadUrl\`, then call finalize with \`documentId\`. The URL itself gives write access: anybody holding it can write that one object until it lapses. The Document does not exist for any reader until finalize succeeds.
- `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 \`brand:write\`. \`error\` is \`forbidden\`.
- `404` — No Brand with that slug. \`error\` is \`not\_found\`.
- `415` — That media type is not accepted. \`error\` is \`unsupported\_type\`, and \`allowed\` names every type that is. This is the declared type; the stored object is checked again at finalize.

Response example, 201:

```json
{
  "documentId": "doc_5e2b41",
  "expiresInSeconds": 900,
  "uploadUrl": "https://a1b2c3d4e5f6.r2.cloudflarestorage.com/documents/org_3a7f10/doc_5e2b41?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Signature=8f1c…"
}
```
