REST API · v1

API Reference

Every unilayer resource is available over a JSON REST API. This page lists every endpoint with the permission it needs, its parameters and example payloads. For concepts and setup, see the documentation.

Base URL

https://<your-host>/api/v1

All paths below are relative to this base URL unless stated otherwise. Request and response bodies are JSON (Content-Type: application/json).

Authentication

Send the user's API token, or a configured static API token (which acts as an admin), as a bearer token with every request. Endpoints that don't need a token: GET /, the /health endpoints, the REST reference and OpenAPI documents, the GraphQL explorer, GET /storage/keys, and the direct-upload parts endpoint, which takes the upload session instead.

curl https://unilayer.example.com/api/v1/collections \
  -H "Authorization: Bearer $TOKEN"

Each endpoint below shows the permission it requires in a chip at the top right, e.g. collections:read. A write permission always includes the matching read.

Scoped collection permissions

The endpoints for collections and items also accept scoped permissions. A collection's scope is the part of its name before the first underscore. For example, shop_orders and shop_products both have the scope shop, so collections:shop:read grants read access to both.

Retrying writes: Idempotency-Key

Send any unique string (at most 255 characters) in the Idempotency-Key header of a POST, PUT, PATCH or DELETE, and the request may be retried without being applied twice. A retry with the same key gets the first response again, with Idempotent-Replay: true; a retry while the first request still runs gets 409. Responses with a 5xx status aren't remembered. Keys are kept for 24 hours and belong to the caller, method and path. Responses that carry a new API token are replayed as {"applied":true}.

Compression

JSON and other text responses are compressed with Brotli or gzip when the client sends Accept-Encoding.

Responses & errors

Items

Item endpoints wrap your data in an envelope. Your fields are in data and system values are in metadata, so they can never collide.

// single item
{
  "data": { "title": "Try unilayer", "done": false },
  "metadata": {
    "id": "550e8400-e29b-41d4-...",
    "index": 1,
    "createdAt": "2026-09-29T10:00:00Z",
    "updatedAt": null
  }
}
// list of items
{
  "data": [ { ... }, { ... } ],
  "metadata": {
    "count": 2,
    "limit": 100,
    "offset": 0,
    "has_more": false
  }
}

All other endpoints return the resource or list directly, without an envelope.

Errors

Errors raised by unilayer return a body with an error code, a message and, where it applies, the field that caused the error and further details. Some responses come from the framework instead: a missing or invalid token gets 401 with a plain-text message, model validation and some 404s use ASP.NET's ProblemDetails, and 429 has an empty body.

{
  "success": false,
  "errors": [
    { "code": "VALIDATION_ERROR", "message": "Field 'title' is required",
      "field": "title", "statusCode": 400 }
  ],
  "requestId": "0HN7...",
  "timestamp": "2026-09-29T10:00:00Z",
  "apiVersion": "1.0",
  "serverVersion": "2026.10.10"
}
StatusMeaning
400Invalid input: validation failure, bad filter or sort, unknown field, malformed ID. Creating something whose name already exists also returns 400, and so do some operations on an asset, user, role or policy that doesn't exist
401Missing or invalid token, or missing permission. Changing an immutable role or policy also returns 401
404Resource not found
409Conflict: a unique value or reference violated (CONSTRAINT_VIOLATION), a collection still referenced, an upload not finished, a purge not allowed yet, or a request with the same Idempotency-Key still running
429Rate limit exceeded, with Retry-After
501Upload sessions and download URLs without a storage service
502 / 504Cluster: forwarding a write to the leader failed or timed out. The write may or may not have been applied
503Cluster node can't accept writes right now (details.leaderEndpoint), or image transform queue is full
507Storage quota exceeded (STORAGE_QUOTA_EXCEEDED, with quotaBytes, usedBytes, neededBytes)

Rate limits

Limits are counted per client in fixed one-minute windows. A request over a limit gets 429 Too Many Requests with Retry-After at once; it is never queued. Both limits are configurable (rateLimit:globalPerMinute, rateLimit:writesPerMinute).

