Download a public document
- Sandbox: available
- Staging: available
- Production: unknown
Downloads the file of a public document, without a bearer token. Use it to embed a file in a web page or an email, for example in an <img> tag.
Auth: none. The public token in the path is the credential: anyone with the URL can get the file.
Behaviour
- The token is the document's
publicToken. A document gets one when it is created or updated withisPublicset to true. - The response is
307 Temporary Redirectto a signed file URL, as inGET /document/{id}, including the same resizing options (width,height,fit). - A token stops working when the document is made private again, or when its public token is replaced.
Example
curl -L 'https://api.sandbox.ovok.com/document/public/example.jwt.eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' -o file.pngtoken*stringThe public token of the DocumentReference resource
width?stringThe width of the binary resource if the resource is an image.
height?stringThe height of the binary resource if the resource is an image.
fit?stringThe fit of the image. See https://sharp.pixelplumbing.com/api-resize#fit for more information.
"cover""cover""contain""fill""inside""outside"ETag?stringThe ETag of the file for GET requests. If provided, the server will check the value of the ETag against the value of the ETag in the request headers. If the values match, the server will return a 304 Not Modified response. If the values do not match, the server will return a 200 OK response and the file content, if the file exists.
Redirect to a signed download URL.
curl -X GET 'https://api.sandbox.ovok.com/document/public/string'Create document upload credentials POST
Creates a document and returns a signed form that you use to upload its file straight to storage. Use it for every new file: Ovok never receives the file bytes itself. **Auth:** bearer token. The document is created with your token, so you need create access to Binary and DocumentReference. **Scope:** the caller's project (from the token). ## Behaviour - Creates an empty Binary and a DocumentReference with `status: current`, the given `fileName` as title and `contentType`, and you as `author`. - `contentType` must be one of the allowed types: `image/jpeg`, `image/jpg`, `image/png`, `image/gif`, `image/webp`, `application/pdf`, `application/json`, `application/xml`, `text/plain`, `text/csv`, `video/mp4`, `video/webm`, `audio/mpeg`, `audio/wav`. - With `isPublic: "true"`, the document also gets a public token (`publicToken`) that anyone can use with `GET /document/public/{token}`. - `uploadOptions` holds a URL and form fields. Send a `multipart/form-data` POST to `uploadOptions.url` with every entry of `uploadOptions.fields` as a form field, then the file as the field `file`. The form expires 10 minutes after it is issued and accepts files up to 5 GB. - The document exists as soon as this call returns, even if you never upload the file. - This route is rate limited: 20 requests a minute for admins, 10 a minute for other users. ## Example ```bash curl -X POST 'https://api.sandbox.ovok.com/document' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -H 'Content-Type: application/json' \ -d '{ "fileName": "cat.png", "contentType": "image/png", "isPublic": "false" }' ``` ```json { "id": "87ea5dfc-8b8e-384d-8489-79496e706390", "meta": { "lastUpdated": "2026-01-01T12:00:00.000Z" }, "author": { "reference": "Practitioner/...", "display": "Max Mustermann" }, "fileName": "cat.png", "contentType": "image/png", "uploadOptions": { "url": "https://...", "fields": { "key": "...", "Policy": "...", "X-Amz-Signature": "...", ... } } } ``` Then upload the file with the returned form: ```bash curl -X POST '<uploadOptions.url>' \ -F 'key=...' \ -F 'Policy=...' \ -F 'X-Amz-Signature=...' \ -F 'file=@cat.png' ```
Download a document GET
Downloads the file of a document by answering 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 DocumentReference is read with your token, so you need read access to it. ## Behaviour - The response is `307 Temporary Redirect`. The `Location` header holds the file URL. Follow the redirect to get the file. - For files Ovok stored, 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 with the document's file name. - Pass `width` and `height` together to get a resized copy of an image. Both must be positive integers up to 16384. `fit` sets how the image fits the box (`cover` by default; also `contain`, `fill`, `inside`, `outside`). The resized copy is cached, so later requests for the same size are fast. Files that are not resizable images, and images larger than 40 MB, are returned unchanged. - If the image cannot be resized, the original file is returned. ## Example ```bash curl -L 'https://api.sandbox.ovok.com/document/c3499c27-2973-0a7f-807e-fb8676a92dcb?width=200&height=200&fit=cover' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -o cat.png ```