REST API

The full Loom REST API, rooted at /api/v1, with its authentication rules and an embedded Swagger explorer over the generated OpenAPI document.

Loom exposes its full functionality via a versioned REST API. All endpoints are rooted at /api/v1.

Authentication

All endpoints except POST /api/v1/login, the OAuth2 routes, /api/v1/health and the OpenAPI document itself require a JWT bearer token:

Authorization: Bearer <token>

Obtain a token via the Authentication flow.

Base URL

http://<host>:8092/api/v1

Default port is 8092 (overridable via LOOM_SERVER_REST_PORT).

OpenAPI Specification

The complete API surface — every route, its path and query parameters, its request and response examples and the authentication it requires — is described by an OpenAPI 3.0 document. It is generated from the server’s endpoint registry, never written by hand, so it cannot drift away from the running code.

Download the spec

Feed it to a client generator, an API workbench (Postman, Insomnia, Bruno) or your editor's HTTP client.

openapi.yaml openapi.json

Explore it

Browse the API by resource group in the explorer below — filter by keyword, expand an operation to see its parameters and examples, and link straight to it.

API Explorer

A running server serves the same document for its own endpoint set, with its own address filled in as the server URL:

curl http://localhost:8092/api/v1/openapi        # YAML (default)
curl http://localhost:8092/api/v1/openapi.yaml   # YAML
curl http://localhost:8092/api/v1/openapi.json   # JSON

For a language Loom does not ship a client for, an OpenAPI generator will scaffold one from the specification:

openapi-generator-cli generate \
  -i https://metaloom.io/docs/examples/openapi.yaml \
  -g typescript-fetch -o ./loom-client

Note	The specification documents request and response bodies by example rather than by schema, so a generated client gives you the routes but leaves the bodies untyped. The maintained clients below do not have that limitation.

Tip	Loom ships maintained, typed clients for Java and Python — see Java Client and Python Client. Prefer either over a generated one.

API Explorer

The explorer below renders the bundled specification. Operations are grouped by resource; use the filter box to narrow the list, and expand an operation to see its parameters, request body and response examples.

To call a live server from here, set the server URL to your instance, click Authorize and paste a JWT obtained from POST /api/v1/login or an API token from the Loom UI admin area. Note that the API must allow your browser’s origin (CORS) for in-page calls to succeed.

Listing, sorting and filtering

Every collection route (/assets, /collections, /users, …) answers with { data, _metainfo } and accepts the same four query parameters.

Parameter Default Description

Parameter	Default	Description
`limit`	`25`	Page size. A bare `GET /api/v1/assets` returns a page, not the collection.
`from`	—	Seek cursor: the uuid to continue after. Take it from `_metainfo.lastUuid` of the previous page.
`sort`	`uuid`	Column to order by — `name`, `created`, `edited`, and per type also `username`, `firstname`, `lastname`, `email`, `sha512`, `md5`.
`dir`	`asc`	`asc` or `desc`.

limit

25

Page size. A bare GET /api/v1/assets returns a page, not the collection.

from

—

Seek cursor: the uuid to continue after. Take it from _metainfo.lastUuid of the previous page.

sort

uuid

Column to order by — name, created, edited, and per type also username, firstname, lastname, email, sha512, md5.

dir

asc

asc or desc.

Primary keys are time-ordered (UUIDv7), so the default order is the order elements were created in: a new element appears at the end of the list rather than in an unpredictable position.

List the assets most recently edited first

curl -H "Authorization: Bearer $TOKEN" \
  "https://loom.example.com/api/v1/assets?sort=edited&dir=desc&limit=50"

Filtering

filter takes one or more terms in the form field[eq]=value, several of them separated by commas in a single filter parameter. Terms are combined with AND.

Field Value Available on

