> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kapso.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve workflow definition

> Get the editor-oriented workflow payload for a specific workflow.

This endpoint returns everything needed to load the canvas:
- Base workflow metadata
- `definition.nodes` built from `flow_steps`
- `definition.edges` built from `flow_edges`

Response details:
- `definition.nodes[].id` is the workflow step identifier, not the database ID
- `definition.edges[].id` is the persisted edge UUID
- `definition.nodes[].data.node_type` is the canonical backend node type
- `definition.nodes[].data.config` changes shape by node type
- Config fields are returned in snake_case
- Function and call-workflow references are returned as IDs in the Platform API; the Kapso CLI can export them as slugs for local source repos

Use this endpoint when building or syncing a visual workflow editor, exporting a workflow graph, or cloning an existing workflow definition.




## OpenAPI

````yaml /api/platform/v1/openapi-workflows.yaml get /workflows/{workflow_id}/definition
openapi: 3.1.0
info:
  title: Kapso Platform API – Advanced Resources
  version: 0.1.0
  description: >
    Build WhatsApp automation workflows and serverless functions. Create
    multi-step conversation flows, inspect executions, and deploy custom logic.
servers:
  - url: https://api.kapso.ai/platform/v1
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Workflows
    description: Create and manage conversation workflows and executions
  - name: Workflow Triggers
    description: Configure workflow triggers to automate execution
  - name: Functions
    description: Manage serverless functions, deployments, and secrets
  - name: WhatsApp Conversations
    description: Query WhatsApp conversation data and related resources