PolicyLimitApplies to
global1000 / minCollections, items, assets, users, roles, policies and GraphQL
write50 / minEvery endpoint that writes – collections, items, assets, users, roles, policies, cluster administration – and GraphQL mutations (RATE_LIMITED)

Separately, failed token attempts are throttled at 30 per client and minute.

Cluster behaviour

In cluster mode you can send any request to any node:

  • Writes are forwarded to the leader automatically and acknowledged once a majority has them.
  • Reads are answered by the node that receives them and can lag the leader by about one heartbeat.
  • If there's no leader, writes return 503. If forwarding to the leader fails, they return 502, or 504 when the leader doesn't answer in time. After any of these the outcome of the write is unknown: send writes with an Idempotency-Key and retry with the same key.
Resource

Collections

Collections are typed tables. Collection names must start with a letter and can contain letters, digits, _ and - (max. 63 characters). Field names must start with a letter or _ and can contain letters, digits and _. They can't start with unilayer_ or be a PostgreSQL reserved word.

Field definition

PropertyTypeDescription
namestringRequired. Field name
typestringTEXT, INTEGER, REAL, BOOLEAN, DATETIME, DATE, TIME, UUID, BYTES, JSON (plus aliases, see docs)
nullableboolDefault true
isRequiredboolMakes the field non-nullable
defaultValuestringDefault value
isUniqueboolAdds a unique index
isIndexedboolAdds an index
isReferenceboolMakes the field a foreign key to another collection. The field must have type UUID
referenceCollectionstringThe referenced collection
referenceFieldstringAlways unilayer_id (the default)
cascadeDeleteboolDeleting the referenced item deletes this one too
orderintPosition of the field
GET/collectionscollections:read · scoped
List collections

Returns the names of the collections you can see. If you only have scoped permissions, the list contains only the collections in your scopes.

Query

limitint, default 100
offsetint, default 0
sortSort order
["shop_orders", "shop_products", "tasks"]
POST/collectionscollections:write · scoped
Create collection

Creates the collection and its database table.

{
  "name": "shop_orders",
  "fields": [
    { "name": "number", "type": "TEXT", "nullable": false, "isUnique": true },
    { "name": "total", "type": "REAL" },
    { "name": "customer", "type": "UUID",
      "isReference": true, "referenceCollection": "shop_customers" }
  ]
}
201 Collection info400 invalid definition / already exists
GET/collections/{name}/infocollections:read · scoped
Get collection info

Returns the collection's metadata, its fields and its system fields.

{
  "name": "tasks",
  "tableName": "unilayer_tasks",
  "createdAt": "2026-09-29T10:00:00Z",
  "updatedAt": null,
  "isSystem": false,
  "fields": [ { "name": "title", "type": "TEXT", "nullable": false, ... } ],
  "systemFields": [ { "name": "unilayer_id", "type": "UUID", "isPrimaryKey": true, ... } ]
}
200404
GET/collections/{name}/fieldscollections:read · scoped
List fields

Returns the collection's field definitions as an array.

GET/collections/{name}/existscollections:read · scoped
Check existence

Returns true or false.

PUT/collections/{name}/schemacollections:write · scoped
Replace schema

Sends the complete list of fields. Fields that are new get added, fields that are missing get removed, and matching fields are kept. You can't change the name or type of an existing field.

{ "fields": [ { "name": "title", "type": "TEXT" }, { "name": "priority", "type": "INTEGER" } ] }
204400404
POST/collections/{name}/fieldscollections:write · scoped
Add field
{
  "name": "sku",
  "type": "TEXT",
  "options": { "isRequired": false, "isUnique": true, "isIndexed": false,
               "defaultValue": null }
}

To add a reference, use type UUID and set options.isForeignKey: true, options.referenceCollection and, if you like, options.cascadeDelete.

200400 invalid / field exists404 collection
PUT/collections/{name}/fields/{fieldName}collections:write · scoped
Update field

