openapi: 3.2.0 info: title: Happyrobot Public Workflows API description: Public API endpoints for Happyrobot version: 0.1.1 servers: - url: https://platform.happyrobot.ai/api/v2 security: - bearerAuth: [] tags: - name: Workflows paths: /workflows/: get: summary: List workflows tags: - Workflows description: Returns paginated workflows for the authenticated organization. Each workflow includes its latest version info (live production version preferred, otherwise most recent). Supports searching by name and filtering by folder. parameters: - schema: default: 1 type: integer minimum: 1 maximum: 9007199254740991 in: query name: page required: false - schema: default: 50 type: integer minimum: 1 maximum: 100 in: query name: page_size required: false - schema: default: desc type: string enum: - asc - desc in: query name: sort required: false - schema: type: string in: query name: search required: false - schema: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ in: query name: folder_id required: false security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ org_id: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ name: type: string slug: type: string icon: type: - string - 'null' folder_id: type: - string - 'null' format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ data_retention_days: type: - number - 'null' timestamp: type: string latest_version: type: - object - 'null' properties: id: type: string name: type: string slug: type: string version_number: type: - number - 'null' is_published: type: boolean is_live: type: boolean environment: type: string workflow_version: description: 'Workflow engine version for this version: 2 = legacy, 3 = explicit-edges engine (loop/path/loop_break nodes available).' type: number published_at: type: - string - 'null' timestamp: type: string required: - id - name - slug - is_published - is_live - timestamp additionalProperties: false required: - id - org_id - name - slug - timestamp - latest_version additionalProperties: false pagination: type: object properties: page: type: integer minimum: -9007199254740991 maximum: 9007199254740991 page_size: type: integer minimum: -9007199254740991 maximum: 9007199254740991 total_pages: type: integer minimum: -9007199254740991 maximum: 9007199254740991 total_records: type: integer minimum: -9007199254740991 maximum: 9007199254740991 has_next_page: type: boolean has_previous_page: type: boolean required: - page - page_size - total_pages - total_records - has_next_page - has_previous_page additionalProperties: false required: - data - pagination additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false post: summary: Create a workflow tags: - Workflows description: 'Creates a new workflow in the authenticated organization. Supports three creation modes: 1. **Plain** — Creates an empty workflow with an initial version. 2. **From template** — Use `from_template` to create a pre-configured workflow with trigger and agent nodes. Available templates: `voice-agent`, `inbound-voice-agent`, `whatsapp-agent`, `sms-agent`, `email-agent`, `chatbot-agent`. Credentials are auto-discovered from the organization. 3. **With version and nodes** — Use `version` to provide custom version metadata and an optional `nodes` array to define the workflow structure inline. The first node must be a `trigger`, subsequent nodes reference their parent via `parent_index`. `from_template` and `version` are mutually exclusive. Optionally, pass a `variables` array to create workflow-scoped environment variables alongside the workflow.' requestBody: content: application/json: schema: type: object properties: name: type: string minLength: 1 icon: default: robot type: string folder_id: type: - string - 'null' format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ settings: type: object properties: data_retention_days: type: - integer - 'null' minimum: -9007199254740991 maximum: 9007199254740991 audits_enabled: type: boolean audit_sampling_bps: type: integer minimum: 0 maximum: 10000 audit_conditions: type: array items: type: object properties: id: type: string title: type: string ors: type: array items: type: object properties: id: type: string ands: type: array items: type: object properties: id: type: string field: type: object properties: group_id: type: string variable_id: type: string required: - group_id - variable_id condition: type: string value: type: array items: description: '!IMPORTANT: This schema describes one Paragraph object. When the containing field is an array of this schema, send a flat Paragraph[] array. Do not send a bare Paragraph object. Only send Paragraph[][] when the containing field is explicitly an array of arrays. Paragraph object schema: {type: ''paragraph'', children: Array<{text: string} | {type: ''variable'', children: [{text: ''''}], group_id: string, variable_id: string}>}' required: - ands output: type: array items: description: '!IMPORTANT: This schema describes one Paragraph object. When the containing field is an array of this schema, send a flat Paragraph[] array. Do not send a bare Paragraph object. Only send Paragraph[][] when the containing field is explicitly an array of arrays. Paragraph object schema: {type: ''paragraph'', children: Array<{text: string} | {type: ''variable'', children: [{text: ''''}], group_id: string, variable_id: string}>}' out_of_office_hours: type: object additionalProperties: type: object properties: timezone: type: string minLength: 1 weekly_schedule: minItems: 7 maxItems: 7 type: array items: type: - array - 'null' items: type: - object - 'null' properties: start: type: string pattern: ^(([0-1][0-9]|2[0-3]):[0-5][0-9]|24:00)$ end: type: string pattern: ^(([0-1][0-9]|2[0-3]):[0-5][0-9]|24:00)$ required: - start - end off_days: type: object additionalProperties: type: array items: type: object properties: start: type: string pattern: ^(([0-1][0-9]|2[0-3]):[0-5][0-9]|24:00)$ end: type: string pattern: ^(([0-1][0-9]|2[0-3]):[0-5][0-9]|24:00)$ required: - start - end required: - timezone - weekly_schedule webhooks: type: array items: type: object properties: url: type: string format: uri headers: type: object additionalProperties: type: string required: - url workflow_approval_process_settings: type: object properties: environments: type: object properties: production: type: boolean staging: type: boolean development: type: boolean required: - production - staging - development required: - environments deployment: description: '@internal' type: object properties: owner: type: - string - 'null' maxLength: 256 pod_id: type: - string - 'null' format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ category_id: type: - string - 'null' format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ stage_id: type: - string - 'null' format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: type: - string - 'null' linked_workflow_ids: type: - array - 'null' items: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ from_template: oneOf: - type: object properties: template: type: string enum: - voice-agent inputs: default: {} type: object properties: agent_name: description: Display name for the AI voice agent. type: string prompt: description: Prompt node overrides. type: object properties: prompt_md: description: Agent system prompt in markdown format. type: string initial_message: description: The first message the agent says when the call/conversation starts. type: string initial_message_uninterruptible: description: Whether the voice agent initial message is uninterruptible. type: boolean model: description: 'LLM model selection as a TemplatedValue (e.g. { type: "static", static: { id: "turbo-one", name: "gpt-4.1" } }).' type: object properties: type: type: string enum: - static - dynamic static: type: object properties: id: type: string name: type: string description: type: string required: - id - name dynamic: type: array items: description: '!IMPORTANT: This schema describes one Paragraph object. When the containing field is an array of this schema, send a flat Paragraph[] array. Do not send a bare Paragraph object. Only send Paragraph[][] when the containing field is explicitly an array of arrays. Paragraph object schema: {type: ''paragraph'', children: Array<{text: string} | {type: ''variable'', children: [{text: ''''}], group_id: string, variable_id: string}>}' required: - type required: - template - type: object properties: template: type: string enum: - inbound-voice-agent inputs: default: {} type: object properties: agent_name: description: Display name for the inbound voice agent. type: string prompt: description: Prompt node overrides. type: object properties: prompt_md: description: Agent system prompt in markdown format. type: string initial_message: description: The first message the agent says when the call/conversation starts. type: string initial_message_uninterruptible: description: Whether the voice agent initial message is uninterruptible. type: boolean model: description: 'LLM model selection as a TemplatedValue (e.g. { type: "static", static: { id: "turbo-one", name: "gpt-4.1" } }).' type: object properties: type: type: string enum: - static - dynamic static: type: object properties: id: type: string name: type: string description: type: string required: - id - name dynamic: type: array items: description: '!IMPORTANT: This schema describes one Paragraph object. When the containing field is an array of this schema, send a flat Paragraph[] array. Do not send a bare Paragraph object. Only send Paragraph[][] when the containing field is explicitly an array of arrays. Paragraph object schema: {type: ''paragraph'', children: Array<{text: string} | {type: ''variable'', children: [{text: ''''}], group_id: string, variable_id: string}>}' required: - type required: - template - type: object properties: template: type: string enum: - whatsapp-agent inputs: default: {} type: object properties: agent_name: description: Display name for the WhatsApp agent. type: string prompt: description: Prompt node overrides. type: object properties: prompt_md: description: Agent system prompt in markdown format. type: string initial_message: description: The first message the agent says when the call/conversation starts. type: string initial_message_uninterruptible: description: Whether the voice agent initial message is uninterruptible. type: boolean model: description: 'LLM model selection as a TemplatedValue (e.g. { type: "static", static: { id: "turbo-one", name: "gpt-4.1" } }).' type: object properties: type: type: string enum: - static - dynamic static: type: object properties: id: type: string name: type: string description: type: string required: - id - name dynamic: type: array items: description: '!IMPORTANT: This schema describes one Paragraph object. When the containing field is an array of this schema, send a flat Paragraph[] array. Do not send a bare Paragraph object. Only send Paragraph[][] when the containing field is explicitly an array of arrays. Paragraph object schema: {type: ''paragraph'', children: Array<{text: string} | {type: ''variable'', children: [{text: ''''}], group_id: string, variable_id: string}>}' required: - type required: - template - type: object properties: template: type: string enum: - sms-agent inputs: default: {} type: object properties: agent_name: description: Display name for the SMS agent. type: string prompt: description: Prompt node overrides. type: object properties: prompt_md: description: Agent system prompt in markdown format. type: string initial_message: description: The first message the agent says when the call/conversation starts. type: string initial_message_uninterruptible: description: Whether the voice agent initial message is uninterruptible. type: boolean model: description: 'LLM model selection as a TemplatedValue (e.g. { type: "static", static: { id: "turbo-one", name: "gpt-4.1" } }).' type: object properties: type: type: string enum: - static - dynamic static: type: object properties: id: type: string name: type: string description: type: string required: - id - name dynamic: type: array items: description: '!IMPORTANT: This schema describes one Paragraph object. When the containing field is an array of this schema, send a flat Paragraph[] array. Do not send a bare Paragraph object. Only send Paragraph[][] when the containing field is explicitly an array of arrays. Paragraph object schema: {type: ''paragraph'', children: Array<{text: string} | {type: ''variable'', children: [{text: ''''}], group_id: string, variable_id: string}>}' required: - type required: - template - type: object properties: template: type: string enum: - email-agent inputs: default: {} type: object properties: agent_name: description: Display name for the Email agent. type: string email_to: description: Default recipient email address. type: string prompt: description: Prompt node overrides. type: object properties: prompt_md: description: Agent system prompt in markdown format. type: string initial_message: description: The first message the agent says when the call/conversation starts. type: string initial_message_uninterruptible: description: Whether the voice agent initial message is uninterruptible. type: boolean model: description: 'LLM model selection as a TemplatedValue (e.g. { type: "static", static: { id: "turbo-one", name: "gpt-4.1" } }).' type: object properties: type: type: string enum: - static - dynamic static: type: object properties: id: type: string name: type: string description: type: string required: - id - name dynamic: type: array items: description: '!IMPORTANT: This schema describes one Paragraph object. When the containing field is an array of this schema, send a flat Paragraph[] array. Do not send a bare Paragraph object. Only send Paragraph[][] when the containing field is explicitly an array of arrays. Paragraph object schema: {type: ''paragraph'', children: Array<{text: string} | {type: ''variable'', children: [{text: ''''}], group_id: string, variable_id: string}>}' required: - type required: - template - type: object properties: template: type: string enum: - chatbot-agent inputs: default: {} type: object properties: agent_name: description: Display name for the chatbot agent. type: string prompt: description: Prompt node overrides. type: object properties: prompt_md: description: Agent system prompt in markdown format. type: string initial_message: description: The first message the agent says when the call/conversation starts. type: string initial_message_uninterruptible: description: Whether the voice agent initial message is uninterruptible. type: boolean model: description: 'LLM model selection as a TemplatedValue (e.g. { type: "static", static: { id: "turbo-one", name: "gpt-4.1" } }).' type: object properties: type: type: string enum: - static - dynamic static: type: object properties: id: type: string name: type: string description: type: string required: - id - name dynamic: type: array items: description: '!IMPORTANT: This schema describes one Paragraph object. When the containing field is an array of this schema, send a flat Paragraph[] array. Do not send a bare Paragraph object. Only send Paragraph[][] when the containing field is explicitly an array of arrays. Paragraph object schema: {type: ''paragraph'', children: Array<{text: string} | {type: ''variable'', children: [{text: ''''}], group_id: string, variable_id: string}>}' required: - type required: - template variables: description: Optional list of workflow-scoped variables to create alongside the workflow. maxItems: 100 type: array items: type: object properties: key: type: string minLength: 1 value_production: type: string value_staging: type: string value_development: type: string is_hidden_in_ui: default: false type: boolean required: - key - value_production - value_staging - value_development version: type: object properties: name: type: string description: type: string nodes: description: Ordered list of nodes to create. The first node must be a trigger. minItems: 1 maxItems: 50 type: array items: oneOf: - type: object properties: type: type: string enum: - trigger event_id: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ description: The trigger event ID name: description: Display name override type: string configuration: description: Trigger-specific configuration (JSONB) type: object additionalProperties: {} webhook_payload: description: Expected payload for webhook nodes. When provided, this is saved as the node output so downstream nodes can reference it. type: object additionalProperties: {} required: - type - event_id - type: object properties: type: type: string enum: - action event_id: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ description: The action event ID name: description: Display name override type: string configuration: description: Action-specific configuration (JSONB) type: object additionalProperties: {} parent_node_index: description: Index of the parent node in the nodes array. Required for non-trigger nodes. type: integer minimum: 0 maximum: 9007199254740991 webhook_payload: description: Expected payload for webhook nodes. When provided, this is saved as the node output so downstream nodes can reference it. type: object additionalProperties: {} required: - type - event_id - type: object properties: type: type: string enum: - agent event_id: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$ description: The agent event ID name: description: Display name override type: string configuration: description: Agent-specific configuration (JSONB) type: object additionalProperties: {} prompt: description: Prompt configuration for the auto-generated prompt child node type: object properties: prompt_md: description: Agent system prompt in markdown type: string initial_message: description: Agent initial message — accepts a plain string or Plate paragraph array type: array items: {} initial_message_uninterruptible: description: Whether the voice agent initial message is uninterruptible. type: boolean parent_node_index: description: Index of the parent node in the nodes array. Required for non-trigger nodes. type: integer minimum: 0 maximum: 9007199254740991 required: - type - event_id - type: object properties: type: type: string enum: - tool name: description: Display name override type: string function: description: Tool function definition. type: object properties: description: type: array items: {} message: type: object properties: type: type: string enum: - ai - fixed - none description: type: array items: {} example: type: string parameters: type: array items: type: object properties: name: type: string description: type: array items: {} example: type: string required: type: boolean required: - name hold_music: type: object properties: type: type: string enum: - static - dynamic static: type: object properties: id: type: string name: type: string description: type: string required: - id - name dynamic: type: array items: description: '!IMPORTANT: This schema describes one Paragraph object. When the containing field is an array of this schema, send a flat Paragraph[] array. Do not send a bare Paragraph object. Only send Paragraph[][] when the containing field is explicitly an array of arrays. Paragraph object schema: {type: ''paragraph'', children: Array<{text: string} | {type: ''variable'', children: [{text: ''''}], group_id: string, variable_id: string}>}' required: - type hold_music_asset_id: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ tool_index_id: type: string tool_index_hash: type: string is_mcp: type: boolean mcp_server_credential_id: type: string mcp_tool_name: type: string parent_node_index: description: Index of the parent node in the nodes array. Required for non-trigger nodes. type: integer minimum: 0 maximum: 9007199254740991 required: - type - type: object properties: type: type: string enum: - prompt name: description: Display name override type: string prompt_md: description: System prompt in markdown (prompt nodes only) type: string initial_message: description: Initial message — accepts a plain string or Plate paragraph array (prompt nodes only) type: array items: {} initial_message_uninterruptible: description: Whether the voice agent initial message is uninterruptible. type: boolean model: description: 'LLM model selection as a TemplatedValue (e.g. { type: "static", static: { id: "turbo-one", name: "gpt-4.1" } }).' type: object properties: type: type: string enum: - static - dynamic static: type: object properties: id: type: string name: type: string description: type: string required: - id - name dynamic: type: array items: description: '!IMPORTANT: This schema describes one Paragraph object. When the containing field is an array of this schema, send a flat Paragraph[] array. Do not send a bare Paragraph object. Only send Paragraph[][] when the containing field is explicitly an array of arrays. Paragraph object schema: {type: ''paragraph'', children: Array<{text: string} | {type: ''variable'', children: [{text: ''''}], group_id: string, variable_id: string}>}' required: - type parent_node_index: description: Index of the parent node in the nodes array. Required for non-trigger nodes. type: integer minimum: 0 maximum: 9007199254740991 required: - type - type: object properties: type: type: string enum: - condition name: description: Display name override type: string type_of_condition: description: Type of condition branch. "conditional" evaluates rules, "fallback" catches unmatched cases. type: string enum: - fallback - conditional order: description: Order among sibling conditional branches. Auto-calculated if omitted. type: integer minimum: -9007199254740991 maximum: 9007199254740991 conditions: description: 'Condition rules. Each entry follows the ConditionSchema: { id?, title?, ors: [{ ands: [{ field: { group_id, variable_id }, condition: '''', value: [{ type: ''paragraph'', children: [{ text: ''...'' }] }] }] }], output?: [...] }. The ''value'' field MUST be an array of Plate paragraph objects — plain strings are rejected. Use an empty array [] to clear all conditions.' type: array items: type: object properties: id: type: string title: type: string ors: type: array items: type: object properties: id: type: string ands: type: array items: type: object properties: id: type: string field: type: object properties: group_id: type: string variable_id: type: string required: - group_id - variable_id condition: type: string value: type: array items: description: '!IMPORTANT: This schema describes one Paragraph object. When the containing field is an array of this schema, send a flat Paragraph[] array. Do not send a bare Paragraph object. Only send Paragraph[][] when the containing field is explicitly an array of arrays. Paragraph object schema: {type: ''paragraph'', children: Array<{text: string} | {type: ''variable'', children: [{text: ''''}], group_id: string, variable_id: string}>}' required: - ands output: type: array items: description: '!IMPORTANT: This schema describes one Paragraph object. When the containing field is an array of this schema, send a flat Paragraph[] array. Do not send a bare Paragraph object. Only send Paragraph[][] when the containing field is explicitly an array of arrays. Paragraph object schema: {type: ''paragraph'', children: Array<{text: string} | {type: ''variable'', children: [{text: ''''}], group_id: string, variable_id: string}>}' parent_node_index: description: Index of the parent node in the nodes array. Required for non-trigger nodes. type: integer minimum: 0 maximum: 9007199254740991 required: - type - type: object properties: type: type: string enum: - module-change name: description: Display name override type: string configuration: description: Module-change configuration (JSONB). Defaults to {}. type: object additionalProperties: {} module_node_index: description: Index of the target prompt node in the nodes array. Resolved to configuration.moduleId after all nodes are created. type: integer minimum: 0 maximum: 9007199254740991 parent_node_index: description: Index of the parent node in the nodes array. Required for non-trigger nodes. type: integer minimum: 0 maximum: 9007199254740991 required: - type - type: object properties: type: type: string enum: - loop name: description: Display name override type: string execute_in_parallel: description: Whether loop iterations run in parallel. Defaults to true. This only controls execution strategy; variables produced by loop body nodes resolve as lists outside the loop in both sequential and parallel modes. type: boolean iterate_for: description: Fixed number of iterations. Mutually exclusive with iterate_over. Fixed-count loop bodies expose iteration_index and execute_in_parallel. type: - integer - 'null' minimum: -9007199254740991 maximum: 9007199254740991 iterate_over: description: Expression to iterate over (array variable). Mutually exclusive with iterate_for. Collection loop bodies expose iteration_index, execute_in_parallel, and the configured loop_variable. type: - string - 'null' loop_variable: description: Collection loops only. Name of the current item variable accessible inside the loop body. Defaults to "iteration_element". Collection loops also expose iteration_index and execute_in_parallel. Fixed-count loops expose iteration_index and execute_in_parallel instead. type: - string - 'null' do_child_run: description: Whether each iteration runs as a standalone child run instead of inline in the parent run. Defaults to false. type: boolean configuration: description: 'Tolerated fallback: loop settings may be nested here instead of at the top level. They are hoisted to the top level server-side (a top-level value wins), so this is type-validated. Prefer setting the fields at the top level.' type: object properties: execute_in_parallel: type: boolean iterate_for: type: - integer - 'null' minimum: -9007199254740991 maximum: 9007199254740991 iterate_over: type: - string - 'null' loop_variable: type: - string - 'null' do_child_run: type: boolean parent_node_index: description: Index of the parent node in the nodes array. Required for non-trigger nodes. type: integer minimum: 0 maximum: 9007199254740991 required: - type - type: object properties: type: type: string enum: - path name: description: Display name override type: string parent_node_index: description: Index of the parent node in the nodes array. Required for non-trigger nodes. type: integer minimum: 0 maximum: 9007199254740991 required: - type - type: object properties: type: type: string enum: - loop_break name: description: Display name override type: string parent_node_index: description: Index of the parent node in the nodes array. Required for non-trigger nodes. type: integer minimum: 0 maximum: 9007199254740991 required: - type skip_test_all: default: false description: When true, skip the automatic background test-all validation after node creation. Useful when the caller will run test-all separately (e.g. MCP tools that need synchronous results). type: boolean required: - name required: true security: - bearerAuth: [] responses: '201': description: Default Response content: application/json: schema: type: object properties: id: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ org_id: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ name: type: string slug: type: string icon: type: - string - 'null' folder_id: type: - string - 'null' format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ timestamp: type: string latest_version: type: - object - 'null' properties: id: type: string name: type: string slug: type: string version_number: type: - number - 'null' is_published: type: boolean is_live: type: boolean environment: type: string workflow_version: description: 'Workflow engine version for this version: 2 = legacy, 3 = explicit-edges engine (loop/path/loop_break nodes available).' type: number published_at: type: - string - 'null' timestamp: type: string required: - id - name - slug - is_published - is_live - timestamp additionalProperties: false variables: type: array items: type: object properties: id: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ key: type: string value_production: type: string value_staging: type: string value_development: type: string is_hidden_in_ui: type: boolean required: - id - key - value_production - value_staging - value_development - is_hidden_in_ui additionalProperties: false required: - id - org_id - name - slug - timestamp - latest_version additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false /workflows/{workflow_id}: get: summary: Get a workflow tags: - Workflows description: Returns a single workflow by UUID or slug, including its latest version info (live production version preferred, otherwise most recent). parameters: - schema: type: string minLength: 1 in: path name: workflow_id required: true description: Workflow UUID or slug security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: id: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ org_id: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ name: type: string slug: type: string icon: type: - string - 'null' folder_id: type: - string - 'null' format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ data_retention_days: type: - number - 'null' timestamp: type: string latest_version: type: - object - 'null' properties: id: type: string name: type: string slug: type: string version_number: type: - number - 'null' is_published: type: boolean is_live: type: boolean environment: type: string workflow_version: description: 'Workflow engine version for this version: 2 = legacy, 3 = explicit-edges engine (loop/path/loop_break nodes available).' type: number published_at: type: - string - 'null' timestamp: type: string required: - id - name - slug - is_published - is_live - timestamp additionalProperties: false live_version: type: - object - 'null' properties: id: type: string name: type: string slug: type: string version_number: type: - number - 'null' is_published: type: boolean is_live: type: boolean environment: type: string workflow_version: description: 'Workflow engine version for this version: 2 = legacy, 3 = explicit-edges engine (loop/path/loop_break nodes available).' type: number published_at: type: - string - 'null' timestamp: type: string required: - id - name - slug - is_published - is_live - timestamp additionalProperties: false required: - id - org_id - name - slug - timestamp - latest_version - live_version additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false patch: summary: Update a workflow tags: - Workflows description: Updates workflow metadata and settings. Accepts a workflow UUID or slug as the path parameter. Set `folder_id` to `null` to move the workflow to the root level. Use `settings` to update configuration such as webhooks, out-of-office hours, approval process, data retention, and audits. This endpoint does not modify versions or nodes. requestBody: content: application/json: schema: type: object properties: name: type: string minLength: 1 icon: type: string folder_id: type: - string - 'null' format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ settings: type: object properties: data_retention_days: type: - integer - 'null' minimum: -9007199254740991 maximum: 9007199254740991 audits_enabled: type: boolean audit_sampling_bps: type: integer minimum: 0 maximum: 10000 audit_conditions: type: array items: type: object properties: id: type: string title: type: string ors: type: array items: type: object properties: id: type: string ands: type: array items: type: object properties: id: type: string field: type: object properties: group_id: type: string variable_id: type: string required: - group_id - variable_id condition: type: string value: type: array items: description: '!IMPORTANT: This schema describes one Paragraph object. When the containing field is an array of this schema, send a flat Paragraph[] array. Do not send a bare Paragraph object. Only send Paragraph[][] when the containing field is explicitly an array of arrays. Paragraph object schema: {type: ''paragraph'', children: Array<{text: string} | {type: ''variable'', children: [{text: ''''}], group_id: string, variable_id: string}>}' required: - ands output: type: array items: description: '!IMPORTANT: This schema describes one Paragraph object. When the containing field is an array of this schema, send a flat Paragraph[] array. Do not send a bare Paragraph object. Only send Paragraph[][] when the containing field is explicitly an array of arrays. Paragraph object schema: {type: ''paragraph'', children: Array<{text: string} | {type: ''variable'', children: [{text: ''''}], group_id: string, variable_id: string}>}' out_of_office_hours: type: object additionalProperties: type: object properties: timezone: type: string minLength: 1 weekly_schedule: minItems: 7 maxItems: 7 type: array items: type: - array - 'null' items: type: - object - 'null' properties: start: type: string pattern: ^(([0-1][0-9]|2[0-3]):[0-5][0-9]|24:00)$ end: type: string pattern: ^(([0-1][0-9]|2[0-3]):[0-5][0-9]|24:00)$ required: - start - end off_days: type: object additionalProperties: type: array items: type: object properties: start: type: string pattern: ^(([0-1][0-9]|2[0-3]):[0-5][0-9]|24:00)$ end: type: string pattern: ^(([0-1][0-9]|2[0-3]):[0-5][0-9]|24:00)$ required: - start - end required: - timezone - weekly_schedule webhooks: type: array items: type: object properties: url: type: string format: uri headers: type: object additionalProperties: type: string required: - url workflow_approval_process_settings: type: object properties: environments: type: object properties: production: type: boolean staging: type: boolean development: type: boolean required: - production - staging - development required: - environments deployment: description: '@internal' type: object properties: owner: type: - string - 'null' maxLength: 256 pod_id: type: - string - 'null' format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ category_id: type: - string - 'null' format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ stage_id: type: - string - 'null' format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: type: - string - 'null' linked_workflow_ids: type: - array - 'null' items: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ parameters: - schema: type: string minLength: 1 in: path name: workflow_id required: true description: Workflow UUID or slug security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: id: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ org_id: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ name: type: string slug: type: string icon: type: - string - 'null' folder_id: type: - string - 'null' format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ timestamp: type: string required: - id - org_id - name - slug - timestamp additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false delete: summary: Delete a workflow tags: - Workflows description: Soft-deletes a workflow by UUID or slug. The workflow must not have any live versions — unpublish all versions before deleting. parameters: - schema: type: string minLength: 1 in: path name: workflow_id required: true description: Workflow UUID or slug security: - bearerAuth: [] responses: '204': description: Workflow deleted content: application/json: schema: description: Workflow deleted '400': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false /workflows/{workflow_id}/versions: get: summary: List workflow versions tags: - Workflows description: Returns paginated versions for a workflow. Supports searching by version number or version name. parameters: - schema: default: 1 type: integer minimum: 1 maximum: 9007199254740991 in: query name: page required: false - schema: default: 50 type: integer minimum: 1 maximum: 100 in: query name: page_size required: false - schema: default: desc type: string enum: - asc - desc in: query name: sort required: false - schema: type: string in: query name: search required: false - schema: type: string minLength: 1 in: path name: workflow_id required: true description: Workflow UUID or slug security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string name: type: string slug: type: string version_number: type: - number - 'null' is_published: type: boolean is_live: type: boolean environment: type: string workflow_version: description: 'Workflow engine version for this version: 2 = legacy, 3 = explicit-edges engine (loop/path/loop_break nodes available).' type: number published_at: type: - string - 'null' timestamp: type: string required: - id - name - slug - is_published - is_live - timestamp additionalProperties: false pagination: type: object properties: page: type: integer minimum: -9007199254740991 maximum: 9007199254740991 page_size: type: integer minimum: -9007199254740991 maximum: 9007199254740991 total_pages: type: integer minimum: -9007199254740991 maximum: 9007199254740991 total_records: type: integer minimum: -9007199254740991 maximum: 9007199254740991 has_next_page: type: boolean has_previous_page: type: boolean required: - page - page_size - total_pages - total_records - has_next_page - has_previous_page additionalProperties: false required: - data - pagination additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false /workflows/templates: get: summary: List workflow templates tags: - Workflows description: Returns a paginated list of available workflow templates. Each template includes a description and the inputs it accepts (marked as required or optional). Use a template's name in the `from_template.template` field when creating a workflow. parameters: - schema: default: 1 type: integer minimum: 1 maximum: 9007199254740991 in: query name: page required: false - schema: default: 50 type: integer minimum: 1 maximum: 100 in: query name: page_size required: false - schema: type: string in: query name: search required: false security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: data: type: array items: type: object properties: template: type: string description: type: string inputs: type: array items: type: object properties: name: type: string type: type: string required: type: boolean description: type: string options: type: array items: type: string default: type: string required: - name - type - required - description additionalProperties: false required: - template - description - inputs additionalProperties: false pagination: type: object properties: page: type: integer minimum: -9007199254740991 maximum: 9007199254740991 page_size: type: integer minimum: -9007199254740991 maximum: 9007199254740991 total_pages: type: integer minimum: -9007199254740991 maximum: 9007199254740991 total_records: type: integer minimum: -9007199254740991 maximum: 9007199254740991 has_next_page: type: boolean has_previous_page: type: boolean required: - page - page_size - total_pages - total_records - has_next_page - has_previous_page additionalProperties: false required: - data - pagination additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false /workflows/{workflow_id}/duplicate: post: summary: Duplicate a workflow tags: - Workflows description: 'Creates a copy of a workflow including all its nodes and configurations. The duplicated workflow is created as a new unpublished workflow with version number 1. If the source uses workflow engine v2, the duplicate remains an editable v2 draft and cannot be published through the public API until upgraded to v3. The existing published v2 source remains live and continues running until explicitly unpublished. - **name** — Optional. Display name for the new workflow. Defaults to `''{original name} Copy''`. - **version_id** — Optional. The specific version to duplicate. Defaults to the latest version of the source workflow. - **org_id** — Optional. Target organization for the copy. Defaults to the API key''s organization. Cross-org duplication requires access to both organizations. Sensitive configurations (e.g. phone numbers, SIP trunks) are cleared during duplication and must be reconfigured.' requestBody: content: application/json: schema: type: object properties: name: description: Display name for the new workflow. When omitted, defaults to '{original workflow name} Copy'. type: string minLength: 1 org_id: description: Target organization ID for the duplicated workflow. Defaults to the organization of the API key. Cross-org duplication requires access to both organizations. type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ version_id: description: The version to duplicate. When omitted, defaults to the latest version of the source workflow. type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ wait_for_test_all: default: false description: When true, block until the post-duplication test-all finishes and return per-node results in `test_all_results`. When false (default), test-all is fired in the background and the response returns immediately. type: boolean parameters: - schema: type: string minLength: 1 in: path name: workflow_id required: true description: Workflow UUID or slug security: - bearerAuth: [] responses: '201': description: Default Response content: application/json: schema: type: object properties: id: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ org_id: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ name: type: string slug: type: string icon: type: - string - 'null' folder_id: type: - string - 'null' format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ timestamp: type: string version: type: - object - 'null' properties: id: type: string name: type: string slug: type: string version_number: type: - number - 'null' is_published: type: boolean is_live: type: boolean environment: type: string workflow_version: description: 'Workflow engine version for this version: 2 = legacy, 3 = explicit-edges engine (loop/path/loop_break nodes available).' type: number published_at: type: - string - 'null' timestamp: type: string required: - id - name - slug - is_published - is_live - timestamp additionalProperties: false warnings: type: array items: type: string test_all_results: type: array items: type: object properties: node_id: type: string persistent_id: type: string name: type: string status: type: string enum: - success - failed - skipped error: type: string required: - node_id - persistent_id - name - status additionalProperties: false required: - id - org_id - name - slug - timestamp - version additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false /workflows/{workflow_id}/publish: post: summary: Publish a workflow tags: - Workflows description: 'Publishes the latest version of the specified workflow to make it live. Before publishing, all action nodes are checked for test errors and untested status. If untested nodes exist (with no errors), a synchronous test-all is triggered first. If any node has test errors, the publish is blocked and errors are returned. Workflow engine v2 versions cannot be published through the public API. Existing published v2 versions remain live and continue running until explicitly unpublished; this endpoint does not stop them. For an eligible v3 target, returns an error if the workflow already has a live version. After the target passes readiness checks, use the unpublish endpoint to take the current version offline, then retry the publish request. Accepts a workflow UUID or slug as the path parameter.' requestBody: content: application/json: schema: type: - object - 'null' properties: environment: default: production description: Target environment for publishing type: string enum: - production - staging - development parameters: - schema: type: string minLength: 1 in: path name: workflow_id required: true description: Workflow UUID or slug security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: id: type: string is_published: type: boolean is_live: type: boolean environment: type: string missing_variables: description: Variable references that could not be resolved against upstream nodes. Informational — does not block publishing. type: array items: type: object properties: node_id: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: The node containing the broken reference node_name: description: Display name of the node type: - string - 'null' missing_variables: type: array items: type: object properties: group_id: type: string description: The referenced variable group ID (persistent_id of the source node) variable_id: type: string description: The referenced variable ID within the group required: - group_id - variable_id additionalProperties: false description: Variable references that could not be resolved required: - node_id - node_name - missing_variables additionalProperties: false required: - id - is_published - is_live - environment additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: number errors: type: array items: type: object properties: node_id: type: string name: type: - string - 'null' error: type: string required: - node_id - name - error additionalProperties: false missing_variables: description: Variable references that could not be resolved against upstream nodes. type: array items: type: object properties: node_id: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: The node containing the broken reference node_name: description: Display name of the node type: - string - 'null' missing_variables: type: array items: type: object properties: group_id: type: string description: The referenced variable group ID (persistent_id of the source node) variable_id: type: string description: The referenced variable ID within the group required: - group_id - variable_id additionalProperties: false description: Variable references that could not be resolved required: - node_id - node_name - missing_variables additionalProperties: false required: - error - message - statusCode additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '403': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '502': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false /workflows/{workflow_id}/unpublish: post: summary: Unpublish a workflow tags: - Workflows description: Finds the currently live version for the workflow and unpublishes it. The version is taken offline and unlocked for editing. Returns 400 if no version is currently live. Accepts a workflow UUID or slug as the path parameter. parameters: - schema: type: string minLength: 1 in: path name: workflow_id required: true description: Workflow UUID or slug security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: id: type: string is_published: type: boolean is_live: type: boolean required: - id - is_published - is_live additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '502': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false /workflows/{workflow_id}/runs: get: summary: List workflow runs tags: - Workflows description: Returns paginated runs for a workflow. Supports filtering by status, date ranges, and annotation. parameters: - schema: default: 1 type: integer minimum: 1 maximum: 9007199254740991 in: query name: page required: false - schema: default: 100 type: integer minimum: 1 maximum: 2000 in: query name: page_size required: false - schema: default: desc type: string enum: - asc - desc in: query name: sort required: false - schema: type: string enum: - scheduled - running - completed - canceled - failed in: query name: status required: false - schema: anyOf: - type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ - type: string enum: - '' in: query name: start_date required: false - schema: anyOf: - type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ - type: string enum: - '' in: query name: end_date required: false - schema: anyOf: - type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ - type: string enum: - '' in: query name: completed_start_date required: false - schema: anyOf: - type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ - type: string enum: - '' in: query name: completed_end_date required: false - schema: type: string enum: - correct - incorrect - critical in: query name: annotation required: false - schema: type: string minLength: 1 in: path name: workflow_id required: true description: Workflow UUID or slug security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string status: type: string enum: - not_started - scheduled - running - skipped - succeeded - completed - canceled - failed org_id: type: string timestamp: type: string use_case_id: type: string version_id: type: string annotation: type: - string - 'null' enum: - correct - incorrect - critical completed_at: type: - string - 'null' input_tokens: type: - integer - 'null' minimum: -9007199254740991 maximum: 9007199254740991 output_tokens: type: - integer - 'null' minimum: -9007199254740991 maximum: 9007199254740991 data: type: object additionalProperties: {} required: - id - status - org_id - timestamp - use_case_id - version_id - annotation - completed_at - input_tokens - output_tokens - data additionalProperties: false pagination: type: object properties: page: type: integer minimum: 1 maximum: 9007199254740991 pageSize: type: integer minimum: 1 maximum: 9007199254740991 totalPages: type: integer minimum: 0 maximum: 9007199254740991 totalRecords: type: integer minimum: 0 maximum: 9007199254740991 hasNextPage: type: boolean hasPreviousPage: type: boolean required: - page - pageSize - totalPages - totalRecords - hasNextPage - hasPreviousPage additionalProperties: false required: - data - pagination additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false post: summary: Trigger a workflow run tags: - Workflows description: Starts a new run for a workflow by proxying to the hooks service. Accepts either a JSON body with payload/environment fields, or a multipart/form-data request with a file and optional form fields (pass environment as a query param for multipart). Supports targeting different environments (production, staging, development). parameters: - schema: type: string minLength: 1 in: path name: workflow_id required: true description: Workflow UUID or slug security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: run_id: type: string queued_run_ids: type: array items: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ status: type: string message: type: string additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '502': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false /workflows/{workflow_id}/sessions: get: summary: List workflow sessions tags: - Workflows description: Returns paginated sessions for a workflow across all runs, ordered by timestamp. parameters: - schema: default: 1 type: integer minimum: 1 maximum: 9007199254740991 in: query name: page required: false - schema: default: 50 type: integer minimum: 1 maximum: 100 in: query name: page_size required: false - schema: default: desc type: string enum: - asc - desc in: query name: sort required: false - schema: type: string minLength: 1 in: path name: workflow_id required: true description: Workflow UUID or slug security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ run_id: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ version_id: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ status: type: string type: type: string duration: type: - integer - 'null' minimum: -9007199254740991 maximum: 9007199254740991 timestamp: type: string failure_reason: type: - string - 'null' required: - id - run_id - version_id - status - type - duration - timestamp - failure_reason additionalProperties: false pagination: type: object properties: page: type: integer minimum: -9007199254740991 maximum: 9007199254740991 page_size: type: integer minimum: -9007199254740991 maximum: 9007199254740991 total_pages: type: integer minimum: -9007199254740991 maximum: 9007199254740991 total_records: type: integer minimum: -9007199254740991 maximum: 9007199254740991 has_next_page: type: boolean has_previous_page: type: boolean required: - page - page_size - total_pages - total_records - has_next_page - has_previous_page additionalProperties: false required: - data - pagination additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false /workflows/{workflow_id}/cancel-runs: post: summary: Cancel active workflow runs tags: - Workflows description: Cancels all current and queued runs for the workflow. By default, the currently live workflow version is also unpublished. Set unpublish_workflow to false to keep the workflow published after cancellation. Accepts a workflow UUID or slug as the path parameter. requestBody: content: application/json: schema: type: object properties: unpublish_workflow: type: boolean parameters: - schema: type: string minLength: 1 in: path name: workflow_id required: true description: Workflow UUID or slug security: - bearerAuth: [] responses: '200': description: Default Response content: application/json: schema: type: object properties: status: type: string workflow_toggle_result: type: - object - 'null' properties: success: type: boolean unpublished_version_id: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ message: type: string error: type: string required: - success additionalProperties: false required: - status - workflow_toggle_result additionalProperties: false '400': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '401': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '404': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '500': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false '502': description: Default Response content: application/json: schema: type: object properties: error: type: string message: type: string statusCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 details: {} required: - error additionalProperties: false components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Opaque