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"
}
| Status | Meaning |
|---|---|
400 | Invalid 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 |
401 | Missing or invalid token, or missing permission. Changing an immutable role or policy also returns 401 |
404 | Resource not found |
409 | Conflict: 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 |
429 | Rate limit exceeded, with Retry-After |
501 | Upload sessions and download URLs without a storage service |
502 / 504 | Cluster: forwarding a write to the leader failed or timed out. The write may or may not have been applied |
503 | Cluster node can't accept writes right now (details.leaderEndpoint), or image transform queue is full |
507 | Storage 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).
| Policy | Limit | Applies to |
|---|---|---|
global | 1000 / min | Collections, items, assets, users, roles, policies and GraphQL |
write | 50 / min | Every 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 return502, or504when the leader doesn't answer in time. After any of these the outcome of the write is unknown: send writes with anIdempotency-Keyand retry with the same key.
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
| Property | Type | Description |
|---|---|---|
name | string | Required. Field name |
type | string | TEXT, INTEGER, REAL, BOOLEAN, DATETIME, DATE, TIME, UUID, BYTES, JSON (plus aliases, see docs) |
nullable | bool | Default true |
isRequired | bool | Makes the field non-nullable |
defaultValue | string | Default value |
isUnique | bool | Adds a unique index |
isIndexed | bool | Adds an index |
isReference | bool | Makes the field a foreign key to another collection. The field must have type UUID |
referenceCollection | string | The referenced collection |
referenceField | string | Always unilayer_id (the default) |
cascadeDelete | bool | Deleting the referenced item deletes this one too |
order | int | Position of the field |
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
limit | int, default 100 |
offset | int, default 0 |
sort | Sort order |
["shop_orders", "shop_products", "tasks"]
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" }
]
}
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, ... } ]
}
Returns the collection's field definitions as an array.
Returns true or false.
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" } ] }
{
"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.
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 } }
Drops the field's column and all of its data.
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.
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.
Items
Items are the rows of a collection. The {id} in the paths below is the item's unilayer_id (a UUID).
Query
| Parameter | Description |
|---|---|
filter | field:op:value. Separate conditions with , for AND and | for OR. Operators: eq ne gt ge gte lt le lte like in isnull notnull |
sort | asc/desc (insertion order), or field, field:desc, f1,f2:desc. System fields such as unilayer_created_at work too |
limit | Page size, 1–1000, default 100 |
offset | Items to skip, default 0 |
fields | Comma-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.
Returns a single item in the item envelope.
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" }
Updates the fields you send and sets updatedAt. Required (non-nullable) fields must always be included.
{ "number": "SO-1001", "total": 199.90 }
Returns the number of items that match the optional filter, as a plain number.
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 } ]
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 } ] }
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"]
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
}
Query
limit / offset | Paging, default 100 / 0 |
sort | e.g. Name:asc (default), UploadedAt:desc |
fields | Field selection, e.g. Name,Size,Version |
fileType | document, image, video, audio, text, spreadsheet, archive, other |
name | Name contains |
minSize / maxSize | Size range in bytes |
includeDeleted | Include soft-deleted assets. Requires assets:write |
Creates the metadata record and returns the new uid. It doesn't upload any content yet.
{ "name": "logo.png" }
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.
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..." }
Checks that the whole file is there and matches its extension, and makes it the asset's new version.
{ "session": "eyJhbGciOiJFUzI1NiIs..." }
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": "..." }
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 }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..." }
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, height | Target size in px. Aspect ratio is kept when only one is set |
scale | Multiplier, e.g. 0.3. Can't be combined with width/height |
fit | contain (default), cover, stretch |
format | webp, png, jpg, gif |
quality | 1–100 (default 80), for jpg / webp |
original | true: the stored file byte for byte, not the optimized copy |
includeDeleted | true: 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.
Replaces the asset's custom key/value metadata.
{ "metadata": { "alt": "Company logo", "credit": "Design team" } }
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.
Restores a soft-deleted asset.
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.
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"
}
Query: limit (default 100), offset, sort.
If you leave out role, the user gets the default role (user).
{ "username": "shop-frontend", "role": "shop-reader" }
{ "role": "shop-editor" }
Issues a new token and invalidates the old one immediately.
Idempotent: deleting a user that doesn't exist also returns 204.
Returns the role names as strings. Useful for filling a role picker.
Returns the permissions the calling token has. Useful for showing or hiding UI features.
["collections:shop:read", "assets:read"]
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"]
}
{ "name": "shop-reader", "description": "Read access to the shop" }
{ "description": "Read-only shop access" }
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"]
}
{
"name": "shop-read",
"description": "Read all shop_* collections and assets",
"permissions": ["collections:shop:read", "assets:read"]
}
Both properties are optional. If you send permissions, it replaces the whole list.
{ "description": "...", "permissions": ["collections:shop:read"] }
POST /policies/1234...-uuid/permissions/assets:write
System
These endpoints live at the server root, not under /api/v1, unless the path says otherwise.
{
"status": "OK",
"message": "unilayer API is running",
"authenticated": false,
"version": "...",
"commitHash": "...",
"buildDate": "..."
}/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.
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.
A machine-readable description of this API, for client generators. An interactive reference is served at /api/v1.
The public keys the storage service checks transfer orders with, as a JSON Web Key Set. During a key rotation it holds both keys.
The answering node's role, the leader, term, log indexes, last snapshot and the members with their availability.
The members as the answering node knows them, as host:port.
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" }
Removes a node from the cluster; stop it afterwards. The leader can't remove itself – let it resign first.
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.
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.