> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ada.cx/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server. # API tool control ## Overview You can expand your AI Agent's functionality by configuring API tools. Each API tool consists of an API call that you can configure behind the scenes. Then, your AI Agent automatically determines when to use it and how to handle the response. > **Note** > > This feature may not be included with your organization's subscription > package. For more information, see Ada's > [Pricing](https://www.ada.cx/pricing) page, or contact your Ada team. ## Limitations API tools have the following constraints. * You can have a maximum of **five active**, customer-facing API tools per AI Agent. You can have additional draft API tools saved in your AI Agent, but those won't affect your AI Agent's responses. * This default limit is configurable and does not represent the maximum capability of the API tools framework. To discuss adjustments, contact your Ada Customer Success Consultant (CSC) or the Accelerate team. ## Use cases API tools enable your AI Agent to retrieve real-time data and perform tasks on behalf of end users. * **Order tracking**: Look up order status, shipping details, or delivery estimates from your e-commerce or fulfillment system. * **Account information**: Retrieve account balances, subscription details, or usage data from your backend systems. * **Product availability**: Query inventory systems to provide real-time stock information. ## Capabilities & configuration API tools allow you to configure API integrations that your AI Agent uses automatically during conversations. * **API integration**: Connect to external systems using GET, POST, PUT, PATCH, or DELETE methods. * **Authentication**: Securely store and reference static or customer login Tokens for authenticated API calls. * **Inputs**: Collect information from end users (such as order ID or email) to include in API requests. On the Voice channel, you can also control how each input is captured and confirmed — see [Voice call capture options](/docs/channels/voice/voice-configuration/voice-call-capture-options). * **Outputs**: Extract specific data from API responses for your AI Agent to use in replies. * **Access control**: Restrict API tools to specific end users based on variable conditions. * **Usage control**: Limit API tools to run only within [Processes](/docs/automation/processes) or [Playbooks](/docs/automation/playbooks), or allow independent use. ## Quick start Get an API tool running in minutes with this streamlined setup. **To create a basic API tool:** Go to **Config > AI AGENT > Tools**, select **＋ Tools**, then **New API tool**. Enter a **Name** and **Description** that explain when your AI Agent should use the API tool. Under **Connect to API**, enter the API **URL** and select the **Method**. Click **Test** to verify the API response. Under **Use API outputs in chat**, click a portion of the response to add it as an output. Click **Publish** to make the API tool available to end users. For detailed configuration options, see [Create an API tool](#create-an-action). ## Implementation & usage Configure and manage API tools to extend your AI Agent's capabilities. ### Create an API tool\[#create-an-action] Configure an API call that your AI Agent can use to retrieve external data and include it in responses to end users. **To create an API tool:** 1. On the Ada dashboard, go to **Config > AI AGENT > Tools**. 2. If the API call you're configuring requires authentication, you can add an authentication token that Ada stores securely. For more information, see [Authenticate your AI Agent's API calls using tokens](/docs/automation/tools/api-tools/token-configuration). Then, you can reference that token in one or more API tools, without the contents of the token being visible in the UI. To reference the token in an API tool, you can type `@` and start typing the name of the token to insert it. 3. Select **＋ Tools**, then **New API tool**. The **New API tool** page opens. 4. Under **Identify this API tool**, enter a **Name** and **Description** for the API tool. The Name and Description provide important context to your AI Agent about when it should make the API call. Imagine you're explaining to a human agent when they should perform the API call and the information you want to provide to end users - your name and description should cover this information. 5. Under **Set usage**, the **AI Agent only uses this API tool within Processes or Playbooks** check box is selected by default. This means that the API tool is restricted to only being used when a [Process](/docs/automation/processes) or [Playbook](/docs/automation/playbooks) refers to it. Clear the check box if you want your AI Agent to be able to run the action independently, rather than in a larger step-by-step Playbook or Process. 6. If required, you can restrict API tools to certain users, based on information your AI Agent collects about your users and saves in variables. > **Note** > > You can only use variables your AI Agent can collect through your browser, or that you collect in a block and allow to be available outside of the structured content the block is in. You can't use variables your AI Agent collects using API tools. * To make the API tool available to all users, select **Everyone**. * To restrict the API tool to certain users, select **Based on the following rules**. A section expands where you can enter the logic your AI Agent uses to decide whether to run the API tool. 1. Under **Where**, in the **Choose a variable** list, select a variable. 2. In the next dropdown, select an operator so you can define a relationship between the variable and the value you want to target. #### Understand comparison operators Comparison operators are logic statements that tell your AI Agent to match end user information that's captured in the variable you're using. The available operators vary based on the variable type you're using: | **Operator** | **Variable types** | **Description** | | :---------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------- | | ![Begins With icon](/_fern-img/e8b9c807586a4238654793da51b49ec15e7045c0691d461567178070e57a1840.webp) **Begins With** | - All text variables (including phone and email) | Match information in the variable that begins with certain text (partial match). | | ![Ends With icon](/_fern-img/9bc404d3db5ea684a901bf8426485894bb62abb8369e498b98dc4e4f3807a5ec.webp) **Ends With** | - All text variables (including phone and email) | Match information in the variable that ends with certain text (partial match). | | ![Contains icon](/_fern-img/a4f0225811b1ecde2f125de907c2ad1b084268805cd89a00f465649ddbf8eaa2.webp) **Contains** | - All text variables (including phone and email)- List variables | Match information in the variable that contains certain text in any position (partial match). | | ![Is icon](/_fern-img/7266dedcf2da1af5c496469379bd4fb68d5e65492c190e9567c75edbbbf7e260.webp) **Is** | - All text variables (including phone and email) - Number variables | Match information in the variable that equals specific text exactly (exact match). | | ![Is Not icon](/_fern-img/d94952ab65e9f266413c582390a1d702ebb32c7a2023709ee96741b6df1b17e4.webp) **Is Not** | - All text variables (including phone and email) - Number variables | Match information in the variable that does not equal specific text exactly (exact match). | | ![Is Not Set icon](/_fern-img/283cad3d89c7d92f279d722592cd958630a40527266a47d316ab3b3b2051b71f.webp) **Is Not Set** | - All text variables (including phone and email) - Number variables - List variables | Match if there is no information contained in the variable. | | ![Is Set icon](/_fern-img/8c1019797a0482018682d52622c9e2fe56ddc5aef8925dc3e3db678c121c6869.webp) **Is Set** | - All text variables (including phone and email) - Number variables - List variables | Match if there is any information contained in the variable. | | ![Greater Than icon](/_fern-img/45636711dfe933087353da3923c6865b6816ea671ad6e9db4739aeea4c80a697.webp) **Greater Than** | - Number variables | Match if the information in the variable is greater than a specific value. | | ![Less Than icon](/_fern-img/f2448b33a8931270e63ea8daab74e67ade1fdfdf1f8853529c2fb0a3e5abda55.webp) **Less Than** | - Number variables - List variables | Match if the information in the variable is less than a specific value. | | ![Is True icon](/_fern-img/fcf3fe21099df957ee22609d5a5c211601d3e402fcc8402c12115f4680a692b0.webp) **Is True** | - Yes/No variables | Match if the information in a variable is Yes (or True). | | ![Is False icon](/_fern-img/2b5c661e7e4445f1ea8f7736ee5b58b14f72283faf2dbd4f01220a26d621b238.webp) **Is False** | - Yes/No variables | Match if the information in a variable is No (or False). | | ![Does Not Contain icon](/_fern-img/2a459cf7a992abeb5cbdf8438f9f1be356bb5fcf915f55f7f1c2cdc3173b101d.webp) **Does Not Contain** | - List variables | Match if none of the selected items contains this value. | | ![Is Equal To icon](/_fern-img/7266dedcf2da1af5c496469379bd4fb68d5e65492c190e9567c75edbbbf7e260.webp) **Is Equal To** | - List variables | Match if the end user selected a particular number of options in a **List Option** block. | | ![Is Greater Than icon](/_fern-img/45636711dfe933087353da3923c6865b6816ea671ad6e9db4739aeea4c80a697.webp) **Is Greater Than** | - List variables | Match if the end user selected more than a particular number of options in a **List Option** block. | | ![Is Less Than icon](/_fern-img/f2448b33a8931270e63ea8daab74e67ade1fdfdf1f8853529c2fb0a3e5abda55.webp) **Is Less Than** | - List variables | Match if the end user selected fewer than a particular number of options in a **List Option** block. | 6. In the **Value** field, enter or select a value for the variable that you want to use to target users. 7. If required, add additional conditions. * To add a new **top-level** condition, click **Add** ![](/_fern-img/eaf3e27905dfafde4c1138201d5674737788133775fed7625fcd3f098c6628f3.webp). If you're adding your first additional top-level condition, in the dropdown that appears, choose **And** or **Or** as the operator for all of your top-level conditions. * To create or add to a **group** of conditions, click the **Add to group** icon ![](/_fern-img/881a5902ee010bd99b16914b2ac663810ad93cade88c2fddc273b4c3bc508b28.webp) beside a condition you want to include in the group. If you're creating a group, in the dropdown that appears, choose **And** or **Or** as the operator for all of the conditions in that group. 7. Under **Acknowledgment (Optional)**, control what your AI Agent says immediately before it starts this API tool. Leave the field blank to let the AI Agent word the acknowledgment itself. Enter an instruction of up to 500 characters to guide what it says. To fix the exact wording, make the whole instruction `say exactly "your text"`. The AI Agent then says your text word for word. Exact wording is never translated. If your AI Agent serves multiple languages, use a regular instruction instead. Voice conversations always send acknowledgment messages. Messaging conversations follow the **Send acknowledgement messages** setting in [personality settings](/docs/setup/persona/personality-setup). If that setting is off, select **Always acknowledge on Chat for this API tool** to send acknowledgments for this API tool only. 8. Under **Get input from chat**, you can tell the AI Agent to ask end users for information it needs to make the API call. If your API call doesn't require any additional information from the end user, you can skip this step. > **Note** > > If you add inputs to your API tool, you must also include them in your > API call, or your AI Agent won't save your API tool. 1. Under **Input**, enter an identifier for the information you need to put into the API call. 2. Make sure you format the name so it can go into a URL (e.g,. use underscores instead of spaces). The name should be descriptive so your AI Agent knows what kind of information to collect from the end user (e.g., `email` or `order_id`). You can click **Add** to add additional inputs as needed. 9. Under **Connect to API**, enter the structure of the API call, using any tokens or inputs you created, or pieces of information the browser collected as a metavariable. For more information on how it does this, see [setMetaFields](/chat/web/sdk-api-reference#setmetafields) in the Chat SDK documentation. For Messaging, use [`setMetaFields`](/messaging/web/sdk-api-reference#setmetafields) or [`setSensitiveMetaFields`](/messaging/web/sdk-api-reference#setsensitivemetafields) for configured API tool inputs. Check the [Messaging metadata limits](/messaging/introduction/reporting-differences-from-the-chat-sdk#meta-field-limits) before adapting legacy examples. 1. On the **Endpoint** tab, under **URL**, enter the URL of the endpoint. You can type `@` to see a list of available tokens, inputs, or metavariables that you can select as a placeholder to include in the URL. 2. Under **Method**, choose the HTTP method for your call (GET, POST, PATCH, PUT, or DELETE). 3. If required, you can add headers to your call. To add headers, click the **Headers** tab, click **Add headers**, then add values in the **Parameter** and **Value** fields. You can click **Add** to continue adding additional headers as required. 4. If you're making a POST, PATCH, or PUT request, on the **Body** tab, enter the payload for your request. 5. Under **This API uses**, select one of the following options:
Option Content-Type header used What it means When to choose it
**JSON** `application/json` A structured, modern data format commonly used by APIs. When your API expects JSON in the request or returns JSON in the response.
**XML** `application/xml` A markup-based data format used by some older or traditional systems. When your API requires XML data or returns XML responses.
**URL Form Encoded** `application/x-www-form-urlencoded` A simple key–value format, similar to how a web form submits information. When your API expects form-style request data (e.g., simple POST requests, OAuth flows, token exchanges).
10. Under **Test API Response**, you can test the API response to test whether it's properly configured. From there, you can target portions of that response for your AI Agent to use in its responses to end users. * If your call doesn't have any custom inputs, click **Test** to make a test call. * If you created custom inputs, click **Set test values**. The **Set test values** window opens. For each input, enter a value to temporarily use for your test API call. Then, click **Save and test** to make a test call using those values. If your call was successful, a response appears. You can hover over a portion of the response to highlight it, then click **Add output** to automatically populate the path to that portion of the response as an output for the next step. 11. Under **Use API outputs in chat (Optional)**, you can specify portions of the API response that your AI Agent should save to include in its responses. If you don't specify any outputs, your AI Agent still makes the API call, but it won't use any information from the response when generating replies to end users. 1. Under **Output**, enter a name for the output. Names help give your AI Agent more context for how to use that output in its responses to end users, and if applicable, in other API tools. 2. Under **Path**, either enter a path to capture the desired portion of the API response, or use a pre-populated path from your response. The Path field uses JMESPath, which is a syntax that allows you to target part of an API response. For instructions and examples you can use if you need to write your own, click to open this expander: #### Use JMESPath to save a portion of a JSON API response You can use JMESPath to save portions of the API response for your AI Agent to use with end users. Even if the API response you're using is in XML format, your AI Agent converts it to JSON so you can write all of your paths the same way. As an example, let's use the [Star Wars API](https://swapi.dev/documentation), which returns information about the *Star Wars* movies. If you use the `/films` endpoint, you get a long list of films and attributes that looks something like this heavily truncated version: ```json { ... "results": [ { "title": "A New Hope", "episode_id": 4, "opening_crawl": "It is a period of civil war...", "director": "George Lucas", "producer": "Gary Kurtz, Rick McCallum", "release_date": "1977-05-25", ... }, { "title": "The Empire Strikes Back", "episode_id": 5, "opening_crawl": "It is a dark time for the Rebellion...", "director": "Irvin Kershner", "producer": "Gary Kurtz, Rick McCallum", "release_date": "1980-05-17", ... }, ... ] } ``` You can target particular attributes or arrays in the response, depending on how the response is structured and what you're looking for. Consider using the [JMESPath online evaluator](https://jmespath.org/) with your API response to verify that your path is successfully targeting the attributes you need. You can read the [full documentation](https://jmespath.org/tutorial.html) at the JMESPath website to learn about the full list of available operators, but to get started quickly, here are some important techniques you're likely to use: * In general, write a statement that goes from the broadest level of the API response down to the specific attributes that you're trying to target. Some responses only have one level, or maybe all you want is a top-level attribute, which means you don't have to worry about nesting. If that's the case, your path can just be the name of the attribute you want to target. * If your API response contains nested attributes, here are several ways to target them: * After the parent attribute, you can denote which items in the array you want to target: * Use empty brackets `[]` to return all child items in a single list. * Put a number in the brackets, like `[0]`, to return a specific child item. Again, remember that JMESPath starts counting at 0, not 1. * You can filter results based on criteria you put in the brackets. * Use `.` before the name of a child attribute. You can target several levels of nested attributes if required. * If the name of an attribute contains a hyphen, you have to put it in double quotation marks `""` so JMESPath can recognize it. Here are a few simple examples of how to target specific parts of the Star Wars API response:
Intent JMESPath Result
Save everything in the `results` array `results` ```json [ { "title": "A New Hope", "episode_id": 4, "opening_crawl": "It is a period of civil war...", "director": "George Lucas", "producer": "Gary Kurtz, Rick McCallum", "release_date": "1977-05-25", ... }, { "title": "The Empire Strikes Back", "episode_id": 5, "opening_crawl": "It is a dark time for the Rebellion...", "director": "Irvin Kershner", "producer": "Gary Kurtz, Rick McCallum", "release_date": "1980-05-17", ... }, ... ] ```
Save all movie titles in the response `results[].title` ```json [ "A New Hope", "The Empire Strikes Back", "Return of the Jedi", "The Phantom Menace", "Attack of the Clones", "Revenge of the Sith" ] ```
Save all info associated with the first movie in the response `results[0]` ```json { "title": "A New Hope", "episode_id": 4, "opening_crawl": "It is a period of civil war...", "director": "George Lucas", "producer": "Gary Kurtz, Rick McCallum", "release_date": "1977-05-25", ... } ```
Save the name of the director of the first movie in the response `results[0].director` ``` "George Lucas" ```
Save a list of characters that were in the first movie in the response `results[0].characters` ```json [ [ "https://swapi.dev/api/people/1/", "https://swapi.dev/api/people/2/", "https://swapi.dev/api/people/3/", "https://swapi.dev/api/people/4/", "https://swapi.dev/api/people/5/", ... ] ] ```
Save a list of movie titles that were released before January 1, 1990 ``results[?release_date<`1990-01-01`].title`` ```json [ "A New Hope", "The Empire Strikes Back", "Return of the Jedi" ] ```
12. **Give my AI Agent access to this information**: Enable this toggle to make the API tool's output available for use within a Process, for example, by other API tools or steps that depend on that data. If this toggle is disabled, the AI Agent does not read the output. 13. **Save output as variable**: Enable this toggle to store the API tool's output in a variable that can be reused later in the Process. You can then reference that variable in later steps. The two toggles work independently. Enable one, the other, both, or neither. An output with both toggles disabled is not saved to a variable and is not shown to the AI Agent. You can click **Add**, or click additional portions of the test response, to add additional outputs as needed. 12. At the top of the page, you can click **Save changes** to save your API tool as a draft, or click **Publish** to test it and make it available to end users. 13. Click **Test** to ensure that your AI Agent triggers your API tool and includes information from the API response as expected. Make sure you test different ways of phrasing questions, and if you included different outputs, different ways of asking for that information. If you find that your AI Agent isn't responding properly, use an API client like Postman to verify that your call is formatted correctly, or consider editing the description of your API tool or output names so your AI Agent can understand them more clearly. > **Tip** > > Because your AI Agent sends the relevant portion of the API response > through an LLM, the wording in your AI Agent's responses varies between > tests. While testing, focus on the information your AI Agent sends back, > rather than the exact wording the LLM generates. ### Edit or delete an API tool\[#UUID-5a6fd489-8115-32c5-1055-a1bb8b2f00c3\_section-idm4605534416368033931003632602] You can modify or remove an API tool at any time. **To edit or delete an API tool:** 1. On the Ada dashboard, go to **Config > AI AGENT > Tools**. 2. Click the API tool you want to modify, then make the required changes. * If the API tool is a draft and you want to save changes to the draft without making the API tool available to end users, click **Save changes**. * If the API tool is a draft and you want to make it active, click **Publish**. As soon as you publish it, it becomes available to end users. * If the API tool is active and you want to remove it from being active without deleting it, click **Convert to draft**. As soon as it becomes a draft, end users stop being able to use it. * To delete the API tool, click the **More options** button ![](/_fern-img/92f471415d4d83cfacae59466c84e0bf868d9e4c6ac35dea1211ad64140bcd87.webp) and click **Delete API tool**. In the confirmation message that appears, click **Delete** again. ## Related features * [Token configuration](/docs/automation/tools/api-tools/token-configuration): Securely store authentication Tokens for API calls that require authentication. * [Processes](/docs/automation/processes): Build multi-step workflows that can include API tools as building blocks. * [Playbooks](/docs/automation/playbooks): Define step-by-step instructions for handling specific topics or tasks. * [API tool response time](/docs/optimization/conversations#api-tool-response-time): Review how long each API tool took to respond in a conversation. --- Have any questions? Contact your Ada team, or email us at [](mailto:help@ada.cx?subject=Help%20Docs%20inquiry).