# Create API Tools

{% hint style="info" %}
You can use MaiAgent's [Tool Creation 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 (application)
* **Kitchen**: The place where food is prepared (system providing services)
* **Waiter**: Passing messages between you and the kitchen (**API**)

You don't need to go directly to the kitchen; you just tell the waiter what you want, the waiter communicates your needs to the kitchen, and then brings the prepared meal to you.

<figure><img src="/files/do5ctXNF4znRmsIgDz4m" alt=""><figcaption><p>API Process Diagram</p></figcaption></figure>

API tools can help you automate standardized processes and configure specific return formats. They can also help you retrieve information from your system, such as:

**E-commerce Customer Service Automation**

```
Customer inquires about order ➡️ API queries order status ➡️ Automatically responds with delivery progress
```

**Marketing Campaign Management**

```
New product launch ➡️ Automatically update website ➡️ Send EDM ➡️ Social media promotion
```

**Online Course Platform:**

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

Through API tools, AI assistants evolve from simple chatbots into intelligent assistants capable of actually executing business processes, significantly improving work efficiency and automation.

## Quick Create API Tool

### 1. Access Tool Management Interface

First, navigate to the "<mark style="color:blue;">AI Features</mark>" section from the left sidebar, then click "<mark style="color:blue;">🔧 Tools</mark>". After entering the tools list page, click the "<mark style="color:blue;">➕ Add Tool</mark>" button in the upper right corner.

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

### 2. Select Tool Type

For tool type, select API.

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

### 3. Set Display Name

Set a clear display name for the tool, here set as <mark style="color:blue;">google calendar</mark>.

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

* **Purpose**: This name will be displayed in the platform interface for all users to view.
* **Recommendation**: Choose a name that clearly expresses the tool's main function for easy user understanding. There are no strict format restrictions for this name.

### 4. Set 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 to internally call and identify this tool.
* **Naming Rules (Important)**:
  * Must use English.
  * Can only include:
    * Lowercase letters (a-z)
    * Uppercase letters (A-Z)
    * Numbers (0-9)
    * Underscores (`_`)
    * Hyphens (`-`)
  * **Examples**: `get_weather_forecast`, `database-query-tool`

In the image below, it's set as <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 Tool Description

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

* **Importance**: A good description helps the AI assistant more accurately understand:
  * The tool's functionality and purpose.
  * When this tool should be used.
  * How to interpret the tool's output results.
* **Recommended Content**: Explain what the tool does, what it inputs, what it outputs, and any usage precautions.

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

### 6. API Configuration Detailed Settings

#### a. 🔗 API URL

* Fill in the complete 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 menu:
  * `GET`: Typically used to retrieve resources.
  * `POST`: Typically used to create new resources or submit data.
  * `PUT`: Typically used to completely replace or update resources.
  * `DELETE`: Typically used to delete 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, telling the receiver some important information before seeing the actual data content. **Without correct headers, API requests may fail authentication, or the receiver may be unable 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, you need to:

* 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 contents (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 header settings screenshot"><figcaption><p>Configure necessary HTTP request headers</p></figcaption></figure>

#### d. 🧩 Parameters Schema

**Parameters schema is like an "order form"**, telling the AI assistant what data it can request from the API and how to request it.

* **Core Configuration**: Define which parameters the AI assistant can or must provide when calling this tool (content to be passed to the system for processing), and the format of these parameters.
* **Format**: Uses standard **JSON Schema** format.
* **Key Elements**:
  * `type: "object"`: Indicates parameters are an object.
  * `properties`: Defines the object for each parameter.
    * **Parameter Name** (e.g., `"search"`): The corresponding object contains details about that parameter.
      * `type`: Parameter's data type (`string`, `integer`, `number`, `boolean`, `array`, `object`).
      * `description`: Explanation for the AI assistant, describing the meaning of this parameter.
      * `default` (optional): Default value for the parameter.
      * `enum` (optional): If parameter values can only be specific options, list them here.
  * `required`: An array containing all **required** parameter names.
* **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 keywords"
          }
      },
      "required": ["search"]
  }
  ```

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

### 7. 💾 Save 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, it's recommended to test whether the API works normally
* You can use testing tools to verify tool functionality, such as:
  * POSTMAN
  * Enterprise's own API testing request platform

**Permission Management**

* Regularly review tool usage status and permission access status


---

# 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.maiagent.ai/maiagent-user-guide/maiagent-user-guide-en/tools/setup_api_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.