# Run a Workflow Through the API

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.

## Prepare access and inputs

Complete the [API quickstart](/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.

## Submit the run

```http
POST /api/v1/workflows/WORKFLOW_ID/runs
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

```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.

## Check completion

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](/api/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.
