---
title: Replace document file
sidebar_label: Replace document file
sidebar_position: 2
description: "Replace the file of an existing document: update its metadata and get a new signed upload form."
---

# Replace document file

| Method | Path |
| --- | --- |
| `POST` | `/document/:id` |

[Authentication](/authentication) · [Access policies](/access-policies) · [Files and documents](/files-and-documents)

Replaces the file of an existing document. The route updates the document's metadata and returns a new signed upload form, as [`POST /document`](/files-and-documents/create-document) does. The document keeps its id, so existing references to it stay valid.

**Auth:** Bearer token. The document is read and updated with your token, so the access policy must allow `DocumentReference:read` and `DocumentReference:update`.
**Scope:** The document must be visible to you in your project (from the token).

## Request

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string (uuid)` | Yes | Document id. |

### Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `fileName` | `string` | Yes | New name of the file. Stored as the document title and used as the download name. At least 1 character. |
| `contentType` | `string` | Yes | MIME type of the new file. Must be one of the types allowed by [Create document](/files-and-documents/create-document), matched exactly. |
| `isPublic` | `boolean` | No | `true` makes the document public, `false` makes it private. A JSON boolean here, unlike the string on `POST /document`. Leave it out to keep the current state. |

## Behaviour

- `fileName` and `contentType` are set on the document first, then the file is deleted. If you lack update access, the call answers `403` and the file is not deleted.
- The current file is deleted when the form is issued, even if you never upload a new one. Until you upload, the document has no file: a download fails at file storage, and a resized download answers `404`.
- Upload with `uploadOptions` as described for [Create document](/files-and-documents/create-document). The form is valid for 10 minutes and accepts files up to 5 GB. If it expires, call this route again for a new form.
- `isPublic: true` on a private document gives it a public token. `isPublic: false` on a public document removes the token, so its public links stop working. Setting the state the document already has changes nothing, and the token stays.
- The document id and, unless you change `isPublic`, the public token stay the same.
- Resized copies of an image that were generated earlier are not cleared by a replace. A resized download for a size you used before can return the earlier image.
- The answer is `201`, as for `POST /document`, even though no new document is created.

## Example

```bash
curl -X POST 'https://api.sandbox.ovok.com/document/3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21' \
  -H "Authorization: Bearer ${OVOK_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "fileName": "new-cat.png",
    "contentType": "image/png"
  }'
```

Then upload the new file with the returned form, as in [Create document](/files-and-documents/create-document#example).

## Successful response

`201` — The document with a new upload URL and form fields.

```json
{
  "id": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21",
  "meta": { "lastUpdated": "2026-10-09T09:20:05.112Z" },
  "author": {
    "reference": "Practitioner/8c5e7a21-4b9d-4f36-a1c8-0d2e6b9f3a54",
    "display": "Alex Lee"
  },
  "fileName": "new-cat.png",
  "contentType": "image/png",
  "uploadOptions": {
    "url": "https://storage.example.com/ovok-files",
    "fields": {
      "key": "binary/5d2a9c64-7e1b-4830-b6f5-9a3c1e8d7b02/8c5e7a21-4b9d-4f36-a1c8-0d2e6b9f3a54",
      "<next field name>": "<its value>",
      "<last field name>": "<its value>"
    }
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string (uuid)` | Document id. Unchanged. |
| `meta.lastUpdated` | `string` | When the document last changed. ISO 8601. |
| `author` | `object` | The first author of the document. Left out when it has none. The author is not changed by a replace. |
| `author.reference` | `string` | Profile reference, for example `Practitioner/<id>`. |
| `author.display` | `string` | Display name of the author. |
| `fileName` | `string` | The new file name. |
| `contentType` | `string` | The new content type. |
| `publicToken` | `string` | Public token. Present only while the document is public. |
| `uploadOptions.url` | `string` | URL to send the upload form to. |
| `uploadOptions.fields` | `object` | Form fields to send with the file, as for [Create document](/files-and-documents/create-document#successful-response). Send every name and value unchanged. |

## Errors

| Status | Meaning |
| --- | --- |
| `400` | `id` is not a UUID, or the body fails validation: `fileName` is missing or empty, `contentType` is missing or not an allowed type, or `isPublic` is not a boolean. `message` lists each problem as `path: message`. |
| `401` | Bearer token is missing, invalid or revoked. |
| `403` | Your access policy does not allow reading or updating the `DocumentReference`. |
| `404` | No document with this id is visible to you, or the document has no file URL. |
| `410` | The document was deleted. |
| `429` | You exceeded the rate limit for your user type. |