---
title: Download document
sidebar_label: Download document
sidebar_position: 4
description: "Download a document's file by redirect to a short-lived signed URL, with optional image resizing."
---

# Download document

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

[Authentication](/authentication) · [Access policies](/access-policies) · [Files and documents](/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](/files-and-documents/replace-document), 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](/files-and-documents/get-public-document), or fetch the file in your own code with your token.

## Example

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