Assets API
The Assets API manages binary files (assets) and the folders that group them. Its default base path is /api/assets. Resource routes are mounted under /resources; /capabilities, /sync-token, /changes and /operations sit directly on the base path. Mount an assets repository with buildAssetsApi from contentia/assets/api. Like every Contentia API server, it requires an access policy.
| JSON:API type | Description |
|---|---|
asset | A binary file with optional metadata |
folder | A logical grouping of assets |
asset-url | Public/private access URLs for an asset (included resource) |
asset-variation | Derived variations of an asset, e.g. image thumbnails (included resource) |
assets-capabilities | What the backend supports (pagination, change signals, filters); returned by GET /capabilities |
An asset's URLs and variations are sideloaded with ?include=urls,variations. Its metadata (MIME type, size, dimensions) is not an included resource: ?meta=true inlines it on the asset's data.meta instead.
Keys that contain / are percent-encoded in URLs: images/hero.jpg becomes images%2Fhero.jpg.
GET / lists the endpoints and is the one route the access policy doesn't guard. GET /openapi.json and GET /openapi.yaml serve the spec the list below is rendered from.
List resources in a folder
/resourcesParameters
Query Parameters
Folder key to list. Takes precedence over filter[folder] and filter[prefix]. Defaults to the root folder.
Alias for folder.
Alias for folder.
How many folder levels deep to walk. Clamped to a minimum of 1. Takes precedence over depth.
11Alias for filter[depth].
11Listing filter (when declared by the backend): case-insensitive substring match on the resource key. Listing filters are generic — any filter[filtering.filters is forwarded to the backend; undeclared names are rejected with 400.
Page number for page-based pagination (1-based). Defaults to 1 when no pagination key is present.
1Items per page. Combines with page[number], page[after] or page[before]; on its own it asks for the first page of that many items. With no page[*] parameter at all a page holds 10 items; when page[number], page[after] or page[before] comes without page[size], a page holds 100 items. Values outside 1 to 100 are clamped into that range rather than rejected.
1Zero-based item offset for offset-based pagination. Without page[limit], 100 items are returned.
0Maximum number of items to return. Read only together with page[offset]; on its own it is ignored and the request gets page 1 of 10 items. Values outside 1 to 100 are clamped into that range.
1Forward cursor. Pass an empty value to start a cursor iteration from the beginning, then follow links.next. Rejected with 400 when the backend does not declare cursor pagination (consult GET /capabilities, pagination.styles.cursor).
Backward cursor. Rejected with 400 when the backend does not declare cursor pagination (consult GET /capabilities, pagination.styles.cursor).
Comma-separated related resources to sideload into included: urls, variations (long-form aliases asset-url, asset-variation are also accepted).
Set to true (or 1, yes) to inline intrinsic asset metadata on data.meta.
Responses
A page of resources, with pagination links and optional meta.page.total / meta.warnings.
/resourcesSamples
Create an asset or folder
/resourcesRequest Body
The binary file to upload. Its name/type are used as fallbacks for key, filename and mimeType.
Optional JSON-encoded object with key, mimeType, filename, customMetadata and cacheControl. Individual form fields take precedence.
Asset key. Falls back to metadata.key, then the file name.
Falls back to the file's type, then 'application/octet-stream'.
Falls back to the file name.
A Cache-Control header value (e.g. public, max-age=3600) stored with the asset.
JSON-encoded string-to-string record. Invalid JSON is ignored.
Responses
The created asset or folder.
/resourcesSamples
Get a single resource by key
/resources/{key}Parameters
Query Parameters
Comma-separated related resources to sideload into included: urls, variations (long-form aliases asset-url, asset-variation are also accepted).
Set to true (or 1, yes) to inline intrinsic asset metadata on data.meta.
Responses
The resource, with optional included related resources and meta.warnings.
/resources/{key}Samples
Delete an asset or folder
/resources/{key}Looks the resource up first to decide between asset and folder deletion. Answers 204 on a clean delete. When the repository removes the resource but reports recoverable warnings, it answers 200 with them in meta.warnings. A resource the repository could not remove is an error, with the HTTP status mapped from its ContentiaError code.
Parameters
Query Parameters
Set to 'true' to delete a folder and its contents recursively.
"true""false"Responses
The delete finished with recoverable warnings, carried in meta.warnings (HTTP 204 forbids a body).
/resources/{key}Samples
Update an asset
/resources/{key}Updates asset metadata (mimeType, cacheControl, customMetadata). The key in the URL is used as the resource id; an id in the body is ignored.
Request Body
Responses
The updated asset.
/resources/{key}Samples
Batch write operations (add asset/folder, update asset, remove)
/operationsFail-fast batch. Every operation is first validated for request shape, before any I/O: a shape-invalid op (e.g. missing data.id, or a missing content on an asset add) returns 400 with zero writes. Every operation is then authorized up front as its own action (createAsset, createFolder, updateAsset, deleteResource); one denial rejects the whole batch with 403 before any write. The ops run in order, and the first failing op ends the batch with an errors entry in results; a remove whose target does not exist fails with status 404. Ops applied before the failure stay applied: this is a fail-fast batch, not a transaction. The vocabulary is operations / results, not the atomic:* vocabulary of the JSON:API Atomic Operations extension, which this endpoint never negotiates.
Request Body
Responses
One result per attempted operation, ending at the first failure if one occurred.
/operationsSamples
Get backend capabilities
/capabilitiesSurfaces the underlying assets repository capabilities (compatibility date, supported pagination styles) so clients can introspect what the backend supports instead of guessing.
Responses
The capabilities resource.
/capabilitiesSamples
Get an opaque change token for a scope
/sync-tokenReturns a token that changes whenever anything inside the scope (a folder, or the whole store when filter[folder] is omitted) changes. Compare tokens only by equality. Capability-gated: backends without change-signal support answer 501 (consult GET /capabilities, changes).
Parameters
Query Parameters
Scope the token to a folder. Omit for the whole store.
Responses
The current sync token for the scope.
/sync-tokenSamples
List changes since a sync token
/changesEnumerates what changed inside the scope since a previously obtained sync token. meta.syncToken on the response carries the new token to resume from. Capability-gated: backends without a change feed answer 501 (consult GET /capabilities, changes).
Parameters
Query Parameters
A sync token previously obtained from GET /sync-token or a prior GET /changes.
Scope the feed to a folder. Omit for the whole store. A token covers one scope, so this must match the filter[folder] the token was obtained with.
Responses
Change summary collection; meta.syncToken carries the new token.
/changes