# Create document upload credentials

Canonical page: https://docs.ovok.com/api/document/create-document-upload-credentials

`POST /document`

Creates a document and returns a signed form that you use to upload its file straight to storage. Use it for every new file: Ovok never receives the file bytes itself.

**Auth:** bearer token. The document is created with your token, so you need create access to Binary and DocumentReference.
**Scope:** the caller's project (from the token).

## Behaviour

- Creates an empty Binary and a DocumentReference with `status: current`, the given `fileName` as title and `contentType`, and you as `author`.
- `contentType` must be one of the allowed types: `image/jpeg`, `image/jpg`, `image/png`, `image/gif`, `image/webp`, `application/pdf`, `application/json`, `application/xml`, `text/plain`, `text/csv`, `video/mp4`, `video/webm`, `audio/mpeg`, `audio/wav`.
- With `isPublic: "true"`, the document also gets a public token (`publicToken`) that anyone can use with `GET /document/public/{token}`.
- `uploadOptions` holds a URL and form fields. Send a `multipart/form-data` POST to `uploadOptions.url` with every entry of `uploadOptions.fields` as a form field, then the file as the field `file`. The form expires 10 minutes after it is issued and accepts files up to 5 GB.
- The document exists as soon as this call returns, even if you never upload the file.
- This route is rate limited: 20 requests a minute for admins, 10 a minute for other users.

## Example

```bash
curl -X POST 'https://api.sandbox.ovok.com/document' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \
  -H 'Content-Type: application/json' \
  -d '{ "fileName": "cat.png", "contentType": "image/png", "isPublic": "false" }'
```

```json
{
  "id": "87ea5dfc-8b8e-384d-8489-79496e706390",
  "meta": { "lastUpdated": "2026-01-01T12:00:00.000Z" },
  "author": { "reference": "Practitioner/...", "display": "Max Mustermann" },
  "fileName": "cat.png",
  "contentType": "image/png",
  "uploadOptions": {
    "url": "https://...",
    "fields": { "key": "...", "Policy": "...", "X-Amz-Signature": "...", ... }
  }
}
```

Then upload the file with the returned form:

```bash
curl -X POST '<uploadOptions.url>' \
  -F 'key=...' \
  -F 'Policy=...' \
  -F 'X-Amz-Signature=...' \
  -F 'file=@cat.png'
```