Download binary file

Method	Path
GET	/binary/:documentReferenceId

Authentication · Access policies · Files and documents

Deprecated

This route is deprecated. Use GET /document/:id to download as a signed-in user, and GET /document/public/:token to download a public document without a token. They accept the same width, height and fit parameters. This route still works.

Downloads the file of a document. The route answers with a redirect to a short-lived signed URL. It serves two kinds of caller: a signed-in user, and anyone who holds the document's public token.

Auth: A bearer token, or a publicResourceToken query parameter. With a bearer token the document is read with your token, so the access policy must allow DocumentReference:read. With publicResourceToken no bearer token is needed: the public token is the credential, and anyone who has it can get the file. A request with neither answers 401. Scope: With a bearer token, the document must be visible to you in your project (from the token). With a public token, the one document the token names. No AccessPolicy applies.

Request

The route is not versioned: the path starts with /binary, with no /v1.

Path parameters

Name	Type	Required	Description
documentReferenceId	string (uuid)	Yes	Document id. With publicResourceToken the id is not compared with the token: the token alone picks the file, but the path still needs a value.

Query parameters

Name	Type	Required	Description
publicResourceToken	string	No	The public token of the document. Send it to download a public document without a bearer token. Returned as meta.publicResourceToken by Upload binary file with public, and as publicToken by the document routes.
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 route is a GET. Query parameters other than the four listed, such as a type parameter shown in some older examples, are ignored.
• 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 file name of the document. You cannot choose between the two.
• With publicResourceToken, the document must carry that token. It stops working when the document is made private again or deleted. A token that is not valid, that belongs to a document that no longer exists, or that the document no longer carries answers 401, not 404.
• width and height must be sent together or not at all. Both must be positive integers up to 16384. They apply to documents whose content type 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.
• The route uses the first attachment of the document. A document with no file URL answers 404.
• Without a bearer token, the route allows 10,000 calls a minute per client IP address. With one, the limit for your user type applies, per user and client IP address, in a 30-second window: 1,000 calls for admins and client applications, 200 for practitioners, 100 for patients and related persons. Super admins are not limited.
• Every response the route produces carries the headers Deprecated: 2024-10-18T00:00:00.000Z, Sunset: 2025-03-01T00:00:00.000Z and Link: <https://docs.ovok.com>; rel="deprecation"; type="text/html". The Sunset date has passed and the route still answers.

Example

As a signed-in user:

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

With a public token, and no bearer token:

curl -L 'https://api.sandbox.ovok.com/binary/3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21?publicResourceToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZWZlcmVuY2UiOiJEb2N1bWVudFJlZmVyZW5jZS8zZjFjMmI3ZS04ZDRhLTRjMWUtOWIyZi02YTdkNWU0YzNiMjEiLCJpYXQiOjE3OTE1MDAwMDB9.c2lnbmF0dXJl' \
  -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/5d2a9c64-7e1b-4830-b6f5-9a3c1e8d7b02/8c5e7a21-4b9d-4f36-a1c8-0d2e6b9f3a54?signature=3b9c1e7a...
Deprecated: 2024-10-18T00:00:00.000Z
Sunset: 2025-03-01T00:00:00.000Z

Header	Description
Location	The signed URL of the file. Valid for one hour. Not a stable link: ask for a new one each time.
Deprecated	The date the route was deprecated.
Sunset	The sunset date announced for the route. It has passed and the route still answers.
Link	Points to this documentation, with rel="deprecation".

Errors

Unlike the document routes, a bad query parameter answers 422, not 400. In that case message is a list of objects, each with a path and a message.

Status	Meaning
400	The file URL is not an http or https URL.
401	No bearer token and no publicResourceToken was sent, the bearer token is not accepted, or the publicResourceToken is not valid, belongs to no document, or the document no longer carries it.
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.
422	width and height are not sent together or are not positive integers up to 16384, or fit is not one of the listed values.
429	You exceeded the rate limit.