Skip to main content
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": "..."
}
FieldTypeDescription
inputobjectPublic workflow input. Must match the workflow input block.
secretsobjectSensitive runtime values. Must match the workflow secrets block.
options.cache_keystringOptional 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_cachebooleanOptional cache toggle. Defaults to true, but cache is only used when options.cache_key is present.
workflow_source_base64stringBase64-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.