Execute workflow

Run the active deployment, or set run.source: "manual" to run the saved draft. Deployed execution requires workspace read access and OAuth api:write scope or an API key; public deployments also allow anonymous synchronous or streamed runs. Manual runs require personal-key or OAuth write access and cannot be async.

Use async: true for a queue receipt, or stream: true for SSE. For a synchronous run with both flags false, send Accept: application/x-ndjson for heartbeat frames and a final frame containing data. Timeouts return 200 with status: "failed" and error.code: "TIMEOUT"; inspect run status. See Streaming for event formats. Input descriptions specify compatible modes; invalid combinations return 400.

Supply X-Run-Id to prevent duplicate execution. Reuse returns 409, without replaying results. A 503 with error.details.code: "ASYNC_ENQUEUE_AMBIGUOUS" omits Retry-After because the run may already have started. Reconcile using the returned run ID; do not start another run with a new or omitted ID.

OAuth scope: api:write.

POST/api/v2/workflows/{workflowId}/execute

Authorization

X-API-Key<token>

Send a personal or workspace API key in X-API-Key. See key types and access; operations that reject workspace keys say so in their description.

In: header

Request examples use an API key. For OAuth, replace the X-API-Key header with Authorization: Bearer YOUR_ACCESS_TOKEN.

curl -X POST "https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/execute" \  -H "X-API-Key: YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "input": {      "ticketId": "ticket_123"    }  }'

const body = JSON.stringify({  "input": {    "ticketId": "ticket_123"  }})fetch("https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/execute", {  method: "POST",  headers: {    "Content-Type": "application/json",    "X-API-Key": "YOUR_API_KEY"  },  body})

package mainimport (  "fmt"  "net/http"  "io/ioutil"  "strings")func main() {  url := "https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/execute"  body := strings.NewReader(`{    "input": {      "ticketId": "ticket_123"    }  }`)  req, _ := http.NewRequest("POST", url, body)  req.Header.Add("X-API-Key", "YOUR_API_KEY")  req.Header.Add("Content-Type", "application/json")  res, _ := http.DefaultClient.Do(req)  defer res.Body.Close()  body, _ := ioutil.ReadAll(res.Body)  fmt.Println(res)  fmt.Println(string(body))}

import requestsurl = "https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/execute"body = """{  "input": {    "ticketId": "ticket_123"  }}"""response = requests.request("POST", url, data = body, headers = {  "Content-Type": "application/json",   "X-API-Key": "YOUR_API_KEY"})print(response.text)

import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import java.net.http.HttpResponse.BodyHandlers;import java.time.Duration;import java.net.http.HttpRequest.BodyPublishers;var body = BodyPublishers.ofString("""{  "input": {    "ticketId": "ticket_123"  }}""");HttpClient client = HttpClient.newBuilder()  .connectTimeout(Duration.ofSeconds(10))  .build();HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()  .uri(URI.create("https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/execute"))  .header("X-API-Key", "YOUR_API_KEY")  .header("Content-Type", "application/json")  .POST(body)  .build();try {  HttpResponse<String> response = client.send(requestBuilder.build(), BodyHandlers.ofString());  System.out.println("Status code: " + response.statusCode());  System.out.println("Response body: " + response.body());} catch (Exception e) {  e.printStackTrace();}

using System;using System.Net.Http;using System.Text;var body = new StringContent("""{  "input": {    "ticketId": "ticket_123"  }}""", Encoding.UTF8, "application/json");var client = new HttpClient();client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY");var response = await client.PostAsync("https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/execute", body);var responseBody = await response.Content.ReadAsStringAsync();

{
  "data": {
    "runId": "run_8f14e45f-ceea-467f-a",
    "workflowId": "3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36",
    "status": "completed",
    "output": {
      "result": "Ticket routed to Support"
    },
    "blockOutputs": null,
    "error": null,
    "startedAt": "2026-08-09T18:04:10.000Z",
    "endedAt": "2026-08-09T18:04:11.000Z",
    "durationMs": 1000
  }
}

{
  "data": {
    "runId": "run_8f14e45f-ceea-467f-a",
    "statusUrl": "https://www.sim.ai/api/v2/workflows/3b1f7c92-8d4e-4a6b-9c0d-5e2f8a714b36/runs/run_8f14e45f-ceea-467f-a"
  }
}

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

