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

# Update revision config (any revision, in place)

> Apply config updates to any revision in place.



## OpenAPI

````yaml /api-reference/openapi.json patch /v1/assistants/{agent_id}/revisions/{revision_id}
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/{agent_id}/revisions/{revision_id}:
    patch:
      tags:
        - assistants
      summary: Update revision config (any revision, in place)
      description: Apply config updates to any revision in place.
      operationId: patchAssistantRevision
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Agent Id
        - name: revision_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Revision Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RevisionConfigUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevisionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    RevisionConfigUpdate:
      properties:
        base_version:
          anyOf:
            - type: integer
            - type: 'null'
          title: Base Version
        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'
        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.
        workflow_enabled:
          type: boolean
          title: Workflow Enabled
          description: >-
            Run the stored workflow for this revision. Omitted leaves it
            unchanged; explicit null is invalid.
          default: false
        memory_enabled:
          type: boolean
          title: Memory Enabled
          description: Enable semantic memory recall and ingestion for this revision.
          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:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Kb Audience Tags
        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
        platform_tools:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Platform Tools
        continue_after_flow:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Continue After Flow
      additionalProperties: false
      type: object
      title: RevisionConfigUpdate
      description: >-
        Request body for PATCH /assistants/{id}/revisions/{rid} — edit any
        revision.


        A subset of the behavioral fields that live on AgentRevision.

        ``base_version`` is the optimistic-concurrency version of the revision.

        If supplied, the revision's ``version`` column must match; a mismatch

        raises ConflictError (409).


        ``extra=forbid``: unknown or removed fields return 422.
    RevisionResponse:
      properties:
        revision:
          $ref: '#/components/schemas/AgentRevisionResponse'
        version:
          type: integer
          title: Version
          default: 0
        prompt_findings:
          items:
            $ref: '#/components/schemas/ValidationFinding'
          type: array
          title: Prompt Findings
          description: >-
            Non-blocking authoring diagnostics for assistant
            persona/system-prompt mentions. Error severity does not mean an
            ordinary draft write failed; activation and active-revision updates
            block until these findings resolve.
      type: object
      required:
        - revision
      title: RevisionResponse
      description: Response for revision create/update — the revision + optimistic version.
    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).
    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
    ValidationFinding:
      properties:
        severity:
          type: string
          enum:
            - error
            - warning
            - suggestion
          title: Severity
        rule_id:
          type: string
          title: Rule Id
        category:
          type: string
          title: Category
        message:
          type: string
          title: Message
        node_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Node Id
        edge_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Edge Id
        related_node_ids:
          items:
            type: string
          type: array
          title: Related Node Ids
        related_edge_ids:
          items:
            type: string
          type: array
          title: Related Edge Ids
        source_span:
          anyOf:
            - $ref: '#/components/schemas/SourceSpan'
            - type: 'null'
        suggested_fix:
          anyOf:
            - type: string
            - type: 'null'
          title: Suggested Fix
        related_spans:
          items:
            $ref: '#/components/schemas/SourceSpan'
          type: array
          title: Related Spans
      type: object
      required:
        - severity
        - rule_id
        - category
        - message
      title: ValidationFinding
      description: >-
        Graph-validator finding (Stage 7 — over the assembled graph).


        For cross-cutting issues (variable drift, gate-consistency) the
        validator

        populates ``related_node_ids`` so the healer can regen multiple nodes in

        coordination instead of one at a time.
    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.
    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.
    SourceSpan:
      properties:
        start_line:
          type: integer
          title: Start Line
        start_col:
          type: integer
          title: Start Col
        end_line:
          type: integer
          title: End Line
        end_col:
          type: integer
          title: End Col
        raw_text_excerpt:
          anyOf:
            - type: string
            - type: 'null'
          title: Raw Text Excerpt
      type: object
      required:
        - start_line
        - start_col
        - end_line
        - end_col
      title: SourceSpan
      description: |-
        Byte/character span into the original instruction markdown.

        ``start_line``/``end_line`` are 1-indexed; columns are 0-indexed. The
        optional ``raw_text_excerpt`` carries a small slice for human-readable
        error messages without forcing readers to re-open the source.
    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.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: x-api-key

````