> ## Documentation Index > Fetch the complete documentation index at: https://docs.sidenet.ai/llms.txt > Use this file to discover all available pages before exploring further. # Run workflow > Runs a workflow version. `?version=active` (default), `draft`, or `v{n}`. Body: `{ input, groupId?, groupName?, runtimeAuth? }` — `input` is the workflow input, `groupId`/`groupName` select the group the run is attributed to (like /v1/chat), and `runtimeAuth` supplies per-request credentials for tool steps (custom + MCP). Drafts are validated at run time and rejected with 422 if invalid. The run executes as an end user: call it with that user's session token. Pass `stream: true` to receive Server-Sent Events instead of a single JSON body: each workflow stream event is emitted as a `data:` line, and the stream ends with a `run-complete` event carrying the same payload as the non-streaming response (`run-error` on failure). Pre-run errors (400/404/422) are returned as plain JSON either way. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/workflows/{id}/run openapi: 3.1.0 info: title: Sidenet API version: 1.0.0 description: >- Sidenet HTTP endpoints exposed by the Sidenet Studio. All routes require an api key that can be generated through the studio in studio.sidenet.ai. servers: - url: https://api.sidenet.ai security: - bearerAuth: [] paths: /v1/workflows/{id}/run: post: tags: - Workflows summary: Run workflow description: >- Runs a workflow version. `?version=active` (default), `draft`, or `v{n}`. Body: `{ input, groupId?, groupName?, runtimeAuth? }` — `input` is the workflow input, `groupId`/`groupName` select the group the run is attributed to (like /v1/chat), and `runtimeAuth` supplies per-request credentials for tool steps (custom + MCP). Drafts are validated at run time and rejected with 422 if invalid. The run executes as an end user: call it with that user's session token. Pass `stream: true` to receive Server-Sent Events instead of a single JSON body: each workflow stream event is emitted as a `data:` line, and the stream ends with a `run-complete` event carrying the same payload as the non-streaming response (`run-error` on failure). Pre-run errors (400/404/422) are returned as plain JSON either way. parameters: - name: id in: path required: true schema: type: string example: 4c2f9e18-7a63-4d05-b1e8-93a7c0f2d641 - name: version in: query required: false schema: type: string default: active description: active (default) | draft | v{n} requestBody: content: application/json: schema: type: object properties: input: type: object additionalProperties: {} description: >- The workflow input: an object whose keys are the fields the version's input_schema declares (validated against that schema by the run). Omit it to run with `{}`. example: text: My order never arrived groupId: type: string minLength: 1 maxLength: 255 nullable: true description: >- Optional stable caller-supplied group id. When sent, group matching is by this id; a differing groupName renames the group. example: grp_84f20c19 groupName: type: string nullable: true description: >- Optional group name. Without groupId this matches by name; alongside groupId it is display-only (rename on change). example: Acme — production runtimeAuth: type: object additionalProperties: type: object additionalProperties: {} description: >- Runtime authentication map: { [providerNameOrId]: { credentials } } — used by tool steps (custom + MCP) example: 8d3b1a75-6c02-4e59-b84f-27a9d5e10c63: token: per-request CRM token stream: type: boolean default: false description: >- When true, respond with Server-Sent Events: one `data:` line per workflow stream event (step start/output/result, nested agent events, …), ending with a `run-complete` (or `run-error`) event that carries the same payload as the non-streaming JSON response. example: false notify_thread: type: boolean default: false description: >- When true (active version only), the run also files its result as a new conversation in the user's thread list — exactly like a scheduled run: pre-titled, marked unread, with the inputs, the output and the run's text output. The response then carries `run_id` and `thread_id`; `stream` is ignored. Use it to trigger a workflow from your own UI without a chat turn. example: false thread_title: type: string minLength: 1 maxLength: 200 description: >- With notify_thread: the conversation title (default " — "). example: Refund triage — 21 Aug additionalProperties: false responses: '200': description: >- Run completed (JSON), or — with `stream: true` — a text/event-stream of workflow events ending in `run-complete`/`run-error`. The `run-complete` event carries exactly the JSON body documented here. content: application/json: schema: type: object properties: status: type: string description: >- `completed`. A failed run answers 500 with `{error, details}`. environment: type: string description: Which environment the run was attributed to. version: type: integer description: The version number that ran — 0 when you ran the draft. traceId: type: string description: >- Correlates this run with its observability trace. Also returned as the `X-Request-Id` / `X-Trace-Id` response headers. result: type: object description: >- The workflow's own output, shaped by the version's `output_schema` — so this varies per workflow. Steps that produce no output leave it empty. run_id: type: string format: uuid description: 'With `notify_thread`: the workflow_runs row.' thread_id: type: string description: >- With `notify_thread`: the conversation the result was filed in. text: type: string nullable: true description: >- The run's text output. With `notify_thread`: the text posted to the thread — the workflow's `output_text` rendered against this run, else a completion notice with the output attached. Without it: the rendered `output_text`, or null when the version declares none. example: status: completed environment: production version: 2 traceId: 0af7651916cd43dd8448eb211c80319c result: category: refund orderId: ord_10482 text/event-stream: schema: type: string description: >- Sent when `stream: true`. One `data:` line per workflow event, ending with a `run-complete` event whose payload is the JSON body above (or `run-error`). '400': description: Missing headers / invalid body / no active version '404': description: Workflow or version not found '422': description: Draft definition invalid '500': description: Run failed security: - sessionToken: [] components: securitySchemes: bearerAuth: type: http scheme: bearer description: >- Organization API key, generated in studio.sidenet.ai. Backend only — never in a browser. sessionToken: type: http scheme: bearer description: >- Session token (`snat_…`) minted by POST /v1/token. Carries the organization and the end user; safe in a browser. ````