# Execute Workflow

`POST /api/workflows/{id}/execute`

## Description
Execute a deployed workflow. Synchronous by default: the response is the execution result, or the body authored by the workflow's Response block. Send X-Execution-Mode: async to queue the run and get a jobId to poll, or set stream: true for Server-Sent Events. For API-key and public callers, every top-level body field that is not a control field listed below is passed to the workflow as input.

## Parameters

- **id** (path) (required) — `string`: The unique identifier of the deployed workflow to execute.

- **X-Execution-Mode** (header) — `string`: Set to async to queue the execution and return HTTP 202 with a jobId. Async requests that also send useDraftState, selectedOutputs, stopAfterBlockId, includeFileBase64, or base64MaxBytes are rejected with HTTP 400. Async requests count against the async rate-limit bucket reported by Get Usage Limits.

- **X-Callback-Url** (header) — `string`: Async only: send it with X-Execution-Mode: async and X-Callback-Secret. When the run completes, fails, or is cancelled, SteelEngine POSTs the run's Get Job Status body to this URL (see the executionCompleted callback). A run paused for human input does not trigger it; the callback fires when the resumed run finishes. The URL must use HTTPS and resolve to a public address. It is checked when the request arrives and again before every delivery, and redirects are not followed. The request is rejected with HTTP 400 when the URL is not HTTPS, resolves to a private, loopback, or link-local address, is longer than 2048 characters, is sent without X-Callback-Secret, or is sent without X-Execution-Mode: async.

- **X-Callback-Secret** (header) — `string`: Required with X-Callback-Url, 16 to 256 characters. Each delivery is signed with it: steelengine-signature is t=<timestamp>,v1=<hex HMAC-SHA256 of "<timestamp>.<raw body>" keyed with this secret>, where <timestamp> is Unix milliseconds. SteelEngine stores the secret encrypted and never logs it. A secret outside the length limits, or one sent without X-Callback-Url, is rejected with HTTP 400.

- **X-SteelEngine-Stream-Version** (header) — `string`: Send 2 with stream: true to receive the current stream format, which ends with a done event carrying the execution result. Without it the stream ends with the legacy final (or error) event.

- **X-SteelEngine-Deployment-Version** (header) — `string`: Pin the execution to one deployment version of the workflow. Public (unauthenticated) callers cannot pin versions and receive HTTP 403.

## Request Body

Workflow input plus optional control fields. Any field not listed here is passed to the workflow as input.

```json
{
  "type": "object",
  "additionalProperties": true,
  "properties": {
    "input": {
      "description": "Workflow input. You can also send object fields at the top level of the body. The Start block unwraps a top-level input object, so both forms reach the workflow the same way. Send a string, number, boolean, or array as input."
    },
    "stream": {
      "type": "boolean",
      "description": "When true, the response is a Server-Sent Events stream (text/event-stream). Combine with selectedOutputs and X-SteelEngine-Stream-Version: 2."
    },
    "selectedOutputs": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Block outputs to stream, as blockName.field (for example agent1.content) or blockId_field. Only used with stream: true. An entry that names no existing block or field returns HTTP 400 with code INVALID_SELECTED_OUTPUT."
    },
    "useDraftState": {
      "type": "boolean",
      "description": "Execute the draft (unpublished) workflow state. Rejected with HTTP 400 for API-key callers and ignored for public callers, so REST callers always run the deployed state."
    },
    "includeFileBase64": {
      "type": "boolean",
      "default": true,
      "description": "Include base64-encoded file content in file outputs."
    },
    "base64MaxBytes": {
      "type": "integer",
      "minimum": 1,
      "description": "Cap on the base64 payload per file, in bytes."
    },
    "stopAfterBlockId": {
      "type": "string",
      "description": "Stop the execution after this block completes. Not accepted with X-Execution-Mode: async."
    }
  }
}
```

## Responses

### 200 — Synchronous execution finished successfully, or a stream was opened. The JSON body is the execution result. If the workflow ends in a Response block, the body is what that block authored, with its status code and headers. With stream: true the body is text/event-stream. It carries chunk events ({blockId, chunk, outputId, invocationId}), then a done event with the execution result, then data: [DONE].

