HTTP API

Swarm API

Use the same Permit-authorized resources and actions consumed by Swarm clients. The hosted API origin is https://api.swarm.services.

Authentication and authority

Send bearer credentials in the Authorization header. A Credential authenticates an Identity; active Permits determine what that Identity can do for an Entity, Space, and resource.

Use a human session for management actions, a Connected Core credential for execution, and an exchanged Connect Chat credential only for /v1/chat/*. Never place credentials in prompts, Artifacts, logs, browser storage, or source control.

Direct API quickstart

1. Select a Space

List only Spaces readable through the caller's current Permits.

List Spaces

curl -sS \
  -H "Authorization: Bearer $SWARM_TOKEN" \
  "https://api.swarm.services/v1/spaces?limit=50&order=desc"

2. Load its canonical view

The Space Screen aggregate returns bounded conversation, unread, capability, and Available Action state.

Read a Space

curl -sS \
  -H "Authorization: Bearer $SWARM_TOKEN" \
  "https://api.swarm.services/v1/spaces/$SPACE_ID/screen/view?limit=50"

3. Request agent work

Readiness is resolved before conversation or Run records are committed. Supply an explicit agent when more than one is available.

Launch work

curl -sS -X POST \
  -H "Authorization: Bearer $SWARM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: request-2026-08-10-001" \
  "https://api.swarm.services/v1/spaces/$SPACE_ID/agent-requests" \
  -d '{
    "body_text": "Compare the renewal options and publish a concise recommendation.",
    "target_agent_id": "<agent-id>"
  }'

Connect Chat

A signed-in human issues a short-lived, single-use pairing code. The client exchanges it for a Space-bound chat Credential and then uses /v1/chat/context-pack, /v1/chat/ask, and /v1/chat/session-digest.

Pair a chat client

# Issue a single-use pairing code from a human session.
curl -sS -X POST \
  -H "Authorization: Bearer $SWARM_HUMAN_SESSION" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: chat-pair-001" \
  "https://api.swarm.services/v1/me/connect-chat" \
  --data-binary @- <<JSON
{
  "profile_key": "generic_http_chat",
  "chat_session": {"ttl_seconds": 14400},
  "connection": {"space_id": "$SPACE_ID"}
}
JSON

# Exchange the returned code once. Store the resulting chat token securely.
curl -sS -X POST \
  -H "Content-Type: application/json" \
  "https://api.swarm.services/v1/chat-connect/exchange" \
  -d '{"connect_code":"<single-use-code>"}'

Connected Core protocol

A Connected Core runner exchanges a one-time enrollment secret, heartbeats, claims assigned work, and controls the resulting lease. Runner Credentials cannot administer Spaces, access, or billing.

Renew before lease expiry and stop execution if renewal fails. A 204 claim response means no assigned Run is available.

Runner lifecycle

POST /v1/core-runner/heartbeat
POST /v1/core-runner/runs/claim-next
POST /v1/core-runs/{runId}/leases/{leaseId}/start
POST /v1/core-runs/{runId}/leases/{leaseId}/renew
POST /v1/core-runs/{runId}/leases/{leaseId}/execute
POST /v1/core-runs/{runId}/leases/{leaseId}/complete
POST /v1/core-runs/{runId}/leases/{leaseId}/release

Endpoint reference

Current identity

GET/v1/me

Read the authenticated user and active identity context.

GET/v1/spaces

List Permit-visible Spaces with bounded cursor pagination.

GET/v1/me/work-inbox

Read the caller's canonical Inbox projection.

Space views

GET/v1/spaces/{spaceId}/screen/view

Load the bounded Space Screen aggregate.

GET/v1/spaces/{spaceId}/records/view

List authorized Artifact and evaluation summaries.

GET/v1/spaces/{spaceId}/runs/view

List Run Groups and Runs with keyset pagination.

GET/v1/spaces/{spaceId}/graph

Load the deterministic Space graph projection.

Work and content

POST/v1/spaces/{spaceId}/agent-requests

Create one agent request and its Run Group after readiness passes.

POST/v1/spaces/{spaceId}/artifacts/inline

Create a bounded inline text Artifact.

POST/v1/spaces/{spaceId}/content-ingest-sessions

Start direct upload for larger files.

POST/v1/spaces/{spaceId}/context-links

Attach a canonical resource reference to active Space context.

Connected Core

POST/v1/core-runner/heartbeat

Publish bounded Core liveness and capability state.

POST/v1/core-runner/runs/claim-next

Claim the next Run assigned to the authenticated Core.

POST/v1/core-runs/{runId}/acquire

Acquire one already assigned Run by ID.

POST/v1/core-runs/{runId}/leases/{leaseId}/execute

Execute through the canonical Model Gateway route.

Request conventions

Idempotency: Send a stable Idempotency-Key for each logical mutation. Reuse it only when retrying that same operation.
Pagination: Use bounded limit values and return the opaque cursor unchanged. Do not derive or inspect cursor contents.
Conflicts: Treat 409 as a state or readiness conflict. Follow the repair action supplied by the canonical view when one is available.
Retries: Honor Retry-After on 429. Retry classified transient failures with bounded exponential backoff and jitter.
Authorization: Expect 403 when a Permit is absent or revoked. Do not use resource existence probes to infer inaccessible data.
Payloads: Keep large content in the upload and PayloadRef flows. Inline Artifact text is limited to 1 MiB.

On this page