Skip to content

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 typeDescription
assetA binary file with optional metadata
folderA logical grouping of assets
asset-urlPublic/private access URLs for an asset (included resource)
asset-variationDerived variations of an asset, e.g. image thumbnails (included resource)
assets-capabilitiesWhat 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.

Resources​

Assets and folders.


List resources in a folder​

GET/resources

Parameters​

Query Parameters

folder

Folder key to list. Takes precedence over filter[folder] and filter[prefix]. Defaults to the root folder.

Type
string
filter[folder]

Alias for folder.

Type
string
filter[prefix]

Alias for folder.

Type
string
filter[depth]

How many folder levels deep to walk. Clamped to a minimum of 1. Takes precedence over depth.

Type
integer
Minimum
1
Default
1
depth

Alias for filter[depth].

Type
integer
Minimum
1
Default
1
filter[search]

Listing filter (when declared by the backend): case-insensitive substring match on the resource key. Listing filters are generic — any filter[] declared in GET /capabilities under filtering.filters is forwarded to the backend; undeclared names are rejected with 400.

Type
string
page[number]

Page number for page-based pagination (1-based). Defaults to 1 when no pagination key is present.

Type
integer
Minimum
1
page[size]

Items 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.

Type
integer
Minimum
1
page[offset]

Zero-based item offset for offset-based pagination. Without page[limit], 100 items are returned.

Type
integer
Minimum
0
page[limit]

Maximum 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.

Type
integer
Minimum
1
page[after]

Forward 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).

Type
string
page[before]

Backward cursor. Rejected with 400 when the backend does not declare cursor pagination (consult GET /capabilities, pagination.styles.cursor).

Type
string
include

Comma-separated related resources to sideload into included: urls, variations (long-form aliases asset-url, asset-variation are also accepted).

Type
string
meta

Set to true (or 1, yes) to inline intrinsic asset metadata on data.meta.

Type
string

Responses​

A page of resources, with pagination links and optional meta.page.total / meta.warnings.

application/vnd.api+json
JSON
{
  
"data": [
  
  
{
  
  
  
"type": "asset",
  
  
  
"id": "string",
  
  
  
"attributes": {
  
  
  
  
"type": "asset",
  
  
  
  
"createdAt": "string",
  
  
  
  
"updatedAt": "string",
  
  
  
  
"content": {
  
  
  
  
  
"additionalProperties": "string"
  
  
  
  
},
  
  
  
  
"version": "string"
  
  
  
},
  
  
  
"meta": {
  
  
  
  
"kind": "image",
  
  
  
  
"size": 0,
  
  
  
  
"mimeType": "string",
  
  
  
  
"filename": "string",
  
  
  
  
"extension": "string",
  
  
  
  
"hash": "string",
  
  
  
  
"hashAlgorithm": "string",
  
  
  
  
"createdAt": "2024-01-01T00:00:00Z",
  
  
  
  
"modifiedAt": "2024-01-01T00:00:00Z",
  
  
  
  
"additionalProperties": "string"
  
  
  
},
  
  
  
"relationships": {
  
  
  
  
"urls": {
  
  
  
  
  
"data": {
  
  
  
  
  
  
"type": "asset-url",
  
  
  
  
  
  
"id": "string"
  
  
  
  
  
}
  
  
  
  
},
  
  
  
  
"variations": {
  
  
  
  
  
"data": {
  
  
  
  
  
  
"type": "asset-variation",
  
  
  
  
  
  
"id": "string"
  
  
  
  
  
}
  
  
  
  
}
  
  
  
},
  
  
  
"links": {
  
  
  
  
"self": "string",
  
  
  
  
"additionalProperties": "string"
  
  
  
}
  
  
}
  
],
  
"included": [
  
  
{
  
  
  
"type": "asset-url",
  
  
  
"id": "string",
  
  
  
"attributes": {
  
  
  
  
"url": "string",
  
  
  
  
"expiresAt": "2024-01-01T00:00:00Z"
  
  
  
}
  
  
}
  
],
  
"links": {
  
  
"self": "string",
  
  
"first": "string",
  
  
"prev": "string",
  
  
"next": "string"
  
},
  
"meta": {
  
  
"page": {
  
  
  
"total": 0
  
  
},
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}

Samples​


Create an asset or folder​

POST/resources

Request 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.

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "asset",
  
  
"id": "string",
  
  
"attributes": {
  
  
  
"type": "asset",
  
  
  
"createdAt": "string",
  
  
  
"updatedAt": "string",
  
  
  
"content": {
  
  
  
  
"additionalProperties": "string"
  
  
  
},
  
  
  
"version": "string"
  
  
},
  
  
"meta": {
  
  
  
"kind": "image",
  
  
  
"size": 0,
  
  
  
"mimeType": "string",
  
  
  
"filename": "string",
  
  
  
"extension": "string",
  
  
  
"hash": "string",
  
  
  
"hashAlgorithm": "string",
  
  
  
"createdAt": "2024-01-01T00:00:00Z",
  
  
  
"modifiedAt": "2024-01-01T00:00:00Z",
  
  
  
"additionalProperties": "string"
  
  
},
  
  
"relationships": {
  
  
  
"urls": {
  
  
  
  
"data": {
  
  
  
  
  
"type": "asset-url",
  
  
  
  
  
"id": "string"
  
  
  
  
}
  
  
  
},
  
  
  
"variations": {
  
  
  
  
"data": {
  
  
  
  
  
"type": "asset-variation",
  
  
  
  
  
"id": "string"
  
  
  
  
}
  
  
  
}
  
  
},
  
  
"links": {
  
  
  
"self": "string",
  
  
  
"additionalProperties": "string"
  
  
}
  
},
  