Field	Value	Available on
`name`	exact name	Collections, tags, libraries, persons, and assets (matched against the filename)
`creator` / `editor`	user uuid	Anything with a creator — assets, collections, tags, libraries, tasks, …
`collection`	collection uuid	Assets — returns the members of that collection
`username`	exact username	Users
`size`	byte range	Assets
`status`	state name	Pipeline runs and run items

name

exact name

Collections, tags, libraries, persons, and assets (matched against the filename)

creator / editor

user uuid

Anything with a creator — assets, collections, tags, libraries, tasks, …

collection

collection uuid

Assets — returns the members of that collection

username

exact username

Users

size

byte range

Assets

status

state name

Pipeline runs and run items

Assets in one collection, created by one user, oldest first

curl -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "filter=collection[eq]=$COLLECTION_UUID,creator[eq]=$USER_UUID" \
  --data-urlencode "sort=created" \
  --get "https://loom.example.com/api/v1/assets"

Note

creator takes a uuid, not a username, so a filter kept in a bookmark or a saved view survives the user being renamed. Every element response carries status.creator.uuid.

Filters match exactly — there is no "contains". For text search across the catalogue use the search endpoints, which rank by relevance.

Warning

When you page a sorted listing, from must name a row that still exists — resuming needs that row’s value in the sort column. If the element has been deleted in the meantime the request answers 400; start the listing again. The default (unsorted) order has no such restriction.

Endpoint Reference

The tables below are a reading guide to the most-used routes, grouped the way you are likely to need them. They are a summary — the API Explorer above is the complete and authoritative list.

Auth

Method Path Description

Method	Path	Description
POST	`/api/v1/login`	Login with username + password, returns a JWT and sets the session cookie
GET	`/api/v1/auth/oauth2/login`	Start the OAuth2 (BFF) flow — redirects to the identity provider
GET	`/api/v1/auth/oauth2/callback`	Handle the identity provider callback and set the Loom JWT
GET	`/api/v1/auth/oauth2/logout`	Clear the session cookie
GET	`/api/v1/me`	Load the currently authenticated user
CRUD	`/api/v1/tokens`	Manage long-lived API tokens

POST

/api/v1/login

GET

/api/v1/auth/oauth2/login

Start the OAuth2 (BFF) flow — redirects to the identity provider

GET

/api/v1/auth/oauth2/callback

Handle the identity provider callback and set the Loom JWT

GET

/api/v1/auth/oauth2/logout

Clear the session cookie

GET

/api/v1/me

Load the currently authenticated user

CRUD

/api/v1/tokens

Manage long-lived API tokens

Assets

Method Path Description

Method	Path	Description
POST	`/api/v1/assets`	Create a new asset
GET	`/api/v1/assets`	List assets (paged)
POST	`/api/v1/assets/bulk/create`	Bulk-create assets
POST	`/api/v1/assets/bulk/update`	Bulk-update assets
GET	`/api/v1/assets/sha512/:sha512`	Load asset by SHA-512 hash
POST	`/api/v1/assets/sha512/:sha512`	Update asset by SHA-512 hash
DELETE	`/api/v1/assets/sha512/:sha512`	Delete asset by SHA-512 hash
GET	`/api/v1/assets/:uuid`	Load asset by UUID
POST	`/api/v1/assets/:uuid`	Update asset by UUID
DELETE	`/api/v1/assets/:uuid`	Delete asset by UUID
POST	`/api/v1/assets/:uuid/tags`	Add tag to asset
PUT	`/api/v1/assets/:uuid/tags`	Add a whole set of tags at once, and remove the ones listed in `withdraw`
DELETE	`/api/v1/assets/:uuid/tags/:tagUuid`	Remove tag from asset, with every placement of it
DELETE	`/api/v1/assets/:uuid/tag-placements/:placementUuid`	Remove one placement of a tag — one face, one timecode — keeping the others
POST	`/api/v1/assets/:uuid/reactions`	Add reaction
GET	`/api/v1/assets/:uuid/reactions`	List reactions
GET	`/api/v1/assets/:uuid/reactions/:reactionUuid`	Load reaction
POST	`/api/v1/assets/:uuid/reactions/:reactionUuid`	Update reaction
DELETE	`/api/v1/assets/:uuid/reactions/:reactionUuid`	Delete reaction
POST	`/api/v1/assets/:uuid/binary`	Upload binary data
GET	`/api/v1/assets/:uuid/binary`	Download binary data
DELETE	`/api/v1/assets/:uuid/binary`	Delete binary data
POST	`/api/v1/assets/:uuid/json-comps`	Upsert a generic JSON component (schema-agnostic node result sink)
GET	`/api/v1/assets/:uuid/json-comps`	List an asset’s JSON components
GET	`/api/v1/assets/:uuid/components`	List typed asset components
POST	`/api/v1/assets/:uuid/node-results`	Record a node-result ledger row (asset, nodeKind, nodeId)

