Skip to main content

REST API

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

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.

Parameter Value Description
:type workflow-run or method-run The execution type to cancel.
:id string The execution's run ID.

Authentication

Requires a Bearer token in the Authorization header — the same token used for WebSocket authentication. When --auth-mode is none (deprecated), no token is required.

Authorization: Bearer <token>

Response

Status Body Condition
200 { "status": "cancelled", "executionType": "...", "executionId": "..." } The execution was found and cancelled.
401 "Unauthorized: token required" or "Unauthorized" Missing or invalid Bearer token.
404 { "status": "not_found", "message": "..." } No active execution with the given type/ID.

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)

Field Type Description
executionType string Filter by type: workflow-run or method-run. Omit to cancel all. 
{ "executionType": "workflow-run" }

Authentication

Same Bearer token requirement as the single-cancel endpoint.

Response

Status Body Condition
200 { "status": "cancelled", "count": <number> } Returns the count of cancelled runs.
400 { "status": "error", "message": "executionType must be 'workflow-run' or 'method-run'" } Invalid executionType value.
401 "Unauthorized: token required" or "Unauthorized" Missing or invalid Bearer token.

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"}'
← PreviousDaemon ManagementNext →Notifications