API Reference

The Swarmd API is organized around REST and JSON-RPC protocols. All requests are routed through the gateway at https://api.dev.swarmd.ai.

Base URL

https://api.dev.swarmd.ai

Services

Service	Path Prefix	Description
Relay	`/relay`	Conversations, A2A and MCP messaging, task execution, policy groups and bindings, HITL approvals
Registry	`/registry`	Agents, MCP servers, channels, subscriptions, LLM providers and gateways, marketplace, kill switches
Tenant Auth	`/tenant-auth`	Authentication, users, groups, identity providers
Audit	`/audit`	Audit events, traces, monitors and alerts, dashboards
A2A Payments	`/a2a-payments`	x402 protocol payments
LLM runtime	`/llm`	OpenAI-compatible gateway calls, e.g. `/llm/v1/{gatewayId}/chat/completions`

Authentication

Almost every endpoint requires a Bearer token:

Authorization: Bearer <token>

There are two ways to obtain one, depending on who is calling:

Caller	Token source
A logged-in user	`POST /tenant-auth/v1/login`, refreshed with `POST /tenant-auth/v1/refresh`
A channel or agent	OAuth2 client credentials against Keycloak, using the client ID and secret issued when the channel or agent was created

A small set of Tenant Auth endpoints are deliberately unauthenticated because they are how a session starts: POST /tenant-auth/v1/tenants, /login, /refresh, /verify-email, /resend-verification, /forgot-password, /reset-password, /accept-invite, /sso/callback, GET /tenant-auth/v1/login/discover and GET /tenant-auth/v1/permissions.

Endpoints are additionally gated by role. The generated reference lists the required roles for each operation, in the form ENTITY:PERMISSION — for example AGENT_CONVERSATIONS:WRITE or AUDIT:READ.

​API Reference

​Base URL

​Services

​Authentication

API Reference

Base URL

Services

Authentication