POST

/api/v1/assets

Create a new asset

GET

/api/v1/assets

List assets (paged)

POST

/api/v1/assets/bulk/create

Bulk-create assets

POST

/api/v1/assets/bulk/update

Bulk-update assets

GET

/api/v1/assets/sha512/:sha512

Load asset by SHA-512 hash

POST

/api/v1/assets/sha512/:sha512

Update asset by SHA-512 hash

DELETE

/api/v1/assets/sha512/:sha512

Delete asset by SHA-512 hash

GET

/api/v1/assets/:uuid

Load asset by UUID

POST

/api/v1/assets/:uuid

Update asset by UUID

DELETE

/api/v1/assets/:uuid

Delete asset by UUID

POST

/api/v1/assets/:uuid/tags

Add tag to asset

PUT

/api/v1/assets/:uuid/tags

Add a whole set of tags at once, and remove the ones listed in withdraw

DELETE

/api/v1/assets/:uuid/tags/:tagUuid

Remove tag from asset, with every placement of it

DELETE

/api/v1/assets/:uuid/tag-placements/:placementUuid

Remove one placement of a tag — one face, one timecode — keeping the others

POST

/api/v1/assets/:uuid/reactions

Add reaction

GET

/api/v1/assets/:uuid/reactions

List reactions

GET

/api/v1/assets/:uuid/reactions/:reactionUuid

Load reaction

POST

/api/v1/assets/:uuid/reactions/:reactionUuid

Update reaction

DELETE

/api/v1/assets/:uuid/reactions/:reactionUuid

Delete reaction

POST

/api/v1/assets/:uuid/binary

Upload binary data

GET

/api/v1/assets/:uuid/binary

Download binary data

DELETE

/api/v1/assets/:uuid/binary

Delete binary data

POST

/api/v1/assets/:uuid/json-comps

Upsert a generic JSON component (schema-agnostic node result sink)

GET

/api/v1/assets/:uuid/json-comps

List an asset’s JSON components

GET

/api/v1/assets/:uuid/components

List typed asset components

POST

/api/v1/assets/:uuid/node-results

Record a node-result ledger row (asset, nodeKind, nodeId)

Tip	`json-comps` + `node-results` is the lightweight persistence path used by Cortex nodes. See Cortex Examples.

Users

Method Path Description

Method	Path	Description
POST	`/api/v1/users`	Create user
GET	`/api/v1/users`	List users (paged)
GET	`/api/v1/users/:uuid`	Load user
POST	`/api/v1/users/:uuid`	Update user
DELETE	`/api/v1/users/:uuid`	Delete user

POST

/api/v1/users

Create user

GET

/api/v1/users

List users (paged)

GET

/api/v1/users/:uuid

Load user

POST

/api/v1/users/:uuid

Update user

DELETE

/api/v1/users/:uuid

Delete user

Groups

Method Path Description

