On this page

Loom

REST API

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

Generating a typed client from the spec is a one-liner with any OpenAPI generator:

openapi-generator-cli generate \
  -i https://metaloom.io/docs/examples/openapi.yaml \
  -g python -o ./loom-client
Tip
 Loom also ships a maintained, typed Java client — see Java Client. Prefer it over a generated one when you work in Java.

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.

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

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

Assets

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

DELETE

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

Remove tag from asset

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

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

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

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

Tags

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

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

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

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

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

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

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

Further Endpoints

Additional endpoints exist for: attachments, tasks, comments, reactions, embeddings, spaces, annotations, persons, clusters, blacklists, pools (asset pools), tokens (API keys), 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>.

Error Responses

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

{
  "message": "Cannot find asset with uuid 'abc'"
}
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