# 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="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-affedbd5ccc8692a11a20ce5fc69a39886d0e2d3%2Fplayma%20(10)%20(1).png?alt=media" 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="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-1849091665b669bc0c5964295e91459b75acbe42%2FMCP%E5%B7%A5%E5%85%B7.png?alt=media" 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="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-36d929d6f379aadbfe05520796e63d6f8fefaf4f%2FAPI%E5%B7%A5%E5%85%B7.png?alt=media" 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="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-1b6a8ebbc7b3900a46b0a20494b1c11c118fbe47%2FAPI%E5%B7%A5%E5%85%B7%20(2).png?alt=media" 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="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-e60b90c068677f55f73f007d3f191a41bc3a9e5f%2FAPI%E5%B7%A5%E5%85%B7%20(4).png?alt=media" 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="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-61fe2994e26226077604c4865223522621a0c39c%2FAPI%E5%B7%A5%E5%85%B7%20(5).png?alt=media" 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="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-7c8ec1446f411f007db93eecab4a2de07ee8036e%2FAPI%E5%B7%A5%E5%85%B7%20(6).png?alt=media" 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="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-a96418d1f33a03fb89d7c99d75cbff4200fa5851%2FAPI%E5%B7%A5%E5%85%B7%20(8).png?alt=media" 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="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-6d67f75950755371440b5dcd1a50016f36259224%2FAPI%E5%B7%A5%E5%85%B7%20(9).png?alt=media" 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="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-5932120820f0a885644b441bac5c63a4492ae567%2FAPI%E5%B7%A5%E5%85%B7%20(11).png?alt=media" 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="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-eb2d956da69f2a187bf9f57c4cc86d0a07c2de73%2FAPI%E5%B7%A5%E5%85%B7%20(13).png?alt=media" 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