Download public document

Method	Path
GET	/document/public/:token

Files and documents · Create document · Update document metadata

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 who has the URL can get the file. Scope: The one document the token names. No AccessPolicy applies, because the caller is not signed in.

Request

Path parameters

Name	Type	Required	Description
token	string	Yes	The document's publicToken.

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.

Behaviour

• The token is the publicToken of a document. A document gets one when it is created with isPublic set to "true", or when it is updated with isPublic set to true. The token is returned by those calls, by Replace document file with isPublic: true, and by Search documents.
• The answer is 307 Temporary Redirect to a signed file URL, valid for one hour, with the same resizing options and rules as Download document.
• The token does not expire. It stops working when the document is made private again or deleted. Making a document private and then public again issues a new token, and the old one stays invalid.
• Treat the URL like a password. Anyone who has it can download the file, and anyone who can read the document can see its publicToken.
• 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.
• The route does not check that the file exists unless you ask for a resized image.
• Without a bearer token, calls are rate limited per client IP address.

Example

curl -L 'https://api.sandbox.ovok.com/document/public/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZWZlcmVuY2UiOiJEb2N1bWVudFJlZmVyZW5jZS8zZjFjMmI3ZS04ZDRhLTRjMWUtOWIyZi02YTdkNWU0YzNiMjEiLCJpYXQiOjE3OTE1MDAwMDB9.c2lnbmF0dXJl?width=200&height=200' \
  -o cat.png

Successful response

307 — Redirect to a signed download URL. There is no JSON body.

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: request the public URL again for a fresh one.

Errors

Status	Meaning
400	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	The token is not a valid public token, the document does not exist, or it no longer carries this token.
404	The document has no file URL, or a resized image is requested and the stored file is missing.
429	You exceeded the rate limit.