"meta": {
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}

Samples​


Get a single resource by key​

GET/resources/{key}

Parameters​

Query Parameters

include

Comma-separated related resources to sideload into included: urls, variations (long-form aliases asset-url, asset-variation are also accepted).

Type
string
meta

Set to true (or 1, yes) to inline intrinsic asset metadata on data.meta.

Type
string

Responses​

The resource, with optional included related resources and meta.warnings.

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "asset",
  
  
"id": "string",
  
  
"attributes": {
  
  
  
"type": "asset",
  
  
  
"createdAt": "string",
  
  
  
"updatedAt": "string",
  
  
  
"content": {
  
  
  
  
"additionalProperties": "string"
  
  
  
},
  
  
  
"version": "string"
  
  
},
  
  
"meta": {
  
  
  
"kind": "image",
  
  
  
"size": 0,
  
  
  
"mimeType": "string",
  
  
  
"filename": "string",
  
  
  
"extension": "string",
  
  
  
"hash": "string",
  
  
  
"hashAlgorithm": "string",
  
  
  
"createdAt": "2024-01-01T00:00:00Z",
  
  
  
"modifiedAt": "2024-01-01T00:00:00Z",
  
  
  
"additionalProperties": "string"
  
  
},
  
  
"relationships": {
  
  
  
"urls": {
  
  
  
  
"data": {
  
  
  
  
  
"type": "asset-url",
  
  
  
  
  
"id": "string"
  
  
  
  
}
  
  
  
},
  
  
  
"variations": {
  
  
  
  
"data": {
  
  
  
  
  
"type": "asset-variation",
  
  
  
  
  
"id": "string"
  
  
  
  
}
  
  
  
}
  
  
},
  
  
"links": {
  
  
  
"self": "string",
  
  
  
"additionalProperties": "string"
  
  
}
  
},
  
"included": [
  
  
{
  
  
  
"type": "asset-url",
  
  
  
"id": "string",
  
  
  
"attributes": {
  
  
  
  
"url": "string",
  
  
  
  
"expiresAt": "2024-01-01T00:00:00Z"
  
  
  
}
  
  
}
  
],
  
