Replace document file

Method	Path
POST	/document/:id

Authentication · Access policies · 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 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, 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. 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

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.

Successful response

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

{
  "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. 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.