Documentation
Quickstart.
Swarms is a REST API. Your agent points at it, spawns a workforce, and gets metered, auditable results back. Everything runs headless — no browser required.
Get an API key
Create a key in the dashboard under Settings → API Keys. Keys are shown once, hashed at rest, and can carry their own spending budget.
Authorization: Bearer hk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxSpawn a single agent
One agent, one task, a dollar budget that acts as a hard ceiling.
curl https://api.swarms.dev/api/v1/spawn \
-H "Authorization: Bearer $SWARMS_KEY" \
-H "Content-Type: application/json" \
-d '{
"task": "Summarize the attached transcript into 5 bullets",
"budgetUsd": 0.25
}'
# → 201 { "jobId": "job_…", "status": "queued", "executionUrl": "/api/v1/jobs/job_…" }Spawn a swarm
Up to 16 workers, run in parallel, as a sequential pipeline, or as a DAG of named steps with dependencies — optionally aggregated into a single merged result. Returns immediately with a run id.
curl https://api.swarms.dev/api/v1/swarms \
-H "Authorization: Bearer $SWARMS_KEY" \
-H "Content-Type: application/json" \
-d '{
"tasks": ["Research", "Draft", "Fact-check"],
"objective": "Launch brief",
"aggregatorTask": "Merge into one brief",
"budgetUsd": 3.00
}'
# → 202 { "swarmRunId": "swr_…", "status": "queued", "workerCount": 3 }Get the result
Poll the run, stream progress over SSE, or receive a signed webhook when it reaches a terminal state — each with a full cost breakdown.
GET /api/v1/swarms/swr_… # snapshot + merged output
GET /api/v1/swarms/swr_…/stream # server-sent events, live
POST /api/v1/webhooks # register a signed callback URLSimulate, schedule, and evaluate
The same execution spine — budgets, ledger, audit trail — runs three more primitives: a CrewAI persona crew, a cron-scheduled recurring run, and an LLM-judge quality gate.
POST /api/v1/simulations # spawn a crew of personas in one sandbox
POST /api/v1/schedules # run any job/swarm/simulation on a cron
POST /api/v1/evaluations # score a run's output against a rubricCall it from an MCP agent
The API is self-describing at GET /api/v1 — an agent that knows only the base URL can discover every endpoint, the skill catalog, and the auth scheme, then navigate from there. No UI, no human in the loop.
GET https://api.swarms.dev/api/v1
# → { "api": "swarms", "links": { "spawn": "/api/v1/spawn",
# "swarms": "/api/v1/swarms", "simulations": "/api/v1/simulations", … } }