REST API

swamp serve exposes a REST API alongside its WebSocket interface. This page documents the available HTTP endpoints.

Authentication

All REST API endpoints require a Bearer token in the Authorization header with admin authorization. The token is the same credential used for WebSocket authentication.

Authorization: Bearer <token>

When --auth-mode is none (deprecated), no token is required.

See Monitor Server Health for how to mint a monitoring token and grant admin access.

Server Info Endpoint

GET /

Returns a JSON object describing the server instance and its capabilities. This is the unauthenticated discovery endpoint — it does not require a Bearer token.

Response body

Response

Example

curl https://swamp.example.com/

{
  "name": "swamp-serve",
  "version": "20260818.234252.0",
  "instanceId": "a1b2c3d4",
  "remoteOnly": true
}

Health Monitoring Endpoints

GET /api/v1/health

Returns a point-in-time JSON snapshot of node health.

Response body

Response

Example

curl https://swamp.example.com/api/v1/health \
  -H "Authorization: Bearer health-monitor.secret"

GET /api/v1/health/stream

Server-Sent Events stream that pushes health snapshots at a configurable interval.

An initial snapshot is sent immediately on connect, then at the configured interval. Supports Last-Event-ID for resumable connections.

Query parameters

SSE format

id: 1
event: health
data: {"instanceId":"...","uptime":3600,...}

id: 2
event: health
data: {"instanceId":"...","uptime":3605,...}

Headers

Includes X-Accel-Buffering: no for nginx reverse proxy compatibility.

Response

Example

curl -N https://swamp.example.com/api/v1/health/stream?interval=10000 \
  -H "Authorization: Bearer health-monitor.secret"

To resume after a disconnect:

curl -N https://swamp.example.com/api/v1/health/stream \
  -H "Authorization: Bearer health-monitor.secret" \
  -H "Last-Event-ID: 42"

GET /internal/runs

Returns all run records from the SQLite-backed RunTrackerStore, including completed, failed, and cancelled runs with full metadata.

Disabled by default. Enable with any of:

• --enable-internal-api flag
• enable-internal-api: true in the serve config file
• SWAMP_ENABLE_INTERNAL_API=true environment variable

Returns 404 when not enabled.

Response

Example

curl https://swamp.example.com/internal/runs \
  -H "Authorization: Bearer health-monitor.secret"

Cancel Endpoints

Cancel a running execution via HTTP. These endpoints complement the CLI commands (swamp workflow cancel, swamp model cancel) for use by external tooling, CI/CD pipelines, or custom dashboards.

POST /api/v1/cancel/:type/:id

Cancel a single running execution by type and ID.

Response

Example

curl -X POST https://swamp.example.com/api/v1/cancel/workflow-run/3f8a2b1c \
  -H "Authorization: Bearer paul-token.secret"

POST /api/v1/cancel

Cancel all running executions, optionally filtered by type.

Request body (optional)

{ "executionType": "workflow-run" }

Response

Example

# Cancel all running executions
curl -X POST https://swamp.example.com/api/v1/cancel \
  -H "Authorization: Bearer paul-token.secret"

# Cancel only workflow runs
curl -X POST https://swamp.example.com/api/v1/cancel \
  -H "Authorization: Bearer paul-token.secret" \
  -H "Content-Type: application/json" \
  -d '{"executionType": "workflow-run"}'

Related

• Monitor Server Health — mint a monitoring token and query health endpoints
• Serve Flags — swamp serve flags, authentication modes, and credential storage
• Execution Cancellation — CLI reference for swamp workflow cancel