> ## 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 tool revision ## OpenAPI ````yaml /api-reference/openapi.json post /v1/tools/{tool_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/tools/{tool_id}/revisions: post: tags: - tools summary: Create a tool revision operationId: createToolRevision parameters: - name: tool_id in: path required: true schema: type: string format: uuid title: Tool Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ToolRevisionCreate' responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ToolRevisionResponse' '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: ToolRevisionCreate: 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 configuration: anyOf: - $ref: '#/components/schemas/APICallConfiguration' - type: 'null' transfer_target: anyOf: - $ref: '#/components/schemas/TransferTargetInput' - type: 'null' response_schema: anyOf: - $ref: '#/components/schemas/ResponseFieldSelector' - type: 'null' input_defaults: anyOf: - additionalProperties: $ref: '#/components/schemas/InputArgConfig' type: object - type: 'null' title: Input Defaults type: object required: - name title: ToolRevisionCreate 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 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 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}}``). TransferTargetInput: properties: destination: type: string title: Destination description: 'Dial target — E.164 (e.g. +15105550100) or a sip: URI' mode: type: string enum: - cold - warm title: Mode default: cold additionalProperties: false type: object required: - destination title: TransferTargetInput description: >- Operator-supplied config for a shared call_transfer target (ENG, voice). The reusable cold-transfer destination. Mirrors the storage-facing fields of :class:`~src.shared.transfer_contracts.TransferTargetConfig`; the request layer only checks shape/``mode`` here, while ``destination`` validity (E.164 or ``sip:`` URI) is enforced at the service layer via :func:`~src.custom_tools.api._shared.transfer_target.validate_transfer_target_config` so a bad destination surfaces as a clean 422. The label / when-to-use are carried on the Tool's ``name`` / ``description``, not here. 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. 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. 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``. 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 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. 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 ````