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

# Create an assistant (agent + workflow) as one unit

> Create an assistant (agent + parent workflow) with an inactive initial
revision in one transaction. Activate explicitly to go live.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/assistants
openapi: 3.1.0
info:
  title: Feather API
  description: >-
    Unified customer experience platform API. Manages identity, conversations,
    memory, agents, procedures, policies, model routing, knowledge bases,
    integrations, and runtime execution.
  version: 1.87.0
servers:
  - url: https://api-sandbox.featherhq.com
    description: Sandbox
  - url: http://localhost:8000
    description: Local dev
security: []
paths:
  /v1/assistants:
    post:
      tags:
        - assistants
      summary: Create an assistant (agent + workflow) as one unit
      description: |-
        Create an assistant (agent + parent workflow) with an inactive initial
        revision in one transaction. Activate explicitly to go live.
      operationId: createAssistantComposite
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssistantCreateComposite'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantCompositeResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    AssistantCreateComposite:
      properties:
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        persona:
          anyOf:
            - type: string
            - type: 'null'
          title: Persona
        system_prompt:
          anyOf:
            - type: string
            - type: 'null'
          title: System Prompt
        system_context_variables:
          anyOf:
            - items:
                $ref: '#/components/schemas/SystemContextVariableSpec'
              type: array
            - type: 'null'
          title: System Context Variables
        context_variables:
          anyOf:
            - items:
                $ref: '#/components/schemas/LegacySystemContextVariableSpec'
              type: array
            - type: 'null'
          title: Context Variables
          description: Deprecated alias for system_context_variables.
          deprecated: true
        variable_defaults:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Variable Defaults
        channel_specific_config:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Channel Specific Config
        router_config_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Router Config Id
        model_settings:
          anyOf:
            - $ref: '#/components/schemas/ModelChainEntry'
            - type: 'null'
        current_time:
          anyOf:
            - $ref: '#/components/schemas/CurrentTimeSettings'
            - type: 'null'
        analyzer_model_settings:
          anyOf:
            - $ref: '#/components/schemas/ModelChainEntry'
            - type: 'null'
          description: >-
            Assistant-revision override for the bound workflow analyzer; stored
            but inactive while the assistant has no effective workflow.
        memory_enabled:
          type: boolean
          title: Memory Enabled
          description: Enable semantic memory recall and ingestion for this revision.
          default: true
        router_model_settings:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Router Model Settings
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
        kb_clearance_level:
          anyOf:
            - type: integer
            - type: 'null'
          title: Kb Clearance Level
        kb_audience_tags:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Kb Audience Tags
        knowledge_gap_analysis_enabled:
          type: boolean
          title: Knowledge Gap Analysis Enabled
          default: true
        tool_refs:
          anyOf:
            - items:
                $ref: '#/components/schemas/ToolRef'
              type: array
            - type: 'null'
          title: Tool Refs
        knowledge_base_refs:
          anyOf:
            - items:
                $ref: '#/components/schemas/KnowledgeBaseRef'
              type: array
            - type: 'null'
          title: Knowledge Base Refs
        instructions:
          type: string
          title: Instructions
          default: ''
        workflow_description:
          anyOf:
            - type: string
            - type: 'null'
          title: Workflow Description
      additionalProperties: false
      type: object
      required:
        - name
      title: AssistantCreateComposite
      description: >-
        Request body for POST /assistants — create an agent + workflow as one
        unit.


        Q1: every assistant gets a workflow shell at creation; an empty flow

        (``instructions=""``) is legal and runs the bare-agent path.
    AssistantCompositeResponse:
      properties:
        agent:
          $ref: '#/components/schemas/AgentResponse'
        agent_revision:
          $ref: '#/components/schemas/AgentRevisionResponse'
        workflow:
          $ref: '#/components/schemas/WorkflowResponse'
        workflow_revision_id:
          type: string
          format: uuid
          title: Workflow Revision Id
      type: object
      required:
        - agent
        - agent_revision
        - workflow
        - workflow_revision_id
      title: AssistantCompositeResponse
      description: Response for POST /assistants — the created agent + workflow.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SystemContextVariableSpec:
      properties:
        name:
          type: string
          title: Name
        type:
          type: string
          enum:
            - string
            - int
            - float
            - bool
            - enum
          title: Type
        enum_values:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Enum Values
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
      additionalProperties: false
      type: object
      required:
        - name
        - type
      title: SystemContextVariableSpec
      description: >-
        An immutable assistant input available to prompts, policies, and tools.


        Assistant scope intentionally has no ``source`` or ``reask_cap`` knobs.
        The source is

        structurally ``system`` and the value is seeded once; extraction/re-ask
        semantics belong to

        workflow-derived variables.
    LegacySystemContextVariableSpec:
      properties:
        name:
          type: string
          title: Name
        type:
          type: string
          enum:
            - string
            - int
            - float
            - bool
            - enum
          title: Type
        enum_values:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Enum Values
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        source:
          anyOf:
            - type: string
              const: system
            - type: 'null'
          title: Source
        reask_cap:
          type: 'null'
          title: Reask Cap
      additionalProperties: false
      type: object
      required:
        - name
        - type
      title: LegacySystemContextVariableSpec
      description: >-
        Deprecated assistant alias shape accepted for response round-tripping.


        Older clients commonly write the response representation back through

        ``context_variables``. Permit its redundant system marker and null
        workflow-only

        field without weakening the canonical, source-free assistant request
        schema.
    ModelChainEntry:
      properties:
        model:
          type: string
          title: Model
        config:
          $ref: '#/components/schemas/ModelConfig'
      type: object
      required:
        - model
      title: ModelChainEntry
    CurrentTimeSettings:
      properties:
        enabled:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Enabled
        timezone:
          anyOf:
            - type: string
            - type: 'null'
          title: Timezone
      additionalProperties: false
      type: object
      title: CurrentTimeSettings
      description: >-
        One tier's optional current-time overrides.


        ``None`` means inherit for that field. An empty object therefore clears
        the tier and inherits

        both values. The API stores only non-null fields.
    ToolRef:
      properties:
        kind:
          type: string
          enum:
            - api
            - integration
            - util
            - kb
          title: Kind
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
        slug:
          anyOf:
            - type: string
            - type: 'null'
          title: Slug
        output_bindings:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Output Bindings
        input_defaults:
          anyOf:
            - additionalProperties:
                $ref: '#/components/schemas/InputArgConfig'
              type: object
            - type: 'null'
          title: Input Defaults
      type: object
      required:
        - kind
      title: ToolRef
      description: >-
        Canonical tool reference — API tool, integration tool, built-in util, or
        KB retrieval.


        ``util`` lets a graph author explicitly opt a built-in utility
        (``util:*``)

        into a node's user-declared tool surface.


        ``kb`` is the runtime-synthesized retrieval reference for an attached
        knowledge

        base (``id`` = the KB's UUID). Graphs author KB attachment via

        ``KnowledgeBaseRef`` (node- or step-level), never by storing a ``kb``
        ToolRef;

        the runtime builds these when surfacing a KB as a model-callable tool or
        when

        executing a ``knowledge_retrieval`` action step.


        ``output_bindings`` maps a declared context-variable name to a dot-path
        into

        this tool's result payload (``record_zip:
        "investmentProperty.address.zip"``).

        When the tool returns successfully on an agent node, the runtime binds
        the

        selected fields into ``context_vars`` MECHANICALLY — no LLM
        transcription —

        so downstream expressions (``eq_normalized(property_zip, record_zip,
        "zip")``)

        compare against ground truth. A missing field or a null value leaves the

        variable unset, which expressions observe via ``missing(<var>)`` — that
        IS

        the mechanical lookup-failure signal; nothing extra is recorded.


        ``input_defaults`` is the operator-set tool-input config (ENG-637/674)
        folded

        inline onto the attachment: ``{field: {"value": ..., "type":
        "default"|"pinned"}}``.

        The ref's own ``canonical_key()`` is the implied tool key, so the
        attachment

        and its arg defaults/pins live as one entry (no parallel keyed column).
        Used by

        the agent attachment path; the workflow compiler never sets it (workflow

        tool-input config lives on ``WorkflowRevision.tool_input_defaults``),
        and it

        does not feed the compile cache hash — so leaving it ``None`` on
        compiled graph

        refs is a no-op. ``None`` = no operator config on this attachment.
    KnowledgeBaseRef:
      properties:
        id:
          type: string
          title: Id
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        clearance_level:
          anyOf:
            - type: integer
            - type: 'null'
          title: Clearance Level
      type: object
      required:
        - id
      title: KnowledgeBaseRef
      description: >-
        Canonical knowledge base reference.


        ``description`` is the compiler-emitted usage intent for this KB
        (when/why

        to query it).


        ``clearance_level`` (ENG-648 P4) optionally CAPS this reference's
        retrieval

        clearance below the agent revision's default — a finer-grained, per-node

        restriction. It can only lower (never raise above) the agent's clearance
        and

        is resolved at peer-build time into the executor's access context.
        ``None``

        ⇒ use the agent default. Stored on the graph IR (no DB migration).
    AgentResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        organization_id:
          type: string
          format: uuid
          title: Organization Id
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        active_revision_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Active Revision Id
        active_revision:
          anyOf:
            - $ref: '#/components/schemas/AgentRevisionResponse'
            - type: 'null'
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
        platform_tools:
          additionalProperties: true
          type: object
          title: Platform Tools
        knowledge_gap_analysis_enabled:
          type: boolean
          title: Knowledge Gap Analysis Enabled
          default: true
        release_suite_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Release Suite Id
        release_gate_mode:
          $ref: '#/components/schemas/ReleaseGateMode'
          default: 'off'
        release_gate_max_failures:
          type: integer
          title: Release Gate Max Failures
          default: 0
        max_active_calls:
          anyOf:
            - type: integer
            - type: 'null'
          title: Max Active Calls
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
        - id
        - organization_id
        - name
        - created_at
        - updated_at
      title: AgentResponse
    AgentRevisionResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        agent_id:
          type: string
          format: uuid
          title: Agent Id
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        persona:
          anyOf:
            - type: string
            - type: 'null'
          title: Persona
        system_prompt:
          anyOf:
            - type: string
            - type: 'null'
          title: System Prompt
        context_variables:
          anyOf:
            - items:
                $ref: '#/components/schemas/ContextVarSpec'
              type: array
            - type: 'null'
          title: Context Variables
          description: >-
            Deprecated legacy projection; contains assistant SYSTEM declarations
            only. Use system_context_variables.
          deprecated: true
        variable_defaults:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Variable Defaults
        tool_refs:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Tool Refs
        knowledge_base_refs:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Knowledge Base Refs
        platform_tools:
          additionalProperties: true
          type: object
          title: Platform Tools
        policies_enabled:
          type: boolean
          title: Policies Enabled
          default: true
        policy_refs:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Policy Refs
        channel_specific_config:
          anyOf:
            - additionalProperties:
                $ref: '#/components/schemas/ChannelConfig'
              propertyNames:
                $ref: '#/components/schemas/ConversationChannel'
              type: object
            - type: 'null'
          title: Channel Specific Config
        router_config_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Router Config Id
        model_settings:
          anyOf:
            - $ref: '#/components/schemas/ModelChainEntry'
            - type: 'null'
        analyzer_model_settings:
          anyOf:
            - $ref: '#/components/schemas/ModelChainEntry'
            - type: 'null'
        workflow_enabled:
          type: boolean
          title: Workflow Enabled
          default: false
        memory_enabled:
          type: boolean
          title: Memory Enabled
          default: true
        current_time:
          anyOf:
            - $ref: '#/components/schemas/CurrentTimeSettings'
            - type: 'null'
        kb_clearance_level:
          anyOf:
            - type: integer
            - type: 'null'
          title: Kb Clearance Level
        kb_audience_tags:
          items:
            type: string
          type: array
          title: Kb Audience Tags
        continue_after_flow:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Continue After Flow
        voice_call_settings:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Voice Call Settings
        created_by:
          anyOf:
            - type: string
            - type: 'null'
          title: Created By
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        published_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Published At
        system_context_variables:
          anyOf:
            - items:
                $ref: '#/components/schemas/SystemContextVariableSpec'
              type: array
            - type: 'null'
          title: System Context Variables
          description: >-
            Assistant-owned immutable inputs. Derived variables belong to
            workflows.
          readOnly: true
      type: object
      required:
        - id
        - agent_id
        - name
        - created_at
        - updated_at
        - system_context_variables
      title: AgentRevisionResponse
    WorkflowResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        organization_id:
          type: string
          format: uuid
          title: Organization Id
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        kind:
          type: string
          title: Kind
          default: assistant
        active_revision_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Active Revision Id
        active_revision:
          anyOf:
            - $ref: '#/components/schemas/WorkflowRevisionResponse'
            - type: 'null'
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
        - id
        - organization_id
        - name
        - created_at
        - updated_at
      title: WorkflowResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    ModelConfig:
      properties:
        temperature:
          anyOf:
            - type: number
              maximum: 2
              minimum: 0
            - type: 'null'
          title: Temperature
        max_tokens:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Max Tokens
        top_p:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Top P
        stop_sequences:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 8
            - type: 'null'
          title: Stop Sequences
        reasoning_effort:
          anyOf:
            - type: string
              enum:
                - none
                - minimal
                - low
                - medium
                - high
                - xhigh
                - max
            - type: 'null'
          title: Reasoning Effort
        request_timeout_ms:
          anyOf:
            - type: integer
              maximum: 20000
              minimum: 1000
            - type: 'null'
          title: Request Timeout Ms
        thinking_budget:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Thinking Budget
      type: object
      title: ModelConfig
    InputArgConfig:
      properties:
        value:
          title: Value
        type:
          $ref: '#/components/schemas/InputArgType'
          default: default
      additionalProperties: false
      type: object
      required:
        - value
      title: InputArgConfig
      description: >-
        One operator-configured input field: a ``value`` plus its enforcement
        ``type``.


        The wire/stored shape of each entry in the ``input_defaults`` map.
        ``type``

        defaults to ``default`` so a caller can omit it for the common case.
    ReleaseGateMode:
      type: string
      enum:
        - 'off'
        - advisory
      title: ReleaseGateMode
      description: >-
        Per-agent release-gate mode (ENG-727). ``off`` = no release checks;

        ``advisory`` = compute + display a verdict but never block activation.

        The gate always runs and surfaces a verdict; it never refuses
        activation.
    ContextVarSpec:
      properties:
        name:
          type: string
          title: Name
        type:
          type: string
          enum:
            - string
            - int
            - float
            - bool
            - enum
          title: Type
        source:
          type: string
          enum:
            - system
            - derived
          title: Source
          default: derived
        enum_values:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Enum Values
        reask_cap:
          anyOf:
            - type: integer
            - type: 'null'
          title: Reask Cap
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
      type: object
      required:
        - name
        - type
      title: ContextVarSpec
      description: >-
        Typed definition for a context variable in the compiled graph.


        ``source`` defaults to ``derived`` so ad-hoc fixtures don't need to
        spell

        out the common case; required-ness is per-node
        (``AgentNode.required_writes``),

        not per-variable.


        ``name`` must satisfy the expression-grammar identifier rule
        (``[A-Za-z_]\w*``)

        so that gate/template references can never miss a declared var.
        Read-time loading

        (``list_active_revision_context_variables``) skips+logs any legacy row
        that

        violates this, so old data degrades safely without blocking startup.
    ChannelConfig:
      properties:
        prompt:
          anyOf:
            - type: string
            - type: 'null'
          title: Prompt
        first_speaking_config:
          anyOf:
            - $ref: '#/components/schemas/FirstSpeakingConfig'
            - type: 'null'
        warm_transfer:
          anyOf:
            - $ref: '#/components/schemas/WarmTransferChannelConfig'
            - type: 'null'
      type: object
      title: ChannelConfig
      description: >-
        Per-channel agent config addon.


        ``prompt`` is an additive system-prompt addon for this channel, rendered
        VERBATIM (v1 does

        NOT template ``{{var}}`` placeholders in it — this keeps it in the
        stable cacheable prefix

        and off the injection surface). ``first_speaking_config`` is the
        first-speaking config

        for this channel (templated). ``warm_transfer`` carries the

        voice-channel warm-transfer briefing script. All optional — a channel

        may have any combination.


        Stored as a JSON dict keyed by channel name on

        ``AgentRevision.channel_specific_config``. Future channel-specific

        fields (tools, voice_config) extend this model additively.
    WorkflowRevisionResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        workflow_id:
          type: string
          format: uuid
          title: Workflow Id
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        instructions:
          type: string
          title: Instructions
        compiled_graph:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Compiled Graph
        executable_graph:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Executable Graph
        quality_report:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Quality Report
        compilation_errors:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Compilation Errors
        compilation_strategy:
          type: string
          title: Compilation Strategy
        compilation_status:
          type: string
          title: Compilation Status
        compilation_task_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Compilation Task Id
        compilation_input_hash:
          anyOf:
            - type: string
            - type: 'null'
          title: Compilation Input Hash
        trigger_type:
          type: string
          title: Trigger Type
        trigger_config:
          additionalProperties: true
          type: object
          title: Trigger Config
        router_config_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Router Config Id
        analyzer_model_settings:
          anyOf:
            - $ref: '#/components/schemas/ModelChainEntry'
            - type: 'null'
        router_model_settings:
          anyOf:
            - $ref: '#/components/schemas/ModelChainEntry'
            - type: 'null'
        policy_ids:
          items: {}
          type: array
          title: Policy Ids
        tool_input_defaults:
          anyOf:
            - additionalProperties:
                additionalProperties:
                  $ref: '#/components/schemas/InputArgConfig'
                type: object
              type: object
            - type: 'null'
          title: Tool Input Defaults
        tools:
          items:
            $ref: '#/components/schemas/WorkflowToolResponse'
          type: array
          title: Tools
        knowledge_base_ids:
          items:
            type: string
            format: uuid
          type: array
          title: Knowledge Base Ids
        created_by:
          anyOf:
            - type: string
            - type: 'null'
          title: Created By
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        graph_version:
          type: integer
          title: Graph Version
          default: 0
        warnings:
          items:
            type: string
          type: array
          title: Warnings
      type: object
      required:
        - id
        - workflow_id
        - name
        - instructions
        - compilation_strategy
        - compilation_status
        - trigger_type
        - trigger_config
        - created_at
        - updated_at
      title: WorkflowRevisionResponse
      description: >-
        Full revision response — the compile-poll target (WF-08).


        Clients poll GET /workflows/revisions/{id} and read
        ``compilation_status``

        + ``compilation_errors`` + ``compiled_graph`` to determine whether an

        async compile job is done. ``compilation_task_id`` is the Celery task

        handle the conductor uses to cancel an in-flight compile.
    InputArgType:
      type: string
      enum:
        - default
        - pinned
      title: InputArgType
      description: |-
        How an operator-configured input value is enforced.

        * ``DEFAULT`` — a suggestion the agent may overwrite.
        * ``PINNED`` — a forced value the caller must use and cannot overwrite.
    FirstSpeakingConfig:
      properties:
        first_speaker:
          type: string
          enum:
            - agent
            - user
          title: First Speaker
          default: agent
        mode:
          type: string
          enum:
            - static
            - dynamic
          title: Mode
          default: static
        text:
          anyOf:
            - type: string
              maxLength: 1000
            - type: 'null'
          title: Text
        instructions:
          anyOf:
            - type: string
              maxLength: 2000
            - type: 'null'
          title: Instructions
        interruptible:
          type: boolean
          title: Interruptible
          default: true
        ai_disclosure_text:
          anyOf:
            - type: string
              maxLength: 500
            - type: 'null'
          title: Ai Disclosure Text
      type: object
      title: FirstSpeakingConfig
      description: |-
        Config for the AI's opening turn (no user input yet).

        Lives inside ``ChannelConfig`` — first-speaking is per-channel.

        Mode-agnostic fields:
        - ``first_speaker``: ``"agent"`` opens the call with the rendered
          message; ``"user"`` skips the greeting (caller speaks first).
          Non-voice channels treat the inbound user message as the
          ``"user"`` opener and ignore this field at runtime.

        Greeting source (only applies when ``first_speaker="agent"``):
        - ``static`` mode: ``text`` is required and emitted verbatim
          (templated via the shared ``{{var}}`` engine, ``src.shared.templating.render``).
        - ``dynamic`` mode: ``instructions`` are sent to the model router
          with the agent persona to render an opening line (instructions
          are templated). When omitted/empty, ``instructions`` falls back
          to ``DEFAULT_DYNAMIC_FIRST_SPEAKING_INSTRUCTIONS`` so operators
          who just want a generic friendly opener don't have to author copy.

        Voice-only fields (ignored on non-audio channels):
        - ``interruptible``: whether the caller can barge in mid-greeting.
        - ``ai_disclosure_text``: regulatory disclosure (e.g. CA SB 1001),
          played as an uninterruptible TTS frame BEFORE the greeting.
          Disclosure plays even when ``first_speaker="user"`` because the
          regulation requires the disclosure regardless of who speaks first.
    WarmTransferChannelConfig:
      properties:
        briefing_template:
          anyOf:
            - type: string
              maxLength: 4000
            - type: 'null'
          title: Briefing Template
      type: object
      title: WarmTransferChannelConfig
      description: >-
        Per-revision warm-transfer copy that versions with the agent revision.


        Holds the ``briefing_template`` the SupervisorAgent renders to brief the
        human

        supervisor on the customer's situation (templated via the shared
        ``{{var}}`` engine,

        ``src.shared.templating.render``, against the customer
        transcript/context). Lives under

        ``channel_specific_config["voice"]["warm_transfer"]`` so it clones
        forward with the

        revision like the system prompt. The platform-tool
        ``WarmTransferConfig`` (enabled,

        timeouts, fallback) is the agent-stable infra knob; this is the
        per-revision script.
    WorkflowToolResponse:
      properties:
        tool:
          $ref: '#/components/schemas/ToolResponse'
      type: object
      required:
        - tool
      title: WorkflowToolResponse
      description: Tool attached to a workflow revision.
    ToolResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        organization_id:
          type: string
          format: uuid
          title: Organization Id
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        tool_type:
          $ref: '#/components/schemas/ToolType'
        active_revision_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Active Revision Id
        active_revision:
          anyOf:
            - $ref: '#/components/schemas/ToolRevisionResponse'
            - type: 'null'
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
        - id
        - organization_id
        - name
        - description
        - tool_type
        - active_revision_id
        - created_at
        - updated_at
      title: ToolResponse
    ToolType:
      type: string
      enum:
        - api_call
        - call_transfer
      title: ToolType
    ToolRevisionResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        tool_id:
          type: string
          format: uuid
          title: Tool Id
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        configuration:
          anyOf:
            - $ref: '#/components/schemas/APICallConfiguration'
            - type: 'null'
        transfer_target:
          anyOf:
            - $ref: '#/components/schemas/TransferTargetView'
            - type: 'null'
        response_schema:
          anyOf:
            - $ref: '#/components/schemas/ResponseFieldSelector'
            - type: 'null'
        status:
          type: string
          title: Status
        has_secrets:
          type: boolean
          title: Has Secrets
          default: false
        input_defaults:
          anyOf:
            - additionalProperties:
                $ref: '#/components/schemas/InputArgConfig'
              type: object
            - type: 'null'
          title: Input Defaults
        compatibility:
          anyOf:
            - $ref: '#/components/schemas/ToolCompatibilityReportResponse'
            - type: 'null'
        created_by:
          anyOf:
            - type: string
            - type: 'null'
          title: Created By
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        default_count:
          type: integer
          title: Default Count
          description: How many input variables carry an operator *default* (ENG-590).
          readOnly: true
        pinned_count:
          type: integer
          title: Pinned Count
          description: How many input variables are operator-*pinned* (ENG-590).
          readOnly: true
        stale_input_fields:
          items:
            type: string
          type: array
          title: Stale Input Fields
          description: Configured variables removed/renamed/retyped by an operator edit.
          readOnly: true
        merged_input_preview:
          additionalProperties: true
          type: object
          title: Merged Input Preview
          description: The input schema with each operator value injected as ``default``.
          readOnly: true
      type: object
      required:
        - id
        - tool_id
        - name
        - description
        - status
        - created_by
        - created_at
        - updated_at
        - default_count
        - pinned_count
        - stale_input_fields
        - merged_input_preview
      title: ToolRevisionResponse
    APICallConfiguration:
      properties:
        url:
          type: string
          title: Url
          description: API endpoint URL — supports {{variable}} placeholders
        method:
          type: string
          enum:
            - GET
            - POST
            - PUT
            - PATCH
            - DELETE
          title: Method
          default: GET
        headers:
          items:
            $ref: '#/components/schemas/HeaderConfig'
          type: array
          title: Headers
        query_params:
          items:
            $ref: '#/components/schemas/QueryParamConfig'
          type: array
          title: Query Params
        body:
          additionalProperties: true
          type: object
          title: Body
        timeout:
          type: integer
          maximum: 300
          minimum: 1
          title: Timeout
          description: Request timeout in seconds
          default: 30
        variables:
          items:
            $ref: '#/components/schemas/VariableDefinition'
          type: array
          title: Variables
        retry:
          anyOf:
            - $ref: '#/components/schemas/RetryConfig'
            - type: 'null'
          description: Per-tool retry configuration
      type: object
      required:
        - url
      title: APICallConfiguration
      description: >-
        Configuration for an API_CALL tool, stored in Tool.configuration.


        Supports ``{{variable}}`` placeholders in url, headers, and body that
        are

        resolved at execution time from the tool's input variables and runtime

        metadata (via ``{{metadata.key}}``).
    TransferTargetView:
      properties:
        destination:
          anyOf:
            - type: string
            - type: 'null'
          title: Destination
        destination_source:
          anyOf:
            - $ref: '#/components/schemas/DestinationSourceConfig'
            - type: 'null'
        mode:
          type: string
          enum:
            - cold
            - warm
          title: Mode
          default: cold
      type: object
      title: TransferTargetView
      description: >-
        A call_transfer revision's stored target, surfaced on reads.


        ``ToolRevisionResponse.configuration`` is api_call-typed and parses to

        ``None`` for a transfer config (it has no ``url``), so this field
        carries the

        destination/mode back for the transfer-target picker. ``label`` /

        ``when_to_use`` come from the parent Tool's ``name`` / ``description``.


        Either ``destination`` (static) or ``destination_source`` (api_tool
        dynamic)

        is present, never both. The unused variant is omitted from
        serialization.
    ResponseFieldSelector:
      properties:
        field_mappings:
          items:
            $ref: '#/components/schemas/ResponseFieldMapping'
          type: array
          title: Field Mappings
      type: object
      title: ResponseFieldSelector
      description: The projection applied to a tool response.
    ToolCompatibilityReportResponse:
      properties:
        tool_id:
          type: string
          format: uuid
          title: Tool Id
        old_revision_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Old Revision Id
        new_revision_id:
          type: string
          format: uuid
          title: New Revision Id
        findings:
          items:
            $ref: '#/components/schemas/ToolCompatibilityFindingResponse'
          type: array
          title: Findings
        has_blocking:
          type: boolean
          title: Has Blocking
        active_blocking_count:
          type: integer
          title: Active Blocking Count
        active_blocking_finding_count:
          type: integer
          title: Active Blocking Finding Count
        active_finding_count:
          type: integer
          title: Active Finding Count
        affected_assistant_count:
          type: integer
          title: Affected Assistant Count
      type: object
      required:
        - tool_id
        - old_revision_id
        - new_revision_id
        - has_blocking
        - active_blocking_count
        - active_blocking_finding_count
        - active_finding_count
        - affected_assistant_count
      title: ToolCompatibilityReportResponse
      description: >-
        Impact report shared by preflight analysis and successful promotion.


        Pre-prod: findings are advisory warnings — promotion always succeeds.
        The

        ``has_blocking`` / ``active_blocking_*`` fields retain their literal

        blocking semantics (and therefore remain false/zero today).
    HeaderConfig:
      properties:
        key:
          type: string
          title: Key
        value:
          type: string
          title: Value
        secure:
          type: boolean
          title: Secure
          description: When true, value is stored encrypted in the database
          default: false
      type: object
      required:
        - key
        - value
      title: HeaderConfig
      description: HTTP header with optional encryption for sensitive values.
    QueryParamConfig:
      properties:
        key:
          type: string
          title: Key
        value:
          type: string
          title: Value
        secure:
          type: boolean
          title: Secure
          description: When true, value is stored encrypted in the database
          default: false
      type: object
      required:
        - key
        - value
      title: QueryParamConfig
      description: URL query parameter with optional encryption for sensitive values.
    VariableDefinition:
      properties:
        name:
          type: string
          title: Name
        type:
          type: string
          enum:
            - str
            - int
            - float
            - bool
          title: Type
          default: str
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        required:
          type: boolean
          title: Required
          default: false
      type: object
      required:
        - name
      title: VariableDefinition
      description: Input parameter definition for an API tool.
    RetryConfig:
      properties:
        max_retries:
          type: integer
          maximum: 5
          minimum: 0
          title: Max Retries
          default: 0
        base_delay_seconds:
          type: number
          maximum: 30
          minimum: 0.1
          title: Base Delay Seconds
          default: 1
        max_delay_seconds:
          type: number
          maximum: 120
          minimum: 1
          title: Max Delay Seconds
          default: 30
        jitter:
          type: boolean
          title: Jitter
          default: true
      type: object
      title: RetryConfig
      description: >-
        Retry configuration — same schema at org, tool, and integration-instance
        level.
    DestinationSourceConfig:
      properties:
        type:
          type: string
          const: api_tool
          title: Type
          default: api_tool
        tool_id:
          type: string
          title: Tool Id
        input_mapping:
          additionalProperties:
            anyOf:
              - type: string
              - type: integer
              - type: number
              - type: boolean
              - type: 'null'
          type: object
          title: Input Mapping
        response_path:
          type: string
          title: Response Path
      additionalProperties: false
      type: object
      required:
        - tool_id
        - response_path
      title: DestinationSourceConfig
      description: >-
        How a transfer target's destination is resolved dynamically at transfer
        time.


        The platform invokes the referenced ``api_call`` GET tool with

        ``input_mapping`` (values may carry ``{{context_variable}}``
        placeholders),

        extracts ``response_path`` from the tool's response, and validates the
        result

        as an E.164 / ``sip:`` destination. The lookup is never exposed to the
        LLM — it

        is a deterministic platform lookup executed through the shared

        ``execute_api_call`` stack (SSRF-pinned client, KMS secret decrypt,

        response-field narrowing, retry). Secrets live on the referenced tool
        (not

        embedded in the transfer target).
    ResponseFieldMapping:
      properties:
        path:
          type: string
          title: Path
          description: Dot-path into the response (e.g. 'data.order.id')
        alias:
          anyOf:
            - type: string
            - type: 'null'
          title: Alias
          description: Output key name; defaults to the full dot-path
      type: object
      required:
        - path
      title: ResponseFieldMapping
      description: One field selected from a provider response.
    ToolCompatibilityFindingResponse:
      properties:
        severity:
          type: string
          enum:
            - blocking
            - advisory
          title: Severity
        assistant_id:
          type: string
          format: uuid
          title: Assistant Id
        assistant_revision_id:
          type: string
          format: uuid
          title: Assistant Revision Id
        revision_state:
          type: string
          enum:
            - active
            - candidate
            - historical
          title: Revision State
        finding_type:
          type: string
          title: Finding Type
        field_path:
          type: string
          title: Field Path
        detail:
          type: string
          title: Detail
        configuration_scope:
          type: string
          enum:
            - assistant_tool_default
            - agent_node_tool
            - action_step_tool
          title: Configuration Scope
        workflow_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Workflow Id
        workflow_revision_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Workflow Revision Id
        component_node_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Component Node Id
        graph_node_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Graph Node Id
        graph_node_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Graph Node Name
        step_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Step Id
        tool_ref_index:
          anyOf:
            - type: integer
            - type: 'null'
          title: Tool Ref Index
      type: object
      required:
        - severity
        - assistant_id
        - assistant_revision_id
        - revision_state
        - finding_type
        - field_path
        - detail
        - configuration_scope
      title: ToolCompatibilityFindingResponse
      description: One frontend-navigable tool-revision compatibility finding.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: x-api-key

````