Files API reference

Use the Files API to download a file stored in a record and to create the short-lived token required by protected file fields. Uploading, replacing, and deleting files is part of the Records API; this page covers the two /api/files operations.

Before you call the API

Use a base URL such as http://127.0.0.1:8090. Replace COLLECTION, RECORD_ID, and FILENAME with values from your own record. Send Authorization: <record-token> when creating a file token. A protected download is permitted only when its collection View API rule permits the request.

POST /api/files/token

Creates a short-lived file token for an authenticated record or superuser. The request requires record authorization; the endpoint does not accept an anonymous request.

curl --request POST \
  --url http://127.0.0.1:8090/api/files/token

{ "token": "FILE_TOKEN" }

Example request:

curl -X POST 'http://127.0.0.1:8090/api/files/token' \
  -H 'Authorization: RECORD_TOKEN'

Use the returned token as the token query parameter on a protected file URL. A successful response contains a non-empty token string.

GET /api/files/{collection}/{recordId}/{filename}

Serves the original file or an image thumbnail. The collection can be its name or ID. If the file field is protected, add a valid file token and satisfy the collection View API rule.

curl --request GET \
  --url http://127.0.0.1:8090/api/files///

The response body is the file bytes.

curl -L 'http://127.0.0.1:8090/api/files/documents/RECORD_ID/photo.png?thumb=300x200&download=1' \
  -o photo.png

WxH crops from the center, WxHt from the top, WxHb from the bottom, and WxHf fits without cropping. 0xH preserves aspect ratio while setting height; Wx0 does the same for width. Unsupported or unavailable thumbnail requests fall back to the original file. A successful response has the file content, not JSON.

Errors and security behavior

The endpoint returns not-found behavior when the collection, record, filename, or protected-file authorization check fails. This deliberately avoids exposing whether a protected resource exists. For protected files, the check uses the file token as the request auth context and then evaluates the collection View API rule.

For related upload and deletion operations, see files and storage and the Records API reference.