Replaces the field's options. Indexes and unique constraints are updated to match. The field's type can't be changed.

{ "options": { "isRequired": true, "isUnique": true } }
Options you leave out are reset to their defaults, so always send the full set.
200404
DELETE/collections/{name}/fields/{fieldName}collections:write · scoped
Delete field

Drops the field's column and all of its data.

200404
POST/collections/{name}/truncatecollections:write · scoped
Truncate collection

Deletes all items but keeps the schema. If other collections reference this one, add ?cascade=true. That also truncates every collection that references it, directly or indirectly. Without it, the request fails with 409 and the error names the collections that reference this one.

204404409 referenced
DELETE/collections/{name}collections:write · scoped
Delete collection

Drops the collection, its table and all of its data. If another collection still references it, the request fails with 409 and the error names the collections that reference it.

204404409 referenced
Resource

Items

Items are the rows of a collection. The {id} in the paths below is the item's unilayer_id (a UUID).

GET/collections/{name}collections:read · scoped
Query items

Query

ParameterDescription
filterfield:op:value. Separate conditions with , for AND and | for OR. Operators: eq ne gt ge gte lt le lte like in isnull notnull
sortasc/desc (insertion order), or field, field:desc, f1,f2:desc. System fields such as unilayer_created_at work too
limitPage size, 1–1000, default 100
offsetItems to skip, default 0
fieldsComma-separated field selection, e.g. title,customer.name. Use * for all fields
GET /collections/shop_orders?filter=total:gte:100,status:in:open\,paid&sort=total:desc&limit=20

The values of in are separated by \,; a plain comma starts the next condition.

References are expanded into nested objects, up to 3 levels deep. The response uses the list envelope, and metadata.has_more tells you whether there's another page.

200400 bad filter/sort404
GET/collections/{name}/{id}collections:read · scoped
Get item

Returns a single item in the item envelope.

200404
POST/collections/{name}collections:write · scoped
Create item

Send the item's fields as a plain JSON object. unilayer sets the system fields itself.

{ "number": "SO-1001", "total": 249.90, "customer": "8c1f...-uuid" }
201 item envelope400 validation404409 constraint violated
PUT/collections/{name}/{id}collections:write · scoped
Update item

Updates the fields you send and sets updatedAt. Required (non-nullable) fields must always be included.

{ "number": "SO-1001", "total": 199.90 }
204400404
DELETE/collections/{name}/{id}collections:write · scoped
Delete item
204404
GET/collections/{name}/countcollections:read · scoped
Count items

Returns the number of items that match the optional filter, as a plain number.

200400 bad filter404
POST/collections/{name}/bulkcollections:write · scoped
Bulk create

Adds up to 1,000 items in one transaction: all of them or none.

[ { "number": "SO-1002", "total": 19.90 }, { "number": "SO-1003", "total": 5.00 } ]
200 item envelopes400404409
PUT/collections/{name}/bulkcollections:write · scoped
Bulk update

Updates up to 1,000 items in one transaction. ids and entities are matched by position. If any id doesn't exist, nothing is changed.

{ "ids": ["8c1f...-uuid", "9d2a...-uuid"],
  "entities": [ { "total": 21.90 }, { "total": 6.00 } ] }
204400404
POST/collections/{name}/bulk/deletecollections:write · scoped
Bulk delete

Deletes up to 1,000 items by id in one transaction and returns how many were deleted. Ids that don't exist are skipped.

["8c1f...-uuid", "9d2a...-uuid"]
200 number deleted400404
Resource

Assets

First create the asset record to get its uid, then upload the content – through an upload session with the storage service, or, deprecated, as base64 through the API. The file type comes from the name's extension: pdf docx pptx (document), png jpg jpeg gif svg webp tif tiff heic (image), mp4 mov (video), m4a mp3 ogg opus wav (audio), xlsx csv (spreadsheet), zip (archive), and txt or no extension (text). Extensions an admin allows through assets:allowedExtensions become other. The content must match its extension, otherwise the upload gets 400.

