> ## Documentation Index > Fetch the complete documentation index at: https://docs.hitl.sh/llms.txt > Use this file to discover all available pages before exploring further. # Create a workflow > Creates a **draft** from a graph of steps, the same graph the editor builds. Invite reviewers, then [activate](/api-reference/workflows/activate) it. Needs `workflow:write`. A key whose signup is not confirmed yet can create drafts. ## OpenAPI ````yaml POST /api/workflows openapi: 3.1.0 info: title: HITL API version: 1.0.0 description: >- Run the workflows you build in HITL, follow each run until a person has answered, and manage who reviews them. servers: - url: https://api.hitl.sh/v1 security: - bearerAuth: [] tags: - name: Workflows - name: Runs - name: Reviewers - name: Webhooks - name: Account - name: Uploads paths: /api/workflows: post: tags: - Workflows summary: Create a workflow description: >- Creates a **draft** from a graph of steps, the same graph the editor builds. Invite reviewers, then [activate](/api-reference/workflows/activate) it. Needs `workflow:write`. A key whose signup is not confirmed yet can create drafts. operationId: workflows-create requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WorkflowGraph' example: name: Refund approval description: A support lead approves or denies refunds. nodes: - id: trigger-1 type: trigger position: x: 0 'y': 0 data: triggerType: webhook - id: review-1 type: review position: x: 0 'y': 200 data: label: Approve refund requestText: >- Refund ${{trigger.body.amount}} to {{trigger.body.customer.name}}? responseType: single_select priority: high timeout: '7200' responseConfig: options: - value: approve label: Approve refund - value: deny label: Deny required: true - id: end-1 type: end position: x: 0 'y': 400 data: label: End edges: - id: e1 source: trigger-1 target: review-1 - id: e2 source: review-1 target: end-1 responses: '201': description: Created content: application/json: schema: type: object properties: error: type: boolean msg: type: string data: $ref: '#/components/schemas/Workflow' example: error: false msg: Workflow created data: id: 6af2ce4e8207961501f59472 name: Refund approval description: >- A support lead approves, denies or escalates refunds over $100. status: draft trigger: type: webhook webhook_id: wf_26db308d0ea2bfd5427999311a169b3b steps: 6 has_review: true runnable: false execution_count: 0 last_executed_at: null created_at: '2026-11-10T07:57:02.477Z' updated_at: '2026-11-10T07:57:05.452Z' '400': $ref: '#/components/responses/E400' '401': $ref: '#/components/responses/E401' '403': $ref: '#/components/responses/E403' components: schemas: WorkflowGraph: type: object properties: name: type: string description: type: string nodes: type: array items: $ref: '#/components/schemas/Step' edges: type: array items: $ref: '#/components/schemas/Edge' trigger: type: object description: Trigger settings additionalProperties: true gradient_id: type: string description: Icon colour Workflow: allOf: - $ref: '#/components/schemas/WorkflowSummary' - type: object properties: nodes: type: array items: $ref: '#/components/schemas/Step' edges: type: array items: $ref: '#/components/schemas/Edge' input_fields: type: array items: $ref: '#/components/schemas/InputField' Step: type: object required: - id - type properties: id: type: string type: type: string enum: - trigger - review - ai - ai_classifier - data_source - condition - transform - action - end position: type: object properties: x: type: number 'y': type: number data: type: object description: >- The step's settings. For a review step: `label`, `requestText` (Markdown, may use `{{trigger.body.}}`), `responseType`, `responseConfig`, `priority`, `timeout` (seconds, as a string). Credentials are redacted in answers. additionalProperties: true Edge: type: object required: - source - target properties: id: type: string source: type: string target: type: string source_handle: type: string description: 'Which exit of the source step: `yes` / `no` for a condition' WorkflowSummary: type: object properties: id: type: string name: type: string description: type: string status: type: string enum: - active - paused - draft trigger: type: object properties: type: type: string enum: - webhook - email - schedule - manual - google_sheets_row webhook_id: type: string steps: type: integer description: Number of steps, trigger and end included has_review: type: boolean description: The workflow has at least one review step runnable: type: boolean description: Active, so `POST /run` will start it execution_count: type: integer last_executed_at: type: - string - 'null' format: date-time created_at: type: string format: date-time updated_at: type: string format: date-time InputField: type: object properties: path: type: string example: customer.email used_by: type: array items: type: string description: Ids of the steps that read it Error: type: object required: - error - msg properties: error: type: boolean example: true msg: type: string description: What went wrong, in plain words code: type: string description: >- A machine-readable reason, when there is one (for example `confirmation_required`) responses: E400: description: Invalid input; `msg` says what to fix content: application/json: schema: $ref: '#/components/schemas/Error' example: error: true msg: Invalid execution id E401: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' example: error: true msg: Invalid API key E403: description: The key lacks the scope, or the signup is not confirmed yet content: application/json: schema: $ref: '#/components/schemas/Error' example: error: true code: confirmation_required msg: 'Confirm the signup first: ask your human for the code in the email' securitySchemes: bearerAuth: type: http scheme: bearer description: 'Your API key: `hitl_live_…`' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.