# REST V2

## **Overview**

REST V2 makes calls to HTTP endpoints, supporting actions such as `GET`, `POST`, `PUT`, and `DELETE`. t uses Double Braces expressions to compose the URL, headers, query parameters, and message body, allowing direct access to pipeline data.

You can configure the connector manually or import its settings from a cURL command or an OpenAPI specification, reducing setup time and the risk of configuration errors.

## **Importing from cURL or OpenAPI**

When integrating an external API, you can import its contract directly into the REST V2 connector instead of configuring each field manually. The connector supports two import formats:

* **cURL**: A command-line tool for making HTTP requests. If you already have a cURL command for the API you want to call, you can paste it directly into the connector.
* **OpenAPI**: A standard specification format (JSON or YAML) that describes an API's endpoints, methods, parameters, and request structure. Most APIs publish an OpenAPI spec in their developer documentation.

To import a configuration:

1. In the REST V2 connector configuration page, click **Import** in the upper right corner and select either **cURL** or **OpenAPI**.
2. Provide the input:
   * For **cURL**: Paste your cURL command. The connector supports `-X`, `-H`, `-d`, `-u`, and `-b` flags.
   * For **OpenAPI**: Drop your OpenAPI contract in JSON or YAML format.
3. Click **Apply**.

<figure><img src="/files/EFDnRB4SP0Pm1ML9xgub" alt=""><figcaption></figcaption></figure>

Digibee parses the input and automatically populates the following fields:

* **URL**: The base URL and path.
* **Verb**: The HTTP method (`GET`, `POST`, `PUT`, `DELETE`, `PATCH`, and `HEAD`).
* **Headers**: All headers defined in the contract.
* **Query Params**: Query parameters defined in the spec.
* **Body**: The request body structure.

{% hint style="warning" %}
Importing will overwrite all current fields in the connector.
{% endhint %}

After importing, review the populated fields and configure any dynamic values your pipeline requires using [Double Braces expressions](/documentation/connectors-and-triggers/double-braces/overview.md).

## **Parameters**

The table below lists all configuration parameters for the connector. Parameters that support [Double Braces expressions](/documentation/connectors-and-triggers/double-braces/overview.md) are marked with ✅ in the **Supports DB** column.

The **Visible when** column indicates parameters that only appear in the interface after a condition is met; parameters that are always visible are indicated with —.

{% hint style="info" %}
This connector supports [**Alias**](/documentation/connectors-and-triggers/double-braces/how-to-reference-data-using-double-braces/previous-steps-access.md), a parameter that saves the connector's output so it can be referenced later in the pipeline through Double Braces expressions.
{% endhint %}

### **Connection**

<table data-header-hidden="false" data-header-sticky data-first-column-sticky data-full-width="true"><thead><tr><th>Parameter</th><th>Description</th><th>Data type</th><th>Supports DB</th><th>Default</th><th>Visible when</th></tr></thead><tbody><tr><td><strong>URL</strong></td><td>Address that will receive the HTTP call. Supports Double Braces, but account references are not allowed.</td><td>String</td><td>✅</td><td><code>https://viacep.com.br/ws/{{ DEFAULT(message.$.cep, "04547-130") }}/json/</code></td><td>—</td></tr><tr><td><strong>Headers</strong></td><td>All headers required for the call (for example, <code>Content-Type: application/json</code>). Supports Double Braces for both key and value fields. Account references are only allowed in value fields.</td><td>Key-value pairs</td><td>✅</td><td><code>Content-Type: application/json</code></td><td>—</td></tr><tr><td><strong>Query Params</strong></td><td>Query parameters required for the call. Supports Double Braces only for value fields.</td><td>Key-value pairs</td><td>✅ (values only)</td><td>N/A</td><td>—</td></tr><tr><td><strong>Verb</strong></td><td>The HTTP method (<code>GET</code>, <code>POST</code>, <code>PUT</code>, <code>DELETE</code>, <code>PATCH</code>, and <code>HEAD</code>).</td><td>String</td><td>❌</td><td><code>GET</code></td><td>—</td></tr><tr><td><strong>Send A File</strong></td><td>If enabled, sends a file in place of the body.</td><td>Boolean</td><td>❌</td><td><code>false</code></td><td><strong>Verb</strong> is <code>POST</code>, <code>PUT</code>, <code>DELETE</code>, or <code>PATCH</code></td></tr><tr><td><strong>File Name</strong></td><td>File name or full file path (for example, <code>tmp/processed/file.txt</code>).</td><td>String</td><td>✅</td><td>N/A</td><td><strong>Send A File</strong> is enabled</td></tr><tr><td><strong>Body</strong></td><td>The body of the request. Click <strong>Write with AI</strong> to get AI support.</td><td>JSON</td><td>✅</td><td>N/A</td><td><strong>Verb</strong> is <code>POST</code>, <code>PUT</code>, <code>DELETE</code>, or <code>PATCH</code></td></tr></tbody></table>

