> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superwire.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Executor API

> HTTP contract for /execute, /validate, and /format.

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

```json theme={"languages":{"custom":["/languages/wire.tmLanguage.json"]}}
{
  "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.

```json theme={"languages":{"custom":["/languages/wire.tmLanguage.json"]}}
{
  "result": {
    "message": "Welcome to Superwire."
  }
}
```

Errors use a structured JSON body.

```json theme={"languages":{"custom":["/languages/wire.tmLanguage.json"]}}
{
  "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.

```text theme={"languages":{"custom":["/languages/wire.tmLanguage.json"]}}
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:

```bash theme={"languages":{"custom":["/languages/wire.tmLanguage.json"]}}
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.