```json
{
  "type": "object",
  "description": "Result of a synchronous workflow execution (X-SteelEngine-Response-Type: execution). A workflow that ends in a Response block returns that block's authored body, status code, and headers instead (X-SteelEngine-Response-Type: response).",
  "properties": {
    "success": {
      "type": "boolean",
      "description": "Whether the workflow executed successfully without errors.",
      "example": true
    },
    "executionId": {
      "type": "string",
      "description": "Unique identifier for this execution. Use this to query logs or cancel the execution.",
      "example": "exec_9f8e7d6c5b"
    },
    "status": {
      "type": "string",
      "enum": [
        "success",
        "failed",
        "cancelled",
        "paused"
      ],
      "description": "Execution outcome reported by the engine, when available. paused means the run is waiting for human input and is not finished.",
      "example": "success"
    },
    "output": {
      "description": "Workflow output. Structure depends on the workflow's blocks.",
      "example": {
        "result": "Hello, world!"
      }
    },
    "error": {
      "type": "string",
      "nullable": true,
      "description": "Error message when the execution failed. Absent or null on success.",
      "example": null
    },
    "metadata": {
      "type": "object",
      "description": "Execution timing metadata.",
      "properties": {
        "duration": {
          "type": "integer",
          "description": "Total execution duration in milliseconds.",
          "example": 1250
        },
        "startTime": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp when execution started.",
          "example": "2025-06-20T14:15:22Z"
        },
        "endTime": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp when execution completed.",
          "example": "2025-06-20T14:15:23Z"
        },
        "timingSemanticsVersion": {
          "type": "integer",
          "description": "Present with value 2 when duration counts active execution time only. Then activeDurationMs, waitDurationMs, and elapsedDurationMs are also present.",
          "example": 2
        },
        "activeDurationMs": {
          "type": "integer",
          "description": "Time spent executing blocks, in milliseconds."
        },
        "waitDurationMs": {
          "type": "integer",
          "description": "Time spent waiting (for example on a paused run), in milliseconds."
        },
        "elapsedDurationMs": {
          "type": "integer",
          "description": "Wall-clock time from start to end, in milliseconds."
        }
      }
    }
  }
}
```

### 202 — Accepted. With X-Execution-Mode: async the body is an async receipt. A synchronous request whose result did not arrive in time returns a pending receipt for the same run. Poll statusUrl instead of resubmitting.

```json
{
  "oneOf": [
    {
      "type": "object",
      "description": "Receipt returned (HTTP 202, X-SteelEngine-Response-Type: async) when X-Execution-Mode: async queues the execution.",
      "properties": {
        "success": {
          "type": "boolean",
          "description": "Whether the execution was successfully queued.",
          "example": true
        },
        "async": {
          "type": "boolean",
          "description": "Always true for async executions. Use this to distinguish from synchronous responses.",
          "example": true
        },
        "jobId": {
          "type": "string",
          "description": "Identifier to poll with Get Job Status. Equal to executionId.",
          "example": "exec_9f8e7d6c5b"
        },
        "executionId": {
          "type": "string",
          "description": "Unique execution identifier. Use this to query execution status or cancel.",
          "example": "exec_9f8e7d6c5b"
        },
        "message": {
          "type": "string",
          "description": "Human-readable status message.",
          "example": "Workflow execution queued"
        },
        "statusUrl": {
          "type": "string",
          "format": "uri",
          "description": "URL of Get Job Status for this execution. Returns the output once the run completes.",
          "example": "https://steelengine.com/api/jobs/exec_9f8e7d6c5b"
        }
      }
    },
    {
      "type": "object",
      "description": "Receipt returned (HTTP 202, X-SteelEngine-Response-Type: pending) when a synchronous execution was admitted but its result did not arrive in time. The run continues. Poll statusUrl instead of sending another request, which would start a second run.",
      "properties": {
        "success": {
          "type": "boolean",
          "description": "Always true: the execution was admitted.",
          "example": true
        },
        "pending": {
          "type": "boolean",
          "description": "Always true. Distinguishes this receipt from an execution result.",
          "example": true
        },
        "executionId": {
          "type": "string",
          "description": "Execution identifier. Use it as the jobId for Get Job Status.",
          "example": "exec_9f8e7d6c5b"
        },
        "message": {
          "type": "string",
          "example": "Workflow execution was admitted, but its result is not yet available"
        },
        "statusUrl": {
          "type": "string",
          "format": "uri",
          "description": "URL of Get Job Status for this execution.",
          "example": "https://steelengine.com/api/jobs/exec_9f8e7d6c5b"
        }
      }
    }
  ]
}
```

