Skip to content

HTTP API

Earlier technical reference

This page is retained from earlier documentation and has not been fully revalidated for the public 2026.10.19 release. Its revision-specific links and examples may describe older or development behavior. Start with the current public-release user guide; do not use this page alone to select installation commands, image tags, or security settings.

The API serves BURROW's UI and external clients. It is an operator-level control surface: it can create agents, change credentials and grants, execute model/tool work, import data and delete retained content. Read authentication and trust boundaries before exposing it.

Browse by family

Reference Covers
Chat and streaming Turn submission, NDJSON events, cancellation and reconnection
Agents and setup Registry, profile documents, initial setup
Sessions and Archive Current/original history, reset/fork/archive, context, handoffs
Tasks, schedules and groups Task board, recurring jobs, group chat, legacy workbench
Settings and integrations Auth, models/OAuth, MCP grants, skills, timezone, retention, API tokens
Memory and Dreams Brains, explicit conversation recall, Tiddle, Dream controls
Files, Forge and exports Workspace editing, attachments, generated artifacts, selective export/import
Mods Distribution, lifecycle, extension routes and UI assets
Health and diagnostics Health, metrics, traces, diagnostic projections and provider usage

Contract download and provenance

Download the historical OpenAPI JSON

Property Value
Specification OpenAPI 3.1.0
Contract info.version 2026.08.25
Inventory 150 paths, 193 operations, 112 component schemas
Contract artifact source revision Backend b20376440086340e8746507ca700a4cd9e07bf96
Documented assembled baseline 2026.10.10.4, commit c15064dd177788afcdda357a5e545510f754a754
SHA-256 e91eb15cd7a4c17d3a104aee6156ff8c559ad4306ae53c7aaf90492dca4ae564

The download and route index are unchanged historical artifacts from the October 2 audit. They are not the current runtime contract. In particular, their /api/albdruck/* operations are retired and are not mounted in this build. Current memory routes use /api/brains; original recall uses /api/session/search and source expansion. See the source-backed endpoint pages above. This refresh does not claim to have regenerated the upstream OpenAPI contract.

The schema is incomplete

It has no authentication security schemes, omits seven Dream operations and the non-API OIDC/logout routes, and contains broad open-object schemas. Its Forge request/catalog and mod-catalog shapes lag implementation. Do not infer anonymous access, unsupported features or complete client compatibility from generated types alone.

Specific drift:

  • Dream settings, diary, consolidation and cycle routes are documented from the current route module
  • Mod catalog responses also carry lifecycle status, failure information, version and Archive UI contributions
  • Forge accepts mode-based selection; its source artifact still requires an explicit connection/model pair and omits the mode property
  • Music availability is catalog-dependent; it is not unconditionally false as the old schema states
  • Forge jobs can include bounded errorDetails; the old job schema omits them
  • Archive calendar uses the requested timezone, despite its old UTC-only summary

The source drift checker scans literal route comparisons. Passing it does not establish dynamic-route, HTTP-method, request or response parity. See known limitations.

Runtime explorer

Method Path Purpose
GET /api/docs Locally vendored Scalar explorer shell
GET /api/docs/{asset} Explorer assets
GET /api/openapi.json Source-tree OpenAPI document

These routes are behind the usual authentication gate. The schema endpoint reads backend/docs/openapi.json within the installed Backend source tree.

That file is absent from this public assembled snapshot. The explorer shell can load while its contract request fails. The download on this documentation site does not change that runtime behavior. The same omitted source assets can affect API-contract export categories.

Request conventions

  • Base URL is the actual service origin, commonly http://127.0.0.1:42817 for a native loopback installation
  • JSON requests use Content-Type: application/json; empty bodies are parsed as {}
  • Supply real agentId and sessionId values rather than relying on default-agent resolution in automation; default is a common session default
  • Identity in a route/query/body selects an application object. It is not a separate authentication principal or tenant boundary
  • Most JSON routes return an ok field, but this is not universal; some memory and byte-download endpoints differ
  • Check both HTTP status and the endpoint's application outcome. HTTP 200, a run ID or a queued response alone does not prove successful execution
  • Pagination conventions differ: opaque cursor, transcript before/from/to, or simple limit. Follow each endpoint and do not manufacture cursors
  • There is no general HTTP API version prefix, universal idempotency header or WebSocket protocol in this surface. Forge has a body-level idempotency contract

Invalid JSON returns 400 invalid_json. Selected route boundaries reject non-object bodies and required fields; the server does not apply a universal OpenAPI request validator. JSON ingestion is bounded before parsing; route families can impose stricter limits. Browser-origin and JSON content-type checks apply to mutations. These checks do not replace authentication or deployment-level request limits. See trust boundaries.

Authentication for clients

Use the configured Basic, trusted-proxy or OIDC session flow for the full API. Scoped Bearer tokens currently support only diagnostics:read and an exact GET allowlist; they cannot administer settings or run chat. A rejected Bearer token returns 403 rather than falling back to interactive authentication.

GET /health is public and contains runtime metadata. /api/health is gated. GET /api/auth/session reports OIDC-session presence, not a general Basic/proxy introspection result. See the complete authentication reference.

Minimal read example

For a loopback development service with authentication explicitly disabled:

curl --fail-with-body http://127.0.0.1:42817/api/agents

For Basic authentication, add --user "$BURROW_USERNAME" and let curl prompt for the password. Do not embed passwords or tokens in command history, URLs, source files or documentation examples. Use your deployment's configured authentication for all other examples.