# HTTP Request Tool

The **HTTP Request Tool** allows your Agent to interact with external APIs and services, extending its capabilities beyond the native Zaia Endless ecosystem.

With it, your Agent can retrieve data, create or update records, trigger third-party actions, or synchronize information with external systems in real time.

***

### 🔹 How the HTTP Request Tool Works

1. You define the Tool with a **clear natural-language description** explaining when it should be used.
2. The Agent reads this description to decide **if and when** the Tool applies during a conversation.
3. You define **Properties (variables)** that the Agent must collect (e.g., ID, email, date).
4. If required properties are missing, the Agent will **ask the user for them first**.
5. Once all required data is available, the Agent executes the HTTP request using your configuration.

This ensures that every request is **complete, contextual, and accurate** before execution.

***

### 🔹 Supported HTTP Methods

The HTTP Request Tool supports all standard REST methods:

* **GET** → Retrieve information
* **POST** → Create new resources
* **PUT** → Update existing resources
* **PATCH** → Perform partial updates
* **DELETE** → Remove resources

***

### ⚙️ Configuration Fields

When creating an HTTP Request Tool, you configure:

* **Name**
* **Description** (what the Tool does and when to use it)
* **URL**
* **Method**
* **Headers**
* **Query parameters**
* **Body**
* **Properties (variables)**

Each property includes:

* Type (string, number, etc.)
* Description (used by the Agent to ask the user correctly)
* Required / optional flag

***

### 🧩 Property Picker (Variable Insertion)

When editing **Headers**, **Query**, or **Body**, Zaia Endless provides a **Property Picker**.

Instead of typing variables manually (`{{variableName}}`), you can:

1. Click inside any field (Headers, Query, or Body).
2. A floating list appears showing all defined properties.
3. Click a property to automatically insert it in the correct format.

💡 **Example**\
If a property is called `userId`, selecting it automatically inserts:

```
{{userId}}
```

This eliminates syntax errors and significantly speeds up configuration.

***

### 🤖 cURL Import Assistant

Zaia Endless includes a **Creation Assistant** that allows you to **import a full HTTP configuration directly from a cURL command**.

#### How it works:

1. Click the **magic wand / assistant icon** when creating an HTTP Request Tool.
2. Paste a full `curl` command (or describe the request).
3. The Assistant automatically:
   * Detects the **HTTP method**
   * Extracts the **URL**
   * Parses **headers**
   * Converts request body fields into **Properties**
   * Pre-fills the Tool configuration

This is especially useful when:

* You already have API examples from documentation
* You are migrating existing integrations
* You want to avoid manual configuration errors

💡 **Example cURL**

```bash
curl -X POST "https://api.example.com/users" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"John","email":"john@email.com"}'
```

The Assistant will automatically generate:

* URL
* Method: POST
* Headers
* Body
* Properties (`name`, `email`)

You can then refine descriptions and required fields before saving.

***

### 🔹 Example Setup

**Name:** Customer API Lookup\
**Description:**\
“Allows the Agent to retrieve customer information from the external CRM using a customer ID.”

**Property:**

* `id` (number) → “Customer ID provided by the user. Must be numeric.”

**Configuration:**

* URL: `https://api.crm.com/customers/{{id}}`
* Method: GET
* Headers:

```json
{
  "Authorization": "Bearer {{api_key}}"
}
```

**Example POST Body:**

```json
{
  "name": "{{name}}",
  "email": "{{email}}",
  "project_type": "{{project_type}}"
}
```

If `project_type` is missing, the Agent will ask the user for it before executing the request.

***

### 🧠 Best Practices

* Be explicit in property descriptions\
  \&#xNAN;*Example:* “Date of birth in format YYYY-MM-DD.”
* Keep Tools focused — one Tool per clear API action.
* Always test requests using the **Internal Chat** before publishing.
* Avoid hardcoding secrets directly in requests.
* For complex APIs, split actions into multiple Tools.
* Use the **Property Picker** and **cURL Assistant** to reduce errors.

***

### ✅ Key Takeaway

The HTTP Request Tool is the **bridge between your Agent and the external world**.

By combining:

* Clear descriptions
* Well-defined properties
* The Property Picker
* The cURL Import Assistant

You enable your Agents to safely, dynamically, and intelligently interact with any external API — asking for missing data when needed and executing only when everything is ready.


---

# 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.zaia.app/tools/available-tools/http-request-tool.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.