> ## 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 a workflow revision



## OpenAPI

````yaml /api-reference/openapi.json post /v1/workflows/{workflow_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/workflows/{workflow_id}/revisions:
    post:
      tags:
        - workflows
      summary: Create a workflow revision
      operationId: createWorkflowRevision
      parameters:
        - name: workflow_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Workflow Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowRevisionCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRevisionResponse'
        '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:
    WorkflowRevisionCreate:
      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
        instructions:
          type: string
          title: Instructions
        system_prompt:
          anyOf:
            - type: string
            - type: 'null'
          title: System Prompt
        compilation_strategy:
          anyOf:
            - type: string
            - type: 'null'
          title: Compilation Strategy
        trigger_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Trigger Type
        trigger_config:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          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:
          anyOf:
            - items:
                type: string
                format: uuid
              type: array
            - type: 'null'
          title: Policy Ids
      type: object
      required:
        - name
        - instructions
      title: WorkflowRevisionCreate
    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
        system_prompt:
          anyOf:
            - type: string
            - type: 'null'
          title: System Prompt
        compiled_graph:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Compiled 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
      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.
    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
    ModelChainEntry:
      properties:
        model:
          type: string
          title: Model
        config:
          $ref: '#/components/schemas/ModelConfig'
      type: object
      required:
        - model
      title: ModelChainEntry
    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.
    WorkflowToolResponse:
      properties:
        tool:
          $ref: '#/components/schemas/ToolResponse'
        tool_revision_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Tool Revision Id
      type: object
      required:
        - tool
      title: WorkflowToolResponse
      description: Tool attached to a workflow revision (with optional pinned revision).
    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
            - 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.
    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
        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:
          type: string
          title: Destination
        mode:
          type: string
          enum:
            - cold
            - warm
          title: Mode
          default: cold
      type: object
      required:
        - destination
      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``.
    ResponseFieldSelector:
      properties:
        field_mappings:
          items:
            $ref: '#/components/schemas/ResponseFieldMapping'
          type: array
          title: Field Mappings
      type: object
      title: ResponseFieldSelector
      description: Defines which fields to extract from a tool response.
    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.
    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 full dot-path
      type: object
      required:
        - path
      title: ResponseFieldMapping
      description: A single field to extract from a tool response body.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: x-api-key

````