### 400 — Invalid request. Schema violations return {error: "Invalid request body", details: [{path, message}]}. An async request that carries draft or override controls is rejected. Invalid X-Callback-Url or X-Callback-Secret headers, or a callback on a synchronous request, are rejected. An API-key request that sets useDraftState, isClientSession, or workflowStateOverride is rejected. A selectedOutputs entry that names no block or field returns code INVALID_SELECTED_OUTPUT. A file input that could not be processed is also rejected.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "description": "Present for INVALID_SELECTED_OUTPUT."
    },
    "details": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### 401 — Invalid or missing API key. Ensure the X-API-Key header is set with a valid key.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Human-readable error message."
    }
  }
}
```

### 402 — The billed account has exceeded its usage limit for the current period.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    }
  }
}
```

### 403 — Access denied. The key is not authorized for this workspace or workflow. Or the request needs write-level access that the key does not have. Or a public caller tried to pin a deployment version.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    }
  }
}
```

### 404 — The requested resource was not found. Verify the ID is correct and belongs to your workspace.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Human-readable error message."
    }
  }
}
```

### 409 — Conflict: the request's workflow call chain is invalid, or the workflow's environment promotion binding rejects this execution (body includes code).

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string"
    }
  }
}
```

### 429 — Too many requests. When the caller's plan rate limit is exceeded, the body is {error} with no Retry-After header. Back off and check Get Usage Limits. When the server admission gate is at capacity, the body is {error, message, retryAfterSeconds} with Retry-After: 5.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "retryAfterSeconds": {
      "type": "integer"
    }
  }
}
```

### 500 — The execution failed (body has the ExecutionResult shape with success: false and error), or the request failed before execution started (body {error}).

```json
{
  "type": "object",
  "description": "Result of a synchronous workflow execution (X-SteelEngine-Response-Type: execution). A workflow that ends in a Response block returns that block's authored body, status code, and headers instead (X-SteelEngine-Response-Type: response).",
  "properties": {
    "success": {
      "type": "boolean",
      "description": "Whether the workflow executed successfully without errors.",
      "example": true
    },
    "executionId": {
      "type": "string",
      "description": "Unique identifier for this execution. Use this to query logs or cancel the execution.",
      "example": "exec_9f8e7d6c5b"
    },
    "status": {
      "type": "string",
      "enum": [
        "success",
        "failed",
        "cancelled",
        "paused"
      ],
      "description": "Execution outcome reported by the engine, when available. paused means the run is waiting for human input and is not finished.",
      "example": "success"
    },
    "output": {
      "description": "Workflow output. Structure depends on the workflow's blocks.",
      "example": {
        "result": "Hello, world!"
      }
    },
    "error": {
      "type": "string",
      "nullable": true,
      "description": "Error message when the execution failed. Absent or null on success.",
      "example": null
    },
    "metadata": {
      "type": "object",
      "description": "Execution timing metadata.",
      "properties": {
        "duration": {
          "type": "integer",
          "description": "Total execution duration in milliseconds.",
          "example": 1250
        },
        "startTime": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp when execution started.",
          "example": "2025-06-20T14:15:22Z"
        },
        "endTime": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp when execution completed.",
          "example": "2025-06-20T14:15:23Z"
        },
        "timingSemanticsVersion": {
          "type": "integer",
          "description": "Present with value 2 when duration counts active execution time only. Then activeDurationMs, waitDurationMs, and elapsedDurationMs are also present.",
          "example": 2
        },
        "activeDurationMs": {
          "type": "integer",
          "description": "Time spent executing blocks, in milliseconds."
        },
        "waitDurationMs": {
          "type": "integer",
          "description": "Time spent waiting (for example on a paused run), in milliseconds."
        },
        "elapsedDurationMs": {
          "type": "integer",
          "description": "Wall-clock time from start to end, in milliseconds."
        }
      }
    }
  }
}
```

### 503 — The execution was admitted but its result could not be recovered. Poll statusUrl. Do not resubmit.

```json
{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean",
      "example": false
    },
    "code": {
      "type": "string",
      "example": "RESULT_UNAVAILABLE"
    },
    "error": {
      "type": "string"
    },
    "executionId": {
      "type": "string"
    },
    "statusUrl": {
      "type": "string",
      "format": "uri"
    }
  }
}
```
