# HTTP

{% hint style="info" %}
The following documentation is for **HTTP v1.7.0** *(BDK)*.
{% endhint %}

## Overview

HTTP integration provides fundamental web communication capabilities for API interactions and web service calls. This integration supports GET, POST, PUT, DELETE, and other HTTP methods for seamless API integration. Enable your workflows to communicate with any REST API or web service.

## Prerequisites

### 1. Required Books

The following Book(s) need to be added to your agent so it can learn and understand the automation procedures defined within them:

* **HTTP**

#### How to Add the Book(s)

1. Go to **Books** → **All Books**.
2. Search for the name of the book and click on it.
3. Click on <kbd>**Install**</kbd> or <kbd>**Add Connection**</kbd> to add the book to your agent.
4. If adding a connection, you'll be prompted for [**connectivity**](#connectivity) details.

## Connectivity

This section outlines the available methods for connecting to the Book, along with the required configuration details for each.

### Connect using API Key

Connect to the HTTP server using an API key. The API key will be sent as a x-api-key header in every request.

| Label   | Description        | Type        |
| ------- | ------------------ | ----------- |
| API Key | The API key value. | `sensitive` |

### Connect using Username and Password

Connect to the HTTP server using basic authentication. Note: If connect is set, "Authorization" header will be added automatically to the request and manually set "Authorization" header will be ignored.

| Label    | Description                            | Type        |
| -------- | -------------------------------------- | ----------- |
| Username | The username for basic authentication. | `text`      |
| Password | The password for basic authentication. | `sensitive` |

### Connect using Token URL, Client ID and Client Secret

Connect to the HTTP server using client credentials method. Note: If connect is set, "Authorization" header will be added automatically to the request and manually set "Authorization" header will be ignored.

| Label         | Description                               | Type        |
| ------------- | ----------------------------------------- | ----------- |
| Token URL     | The token URL for client credentials.     | `text`      |
| Client ID     | The client ID for client credentials.     | `text`      |
| Client Secret | The client secret for client credentials. | `sensitive` |

### Connect using Username and Password

Connect to the HTTP server using digest authentication. Note: If connect is set, "Authorization" header will be added automatically to the request and manually set "Authorization" header will be ignored.

| Label    | Description                             | Type        |
| -------- | --------------------------------------- | ----------- |
| Username | The username for digest authentication. | `text`      |
| Password | The password for digest authentication. | `sensitive` |

### Connect using Token URL, Username, Password, Client ID and Client Secret

Connect to the HTTP server using password grant method. Note: If connect is set, "Authorization" header will be added automatically to the request and manually set "Authorization" header will be ignored.

| Label         | Description                           | Type        |
| ------------- | ------------------------------------- | ----------- |
| Token URL     | The token URL for password grant.     | `text`      |
| Username      | The username for password grant.      | `text`      |
| Password      | The password for password grant.      | `sensitive` |
| Client ID     | The client ID for password grant.     | `text`      |
| Client Secret | The client secret for password grant. | `sensitive` |

### Configuration

The following table details all the available configuration options for this book.

| Concept                    | Description                                                                                                   | Type      | Default Value |
| -------------------------- | ------------------------------------------------------------------------------------------------------------- | --------- | ------------- |
| `timeout`                  | Get the value of the timeout.                                                                                 | `number`  | 30            |
| `offload threshold`        | The size in MB of the maximum payload size that will be returned in the response as it comes from the server. | `number`  | 5             |
| `allow insecure transport` | Get the value of the allow insecure transport.                                                                | `boolean` | False         |

Configuration can be set or retrieved as shown in the following examples:

```generic
the department's HTTP's timeout is 30
```

```generic
the department's HTTP's offload threshold is 5
```

## Procedures

### to delete a url

Make a DELETE request to the specified url.

**Input Concepts**

| Concept   | Description                                                                                                                                                                                                                          | Type   | Required | Default Value |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | -------- | ------------- |
| `url`     | The URL to make the DELETE request to.                                                                                                                                                                                               | `text` | Yes      | (no default)  |
| `headers` | The headers to include in the request. For example {"Authorization": "Bearer "}. Note: If connect is set, "Authorization" header will be added automatically to the request and manually set "Authorization" header will be ignored. | `json` | No       | (no default)  |

