HTTP API - swarmlord

Live OpenAPI

The canonical, always-current schema.

Every endpoint is at https://api.swarmlord.ai and requires a bearer token:

Authorization: Bearer slsk_...

Mint tokens with swarmlord login (CLI) or the dashboard.

Deploy a bundle

POST /deploy
Content-Type: application/jsonc

{ "name": "hello-agent", "model": {...}, "instructions": "..." }

Returns { ok: true, agentId, warnings } or { ok: false, errors }.

Create a session

POST /agent/<name>/session
Content-Type: application/json

{}

Returns { id }.

Send a message (streaming)

POST /session/<id>
Content-Type: application/json
Accept: text/event-stream

{ "parts": [{ "type": "text", "text": "Hi" }] }

Response is an SSE stream of events for this turn.

Send a message (async)

POST /session/<id>?async=1

{ "parts": [{ "type": "text", "text": "Long task..." }] }

Returns 202 { messageId } immediately. Events are persisted to the session for later replay.

GET /session/<id>/events
Accept: text/event-stream
Last-Event-ID: 5

Replays events with seq > 5, then streams new ones.

Fork

POST /session/<id>/fork

Snapshots state into a new session id. Returns { id }.

Abort

POST /session/<id>/abort

Cancels the in-flight model call.

Revert / regenerate

POST /session/<id>/revert      { "messageId": "..." }
POST /session/<id>/regenerate  { "assistantMessageId": "..." }

Upload an attachment

POST /session/<id>/upload
Content-Type: multipart/form-data

[email protected]

Stores the file and returns { url } — an r2://media/... reference you can include in a later message or download.

Download an attachment / artifact

GET /session/<id>/media?key=media/<uuid>-data.csv

Streams the stored object with its original Content-Type. key is the path from the r2:// ref and is scoped to the media/ prefix.

Keys

GET    /key
POST   /key
DELETE /key/<id>

Secrets

GET    /secret              # keys only, never values
PUT    /secret/<key>        { "value": "..." }
DELETE /secret/<key>

Webhooks

POST /webhook
{ "url": "https://example.com/hook", "events": ["session.completed"] }

Each delivery includes x-swarmlord-signature: <hmac-sha256> and x-swarmlord-timestamp headers. Verify with verifyWebhook() from swarmlord/webhooks.

Triggers

Webhook-triggered agents are reachable at:

POST /trigger/<userId>/<agentId>/<suffix>

The request body becomes the initial user message. No auth header — the URL is the secret.

Errors

Status	Meaning
400	Validation error.
401	Missing or invalid token.
403	Token valid but lacks access.
404	Agent or session not found.
429	Rate-limited. Retry after `Retry-After`.
5xx	Server error. Response body holds a trace id.

Health

GET /auth/health

Returns 200 { "ok": true } if the platform is reachable.

Live OpenAPI

​Deploy a bundle

​Create a session

​Send a message (streaming)

​Send a message (async)

​Subscribe / replay

​Fork

​Abort

​Revert / regenerate

​Upload an attachment

​Download an attachment / artifact

​Keys

​Secrets

​Webhooks

​Triggers

​Errors

​Health