Skip to content

REST API#

swarm exposes a FastAPI-based REST API with 84 endpoints across 17 routers. Three ways to explore:

  • Narrative reference — endpoints grouped by concern (pipelines, plugins, cron, batch, permissions, auth, deployments, …)
  • OpenAPI explorer — interactive Swagger UI against live schema
  • Direct OpenAPI JSON — GET /openapi.json from any running swarm

Base URL#

  • Local dev: http://localhost:8000
  • Managed SaaS: https://api.<your-tenant>.theaisingularity.org
  • Self-hosted: whatever you configured in your Helm values

Authentication#

Every request under /api/v1/* requires a bearer token:

Authorization: Bearer <token>

Get a token via:

  1. Sign in to the dashboard via SSO
  2. Profile → API tokens → Create
  3. Copy the token (shown once)
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@local", "password": "<seeded>"}'
# → {"token": "eyJ..."}

swarm login --email admin@local --password <seeded>
# Token cached at ~/.swarm/auth.json for subsequent CLI calls

Tokens are JWT with a default 24-hour lifetime. Refresh via /api/v1/auth/refresh.

Roles + permissions#

Role Default capabilities
viewer Read-only: list pipelines, view logs, download artefacts
operator viewer + run/cancel pipelines, approve HITL gates, run batch jobs
admin operator + install plugins, manage users, modify feature flags, delete runs

Every route has a role gate — see Permissions & audit for the model. 403 on insufficient role; 401 on bad token; 404 on a resource the caller can't see (we don't leak existence to unauthorized users).

Rate limits#

Default (dev): none.

Default (production SaaS):

Route class Limit
/auth/* 20/minute per IP
GET /* 1000/minute per token
POST /* (write) 100/minute per token
POST /pipelines 20/hour per token
POST /batch/* 5/hour per token

Rate-limit headers returned on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Over-limit → 429 with Retry-After header.

Pagination#

List endpoints return:

{
  "items": [...],
  "total": 243,
  "limit": 50,
  "offset": 0
}

Paginate with ?limit=N&offset=M. Maximum limit is 1000 for most endpoints.

Cursor pagination is not supported in v0.11 but on the roadmap for v0.12.

Errors#

Standard RFC 7807 problem details:

{
  "type": "https://docs.theaisingularity.org/errors/permission-denied",
  "title": "Permission denied",
  "status": 403,
  "detail": "agent_allowlist rule for data_cleaner does not permit deploy_serving",
  "instance": "/api/v1/tools/invoke",
  "rule_source": "agent_allowlist",
  "correlation_id": "req_abc123"
}

correlation_id is logged server-side — include it in any support request.

WebSocket streams#

Live streaming via WebSocket:

Route Streams
WS /api/v1/pipelines/{run_id}/stream Agent messages, tool calls, training logs
WS /api/v1/batch/{batch_id}/stream Checkpoint progress + per-record completion
WS /api/v1/deployments/{model}/events Shadow-traffic events, drift alerts

Authenticate via ?token=<jwt> query parameter (WebSocket protocol doesn't allow Authorization header in the initial handshake).

Versioning#

  • Current API: v1 (under /api/v1/*)
  • Breaking changes: at most one new major version per 12 months (semantic versioning)
  • Deprecated endpoints: flagged via Deprecation + Sunset HTTP headers, removed after at least 6 months' notice

SDKs#

  • Python — bundled with ml_team/ package; see Python SDK
  • TypeScript — auto-generated from OpenAPI in ml_team/dashboard/src/lib/api.ts
  • Other languages — OpenAPI spec at /openapi.json; generate with openapi-generator

Next#