> ## 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 agent revision



## OpenAPI

````yaml /api-reference/openapi.json post /v1/agents/{agent_id}/revisions
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.21.0
servers:
  - url: https://api-sandbox.featherhq.com
    description: Sandbox
  - url: http://localhost:8000
    description: Local dev
security: []
paths:
  /v1/agents/{agent_id}/revisions:
    post:
      tags:
        - agents
      summary: Create an agent revision
      operationId: createAgentRevision
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Agent Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentRevisionCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRevisionResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    AgentRevisionCreate:
      properties:
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        based_on_revision_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Based On Revision Id
        persona:
          anyOf:
            - type: string
            - type: 'null'
          title: Persona
        system_prompt:
          anyOf:
            - type: string
            - type: 'null'
          title: System Prompt
        global_skill_ids:
          anyOf:
            - items:
                type: string
                format: uuid
              type: array
            - type: 'null'
          title: Global Skill Ids
        context_variables:
          anyOf:
            - items:
                $ref: '#/components/schemas/ContextVarSpec'
              type: array
            - type: 'null'
          title: Context Variables
        variable_defaults:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Variable Defaults
        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
        policies_enabled:
          type: boolean
          title: Policies Enabled
          default: true
        policy_refs:
          anyOf:
            - items:
                $ref: '#/components/schemas/PolicyRefSpec'
              type: array
            - type: 'null'
          title: Policy Refs
        channel_specific_config:
          anyOf:
            - additionalProperties:
                $ref: '#/components/schemas/ChannelConfig'
              propertyNames:
                enum:
                  - sms
                  - voice
                  - api
                  - sandbox
                  - email
              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'
        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
      type: object
      required:
        - name
      title: AgentRevisionCreate
    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
        global_skill_ids:
          anyOf:
            - items:
                type: string
                format: uuid
              type: array
            - type: 'null'
          title: Global Skill Ids
        context_variables:
          anyOf:
            - items:
                $ref: '#/components/schemas/ContextVarSpec'
              type: array
            - type: 'null'
          title: Context Variables
        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
        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:
                enum:
                  - sms
                  - voice
                  - api
                  - sandbox
                  - email
              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'
        kb_clearance_level:
          anyOf:
            - type: integer
            - type: 'null'
          title: Kb Clearance Level
        kb_audience_tags:
          items:
            type: string
          type: array
          title: Kb Audience Tags
        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
      type: object
      required:
        - id
        - agent_id
        - name
        - created_at
        - updated_at
      title: AgentRevisionResponse
    ErrorResponse:
      properties:
        error:
          type: string
          title: Error
        message:
          type: string
          title: Message
      type: object
      required:
        - error
        - message
      title: ErrorResponse
      description: Standard error response returned by all API error handlers.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    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.
    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).
    PolicyRefSpec:
      properties:
        policy_id:
          type: string
          format: uuid
          title: Policy Id
      type: object
      required:
        - policy_id
      title: PolicyRefSpec
      description: >-
        One attached-policy reference stored on ``AgentRevision.policy_refs``.


        The single canonical attachment shape, shared by the assistant-revision

        attachment API (``PolicyAttachmentUpdate``) and the agents request
        bodies

        (``AgentRevisionCreate``/``Update``, which import this type). A ref
        carries ONLY

        the ``policy_id`` — attaching a policy is what makes it run on the
        assistant.

        There is no separate per-attachment run/suspend toggle: detach to stop a
        policy,

        or use the per-revision ``policies_enabled`` master switch (or the
        org-wide kill

        switch) for coarser control. Mode is per-policy now (no per-attachment
        override).

        Only ``scope=attachable`` policies are referenced here —
        ``scope=organization``

        policies auto-apply and are never listed. Catalog existence +
        org-ownership of

        the referenced policy is checked at write time.
    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
        (templated). ``first_speaking_config`` is the first-speaking config
        for this channel (also 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.
    ModelChainEntry:
      properties:
        model:
          type: string
          title: Model
        config:
          $ref: '#/components/schemas/ModelConfig'
      type: object
      required:
        - model
      title: ModelChainEntry
    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
    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.
    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.
    ModelConfig:
      properties:
        temperature:
          anyOf:
            - type: number
            - type: 'null'
          title: Temperature
        max_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Max Tokens
        top_p:
          anyOf:
            - type: number
            - type: 'null'
          title: Top P
        stop_sequences:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Stop Sequences
        reasoning_effort:
          anyOf:
            - type: string
              enum:
                - none
                - low
                - medium
                - high
                - xhigh
            - type: 'null'
          title: Reasoning Effort
        request_timeout_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: Request Timeout Ms
        thinking_budget:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Thinking Budget
      type: object
      title: ModelConfig
    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.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: x-api-key

````