"meta": {
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}

Samples​


Delete an asset or folder​

DELETE/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

recursive

Set to 'true' to delete a folder and its contents recursively.

Type
string
Valid values
"true""false"

Responses​

The delete finished with recoverable warnings, carried in meta.warnings (HTTP 204 forbids a body).

application/vnd.api+json
JSON
{
  
"meta": {
  
  
"deleted": true,
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}

Samples​


Update an asset​

PATCH/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​

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "asset",
  
  
"attributes": {
  
  
  
"mimeType": "string",
  
  
  
"cacheControl": "string",
  
  
  
"customMetadata": {
  
  
  
  
"additionalProperties": "string"
  
  
  
}
  
  
}
  
}
}

Responses​

The updated asset.

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "asset",
  
  
"id": "string",
  
  
"attributes": {
  
  
  
"type": "asset",
  
  
  
"createdAt": "string",
  
  
  
"updatedAt": "string",
  
  
  
"content": {
  
  
  
  
"additionalProperties": "string"
  
  
  
},
  
  
  
"version": "string"
  
  
},
  
  
"meta": {
  
  
  
"kind": "image",
  
  
  
"size": 0,
  
  
  
"mimeType": "string",
  
  
  
"filename": "string",
  
  
  
"extension": "string",
  
  
  
"hash": "string",
  
  
  
"hashAlgorithm": "string",
  
  
  
"createdAt": "2024-01-01T00:00:00Z",
  
  
  
"modifiedAt": "2024-01-01T00:00:00Z",
  
  
  
"additionalProperties": "string"
  
  
},
  
  
"relationships": {
  
  
  
"urls": {
  
  
  
  
"data": {
  
  
  
  
  
"type": "asset-url",
  
  
  
  
  
"id": "string"
  
  
  
  
}
  
  
  
},
  
  
  
"variations": {
  
  
  
  
"data": {
  
  
  
  
  
"type": "asset-variation",
  
  
  
  
  
"id": "string"
  
  
  
  
}
  
  
  
}
  
  
},
  
  
"links": {
  
  
  
"self": "string",
  
  
  
"additionalProperties": "string"
  
  
}
  
},
  
"meta": {
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}

Samples​


Operations​

Fail-fast batch write operations.


Batch write operations (add asset/folder, update asset, remove)​

POST/operations

Fail-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​

application/vnd.api+json
JSON
{
  
"operations": [
  
  
{
  
  
  
"op": "add",
  
  
  
"data": {
  
  
  
  
"type": "asset",
  
  
  
  
"id": "string",
  
  
  
  
"attributes": {
  
  
  
  
  
"mimeType": "string",
  
  
  
  
  
"filename": "string",
  
  
  
  
  
"cacheControl": "string",
  
  
  
  
  
"customMetadata": {
  
  
  
  
  
  
"additionalProperties": "string"
  
  
  
  
  
},
  
  
  
  
  
"content": "string"
  
  
  
  
}
  
  
  
}
  
  
}
  
]
}

Responses​

One result per attempted operation, ending at the first failure if one occurred.

