Upload binary file

Method	Path
POST	/binary/single

Authentication · Access policies · Files and documents

Deprecated

This route is deprecated. Use POST /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, 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, 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 or GET /document/public/:token. 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, Download document, Update document metadata and 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

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:

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.

{
  "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.