Executor API

The Docker executor exposes three HTTP endpoints:

POST /execute executes the workflow and returns JSON by default.
POST /validate validates workflow source and returns validation diagnostics.
POST /format formats workflow source and returns canonical output.

POST /execute switches to Server-Sent Events when the request includes Accept: text/event-stream.

Request body

{
  "input": {
    "message": "Write a short welcome message."
  },
  "secrets": {
    "api_key": "sk-..."
  },
  "options": {
    "cache_key": "tenant-1:conversation-42"
  },
  "workflow_source_base64": "..."
}

Field	Type	Description
`input`	object	Public workflow input. Must match the workflow `input` block.
`secrets`	object	Sensitive runtime values. Must match the workflow `secrets` block.
`options.cache_key`	string	Optional client-controlled cache key. When present and caching is enabled, matching agent outputs can be reused for later requests with the same key.
`options.use_cache`	boolean	Optional cache toggle. Defaults to `true`, but cache is only used when `options.cache_key` is present.
`workflow_source_base64`	string	Base64-encoded `.wire` source.

`/execute` response

Successful responses return the workflow output block as JSON.

{
  "result": {
    "message": "Welcome to Superwire."
  }
}

Errors use a structured JSON body.

{
  "error": {
    "kind": "validation_error",
    "message": "Unknown reference: agent.missing.summary",
    "issues": [
      {
        "path": "agent.writer.instruction",
        "message": "Unknown reference: agent.missing.summary"
      }
    ]
  }
}

`/execute` streaming response

When Accept: text/event-stream is set, /execute responds with text/event-stream. A typical stream contains lifecycle events, agent events, tool/MCP events, and a final completion event.

event: workflow_started
data: {}

event: workflow_planned
data: {"nodes":[]}

event: agent_started
data: {"agent":"reply"}

event: agent_completed
data: {"output":{"message":"Welcome to Superwire."}}

event: workflow_completed
data: {"output":{"result":{"message":"Welcome to Superwire."}}}

Exact event payloads may evolve with the executor. Treat workflow_completed as the terminal success event and workflow_failed as the terminal failure event. Streaming responses include an x-superwire-run-id response header. If the client connection drops unintentionally, reconnect with GET /execute/{run_id}/events and pass the last received SSE event id with the Last-Event-ID header. To intentionally stop backend work for a running stream, call:

curl -X POST http://localhost:13703/execute/{run_id}/cancel

Cancelling is different from disconnecting. A disconnected stream remains available for reconnection; a cancelled run is marked terminal and the executor aborts its backend task.

Security notes

Do not log raw request bodies in production because secrets contains provider and MCP credentials.
Prefer short-lived API keys or internal credentials when possible.
Keep .wire source free of hardcoded secrets.

Get Started

Core Concepts

DSL Reference

MCP & Tools

Guides

Runtime

Integrations

Request body

`/execute` response

`/execute` streaming response

Security notes

​Request body

​/execute response

​/execute streaming response

​Security notes

Request body

`/execute` response

`/execute` streaming response

Security notes