Web UI and API¶
pip install "multi-agent-swarm[server]"
swarm serve # http://127.0.0.1:8000
The UI shows an estimate before you start, then live progress per worker, and the finished report with hover-over source quotes. From there you can download the report or ask a follow-up question.
Exposing the server
By default the server listens only on 127.0.0.1 and needs no key. It refuses to listen
on a public interface until a key exists (swarm keys create) or SWARM_API_TOKEN is
set. Every job is capped at SWARM_MAX_USD_PER_JOB (default $2), whatever the request
asks for. Requests addressed to any host name other than localhost and the names in
SWARM_ALLOWED_HOSTS are rejected, which blocks DNS rebinding. For a real deployment
(HTTPS, workers, keys, monitoring), see Deploying to production.
REST API¶
Interactive docs are served at /api/docs. Send Authorization: Bearer <key> once keys or
SWARM_API_TOKEN are configured. Each key sees only its own jobs. Every response carries an
X-Request-ID header.
| Method | Path | |
|---|---|---|
| GET | /healthz, /readyz |
liveness; readiness (database reachable) |
| GET | /metrics |
Prometheus metrics (admin key or SWARM_METRICS_TOKEN) |
| GET | /api/me |
your key, limits and today's spend |
| GET | /api/estimate?preset=&search= |
cost estimate for research |
| POST | /api/jobs |
start a job (below) → {"id"} |
| POST | /api/research |
start a research job: {"question", "preset", "search", "include_domains", "exclude_domains", "recency_days", "kind", "language", "max_usd"} |
| GET | /api/jobs?limit=&offset= |
your recent jobs |
| GET | /api/jobs/{id} |
status, stats, cost, attempts, recent events |
| DELETE | /api/jobs/{id} |
cancel (queued: at once; running: at the worker's next heartbeat) |
| GET | /api/jobs/{id}/events |
live progress as Server-Sent Events; send Last-Event-ID to resume |
| GET | /api/jobs/{id}/report?format=md\|html\|json |
the result |
| POST | /api/jobs/{id}/follow-up |
{"question", "max_usd"}: a follow-up research job with the same settings |
POST /api/jobs bodies, by kind:
{"kind": "research", "question": "...", "preset": "standard", "source_kind": "news", "max_usd": 1}
{"kind": "write", "brief": "A guide to ...", "words": 2000, "sections": 6}
{"kind": "doc", "action": "translate", "text": "...", "to": "German"}
{"kind": "doc", "action": "summarize", "text": "...", "words": 300}
{"kind": "doc", "action": "rewrite", "text": "...", "style": "plain English for customers"}
Errors: 401 missing or bad key · 402 the key's daily budget would be exceeded · 404
not found (or another user's job) · 409 result not ready · 413 request too large · 422
invalid input · 429 rate limit (with Retry-After).
KEY=sws_... # from `swarm keys create`
curl -s -X POST localhost:8000/api/research -H "Authorization: Bearer $KEY" \
-H 'content-type: application/json' -d '{"question": "Do heat pumps work in cold climates?", "preset": "quick"}'
curl -sN localhost:8000/api/jobs/<id>/events -H "Authorization: Bearer $KEY" # live progress
Docker¶
docker build -t swarm .
docker run -p 8000:8000 -e ANTHROPIC_API_KEY -e TINYFISH_API_KEY -e SWARM_API_TOKEN=change-me -v swarm-data:/data swarm
For HTTPS, separate workers, Kubernetes and systemd, see Deploying to production.