Download document

Method	Path
GET	/document/:id

Authentication · Access policies · Files and documents

Downloads the file of a document. The route answers with a redirect to a short-lived signed URL. Use it to show or download a file you have access to.

Auth: Bearer token. The document is read with your token, so the access policy must allow DocumentReference:read. 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.

Query parameters

Name	Type	Required	Description
width	integer	No	Width of the resized image, in pixels. Positive, at most 16384. Send it together with height.
height	integer	No	Height of the resized image, in pixels. Positive, at most 16384. Send it together with width.
fit	"cover" | "contain" | "fill" | "inside" | "outside"	No	How the image fits the width by height box. Default cover. Checked even when you do not resize.

Behaviour

• The answer is 307 Temporary Redirect. The Location header holds the file URL. Follow the redirect to get the file, for example with curl -L.
• The signed URL is valid for one hour. Images (image/jpeg, image/jpg, image/png, image/gif, image/webp) are served inline. Every other type is served as an attachment, named with the document's fileName.
• width and height must be sent together or not at all. Both must be positive integers up to 16384. They apply to documents whose contentType is an image type, and are ignored for every other type.
• A resized JPEG, PNG or WebP image keeps its format. An image is never enlarged: a box larger than the image returns the image at its own size. The resized copy is stored, so a later request for the same size and fit is fast.
• The redirect goes to the document's own file URL, with no resizing, for a GIF, for an image larger than 40 MB, and when the resize fails.
• When you ask for a resized image and the stored file is missing, the route answers 404. Without width and height, the route does not check that the file exists. If the file was never uploaded, or was removed by Replace document file, the redirect still happens and the storage URL fails.
• The route uses the first attachment of the document. A document with no file URL answers 404.
• A browser <img> tag cannot send a bearer token. To embed an image in a page, make the document public and use Download public document, or fetch the file in your own code with your token.

Example

curl -L 'https://api.sandbox.ovok.com/document/3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21?width=200&height=200&fit=cover' \
  -H "Authorization: Bearer ${OVOK_TOKEN}" \
  -o cat.png

Successful response

307 — Redirect to a signed download URL. There is no JSON body.

HTTP/1.1 307 Temporary Redirect
Location: https://storage.example.com/ovok-files/5d2a9c64-7e1b-4830-b6f5-9a3c1e8d7b02/8c5e7a21-4b9d-4f36-a1c8-0d2e6b9f3a54?signature=3b9c1e7a...

Header	Description
Location	The signed URL of the file. Valid for one hour. Not a stable link: ask for a new one each time.

Errors

Status	Meaning
400	id is not a UUID, width and height are not sent together or are not positive integers up to 16384, fit is not one of the listed values, or the file URL is not an http or https URL.
401	Bearer token is missing, invalid or revoked.
403	Your access policy does not allow reading the DocumentReference.
404	No document with this id is visible to you, the document has no file URL, or a resized image is requested and the stored file is missing.
410	The document was deleted.
429	You exceeded the rate limit for your user type.