Asset metadata

{
  "uid": "3f2c...-uuid",
  "name": "logo.png",
  "storagePath": "...",
  "size": 48213,
  "contentType": "image/png",
  "fileType": "image",
  "checksum": "9f86d081884c7d65...",   // SHA-256
  "metadata": { "alt": "Company logo" },
  "uploadedAt": "2026-09-29T10:00:00Z",
  "isDeleted": false,
  "deletedAt": null,
  "version": 1,
  "quotaScope": null
}
GET/assetsassets:read
List assets

Query

limit / offsetPaging, default 100 / 0
sorte.g. Name:asc (default), UploadedAt:desc
fieldsField selection, e.g. Name,Size,Version
fileTypedocument, image, video, audio, text, spreadsheet, archive, other
nameName contains
minSize / maxSizeSize range in bytes
includeDeletedInclude soft-deleted assets. Requires assets:write
200 metadata[]
POST/assetsassets:write
Create asset

Creates the metadata record and returns the new uid. It doesn't upload any content yet.

{ "name": "logo.png" }
201 metadata400 name missing / type not allowed
POST/assets/{uid}/upload-sessionassets:write
Start an upload

Checks type, size and quota and returns a transfer order for the storage service (or, in direct mode, for S3). quotaScope and quotaLimitBytes are optional: the asset belongs to the scope once the upload is complete.

{ "size": 48213, "sha256": "9f86d081884c7d65...", "quotaScope": "workspace-42", "quotaLimitBytes": 1073741824 }

// response
{
  "uid": "3f2c...-uuid", "version": 2, "session": "eyJhbGciOiJFUzI1NiIs...",
  "transfer": { "url": "https://files.example.com/v1/files/uploads/...?token=...", "method": "PUT",
                "headers": { "Content-Length": "48213" }, "expiresAt": "2026-10-23T14:15:00+00:00" }
}

From 16 MiB the order has parts: PUT each part to its URL, keep each ETag, then POST the list [{"partNumber":1,"etag":"..."}] to the order's URL.

200 session + order400501 no storage service507 quota
POST/assets/{uid}/upload-session/renewassets:write
Renew an upload

Hands out a new order and a new session for the same upload, keeping the parts already stored. Use it when an order expired or an upload was interrupted.

{ "session": "eyJhbGciOiJFUzI1NiIs..." }
200 session + order409 can't be completed anymore501
POST/assets/{uid}/upload-session/completeassets:write
Complete an upload

Checks that the whole file is there and matches its extension, and makes it the asset's new version.

{ "session": "eyJhbGciOiJFUzI1NiIs..." }
200 metadata400409 not finished / changed meanwhile501507
GET/assets/{uid}/download-urlassets:read
Get a download URL

Returns a GET order for the content that works without a token until expiresAt. Takes the image transform parameters, original=true for the stored file instead of an optimized copy, and disposition=inline|attachment. The storage service answers Range requests on it.

{ "url": "https://files.example.com/v1/files/...?token=...", "method": "GET", "headers": {}, "expiresAt": "..." }
200 order400501
GET/assets/quotaassets:read
Quota usage

What a scope takes (?scope=), or all assets without it. reservedBytes is what open uploads add; quotaBytes is the global storage:quotaBytes.

{ "scope": "workspace-42", "usedBytes": 52428800, "reservedBytes": 48213, "quotaBytes": 0 }
PUT/assets/{uid}assets:write
Upload content deprecated

Uploads or replaces the file content as base64 (contentBase64, or contentBytes), up to 100 MB by default. Every upload increases version, recalculates checksum and invalidates cached image variants. Once the storage service is enabled, the response carries Deprecation, Sunset and a Link to the upload session.

{ "contentBase64": "iVBORw0KGgoAAAANSUhEUgAA..." }
200 metadata400 no / invalid content, unknown uid507 quota
GET/assets/{uid}assets:read
Download asset

