API Reference

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

["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": "TEXT",
      "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,
               "maxLength": 64, "defaultValue": null }
}

To add a reference, set options.isForeignKey: true and options.referenceCollection.

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.

Query

GET /collections/shop_orders?filter=total:gte:100,status:in:open,paid&sort=total:desc&limit=20

References are expanded into nested objects, up to 3 levels deep. The response uses the list envelope, and metadata.hasMore 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 }

Query

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

{ "name": "logo.png" }

Uploads or replaces the file content. Every upload increases version, recalculates checksum and invalidates cached image variants.

{ "contentBase64": "iVBORw0KGgoAAAANSUhEUgAA..." }

Returns the file content with its content type. For images you can add transform parameters:

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.

Restores a soft-deleted asset.

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.

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"]

{ "name": "shop-reader", "description": "Read access to the shop" }

{ "description": "Read-only shop access" }

{
  "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