---
title: "HTTP Request Step"
icon: "plug"
---

# 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>