Method	Path	Description
POST	`/api/v1/groups`	Create group
GET	`/api/v1/groups`	List groups
GET	`/api/v1/groups/:uuid`	Load group
POST	`/api/v1/groups/:uuid`	Update group
DELETE	`/api/v1/groups/:uuid`	Delete group

POST

/api/v1/groups

Create group

GET

/api/v1/groups

List groups

GET

/api/v1/groups/:uuid

Load group

POST

/api/v1/groups/:uuid

Update group

DELETE

/api/v1/groups/:uuid

Delete group

Roles

Method Path Description

Method	Path	Description
POST	`/api/v1/roles`	Create role
GET	`/api/v1/roles`	List roles
GET	`/api/v1/roles/:uuid`	Load role
POST	`/api/v1/roles/:uuid`	Update role
DELETE	`/api/v1/roles/:uuid`	Delete role

POST

/api/v1/roles

Create role

GET

/api/v1/roles

List roles

GET

/api/v1/roles/:uuid

Load role

POST

/api/v1/roles/:uuid

Update role

DELETE

/api/v1/roles/:uuid

Delete role

Method	Path	Description
POST	`/api/v1/tags`	Create tag
GET	`/api/v1/tags`	List tags
GET	`/api/v1/tags/:uuid`	Load tag
POST	`/api/v1/tags/:uuid`	Update tag
DELETE	`/api/v1/tags/:uuid`	Delete tag

Pipelines

Pipelines are versioned: each update creates a new immutable version. Runs are executed by Loom’s engine and delegated to registered Cortex workers — see Pipeline Mechanism.

Method Path Description

Method	Path	Description
POST	`/api/v1/pipelines`	Create pipeline (writes version 1)
GET	`/api/v1/pipelines`	List pipelines
GET	`/api/v1/pipelines/:uuid`	Load pipeline (latest version)
POST	`/api/v1/pipelines/:uuid`	Update pipeline (creates a new version)
DELETE	`/api/v1/pipelines/:uuid`	Delete pipeline
POST	`/api/v1/pipelines/:uuid/run`	Start a run (body: `mediaUuids`, `pathGlobs`, `dryRun`)
GET	`/api/v1/pipelines/:uuid/runs`	List run history with status + counters
GET	`/api/v1/pipelines/:uuid/versions`	List versions
GET	`/api/v1/pipelines/:uuid/versions/:version`	Load a specific version
POST	`/api/v1/pipelines/:uuid/versions/:version/restore`	Restore a version as a new version
GET	`/api/v1/pipelines/events/ws`	WebSocket: live pipeline run events

POST

/api/v1/pipelines

Create pipeline (writes version 1)

GET

/api/v1/pipelines

List pipelines

GET

/api/v1/pipelines/:uuid

Load pipeline (latest version)

POST

/api/v1/pipelines/:uuid

Update pipeline (creates a new version)

DELETE

/api/v1/pipelines/:uuid

Delete pipeline

POST

/api/v1/pipelines/:uuid/run

Start a run (body: mediaUuids, pathGlobs, dryRun)

GET

/api/v1/pipelines/:uuid/runs

List run history with status + counters

GET

/api/v1/pipelines/:uuid/versions

List versions

GET

/api/v1/pipelines/:uuid/versions/:version

Load a specific version

POST

/api/v1/pipelines/:uuid/versions/:version/restore

Restore a version as a new version

GET

/api/v1/pipelines/events/ws

WebSocket: live pipeline run events

Processors (Cortex workers)

Method Path Description

Method	Path	Description
GET	`/api/v1/processors`	List registered Cortex workers and their state
GET	`/api/v1/processors/:uuid`	Load one worker (capabilities, node-kind restriction)
GET	`/api/v1/processors/ws`	WebSocket: the control channel Cortex workers connect to

GET

/api/v1/processors

List registered Cortex workers and their state

GET

/api/v1/processors/:uuid

Load one worker (capabilities, node-kind restriction)

GET

/api/v1/processors/ws

WebSocket: the control channel Cortex workers connect to

