Skip to content
API Reference

Run a Workflow Through the API

Version: unreleased · Docs: 3c6ab9f2Download Markdown

Create and test the workflow in Redbelt, then run it with POST /api/v1/workflows/WORKFLOW_ID/runs. The API runs the workflow as saved; it can’t change the workflow’s steps.

Complete the API quickstart. The API key identity needs access to the workflow, required Knowledge and app connections. Share each dependency with the service user where supported. A definition’s visibility does not grant access to its author’s private connection.

Call GET /api/v1/workflows for accessible definitions, then GET /api/v1/workflows/WORKFLOW_ID for its input_schema. Supply inputs using those configured field names and values.

POST /api/v1/workflows/WORKFLOW_ID/runs
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{
"request_id": "YOUR_UUIDV7",
"inputs": {
"project_update": "Design approved; implementation starts Monday."
}
}

Replace project_update with a field from your workflow. Save the exact body and UUIDv7 request_id before sending. 202 returns the workflow execution id and thread_id. Reuse the same ID and body after a lost response.

Optional thread_id selects an accessible existing thread. For workflows with an explicit trigger, trigger names the trigger step and trigger_input supplies that trigger’s payload. Omit them for the normal entry point.

Read GET /api/v1/executions/workflow/EXECUTION_ID. Completed outputs appear in structured_output; wait_id indicates required input or approval. Track Runs and Retrieve Results explains waiting for results, answering waits, cancellation, and authenticated artifact downloads.

A saved workflow can still fail when an input is invalid, a connection is unavailable, a tool needs approval, or the model provider or spending limit blocks it. Check the accepted run before sending a new request ID.