> ## Documentation Index > Fetch the complete documentation index at: https://docs.beltic.com/llms.txt > Use this file to discover all available pages before exploring further. # Execute Workflow > Run a workflow synchronously. Returns `200` if the run reaches a terminal state (`completed`, `failed`, `cancelled`) and `202` if the run pauses awaiting external input (`paused`). By default the latest deployed workflow state is used. Pass `useDraftState: true` to run the draft state, or `workflow` to run an inline state graph. ## OpenAPI ````yaml POST /v1/workflows/execute openapi: 3.1.0 info: title: Beltic Workflow API version: 1.0.0 description: >- # Workflow API The Beltic Workflow API runs configurable workflows that orchestrate Beltic verification services (identity, business, document, screening, website check) along with HTTP requests, AI completions, and human-in-the-loop steps. ## Key Features - **Run workflows**: Submit a workflow for execution against the deployed or draft state - **List workflows**: Discover available workflows in your organization - **Inspect executions**: List recent executions across all workflows or for a specific workflow, including status, output verdicts, and paused-block metadata ## Authentication Most requests authenticate with a Bearer JWT obtained from your Beltic session, but server-to-server callers may also use an API key. The API key implies the calling organization and workflow environment. **Bearer JWT (default):** ``` Authorization: Bearer YOUR_JWT ``` **API key (server-to-server):** ``` x-api-key: YOUR_API_KEY ``` ## Response Format Responses are plain JSON (not JSON:API). Error responses have the shape `{ "error": string, "code"?: string, "details"?: ... }`. contact: name: Beltic API Support email: engineering@beltic.com servers: - url: https://api.beltic.com description: Production security: - BearerAuth: [] - ApiKeyAuth: [] tags: - name: Workflows description: List workflows and retrieve workflow-scoped execution history. - name: Executions description: Start workflow executions and list execution history across all workflows. externalDocs: description: Beltic Platform Documentation url: https://docs.beltic.com paths: /v1/workflows/execute: post: tags: - Executions summary: Execute a workflow description: >- Run a workflow synchronously. Returns `200` if the run reaches a terminal state (`completed`, `failed`, `cancelled`) and `202` if the run pauses awaiting external input (`paused`). By default the latest deployed workflow state is used. Pass `useDraftState: true` to run the draft state, or `workflow` to run an inline state graph. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExecuteRequest' responses: '200': description: Execution reached a terminal state. content: application/json: schema: $ref: '#/components/schemas/ExecutionResult' '202': description: Execution paused awaiting external input. content: application/json: schema: $ref: '#/components/schemas/ExecutionResult' '400': description: >- Invalid request — for example, a `runFromBlock` request that cannot be applied to the workflow. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Authentication failed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Caller lacks the `workflows:execute` permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: >- Workflow not found, or `runFromBlock` referenced an execution that no longer exists (code `RUN_FULL_WORKFLOW_FIRST`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: >- `runFromBlock` could not be applied because the workflow graph changed or an upstream block is missing (codes `RUN_FROM_BLOCK_GRAPH_CHANGED`, `RUN_FROM_BLOCK_UPSTREAM_MISSING`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: >- Request body failed schema validation, or workflow input failed contract validation. content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' '500': description: Server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] - ApiKeyAuth: [] components: schemas: ExecuteRequest: type: object required: - workflowId properties: workflowId: type: string description: Workflow ID to execute. workflow: type: object description: >- Optional inline workflow state. When provided, replaces the persisted workflow definition for this run. additionalProperties: true useDraftState: type: boolean description: >- When `true`, run the workflow's draft state instead of the latest deployed version. Defaults to `false`. options: $ref: '#/components/schemas/ExecuteOptions' runFromBlock: $ref: '#/components/schemas/RunFromBlockRequest' parentExecutionId: type: string description: Parent execution ID when this run is a subworkflow. callChain: type: array description: >- Ancestor workflow IDs leading to this run. Used for cycle detection in subworkflows. items: type: string minLength: 1 ExecutionResult: type: object description: >- Result of an execution. Returned by `POST /v1/workflows/execute` with status `200` (completed/failed) or `202` (paused). required: - success - output - executionId properties: success: type: boolean output: type: object description: Normalized block output keyed by block ID. additionalProperties: true error: type: string description: Error message when the run did not complete successfully. status: $ref: '#/components/schemas/ExecutionStatus' executionId: type: string pausePoints: type: array description: Active pause points when the run is paused awaiting external input. items: type: object additionalProperties: true logs: type: array description: Block-level execution logs. items: type: object additionalProperties: true finalState: type: object description: >- Compact snapshot of final execution state. Populated on successful completion to support future partial (run-from-block) re-runs. additionalProperties: true ErrorResponse: type: object required: - error properties: error: type: string description: Human-readable error message. code: type: string description: Machine-readable error code, when available. ValidationErrorResponse: type: object description: Returned when the request body fails schema validation. required: - error properties: error: type: string example: Invalid request body code: type: string details: type: object description: >- Flattened Zod issue tree. Shape: `{ formErrors: string[], fieldErrors: Record }`. additionalProperties: true fields: type: array description: Field-level validation errors. items: type: object required: - name - message properties: name: type: string message: type: string ExecuteOptions: type: object description: Runtime options for an execution. properties: executionId: type: string description: Caller-supplied execution ID. Generated if omitted. input: type: object description: Input payload matched against the workflow's input contract. additionalProperties: true environmentVariables: type: object description: Environment variables made available to the workflow run. additionalProperties: type: string workflowVariables: type: object description: Workflow-scoped variables made available to the workflow run. additionalProperties: true maxParallelNodes: type: integer minimum: 1 description: Cap on concurrent block execution within this run. RunFromBlockRequest: type: object description: >- Partial re-run descriptor. The referenced execution must already exist; raw source-state injection is intentionally unavailable to public callers. required: - startBlockId - executionId properties: startBlockId: type: string minLength: 1 description: Block ID to re-run from. executionId: type: string minLength: 1 description: ID of the existing execution whose state will be used as the seed. ExecutionStatus: type: string enum: - completed - failed - paused - cancelled description: Terminal or paused status of a workflow execution. securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: Beltic-issued JWT bearer token. ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Workflow API key. The key identifies the calling organization and workflow environment. ````