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

# Update workflow

> Update workflow metadata or replace workflow definition collections.

Common updates:
- Change workflow name or description
- Update workflow definition nodes and edges
- Activate workflow by setting status to 'active'
- Archive workflow by setting status to 'archived'

Definition update semantics:
- Omit `definition` to update metadata only.
- Omit `definition.nodes` to leave nodes unchanged.
- Include `definition.nodes` only when sending the complete desired node set. Nodes omitted from that array are removed.
- Omit `definition.edges` to leave edges unchanged.
- Include `definition.edges` only when sending the complete desired edge set. Edges omitted from that array are removed.
- Use snake_case config keys in API payloads.

Successful responses contain workflow metadata, including the new `lock_version`. They do not include the expanded graph. Call `GET /workflows/{workflow_id}/definition` after updating when you need the saved nodes and edges.

You can update the definition of an active workflow. Changes take effect immediately for new executions; running executions continue with the snapshot they started with.




## OpenAPI

````yaml /api/platform/v1/openapi-workflows.yaml patch /workflows/{workflow_id}
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}:
    parameters:
      - name: workflow_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Workflow identifier
    patch:
      tags:
        - Workflows
      summary: Update workflow
      description: >
        Update workflow metadata or replace workflow definition collections.


        Common updates:

        - Change workflow name or description

        - Update workflow definition nodes and edges

        - Activate workflow by setting status to 'active'

        - Archive workflow by setting status to 'archived'


        Definition update semantics:

        - Omit `definition` to update metadata only.

        - Omit `definition.nodes` to leave nodes unchanged.

        - Include `definition.nodes` only when sending the complete desired node
        set. Nodes omitted from that array are removed.

        - Omit `definition.edges` to leave edges unchanged.

        - Include `definition.edges` only when sending the complete desired edge
        set. Edges omitted from that array are removed.

        - Use snake_case config keys in API payloads.


        Successful responses contain workflow metadata, including the new
        `lock_version`. They do not include the expanded graph. Call `GET
        /workflows/{workflow_id}/definition` after updating when you need the
        saved nodes and edges.


        You can update the definition of an active workflow. Changes take effect
        immediately for new executions; running executions continue with the
        snapshot they started with.
      operationId: updateWorkflow
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowUpdateRequest'
      responses:
        '200':
          description: Workflow updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          description: >-
            Conflict — the supplied `lock_version` is stale. Refetch the
            workflow to get the current version and retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  schemas:
    WorkflowUpdateRequest:
      type: object
      required:
        - workflow
      properties:
        workflow:
          type: object
          properties:
            name:
              type: string
              description: Workflow name (must be unique within project)
            slug:
              type: string
              description: >
                URL-safe identifier. Slug is decoupled from name — renaming the
                workflow does not change the slug, you must update it
                explicitly.
              pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
              example: inbound-support
            description:
              type:
                - string
                - 'null'
              description: Workflow description
            status:
              type: string
              enum:
                - draft
                - active
                - archived
              description: Workflow lifecycle status
            message_debounce_seconds:
              type:
                - integer
                - 'null'
              description: 'Debounce window for incoming messages in seconds (default: 1)'
            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.

                - `disabled`: Do nothing

                - `read_only`: Mark as read, no typing indicator

                - `read_with_typing`: Mark as read and show typing indicator
                (default)
            lock_version:
              type: integer
              description: >-
                Current optimistic lock version. Required to prevent concurrent
                modification conflicts.
            definition:
              $ref: '#/components/schemas/WorkflowDefinitionInput'
              description: >
                Updated workflow graph structure. Omit `definition` to update
                metadata only. Inside `definition`, omit `nodes` or `edges` to
                leave that collection unchanged; include `nodes` or `edges` only
                when sending the complete desired set for that collection.
    WorkflowResponse:
      type: object
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/Workflow'
      description: Single workflow response
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable error message
    WorkflowDefinitionInput:
      type: object
      properties:
        nodes:
          type: array
          description: >
            Desired node set for the workflow. When `nodes` is present on create
            or update, it is treated as the complete node set: nodes omitted
            from the array are removed. Omit `nodes` to leave existing nodes
            unchanged on update.
          items:
            $ref: '#/components/schemas/WorkflowDefinitionInputNode'
        edges:
          type: array
          description: >
            Desired edge set for the workflow. When `edges` is present on create
            or update, it is treated as the complete edge set: edges omitted
            from the array are removed. Omit `edges` to leave existing edges
            unchanged on update.
          items:
            $ref: '#/components/schemas/WorkflowDefinitionInputEdge'
      additionalProperties: false
      description: >
        Workflow graph write payload. Field names are snake_case. The expanded
        definition response includes persisted IDs such as edge IDs and
        condition IDs; those IDs are optional in write payloads.
    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
    WorkflowDefinitionInputNode:
      type: object
      required:
        - id
        - position
        - data
      properties:
        id:
          type: string
          description: >-
            Stable step identifier used by edges. Use a readable identifier such
            as `send_intro`.
          pattern: ^[A-Za-z][A-Za-z0-9_-]*$
          example: send_intro
        type:
          type: string
          description: Canvas renderer type. Use `flow-node`.
          example: flow-node
        position:
          $ref: '#/components/schemas/WorkflowDefinitionNodePosition'
        data:
          $ref: '#/components/schemas/WorkflowDefinitionInputNodeData'
      additionalProperties: false
      description: Node write payload.
    WorkflowDefinitionInputEdge:
      type: object
      required:
        - source
        - target
      properties:
        id:
          type: string
          format: uuid
          description: Optional existing edge ID. Usually omitted for new edges.
        source:
          type: string
          description: Source node identifier.
          example: start
        target:
          type: string
          description: Target node identifier.
          example: send_intro
        label:
          type: string
          description: >-
            Transition label. Use `next` for non-decision nodes. For decide
            nodes, this must match a condition label.
          default: next
          example: next
        type:
          type: string
          description: Optional canvas edge renderer type. The API returns `default`.
          example: default
        flow_condition_id:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            Optional persisted condition ID for decide-step edges. If omitted,
            the API resolves decide edges by `label`.
      additionalProperties: false
      description: Edge write payload.
    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.
    WorkflowDefinitionInputNodeData:
      type: object
      required:
        - node_type
        - config
      properties:
        node_type:
          type: string
          enum:
            - start
            - send_text
            - send_template
            - send_interactive
            - wait_for_response
            - decide
            - function
            - webhook
            - agent
            - call
            - handoff
            - set_variable
          description: Canonical backend node type.
        config:
          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'
          description: Node configuration. Shape depends on `node_type`.
        display_name:
          type: string
          description: Optional human-friendly label shown in the visual editor.
      additionalProperties: false
      description: Node data write payload.
    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.
        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.
    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'
    ValidationError:
      description: Request validation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````