HTTP API

The REST API is how a service, script or the dashboard talks to Long Tail over HTTP. Use it to resolve escalations, start workflows, manage roles and users, and read operational data.

Base URL

REST endpoints live under /api on the Long Tail server. The MCP endpoint is served at /mcp. Examples on these pages use https://lt.acme.dev. Bodies are JSON: send Content-Type: application/json on POST, PUT and PATCH.

export LT_URL=https://lt.acme.dev

Authentication

Send a token in the Authorization header on every request:

Authorization: Bearer <token>

Two kinds of token work in that header.

Token	How to get it	Lifetime
User JWT	`POST /api/auth/login` with a username and password	24 hours
Bot API key (`lt_bot_...`)	`POST /api/bot-accounts/:id/api-keys` on a service account	Until revoked, or until its optional `expires_at`

curl -s $LT_URL/api/auth/login \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"username": "superadmin", "password": "'"$LT_PASSWORD"'"}'

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "a1b2c3d4-...",
    "external_id": "superadmin",
    "display_name": "Super Admin",
    "roles": [{ "role": "superadmin", "type": "superadmin" }]
  }
}

export LT_TOKEN=eyJhbGciOiJIUzI1NiIs...
curl -s $LT_URL/api/escalations/available -H "Authorization: Bearer $LT_TOKEN"

A bot API key authenticates through the same middleware as a person, and RBAC checks use the service account’s roles. Embedded deployments can also authenticate through SSO, and a custom auth adapter can replace the JWT check; see Auth and SSO.

GET /api/settings, GET /api/settings/custom.css and POST /api/auth/login are public. Everything else requires a token.

Errors

A non-2xx response carries a JSON body with an error message:

{ "error": "Escalation not found" }

Status	Meaning
`400`	The request is missing a required field or has an invalid value.
`401`	No token, an invalid token, or an expired one (`"Token expired"`).
`403`	The caller lacks the access the route needs, for example `"Forbidden: admin access required"`.
`404`	The resource does not exist, or the caller’s scope hides it.
`409`	A conflict, such as a duplicate name or a claim held by someone else.
`422`	The payload failed the role’s schema.

Schema validation (422)

When a role enforces its resolver schema, every resolve route rejects a non-conforming payload with one canonical body. Each entry in violations names a field and a message.

{
  "error": "resolverPayload failed schema validation (2 violations)",
  "code": "schema_validation",
  "violations": [
    { "field": "contact_email", "message": "Enter a valid email address" },
    { "field": "tier", "message": "Must be one of: free, starter, professional, enterprise" }
  ],
  "role": "intake-reviewer",
  "schemaVersion": 3
}

Bulk resolve routes tag each violation with its escalationId. See Schema enforcement.

Access and scopes

Routes check access at three levels.

Level	Who has it
Authenticated	Any valid token.
Builder access	Superadmin or the `engineer` role. Needed to deploy workflows, register topics, manage MCP servers and namespaces.
Admin access	`admin` or `superadmin`. Needed for users, DBA and maintenance changes.

Escalation routes also apply a work-surface scope. A member grant on a role carries two dials:

Dial	Values	Governs
`read_scope`	`self`, `all`	Which escalations the member sees: list, get, find by metadata, stats.
`write_scope`	`none`, `self`, `all`	Which escalations the member may act on: claim, resolve, cancel.

self means escalations assigned to the member. all means the whole role queue. Both default to all, and write_scope can never exceed read_scope. Releasing, escalating and assigning by query require write_scope=all. admin and superadmin ignore scope and act on the whole queue. See Work-surface scope.

Pagination

List routes page with limit and offset and return the page with a total:

curl -s "$LT_URL/api/escalations?status=pending&limit=50&offset=100" \
  -H "Authorization: Bearer $LT_TOKEN"

{ "escalations": [ ... ], "total": 412 }

Default limits vary by route (50 for escalations and tasks, 20 for pipeline runs); each page lists its own. Two routes use cursors instead: the escalation timeline takes before (an ISO instant), and the file browser returns a nextToken to pass back as continuationToken.

Areas

Area	What it covers	Endpoints
Escalations	List, claim, resolve, cancel and bulk-manage escalations; faceted search, batch items, analytics.	48
Agents	Agent automations: identity, goals, event subscriptions, schedules.	9
Control plane	Admin-only app discovery, worker health, throttling and stream statistics.	6
DBA	On-demand pruning and migration deploys.	2
Exports	Workflow state and typed execution history.	5
File browser	Browse, preview, download, share and delete files in storage.	5
Knowledge	The domain-scoped key-value knowledge store.	8
Maintenance	The automated cleanup schedule.	2
MCP endpoint	The streamable-http MCP endpoint that external MCP clients connect to.	1
MCP servers	MCP server registrations, connections and tool calls.	10
Namespaces	Namespaces for MCP process servers.	2
Personas	Personas, their roles and user assignments.	11
Pipelines	Pipeline runs, execution detail and interrupts.	4
Roles	Roles, schemas, members, scope and escalation chains.	15
Service accounts	Bot accounts and their API keys.	11
Settings	Dashboard configuration, custom CSS and NATS credentials.	3
Tasks	Task records and processes.	6
Topics	The event topic catalog and test publishing.	6
Users	Users, their properties and the caller’s own preferences.	9
Workflows	Discover, configure, invoke, observe and terminate workflows.	19
YAML workflows	Create, deploy, activate and invoke YAML workflows.	14

ConditionalThe wait that creates the escalations these routes resolve.

Schema enforcementHow resolve routes validate payloads and report violations.

IdentityUsers, roles and service accounts.

SDK referenceThe typed client for the same routes.