---
title: Upload binary file
sidebar_label: Upload binary file (deprecated)
sidebar_position: 8
description: "Deprecated. Upload one file in a multipart request and get its document record back. Use POST /document instead."
---

# Upload binary file

| Method | Path |
| --- | --- |
| `POST` | `/binary/single` |

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

:::warning[Deprecated]
This route is deprecated. Use [`POST /document`](/files-and-documents/create-document) instead, then send the file to the signed upload form it returns. That flow keeps the file out of the API request and accepts files up to 5 GB, where this route stops below 200 MiB. This route still works.
:::

Uploads one file and creates a document for it in a single request. The file travels through Ovok, which checks it and stores it. Use it only to keep an existing integration running.

**Auth:** Bearer token. Any signed-in user can call it, if the access policy allows `Binary:create` and `DocumentReference:create`.
**Scope:** The document is created in the caller's project (from the token). Unlike [Create document](/files-and-documents/create-document), it records no author.

## Request

Send `multipart/form-data`. The route is not versioned: the path starts with `/binary`, with no `/v1`.

### Form fields

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `file` | `file` | Yes | The file to store. It must be smaller than 200 MiB (209,715,200 bytes). The content type of the part must be one of the [allowed file types](/files-and-documents#allowed-file-types), matched exactly. The file name of the part becomes the document title. |

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `public` | `string` | No | Send `true` to make the document public and get a public token. Any non-empty value, including `false`, has this effect. Leave the parameter out, or send it empty, for a private document. |

## Behaviour

- Send one file, in a part named `file`. A file in a part with any other name, or a second file, is rejected with `400`. Other form fields are ignored.
- The route checks the size of the file, then its content type, then its bytes. The file is checked against known malware signatures, and a match is rejected.
- Creates a `Binary` for the file, then a `DocumentReference` with status `current` that points at it, with the file name as the attachment title. The two are created one after the other, not in one transaction. If the second fails, the `Binary` remains.
- With `public` set, a public token is added to the document and returned as `meta.publicResourceToken`. Anyone who has it can download the file with [`GET /binary/:documentReferenceId`](/files-and-documents/download-binary) or [`GET /document/public/:token`](/files-and-documents/get-public-document). Upload still needs a bearer token: only the download is open.
- The document is the same kind of record the document routes manage, so you can list, download, update and delete it with [Search documents](/files-and-documents/search-documents), [Download document](/files-and-documents/get-document), [Update document metadata](/files-and-documents/update-document) and [Delete document](/files-and-documents/delete-document).
- Any failure while storing the file or creating the document answers `400`, not `403`. That includes an access policy that does not allow `Binary:create` or `DocumentReference:create`.
- The route has no limit of its own. 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. A request refused before it reaches the route, for example a `401` for a missing token, does not carry them.

## Example

```bash
curl -X POST 'https://api.sandbox.ovok.com/binary/single' \
  -H "Authorization: Bearer ${OVOK_TOKEN}" \
  -F 'file=@cat.png;type=image/png'
```

To get a public token as well:

```bash
curl -X POST 'https://api.sandbox.ovok.com/binary/single?public=true' \
  -H "Authorization: Bearer ${OVOK_TOKEN}" \
  -F 'file=@cat.png;type=image/png'
```

## Successful response

`201` — The new document record.

```json
{
  "resourceType": "DocumentReference",
  "id": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21",
  "status": "current",
  "content": [
    {
      "contentType": "image/png",
      "url": "https://storage.example.com/5d2a9c64-7e1b-4830-b6f5-9a3c1e8d7b02/8c5e7a21-4b9d-4f36-a1c8-0d2e6b9f3a54",
      "title": "cat.png"
    }
  ],
  "meta": {
    "versionId": "9a7d5e4c-3b21-4c1e-8d4a-3f1c2b7e6a05"
  }
}
```

The body is a flat record, not the FHIR JSON of a `DocumentReference`: each `content` entry holds `contentType`, `url` and `title` directly, with no `attachment` level. Fields the route does not set, such as `author`, `subject` and `type`, are left out.

| Field | Type | Description |
| --- | --- | --- |
| `resourceType` | `string` | Always `DocumentReference`. |
| `id` | `string (uuid)` | Document id. Use it in the download routes and the document routes. |
| `status` | `string` | Always `current`. |
| `content` | `array` | One entry, for the file. |
| `content[].contentType` | `string` | The content type of the part you sent. |
| `content[].url` | `string` | Storage address of the file. Do not use it to download the file: use a download route, which answers with a fresh signed link. |
| `content[].title` | `string` | The file name of the part you sent. |
| `meta.versionId` | `string` | Version of the document. |
| `meta.publicResourceToken` | `string` | Public token. Present only when `public` was sent. |

## Errors

| Status | Meaning |
| --- | --- |
| `400` | No file was sent, the file is in a part not named `file`, more than one file was sent, the file is 200 MiB or larger, its content type is not an allowed type, or it matches a malware signature. Also any failure while storing the file or creating the document, including an access policy that does not allow it. |
| `401` | Bearer token is missing, invalid or revoked. |
| `429` | You exceeded the rate limit for your user type. |