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

# Create Tool

> Tool names are automatically normalized to camelCase (e.g. `capture_lead` → `captureLead`). Top-level `extraction_parameters`, `static_parameters`, and `include_standard_metadata` are automatically migrated into `payload_config` if provided outside it.


Webhook tools use one canonical configuration across prompt agents, flow agents, and tests:

* For webhook tools, `description` is required because it tells the model when the tool is appropriate.
* `config.url` must be a final public HTTP(S) endpoint. Local and non-public literal targets are rejected at save time; dispatch also rejects non-public or mixed DNS answers. Redirects are not followed.
* `config.method` supports `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`; `timeout_seconds` is 1–60 seconds and defaults to 30.
* Request headers must have non-empty names and string values. Routing/framing headers such as `Host`, `Content-Length`, `Transfer-Encoding`, `Connection`, `Expect`, `Keep-Alive`, `Proxy-*`, `TE`, `Trailer`, and `Upgrade` are rejected. Authorization and custom content types remain supported.
* Payload parameter names are normalized to camelCase. Extraction descriptions are required, and `required` defaults to `true` when omitted.
* Webhook tools are dispatched once. `retry_count` is unsupported because automatically replaying an action could duplicate a non-idempotent operation.


## OpenAPI

````yaml POST /tools
openapi: 3.1.0
info:
  title: Yappr API
  description: >
    Create and manage AI voice agents, purchase phone numbers, configure tools,
    and initiate calls — all via REST.
  version: 1.0.0
  contact:
    url: https://goyappr.com
servers:
  - url: https://api.goyappr.com
    description: Production
security:
  - apiKey: []
paths:
  /tools:
    post:
      tags:
        - Tools
      summary: Create tool
      description: >
        Tool names are automatically normalized to camelCase (e.g.
        `capture_lead` → `captureLead`). Top-level `extraction_parameters`,
        `static_parameters`, and `include_standard_metadata` are automatically
        migrated into `payload_config` if provided outside it.
      operationId: createTool
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - type
                - config
              properties:
                name:
                  type: string
                  example: capture_lead
                description:
                  type: string
                  description: >-
                    Required and non-empty when type is webhook; optional for
                    function tools.
                type:
                  type: string
                  enum:
                    - webhook
                    - function
                idempotency_key:
                  type: string
                config:
                  type: object
                  description: >-
                    Webhook configuration is validated as described below;
                    function-tool configuration is stored as an arbitrary JSON
                    object.
              allOf:
                - if:
                    properties:
                      type:
                        const: webhook
                    required:
                      - type
                  then:
                    required:
                      - description
                    properties:
                      description:
                        type: string
                        pattern: \S
                      config:
                        type: object
                        required:
                          - url
                          - method
                        properties:
                          url:
                            type: string
                            format: uri
                            description: >-
                              Final public HTTP(S) endpoint. Local and
                              non-public literal targets are rejected when
                              saved; dispatch also rejects non-public or mixed
                              DNS answers and does not follow redirects.
                          method:
                            type: string
                            enum:
                              - GET
                              - POST
                              - PUT
                              - PATCH
                              - DELETE
                          headers:
                            type: object
                            additionalProperties:
                              type: string
                            description: >-
                              String-valued request headers. Routing/framing
                              headers such as Host, Content-Length,
                              Transfer-Encoding, Connection, Expect, Keep-Alive,
                              Proxy-*, TE, Trailer, and Upgrade are rejected.
                          timeout_seconds:
                            type: integer
                            minimum: 1
                            maximum: 60
                            default: 30
                          payload_config:
                            type: object
                            properties:
                              include_standard_metadata:
                                type: boolean
                                default: true
                              static_parameters:
                                type: array
                                items:
                                  type: object
                                  required:
                                    - name
                                    - value
                                  properties:
                                    name:
                                      type: string
                                      description: Normalized to camelCase
                                    value:
                                      type: string
                              extraction_parameters:
                                type: array
                                items:
                                  $ref: '#/components/schemas/ToolExtractionParameter'
      responses:
        '201':
          description: Tool created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tool'
components:
  schemas:
    Tool:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          description: Normalized to camelCase (e.g. 'capture_lead' → 'captureLead')
        description:
          type: string
          nullable: true
        type:
          type: string
          enum:
            - webhook
            - function
        config:
          type: object
        is_active:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Your Yappr API key (e.g. `ypr_live_...`). Generate one in the dashboard
        under **Settings → API Keys**.

````