Returns the file content with its content type – the optimized copy of an image if there is one. Use download URLs once the storage service is enabled; then this endpoint is deprecated and doesn't honour Range. Parameters:

width, heightTarget size in px. Aspect ratio is kept when only one is set
scaleMultiplier, e.g. 0.3. Can't be combined with width/height
fitcontain (default), cover, stretch
formatwebp, png, jpg, gif
quality1–100 (default 80), for jpg / webp
originaltrue: the stored file byte for byte, not the optimized copy
includeDeletedtrue: also a soft-deleted asset. Requires assets:write
GET /assets/{uid}?width=300&height=300&fit=cover&format=webp

Transformed responses include an ETag. Send If-None-Match to get 304 when the image hasn't changed.

200 file304400 not an image / bad params404503 transform queue full
GET/assets/{uid}/metadataassets:read
Get metadata
200 metadata404
PUT/assets/{uid}/metadataassets:write
Update metadata

Replaces the asset's custom key/value metadata.

{ "metadata": { "alt": "Company logo", "credit": "Design team" } }
204400 unknown uid
DELETE/assets/{uid}assets:write · assets:purge
Delete asset

Soft-deletes the asset. You can restore it later. With ?purge=true (needs assets:purge), a deleted asset is removed for good: content, optimized copies, variants and record. A purge is only allowed once the asset has been deleted long enough (retention); &force=true skips that check.

204400 unknown uid / force without purge409 not purgeable yet
POST/assets/{uid}/restoreassets:write
Restore asset

Restores a soft-deleted asset.

204400 unknown uid507 quota
Security

Users

A user is a client of the API – an app, a service, a script –, not an end user of your app. It has a username, exactly one role and an API token. Creating a user, changing a role, renewing a token or deleting a user requires the caller to hold every permission of the target role; otherwise the request gets 401.

The plain-text apiToken is returned only when you create a user or renew their token. unilayer stores only a hash, so save the token right away.
{
  "id": "a1b2c3d4-...",
  "username": "shop-frontend",
  "role": "shop-reader",
  "apiToken": "...",        // create / renew only
  "createdAt": "2026-09-29T10:00:00Z"
}
GET/usersusers:read
List users

Query: limit (default 100), offset, sort.

GET/users/{id}users:read
Get user
200404
POST/usersusers:write
Create user

If you leave out role, the user gets the default role (user).

{ "username": "shop-frontend", "role": "shop-reader" }
201 user + apiToken400 invalid / username taken
PUT/users/{id}/roleusers:write
Change role
{ "role": "shop-editor" }
204400 unknown user / role
POST/users/{id}/renew-tokenusers:write
Renew token

Issues a new token and invalidates the old one immediately.

200 user + apiToken400 unknown user
DELETE/users/{id}users:write
Delete user

Idempotent: deleting a user that doesn't exist also returns 204.

204
GET/users/rolesusers:read
List assignable role names

Returns the role names as strings. Useful for filling a role picker.

GET/users/me/permissionsany valid token
My permissions

Returns the permissions the calling token has. Useful for showing or hiding UI features.

["collections:shop:read", "assets:read"]
Security

Roles

A role bundles policies. The built-in admin role is immutable, so any attempt to change it returns 401. Assigning a policy requires the caller to hold all of its permissions.

{
  "id": "8765...-uuid",
  "name": "shop-reader",
  "description": "Read access to the shop",
  "createdAt": "2026-09-29T10:00:00Z",
  "isImmutable": false,
  "policies": ["shop-read"]
}
GET/rolessecurity:read
List roles
GET/roles/{name}security:read
Get role by name
200404
POST/rolessecurity:write
Create role
{ "name": "shop-reader", "description": "Read access to the shop" }
201 role400 invalid / name taken
PUT/roles/{roleId}security:write
Update role
{ "description": "Read-only shop access" }
200 role400 not found401 immutable
DELETE/roles/{roleId}security:write
Delete role
204400 not found401 immutable
POST/roles/{roleId}/policies/{policyId}security:write
Assign policy to role
204400 unknown / already assigned401 permission not held
DELETE/roles/{roleId}/policies/{policyId}security:write
Remove policy from role
204
Security