### **Authentication**

<table data-header-hidden="false" data-header-sticky data-first-column-sticky data-full-width="true"><thead><tr><th>Parameter</th><th>Description</th><th>Data type</th><th>Supports DB</th><th>Default</th><th>Visible when</th></tr></thead><tbody><tr><td><strong>Use Dynamic Account</strong></td><td>If enabled, uses the account dynamically; otherwise, uses it statically.</td><td>Boolean</td><td>❌</td><td><code>false</code></td><td>—</td></tr><tr><td><strong>Scoped</strong></td><td>If enabled, isolates the stored account from other sub-processes. Not supported for accounts used in headers or body. To learn more, read the <a href="/spaces/jvO5S91EQURCEhbZOuuZ/pages/cbkYqH3fxzeL7zOKNawz">Dynamic Accounts documentation</a>.</td><td>Boolean</td><td>❌</td><td><code>false</code></td><td><strong>Use Dynamic Account</strong> is enabled</td></tr><tr><td><strong>Account Name</strong></td><td>Account name generated dynamically through the <a href="/pages/0kxlZ011XP4A2T43v9kh"><strong>Store Account</strong></a> connector.</td><td>String</td><td>❌</td><td>N/A</td><td><strong>Use Dynamic Account</strong> is enabled</td></tr><tr><td><strong>Account</strong></td><td>Account used by the connector. Learn more in the <a href="#using-accounts"><strong>Using accounts</strong></a> section.</td><td>String</td><td>❌</td><td>N/A</td><td><strong>Use Dynamic Account</strong> is disabled</td></tr><tr><td><strong>Custom Account #1</strong></td><td>Account whose credentials can be referenced in any Double Braces-supported field through <code>{{ account.custom-1.&#x3C;field> }}</code>. Learn more in the <a href="#using-custom-accounts"><strong>Using custom accounts</strong></a> section.</td><td>String</td><td>❌</td><td>N/A</td><td>—</td></tr><tr><td><strong>Custom Account #2</strong></td><td>Account whose credentials can be referenced in any Double Braces-supported field through <code>{{ account.custom-1.&#x3C;field> }}</code>. Learn more in the <a href="#using-custom-accounts"><strong>Using custom accounts</strong></a> section.</td><td>String</td><td>❌</td><td>N/A</td><td>—</td></tr></tbody></table>

### **Timeouts**

