Files API reference
Reference file downloads, image modifiers, protected-file tokens, and file access errors.
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.
/api/files/tokenRecord authorization token.
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.
/api/files/{collection}/{recordId}/{filename}Collection name or ID containing the record.
Record ID containing the file field.
Stored file name.
Image modifier: `WxH`, `WxHt`, `WxHb`, `WxHf`, `0xH`, or `Wx0`. A configured field thumbnail size is required for generated thumbnails.
Short-lived file token for a protected file.
Use `1`, `t`, or `true` to request download disposition instead of inline preview.
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.pngWxH 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.