# Request

Use Request to fetch data from an HTTP API or send data to an external service.

## Overview

**Type:** `request`

URLs, headers, and request data accept [Morpher templates](/docs/morpher). Set the step's `output` name to make its response available to later steps. HTTP and network errors fail the step.

## Configuration

Put these fields in the step's `config` object. The examples below are configuration fragments; see [Execute workflows](/docs/execute-workflows) for a complete request. Supply referenced variables, credentials, and calculated values such as `currentTime` in context.

### URL

* **Type:** String
* **Required:** Yes
* **Templatable:** Yes
* **Description:** The target endpoint URL

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

### Method

* **Type:** Enum
* **Required:** Yes
* **Default:** `GET`
* **Options:** `GET`, `POST`, `PUT`, `DELETE`, `PATCH`
* **Description:** HTTP method to use for the request

### Headers

* **Type:** Object (Key-Value pairs)
* **Required:** No
* **Templatable:** Yes
* **Description:** Custom HTTP headers to include in the request

```json
{
  "Authorization": "Bearer {{ token }}",
  "Content-Type": "application/json",
  "X-Custom-Header": "{{ customValue }}"
}
```

### Data

* **Type:** Object
* **Required:** No
* **Templatable:** Yes
* **Description:** Request body payload (for POST, PUT, PATCH methods)

```json
{
  "name": "{{ user.name }}",
  "email": "{{ user.email }}",
  "role": "{{ user.role }}"
}
```

### Timeout

* **Type:** Number
* **Required:** No
* **Default:** `30000` (30 seconds)
* **Min:** `1000` (1 second)
* **Max:** `300000` (5 minutes)
* **Description:** HTTP client timeout in milliseconds. The workflow request timeout (`options.timeout`) defaults to and is capped at 30 seconds. The step timeout also defaults to 30 seconds; this field does not extend either timeout.

## Output

The Request step returns an object containing the API response:

```typescript
{
  status: number,      // HTTP status code (e.g., 200, 404, 500)
  data: any,          // Response body
  headers: object     // Response headers
}
```

### Accessing the output

```
{{ request_step.data.userId }}
{{ request_step.status }}
{{ request_step.data }}
```

## Examples

### GET request with authentication

```json
{
  "url": "{{ apiUrl }}/users/{{ userId }}",
  "method": "GET",
  "headers": {
    "Authorization": "Bearer {{ token }}"
  }
}
```

### POST request with data

```json
{
  "url": "https://api.example.com/users",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{ apiToken }}"
  },
  "data": {
    "name": "{{ user.name }}",
    "email": "{{ user.email }}",
    "role": "admin"
  }
}
```

### PUT request with dynamic URL

```json
{
  "url": "{{ baseUrl }}/resources/{{ resourceId }}",
  "method": "PUT",
  "headers": {
    "Authorization": "Bearer {{ token }}"
  },
  "data": {
    "status": "active",
    "updatedAt": "{{ currentTime }}"
  },
  "timeout": 60000
}
```

### DELETE request

```json
{
  "url": "https://api.example.com/items/{{ itemId }}",
  "method": "DELETE",
  "headers": {
    "Authorization": "Bearer {{ token }}"
  }
}
```

## Error handling

Request failures stop their sequence. Use Batch with `failFast: false` when later steps need to inspect the failure as data. The captured result has an `error` string instead of the normal `status`, `data`, and `headers` fields.

### HTTP errors

When the API returns an error response (4xx, 5xx status codes), the step throws a `FluxError` with:

```typescript
{
  code: "FLUX_REQUEST_ERROR",
  message: "HTTP request failed: [error details]",
  details: {
    status: number,        // HTTP status code
    statusText: string,    // Status message
    data: any             // Error response body
  }
}
```

### Network errors

Axios network errors, including timeouts and DNS failures, also use `HTTP request failed: [error message]`, with no HTTP response status. Other request errors use:

```typescript
{
  code: "FLUX_REQUEST_ERROR",
  message: "Request failed: [error message]"
}
```

## Best practices

### Security

* Supply API keys at execution time rather than hard-coding them in reusable configuration.
* Reference credentials with a template, for example `"Authorization": "Bearer {{ apiKey }}"`. Context is workflow data, not a separate secret store.
* Never expose credentials in logs or error messages

### Reliability

* Set appropriate timeout values based on the expected response time of the API
* Use step-level retry settings for transient failures. Retry non-idempotent operations only when the external API supports safe retries.
* HTTP and network failures stop the workflow. To collect errors as data, use a Batch step with `failFast: false`, then inspect its results.

### Performance

* Use shorter timeouts for non-critical requests to avoid blocking your workflow
* Consider batch operations when making multiple requests to the same API
* Cache responses when appropriate to reduce API calls

## Common use cases

* **User authentication:** Verify credentials against an external auth service
* **Data enrichment:** Fetch additional user or business data from third-party APIs
* **Webhook triggers:** Send notifications to external systems
* **CRM integration:** Sync customer data with Salesforce, HubSpot, or similar platforms
* **Payment processing:** Initiate transactions via Stripe, PayPal, or other payment gateways
* **Analytics tracking:** Send events to analytics platforms
