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

# Request block

## Overview

The Request block makes an API call. You can save all or part of the response as a variable so you can serve the content in text blocks, or use the response to populate a list of options in the [List Option block](/docs/handoffs/handoff-management/blocks/list-option-block).

The Request block also supports triggering custom handoff integrations via the [Handoffs API](/api-reference/conversations/introduction). When configured as a handoff trigger, the block calls your integration's endpoint and automatically manages the conversation's handoff state.

## Use as a handoff trigger

The Request block can initiate a handoff to an external live agent platform or internal system. When the handoff options are enabled, the block handles handoff state management automatically:

* **On a successful response**, the conversation enters a handoff state. The AI Agent stops responding, and your integration takes over.
* **On a failed response**, the conversation is cleaned up and redirected to the error fallback block.

> **Warning**
>
> When using the Request block as a handoff trigger, place it inside a Handoff flow. Do not use it directly in a Playbook or Action. Starting a handoff outside of a Handoff flow can cause unexpected behavior, including the AI Agent responding during an active handoff.

**To configure the Request block as a handoff trigger:**

1. Add a Request block to your handoff flow.

2. Set the **Method** to the HTTP method your integration expects (for example, POST).

3. Enter your integration's endpoint URL in the **URL** field (for example, `https://your-integration.example.com/webhooks/start-handoff`).

4. Under **Body Content**, pass the data your integration needs to start the handoff. At minimum, include the conversation ID:

   | Key                   | Value              | Type   |
   | --------------------- | ------------------ | ------ |
   | `ada_conversation_id` | `@conversation_id` | string |

   You can also pass additional context such as end user ID, custom metadata, or routing information.

5. Enable the **Track as Handoff** option. This tells the AI Agent to enter a handoff state when the request succeeds.

6. Enable the **Pause conversation here until handoff ends** option. This prevents the AI Agent from responding while the handoff is active.

7. Set the **Handoff integration label** to a unique identifier for your integration (for example, `my-custom-handoff`). This value appears as the `handoff_integration` field on the conversation and in webhook events. Use it to filter webhook deliveries via Svix Channels so each integration only receives its own events.

For a complete working example, see the [ada-handoffs-api-demo](https://github.com/AdaSupport/ada-handoffs-api-demo) repository. For a full end-to-end walkthrough of building a custom handoff integration, see the [Creating a custom handoff](/reference/conversations/developer-guides/creating-a-custom-handoff) developer guide.

## Limitations

The Request block has the following constraints when processing API responses:

* 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 AI Agent 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 AI Agent might not be able to correctly parse your variable content.

## Configuration

Set up an API call and save all or part of the response as variables for use in other blocks.

**To configure the Request block:**

1. Enter the API address in the **URL** field.

2. Select your request type from the **Method** list.

3. If required, use the **Headers** fields to pass metadata, like public access tokens, content type, and language.

   **Example:**

   ![](/_fern-img/73960ed6b0bc8efde417624f665b2e039d573de588d08751415f2a4dceb82499.webp)

4. 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.).

5. 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-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-img/4b9927f60dd2b5a2db7839e81277dd6a9415b51258d473d6cd24061432b2e8d8.webp) at the top of the response.

6. Under **Error fallback**, you can click to edit the AI Agent's response if an error occurs and it can't complete the call successfully.

7. 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.

   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 [Data keys](#use-data-keys).

8. 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.

### Data keys

Data keys are a way to tell your AI Agent 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.

#### Data key notation

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

#### Learn more

Here's a portion of a response from the [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

#### Learn more

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 AI Agent 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 AI Agent 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

#### Learn more

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 to target a piece of information that pertains to human characters, start the data key with `results[0]`. From there, target 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]`.

---

Have any questions? Contact your Ada team, or email us at [](mailto:help@ada.cx?subject=Help%20Docs%20inquiry).