APIs: Send HTTP Request

This actions makes API requests in your workflow.

To explain how to use it, we will go over a specific example in which we send an API request to open.ai to get answers to questions saved in a table. In this example, open.ai is used to let AI generate answers to pre-defined questions.

Note: The example with open.ai is simply used for demonstration purposes in order to show how to make custom API calls.

If you really need to send a request to open.ai, simply use Ask ChatGPT building block which conveniently contains all the configuration options you need. Normally, you do not need to use Send HTTP Request building block for interacting with open.ai.

Example: OpenAI Final Set-up

In the picture, you can see the final set-up you need to do, and we will go over each option in more detail below:

Select method

Here you can select different methods (PUT, POST, GET, PATCH, etc.) to create your specific API request.

In the example of open.ai, we need to select POST. To determine what method you need to use, you need to check the documentation or a tutorial page of the API that you are using.

URL

Insert the url that you want to call.

Beware that some request URLs require slash at the end and some don't. If you add an unnecessary slash, you request may not go through.

You can add dynamic data from tables as well. Let's diverge from open.ai for a moment and take another example: Imagine you need to identify a likely age group that your lead or prospect belongs to. For that, you can call agify api. The api url is https://api.agify.io?name=michael. As you can see, the name "michael" is dynamic and so you can simply replace that by a table reference. This way in every loop iteration, your TaskBot will make a request with a different name.

Headers

You need to check the requirements of your API what headers you need to add. Often, authorization header is required. For example, in open.ai, you would need to add these two headers:

Body

You need to check the requirements of your API if you need to add any body. In open.ai, you would likely need to add the question that you want to get the answer to in your body, and so it would look like this:

Note that the body includes a table reference, as you might want to iterate over a list of questions or get the question dynamically from a different source.

Save Data from Response

Before you hit RUN to call the API, you need to create a table with matching columns. In a moment, you will learn how column matching with API's response keys is done. For now, make sure to create an empty table or use an existing one and then select it in the dropdown Save response body, as shown below:

In case that you do not need to save response - for example, because it's a patch request where you do not expect to receive any response - simply leave that dropdown empty.

In the open.ai example, we want to save the answer and this is why we need to create and select a table (in this example called "Answers").

Column Matching and Record Path

Your TaskBot will automatically match data from keys to your columns, unless there are nested key-value pairs.

For now, let's leave nested key-value pairs aside (we'll get to it in a moment) and assume that your API call returns a simple response with keys on the same level without any nested values like so:

In this case, you need to create a table that contains columns that you want to save response to, like so:

Note that this table only contains name and age but it doesn't contain count. This is because you are flexible on what keys to save. So if your table contains columns that are not part of the keys in the API response or, like in the example above, does not contain some keys that are part of the API response, those will simply be ignored. In other words, you can add count if you want or you can omit it if that piece of data does not need to be saved.

After hitting RUN, this is how the data will be populated:

Nested key-values and record path

Let's get back to the open.ai example. Sample response from open.ai looks like this:

{
    "id": "cmpl-GERzeJQ4lvqPk8SkZu4XMIuR",
    "object": "text_completion",
    "created": 1586839808,
    "model": "text-davinci:003",
    "choices": [
        {
            "text": “THIS IS THE ANSWER TO THE QUESTION THAT WE WANT TO SAVE"
            "index": 0,
            "logprobs": null,
            "finish_reason": "length"
        }
    ],
    "usage": {
        "prompt_tokens": 5,
        "completion_tokens": 7,
        "total_tokens": 12
    }
}

In this case, we have non-nested and nested values. So if you wanted to save id, object, created and model, you would simply create a table with columns named exactly like that, as explained in the example above.

But for those key-values that are nested, we need to create a record path like so:

choices[0]['text']

Any value inside a list marked by square brackets needs to be accessed with numbers where 0 corresponds to the first item, 1 to the second, etc. placed into square brackets. Any value inside a nested object marked by braces needs to be accessed with its key placed into square brackets.

This record path has to be added extra to the building block like so:

The nested path also needs to be added as a column name to the table:

Save Status Response

You can save the response code to a table. This allows you to recognise errors in the workflow for 400 or 500 codes, so that your TaskBot can handle them accordingly.

Example: Break loop if status request is unsuccessful

A typical example would be to break the loop in case the status is not equal 200 (200 means success) as shown here:

Invalid JSON Body Error

Beware that json format does not accept double quotes inside the double quotes. See example below.

Remove double quotes from dynamic data

Since you may be getting this data dynamically from a website or from a user input (in case you use parameters or table references), you may want to first replace double quotes by single quotes using Format Data building block and selection the option Replace text, as shown below: