Create an API Tool
This guide walks you through creating a new API tool on the platform.
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.
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
Marketing Campaign Management
Online Course Platform:
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 "AI Features" section, then click "🔧 Tools." On the tool list page, click the "➕ Add Tool" button in the upper right corner.
2. Select the Tool Type
Select API as the tool type.
3. Set the Display Name
Set a clear display name for the tool. In this example, set it to google calendar.
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 "Tool Name" 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 google_calendar_retriever
5. Write the Tool Description
In the "Tool Description" 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.
6. Detailed API Configuration
a. 🔗 API URL
Enter the full URL of the target API endpoint (including
http://orhttps://).Example:
https://api.opencalendar.org/data/2.5
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.
c. 📰 Headers
Headers are like the "envelope" 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 "➕ 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:
d. 🔎 Query Parameters
Query parameters are query strings appended after the question mark in a URL (for example, ?format=json&limit=10) and are sent with every request. They are suitable for fixed query conditions or API keys that can only be passed through the query string.
Click "Available Context Variables" to expand the list of currently supported variables (contact ID, conversation ID, inbox ID, and others).
Format: A valid JSON object where each key is a parameter name and each value is the parameter content (a string).
Values can be fixed text, or they can use
{{parameter_name}}to reference a parameter declared in the Parameters Schema and supplied by the AI assistant when the tool is called. This lets you configure query conditions where the first part is fixed and the remaining value is provided by the user. See Reference AI assistant parameters in Query Parameters below.Example:
e. 🧩 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):
7. 💾 Save the 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!
Reference AI assistant parameters in Query Parameters
Many third-party APIs use query conditions made up of a single string containing fixed syntax and a user-provided value. Examples include the OData-style $filter=ProductName eq 'Chai' and the q= parameter used by search APIs. These APIs do not expect a separate parameter; instead, they require the value to be embedded in a fixed string.
Enter {{parameter_name}} in a Query Parameters value. When the AI assistant calls the tool, MaiAgent substitutes the value of the parameter with the same name from the Parameters Schema before sending the request. The person configuring the tool defines the fixed structure, while the AI assistant only supplies the value, so syntax correctness no longer depends on the model.
Use case
A procurement department wants its internal AI assistant to directly answer questions such as, "What are the current unit price and inventory for a product?" The data comes from an OData query service provided by the company's product catalog system. Previously, each API query required custom code. Now, a procurement specialist can create an API tool, set the query condition to ProductName eq '{{product_name}}', and assign the tool to the AI assistant. When a colleague asks, "What are the unit price and inventory for Chai?", the AI assistant automatically inserts Chai into the query condition, calls the API, and replies with the product name, unit price, and inventory.
Setup steps
The following example uses the public Northwind sample data service (OData), so you can follow the steps directly:
Assign the tool to an AI assistant and test it
Follow Assign Tools to an AI Assistant to add this tool to an AI assistant in Agent mode and save it. Then, use the left navigation bar to open "Agent Marketplace", switch to "Organization-created", and select the AI assistant to start a conversation. Enter "What are the unit price and inventory for Chai?" The AI assistant displays "Tool used" and replies with Chai's unit price and inventory.
Substitution rules
Variable names must match the Parameters Schema
{{product_name}} corresponds to the parameter name under properties in the Parameters Schema. The name is case-sensitive.
Only values are substituted
Templates apply only to Query Parameters values. Keys remain unchanged and are not substituted.
Values are inserted verbatim
Parameter values are always inserted as literal text with no numeric conversion. For example, the leading zero in the business registration number 04595257 is preserved.
Missing values stop the request
If the AI assistant does not provide the parameter for a call, or the value is empty, the tool stops with an error that identifies the missing parameter. It does not send {{product_name}} as-is.
Context variables take priority
If a parameter has the same name as a context variable, such as contact_id or conversation_id, the context variable's value is always used. A value provided by the AI assistant cannot override it.
Referenced parameters are still sent separately
A parameter referenced by a template is still sent as an independent query parameter according to the existing behavior (for example, product_name=Chai is also sent). Most APIs ignore extra parameters.
Parameter names are preserved
Query parameter keys containing underscores or uppercase letters, such as Business_Accounting_NO, are preserved and are not rewritten by the system.
Existing tool settings that do not contain {{ }} are completely unaffected. If the system previously rewrote a Query Parameter name in an existing tool (for example, changing Business_Accounting_NO to business__accounting_no), reopen the tool, restore the correct name, and save it. When you reopen the editing window, Query Parameters values are masked as ****; saving directly does not remove the original values.
⚠️ 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
Last updated
Was this helpful?