**Output Concepts**

| Concept  | Description                           | Type                                  |
| -------- | ------------------------------------- | ------------------------------------- |
| `answer` | The response from the DELETE request. | \`\` or `file` or `list of` or `text` |

**Examples**

Delete a post with the following details

```generic
delete "https://jsonplaceholder.typicode.com/posts/1"
```

Delete a post with Authentication header

```generic
create a json
use the above as the headers input
set the headers input's "Authentication" to "Bearer <token>"
delete "https://jsonplaceholder.typicode.com/posts/1"
... the headers is the headers input
```

### to head a url

Make a HEAD request to the specified url.

**Input Concepts**

| Concept   | Description                                                                                                                                                                                                                          | Type   | Required | Default Value |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | -------- | ------------- |
| `url`     | The URL to make the HEAD request to.                                                                                                                                                                                                 | `text` | Yes      | (no default)  |
| `headers` | The headers to include in the request. For example {"Authorization": "Bearer "}. Note: If connect is set, "Authorization" header will be added automatically to the request and manually set "Authorization" header will be ignored. | `json` | No       | (no default)  |

**Output Concepts**

| Concept  | Description                         | Type                                  |
| -------- | ----------------------------------- | ------------------------------------- |
| `answer` | The response from the HEAD request. | \`\` or `file` or `list of` or `text` |

**Examples**

Get the headers of a post with the following details

```generic
head "https://jsonplaceholder.typicode.com/posts/1"
```

Get the headers of a post with Authentication header

```generic
create a json
use the above as the headers input
set the headers input's "Authentication" to "Bearer <token>"
head "https://jsonplaceholder.typicode.com/posts/1"
... the headers is the headers input
```

### to patch payload on a url

Make a PATCH request to the specified url.

**Input Concepts**

| Concept   | Description                                                                                                                                                                                                                          | Type                                  | Required | Default Value |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------- | -------- | ------------- |
| `url`     | The URL to make the PATCH request to.                                                                                                                                                                                                | `text`                                | Yes      | (no default)  |
| `payload` | The payload to include in the request.                                                                                                                                                                                               | \`\` or `file` or `list of` or `text` | Yes      | (no default)  |
| `headers` | The headers to include in the request. For example {"Authorization": "Bearer "}. Note: If connect is set, "Authorization" header will be added automatically to the request and manually set "Authorization" header will be ignored. | `json`                                | No       | (no default)  |

**Output Concepts**

| Concept  | Description                          | Type                                  |
| -------- | ------------------------------------ | ------------------------------------- |
| `answer` | The response from the PATCH request. | \`\` or `file` or `list of` or `text` |

**Examples**

Update a post with the following details

```generic
create a json
use the above as the post json
set the post json's title to "My Post Title"
set the post json's body to "Awesome Body"
set the post json's userId to 1
patch the post json on "https://jsonplaceholder.typicode.com/posts/1"
```

Update a post with Authentication header

```generic
create a json
use the above as the post json
set the post json's title to "My Post Title edited"
set the post json's body to "Awesome Body"
set the post json's userId to 1
create a json
use the above as the headers input
set the headers input's "Authentication" to "Bearer <token>"
patch the post json to "https://jsonplaceholder.typicode.com/posts"
... the headers is the headers input
```

### to post payload to a url

Make a POST request to the specified url.

**Input Concepts**

| Concept   | Description                                                                                                                                                                                                                          | Type                                  | Required | Default Value |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------- | -------- | ------------- |
| `url`     | The URL to make the POST request to.                                                                                                                                                                                                 | `text`                                | Yes      | (no default)  |
| `payload` | The payload to include in the request.                                                                                                                                                                                               | \`\` or `file` or `list of` or `text` | Yes      | (no default)  |
| `headers` | The headers to include in the request. For example {"Authorization": "Bearer "}. Note: If connect is set, "Authorization" header will be added automatically to the request and manually set "Authorization" header will be ignored. | `json`                                | No       | (no default)  |

**Output Concepts**

| Concept  | Description                         | Type                                  |
| -------- | ----------------------------------- | ------------------------------------- |
| `answer` | The response from the POST request. | \`\` or `file` or `list of` or `text` |

**Examples**

Create a new post with the following details

```generic
create a json
use the above as the post json
set the post json's title to "My Post Title"
set the post json's body to "Awesome Body"
set the post json's userId to 1
post the post json to "https://jsonplaceholder.typicode.com/posts"
```

Create a new post with Authentication header

```generic
create a json
use the above as the post json
set the post json's title to "My Post Title"
set the post json's body to "Awesome Body"
set the post json's userId to 1
create a json
use the above as the headers input
set the headers input's "Authentication" to "Bearer <token>"
post the post json to "https://jsonplaceholder.typicode.com/posts"
... the headers is the headers input
```

### to put payload on a url

Make a PUT request to the specified url.

**Input Concepts**

| Concept   | Description                                                                                                                                                                                                                          | Type                                  | Required | Default Value |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------- | -------- | ------------- |
| `url`     | The URL to make the PUT request to.                                                                                                                                                                                                  | `text`                                | Yes      | (no default)  |
| `payload` | The payload to include in the request.                                                                                                                                                                                               | \`\` or `file` or `list of` or `text` | Yes      | (no default)  |
| `headers` | The headers to include in the request. For example {"Authorization": "Bearer "}. Note: If connect is set, "Authorization" header will be added automatically to the request and manually set "Authorization" header will be ignored. | `json`                                | No       | (no default)  |

**Output Concepts**

| Concept  | Description                        | Type                                  |
| -------- | ---------------------------------- | ------------------------------------- |
| `answer` | The response from the PUT request. | \`\` or `file` or `list of` or `text` |

**Examples**

Update a post with the following details

```generic
create a json
use the above as the post json
set the post json's title to "My Post Title edited"
set the post json's body to "Awesome Body"
set the post json's userId to 1
put the post json on "https://jsonplaceholder.typicode.com/posts/1"
```

Update a post with Authentication header

```generic
create a json
use the above as the post json
set the post json's title to "My Post Title edited"
set the post json's body to "Awesome Body"
set the post json's userId to 1
create a json
use the above as the headers input
set the headers input's "Authentication" to "Bearer <token>"
put the post json on "https://jsonplaceholder.typicode.com/posts"
... the headers is the headers input
```

### to retrieve a url

![FILTER - CAPABLE](https://img.shields.io/static/v1?label=FILTER\&message=CAPABLE\&color=blue)

Make a GET request to the specified url.

**Input Concepts**

| Concept   | Description                                                                                                                                                                                                                          | Type   | Required | Default Value |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | -------- | ------------- |
| `url`     | The URL to make the GET request to.                                                                                                                                                                                                  | `text` | Yes      | (no default)  |
| `headers` | The headers to include in the request. For example {"Authorization": "Bearer "}. Note: If connect is set, "Authorization" header will be added automatically to the request and manually set "Authorization" header will be ignored. | `json` | No       | (no default)  |

**Output Concepts**

| Concept  | Description                        | Type                                  |
| -------- | ---------------------------------- | ------------------------------------- |
| `answer` | The response from the GET request. | \`\` or `file` or `list of` or `text` |

**Examples**

Retrieve all posts

```generic
retrieve "https://jsonplaceholder.typicode.com/posts"
```

Retrieve a post with id 1

```generic
retrieve "https://jsonplaceholder.typicode.com/posts/1"
```

Retrieve all posts by a user with id 1

```generic
retrieve "https://jsonplaceholder.typicode.com/posts" whose "userId" is 1
```

Retrieve all posts with Authenticated header

```generic
create a json
use the above as the headers input
set the headers input's "Authentication" to "Bearer <token>"
retrieve "https://jsonplaceholder.typicode.com/posts"
... the headers is the headers input
```