Execute Workflow
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.
/api/workflows/{id}/executeAuthorization
apiKey Your SteelEngine API key (personal, workspace, or organization). Create personal and workspace keys under Settings > API Keys. Create organization keys under Organization Settings > API Keys.
In: header
Path Parameters
The unique identifier of the deployed workflow to execute.
Header Parameters
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.
Value in
- "async"
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.
urilength <= 2048Required with X-Callback-Url, 16 to 256 characters. Each delivery is signed with it: steelengine-signature is t=,v1=<hex HMAC-SHA256 of "." keyed with this secret>, where 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.
16 <= length <= 256Send 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.
Value in
- "2"
Pin the execution to one deployment version of the workflow. Public (unauthenticated) callers cannot pin versions and receive HTTP 403.
length <= 255Request Body
application/json
Workflow input plus optional control fields. Any field not listed here is passed to the workflow as input.
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
Callbacks
curl -X POST "https://example.com/api/workflows/string/execute" \ -H "Content-Type: application/json" \ -d '{ "query": "What is the weather in Tokyo?" }'{ "success": true, "executionId": "exec_abc123", "output": { "content": "The weather in Tokyo is sunny, 22°C." }, "metadata": { "startTime": "2026-01-15T10:30:00Z", "endTime": "2026-01-15T10:30:01Z", "duration": 1250 }}