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.
1 · 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_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx2 · Spawn 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_…" }3 · Spawn a swarm
Up to 16 workers, run in parallel or as a sequential pipeline, 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 }4 · 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 URL5 · Call 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", "estimateSwarm": "/api/v1/swarms/estimate" }, … }