Playbook API tool docs

In this video, we’re going to walk through how to call an API inside a playbook. As you can see, I’ve created a playbook called What’s the Forecast, which is triggered when the user asks about the weather today.

The first step is asking the user: Which city are you in? After that, we’ll set up the API tool.

To do that, click Add Tool, then choose Custom API Tool. Here, you can enter the endpoint URL. In this example, we’re using the Weather API.

You can use any API you want—just fill in the headers and parameters as needed. The POST request can also be customized. If you check the Weather API documentation, you’ll see that their API is called using this URL along with two query parameters.

I’m including two parameters: key and q.

The Description field is important—it tells the AI how to extract the correct query or payload values from the user’s conversation.

For the parameter key, we’ll always pass the API key.

For the second parameter, q, we’ll pass the name of the city—for example, London or Toronto.

Next, we need to test the API call.

Paste in the same API key, enter “Toronto” as the city, send the test request, and you should receive a 200 response with all the data you need.

Now let’s name the API tool—here, we’ll call it Weather Forecast—and add a description, such as Get the weather forecast for a specific city.

Add the tool to the playbook.

Now, in our second step, we can use this tool by selecting Weather Forecast.

You can also configure the tool here if you want to adjust its parameters.

Let’s save the playbook and try it out.

If we ask, What’s the weather today?, and then specify “Toronto,” the playbook will call the API…

…and return the information we requested. For example: Toronto, Ontario — the weather is partly cloudy, around 5 degrees, and the humidity is about 81%. That matches the actual data.

And that’s it—that’s how you call an API inside a playbook.