Learn more in the [**Configuring the timeouts**](#configuring-the-timeouts) section.

<table data-header-hidden="false" data-header-sticky data-first-column-sticky data-full-width="true"><thead><tr><th>Parameter</th><th>Description</th><th>Data type</th><th>Supports DB</th><th>Default</th></tr></thead><tbody><tr><td><strong>Connect Timeout</strong></td><td>Maximum time to establish a connection with the server, in milliseconds (includes DNS, TCP handshake, and TLS when applicable).</td><td>Integer</td><td>❌</td><td><code>30000</code></td></tr><tr><td><strong>Read Timeout</strong></td><td>Maximum time to wait for a response after the connection is established, in milliseconds.</td><td>Integer</td><td>❌</td><td><code>30000</code></td></tr><tr><td><strong>Write Timeout</strong></td><td>Maximum time to send the request body to the server, in milliseconds.</td><td>Integer</td><td>❌</td><td><code>30000</code></td></tr><tr><td><strong>Call Timeout</strong></td><td>Total time allowed for the entire request (connect, write, read), in milliseconds.</td><td>Integer</td><td>❌</td><td><code>30000</code></td></tr></tbody></table>

### **Error handling**

<table data-header-hidden="false" data-header-sticky data-first-column-sticky data-full-width="true"><thead><tr><th>Parameter</th><th>Description</th><th>Data type</th><th>Supports DB</th><th>Default</th></tr></thead><tbody><tr><td><strong>Stop On Client Error</strong></td><td>If enabled, interrupts pipeline execution on a 4xx HTTP error.</td><td>Boolean</td><td>❌</td><td><code>false</code></td></tr><tr><td><strong>Stop On Server Error</strong></td><td>If enabled, interrupts pipeline execution on a 5xx HTTP error.</td><td>Boolean</td><td>❌</td><td><code>false</code></td></tr></tbody></table>

### **Response**

<table data-header-hidden="false" data-header-sticky data-first-column-sticky data-full-width="true"><thead><tr><th>Parameter</th><th>Description</th><th>Data type</th><th>Supports DB</th><th>Default</th><th>Visible when</th></tr></thead><tbody><tr><td><strong>Override Response Charset</strong></td><td>If enabled, replaces the charset returned by the endpoint with the value specified in <strong>Response Charset</strong>.</td><td>Boolean</td><td>❌</td><td><code>false</code></td><td>—</td></tr><tr><td><strong>Response Charset</strong></td><td>Charset to apply.</td><td>String</td><td>❌</td><td><code>UTF-8</code></td><td><strong>Override Response Charset</strong> is enabled</td></tr></tbody></table>

### **Advanced**

These parameters are only available when **Advanced Settings** is enabled.

<table data-header-hidden="false" data-header-sticky data-first-column-sticky data-full-width="true"><thead><tr><th>Parameter</th><th>Description</th><th>Data type</th><th>Supports DB</th><th>Default</th><th>Visible when</th></tr></thead><tbody><tr><td><strong>Raw Mode</strong></td><td>If enabled, receives or sends a non-JSON payload.</td><td>Boolean</td><td>❌</td><td><code>false</code></td><td>—</td></tr><tr><td><strong>Raw Mode As Base64</strong></td><td>If enabled, returns the response encoded in Base64.</td><td>Boolean</td><td>❌</td><td><code>false</code></td><td><strong>Raw Mode</strong> is enabled</td></tr><tr><td><strong>Save As Local File</strong></td><td>If enabled, saves the response as a file in the local pipeline directory.</td><td>Boolean</td><td>❌</td><td><code>false</code></td><td>—</td></tr><tr><td><strong>Response File Name</strong></td><td>File name or full file path (for example, <code>tmp/processed/file.txt</code>). Supports Double Braces, but account references are not allowed.</td><td>String</td><td>✅</td><td>N/A</td><td><strong>Save As Local File</strong> is enabled</td></tr><tr><td><strong>Allow Insecure Endpoints</strong></td><td>If enabled, allows calls to HTTPS endpoints with invalid certificates.</td><td>Boolean</td><td>❌</td><td><code>false</code></td><td>—</td></tr><tr><td><strong>Enable Retries</strong></td><td>If enabled, retries the request after server errors.</td><td>Boolean</td><td>❌</td><td><code>false</code></td><td>—</td></tr><tr><td><strong>Number Of Retries</strong></td><td>Maximum number of retry attempts before giving up.</td><td>Integer</td><td>❌</td><td><code>0</code></td><td><strong>Enable Retries</strong> is enabled</td></tr><tr><td><strong>Time To Wait Between Retries</strong></td><td>Wait time between retry attempts, in milliseconds.</td><td>Integer</td><td>❌</td><td><code>0</code></td><td><strong>Enable Retries</strong> is enabled</td></tr><tr><td><strong>Compress Body With GZIP</strong></td><td>If enabled, compresses the request body using GZIP.</td><td>Boolean</td><td>❌</td><td><code>false</code></td><td>—</td></tr><tr><td><strong>Force HTTP 1.1</strong></td><td>If enabled, forces the request to use HTTP 1.1.</td><td>Boolean</td><td>❌</td><td><code>false</code></td><td>—</td></tr><tr><td><strong>Disable Connection Pooling</strong></td><td>If enabled, does not reuse connections. Recommended for endpoints with connection reuse issues.</td><td>Boolean</td><td>❌</td><td><code>false</code></td><td>—</td></tr><tr><td><strong>Invalidate SSL Sessions On Every Call</strong></td><td>If enabled, invalidates SSL sessions on every request. Recommended for endpoints with SSL session reuse issues. Activating this option makes the connector single-threaded.</td><td>Boolean</td><td>❌</td><td><code>false</code></td><td>—</td></tr><tr><td><strong>Enable Follow Redirect</strong></td><td>If enabled, automatically follows redirects for 302 responses. If disabled, returns the original 302 response for inspection before the redirect.</td><td>Boolean</td><td>❌</td><td><code>true</code></td><td>—</td></tr></tbody></table>

### **Documentation**

<table data-header-hidden="false" data-header-sticky data-full-width="true"><thead><tr><th>Parameter</th><th>Description</th><th>Data type</th><th>Supports DB</th><th>Default</th></tr></thead><tbody><tr><td><strong>Documentation</strong></td><td>Space for documenting connector configuration details and business rules.</td><td>String</td><td>❌</td><td>N/A</td></tr></tbody></table>

## **Messages flow**

### **Input**

The message body supports both static values and Double Braces expressions. This does not apply to `GET` requests.

{% code fullWidth="false" %}

```json
{
    "id": {{ DEFAULT(message.customer.id, UUID()) }},
    "name": {{ message.customer.name }},
    "type": "1"
}
```

{% endcode %}

### **Output**

{% tabs %}
{% tab title="Success" %}
Default response when the call succeeds.

{% code overflow="wrap" %}

```json
{
    status: 2xx,
    statusMessage: "STATUS_MESSAGE",
    body: {},
    headers: {}
}
```

{% endcode %}
{% endtab %}

{% tab title="Success — Raw Mode as Base64" %}
Returned when **Raw Mode As Base64** is active. The response body is encoded in Base64.

{% code overflow="wrap" %}

```json
{
    status: 2xx,
    statusMessage: "STATUS_MESSAGE",
    body: "content in base64 format",
    headers: {}
}
```

{% endcode %}
{% endtab %}

{% tab title="Success — Save As Local File" %}
Returned when **Save As Local File** is enabled. The response body contains the name of the saved file.

{% code overflow="wrap" %}

```json
{
    status: 2xx,
    statusMessage: "STATUS_MESSAGE",
    body: {
        file: "name of the file defined in the Response File Name property"
    },
    headers: {}
}

```

{% endcode %}
{% endtab %}

{% tab title="Error" %}
Returned when the HTTP call fails.

{% code overflow="wrap" %}

```json
{
    error: "error message",
    code: XXX,
    body: {},
    headers: {}
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

## **REST V2 in action**

### **Configuring the timeouts**

#### **Connect timeout**

Defines the maximum time allowed to establish a connection with the server. If the server is unavailable or slow to accept the connection, the request fails after this timeout.

**Example:** The server takes longer than 10 seconds to complete the handshake. The connection fails due to a timeout.

#### **Read timeout**

Specifies the maximum time to wait for a response after the request has been sent. Prevents the pipeline client from waiting indefinitely for data.

**Example:** The server accepted the connection but takes more than 15 seconds to start responding. A timeout error is returned.

#### **Write timeout**

Sets the maximum time allowed to send the request body to the server. Particularly relevant for requests with large payloads, such as file uploads.

**Example:** Uploading a file takes more than 30 seconds. The request fails due to a write timeout.

#### **Call timeout**

Defines the total timeout for the entire HTTP call, including connection, writing, and reading phases. If the combined duration exceeds this value, the request is aborted.

**Example:** You configure a 60-second timeout for the entire operation. If connecting, sending, and receiving together exceed this limit, the request is canceled.

### **Sending a binary file**

To send a binary file through REST V2, provide:

* The destination endpoint in **URL**
* The content type (MIME type of the file) in the header, for example, `application/pdf`
* The path where the file can be found in the **File Name** field

### **Making requests with content-type: multipart/form-data**

Set the `Content-Type: multipart/form-data` header in the connector. When you select any HTTP verb other than `GET`, a body field appears for you to define the payload.

To specify **fields**:

{% code fullWidth="false" %}

```json
{
  "fields": {
    "field_name1": "field_value_1",
    "field_name2": "field_value_2"
  }
}
```

{% endcode %}

To specify **files**:

```json
{
  "files": {
    "file_field_name1": "path_to_file_1",
    "file_field_name2": "path_to_file_2"
  }
}
```

You can combine both structures and use Double Braces expressions for dynamic values.

### **Making requests with content-type: application/x-www-form-urlencoded**

Set the `Content-Type: application/x-www-form-urlencoded` header in the connector. When you select any HTTP verb other than `GET`, a body field appears for you to define the payload.

Example:

```json
{
  "field_name1": "field_value_1",
  "field_name2": "field_value_2"
}
```

### **Using accounts**

REST V2 supports three account parameters, each with a different behavior:

* **Account**: The connector automatically prepares the request with the account credentials according to the authentication technology.
* **Custom Account #1** and **Custom Account #2**: Can only be used to reference credential values in other fields through Double Braces, for example `{{ account.custom-1.value }}`.

{% hint style="info" %}
The **Account** parameter always takes precedence over custom accounts.
{% endhint %}

The table below describes how the connector prepares the authorization for each supported account type.

<table data-header-hidden="false" data-header-sticky><thead><tr><th width="226">Account type</th><th>How the connector handles authorization</th></tr></thead><tbody><tr><td><strong>API Key</strong></td><td>Appends <code>URL-PARAM-NAME</code> and <code>API-KEY</code> as query parameters: <code>https://www.address.com?&#x3C;URL-PARAM-NAME>=&#x3C;API-KEY></code></td></tr><tr><td><strong>AWS V4</strong></td><td>Generates AWS authentication headers and signs the message using the AWS Signature Version 4 algorithm. Check the AWS service documentation for any additional required headers or parameters.</td></tr><tr><td><strong>Basic</strong></td><td>Encodes <code>USERNAME</code> and <code>PASSWORD</code> in Base64 and adds an authorization header: <code>Authorization: Basic &#x3C;ENCODED-INFORMATION></code></td></tr><tr><td><strong>Certificate Chain</strong></td><td>Uses the provided chain to validate and establish a secure connection with the API server.</td></tr><tr><td><strong>Custom Auth Header</strong></td><td>Creates a custom header using <code>HEADER-NAME</code> and <code>HEADER-VALUE</code>: <code>&#x3C;HEADER-NAME>: &#x3C;HEADER-VALUE></code></td></tr><tr><td><strong>Google Key</strong></td><td>Generates a Google authentication token and adds an authorization header: <code>Authorization: Bearer &#x3C;GOOGLE-JWT-TOKEN></code>. Check the Google service documentation for any additional required headers or parameters.</td></tr><tr><td><strong>OAuth 2</strong></td><td>Behavior varies by provider. For Microsoft and Google: <code>Authorization: Bearer &#x3C;PROVIDER_ACCESS_TOKEN></code>. For Mercado Livre: <code>https://www.address.com?access_token=&#x3C;API-KEY></code></td></tr><tr><td><strong>OAuth Bearer Token</strong></td><td>Uses an existing OAuth token and adds an authorization header: <code>Authorization: Bearer &#x3C;TOKEN></code></td></tr><tr><td><strong>NTLM</strong></td><td>Handles NTLM authentication automatically using the credentials defined in the account.</td></tr></tbody></table>

To learn more about account types and configuration, read the [Accounts documentation](/documentation/developer-guide/development-cycle/build-overview/accounts.md).

### **Using custom accounts**

**Custom Account #1** and **Custom Account #2** allow you to reference account credentials directly in any field that supports Double Braces, **except the URL field.** This is useful when you need to use account values in a flexible way, without relying on the automatic authentication handled by the **Account** parameter.

{% hint style="info" %}
Credentials referenced through custom accounts are not exposed in the connector output. The behavior is the same as other account types: values are used internally to perform the call and don’t appear in the pipeline response.
{% endhint %}

To use a custom account:

1. In the **Authentication** section, select the desired account in **Custom Account #1** or **Custom Account #2**.
2. In any field that supports Double Braces, reference the account values using the expressions below.

{% hint style="warning" %}
The **OAuth 2** account type is not supported for custom account references.
{% endhint %}

The available fields depend on the account type selected:

<table data-header-hidden="false" data-header-sticky data-full-width="false"><thead><tr><th width="231">Account type</th><th>Available fields</th></tr></thead><tbody><tr><td><strong>API Key</strong></td><td><ul><li><code>{{ account.custom-1.url-param-name }}</code></li><li><code>{{ account.custom-1.value }}</code></li></ul></td></tr><tr><td><strong>Basic</strong></td><td><ul><li><code>{{ account.custom-1.username }}</code></li><li><code>{{ account.custom-1.password }}</code></li></ul></td></tr><tr><td><strong>Custom Auth Header</strong></td><td><ul><li><code>{{ account.custom-1.header-name }}</code></li><li><code>{{ account.custom-1.header-value }}</code></li></ul></td></tr><tr><td><strong>OAuth Bearer Token</strong></td><td><ul><li><code>{{ account.custom-1.token }}</code></li></ul></td></tr><tr><td><strong>Certificate Chain</strong></td><td><ul><li><code>{{ account.custom-1.chain }}</code></li><li><code>{{ account.custom-1.password }}</code></li></ul></td></tr><tr><td><strong>Google Key</strong></td><td><ul><li><code>{{ account.custom-1.key }}</code></li><li><code>{{ account.custom-1.scopes }}</code></li></ul></td></tr><tr><td><strong>AWS V4</strong></td><td><ul><li><code>{{ account.custom-1.service-name }}</code></li><li><code>{{ account.custom-1.access-key }}</code></li><li><code>{{ account.custom-1.secret-key }}</code></li><li><code>{{ account.custom-1.session-token }}</code></li><li><code>{{ account.custom-1.region }}</code></li></ul></td></tr><tr><td><strong>OAuth 2</strong></td><td><ul><li><code>{{ account.custom-1.provider }}</code></li><li><code>{{ account.custom-1.scopes }}</code></li></ul></td></tr><tr><td><strong>NTLM</strong></td><td><ul><li><code>{{ account.custom-1.username }}</code></li><li><code>{{ account.custom-1.password }}</code></li><li><code>{{ account.custom-1.domain }}</code></li><li><code>{{ account.custom-1.hostname }}</code></li></ul></td></tr></tbody></table>

{% hint style="info" %}
Replace `custom-1` with `custom-2` when referencing **Custom Account #2**.
{% endhint %}

**Example:** Using a Basic account to pass credentials in the request body:

```json
{
    "username": "{{ account.custom-1.username }}",
    "password": "{{ account.custom-1.password }}"
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.digibee.com/documentation/connectors-and-triggers/connectors/web-protocols/rest-v2.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.