paths:
  /workflows/{workflow_id}/definition:
    parameters:
      - name: workflow_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Workflow identifier
    get:
      tags:
        - Workflows
      summary: Retrieve workflow definition
      description: >
        Get the editor-oriented workflow payload for a specific workflow.


        This endpoint returns everything needed to load the canvas:

        - Base workflow metadata

        - `definition.nodes` built from `flow_steps`

        - `definition.edges` built from `flow_edges`


        Response details:

        - `definition.nodes[].id` is the workflow step identifier, not the
        database ID

        - `definition.edges[].id` is the persisted edge UUID

        - `definition.nodes[].data.node_type` is the canonical backend node type

        - `definition.nodes[].data.config` changes shape by node type

        - Config fields are returned in snake_case

        - Function and call-workflow references are returned as IDs in the
        Platform API; the Kapso CLI can export them as slugs for local source
        repos


        Use this endpoint when building or syncing a visual workflow editor,
        exporting a workflow graph, or cloning an existing workflow definition.
      operationId: getWorkflowDefinition
      responses:
        '200':
          description: Workflow definition retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowWithDefinitionResponse'
              example:
                data:
                  id: 2c2d03de-f8e5-4e9d-87fd-d168a8d04a6c
                  name: Lead qualification
                  description: Qualify inbound leads before handing off to sales
                  status: draft
                  lock_version: 3
                  message_debounce_seconds: 1
                  inbound_message_read_mode: read_with_typing
                  created_at: '2026-03-10T14:05:22.000Z'
                  updated_at: '2026-03-12T09:44:18.000Z'
                  project_id: 7b7d09f1-4f2d-477c-bb1c-0fc8d1bb6d3e
                  execution_count: 12
                  last_executed_at: '2026-03-12T09:40:05.000Z'
                  definition:
                    nodes:
                      - id: start
                        type: flow-node
                        position:
                          x: 120
                          'y': 80
                        data:
                          node_type: start
                          config: {}
                          display_name: Start
                      - id: send_intro
                        type: flow-node
                        position:
                          x: 380
                          'y': 80
                        data:
                          node_type: send_text
                          config:
                            whatsapp_config_id: ab11ff46-0f30-49e5-b5ef-a78662bc0ef1
                            phone_number_id: '15551234567'
                            message: Hi {{vars.first_name}}, thanks for contacting us.
                            delay_seconds: 0
                            provider_model_id: null
                            provider_model_name: null
                            ai_field_config: {}
                            to_phone_number: null
                          display_name: Send Text Message
                      - id: wait_reply
                        type: flow-node
                        position:
                          x: 660
                          'y': 80
                        data:
                          node_type: wait_for_response
                          config:
                            has_timeout: true
                            timeout_seconds: 300
                            save_response_to: latest_reply
                          display_name: Wait for response
                    edges:
                      - id: 6952ed87-5016-444d-a145-7339c4d3c642
                        source: start
                        target: send_intro
                        label: next
                        type: default
                        flow_condition_id: null
                      - id: 0c2b6fc5-eb0c-41cc-8dcf-6aa4f5dd6ca1
                        source: send_intro
                        target: wait_reply
                        label: next
                        type: default
                        flow_condition_id: null
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
components:
  schemas:
    WorkflowWithDefinitionResponse:
      type: object
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/WorkflowWithDefinition'
      description: >-
        Single workflow response including the canvas definition and editor
        metadata
    WorkflowWithDefinition:
      allOf:
        - $ref: '#/components/schemas/Workflow'
        - type: object
          required:
            - definition
          properties:
            definition:
              $ref: '#/components/schemas/WorkflowDefinition'
      description: >
        Expanded workflow payload returned by `GET
        /workflows/{workflow_id}/definition`.

        This is the editor-oriented response: it contains the workflow metadata
        plus the full canvas graph.
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable error message
    Workflow:
      type: object
      required:
        - id
        - name
        - slug
        - status
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
          description: Unique workflow identifier
        name:
          type: string
          description: Workflow name (unique per project)
        slug:
          type: string
          description: >
            URL-safe workflow identifier (lowercase alphanumeric with hyphens).
            Stable across renames — useful as an external sync key.
            Auto-generated from `name` on create if not provided. Unique within
            the project.
          pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
          example: inbound-support
        description:
          type:
            - string
            - 'null'
          description: Optional workflow description
        status:
          type: string
          enum:
            - draft
            - active
            - archived
          description: |
            Workflow lifecycle status:
            - `draft`: Under development, not executable
            - `active`: Published and executable
            - `archived`: Inactive, no longer in use
        lock_version:
          type:
            - integer
            - 'null'
          description: >
            Optimistic locking version. Increment on each update to prevent
            concurrent modification conflicts. Include this value when updating
            to ensure you're working with the latest version.
        message_debounce_seconds:
          type:
            - integer
            - 'null'
          description: >
            Debounce window for incoming messages in seconds (default: 1). When
            a user sends multiple messages rapidly, the workflow waits this
            duration before processing to batch messages together. Prevents
            workflow from reacting to every keystroke.
        agent_default_tools_version:
          type:
            - integer
            - 'null'
          description: >-
            Version used to decide which built-in agent tools are required by
            default for this workflow.
        inbound_message_read_mode:
          type: string
          enum:
            - disabled
            - read_only
            - read_with_typing
          description: >
            Controls how inbound WhatsApp messages are marked as read before the
            workflow responds (default: read_with_typing).

            - `disabled`: Do nothing — messages are not marked as read

            - `read_only`: Mark messages as read without showing a typing
            indicator

            - `read_with_typing`: Mark as read and show a typing indicator
            before responding
        created_at:
          type: string
          format: date-time
          description: Workflow creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Last modification timestamp
        project_id:
          type: string
          format: uuid
          description: Project this workflow belongs to
        execution_count:
          type: integer
          minimum: 0
          description: Total number of times this workflow has been executed
        last_executed_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Timestamp of most recent execution, null if never executed
    WorkflowDefinition:
      type: object
      required:
        - nodes
        - edges
      properties:
        nodes:
          type: array
          description: >
            Canvas nodes derived from `flow_steps`.

            `id` is the step identifier used inside the workflow definition, not
            the database primary key.
          items:
            $ref: '#/components/schemas/WorkflowDefinitionNode'
        edges:
          type: array
          description: Canvas edges derived from `flow_edges`.
          items:
            $ref: '#/components/schemas/WorkflowDefinitionEdge'
      description: Full workflow graph definition used by the canvas editor.
    WorkflowDefinitionNode:
      type: object
      required:
        - id
        - type
        - position
        - data
      properties:
        id:
          type: string
          description: >
            Stable step identifier within the workflow graph.

            This matches `flow_steps.identifier` and is what edges reference via
            `source` and `target`.
          example: send_intro
        type:
          type: string
          description: Canvas renderer type. The API currently returns `flow-node`.
          example: flow-node
        position:
          $ref: '#/components/schemas/WorkflowDefinitionNodePosition'
        data:
          $ref: '#/components/schemas/WorkflowDefinitionNodeData'
      description: A node in the workflow canvas.
    WorkflowDefinitionEdge:
      type: object
      required:
        - id
        - source
        - target
        - type
      properties:
        id:
          type: string
          format: uuid
          description: Edge identifier (`flow_edges.id`).
        source:
          type: string
          description: Source node identifier (`flow_steps.identifier`).
          example: start
        target:
          type: string
          description: Target node identifier (`flow_steps.identifier`).
          example: send_intro
        label:
          type:
            - string
            - 'null'
          description: Transition label, usually `next` or a decision branch label.
          example: next
        type:
          type: string
          description: Canvas edge renderer type. The API currently returns `default`.
          example: default
        flow_condition_id:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            Condition ID attached to decide-step edges. Null for non-decision
            edges.
      additionalProperties: false
      description: A directed transition between two workflow nodes.
    WorkflowDefinitionNodePosition:
      type: object
      required:
        - x
        - 'y'
      properties:
        x:
          type: number
          description: Horizontal canvas position.
          example: 360
        'y':
          type: number
          description: Vertical canvas position.
          example: 120
      additionalProperties: false
      description: Canvas position of the node.
    WorkflowDefinitionNodeData:
      type: object
      required:
        - node_type
        - config
        - display_name
      properties:
        node_type:
          type: string
          description: >
            Persisted workflow node type.


            Common values returned by the Rails serializer:

            - `start`

            - action node types from executable actions such as `send_text`,
            `send_template`, `send_interactive`, `webhook`, `set_variable`,
            `handoff`

            - `wait_for_response`

            - `decide`

            - `agent`

            - `call`
          example: wait_for_response
        config:
          description: >
            Node configuration payload. Shape depends on `node_type`.


            Built-in shapes returned by the definition endpoint:

            - `start`: empty object

            - `wait_for_response`: timeout and variable capture settings

            - `decide`: decision strategy, branches, and model/function settings

            - `agent`: model settings plus nested tools, webhooks, knowledge
            bases, and MCP servers

            - `call`: referenced workflow ID/name and error variable mapping


            Action nodes use the underlying action model's `to_config` output,
            so keys vary by action type.
          anyOf:
            - $ref: '#/components/schemas/WorkflowNodeStartConfig'
            - $ref: '#/components/schemas/WorkflowNodeSendTextConfig'
            - $ref: '#/components/schemas/WorkflowNodeSendTemplateConfig'
            - $ref: '#/components/schemas/WorkflowNodeSendInteractiveConfig'
            - $ref: '#/components/schemas/WorkflowNodeWaitForResponseConfig'
            - $ref: '#/components/schemas/WorkflowNodeDecideConfig'
            - $ref: '#/components/schemas/WorkflowNodeFunctionConfig'
            - $ref: '#/components/schemas/WorkflowNodeWebhookConfig'
            - $ref: '#/components/schemas/WorkflowNodeAgentConfig'
            - $ref: '#/components/schemas/WorkflowNodeCallConfig'
            - $ref: '#/components/schemas/WorkflowNodeHandoffConfig'
            - $ref: '#/components/schemas/WorkflowNodeSetVariableConfig'
            - $ref: '#/components/schemas/WorkflowNodeEmitEventConfig'
            - type: object
              additionalProperties: true
        display_name:
          type: string
          description: Human-friendly label shown in the visual editor.
          example: Wait for response
      additionalProperties: false
      description: Node payload rendered under `definition.nodes[].data`.
    WorkflowNodeStartConfig:
      type: object
      additionalProperties: false
      description: Empty config for the `start` node.
    WorkflowNodeSendTextConfig:
      type: object
      required:
        - message
      properties:
        message:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
          description: >-
            Text message body. Supports workflow variable interpolation such as
            `{{vars.customer_name}}`.
          example: Hi {{vars.customer_name}}, how can we help?
        phone_number_id:
          type:
            - string
            - 'null'
          description: >-
            Preferred WhatsApp Business phone number ID to send from. If
            omitted, Kapso uses the conversation's phone number.
        whatsapp_config_id:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            Legacy internal WhatsApp config ID. Prefer `phone_number_id` for new
            integrations.
        to_phone_number:
          type:
            - string
            - 'null'
          description: >-
            Override destination phone number. Mainly used by observer-mode
            workflows that are not attached to an inbound conversation.
        delay_seconds:
          type:
            - integer
            - 'null'
          minimum: 0
          description: Delay before sending the message.
        provider_model_id:
          type:
            - string
            - 'null'
          format: uuid
          description: AI model ID used when resolving AI fields.
        provider_model_name:
          type:
            - string
            - 'null'
          description: AI model name used when resolving AI fields.
        ai_field_config:
          type: object
          additionalProperties: true
          description: AI field-resolution settings.
      additionalProperties: false
      description: Config for `send_text` nodes.
    WorkflowNodeSendTemplateConfig:
      type: object
      required:
        - template_id
      properties:
        template_id:
          type: string
          format: uuid
          description: WhatsApp template ID.
        template_name:
          type:
            - string
            - 'null'
          description: Template name returned by definition responses.
        parameters:
          description: >-
            Template parameters. Supports Meta components format,
            `template_params`, arrays, and objects.
        phone_number_id:
          type:
            - string
            - 'null'
          description: >-
            Preferred WhatsApp Business phone number ID to send from. If
            omitted, Kapso uses the conversation's phone number.
        whatsapp_config_id:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            Legacy internal WhatsApp config ID. Prefer `phone_number_id` for new
            integrations.
        to_phone_number:
          type:
            - string
            - 'null'
          description: Override destination phone number.
        provider_model_id:
          type:
            - string
            - 'null'
          format: uuid
        provider_model_name:
          type:
            - string
            - 'null'
        ai_field_config:
          type: object
          additionalProperties: true
      additionalProperties: false
      description: Config for `send_template` nodes.
    WorkflowNodeSendInteractiveConfig:
      type: object
      required:
        - interactive_type
        - body_text
      properties:
        interactive_type:
          type: string
          enum:
            - button
            - list
            - cta_url
            - flow
            - product
            - product_list
            - catalog_message
            - location_request_message
          description: WhatsApp interactive message type.
        body_text:
          oneOf:
            - type: string
              maxLength: 1024
            - type: object
              additionalProperties: true
          description: Main message body.
        footer_text:
          type:
            - string
            - 'null'
        header_type:
          type:
            - string
            - 'null'
          enum:
            - none
            - text
            - image
            - video
            - document
            - null
        header_text:
          type:
            - string
            - 'null'
        header_media_url:
          type:
            - string
            - 'null'
        buttons:
          type: array
          maxItems: 3
          items:
            $ref: '#/components/schemas/WorkflowNodeInteractiveButton'
        list_button_text:
          type:
            - string
            - 'null'
        list_sections:
          type: array
          maxItems: 10
          items:
            $ref: '#/components/schemas/WorkflowNodeInteractiveListSection'
        cta_display_text:
          type:
            - string
            - 'null'
        cta_url:
          type:
            - string
            - 'null'
        flow_id:
          type:
            - string
            - 'null'
        flow_cta:
          type:
            - string
            - 'null'
        flow_token:
          type:
            - string
            - 'null'
        flow_action:
          type:
            - string
            - 'null'
          enum:
            - navigate
            - data_exchange
            - null
        flow_action_payload:
          type:
            - object
            - 'null'
          additionalProperties: true
        header_config:
          type:
            - object
            - 'null'
          additionalProperties: true
          description: Legacy expanded header config returned by definition responses.
        action_config:
          type:
            - object
            - 'null'
          additionalProperties: true
          description: Legacy expanded action config returned by definition responses.
        phone_number_id:
          type:
            - string
            - 'null'
          description: >-
            Preferred WhatsApp Business phone number ID to send from. If
            omitted, Kapso uses the conversation's phone number.
        whatsapp_config_id:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            Legacy internal WhatsApp config ID. Prefer `phone_number_id` for new
            integrations.
        to_phone_number:
          type:
            - string
            - 'null'
          description: Override destination phone number.
        provider_model_id:
          type:
            - string
            - 'null'
          format: uuid
        provider_model_name:
          type:
            - string
            - 'null'
        ai_field_config:
          type: object
          additionalProperties: true
      additionalProperties: false
      description: Config for `send_interactive` nodes.
    WorkflowNodeWaitForResponseConfig:
      type: object
      properties:
        has_timeout:
          type: boolean
          description: Whether the wait step automatically times out.
        timeout_seconds:
          type:
            - integer
            - 'null'
          description: Timeout duration in seconds when `has_timeout` is true.
        save_response_to:
          type:
            - string
            - 'null'
          description: Variable name where the incoming response should be stored.
      additionalProperties: false
      description: Config returned for `wait_for_response` nodes.
    WorkflowNodeDecideConfig:
      type: object
      required:
        - decision_type
        - conditions
        - llm_configuration
      properties:
        decision_type:
          type: string
          enum:
            - ai
            - function
          description: Whether branching is evaluated by an AI model or a Kapso function.
        conditions:
          type: array
          description: Ordered branch definitions for the decide step.
          items:
            $ref: '#/components/schemas/WorkflowNodeDecideCondition'
        llm_configuration:
          type: object
          description: Additional LLM configuration stored on the decide step.
          additionalProperties: true
        function_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Referenced function ID when `decision_type=function`.
        function_name:
          type:
            - string
            - 'null'
          description: Referenced function name when `decision_type=function`.
        provider_model_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Referenced model ID when `decision_type=ai`.
        provider_model_name:
          type:
            - string
            - 'null'
          description: Referenced model name when `decision_type=ai`.
        llm_temperature:
          type:
            - number
            - 'null'
          description: Sampling temperature for AI decisions.
        llm_max_tokens:
          type:
            - integer
            - 'null'
          description: Max output tokens for AI decisions.
      additionalProperties: false
      description: Config returned for `decide` nodes.
    WorkflowNodeFunctionConfig:
      type: object
      required:
        - function_id
      properties:
        function_id:
          type: string
          format: uuid
          description: Kapso Function ID to execute.
        function_name:
          type:
            - string
            - 'null'
          description: Function name returned by definition responses.
        save_response_to:
          type:
            - string
            - 'null'
          description: Variable name where the function response should be stored.
      additionalProperties: false
      description: Config for `function` nodes.
    WorkflowNodeWebhookConfig:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          description: External URL to call.
        method:
          type: string
          enum:
            - GET
            - POST
            - PUT
            - PATCH
            - DELETE
          default: POST
        headers:
          oneOf:
            - type: object
              additionalProperties:
                type: string
            - type: string
          description: >-
            HTTP headers. Object form is preferred; definition responses may
            contain JSON strings for legacy webhook actions.
        body_template:
          description: >-
            Request body template. Object form is preferred; definition
            responses may contain JSON strings for legacy webhook actions.
        provider_model_id:
          type:
            - string
            - 'null'
          format: uuid
        provider_model_name:
          type:
            - string
            - 'null'
        ai_field_config:
          type: object
          additionalProperties: true
        save_response_to:
          type:
            - string
            - 'null'
          description: Variable name where the webhook response should be stored.
      additionalProperties: false
      description: Config for `webhook` nodes.
    WorkflowNodeAgentConfig:
      type: object
      properties:
        system_prompt:
          type:
            - string
            - 'null'
        provider_model_id:
          type:
            - string
            - 'null'
          format: uuid
        provider_model_name:
          type:
            - string
            - 'null'
        temperature:
          type:
            - number
            - 'null'
        max_iterations:
          type:
            - integer
            - 'null'
        max_tokens:
          type:
            - integer
            - 'null'
        reasoning_effort:
          type:
            - string
            - 'null'
          enum:
            - none
            - minimal
            - low
            - medium
            - high
            - xhigh
            - null
        observer_prompt_mode:
          type: string
          enum:
            - analysis_only
            - interactive_chat
          description: Prompt orchestration mode used by the flow agent.
        message_delivery_mode:
          type: string
          enum:
            - auto_send_assistant_text
            - tool_only
          default: auto_send_assistant_text
          description: >
            Controls how assistant text becomes user-visible.

            - `auto_send_assistant_text`: normal assistant text responses are
            sent to the WhatsApp user automatically.

            - `tool_only`: normal assistant text is internal only; the agent
            must call `send_notification_to_user` to send user-visible messages.
        enabled_default_tools:
          type: array
          items:
            type: string
          description: Built-in agent tools enabled for this node.
          example:
            - emit_event
            - complete_task
        default_tool_configs:
          type: object
          description: Optional configuration for built-in agent tools.
          properties:
            emit_event:
              type: object
              description: Configuration for the built-in `emit_event` tool.
              properties:
                event_definition_ids:
                  type: array
                  description: >-
                    Optional allowlist of project event definition IDs the agent
                    may emit. Omit or leave empty to allow any valid project
                    event.
                  items:
                    type: string
                    format: uuid
              additionalProperties: false
          additionalProperties: true
        flow_agent_function_tools:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowNodeAgentFunctionTool'
        flow_agent_webhooks:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowNodeAgentWebhook'
        flow_agent_knowledge_bases:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowNodeAgentKnowledgeBase'
        flow_agent_mcp_servers:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowNodeAgentMcpServer'
        flow_agent_resources:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowNodeAgentResource'
      additionalProperties: false
      description: Config returned for `agent` nodes.
    WorkflowNodeCallConfig:
      type: object
      properties:
        workflow_id:
          type:
            - string
            - 'null'
          format: uuid
          description: ID of the called workflow.
        workflow_name:
          type:
            - string
            - 'null'
          description: Name of the called workflow.
        save_error_to:
          type:
            - string
            - 'null'
          description: Variable name where child-workflow errors should be stored.
      additionalProperties: false
      description: Config returned for `call` nodes.
    WorkflowNodeHandoffConfig:
      type: object
      properties:
        reason:
          type:
            - string
            - 'null'
          description: Optional reason stored with the handoff event.
        context_data:
          description: >-
            Optional context payload made available to the human handoff
            process.
      additionalProperties: false
      description: Config for `handoff` nodes.
    WorkflowNodeSetVariableConfig:
      type: object
      required:
        - variable_name
        - variable_value
      properties:
        variable_name:
          type: string
          description: Workflow variable name to set.
        variable_value:
          description: Value to store. Strings support variable interpolation.
        value_type:
          type: string
          enum:
            - string
            - number
            - boolean
            - json
          default: string
          description: Value coercion mode.
      additionalProperties: false
      description: Config for `set_variable` nodes.
    WorkflowNodeEmitEventConfig:
      type: object
      required:
        - event_name
      properties:
        event_name:
          type: string
          description: Lowercase dotted snake_case Project Event name to emit.
          example: conversation.csat_scored
        properties:
          type: object
          additionalProperties:
            oneOf:
              - type: string
              - type: number
              - type: boolean
              - type: 'null'
          description: >-
            Flat scalar Project Event properties. Values may be string, number,
            boolean, or null.
          example:
            score: 5
            source: workflow
        occurred_at:
          type:
            - string
            - 'null'
          description: >-
            Optional ISO 8601 timestamp or workflow variable. Leave blank to use
            current time.
          example: '{{vars.scored_at}}'
      additionalProperties: false
      description: Config for `emit_event` nodes.
    WorkflowNodeInteractiveButton:
      type: object
      required:
        - id
        - title
      properties:
        id:
          type: string
          description: Stable button payload ID.
        title:
          type: string
          maxLength: 20
          description: Button label shown to the user.
      additionalProperties: false
    WorkflowNodeInteractiveListSection:
      type: object
      required:
        - rows
      properties:
        title:
          type: string
        rows:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowNodeInteractiveListRow'
      additionalProperties: false
    WorkflowNodeDecideCondition:
      type: object
      required:
        - id
        - label
      properties:
        id:
          type: string
          format: uuid
          description: Condition identifier.
        label:
          type: string
          description: Edge label emitted by this condition.
          example: qualified
        description:
          type:
            - string
            - 'null'
          description: Human-readable condition description.
      additionalProperties: false
      description: A branch option inside a decide step.
    WorkflowNodeAgentFunctionTool:
      type: object
      properties:
        name:
          type: string
        description:
          type:
            - string
            - 'null'
        function_id:
          type:
            - string
            - 'null'
          format: uuid
        function_name:
          type:
            - string
            - 'null'
        input_schema:
          type: object
          description: JSON Schema-like input contract exposed to the agent.
          additionalProperties: true
      additionalProperties: false
      description: Function tool attached to an agent node.
    WorkflowNodeAgentWebhook:
      type: object
      properties:
        name:
          type: string
        description:
          type:
            - string
            - 'null'
        url:
          type:
            - string
            - 'null'
          description: URL the agent can call.
        http_method:
          type:
            - string
            - 'null'
          description: HTTP method used for the request.
        headers:
          type:
            - object
            - 'null'
          additionalProperties: true
        body:
          description: Request body template.
        body_schema:
          type:
            - object
            - 'null'
          description: Optional schema describing the request/response payload.
          additionalProperties: true
        jmespath_query:
          type:
            - string
            - 'null'
          description: Optional JMESPath projection applied to the response.
        ai_field_config:
          type: object
          description: AI field-resolution settings for dynamic fields.
          additionalProperties: true
      additionalProperties: false
      description: Custom webhook tool attached to an agent node.
    WorkflowNodeAgentKnowledgeBase:
      type: object
      properties:
        name:
          type: string
        description:
          type:
            - string
            - 'null'
        knowledge_base_text:
          type:
            - string
            - 'null'
          description: Inline knowledge base content available to the agent.
      additionalProperties: false
      description: Inline knowledge base attached to an agent node.
    WorkflowNodeAgentMcpServer:
      type: object
      properties:
        name:
          type: string
        description:
          type:
            - string
            - 'null'
        url:
          type:
            - string
            - 'null'
          description: MCP server base URL.
        headers:
          type:
            - object
            - 'null'
          additionalProperties: true
      additionalProperties: false
      description: MCP server definition attached to an agent node.
    WorkflowNodeAgentResource:
      type: object
      properties:
        id:
          type:
            - string
            - 'null'
          format: uuid
          description: Resource ID returned by definition responses.
        resource_type:
          type: string
          enum:
            - github_repository
          description: Resource type. v1 supports GitHub repositories.
        repo_url:
          type: string
          description: GitHub repository URL.
          example: https://github.com/org/repo
        owner:
          type:
            - string
            - 'null'
          description: Repository owner returned by definition responses.
        repo_name:
          type:
            - string
            - 'null'
          description: Repository name returned by definition responses.
        branch:
          type:
            - string
            - 'null'
          description: Branch to clone. Defaults to the repository default branch.
        pat:
          type:
            - string
            - 'null'
          description: >-
            GitHub Personal Access Token. Accepted on write; never returned by
            the API.
        has_pat:
          type:
            - boolean
            - 'null'
          description: Returned when credentials are stored for the resource.
        imported_missing_pat:
          type:
            - boolean
            - 'null'
          description: >-
            Returned when an imported resource references credentials that were
            not present in the write payload.
      additionalProperties: false
      description: Repository resource mounted into an agent sandbox.
    WorkflowNodeInteractiveListRow:
      type: object
      required:
        - id
        - title
      properties:
        id:
          type: string
        title:
          type: string
          maxLength: 24
        description:
          type: string
          maxLength: 72
      additionalProperties: false
  responses:
    UnauthorizedError:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFoundError:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````