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

# Custom function schema reference

> Every field in a Bolna custom function: the OpenAI-style function definition, the API configuration Bolna uses to call your endpoint, and %(name)s format specifiers.

This page documents every field of a [custom function](/docs/tool-calling/custom-function-calls). For a walkthrough of creating one in the dashboard, start there.

## Complete schema structure

Every custom function has two parts: **Function Definition** (tells LLM what it does) and **API Configuration** (tells Bolna how to call your API).

```json theme={"system"}
{
  "name": "function_name",
  "description": "Detailed description of when to call this function",
  "pre_call_message": "What agent says while the API is being called",
  "parameters": {
    "type": "object",
    "properties": {
      "param_name": {
        "type": "string",
        "description": "What this parameter represents"
      }
    },
    "required": ["param_name"]
  },
  "key": "custom_task",
  "value": {
    "method": "GET",
    "param": {
      "param_name": "%(param_name)s"
    },
    "url": "https://your-api.com/endpoint",
    "api_token": "Bearer your_token",
    "headers": {}
  }
}
```

<Warning>
  **Mandatory:** The field `"key": "custom_task"` must be present exactly as shown. Do not modify this value.
</Warning>

***

## Schema reference

<Info>
  Parts 1-2 follow the [OpenAI function calling specification](https://platform.openai.com/docs/guides/function-calling) - they define **what** the function does. Parts 3-5 are Bolna extensions that define **how** to execute the API call automatically.
</Info>

<Tabs>
  <Tab title="Function Definition">
    ### 1. Function Definition

    These fields tell the LLM about your function:

    | Field | Required | Description |
    | - | - | - |
    | `name` | Yes | Unique function identifier. Use `snake_case` (e.g., `get_order_status`) |
    | `description` | Yes | Tells the LLM when to trigger this function. Be specific and detailed. |
    | `parameters` | Yes | Defines what information to collect from the caller |
  </Tab>

  <Tab title="Parameters Object">
    ### 2. Parameters Object

    The `parameters` object defines what information the LLM should collect from the caller.

    ```json theme={"system"}
    "parameters": {
      "type": "object",
      "properties": {
        "customer_name": {
          "type": "string",
          "description": "The customer's full name"
        },
        "order_id": {
          "type": "string",
          "description": "The order ID, usually starts with ORD-"
        },
        "quantity": {
          "type": "integer",
          "description": "Number of items"
        }
      },
      "required": ["customer_name", "order_id"]
    }
    ```

    **Supported Data Types:**

    | Type | Use Case | Example Values |
    | - | - | - |
    | `string` | Text, names, IDs, phone numbers | `"John Doe"`, `"ORD-12345"` |
    | `integer` | Whole numbers | `5`, `100`, `-10` |
    | `number` | Decimal numbers | `29.99`, `3.14` |
    | `boolean` | True/false flags | `true`, `false` |

    **Required vs Optional:**

    | In `required` array? | Behavior |
    | - | - |
    | Yes | LLM will keep asking until this value is provided |
    | No | Optional - included if mentioned, skipped otherwise |
  </Tab>

  <Tab title="Bolna Extensions">
    ### 3. Bolna Extensions

    These fields are specific to Bolna:

    | Field | Required | Description |
    | - | - | - |
    | `pre_call_message` | No | Message the agent speaks while API is executing (e.g., *"One moment please..."*) |
    | `key` | Yes | Must be `"custom_task"` - identifies this as a custom function |
    | `value` | Yes | API configuration object (see below) |
  </Tab>

  <Tab title="API Configuration">
    ### 4. API Configuration (`value` object)

    This tells Bolna how to make the HTTP request:

    | Field | Required | Description |
    | - | - | - |
    | `method` | Yes | HTTP method: `GET`, `POST`, `PUT`, `PATCH`, `DELETE` |
    | `url` | Yes | Your API endpoint URL |
    | `param` | Yes | Maps parameters to API request using format specifiers |
    | `api_token` | No | Authorization header value (e.g., `Bearer your_token`) |
    | `headers` | No | Additional HTTP headers as key-value pairs |
    | `pre_call_webhook_param` | No | Body template for a [pre-call webhook](/docs/tool-calling/pre-call-webhooks) that fires *before* the main API call. This is the on/off switch — if it is not set, no pre-call webhook fires. |
    | `pre_call_webhook_url` | No | Where to send the pre-call webhook. If omitted, the agent-level Webhook URL is used. See [Pre-call Webhooks](/docs/tool-calling/pre-call-webhooks). |
  </Tab>

  <Tab title="Format Specifiers">
    ### 5. Format Specifiers

    The `param` object maps your parameters to the API request. Use Python-style format specifiers:

    | Data Type | Format Specifier | Example |
    | - | - | - |
    | String | `%(param_name)s` | `"customer_id": "%(customer_id)s"` |
    | Integer | `%(param_name)i` | `"quantity": "%(quantity)i"` |
    | Float | `%(param_name)f` | `"price": "%(price)f"` |

    <Info>
      **Parameter names must match exactly.** The name in `properties` must be identical to the name in `param` mapping (case-sensitive).
    </Info>
  </Tab>
</Tabs>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.