> This page is for version Scripted.
> For other versions, use one of these documentation indexes:
> - Generative (default): https://developers.ada.cx/generative/llms.txt
> - Scripted: https://developers.ada.cx/scripted/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.ada.cx/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.ada.cx/_mcp/server.

# Make API requests using the HTTP Request block

## What is the Request block?\[#UUID-e5670829-5c08-ccd9-17b6-c4be1397be71_id_360026752193_id_h_f18ee4be-9b28-4c8b-a1cc-c278f9d86cea]

The Request block lets your bot make calls to an API. The information
you receive from the API can be saved as variables and used in your
Answers. For more information, see [What is a variable?](/scripted/docs/build-and-maintain-your-bot/personalize-conversations/get-started-with-variables#UUID-47544806-121d-a9b6-bc67-8761f3b53924_id_360026518374_id_h_e5f95a5c-4028-491d-a491-06aff4752b7a "What is a variable?").

> **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.
>
> The number of HTTP Request blocks your organization can configure also
> varies depending on your subscription package.

Ada bots support five types of HTTP requests:

* **GET** - Retrieves information

* **POST** - Submits information

* **PATCH** - Makes partial changes to information

* **PUT** - Creates new or overwrites existing information

* **DELETE** - Deletes information

> **Note**
>
> POST, PATCH, PUT, and DELETE all require
> [authentication](/scripted/docs/use-ada-with-your-website/serve-your-website-information-in-chat/let-chatters-sign-into-your-website) to use. You can securely store and retrieve API tokens using the [Token Vault app](/scripted/docs/integrate-ada-with-other-tools/securely-store-api-tokens-using-the-token-vault).

**Example:** Below is what a complete Request block looks like.

![](/_fern-files/_img/5258ba36c1b57eeaa34f75d992667d2b3a11398c172cbfd8dfc939b81f50b80f.webp)

## Set up the Request block to make an API call\[#UUID-e5670829-5c08-ccd9-17b6-c4be1397be71_id_360026752193_id_h_c75911c9-c788-40b1-be55-c3717056d2e5]

1. On the Ada dashboard, go to **Build** > **Answers** and open an existing Answer, or create a new
   one. Drag and drop a **Request block** into the Answer
   editor.
2. Enter the API address in the **URL** field.
3. Select your request type from the **Method** list.
4. If required, use the **Headers** fields to pass
   metadata, like public access tokens, content type, and language.

   **Example:**

   ![](/_fern-files/_img/73960ed6b0bc8efde417624f665b2e039d573de588d08751415f2a4dceb82499.webp)
5. If required, fill out the **Body Content** fields to
   pass details or instructions to the API server. Make sure you accurately
   define the content type (string, number, list, etc.).
6. Click **Test Request** to send a sample API call and
   see the response body that comes back.
   * If you want to repeat the request, click the **Repeat** ![](/_fern-files/_img/3a48ded5acfab3fb6dcec6401213706c47ca799f8b8f6f7c4980b4bb76965574.webp) icon at the top of the response.
   * If you want to copy the response body to your clipboard, click
     the **Copy** icon ![](/_fern-files/_img/4b9927f60dd2b5a2db7839e81277dd6a9415b51258d473d6cd24061432b2e8d8.webp) at the top of the response.
7. Under **Error Answer**, select an Answer to appear as a fallback if the API call is unsuccessful.
8. Under **Save As Variable**, save all or a portion of
   the response body in one or more variables for use in other blocks.

   The easiest way to save a particular attribute is to click a blue
   tag with a “+” icon in the response body to automatically save that
   attribute as a variable. You can select or create a variable to save
   that value in, and the Data Key field automatically populates, as
   below.

   For more complex use cases, you may have to type in a data key
   yourself, so you can target a particular attribute or array in the
   response. For more information, see [Use data keys to target a portion of an API response](#UUID-e5670829-5c08-ccd9-17b6-c4be1397be71_section-idm4491529808793633386703349451).
9. To add an additional variable, you can either click another tag
   in the response body, or click the green “+” icon by the **Save As
   Variable** fields.
**Example:**
![](/_fern-files/developers.ada.cx/f5c36b8ce3c171fbc735d8b042e9cd9f8d6f7ea1c174c5e6df5ceca8afb31fd4/ada.docs.buildwithfern.com/2025-05-28T19:49:52.708Z/versions/assets/image/uuid-015b12c4-761d-af95-0786-821ffde01f9f.gif)
12. Create your Answer content [using the variables](/scripted/docs/build-and-maintain-your-bot/personalize-conversations/use-variables-in-answers) you’ve now saved.

> **Note**
>
> If there are more than five variables within the block, it will be
> collapsed by default the next time you view the Answer. This allows you
> to more easily scroll through the Answer's content. To expand the block
> and view all of the variables, click the arrow icon next to the trash
> can icon in the upper-right corner of the block.

## Use data keys to target a portion of an API response\[#UUID-e5670829-5c08-ccd9-17b6-c4be1397be71_section-idm4491529808793633386703349451]

Data keys are a way to tell your bot to target a portion of the API
request so you can save it as a variable. There is a variety of ways to
do this, depending on your end goal. If you need any assistance, don't
hesitate to contact your Ada team.

### Limitations\[#data-key-limitations]

Before targeting data in your API response, you should know that there are some limitations to how Ada processes the data they contain:

* You can target nested data in your response, but only up to eight levels. If you try to target values that are nested farther down in your response, your bot won't be able to retrieve them.
* Variables can contain up to 100,000 characters. Particularly when you're saving all or part of an API response as a variable, make sure you don't exceed this limit. If you do, you may start seeing errors, because your bot might not be able to correctly parse your variable content.

### Data key notation\[#UUID-e5670829-5c08-ccd9-17b6-c4be1397be71_section-idm4557955708899233388171120898]

Ada uses different types of notation to target different parts of the
response:

* **Target the entire API response**

  To save the entire API response in a variable, use the
  `ada_response_string` data key.

* **Target a specific attribute or array**

  To target a specific attribute or array, enter its name exactly as it
  appears in the API.

  #### Example: Target a specific attribute

  Here's a portion of a response from the above [Studio Ghibli API](https://ghibliapi.herokuapp.com/), which contains information
  about *Princess Mononoke*:

  ```json
  {
    "id": "0440483e-ca0e-4120-8c50-4c8cd9b965d6",
    "title": "Princess Mononoke",
    "original_title": "もののけ姫",
    "original_title_romanised": "Mononoke hime",
    "image": "https://image.tmdb.org/t/p/w600_and_h900_bestv2/jHWmNr7m544fJ8eItsfNk8fs2Ed.jpg",
    "movie_banner": "https://image.tmdb.org/t/p/original/6pTqSq0zYIWCsucJys8q5L92kUY.jpg",
    "description": "Ashitaka, a prince of the disappearing Ainu tribe, is cursed by a demonized boar god and must journey to the west to find a cure. Along the way, he encounters San, a young human woman fighting to protect the forest, and Lady Eboshi, who is trying to destroy it. Ashitaka must find a way to bring balance to this conflict.",
    "director": "Hayao Miyazaki",
    "producer": "Toshio Suzuki",
    "release_date": "1997",
    "running_time": "134",
    "rt_score": "92",
    ...
  }
  ```

  To save the movie title as a variable, use the data key `title`.
  Note that the key has to exactly match what's in the API response, so
  the data key `Title` wouldn't work.

  #### Example: Target a specific array

  If the API request returns an array, you can save the whole array as a
  variable as well. For example, here's a heavily truncated response
  from the [Star Wars API](https://swapi.dev/documentation), which
  contains a list of the *Star Wars* movies:

  ```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",
        ...
      },
    ...
    ]
  }
  ```

  In this case, you could use the `results` data key to save an array
  containing information about all of the movies in your variable.

* **Target a child array or attribute**

  You can use dot or bracket notation to target either arrays or
  attributes nested in other arrays or attributes.

  Any of these notations would get your bot to look for an attribute
  called `parent` and save either an array or attribute within it called `child`:

  * `parent.child`

  * `parent[child]`

  * `"parent"["child"]`

    * Using quotation marks might help if the array or attribute name
      has a space in it. You must use double quotes, as above; if you
      use single quotes (e.g., `'parent'['child']`), the data key won't
      work.

  If you're looking for something nested inside an array, you can target
  a particular instance based on its order in the API response. Note
  that this numbering starts at 0, not at 1, and that these numbers must
  be in brackets.

  For example, with this notation, your bot would look for the *first* item in the array called `parent`, find the array within it called `child`, and save the *second* item within the child array:

  * `parent[0].child[1]`

  * `[parent][0][child][1]`

  * `["parent"][0]["child"][1]`

  > **Warning**
  >
  > This method assumes that responses in the API will always be in the
  > same order. Remember to test your API request with a variety of
  > scenarios to ensure your data key correctly selects the attribute
  > you're looking for. If you find that the order of items in your API
  > response varies between calls, contact your Ada team to find a
  > solution.

  #### Example: Target attributes or arrays nested in an array

  Here's another example from the Star Wars API, this time with a list
  of species that appear in the movies:

  ```json
  {
    ...
    "results": [
      {
        "name": "Human",
        "classification": "mammal",
        "designation": "sentient",
        ...
        "films": [
          "https://swapi.dev/api/films/1/",
          "https://swapi.dev/api/films/2/",
          "https://swapi.dev/api/films/3/", 
          "https://swapi.dev/api/films/4/", 
          "https://swapi.dev/api/films/5/", 
          "https://swapi.dev/api/films/6/"
        ],
        ...
      },
      ...
    ]
  }
  ```

  "Human" is the first item in the list of *Star Wars* species in the
  `results` array, so if we want to target a piece of information that
  pertains to human characters, we'll start the data key with
  `results[0]`. From there, we can start targeting more specific
  information:

  * To target the `name` attribute of the species, use the data key
    `results[0].name`.

  * To target the entire array of *Star Wars* films in which humans
    appear, use the data key `results[0].films`.

  * To target only the fourth *Star Wars* film in which humans appear,
    use the data key `results[0].films[3]`.

## Frequently asked questions\[#UUID-e5670829-5c08-ccd9-17b6-c4be1397be71_id_360026752193_id_h_ad7a8046-4ef6-4dee-a0d4-b0301d698b26]

**Q: I sometimes get "Failed to Load Variable" emails, telling me a
variable in my Request block has a bad access key and that I should
remove it. What does that mean? Does that mean my Request block isn't
working?**

A: Not necessarily. Those emails are Ada's way of giving you a heads up
that it was expecting data to be passed to that variable from your
database, but nothing corresponding to that variable was received from
your API.

There are a few reasons why this may happen. You may need to double
check your API configuration and ensure that there is indeed information
that should be passed to that variable. However, there are many cases
where data doesn't need to be passed to the bot.

For example, if you're an e-commerce company and you're using the bot to
track orders, you may have two variables that cover the customer's
address and apartment number. But say a customer purchases something
from your site and they don't live in an apartment (and therefore have
no apartment number). When they look up their order status in the bot,
your API has no apartment number associated with that account, and
therefore nothing to pass to the variable. You'll then receive a Failed
to Load Variable email. It doesn't mean anything went wrong, just that
there was no information to pass to the bot at that time.

**Q: When my team and I are creating an API for the bot, do we need
readable strings for individual values? Is there anything the bot can't
"read"? Is there anything else that we should consider?**

A: As a general rule, the Request block supports JSON format for the API
request and response. If the response from the API is anything other
than JSON, the Request block will provide the chatter with the block’s
error Answer.

Currently, all non-200 status codes trigger the Request block's error
Answer. As a result, we recommend sending a 200 "OK" status for cases in
which the API endpoint is reachable and you want to provide chatters
with descriptive error messages.

---

Have any questions? Contact your Ada team, or email us at [](<mailto:help@ada.support%20%E2%80%9CHelp Docs inquiry%E2%80%9D>).