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

# Create mid call tool

> Create a new mid call tool

This endpoint allows you to create a new mid call tool that can be used by your AI assistants to interact with external APIs during calls.

### Body Parameters

<Info>
  The public API creates **HTTP request** tools. Automation Platform tools (which
  generate a linked flow) are created from the dashboard. Tool values support
  dynamic variables — use `{param}` for AI-extracted parameters in the URL, and
  `{{variable}}` (e.g. `{{customer_phone}}`) in the URL, header values, and static
  field values.
</Info>

<ParamField body="name" type="string" required>
  Tool name — letters, numbers and underscores, starting with a letter or underscore (max 64 characters, e.g., `get_weather`, `book_appointment`)
</ParamField>

<ParamField body="description" type="string" required>
  Detailed explanation of when and how the AI should use this tool (max 255 characters)
</ParamField>

<ParamField body="endpoint" type="string" required>
  Valid URL of the API endpoint to call (max 2048 characters)
</ParamField>

<ParamField body="method" type="string" required>
  HTTP method: `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`
</ParamField>

<ParamField body="body_format" type="string" optional>
  How the request body is encoded for write methods (POST/PUT/PATCH): `json` (default) or `form` (`application/x-www-form-urlencoded`)
</ParamField>

<ParamField body="timeout" type="integer" optional>
  Request timeout in seconds (1-30, default: 10)
</ParamField>

<ParamField body="headers" type="array" optional>
  HTTP headers to send with the request

  <Expandable title="headers properties">
    <ParamField body="name" type="string" required>
      Header name
    </ParamField>

    <ParamField body="value" type="string" required>
      Header value (max 2048 chars; supports `{{variable}}` substitution)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="static_fields" type="array" optional>
  Fixed key/value pairs always sent with the request (the AI never changes them)

  <Expandable title="static_fields properties">
    <ParamField body="key" type="string" required>
      Field key (max 64 chars)
    </ParamField>

    <ParamField body="value" type="string" optional>
      Field value (max 2048 chars; supports `{{variable}}` substitution)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="schema" type="array" optional>
  Parameters that the AI will extract from conversation and send to the endpoint

  <Expandable title="schema properties">
    <ParamField body="name" type="string" required>
      Parameter name (1-64 chars, must start with a letter or underscore, can contain letters, numbers and underscores)
    </ParamField>

    <ParamField body="type" type="string" required>
      Parameter type: `string`, `number`, `float`, or `boolean`
    </ParamField>

    <ParamField body="description" type="string" required>
      Description to help AI understand how to extract this parameter (3-255 chars)
    </ParamField>

    <ParamField body="required" type="boolean" optional>
      Whether the AI must collect this parameter. Optional parameters are only sent when a value was collected. Defaults to `false`.
    </ParamField>
  </Expandable>
</ParamField>

### Response fields

<ResponseField name="message" type="string">
  Success message
</ResponseField>

<ResponseField name="data" type="object">
  The created tool object

  <Expandable title="data properties">
    <ResponseField name="id" type="integer">
      The unique identifier of the tool
    </ResponseField>

    <ResponseField name="name" type="string">
      The name of the tool
    </ResponseField>

    <ResponseField name="description" type="string">
      Tool description
    </ResponseField>

    <ResponseField name="type" type="string">
      Tool type: `http` or `automation`
    </ResponseField>

    <ResponseField name="endpoint" type="string">
      API endpoint URL
    </ResponseField>

    <ResponseField name="method" type="string">
      HTTP method
    </ResponseField>

    <ResponseField name="body_format" type="string">
      Request body encoding: `json` or `form`
    </ResponseField>

    <ResponseField name="timeout" type="integer">
      Request timeout in seconds
    </ResponseField>

    <ResponseField name="headers" type="array">
      HTTP headers
    </ResponseField>

    <ResponseField name="static_fields" type="array">
      Fixed key/value pairs always sent with the request
    </ResponseField>

    <ResponseField name="schema" type="array">
      Parameter schema
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "message": "Tool created successfully",
    "data": {
      "id": 1,
      "name": "check_order_status",
      "description": "Use this tool to check the status of a customer's order.",
      "type": "http",
      "endpoint": "https://api.yourstore.com/orders/{order_id}/status",
      "method": "GET",
      "body_format": "json",
      "timeout": 10,
      "headers": [
        {
          "name": "Content-Type",
          "value": "application/json"
        },
        {
          "name": "Authorization",
          "value": "Bearer {{crm_key}}"
        }
      ],
      "static_fields": [
        {
          "key": "source",
          "value": "autocalls"
        },
        {
          "key": "caller",
          "value": "{{customer_phone}}"
        }
      ],
      "schema": [
        {
          "name": "order_id",
          "type": "string",
          "description": "The customer's order ID",
          "required": true
        },
        {
          "name": "amount",
          "type": "float",
          "description": "Order total as a decimal, e.g. 19.99",
          "required": false
        },
        {
          "name": "priority_order",
          "type": "boolean",
          "description": "Whether this is a priority order",
          "required": false
        }
      ],
      "created_at": "2025-10-10T12:00:00.000000Z",
      "updated_at": "2025-10-10T12:00:00.000000Z"
    }
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "Tool name must start with a letter or underscore and contain only letters, numbers, and underscores (max 64 characters).",
    "errors": {
      "name": [
        "Tool name must start with a letter or underscore and contain only letters, numbers, and underscores (max 64 characters)."
      ]
    }
  }
  ```

  ```json 422 Plan Limit Reached theme={null}
  {
    "message": "You have reached your plan limit of 5 mid call tools. Please upgrade your plan to create more tools."
  }
  ```
</ResponseExample>

### Attaching Tools to Assistants

After creating a tool, you need to attach it to an assistant to use it during calls. Tools are managed through the Assistant API:

* **[Create Assistant](/api-reference/assistants/create-assistant)** - Use the `tool_ids` parameter to attach tools when creating an assistant
* **[Update Assistant](/api-reference/assistants/update-assistant)** - Use the `tool_ids` parameter to add, remove, or replace tools on an existing assistant