> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-en/tools/setup_api_tool.md).

# Create an API Tool

{% hint style="info" %}
You can use MaiAgent's [Tool Builder AI Assistant](https://chat.maiagent.ai/web-chats/27934296-105a-4f3f-80f0-7e9dcdb638d3) to help you create API tools
{% endhint %}

API tools are used to integrate external services and automate operational workflows.

## **What Is an API?**

**API (Application Programming Interface)** is a bridge for communication between different software systems. Simply put, it's like a **"waiter" in the software world**, helping different programs exchange information and execute functions.

Imagine you're dining at a restaurant:

* **You**: The customer who needs food (the application)
* **Kitchen**: The place that prepares food (the service provider system)
* **Waiter**: The person who relays messages between you and the kitchen (**API**)

You don't need to go into the kitchen yourself — just tell the waiter what you want. The waiter conveys your request to the kitchen, then brings the finished meal to you.

<figure><img src="/files/do5ctXNF4znRmsIgDz4m" alt=""><figcaption><p>API workflow diagram</p></figcaption></figure>

API tools can help you automate standardized workflows, set specific response formats, and retrieve information from your systems such as:

**E-Commerce Customer Service Automation**

```
Customer asks about order ➡️ API queries order status ➡️ Automatically replies with delivery progress
```

**Marketing Campaign Management**

```
New product listed ➡️ Automatically updates website ➡️ Sends EDM ➡️ Promotes on social media
```

**Online Course Platform:**

```
Student asks about course progress ➡️ API queries learning records ➡️ Automatically replies with completion percentage and next class time
```

Through API tools, the AI assistant evolves from a simple chatbot into an intelligent assistant capable of executing actual business workflows, significantly improving work efficiency and automation.

## Quick API Tool Setup

### 1. Access the Tool Management Interface

From the left navigation panel, go to the "<mark style="color:blue;">AI Features</mark>" section, then click "<mark style="color:blue;">🔧 Tools</mark>." On the tool list page, click the "<mark style="color:blue;">➕ Add Tool</mark>" button in the upper right corner.

<figure><img src="/files/BIDjwugoD6MaLatxrK8q" alt="Tool list page and add button"><figcaption><p>Click "➕ Add Tool" to get started</p></figcaption></figure>

### 2. Select the Tool Type

Select API as the tool type.

<figure><img src="/files/E3RxJjZ3amCsnXv2KmoG" alt=""><figcaption></figcaption></figure>

### 3. Set the Display Name

Set a clear display name for the tool. In this example, set it to <mark style="color:blue;">google calendar</mark>.

<figure><img src="/files/3tvZzGbfLcxRUEHO9hoy" alt=""><figcaption></figcaption></figure>

* **Purpose**: This name is displayed on the platform interface for all users to see.
* **Recommendation**: Choose a name that clearly describes the tool's main function for easy user understanding. There are no strict formatting requirements for this name.

### 4. Set the Tool Name

Next is the "<mark style="color:blue;">Tool Name</mark>" field.

* **Purpose**: This name is the unique identifier used by the AI assistant internally to call and identify this tool.
* **Naming Rules (Important)**:
  * Must be in English.
  * Can only contain:
    * Lowercase letters (a-z)
    * Uppercase letters (A-Z)
    * Numbers (0-9)
    * Underscores (`_`)
    * Hyphens (`-`)
  * **Examples**: `get_weather_forecast`, `database-query-tool`

The example below is set to <mark style="color:blue;">google\_calendar\_retriever</mark>

<figure><img src="/files/ezB6KOeJa1XFG5jtyHv6" alt=""><figcaption><p>API tool name definition</p></figcaption></figure>

### 5. Write the Tool Description

In the "<mark style="color:blue;">Tool Description</mark>" field, provide a clear and detailed tool description.

* **Importance**: A good description helps the AI assistant more accurately understand:
  * The tool's function and purpose.
  * When to use this tool.
  * How to interpret the tool's output results.
* **Suggested Content**: Describe what the tool does, what it takes as input, what it outputs, and any usage notes.

