REST API

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

Authentication

REST API endpoints take a Bearer token in the Authorization header. The token is the same credential used for WebSocket authentication.

Authorization: Bearer <token>

The two health endpoints, GET /api/v1/health and GET /api/v1/health/stream, accept any valid server token and narrow what they return to what the token may read. Every other endpoint on this page except GET / and GET /health requires admin (admin on access:*) and answers 403 without it.

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

See Monitor Server Health for how to mint a monitoring token.

Liveness Endpoint

GET / and GET /health

A liveness check. Both paths answer the same fixed body in every auth mode and do not require a Bearer token. They report nothing about the server's schedules, webhooks or instance; read those from GET /api/v1/health.

Response body

Response

Example

curl https://swamp.example.com/health

{ "status": "ok", "version": "1" }

Health Monitoring Endpoints

GET /api/v1/health

Returns a point-in-time JSON snapshot of node health. Any valid server token may read it; see What each token sees.

Response body

What each token sees

An admin token sees the full snapshot. Any other token sees:

• activeRuns, scheduling.schedules and webhooks narrowed to the behaviors and workflows it may read (see Authorization), with principalId set to null on every run
• workers and components empty, and no retention
• instance fields (instanceId, deploymentMode, remoteOnly, ready), uptimeMs and metrics in full

One collected snapshot serves every reader for up to one second, so a snapshot can be up to a second old. After a tag edit that changes which grants match a behavior or workflow, a non-admin reader's view can take up to five seconds to follow. Grant changes apply at once.

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. Any valid server token may open a stream, and each snapshot is narrowed as described in What each token sees.

A token may hold at most 10 open streams, counted across every mint of the token name, and its principal at most 20 across all of its tokens. A stream beyond either limit is refused with 429.

Query parameters

SSE format

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

id: 2
event: health
data: {"instanceId":"...","uptimeMs":3605000,...}

The stream is a token session. When its token is revoked, rotated, or expires, or its principal loses access, the server sends a final session-ended event and closes the stream. The event has no id, and its data holds a close code and a reason:

event: session-ended
data: {"code":4003,"reason":"Session revoked: token revoked"}

A revoke on this instance ends the stream at once. A revoke on another instance takes effect at the next revalidation pass: up to 30 seconds plus the datastore poll interval. A close caused by the token itself — revoked, rotated, expired or deleted — records an auth.session.terminated audit event, as for WebSocket sessions. Consumers that ignore unknown event names are unaffected.

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 paul-token.secret"

Cancel Endpoints

Cancel a running execution via HTTP. These endpoints complement the CLI commands (swamp workflow cancel, swamp behavior 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