# http

Makes HTTP requests to external APIs and endpoints. The response is stored in a variable for further processing.

```liquid
{% http url: "https://api.example.com/data", method: "GET" as response %}

{% if response.ok %}
  {% log "Request successful: " | append: response.status %}
{% endif %}
```

#### Syntax

```liquid
{% http url: endpoint, method: http_method, headers: headers_object, body: body_object as result_variable %}
```

#### Parameters

| Parameter | Required | Description                                                                              |
| --------- | -------- | ---------------------------------------------------------------------------------------- |
| `url`     | Yes      | The endpoint URL to call                                                                 |
| `method`  | Yes      | HTTP method: `"GET"`, `"POST"`, `"PUT"`, `"PATCH"`, `"DELETE"`                           |
| `headers` | No       | Object containing request headers                                                        |
| `body`    | No       | Request payload (automatically JSON-stringified unless Content-Type specifies otherwise) |
| `raw`     | No       | Set to `true` to return raw text instead of parsed JSON                                  |

#### Result Object

| Property     | Type          | Description                                       |
| ------------ | ------------- | ------------------------------------------------- |
| `url`        | string        | The final URL (after redirects)                   |
| `status`     | number        | HTTP status code (200, 404, 500, etc.)            |
| `statusText` | string        | HTTP status message ("OK", "Not Found", etc.)     |
| `headers`    | object        | Response headers as key-value pairs               |
| `ok`         | boolean       | `true` if status is 200-299                       |
| `body`       | object/string | Parsed JSON response (or raw text if `raw: true`) |

Example result:

```json
{
  "url": "https://api.example.com/data",
  "status": 200,
  "statusText": "OK",
  "headers": {
    "content-type": "application/json"
  },
  "ok": true,
  "body": {
    "success": true,
    "data": []
  }
}
```

#### Examples

**Simple GET request:**

```liquid
{% http url: "https://api.example.com/products", method: "GET" as response %}

{% if response.ok %}
  {% for product in response.body.products %}
    {% log "Product: " | append: product.name %}
  {% endfor %}
{% else %}
  {% log "Request failed: " | append: response.status %}
{% endif %}
```

**POST request with JSON body:**

```liquid
{% json request_body %}
  {
    "name": "{{ product.title }}",
    "sku": "{{ product.sku }}",
    "price": {{ product.price }}
  }
{% endjson %}

{% json headers %}
  {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{ api_token }}"
  }
{% endjson %}

{% http url: "https://api.example.com/products", method: "POST", headers: headers, body: request_body as response %}

{% if response.status == 201 %}
  {% log "Product created with ID: " | append: response.body.id %}
{% else %}
  {% log "Error: " | append: response.body.message %}
{% endif %}
```

**PUT request to update resource:**

```liquid
{% assign endpoint = "https://api.example.com/orders/" | append: order.id %}

{% json headers %}
  {
    "Content-Type": "application/json",
    "X-API-Key": "{{ API_KEY }}"
  }
{% endjson %}

{% json body %}
  {
    "status": "shipped",
    "tracking_number": "{{ tracking_number }}"
  }
{% endjson %}

{% http url: endpoint, method: "PUT", headers: headers, body: body as response %}

{% if response.ok %}
  {% log "Order updated successfully" %}
{% endif %}
```

**Form-urlencoded POST request:**

```liquid
{% json headers %}
  {
    "Content-Type": "application/x-www-form-urlencoded"
  }
{% endjson %}

{% assign form_body = "grant_type=client_credentials&client_id=" | append: CLIENT_ID | append: "&client_secret=" | append: CLIENT_SECRET %}

{% http url: "https://auth.example.com/oauth/token", method: "POST", headers: headers, body: form_body as response %}

{% if response.ok %}
  {% assign access_token = response.body.access_token %}
  {% log "Token obtained successfully" %}
{% endif %}
```

**Send data to webhook:**

```liquid
{% json payload %}
  {
    "event": "order_created",
    "order_id": {{ order.id }},
    "customer_email": "{{ order.email }}",
    "total": {{ order.total_price }},
    "timestamp": "{{ 'now' | date: '%Y-%m-%dT%H:%M:%SZ' }}"
  }
{% endjson %}

{% json headers %}
  {
    "Content-Type": "application/json"
  }
{% endjson %}

{% http url: WEBHOOK_URL, method: "POST", headers: headers, body: payload as response %}

{% log "Webhook response: " | append: response.status %}
```

**GET raw text response (e.g., CSV):**

```liquid
{% http url: "https://api.example.com/export.csv", method: "GET", raw: true as response %}

{% if response.ok %}
  {% assign csv_content = response.body %}
  {% assign rows = csv_content | parse_csv %}

  {% for row in rows %}
    {% log row %}
  {% endfor %}
{% endif %}
```

**Send XML data:**

```liquid
{% capture xml_body %}<?xml version="1.0" encoding="UTF-8"?>
<order>
  <id>{{ order.id }}</id>
  <total>{{ order.total_price }}</total>
</order>
{% endcapture %}

{% json headers %}
  {
    "Content-Type": "text/xml"
  }
{% endjson %}

{% http url: "https://api.example.com/orders", method: "POST", headers: headers, body: xml_body as response %}

{% log "XML request status: " | append: response.status %}
```

**Integrate with external CRM:**

```liquid
{% json headers %}
  {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{ CRM_API_KEY }}"
  }
{% endjson %}

{% json contact_data %}
  {
    "email": "{{ customer.email }}",
    "firstName": "{{ customer.first_name }}",
    "lastName": "{{ customer.last_name }}",
    "properties": {
      "total_orders": {{ customer.orders_count }},
      "total_spent": {{ customer.total_spent }}
    }
  }
{% endjson %}

{% http url: "https://api.crm.com/contacts", method: "POST", headers: headers, body: contact_data as response %}

{% if response.ok %}
  {% log "Contact synced to CRM" %}
{% else %}
  {% log "CRM sync failed: " | append: response.body.error %}
{% endif %}
```

#### Notes

* Consumes 1 credit per request
* Request body is automatically JSON-stringified unless Content-Type is:
  * `application/x-www-form-urlencoded`
  * `multipart/form-data`
  * `text/plain`
  * `text/xml`
* Rate limited responses (429) are automatically retried with backoff
* Server errors are retried up to 3 times before failing
* Request timeout is 5 minutes
* Use `raw: true` when expecting non-JSON responses (CSV, XML, plain text)


---

# 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.datajet-app.com/liquid/tags/http.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.