---
title: Download binary file
sidebar_label: Download binary file (deprecated)
sidebar_position: 9
description: "Deprecated. Download a file by redirect to a short-lived signed URL, with a bearer token or a public token. Use GET /document/:id or GET /document/public/:token instead."
---

# Download binary file

| Method | Path |
| --- | --- |
| `GET` | `/binary/:documentReferenceId` |

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

:::warning[Deprecated]
This route is deprecated. Use [`GET /document/:id`](/files-and-documents/get-document) to download as a signed-in user, and [`GET /document/public/:token`](/files-and-documents/get-public-document) 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](/files-and-documents/upload-binary) 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:

```bash
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:

```bash
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
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. |