application/vnd.api+json
JSON
{
  
"results": [
  
  
{
  
  
  
"data": {
  
  
  
  
"type": "asset",
  
  
  
  
"id": "string",
  
  
  
  
"attributes": {
  
  
  
  
  
"type": "asset",
  
  
  
  
  
"createdAt": "string",
  
  
  
  
  
"updatedAt": "string",
  
  
  
  
  
"content": {
  
  
  
  
  
  
"additionalProperties": "string"
  
  
  
  
  
},
  
  
  
  
  
"version": "string"
  
  
  
  
},
  
  
  
  
"meta": {
  
  
  
  
  
"kind": "image",
  
  
  
  
  
"size": 0,
  
  
  
  
  
"mimeType": "string",
  
  
  
  
  
"filename": "string",
  
  
  
  
  
"extension": "string",
  
  
  
  
  
"hash": "string",
  
  
  
  
  
"hashAlgorithm": "string",
  
  
  
  
  
"createdAt": "2024-01-01T00:00:00Z",
  
  
  
  
  
"modifiedAt": "2024-01-01T00:00:00Z",
  
  
  
  
  
"additionalProperties": "string"
  
  
  
  
},
  
  
  
  
"relationships": {
  
  
  
  
  
"urls": {
  
  
  
  
  
  
"data": {
  
  
  
  
  
  
  
"type": "asset-url",
  
  
  
  
  
  
  
"id": "string"
  
  
  
  
  
  
}
  
  
  
  
  
},
  
  
  
  
  
"variations": {
  
  
  
  
  
  
"data": {
  
  
  
  
  
  
  
"type": "asset-variation",
  
  
  
  
  
  
  
"id": "string"
  
  
  
  
  
  
}
  
  
  
  
  
}
  
  
  
  
},
  
  
  
  
"links": {
  
  
  
  
  
"self": "string",
  
  
  
  
  
"additionalProperties": "string"
  
  
  
  
}
  
  
  
},
  
  
  
"meta": {
  
  
  
  
"warnings": [
  
  
  
  
  
{
  
  
  
  
  
  
"code": "string",
  
  
  
  
  
  
"status": "string",
  
  
  
  
  
  
"title": "string",
  
  
  
  
  
  
"detail": "string",
  
  
  
  
  
  
"source": {
  
  
  
  
  
  
  
"pointer": "string"
  
  
  
  
  
  
}
  
  
  
  
  
}
  
  
  
  
]
  
  
  
}
  
  
}
  
]
}

Samples​


Capabilities​

Introspection of what the underlying assets backend supports.


Get backend capabilities​

GET/capabilities

Surfaces 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.

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "assets-capabilities",
  
  
"id": "self",
  
  
"attributes": {
  
  
  
"compatibilityDate": "2024-01-01",
  
  
  
"pagination": {
  
  
  
  
"supported": false,
  
  
  
  
"description": "string"
  
  
  
},
  
  
  
"versionTracking": {
  
  
  
  
"supported": false,
  
  
  
  
"description": "string"
  
  
  
},
  
  
  
"changes": {
  
  
  
  
"supported": false,
  
  
  
  
"description": "string"
  
  
  
},
  
  
  
"filtering": {
  
  
  
  
"supported": false,
  
  
  
  
"description": "string"
  
  
  
}
  
  
},
  
  
"links": {
  
  
  
"self": "string",
  
  
  
"additionalProperties": "string"
  
  
}
  
}
}

Samples​


Changes​

Capability-gated change signals (sync tokens + change feed).


Get an opaque change token for a scope​

GET/sync-token

Returns 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

filter[folder]

Scope the token to a folder. Omit for the whole store.

Type
string

Responses​

The current sync token for the scope.

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "sync-token",
  
  
"id": "string",
  
  
"attributes": {
  
  
  
"syncToken": "string",
  
  
  
"folder": "string"
  
  
},
  
  
"links": {
  
  
  
"self": "string",
  
  
  
"additionalProperties": "string"
  
  
}
  
},
  
"meta": {
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}

Samples​


List changes since a sync token​

GET/changes

Enumerates 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

filter[since]*

A sync token previously obtained from GET /sync-token or a prior GET /changes.

Type
string
Required
filter[folder]

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.

Type
string

Responses​

Change summary collection; meta.syncToken carries the new token.

application/vnd.api+json
JSON
{
  
"data": [
  
  
{
  
  
  
"type": "change-summary",
  
  
  
"id": "string",
  
  
  
"attributes": {
  
  
  
  
"deleted": true,
  
  
  
  
"version": "string"
  
  
  
}
  
  
}
  
],
  
"meta": {
  
  
"page": {
  
  
  
"total": 0
  
  
},
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
],
  
  
"syncToken": "string"
  
}
}

Samples​