> ## Documentation Index
> Fetch the complete documentation index at: https://explore.airia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Https step

# HTTP Request Step

Use the **HTTP Request** step to make an HTTP/HTTPS call to an external service (REST API, webhook, internal endpoint via ACC) and then use the **status code, headers, and parsed body** in later steps.

## When to use this step

* Call a 3rd-party API (CRM, ticketing, payments, internal microservice)
* Trigger a webhook (send events, notifications)
* Fetch data needed for routing, decisions, or enrichment
* Post structured data to an external system after an extraction step

***

## Before you start

Make sure you have:

* The API **URL** and required **method** (GET/POST/etc.)
* Authentication details (token, basic auth, API key) saved as an **Airia Credential** if possible
* If the endpoint is behind a firewall: access via **Airia Cloud Connector (ACC)** and the correct **ACC Group**

<Tip>
  Prefer **Credentials** over hardcoding secrets in headers/body. It’s safer and easier to rotate.
</Tip>

***

## Add the step

1. In **Agent Studio**, open your workflow
2. Click **Add step**
3. Select **HTTP Request**
4. Give it a clear name (example: `FetchCustomer`, `CreateTicket`, `SendWebhook`)

***

## Configure the request

The step UI is typically split into tabs: **Settings**, **Headers**, **Query Params**, **Body**.

### Settings tab

#### Method

Choose the HTTP method:

* **GET** (fetch)
* **POST** (create/submit)
* **PUT/PATCH** (update)
* **DELETE** (remove)

#### URL

Enter the full endpoint URL.

You can include variables:

* `https://api.example.com/users/{{userId}}`

<Info>
  Variables are substituted at runtime. If a variable is missing, you may see the raw `{{variable}}` reach the server (or the request fails).
</Info>

#### Credentials (Authentication)

If the API requires auth, select a **Credential**. Supported patterns:

* **Basic Auth** (username/password)
* **Header Auth** (e.g., `Authorization: Bearer <token>` or `X-API-Key: <key>`)
* **Query Param Auth** (token passed as a query parameter)

<Tip>
  If you pick a Credential, avoid also manually setting the same auth header in **Headers** (it can conflict or overwrite).
</Tip>

#### Timeout

Set how long Airia should wait before failing the request.

* Use short timeouts for health checks (e.g., 3–10s)
* Use longer timeouts for heavy endpoints (e.g., 60–300s)

<Note>
  Max timeout is 10 minutes (600s).
</Note>

#### Ignore SSL Errors

Turn on **Ignore SSL Errors** only for development/testing or self-signed cert environments.

<Warning>
  Do not enable this in production unless you understand the security tradeoff.
</Warning>

#### Route through ACC (Cloud Connector)

Enable **Route Through ACC** to reach internal endpoints (behind corporate firewalls/VPC).

If you have multiple connector groups, choose the correct **ACC Group**.

***

### Headers tab

Add request headers as key/value pairs.

Common examples:

* `Accept: application/json`
* `Content-Type: application/json` (often set automatically when Body type is JSON)
* `Authorization: Bearer {{token}}` (only if you’re not using Credentials)

You can use variables in **values**:

* `X-Customer-Id: {{customerId}}`

<Tip>
  Only header **values** support variable substitution. Keep header names static.
</Tip>

***

### Query Params tab

Add URL query parameters as key/value pairs.

Example:

* `limit: 50`
* `offset: {{pageOffset}}`
* `status: active`

This produces:

* `?limit=50&offset=0&status=active`

***

### Body tab

Use **Body** when sending data (typically POST/PUT/PATCH).

#### Choose a body type

* **JSON**: best for modern APIs
* **Form**: `application/x-www-form-urlencoded` style endpoints
* **None**: no body (common for GET)

#### JSON body (recommended)

Write JSON and inject variables where needed:

* `{ "email": "{{userEmail}}", "role": "admin" }`

#### Form body

Add **Form Data** fields (key/value pairs). Airia encodes them for you.

<Info>
  If your API expects `multipart/form-data` (file uploads), confirm current step support in your environment—this step focuses on JSON and URL-encoded form patterns.
</Info>

***

## Using variables effectively

You can reference values produced earlier in the workflow (or global variables), then inject them into:

* URL path segments
* Header values
* Query param values
* Body content

Best practices:

* Validate that the variable exists before calling (via a condition/router step)
* Keep URLs readable: prefer `{{userId}}` over complex expressions in the URL
* If building complex payloads, build the payload in a prior step (formatter) and reference it here

***

## What the step outputs

After the request runs, downstream steps can read:

* **Success** (true/false)
* **StatusCode** (200, 404, 500…)
* **Headers**
* **Body** (auto-parsed when possible)
* **ContentType**
* **ErrorMessage** (when failed)

Use it like:

* `Steps.<YourStepName>.Output.Success`
* `Steps.<YourStepName>.Output.StatusCode`
* `Steps.<YourStepName>.Output.Body`

<Note>
  If the response is JSON, Body is parsed so you can access fields directly (e.g., `Body.id`, `Body.data.items[0]`).
</Note>

***

## Common recipes

### 1) Simple GET to fetch data

**Use when:** you need customer/profile/status data.

* Method: **GET**
* URL: `https://api.example.com/users/{{userId}}`
* Headers: `Accept: application/json`

Then branch downstream:

* If `Success` is true and `StatusCode` is 200 → continue
* Else → fallback path (retry, notify, or return a friendly error)

***

### 2) POST JSON to create/update a record

**Use when:** you want to create tickets, leads, messages, etc.

* Method: **POST**
* Content type: **JSON**
* Body: `{ "name": "{{name}}", "email": "{{email}}" }`
* Auth: Credential (preferred)

***

### 3) Call an internal API via ACC

**Use when:** the API is only reachable inside a corporate network.

* Enable **Route Through ACC**
* Select **ACC Group**
* Keep timeout slightly higher if the route adds latency

***

## Troubleshooting

### Request fails with 401/403

* Confirm the **Credential** is the right type for the API
* Ensure the token isn’t expired
* If using both Credential + manual auth header, remove one

### Timeout errors

* Increase timeout (especially for slow endpoints)
* Test the endpoint latency outside the workflow
* If internal endpoint: try **ACC routing** and verify the connector group

### SSL / certificate errors

* Confirm the endpoint has a valid cert chain
* For dev/self-signed only: enable **Ignore SSL Errors**

### Body is empty (null)

* Some APIs return no body on success (e.g., 204)
* Check `StatusCode` and `ContentType`
* Confirm you’re reading the right part of the response (some APIs return data in headers)

***

## Security & reliability tips

<Warning>
  Never paste secrets directly into Headers/Body for production workflows. Use Credentials.
</Warning>

<Tip>
  Always branch on `Success` + `StatusCode` before using `Body` in later steps to avoid null/shape errors.
</Tip>