Create API Tools

This guide will walk you through creating new API tools on the platform.

You can use the Tool Creation AI Assistant made by MaiAgent to help you create API tools

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

What is an API?

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

Imagine dining at a restaurant:

• You: The customer who needs food (application)

• Kitchen: Where food is prepared (service-providing system)

• Waiter: Passes messages between you and the kitchen (API)

You don't need to go directly into the kitchen - just tell the waiter what you want, and they'll communicate your needs to the kitchen and bring the prepared food to you.

API Flow Diagram

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

E-commerce Customer Service Automation

Customer order inquiry ➡️ API checks order status ➡️ Automatic delivery progress reply

Marketing Campaign Management

New product launch ➡️ Auto-update website ➡️ Send EDM ➡️ Social media promotion

Online Course Platform:

Student progress inquiry ➡️ API checks learning records ➡️ Auto-reply with completion percentage and next class time

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

Quick API Tool Creation

1. Access Tool Management Interface

First, navigate to the "AI Features" section from the left sidebar, then click "🔧 Tools". Once on the tools list page, click the "➕ Add Tool" button in the top right corner.

Click "➕ Add Tool" to begin creation

2. Select Tool Type

For tool type, select API.

3. Set Display Name

Set a clear display name for the tool, in this case google calendar.

• Purpose: This name will be displayed in the platform interface for all users to see.

• Recommendation: Choose a name that clearly expresses the tool's main function for easy user understanding. This name has no strict format restrictions.

4. Set Tool Name

Next is the "Tool Name" 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 contain:

    • Lowercase letters (a-z)

    • Uppercase letters (A-Z)

    • Numbers (0-9)

    • Underscore (_)

    • Hyphen (-)

  • Examples: get_weather_forecast, database-query-tool

Set as google_calendar_retriever in the image below

API Tool Name Definition

5. Write Tool Description

In the "Tool Description" field, users can provide clear and detailed tool documentation.

• Importance: Good descriptions help AI assistants better understand:

  • The tool's functionality and purpose

  • When to use this tool

  • How to interpret the tool's output

• Recommended Content: Explain what the tool does, what it takes as input, what it outputs, and any usage notes

Tool Description

6. API Configuration Details

a. 🔗 API URL

• Enter the complete URL of the target API endpoint (including http:// or https://)

• Example: https://api.opencalendar.org/data/2.5

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

c. 📰 Headers

Headers are like the "envelope" of a letter, telling the receiver important information before seeing the actual content. Without correct headers, API requests may fail authentication or the receiver may not be able to properly parse the data.

Common Uses:

• Authentication (Authorization, X-API-Key)

• Specify content type (Content-Type)

• Specify accepted response format (Accept)

To add headers, you need to:

• Click "➕ Add Header" 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:

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

Set required HTTP request headers

d. 🧩 Parameters Schema

The parameter structure is like a "menu", telling the AI assistant what data can be requested from the API and how to request it.

• Core Settings: Define what parameters the AI assistant can or must provide when calling this tool (content to be passed to the system for processing) and their format

• Format: Uses standard JSON Schema format

• Key Elements:

  • type: "object": Indicates parameters are an object

  • properties: Object defining each parameter

    • Parameter Name (e.g. "search"): Corresponding object contains parameter details

      • type: Parameter data type (string, integer, number, boolean, array, object)

      • description: Explanation of the parameter's meaning for the AI assistant

      • default (optional): Parameter's default value

      • enum (optional): List of allowed values if parameter can only be certain options

  • required: Array containing names of all required parameters

• Example (Media Search Tool):

  {
      "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"]
  }

Use JSON Schema to precisely define API parameters

7. 💾 Save Tool

After confirming all settings are correct, scroll to the bottom of the page and click the "Confirm" button. Your new tool is now created!

⚠️ Important Reminders

Connection Testing

• After creating the tool, it's recommended to test if the API works properly

• Use testing tools to validate tool functionality, such as:

  • POSTMAN

  • Enterprise's own API testing request platform

Permission Management

• Regularly check tool usage status and permission settings