<figure><img src="/files/dKiiESRlFn5XgjWACoAR" alt=""><figcaption><p>Tool description</p></figcaption></figure>

### 6. Detailed API Configuration

#### a. 🔗 API URL

* Enter the full URL of the target API endpoint (including `http://` or `https://`).
* **Example**: `https://api.opencalendar.org/data/2.5`

<figure><img src="/files/PypK3fZOctw2eEDBmo7c" alt=""><figcaption></figcaption></figure>

#### b. 📮 HTTP Method

* Select the HTTP verb required by the API service from the dropdown:
  * `GET`: Typically used for retrieving resources.
  * `POST`: Typically used for creating new resources or submitting data.
  * `PUT`: Typically used for fully replacing or updating resources.
  * `DELETE`: Typically used for deleting resources.

<figure><img src="/files/9bCQUzzqaFsbeBJgvGvx" alt=""><figcaption></figcaption></figure>

#### c. 📰 Headers

Headers are like the "<mark style="color:blue;">envelope</mark>" of a letter. Before seeing the actual data content, they tell the receiver some important information. **Without correct headers, API requests may fail authentication, or the receiver may not be able to parse the data correctly.**

**Common Uses**:

* Authentication (`Authorization`, `X-API-Key`)
* Specify content type (`Content-Type`)
* Specify accepted response format (`Accept`)

To add headers:

* Click "<mark style="color:blue;">➕ Add Header</mark>" to define HTTP headers sent with the request.
* **Format**: Must be a valid JSON object where keys are header names and values are header content (strings).
* **Example**:

  ```json
  {
    "Content-Type": "application/json; charset=utf-8",
    "Authorization": "Bearer {{SECRET_API_TOKEN}}",
    "Accept": "application/vnd.github.v3+json"
  }
  ```

<figure><img src="/files/j2stKgNc2fYAlYvh3sbF" alt="API headers configuration screenshot"><figcaption><p>Configure required HTTP request headers</p></figcaption></figure>

#### d. 🧩 Parameters Schema

**The parameters schema is like an "order form"** — it tells the AI assistant what data it can request from the API and how to make the request.

* **Core Configuration**: Define which parameters the AI assistant can or must provide when calling this tool, as well as the format of those parameters.
* **Format**: Use standard **JSON Schema** format.
* **Key Elements**:
  * `type: "object"`: Indicates the parameters are an object.
  * `properties`: Defines the object for each parameter.
    * **Parameter name** (e.g., `"search"`): The corresponding object contains that parameter's details.
      * `type`: The parameter's data type (`string`, `integer`, `number`, `boolean`, `array`, `object`).
      * `description`: A description for the AI assistant explaining the parameter's meaning.
      * `default` (optional): The parameter's default value.
      * `enum` (optional): If the parameter value can only be one of specific options, list them here.
  * `required`: An array containing the names of all **required** parameters.
* **Example** (video search tool):

  ```json
  {
      "type": "object",
      "properties": {
          "limit": {
              "type": "integer",
              "minimum": 1,
              "description": "Maximum number of results to return"
          },
          "fields": {
              "type": "string",
              "description": "Comma-separated list of fields"
          },
          "search": {
              "type": "string",
              "description": "Search keyword"
          }
      },
      "required": ["search"]
  }
  ```

<figure><img src="/files/veahQQ54bUNf4hk0aaUT" alt="API parameters schema configuration screenshot"><figcaption><p>Use JSON Schema to precisely define API parameters</p></figcaption></figure>

### 7. 💾 Save the Tool

After confirming all settings are correct, scroll to the bottom of the page and click the "<mark style="color:blue;">Confirm</mark>" button. Your new tool is now created!

<figure><img src="/files/X4oGUQOizpvkBFnayoqi" alt=""><figcaption></figcaption></figure>

## ⚠️ Important Reminders

**Connection Testing**

* After creating the tool, test the API to ensure it works properly
* Use testing tools to verify functionality, such as:
  * POSTMAN
  * Your company's own API testing platform

**Permission Management**

* Regularly check tool usage status and permission access settings


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-en/tools/setup_api_tool.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.