AI Agent — Chats

Method Path Description

Method	Path	Description
POST	`/api/v1/chats`	Create a chat
GET	`/api/v1/chats`	List chats
GET/POST/DELETE	`/api/v1/chats/:uuid`	Load / update / delete a chat
POST	`/api/v1/chats/:uuid/stream`	Send a message; receive the agent run as an SSE stream
DELETE	`/api/v1/chats/:uuid/stream`	Cancel the active run

POST

/api/v1/chats

Create a chat

GET

/api/v1/chats

List chats

GET/POST/DELETE

/api/v1/chats/:uuid

Load / update / delete a chat

POST

/api/v1/chats/:uuid/stream

Send a message; receive the agent run as an SSE stream

DELETE

/api/v1/chats/:uuid/stream

Cancel the active run

See Chat & AI Agent for the streaming event protocol.

AI Agent — Sessions, Skills, Memory

Method Path Description

Method	Path	Description
CRUD	`/api/v1/chat-sessions`	Publishable snapshots of a chat’s working state
CRUD	`/api/v1/skills`	User-owned skill instruction packages
GET	`/api/v1/skills/library`	Browse published skills
POST	`/api/v1/skills/:uuid/install`	Install (copy) a published skill
GET	`/api/v1/memory/scopes`	List the caller’s memory scopes with usage + quota
GET	`/api/v1/memory`	List notes of a scope
GET/POST/PUT/DELETE	`/api/v1/memory/entry`	Read / create / upsert / delete a memory note

CRUD

/api/v1/chat-sessions

Publishable snapshots of a chat’s working state

CRUD

/api/v1/skills

User-owned skill instruction packages

GET

/api/v1/skills/library

Browse published skills

POST

/api/v1/skills/:uuid/install

Install (copy) a published skill

GET

/api/v1/memory/scopes

List the caller’s memory scopes with usage + quota

GET

/api/v1/memory

List notes of a scope

GET/POST/PUT/DELETE

/api/v1/memory/entry

Read / create / upsert / delete a memory note

Libraries

Method Path Description

Method	Path	Description
POST	`/api/v1/libraries`	Create library
GET	`/api/v1/libraries`	List libraries
GET	`/api/v1/libraries/:uuid`	Load library
POST	`/api/v1/libraries/:uuid`	Update library
DELETE	`/api/v1/libraries/:uuid`	Delete library

POST

/api/v1/libraries

Create library

GET

/api/v1/libraries

List libraries

GET

/api/v1/libraries/:uuid

Load library

POST

/api/v1/libraries/:uuid

Update library

DELETE

/api/v1/libraries/:uuid

Delete library

Collections

Method Path Description

Method	Path	Description
POST	`/api/v1/collections`	Create collection
GET	`/api/v1/collections`	List collections
GET	`/api/v1/collections/:uuid`	Load collection
POST	`/api/v1/collections/:uuid`	Update collection
DELETE	`/api/v1/collections/:uuid`	Delete collection

POST

/api/v1/collections

Create collection

GET

/api/v1/collections

List collections

GET

/api/v1/collections/:uuid

Load collection

POST

/api/v1/collections/:uuid

Update collection

DELETE

/api/v1/collections/:uuid

Delete collection

Problem Reports

/api/v1/failure-reports collects what users report as broken from the UI, joined to the server log by the trace ID of the request that failed.

Method Path Description

Method	Path	Description
`POST`	`/failure-reports`	Submit a report. Only `action` is required
`GET`	`/failure-reports`	List reports (paged)
`GET`	`/failure-reports/<uuid>`	Load one report
`GET`	`/failure-reports/<uuid>/screenshot`	Download the attached screenshot
`POST`	`/failure-reports/<uuid>`	Triage: `NEW`, `ACKNOWLEDGED` or `RESOLVED`
`DELETE`	`/failure-reports/<uuid>`	Delete a report and its screenshot

POST

