API Reference

Every feature in the Aura Workshop desktop app is also reachable over HTTP. The embedded web server exposes 258 REST + WebSocket endpoints plus a drop-in OpenAI/Anthropic-compatible gateway — an identical surface in both desktop and headless daemon deployments. This reference is verified route-by-route against Aura Workshop 1.36.2.

The surface

The axum web server binds port 18800 and composes its router from six sub-routers. Every bare path in the tables below (e.g. /settings, /tasks) is served under the /api nest — the real URL is /api/settings, /api/tasks. Paths shown with an explicit leading segment (/auth/*, /oauth/callback, /ws/*, /charts/*, /media/*, /v1/*, /acp/*, /.well-known/*, and the literal /api/health + /api/heartbeat/incoming) are already fully qualified.

Totals: 247 application routes (routes.rs) + 11 ACP inbound routes (acp_routes.rs) = 258 REST + WebSocket endpoints. The gateway (/v1/*) and the two /ws/* sockets are counted within the 247. The desktop app additionally calls 365 Tauri commands in-process — see Tauri commands.

Authentication model

The middleware runs on every request and sorts routes into four buckets:

1. Always public (auth bypassed): /auth/*, /api/health, /api/heartbeat*, /ws/*, /api/image-proxy, /charts/*, /acp/ping, /.well-known/*, plus the public ACP manifest GETs /acp/agents and /acp/agents/*.
2. Non-API static: any path not starting with /api/, /v1/, or /acp/ passes through (the SPA, /oauth/callback, /media/*). The login page renders client-side.
3. Guarded: everything under /api/, /v1/, and /acp/* (except the public ACP GETs) requires a matching Authorization: Bearer token (constant-time compared) or a valid JWT session cookie.
4. Strict remote mode: when AURA_REMOTE_DEPLOYMENT=true or AURA_VIEWER_MODE=true, guarded routes are rejected with 401 even if no token/password is configured. Only local Tauri-app usage (neither env var set) keeps the "allow all on localhost" fallback.

The bearer token is sourced from the AURA_WEB_TOKEN env var (preferred) or settings.web_server_token in the DB. Password auth via POST /auth/login issues a JWT cookie as an alternative.

# Authenticated request
curl -H "Authorization: Bearer $AURA_WEB_TOKEN" \
  http://localhost:18800/api/tasks

REST handlers return a JSON error body with an appropriate HTTP status (400 / 401 / 404 / 429 / 500). /api/health and /acp/ping report the versioned identity aura-workshop/1.36.2.

Tasks

Agent tasks — the durable unit of work. For simple tool-less chat see Conversations.

# Create a task
curl -X POST -H "Authorization: Bearer $AURA_WEB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Prime generator","description":"Write a Python script that prints primes","task_mode":"execute","auto_run":true}' \
  http://localhost:18800/api/tasks

Chat & agent (SSE)

These endpoints stream Content-Type: text/event-stream. Events include text, thinking, tool_start, tool_end, node_*, done, and error — see SSE event shapes.

# Stream a one-shot agent run
curl -N -X POST -H "Authorization: Bearer $AURA_WEB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"What is the capital of France?"}' \
  http://localhost:18800/api/agent/run

# event: text
# data: {"content":"The capital of France is Paris."}
# event: done
# data: {"task_id":"task_abc123","status":"completed"}

Conversations & messages

Simple chat conversations, no tool access.

Platform & settings

Memory & knowledge

File-based markdown memory plus the memory_facts index with hybrid recall and distillation, alongside three knowledge stores. See Memory & Knowledge for the concepts.

Native memory

Embeddings for hybrid recall come from a user-configured external endpoint (Settings → Memory) — there is no bundled embedding server.

Wiki

Markdown knowledge pages (wiki_pages + FTS), injection-scanned.

Code graph

Heuristic symbol + import index (code_symbols + FTS, code_edges) over Rust/TS/JS/Py/Go.

Concept graph

LLM triple-extraction knowledge graph (concept_nodes + concept_edges).

Skills & role skills

Role skills are markdown system-prompt personas — a separate system from skills.

Design systems (markdown design guides with live previews):

Automation

Schedules, chat listeners, webhooks, and slash commands. See Automation & Workflows for the concepts.

Schedules

schedule_type: once | hourly | daily | weekly | cron. duration_type: once | repeat_until | forever. background_deploy=true + target_agent_id forwards execution to a remote agent.

Listeners

IM bindings tie a (listener, channel, thread) to a task for conversational continuity:

Webhooks

Slash commands

handler_type: agent_task | workflow | skill | builtin.

Workflows & teams

Teams — role bundles run as a nested workflow:

Multi-agent orchestration (cloud + peer participants via the debate/plan/goal engines):

Autonomous loops

Self-paced agent loops (task_mode="autonomous"), backed by the autonomous_loops table plus a scheduled_tasks arming row per loop. See Autonomous Agents.

MCP & plugins

Plugins — CLI tools that register as MCP servers via a manifest (plugins table):

Render helpers (diagrams / charts to files served under /charts/):

Models & providers

Custom providers & credentials:

Billing & routing

License:

Dependencies (downloadable runtime deps — Node, Python, browser-act, etc.):

OAuth & integrations

Direct OAuth (our client IDs, PKCE flow) — see Integrations.

Composio (cloud OAuth, ~100 toolkits):

Cloud storage connectors:

ACP peers

Local admin of the acp_agents table (discovered + manual peers). Discovered peers default enabled=0 until you admit them. Peer discovery uses UDP broadcast on port 18802.

ACP inbound REST surface

The routes peers call into our agent (acp_routes.rs). /acp/ping and the /acp/agents GETs are public; everything else requires Bearer auth. {*name} captures slashes so slash-namespaced agents (e.g. aura-workshop/cursor) resolve.

Files, projects & ops

Files & voice

Projects

Import / export

Data management

Viewer (remote deployment dashboard)

Health, media & metrics

WebSocket endpoints

Both live outside the /api nest and bypass auth in the middleware.

Gateway (OpenAI/Anthropic-compatible)

The /v1/* gateway makes Aura a drop-in LLM endpoint. Each request is parsed, the provider is resolved from the model name, the key + base URL are looked up from settings, and the request is proxied upstream — streaming responses are re-emitted in the client's expected format, with spend limits, fallback, and usage logging applied automatically. Point any OpenAI or Anthropic SDK at your Aura instance to centralize LLM access, cost control, and audit through a single endpoint. These routes are guarded (auth required).

# Use Aura as an OpenAI-compatible endpoint
curl -X POST http://localhost:18800/v1/chat/completions \
  -H "Authorization: Bearer $AURA_WEB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role":"user","content":"Hello!"}],
    "stream": true
  }'

Passing "model": "auto" lets Aura Routing pick the tier — see Models & Providers.

SSE event shapes

Streaming endpoints (/chat/*, /agent/run, /tasks/{id}/run, /tasks/{id}/resume, /events, /viewer/events, /acp/runs/{id}/events) emit named event: lines with JSON payloads.

Multi-agent runs dual-emit every event on both the SSE broadcaster (/api/events) and the Tauri window, namespaced multi_agent.plan.* / acp.debate.*. Every event carries a monotonic _seq so SSE reconnects can de-dup.

Tauri commands

The desktop app calls 365 #[command] functions via Tauri invoke() instead of HTTP, registered in a single generate_handler! macro. Commands and REST routes are two front doors onto the same shared business logic — browser mode maps each command name onto its REST equivalent, so any command that isn't mirrored as a REST route breaks daemon/browser deployments. They cover the same domains as the tables above: tasks, chat & agent, goals/plan/autonomous, settings, skills, MCP/plugins, automation, memory & knowledge, providers/models, OAuth & Composio, ACP + multi-agent, billing/licensing, remote deployment, voice/files, and more.

Rate limits & guards