Policies

A policy is a named list of permission strings (see permissions). The built-in fullaccess policy is immutable. Creating a policy, changing its permissions or adding one requires the caller to hold those permissions; otherwise the request gets 401.

{
  "id": "1234...-uuid",
  "name": "shop-read",
  "description": "Read all shop_* collections and assets",
  "createdAt": "2026-09-29T10:00:00Z",
  "isImmutable": false,
  "permissions": ["collections:shop:read", "assets:read"]
}
GET/policiessecurity:read
List policies
GET/policies/{name}security:read
Get policy by name
200404
POST/policiessecurity:write
Create policy
{
  "name": "shop-read",
  "description": "Read all shop_* collections and assets",
  "permissions": ["collections:shop:read", "assets:read"]
}
201 policy400 invalid / name taken401 permission not held
PUT/policies/{policyId}security:write
Update policy

Both properties are optional. If you send permissions, it replaces the whole list.

{ "description": "...", "permissions": ["collections:shop:read"] }
200 policy400 not found401 immutable
DELETE/policies/{policyId}security:write
Delete policy
204400 not found401 immutable
POST/policies/{policyId}/permissions/{permission}security:write
Add permission
POST /policies/1234...-uuid/permissions/assets:write
204401 permission not held / immutable
DELETE/policies/{policyId}/permissions/{permission}security:write
Remove permission
204
Operations

System

These endpoints live at the server root, not under /api/v1, unless the path says otherwise.

GET/public
Status & version
{
  "status": "OK",
  "message": "unilayer API is running",
  "authenticated": false,
  "version": "...",
  "commitHash": "...",
  "buildDate": "..."
}
GET/health · /health/live · /health/readypublic
Health checks

/health reports all checks with their data: database, Valkey, storage or storage service, and cluster. /health/live (database) and /health/ready (database, Valkey, storage service, cluster) are meant for orchestrator probes. In cluster mode, /health reports Degraded (still HTTP 200) when a certificate is close to expiring.

POST/api/v1/graphqlcollections:read / write
GraphQL

A GraphQL API generated from your collections, with the same permissions as REST. The explorer is at GET /api/v1/graphql/ui and the SDL download at GET /api/v1/graphql/schema. See the GraphQL guide.

GET/api/v1/openapi/{document}.json—
OpenAPI document

A machine-readable description of this API, for client generators. An interactive reference is served at /api/v1.

GET/api/v1/storage/keyspublic
Storage signing keys

The public keys the storage service checks transfer orders with, as a JSON Web Key Set. During a key rotation it holds both keys.

GET/api/v1/cluster/statuscluster:admin
Cluster status

The answering node's role, the leader, term, log indexes, last snapshot and the members with their availability.

GET/api/v1/cluster/memberscluster:admin
List members

The members as the answering node knows them, as host:port.

POST/api/v1/cluster/memberscluster:admin
Add a member

Adds a running node that was started with the current members as its peers. The leader brings it up to date from a snapshot and commits the new member list; the call returns when that is done, with the new list.

{ "endpoint": "10.0.0.4:7000" }
200 members409 node not reachable
DELETE/api/v1/cluster/members/{host:port}cluster:admin
Remove a member

Removes a node from the cluster; stop it afterwards. The leader can't remove itself – let it resign first.

200 members404 not a member409 leader / too few members
POST/api/v1/cluster/resigncluster:admin
Resign leadership

The leader gives up leadership and sits out the next election, e.g. before you restart it. Every cluster endpoint returns 400 when cluster mode is off.

202409 not the leader
POST/api/v1/cluster/snapshotcluster:admin
Request cluster snapshot

Asks this node to take a snapshot at the next log entry it applies. The response comes back right away: 202 means the request was accepted, not that the snapshot is done. Returns 400 if cluster mode is off. The cluster:admin permission is part of the built-in fullaccess policy.

202400