/failure-reports

Submit a report. Only action is required

GET

/failure-reports

List reports (paged)

GET

/failure-reports/<uuid>

Load one report

GET

/failure-reports/<uuid>/screenshot

Download the attached screenshot

POST

/failure-reports/<uuid>

Triage: NEW, ACKNOWLEDGED or RESOLVED

DELETE

/failure-reports/<uuid>

Delete a report and its screenshot

Submitting a report requires authentication and no permission. That is deliberate: a permission to report a failure would, wherever it went ungranted, turn the one response to a breakage into a 403. Reading, triaging and deleting need READ_FAILURE_REPORT, UPDATE_FAILURE_REPORT and DELETE_FAILURE_REPORT respectively.

Only action — what was being attempted, in your own vocabulary — is mandatory. Everything describing the failing request is optional, because failures that produced no response at all are worth reporting too:

{
  "action": "createPerson",
  "traceId": "9f2c41ab7d0e4c6fa1b83e5d72c09148",
  "httpMethod": "POST",
  "path": "/api/v1/persons",
  "statusCode": 500,
  "errorMessage": "Internal Server Error",
  "route": "/detection",
  "text": "I filled in the name and pressed Create. The dialog closed but the person is not there.",
  "screenshot": "data:image/png;base64,..."
}

A screenshot may be sent as a data URL or as bare base64, up to 5 MB decoded, and must be a PNG, JPEG or WebP — the image type is determined from the bytes, not from what the request claims. An oversized image answers 413. The userAgent recorded on a report is taken from the request headers rather than the body, so it reflects what the server observed.

Further Endpoints

Additional endpoints exist for: attachments, tasks, comments, reactions, embeddings, spaces, annotations, persons, clusters, blacklists, pools (asset pools), tokens (API keys), notifications, me, health, and the pipeline node metadata under pipeline/node-descriptors and pipeline/content-types. Most follow the same CRUD pattern under /api/v1/<resource>.

Two of them deviate deliberately:

tasks/<uuid>/assignees — GET lists who a task is assigned to, POST adds users and/or groups, and the two DELETE sub-paths assignees/users/<uuid> and assignees/groups/<uuid> remove one.
notifications — the caller’s own inbox, and read-only apart from dismissal: there is no create route, because notifications are raised by the server when something happens. POST /notifications/<uuid> marks one read, POST /notifications/read-all marks them all, DELETE /notifications/<uuid> dismisses one and DELETE /notifications clears the inbox. Every route sees only your own entries; another user’s notification answers 404.

Error Responses

All errors return the HTTP status code plus a JSON body carrying a human readable message and the traceId of the request:

{
  "message": "Cannot find asset with uuid 'abc'",
  "traceId": "9f2c41ab7d0e4c6fa1b83e5d72c09148"
}

Every response — successful or not — also carries the same value in an X-Trace-Id header, and the server writes it into the log line for the failure. Quote it when reporting a problem and the exact request can be found with certainty rather than by guessing from timestamps. If your client already has an identifier of its own, send it as X-Trace-Id and it will be used, provided it is at most 64 characters of letters, digits, -, _ or .; anything else is replaced with a freshly generated one.

Code	Meaning
400	Validation error, or a malformed path/query parameter
401	Missing, expired or invalid token
403	The user lacks the permission the operation requires
404	No such resource
409	Conflict — e.g. a chat run is already active, or a memory entry already exists
500	Internal server error
503	No processor available to accept a pipeline run

Looking for something else?

All documentation Feature overview

Authentication

Base URL

OpenAPI Specification

Download the spec

Explore it

API Explorer

Listing, sorting and filtering

Filtering

Endpoint Reference

Auth

Assets

Users

Groups

Roles

Tags

Pipelines

Processors (Cortex workers)

AI Agent — Chats

AI Agent — Sessions, Skills, Memory

Libraries

Collections

Problem Reports

Further Endpoints

Error Responses