{
  "error": {
    "code": "USAGE_LIMIT_EXCEEDED",
    "message": "Usage limit exceeded. Please upgrade your plan to continue."
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient workspace permissions",
    "details": {
      "code": "INSUFFICIENT_WORKSPACE_ROLE"
    }
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Not found"
  }
}

{
  "error": {
    "code": "CONFLICT",
    "message": "Run ID has already been used",
    "details": {
      "code": "RUN_ID_CONFLICT",
      "runId": "0f7c1a2e-9b3d-4c58-8a21-6d4e5f7a9b01"
    }
  }
}

{
  "error": {
    "code": "PAYLOAD_TOO_LARGE",
    "message": "Request body is too large"
  }
}

{
  "error": {
    "code": "UNSUPPORTED_MEDIA_TYPE",
    "message": "Request body must be sent as application/json"
  }
}

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "API rate limit exceeded",
    "details": {
      "retryAfter": "2026-01-01T00:00:30.000Z"
    }
  }
}

{
  "error": {
    "code": "CLIENT_CLOSED_REQUEST",
    "message": "Client cancelled request",
    "details": {
      "runId": "0f7c1a2e-9b3d-4c58-8a21-6d4e5f7a9b01"
    }
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  }
}

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable"
  }
}

Path parameters

workflowId*string

Unique workflow identifier.

Length1 <= length

Header parameters

x-run-id?string

Run ID for API-key or OAuth callers; ignored for anonymous requests. Reuse it after an uncertain response: a claimed ID returns 409 with RUN_ID_CONFLICT, without replaying results. Check Get workflow run, but 404 can persist while the ID remains claimed and does not establish whether execution started. Do not automatically restart with a fresh or omitted ID; either can start another run.

Match^[A-Za-z0-9._:-]+$

Length1 <= length <= 128

x-sim-via?string

Comma-separated workflow identifiers naming the workflow-to-workflow call chain that led to this request. Each hop appends its own workflow id, and Sim sets it automatically; supply it yourself only when relaying an existing chain. A chain at the maximum depth is rejected with 409 and error.details.code: "CALL_CHAIN_DEPTH_EXCEEDED".

Request body

application/json

Input, workflow-state selection, and execution-mode options. Input descriptions specify compatible modes; invalid combinations return 400.

TypeScript definitions

Use the request body type in TypeScript.

input?

Workflow input keyed by the selected trigger input-field name.

run?|

Workflow state and entry point to execute. Omit for the active deployment. Manual execution requires OAuth or personal-key write access and supports synchronous or streamed runs only.

async?boolean

Queue the run and return a 202 receipt. Requires an API key or OAuth access token and a deployed run source. Cannot stream, select outputs, enable thinking/tool events, or include file-inlining options (includeFileBase64 or base64MaxBytes).

Defaultfalse

executionTimeoutSeconds?integer

Maximum duration of an asynchronous run, in seconds, capped by the plan's execution timeout. Requires async: true; otherwise returns 400.

Range1 <= value <= 604800

stream?boolean

Return Server-Sent Events instead of JSON when true. Cannot be combined with async.

Defaultfalse

selectedOutputs?array<>

Select <blockName>.<outputPath> or <childWorkflowId>.<blockName>.<outputPath> using normalized block reference names. Child selectors cover every invocation. Synchronous results use selector strings verbatim as blockOutputs keys; streaming selections shape the envelope. Unknown block names or IDs return 400 with available blocks before execution. Unexecuted blocks and absent paths are omitted. Incompatible with async; select outputs from the finished run resource instead.

Itemsitems <= 100

includeThinking?boolean

Include model reasoning events in an agent-event stream. Requires stream: true and the X-Sim-Stream-Protocol: agent-events-v1 request header, and is rejected when async is true.

Defaultfalse

includeToolCalls?boolean

Include tool-call events in an agent-event stream. Requires stream: true and the X-Sim-Stream-Protocol: agent-events-v1 request header, and is rejected when async is true.

Defaultfalse

includeFileBase64?boolean

Inline eligible output files as base64 content. Rejected when async is true.

base64MaxBytes?integer

Maximum total bytes of file content to inline as base64, lowering but never raising the server limit of 16 MiB. Rejected when async is true.

Range0 < value <= 16777216

Response body

application/json

Sunbelt Computer Software

PL/B Language Development and Support

Execute workflow

Authorization

Path parameters

Header parameters

Request body

Response body

Sunbelt Computer Software

PL/B Language Development and Support

Execute workflow

Authorization

Path parameters

Header parameters

Request body

Response body

200application/json

202

400

401

402

403

404

409

413

415

429

499

500

503