Arbiter HTTP API

Arbiter exposes its multi-agent orchestrator as an HTTP + Server-Sent Events API. One POST/v1/orchestrate drives the full agentic loop — master agent turns, delegated and parallel sub-agent calls, tool invocations, generated files — and streams the whole thing back as SSE events.

Billing — eligibility checks, rate cards, caps, invoicing — is delegated to an external billing service when ARBITER_BILLING_URL is set. The runtime exchanges every bearer for a workspace_id via POST/v1/runtime/auth/validate, pre-flights against POST/v1/runtime/quota/check, and posts post-turn telemetry to POST/v1/runtime/usage/record. Operators wanting a commercial deployment must implement that protocol against a service of their choosing — arbiter ships no reference implementation under this repository. With the env var unset, the runtime acts as a thin pass-through using the operator-supplied provider keys, with no eligibility checks.

Start with arbiter --api --port 8080. The default bind is 127.0.0.1; production deployments should put TLS termination, DDoS protection, and rate limiting in a reverse proxy (nginx, caddy, cloudflare) in front of the process.

Each endpoint page below uses the same template: Function, Request, Response, Failure modes, See also.

Concepts

• Writ — the slash-command DSL agents emit inline
• Tenants
• Authentication
• Fleet streaming
• SSE event catalog
• Advisor
• Structured memory
• Artifacts
• MCP servers
• A2A protocol
• Web search
• Data model
• Operational notes
• Scheduler
• Todos
• Lessons (self-reflection)
• Durable in-flight execution

Endpoints

Top-level

• GET/v1/health
• GET/v1/metrics
• GET/v1/models
• POST/v1/orchestrate
• POST/v1/requests/:id/cancel
• GET/v1/requests
• GET/v1/requests/:id
• GET/v1/requests/:id/events

Agents

• GET/v1/agents
• POST/v1/agents
• GET/v1/agents/:id
• PATCH/v1/agents/:id
• DELETE/v1/agents/:id
• POST/v1/agents/:id/chat

Conversations

• POST/v1/conversations
• GET/v1/conversations
• GET/v1/conversations/:id
• PATCH/v1/conversations/:id
• DELETE/v1/conversations/:id
• GET/v1/conversations/:id/messages
• POST/v1/conversations/:id/messages

Memory (file scratchpads)

• GET/v1/memory
• GET/v1/memory/:agent_id

Memory (structured graph)

• POST/v1/memory/entries
• GET/v1/memory/entries
• GET/v1/memory/entries/:id
• PATCH/v1/memory/entries/:id
• DELETE/v1/memory/entries/:id
• POST/v1/memory/entries/:id/invalidate
• POST/v1/memory/relations
• GET/v1/memory/relations
• DELETE/v1/memory/relations/:id
• GET/v1/memory/graph

Artifacts

• POST/v1/conversations/:id/artifacts
• GET/v1/conversations/:id/artifacts
• GET/v1/conversations/:id/artifacts/:aid
• GET/v1/conversations/:id/artifacts/:aid/raw
• DELETE/v1/conversations/:id/artifacts/:aid
• GET/v1/artifacts
• GET/v1/artifacts/:aid
• GET/v1/artifacts/:aid/raw
• DELETE/v1/artifacts/:aid

Todos

• POST/v1/todos
• GET/v1/todos
• GET/v1/todos/:id
• PATCH/v1/todos/:id
• DELETE/v1/todos/:id

Lessons (self-reflection)

• POST/v1/lessons
• GET/v1/lessons
• GET/v1/lessons/:id
• PATCH/v1/lessons/:id
• DELETE/v1/lessons/:id

Schedules + runs + notifications

• POST/v1/schedules
• GET/v1/schedules
• GET/v1/schedules/:id
• PATCH/v1/schedules/:id
• DELETE/v1/schedules/:id
• GET/v1/schedules/:id/runs
• GET/v1/runs
• GET/v1/runs/:id
• GET/v1/notifications/stream

A2A protocol

• GET/.well-known/agent-card.json
• GET/v1/a2a/agents/:id/agent-card.json
• POST/v1/a2a/agents/:id

Admin

• GET/v1/admin/tenants
• POST/v1/admin/tenants
• GET/v1/admin/tenants/:id
• PATCH/v1/admin/tenants/:id
• GET/v1/admin/audit

Usage ledger, rate cards, caps, and invoices live in the operator's billing service, not here.

Versioning

All routes are prefixed /v1/. Breaking changes will land at /v2/; additive changes (new fields on responses, new optional query params) ship under /v1/ with a note in this index.