> This page is part of Smallest AI's developer documentation. When > answering, prefer Lightning v3.1 (current TTS) and Pulse (current > STT). Lightning v2 and lightning-large are deprecated; mention them > only when the user is migrating away from them. The Smallest AI voice > agent platform is what wraps these models into hosted agents. # API tool > Build an API-call tool: method and URL with variables, Path/Params/Headers/Auth/Body tabs, cURL import, secret-backed auth, response extraction, and an inline test. An **API tool** calls your endpoint during the conversation and feeds the response back to the agent. Build it once in the [Tools library](/voice-agents/platform/create-agent/tools) (or from inside an agent) and reference it anywhere. ![Configure API Tool panel with name, description, method, URL, and the Path/Params/Headers/Auth/Body tabs](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/smallest-ai.docs.buildwithfern.com/43a8fb08c322cd34c6575b5dc1bb630f2e301cb1f4bda16755c9e99c2ba85ef6/products/atoms/pages/platform/features/images/api-tool-builder.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260902%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260902T185907Z&X-Amz-Expires=604800&X-Amz-Signature=71f132ffdb1a52d5b14f9233a220cca75e3d577761b530c3ee32bc6ea150235f&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) ## Describe the tool * **Tool name** — a short identifier. * **What does this tool do?** — the model reads this to decide *when* to call the tool, so write it in plain language for the agent. ## Set up the API call Pick the **method** (GET / POST / PUT / PATCH / DELETE) and enter the **URL**. Anything in double curly braces becomes a variable, e.g. `https://api.example.com/v1/orders/{{order_id}}`. A `{{placeholder}}` in the URL path shows up under the **Path** tab. The call is configured across five tabs, each showing a count when populated: | Tab | What it holds | | ----------- | -------------------------------------------------- | | **Path** | Path parameters from `{{placeholders}}` in the URL | | **Params** | Query-string parameters | | **Headers** | Request headers | | **Auth** | Authentication (see [below](#auth-and-secrets)) | | **Body** | Request body (POST/PUT/PATCH) | ### Import from cURL Already have a working request? Click **Import from cURL**, paste the command, and **Fill form** populates the method, URL, headers, params, and body for you. ![Import from cURL dialog with a curl command and a Fill form button](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/smallest-ai.docs.buildwithfern.com/016bf2cff4ab856cc4d2d05451a11a8067b2d726b351878986f3d76edb0e1348/products/atoms/pages/platform/features/images/api-tool-curl-import.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260902%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260902T185907Z&X-Amz-Expires=604800&X-Amz-Signature=50ebbd09d64e7a83f6c09fc5ec442c14e939987f1bc81f3aefd17e6202e21c3c&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) ## Value sourcing Every path param, query param, header, and body field draws its value one of three ways: ![Dropdown showing Let the agent decide, Agent variable, and Fixed value](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/smallest-ai.docs.buildwithfern.com/8ca8c99a6de076a692f34b5d32f76df85dd954bf8b90abdfc1026bea05aaffb7/products/atoms/pages/platform/features/images/api-tool-value-source.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260902%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260902T185907Z&X-Amz-Expires=604800&X-Amz-Signature=96d5c9992838632db73d0d33bc20ea8463cb416fc8e991c65cbe85d574881f3c&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) | Source | Meaning | Needs | | ------------------------ | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Let the agent decide** | The model fills it from the conversation | A clear description (e.g. "the customer's order number") + a type (Text / Number / Boolean / Enum) and a required flag | | **Agent variable** | A value already known at call time | A variable — pick from **Custom** (your variables) or **System** (`call_id`, `conversation_type`, `agent_number`, `user_number`, `current_date`, `current_time`) | | **Fixed value** | The same on every call | The constant value | On the **Body** tab the same three modes appear as **Agent decides / Agent variable / Fixed value** — same behavior, slightly shorter labels. ## Auth and secrets The **Auth** tab handles authentication. You never paste a raw key here — you reference a [secret](/voice-agents/platform/create-agent/secrets) by name, and the platform injects it into the outbound request at call time. ![Auth tab set to Bearer with a Select secret dropdown and Create new secret option](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/smallest-ai.docs.buildwithfern.com/22f0695414301231f9cfcf89a7fb29d9cf88b990744314eb039661cb457296e0/products/atoms/pages/platform/features/images/api-tool-auth-bearer.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260902%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260902T185907Z&X-Amz-Expires=604800&X-Amz-Signature=fda05c3094d8ce12312dc8eeb509c1ab5b931d5bad0255c83f3a69e0d35424cf&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) | Auth type | Fields | | ----------- | ---------------------------------------------------------------------------------- | | **None** | — | | **Bearer** | A **token** secret → sent as `Authorization: Bearer ` | | **Api Key** | A **name**, a **location** (`header` or `query`), and a **value** secret | | **Basic** | A **username** and a **password** secret → sent as `Authorization: Basic ` | ![Api Key auth with Name, Location header or query, and Value secret picker](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/smallest-ai.docs.buildwithfern.com/63738cfd765c9a99a0abf54e9d1aecca1a910732d8bd07194d7246956ec7afec/products/atoms/pages/platform/features/images/api-tool-auth-apikey.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260902%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260902T185907Z&X-Amz-Expires=604800&X-Amz-Signature=7f8f50c7ec90bfb91c47ff96d51110135cbdeb5894a82e5231d6b001eb26943c&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) The secret is resolved and injected **server-side at call time**, then stripped before the config reaches the runtime — it never appears in the served agent config, call logs, or webhooks. Because of that, the inline **Test API** (below) runs **without** the auth secret, so testing an authenticated tool may return `401`/`403`. Test against a public endpoint, or verify auth on a real call. ## Body For POST/PUT/PATCH, build the body field by field — each field has a **data type** (String / Number / Boolean / Object / Array), an identifier, and a value source. Or switch to **Edit as JSON** for a structured schema view. Live validation blocks a save with a broken body; **Prettify** reformats only. ![Body tab with Add property and Edit as JSON](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/smallest-ai.docs.buildwithfern.com/c836c06e52ebffb3e0fd6ea2cf27e14e685e8d0e94ba963ea30a331209311ffd/products/atoms/pages/platform/features/images/api-tool-body.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260902%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260902T185907Z&X-Amz-Expires=604800&X-Amz-Signature=20f058abd52ed9e533c31a8ea0b1a040bbfc7de4ae52069b31ce52577547bbeb&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) The **Edit as JSON** view is a per-field descriptor map. `value_type` is `llm` (carries a `description` + `required`), `agent_variable` (carries a `variable`), or `fixed` (carries a `literal`): ```json { "customer_name": { "type": "text", "value_type": "llm", "description": "The customer's full name", "required": true }, "user_id": { "type": "string", "value_type": "agent_variable", "variable": "user_id" }, "channel": { "type": "string", "value_type": "fixed", "literal": "web" } } ``` The `type` here is not the same axis in every row, which is expected: for an `llm` field it is the **parameter** type (`text` / `number` / `boolean` / `enum`), while for `agent_variable` and `fixed` fields it is the JSON **data** type (`string` / `number` / `boolean` / `object` / `array`). That is why `customer_name` reads `"type": "text"` and the others read `"type": "string"`. Nested shapes use `{"type": "object", "properties": { … }}` and `{"type": "array", "items": [ … ]}`. ## Timeout and response extraction * **Timeout (ms)** — how long to wait for a response (default 5000). * **Response variable extraction** — map fields from the response into variables the agent can reuse later, by name and JSONPath (e.g. `order_total` ← `$.total`). Add as many as you need. ## Test it Click **Test API**, fill any sample inputs, and **Run test** to fire a live request and see the status + response inline — no separate tool needed. ## Related #### [Tools library](/voice-agents/platform/create-agent/tools) Create once, reference across agents #### [Secrets](/voice-agents/platform/create-agent/secrets) The vault your tool Auth references