> 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/api/api-reference/gong-ju-he-lian-jie-qi.md).
# 工具與連接器
### 建立工具
POST `/api/v1/tools/`
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | object | 否 | Tool name may only contain letters, digits, underscores (\_) and hyphens (-). Not required for MCP tools; for API tools it is the tool name given to the LLM. |
| displayName | string | 是 | A name with any characters, used by users for configuration and management. |
| description | string | 否 | Tool description shown to users. Not required for MCP tools. |
| prompt | string | 否 | Tool description/prompt given to the LLM. If empty, the description field is used. Not required for MCP tools. |
| toolType | string (enum: api, function, mcp, desktop, flex, quick\_reply, quick\_menu) | 否 | `api`: API ; `function`: Function ; `mcp`: MCP ; `desktop`: Desktop ; `flex`: Flex Message ; `quick_reply`: Quick Reply ; `quick_menu`: Quick Menu; |
| apiUrl | string | 否 | |
| httpMethod | object | 否 | |
| rawHeaders | object | 否 | |
| sensitiveHeaders | array\[string] | 否 | |
| rawQueryParams | object | 否 | Query string parameters appended to every request of this API tool. Values support the same {{variable}} template rendering as raw\_headers. On key collision with LLM-generated arguments, these values ... |
| rawParametersSchema | object | 否 | |
| functionCode | string | 否 | |
| mcpUrl | string | 否 | |
| mcpRegistry | string (uuid) | 否 | Registry backing this MCP tool. Null for manual-URL MCP tools. |
| mcpAllowedTools | object | 否 | |
| rawMcpHeader | object | 否 | Default headers used when the Contact has no matching MCP Credential. |
| authSubject | object | 否 | Shared uses the tool level token plus per contact credentials; contact requires per contact authentication only; caller mints a short-lived token for the conversation-bound member (falls back to per c... |
| flexTemplateJson | object | 否 | FlexMessage JSON template. Required for FLEX\_MESSAGE tools. Stores the full LINE FlexMessage JSON structure (bubble / carousel / box / text / image / button etc.). |
| flexSchema | object | 否 | AI dynamic field schema for FlexMessage. JSON object whose keys are field paths parsed from flex\_template\_json (e.g. text / image url / button label / button uri / button message). Each value may be e... |
| quickReplyConfig | object | 否 | Authoring config for QUICK\_REPLY tools. Structured JSON describing the chip buttons: static list or dynamic (LLM-generated) mode, each field either a fixed value or an LLM prompt. |
| quickMenuConfig | object | 否 | Authoring config for QUICK\_MENU tools. Structured JSON describing the persistent input-bar menu rendered by the web chat only: layout (grid / list), default open state, and 2-6 items each carrying a d... |
| category | string (enum: knowledge\_base, web\_search, web\_fetch, code\_execution, file\_processing, image\_video\_generation, database\_query, third\_party\_integration, browser\_operation, agent\_collaboration, other) | 否 | `knowledge_base`: Knowledge base retrieval ; `web_search`: Web search ; `web_fetch`: Web page fetch ; `code_execution`: Code execution ; `file_processing`: File processing ; `image_video_generation`: ... |
| displayCopyByLocale | object | 否 | |
| outputRenderTemplateByLocale | object | 否 | |
| toolDisplayMode | object | 否 | |
| groups | array\[IdName] | 否 | Groups this tool is assigned to. Non-owner members must pick at least one group they belong to. |
**請求結構範例**
```typescript
{
"name"?: // 可能有不同的類型 (非必填)
string // Tool name may only contain letters, digits, underscores (_) and hyphens (-). Not required for MCP tools; for API tools it is the tool name given to the LLM. (非必填)
"displayName": string // A name with any characters, used by users for configuration and management.
"description"?: string // Tool description shown to users. Not required for MCP tools. (非必填)
"prompt"?: string // Tool description/prompt given to the LLM. If empty, the description field is used. Not required for MCP tools. (非必填)
"toolType"?: string (enum: api, function, mcp, desktop, flex, quick_reply, quick_menu) // * `api` - API
* `function` - Function
* `mcp` - MCP
* `desktop` - Desktop
* `flex` - Flex Message
* `quick_reply` - Quick Reply
* `quick_menu` - Quick Menu (非必填)
"apiUrl"?: string // 非必填
"httpMethod"?: // 可能有不同的類型 (非必填)
string (enum: get, post, put, delete, patch) // 非必填
"rawHeaders"?: object // 非必填
"sensitiveHeaders"?: [ // 非必填
string
]
"rawQueryParams"?: object // Query string parameters appended to every request of this API tool. Values support the same {{variable}} template rendering as raw_headers. On key collision with LLM-generated arguments, these values win — use this field for API keys that must travel in the query string. (非必填)
"rawParametersSchema"?: object // 非必填
"functionCode"?: string // 非必填
"mcpUrl"?: string // 非必填
"mcpRegistry"?: string (uuid) // Registry backing this MCP tool. Null for manual-URL MCP tools. (非必填)
"mcpAllowedTools"?: object // 非必填
"rawMcpHeader"?: object // Default headers used when the Contact has no matching MCP Credential. (非必填)
"authSubject"?: // Shared uses the tool level token plus per contact credentials; contact requires per contact authentication only; caller mints a short-lived token for the conversation-bound member (falls back to per contact credentials when the conversation has no bound member). MCP tools only.
* `shared` - Shared
* `contact` - Contact
* `caller` - Caller (非必填)
{
}
"flexTemplateJson"?: object // FlexMessage JSON template. Required for FLEX_MESSAGE tools. Stores the full LINE FlexMessage JSON structure (bubble / carousel / box / text / image / button etc.). (非必填)
"flexSchema"?: object // AI dynamic field schema for FlexMessage. JSON object whose keys are field paths parsed from flex_template_json (e.g. text / image url / button label / button uri / button message). Each value may be either a plain string (the AI prompt) or an object carrying additional metadata such as a field tag, e.g. {"prompt": "...", "tag": "title"}. Empty values fall back to the template default. (非必填)
"quickReplyConfig"?: object // Authoring config for QUICK_REPLY tools. Structured JSON describing the chip buttons: static list or dynamic (LLM-generated) mode, each field either a fixed value or an LLM prompt. (非必填)
"quickMenuConfig"?: object // Authoring config for QUICK_MENU tools. Structured JSON describing the persistent input-bar menu rendered by the web chat only: layout (grid / list), default open state, and 2-6 items each carrying a display label plus an action payload (send prompt / prefill text / open http(s) link). (非必填)
"category"?: string (enum: knowledge_base, web_search, web_fetch, code_execution, file_processing, image_video_generation, database_query, third_party_integration, browser_operation, agent_collaboration, other) // * `knowledge_base` - Knowledge base retrieval
* `web_search` - Web search
* `web_fetch` - Web page fetch
* `code_execution` - Code execution
* `file_processing` - File processing
* `image_video_generation` - Image/video generation
* `database_query` - Database query
* `third_party_integration` - Third-party integration
* `browser_operation` - Browser operation
* `agent_collaboration` - Agent collaboration
* `other` - Other (catch-all) (非必填)
"displayCopyByLocale"?: object // 非必填
"outputRenderTemplateByLocale"?: object // 非必填
"toolDisplayMode"?: // 可能有不同的類型 (非必填)
string (enum: full, compact, hidden) // 非必填
"groups"?: [ // Groups this tool is assigned to. Non-owner members must pick at least one group they belong to. (非必填)
{
"id": string (uuid)
}
]
}
```
**請求範例值**
```json
{
"name": null,
"displayName": "範例字串",
"description": "範例字串",
"prompt": "範例字串",
"toolType": "api",
"apiUrl": "範例字串",
"httpMethod": null,
"rawHeaders": null,
"sensitiveHeaders": [
"範例字串"
],
"rawQueryParams": null,
"rawParametersSchema": null,
"functionCode": "範例字串",
"mcpUrl": "範例字串",
"mcpRegistry": "550e8400-e29b-41d4-a716-446655440000",
"mcpAllowedTools": null,
"rawMcpHeader": null,
"authSubject": {},
"flexTemplateJson": null,
"flexSchema": null,
"quickReplyConfig": null,
"quickMenuConfig": null,
"category": "knowledge_base",
"displayCopyByLocale": null,
"outputRenderTemplateByLocale": null,
"toolDisplayMode": null,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
]
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/tools/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": null,
"displayName": "範例字串",
"description": "範例字串",
"prompt": "範例字串",
"toolType": "api",
"apiUrl": "範例字串",
"httpMethod": null,
"rawHeaders": null,
"sensitiveHeaders": [
"範例字串"
],
"rawQueryParams": null,
"rawParametersSchema": null,
"functionCode": "範例字串",
"mcpUrl": "範例字串",
"mcpRegistry": "550e8400-e29b-41d4-a716-446655440000",
"mcpAllowedTools": null,
"rawMcpHeader": null,
"authSubject": {},
"flexTemplateJson": null,
"flexSchema": null,
"quickReplyConfig": null,
"quickMenuConfig": null,
"category": "knowledge_base",
"displayCopyByLocale": null,
"outputRenderTemplateByLocale": null,
"toolDisplayMode": null,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
]
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"name": null,
"displayName": "範例字串",
"description": "範例字串",
"prompt": "範例字串",
"toolType": "api",
"apiUrl": "範例字串",
"httpMethod": null,
"rawHeaders": null,
"sensitiveHeaders": [
"範例字串"
],
"rawQueryParams": null,
"rawParametersSchema": null,
"functionCode": "範例字串",
"mcpUrl": "範例字串",
"mcpRegistry": "550e8400-e29b-41d4-a716-446655440000",
"mcpAllowedTools": null,
"rawMcpHeader": null,
"authSubject": {},
"flexTemplateJson": null,
"flexSchema": null,
"quickReplyConfig": null,
"quickMenuConfig": null,
"category": "knowledge_base",
"displayCopyByLocale": null,
"outputRenderTemplateByLocale": null,
"toolDisplayMode": null,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
]
};
axios.post("https://api.maiagent.ai/api/v1/tools/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/tools/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"name": None,
"displayName": "範例字串",
"description": "範例字串",
"prompt": "範例字串",
"toolType": "api",
"apiUrl": "範例字串",
"httpMethod": None,
"rawHeaders": None,
"sensitiveHeaders": [
"範例字串"
],
"rawQueryParams": None,
"rawParametersSchema": None,
"functionCode": "範例字串",
"mcpUrl": "範例字串",
"mcpRegistry": "550e8400-e29b-41d4-a716-446655440000",
"mcpAllowedTools": None,
"rawMcpHeader": None,
"authSubject": {},
"flexTemplateJson": None,
"flexSchema": None,
"quickReplyConfig": None,
"quickMenuConfig": None,
"category": "knowledge_base",
"displayCopyByLocale": None,
"outputRenderTemplateByLocale": None,
"toolDisplayMode": None,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
]
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/tools/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'name' => null,
'displayName' => '範例字串',
'description' => '範例字串',
'prompt' => '範例字串',
'toolType' => 'api',
'apiUrl' => '範例字串',
'httpMethod' => null,
'rawHeaders' => null,
'sensitiveHeaders' => [
'範例字串'
],
'rawQueryParams' => null,
'rawParametersSchema' => null,
'functionCode' => '範例字串',
'mcpUrl' => '範例字串',
'mcpRegistry' => '550e8400-e29b-41d4-a716-446655440000',
'mcpAllowedTools' => null,
'rawMcpHeader' => null,
'authSubject' => new \stdClass(),
'flexTemplateJson' => null,
'flexSchema' => null,
'quickReplyConfig' => null,
'quickMenuConfig' => null,
'category' => 'knowledge_base',
'displayCopyByLocale' => null,
'outputRenderTemplateByLocale' => null,
'toolDisplayMode' => null,
'groups' => [
[
'id' => '550e8400-e29b-41d4-a716-446655440000'
]
]
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
{
"id": string (uuid)
"name"?: // 可能有不同的類型 (非必填)
string // Tool name may only contain letters, digits, underscores (_) and hyphens (-). Not required for MCP tools; for API tools it is the tool name given to the LLM. (非必填)
"displayName": string // A name with any characters, used by users for configuration and management.
"description"?: string // Tool description shown to users. Not required for MCP tools. (非必填)
"prompt"?: string // Tool description/prompt given to the LLM. If empty, the description field is used. Not required for MCP tools. (非必填)
"toolType"?: string (enum: api, function, mcp, desktop, flex, quick_reply, quick_menu) // * `api` - API
* `function` - Function
* `mcp` - MCP
* `desktop` - Desktop
* `flex` - Flex Message
* `quick_reply` - Quick Reply
* `quick_menu` - Quick Menu (非必填)
"apiUrl"?: string // 非必填
"httpMethod"?: // 可能有不同的類型 (非必填)
string (enum: get, post, put, delete, patch) // 非必填
"rawHeaders"?: object // 非必填
"rawHeadersMasked": object
"sensitiveHeaders"?: [ // 非必填
string
]
"globalSensitiveHeaders": [ // Expose platform defaults as read-only authoring guidance.
string
]
"rawQueryParams"?: object // Query string parameters appended to every request of this API tool. Values support the same {{variable}} template rendering as raw_headers. On key collision with LLM-generated arguments, these values win — use this field for API keys that must travel in the query string. (非必填)
"rawQueryParamsMasked": object
"rawParametersSchema"?: object // 非必填
"functionCode"?: string // 非必填
"organization": string (uuid)
"createdBy": string (uuid)
"isGlobal": boolean // If set as global tool, all organizations can use this tool
"mcpUrl"?: string // 非必填
"mcpRegistry"?: string (uuid) // Registry backing this MCP tool. Null for manual-URL MCP tools. (非必填)
"mcpAllowedTools"?: object // 非必填
"rawMcpHeader"?: object // Default headers used when the Contact has no matching MCP Credential. (非必填)
"rawMcpHeaderMasked": object
"authSubject"?: // Shared uses the tool level token plus per contact credentials; contact requires per contact authentication only; caller mints a short-lived token for the conversation-bound member (falls back to per contact credentials when the conversation has no bound member). MCP tools only.
* `shared` - Shared
* `contact` - Contact
* `caller` - Caller (非必填)
{
}
"flexTemplateJson"?: object // FlexMessage JSON template. Required for FLEX_MESSAGE tools. Stores the full LINE FlexMessage JSON structure (bubble / carousel / box / text / image / button etc.). (非必填)
"flexSchema"?: object // AI dynamic field schema for FlexMessage. JSON object whose keys are field paths parsed from flex_template_json (e.g. text / image url / button label / button uri / button message). Each value may be either a plain string (the AI prompt) or an object carrying additional metadata such as a field tag, e.g. {"prompt": "...", "tag": "title"}. Empty values fall back to the template default. (非必填)
"quickReplyConfig"?: object // Authoring config for QUICK_REPLY tools. Structured JSON describing the chip buttons: static list or dynamic (LLM-generated) mode, each field either a fixed value or an LLM prompt. (非必填)
"quickMenuConfig"?: object // Authoring config for QUICK_MENU tools. Structured JSON describing the persistent input-bar menu rendered by the web chat only: layout (grid / list), default open state, and 2-6 items each carrying a display label plus an action payload (send prompt / prefill text / open http(s) link). (非必填)
"category"?: string (enum: knowledge_base, web_search, web_fetch, code_execution, file_processing, image_video_generation, database_query, third_party_integration, browser_operation, agent_collaboration, other) // * `knowledge_base` - Knowledge base retrieval
* `web_search` - Web search
* `web_fetch` - Web page fetch
* `code_execution` - Code execution
* `file_processing` - File processing
* `image_video_generation` - Image/video generation
* `database_query` - Database query
* `third_party_integration` - Third-party integration
* `browser_operation` - Browser operation
* `agent_collaboration` - Agent collaboration
* `other` - Other (catch-all) (非必填)
"displayCopyByLocale"?: object // 非必填
"outputRenderTemplateByLocale"?: object // 非必填
"toolDisplayMode"?: // 可能有不同的類型 (非必填)
string (enum: full, compact, hidden) // 非必填
"groups"?: [ // Groups this tool is assigned to. Non-owner members must pick at least one group they belong to. (非必填)
{
"id": string (uuid)
"name": string
}
]
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
"canUpdate": boolean // Return whether the current user can update this resource.
"canDelete": boolean // Return whether the current user can delete this resource.
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"displayName": "回應字串",
"description": "回應字串",
"prompt": "回應字串",
"toolType": "api",
"apiUrl": "回應字串",
"httpMethod": "get",
"rawHeaders": null,
"rawHeadersMasked": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"sensitiveHeaders": [
"回應字串"
],
"globalSensitiveHeaders": [
"回應字串"
],
"rawQueryParams": null,
"rawQueryParamsMasked": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"rawParametersSchema": null,
"functionCode": "回應字串",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"createdBy": "550e8400-e29b-41d4-a716-446655440000",
"isGlobal": false,
"mcpUrl": "回應字串",
"mcpRegistry": "550e8400-e29b-41d4-a716-446655440000",
"mcpAllowedTools": null,
"rawMcpHeader": null,
"rawMcpHeaderMasked": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"authSubject": {},
"flexTemplateJson": null,
"flexSchema": null,
"quickReplyConfig": null,
"quickMenuConfig": null,
"category": "knowledge_base",
"displayCopyByLocale": null,
"outputRenderTemplateByLocale": null,
"toolDisplayMode": "full",
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"createdAt": "回應字串",
"updatedAt": "回應字串",
"canUpdate": false,
"canDelete": false
}
```
***
### 列出工具
GET `/api/v1/tools/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------- | ------------------------------------------------------------ |
| `clientPlatform` | ❌ | string | 呼叫端平台。傳入 "desktop" 時會包含 desktop 類型工具，其餘值或未傳入則預設排除 desktop 工具 |
| `isGlobal` | ❌ | boolean | 設定為 "true" 以獲取全域工具，否則獲取組織工具 |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `toolType` | ❌ | string | 過濾工具類型：api, function, mcp, desktop |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/tools/?clientPlatform=desktop&isGlobal=true&page=1&pageSize=1&toolType=api" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/tools/?clientPlatform=desktop&isGlobal=true&page=1&pageSize=1&toolType=api", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/tools/?clientPlatform=desktop&isGlobal=true&page=1&pageSize=1&toolType=api"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/tools/?clientPlatform=desktop&isGlobal=true&page=1&pageSize=1&toolType=api", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"name"?: // 可能有不同的類型 (非必填)
string // Tool name may only contain letters, digits, underscores (_) and hyphens (-). Not required for MCP tools; for API tools it is the tool name given to the LLM. (非必填)
"displayName": string // A name with any characters, used by users for configuration and management.
"description"?: string // Tool description shown to users. Not required for MCP tools. (非必填)
"prompt"?: string // Tool description/prompt given to the LLM. If empty, the description field is used. Not required for MCP tools. (非必填)
"toolType"?: string (enum: api, function, mcp, desktop, flex, quick_reply, quick_menu) // * `api` - API
* `function` - Function
* `mcp` - MCP
* `desktop` - Desktop
* `flex` - Flex Message
* `quick_reply` - Quick Reply
* `quick_menu` - Quick Menu (非必填)
"apiUrl"?: string // 非必填
"httpMethod"?: // 可能有不同的類型 (非必填)
string (enum: get, post, put, delete, patch) // 非必填
"rawHeaders"?: object // 非必填
"rawHeadersMasked": object
"sensitiveHeaders"?: [ // 非必填
string
]
"globalSensitiveHeaders": [ // Expose platform defaults as read-only authoring guidance.
string
]
"rawQueryParams"?: object // Query string parameters appended to every request of this API tool. Values support the same {{variable}} template rendering as raw_headers. On key collision with LLM-generated arguments, these values win — use this field for API keys that must travel in the query string. (非必填)
"rawQueryParamsMasked": object
"rawParametersSchema"?: object // 非必填
"functionCode"?: string // 非必填
"organization": string (uuid)
"createdBy": string (uuid)
"isGlobal": boolean // If set as global tool, all organizations can use this tool
"mcpUrl"?: string // 非必填
"mcpRegistry"?: string (uuid) // Registry backing this MCP tool. Null for manual-URL MCP tools. (非必填)
"mcpAllowedTools"?: object // 非必填
"rawMcpHeader"?: object // Default headers used when the Contact has no matching MCP Credential. (非必填)
"rawMcpHeaderMasked": object
"authSubject"?: // Shared uses the tool level token plus per contact credentials; contact requires per contact authentication only; caller mints a short-lived token for the conversation-bound member (falls back to per contact credentials when the conversation has no bound member). MCP tools only.
* `shared` - Shared
* `contact` - Contact
* `caller` - Caller (非必填)
{
}
"flexTemplateJson"?: object // FlexMessage JSON template. Required for FLEX_MESSAGE tools. Stores the full LINE FlexMessage JSON structure (bubble / carousel / box / text / image / button etc.). (非必填)
"flexSchema"?: object // AI dynamic field schema for FlexMessage. JSON object whose keys are field paths parsed from flex_template_json (e.g. text / image url / button label / button uri / button message). Each value may be either a plain string (the AI prompt) or an object carrying additional metadata such as a field tag, e.g. {"prompt": "...", "tag": "title"}. Empty values fall back to the template default. (非必填)
"quickReplyConfig"?: object // Authoring config for QUICK_REPLY tools. Structured JSON describing the chip buttons: static list or dynamic (LLM-generated) mode, each field either a fixed value or an LLM prompt. (非必填)
"quickMenuConfig"?: object // Authoring config for QUICK_MENU tools. Structured JSON describing the persistent input-bar menu rendered by the web chat only: layout (grid / list), default open state, and 2-6 items each carrying a display label plus an action payload (send prompt / prefill text / open http(s) link). (非必填)
"category"?: string (enum: knowledge_base, web_search, web_fetch, code_execution, file_processing, image_video_generation, database_query, third_party_integration, browser_operation, agent_collaboration, other) // * `knowledge_base` - Knowledge base retrieval
* `web_search` - Web search
* `web_fetch` - Web page fetch
* `code_execution` - Code execution
* `file_processing` - File processing
* `image_video_generation` - Image/video generation
* `database_query` - Database query
* `third_party_integration` - Third-party integration
* `browser_operation` - Browser operation
* `agent_collaboration` - Agent collaboration
* `other` - Other (catch-all) (非必填)
"displayCopyByLocale"?: object // 非必填
"outputRenderTemplateByLocale"?: object // 非必填
"toolDisplayMode"?: // 可能有不同的類型 (非必填)
string (enum: full, compact, hidden) // 非必填
"groups"?: [ // Groups this tool is assigned to. Non-owner members must pick at least one group they belong to. (非必填)
{
"id": string (uuid)
"name": string
}
]
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
"canUpdate": boolean // Return whether the current user can update this resource.
"canDelete": boolean // Return whether the current user can delete this resource.
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"displayName": "回應字串",
"description": "回應字串",
"prompt": "回應字串",
"toolType": "api",
"apiUrl": "回應字串",
"httpMethod": "get",
"rawHeaders": null,
"rawHeadersMasked": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"sensitiveHeaders": [
"回應字串"
],
"globalSensitiveHeaders": [
"回應字串"
],
"rawQueryParams": null,
"rawQueryParamsMasked": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"rawParametersSchema": null,
"functionCode": "回應字串",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"createdBy": "550e8400-e29b-41d4-a716-446655440000",
"isGlobal": false,
"mcpUrl": "回應字串",
"mcpRegistry": "550e8400-e29b-41d4-a716-446655440000",
"mcpAllowedTools": null,
"rawMcpHeader": null,
"rawMcpHeaderMasked": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"authSubject": {},
"flexTemplateJson": null,
"flexSchema": null,
"quickReplyConfig": null,
"quickMenuConfig": null,
"category": "knowledge_base",
"displayCopyByLocale": null,
"outputRenderTemplateByLocale": null,
"toolDisplayMode": "full",
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"createdAt": "回應字串",
"updatedAt": "回應字串",
"canUpdate": false,
"canDelete": false
}
]
}
```
***
### 取得特定工具
GET `/api/v1/tools/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ------------------------------------ |
| `id` | ✅ | string | A UUID string identifying this Tool. |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"name"?: // 可能有不同的類型 (非必填)
string // Tool name may only contain letters, digits, underscores (_) and hyphens (-). Not required for MCP tools; for API tools it is the tool name given to the LLM. (非必填)
"displayName": string // A name with any characters, used by users for configuration and management.
"description"?: string // Tool description shown to users. Not required for MCP tools. (非必填)
"prompt"?: string // Tool description/prompt given to the LLM. If empty, the description field is used. Not required for MCP tools. (非必填)
"toolType"?: string (enum: api, function, mcp, desktop, flex, quick_reply, quick_menu) // * `api` - API
* `function` - Function
* `mcp` - MCP
* `desktop` - Desktop
* `flex` - Flex Message
* `quick_reply` - Quick Reply
* `quick_menu` - Quick Menu (非必填)
"apiUrl"?: string // 非必填
"httpMethod"?: // 可能有不同的類型 (非必填)
string (enum: get, post, put, delete, patch) // 非必填
"rawHeaders"?: object // 非必填
"rawHeadersMasked": object
"sensitiveHeaders"?: [ // 非必填
string
]
"globalSensitiveHeaders": [ // Expose platform defaults as read-only authoring guidance.
string
]
"rawQueryParams"?: object // Query string parameters appended to every request of this API tool. Values support the same {{variable}} template rendering as raw_headers. On key collision with LLM-generated arguments, these values win — use this field for API keys that must travel in the query string. (非必填)
"rawQueryParamsMasked": object
"rawParametersSchema"?: object // 非必填
"functionCode"?: string // 非必填
"organization": string (uuid)
"createdBy": string (uuid)
"isGlobal": boolean // If set as global tool, all organizations can use this tool
"mcpUrl"?: string // 非必填
"mcpRegistry"?: string (uuid) // Registry backing this MCP tool. Null for manual-URL MCP tools. (非必填)
"mcpAllowedTools"?: object // 非必填
"rawMcpHeader"?: object // Default headers used when the Contact has no matching MCP Credential. (非必填)
"rawMcpHeaderMasked": object
"authSubject"?: // Shared uses the tool level token plus per contact credentials; contact requires per contact authentication only; caller mints a short-lived token for the conversation-bound member (falls back to per contact credentials when the conversation has no bound member). MCP tools only.
* `shared` - Shared
* `contact` - Contact
* `caller` - Caller (非必填)
{
}
"flexTemplateJson"?: object // FlexMessage JSON template. Required for FLEX_MESSAGE tools. Stores the full LINE FlexMessage JSON structure (bubble / carousel / box / text / image / button etc.). (非必填)
"flexSchema"?: object // AI dynamic field schema for FlexMessage. JSON object whose keys are field paths parsed from flex_template_json (e.g. text / image url / button label / button uri / button message). Each value may be either a plain string (the AI prompt) or an object carrying additional metadata such as a field tag, e.g. {"prompt": "...", "tag": "title"}. Empty values fall back to the template default. (非必填)
"quickReplyConfig"?: object // Authoring config for QUICK_REPLY tools. Structured JSON describing the chip buttons: static list or dynamic (LLM-generated) mode, each field either a fixed value or an LLM prompt. (非必填)
"quickMenuConfig"?: object // Authoring config for QUICK_MENU tools. Structured JSON describing the persistent input-bar menu rendered by the web chat only: layout (grid / list), default open state, and 2-6 items each carrying a display label plus an action payload (send prompt / prefill text / open http(s) link). (非必填)
"category"?: string (enum: knowledge_base, web_search, web_fetch, code_execution, file_processing, image_video_generation, database_query, third_party_integration, browser_operation, agent_collaboration, other) // * `knowledge_base` - Knowledge base retrieval
* `web_search` - Web search
* `web_fetch` - Web page fetch
* `code_execution` - Code execution
* `file_processing` - File processing
* `image_video_generation` - Image/video generation
* `database_query` - Database query
* `third_party_integration` - Third-party integration
* `browser_operation` - Browser operation
* `agent_collaboration` - Agent collaboration
* `other` - Other (catch-all) (非必填)
"displayCopyByLocale"?: object // 非必填
"outputRenderTemplateByLocale"?: object // 非必填
"toolDisplayMode"?: // 可能有不同的類型 (非必填)
string (enum: full, compact, hidden) // 非必填
"groups"?: [ // Groups this tool is assigned to. Non-owner members must pick at least one group they belong to. (非必填)
{
"id": string (uuid)
"name": string
}
]
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
"canUpdate": boolean // Return whether the current user can update this resource.
"canDelete": boolean // Return whether the current user can delete this resource.
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"displayName": "回應字串",
"description": "回應字串",
"prompt": "回應字串",
"toolType": "api",
"apiUrl": "回應字串",
"httpMethod": "get",
"rawHeaders": null,
"rawHeadersMasked": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"sensitiveHeaders": [
"回應字串"
],
"globalSensitiveHeaders": [
"回應字串"
],
"rawQueryParams": null,
"rawQueryParamsMasked": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"rawParametersSchema": null,
"functionCode": "回應字串",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"createdBy": "550e8400-e29b-41d4-a716-446655440000",
"isGlobal": false,
"mcpUrl": "回應字串",
"mcpRegistry": "550e8400-e29b-41d4-a716-446655440000",
"mcpAllowedTools": null,
"rawMcpHeader": null,
"rawMcpHeaderMasked": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"authSubject": {},
"flexTemplateJson": null,
"flexSchema": null,
"quickReplyConfig": null,
"quickMenuConfig": null,
"category": "knowledge_base",
"displayCopyByLocale": null,
"outputRenderTemplateByLocale": null,
"toolDisplayMode": "full",
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"createdAt": "回應字串",
"updatedAt": "回應字串",
"canUpdate": false,
"canDelete": false
}
```
***
### 更新工具
PUT `/api/v1/tools/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ------------------------------------ |
| `id` | ✅ | string | A UUID string identifying this Tool. |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | object | 否 | Tool name may only contain letters, digits, underscores (\_) and hyphens (-). Not required for MCP tools; for API tools it is the tool name given to the LLM. |
| displayName | string | 是 | A name with any characters, used by users for configuration and management. |
| description | string | 否 | Tool description shown to users. Not required for MCP tools. |
| prompt | string | 否 | Tool description/prompt given to the LLM. If empty, the description field is used. Not required for MCP tools. |
| toolType | string (enum: api, function, mcp, desktop, flex, quick\_reply, quick\_menu) | 否 | `api`: API ; `function`: Function ; `mcp`: MCP ; `desktop`: Desktop ; `flex`: Flex Message ; `quick_reply`: Quick Reply ; `quick_menu`: Quick Menu; |
| apiUrl | string | 否 | |
| httpMethod | object | 否 | |
| rawHeaders | object | 否 | |
| sensitiveHeaders | array\[string] | 否 | |
| rawQueryParams | object | 否 | Query string parameters appended to every request of this API tool. Values support the same {{variable}} template rendering as raw\_headers. On key collision with LLM-generated arguments, these values ... |
| rawParametersSchema | object | 否 | |
| functionCode | string | 否 | |
| mcpUrl | string | 否 | |
| mcpRegistry | string (uuid) | 否 | Registry backing this MCP tool. Null for manual-URL MCP tools. |
| mcpAllowedTools | object | 否 | |
| rawMcpHeader | object | 否 | Default headers used when the Contact has no matching MCP Credential. |
| authSubject | object | 否 | Shared uses the tool level token plus per contact credentials; contact requires per contact authentication only; caller mints a short-lived token for the conversation-bound member (falls back to per c... |
| flexTemplateJson | object | 否 | FlexMessage JSON template. Required for FLEX\_MESSAGE tools. Stores the full LINE FlexMessage JSON structure (bubble / carousel / box / text / image / button etc.). |
| flexSchema | object | 否 | AI dynamic field schema for FlexMessage. JSON object whose keys are field paths parsed from flex\_template\_json (e.g. text / image url / button label / button uri / button message). Each value may be e... |
| quickReplyConfig | object | 否 | Authoring config for QUICK\_REPLY tools. Structured JSON describing the chip buttons: static list or dynamic (LLM-generated) mode, each field either a fixed value or an LLM prompt. |
| quickMenuConfig | object | 否 | Authoring config for QUICK\_MENU tools. Structured JSON describing the persistent input-bar menu rendered by the web chat only: layout (grid / list), default open state, and 2-6 items each carrying a d... |
| category | string (enum: knowledge\_base, web\_search, web\_fetch, code\_execution, file\_processing, image\_video\_generation, database\_query, third\_party\_integration, browser\_operation, agent\_collaboration, other) | 否 | `knowledge_base`: Knowledge base retrieval ; `web_search`: Web search ; `web_fetch`: Web page fetch ; `code_execution`: Code execution ; `file_processing`: File processing ; `image_video_generation`: ... |
| displayCopyByLocale | object | 否 | |
| outputRenderTemplateByLocale | object | 否 | |
| toolDisplayMode | object | 否 | |
| groups | array\[IdName] | 否 | Groups this tool is assigned to. Non-owner members must pick at least one group they belong to. |
**請求結構範例**
```typescript
{
"name"?: // 可能有不同的類型 (非必填)
string // Tool name may only contain letters, digits, underscores (_) and hyphens (-). Not required for MCP tools; for API tools it is the tool name given to the LLM. (非必填)
"displayName": string // A name with any characters, used by users for configuration and management.
"description"?: string // Tool description shown to users. Not required for MCP tools. (非必填)
"prompt"?: string // Tool description/prompt given to the LLM. If empty, the description field is used. Not required for MCP tools. (非必填)
"toolType"?: string (enum: api, function, mcp, desktop, flex, quick_reply, quick_menu) // * `api` - API
* `function` - Function
* `mcp` - MCP
* `desktop` - Desktop
* `flex` - Flex Message
* `quick_reply` - Quick Reply
* `quick_menu` - Quick Menu (非必填)
"apiUrl"?: string // 非必填
"httpMethod"?: // 可能有不同的類型 (非必填)
string (enum: get, post, put, delete, patch) // 非必填
"rawHeaders"?: object // 非必填
"sensitiveHeaders"?: [ // 非必填
string
]
"rawQueryParams"?: object // Query string parameters appended to every request of this API tool. Values support the same {{variable}} template rendering as raw_headers. On key collision with LLM-generated arguments, these values win — use this field for API keys that must travel in the query string. (非必填)
"rawParametersSchema"?: object // 非必填
"functionCode"?: string // 非必填
"mcpUrl"?: string // 非必填
"mcpRegistry"?: string (uuid) // Registry backing this MCP tool. Null for manual-URL MCP tools. (非必填)
"mcpAllowedTools"?: object // 非必填
"rawMcpHeader"?: object // Default headers used when the Contact has no matching MCP Credential. (非必填)
"authSubject"?: // Shared uses the tool level token plus per contact credentials; contact requires per contact authentication only; caller mints a short-lived token for the conversation-bound member (falls back to per contact credentials when the conversation has no bound member). MCP tools only.
* `shared` - Shared
* `contact` - Contact
* `caller` - Caller (非必填)
{
}
"flexTemplateJson"?: object // FlexMessage JSON template. Required for FLEX_MESSAGE tools. Stores the full LINE FlexMessage JSON structure (bubble / carousel / box / text / image / button etc.). (非必填)
"flexSchema"?: object // AI dynamic field schema for FlexMessage. JSON object whose keys are field paths parsed from flex_template_json (e.g. text / image url / button label / button uri / button message). Each value may be either a plain string (the AI prompt) or an object carrying additional metadata such as a field tag, e.g. {"prompt": "...", "tag": "title"}. Empty values fall back to the template default. (非必填)
"quickReplyConfig"?: object // Authoring config for QUICK_REPLY tools. Structured JSON describing the chip buttons: static list or dynamic (LLM-generated) mode, each field either a fixed value or an LLM prompt. (非必填)
"quickMenuConfig"?: object // Authoring config for QUICK_MENU tools. Structured JSON describing the persistent input-bar menu rendered by the web chat only: layout (grid / list), default open state, and 2-6 items each carrying a display label plus an action payload (send prompt / prefill text / open http(s) link). (非必填)
"category"?: string (enum: knowledge_base, web_search, web_fetch, code_execution, file_processing, image_video_generation, database_query, third_party_integration, browser_operation, agent_collaboration, other) // * `knowledge_base` - Knowledge base retrieval
* `web_search` - Web search
* `web_fetch` - Web page fetch
* `code_execution` - Code execution
* `file_processing` - File processing
* `image_video_generation` - Image/video generation
* `database_query` - Database query
* `third_party_integration` - Third-party integration
* `browser_operation` - Browser operation
* `agent_collaboration` - Agent collaboration
* `other` - Other (catch-all) (非必填)
"displayCopyByLocale"?: object // 非必填
"outputRenderTemplateByLocale"?: object // 非必填
"toolDisplayMode"?: // 可能有不同的類型 (非必填)
string (enum: full, compact, hidden) // 非必填
"groups"?: [ // Groups this tool is assigned to. Non-owner members must pick at least one group they belong to. (非必填)
{
"id": string (uuid)
}
]
}
```
**請求範例值**
```json
{
"name": null,
"displayName": "範例字串",
"description": "範例字串",
"prompt": "範例字串",
"toolType": "api",
"apiUrl": "範例字串",
"httpMethod": null,
"rawHeaders": null,
"sensitiveHeaders": [
"範例字串"
],
"rawQueryParams": null,
"rawParametersSchema": null,
"functionCode": "範例字串",
"mcpUrl": "範例字串",
"mcpRegistry": "550e8400-e29b-41d4-a716-446655440000",
"mcpAllowedTools": null,
"rawMcpHeader": null,
"authSubject": {},
"flexTemplateJson": null,
"flexSchema": null,
"quickReplyConfig": null,
"quickMenuConfig": null,
"category": "knowledge_base",
"displayCopyByLocale": null,
"outputRenderTemplateByLocale": null,
"toolDisplayMode": null,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
]
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": null,
"displayName": "範例字串",
"description": "範例字串",
"prompt": "範例字串",
"toolType": "api",
"apiUrl": "範例字串",
"httpMethod": null,
"rawHeaders": null,
"sensitiveHeaders": [
"範例字串"
],
"rawQueryParams": null,
"rawParametersSchema": null,
"functionCode": "範例字串",
"mcpUrl": "範例字串",
"mcpRegistry": "550e8400-e29b-41d4-a716-446655440000",
"mcpAllowedTools": null,
"rawMcpHeader": null,
"authSubject": {},
"flexTemplateJson": null,
"flexSchema": null,
"quickReplyConfig": null,
"quickMenuConfig": null,
"category": "knowledge_base",
"displayCopyByLocale": null,
"outputRenderTemplateByLocale": null,
"toolDisplayMode": null,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
]
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"name": null,
"displayName": "範例字串",
"description": "範例字串",
"prompt": "範例字串",
"toolType": "api",
"apiUrl": "範例字串",
"httpMethod": null,
"rawHeaders": null,
"sensitiveHeaders": [
"範例字串"
],
"rawQueryParams": null,
"rawParametersSchema": null,
"functionCode": "範例字串",
"mcpUrl": "範例字串",
"mcpRegistry": "550e8400-e29b-41d4-a716-446655440000",
"mcpAllowedTools": null,
"rawMcpHeader": null,
"authSubject": {},
"flexTemplateJson": null,
"flexSchema": null,
"quickReplyConfig": null,
"quickMenuConfig": null,
"category": "knowledge_base",
"displayCopyByLocale": null,
"outputRenderTemplateByLocale": null,
"toolDisplayMode": null,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
]
};
axios.put("https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"name": None,
"displayName": "範例字串",
"description": "範例字串",
"prompt": "範例字串",
"toolType": "api",
"apiUrl": "範例字串",
"httpMethod": None,
"rawHeaders": None,
"sensitiveHeaders": [
"範例字串"
],
"rawQueryParams": None,
"rawParametersSchema": None,
"functionCode": "範例字串",
"mcpUrl": "範例字串",
"mcpRegistry": "550e8400-e29b-41d4-a716-446655440000",
"mcpAllowedTools": None,
"rawMcpHeader": None,
"authSubject": {},
"flexTemplateJson": None,
"flexSchema": None,
"quickReplyConfig": None,
"quickMenuConfig": None,
"category": "knowledge_base",
"displayCopyByLocale": None,
"outputRenderTemplateByLocale": None,
"toolDisplayMode": None,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
]
}
response = requests.put(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
put("https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'name' => null,
'displayName' => '範例字串',
'description' => '範例字串',
'prompt' => '範例字串',
'toolType' => 'api',
'apiUrl' => '範例字串',
'httpMethod' => null,
'rawHeaders' => null,
'sensitiveHeaders' => [
'範例字串'
],
'rawQueryParams' => null,
'rawParametersSchema' => null,
'functionCode' => '範例字串',
'mcpUrl' => '範例字串',
'mcpRegistry' => '550e8400-e29b-41d4-a716-446655440000',
'mcpAllowedTools' => null,
'rawMcpHeader' => null,
'authSubject' => new \stdClass(),
'flexTemplateJson' => null,
'flexSchema' => null,
'quickReplyConfig' => null,
'quickMenuConfig' => null,
'category' => 'knowledge_base',
'displayCopyByLocale' => null,
'outputRenderTemplateByLocale' => null,
'toolDisplayMode' => null,
'groups' => [
[
'id' => '550e8400-e29b-41d4-a716-446655440000'
]
]
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"name"?: // 可能有不同的類型 (非必填)
string // Tool name may only contain letters, digits, underscores (_) and hyphens (-). Not required for MCP tools; for API tools it is the tool name given to the LLM. (非必填)
"displayName": string // A name with any characters, used by users for configuration and management.
"description"?: string // Tool description shown to users. Not required for MCP tools. (非必填)
"prompt"?: string // Tool description/prompt given to the LLM. If empty, the description field is used. Not required for MCP tools. (非必填)
"toolType"?: string (enum: api, function, mcp, desktop, flex, quick_reply, quick_menu) // * `api` - API
* `function` - Function
* `mcp` - MCP
* `desktop` - Desktop
* `flex` - Flex Message
* `quick_reply` - Quick Reply
* `quick_menu` - Quick Menu (非必填)
"apiUrl"?: string // 非必填
"httpMethod"?: // 可能有不同的類型 (非必填)
string (enum: get, post, put, delete, patch) // 非必填
"rawHeaders"?: object // 非必填
"rawHeadersMasked": object
"sensitiveHeaders"?: [ // 非必填
string
]
"globalSensitiveHeaders": [ // Expose platform defaults as read-only authoring guidance.
string
]
"rawQueryParams"?: object // Query string parameters appended to every request of this API tool. Values support the same {{variable}} template rendering as raw_headers. On key collision with LLM-generated arguments, these values win — use this field for API keys that must travel in the query string. (非必填)
"rawQueryParamsMasked": object
"rawParametersSchema"?: object // 非必填
"functionCode"?: string // 非必填
"organization": string (uuid)
"createdBy": string (uuid)
"isGlobal": boolean // If set as global tool, all organizations can use this tool
"mcpUrl"?: string // 非必填
"mcpRegistry"?: string (uuid) // Registry backing this MCP tool. Null for manual-URL MCP tools. (非必填)
"mcpAllowedTools"?: object // 非必填
"rawMcpHeader"?: object // Default headers used when the Contact has no matching MCP Credential. (非必填)
"rawMcpHeaderMasked": object
"authSubject"?: // Shared uses the tool level token plus per contact credentials; contact requires per contact authentication only; caller mints a short-lived token for the conversation-bound member (falls back to per contact credentials when the conversation has no bound member). MCP tools only.
* `shared` - Shared
* `contact` - Contact
* `caller` - Caller (非必填)
{
}
"flexTemplateJson"?: object // FlexMessage JSON template. Required for FLEX_MESSAGE tools. Stores the full LINE FlexMessage JSON structure (bubble / carousel / box / text / image / button etc.). (非必填)
"flexSchema"?: object // AI dynamic field schema for FlexMessage. JSON object whose keys are field paths parsed from flex_template_json (e.g. text / image url / button label / button uri / button message). Each value may be either a plain string (the AI prompt) or an object carrying additional metadata such as a field tag, e.g. {"prompt": "...", "tag": "title"}. Empty values fall back to the template default. (非必填)
"quickReplyConfig"?: object // Authoring config for QUICK_REPLY tools. Structured JSON describing the chip buttons: static list or dynamic (LLM-generated) mode, each field either a fixed value or an LLM prompt. (非必填)
"quickMenuConfig"?: object // Authoring config for QUICK_MENU tools. Structured JSON describing the persistent input-bar menu rendered by the web chat only: layout (grid / list), default open state, and 2-6 items each carrying a display label plus an action payload (send prompt / prefill text / open http(s) link). (非必填)
"category"?: string (enum: knowledge_base, web_search, web_fetch, code_execution, file_processing, image_video_generation, database_query, third_party_integration, browser_operation, agent_collaboration, other) // * `knowledge_base` - Knowledge base retrieval
* `web_search` - Web search
* `web_fetch` - Web page fetch
* `code_execution` - Code execution
* `file_processing` - File processing
* `image_video_generation` - Image/video generation
* `database_query` - Database query
* `third_party_integration` - Third-party integration
* `browser_operation` - Browser operation
* `agent_collaboration` - Agent collaboration
* `other` - Other (catch-all) (非必填)
"displayCopyByLocale"?: object // 非必填
"outputRenderTemplateByLocale"?: object // 非必填
"toolDisplayMode"?: // 可能有不同的類型 (非必填)
string (enum: full, compact, hidden) // 非必填
"groups"?: [ // Groups this tool is assigned to. Non-owner members must pick at least one group they belong to. (非必填)
{
"id": string (uuid)
"name": string
}
]
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
"canUpdate": boolean // Return whether the current user can update this resource.
"canDelete": boolean // Return whether the current user can delete this resource.
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"displayName": "回應字串",
"description": "回應字串",
"prompt": "回應字串",
"toolType": "api",
"apiUrl": "回應字串",
"httpMethod": "get",
"rawHeaders": null,
"rawHeadersMasked": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"sensitiveHeaders": [
"回應字串"
],
"globalSensitiveHeaders": [
"回應字串"
],
"rawQueryParams": null,
"rawQueryParamsMasked": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"rawParametersSchema": null,
"functionCode": "回應字串",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"createdBy": "550e8400-e29b-41d4-a716-446655440000",
"isGlobal": false,
"mcpUrl": "回應字串",
"mcpRegistry": "550e8400-e29b-41d4-a716-446655440000",
"mcpAllowedTools": null,
"rawMcpHeader": null,
"rawMcpHeaderMasked": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"authSubject": {},
"flexTemplateJson": null,
"flexSchema": null,
"quickReplyConfig": null,
"quickMenuConfig": null,
"category": "knowledge_base",
"displayCopyByLocale": null,
"outputRenderTemplateByLocale": null,
"toolDisplayMode": "full",
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"createdAt": "回應字串",
"updatedAt": "回應字串",
"canUpdate": false,
"canDelete": false
}
```
***
### 部分更新工具
PATCH `/api/v1/tools/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ------------------------------------ |
| `id` | ✅ | string | A UUID string identifying this Tool. |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | object | 否 | Tool name may only contain letters, digits, underscores (\_) and hyphens (-). Not required for MCP tools; for API tools it is the tool name given to the LLM. |
| displayName | string | 否 | A name with any characters, used by users for configuration and management. |
| description | string | 否 | Tool description shown to users. Not required for MCP tools. |
| prompt | string | 否 | Tool description/prompt given to the LLM. If empty, the description field is used. Not required for MCP tools. |
| toolType | string (enum: api, function, mcp, desktop, flex, quick\_reply, quick\_menu) | 否 | `api`: API ; `function`: Function ; `mcp`: MCP ; `desktop`: Desktop ; `flex`: Flex Message ; `quick_reply`: Quick Reply ; `quick_menu`: Quick Menu; |
| apiUrl | string | 否 | |
| httpMethod | object | 否 | |
| rawHeaders | object | 否 | |
| sensitiveHeaders | array\[string] | 否 | |
| rawQueryParams | object | 否 | Query string parameters appended to every request of this API tool. Values support the same {{variable}} template rendering as raw\_headers. On key collision with LLM-generated arguments, these values ... |
| rawParametersSchema | object | 否 | |
| functionCode | string | 否 | |
| mcpUrl | string | 否 | |
| mcpRegistry | string (uuid) | 否 | Registry backing this MCP tool. Null for manual-URL MCP tools. |
| mcpAllowedTools | object | 否 | |
| rawMcpHeader | object | 否 | Default headers used when the Contact has no matching MCP Credential. |
| authSubject | object | 否 | Shared uses the tool level token plus per contact credentials; contact requires per contact authentication only; caller mints a short-lived token for the conversation-bound member (falls back to per c... |
| flexTemplateJson | object | 否 | FlexMessage JSON template. Required for FLEX\_MESSAGE tools. Stores the full LINE FlexMessage JSON structure (bubble / carousel / box / text / image / button etc.). |
| flexSchema | object | 否 | AI dynamic field schema for FlexMessage. JSON object whose keys are field paths parsed from flex\_template\_json (e.g. text / image url / button label / button uri / button message). Each value may be e... |
| quickReplyConfig | object | 否 | Authoring config for QUICK\_REPLY tools. Structured JSON describing the chip buttons: static list or dynamic (LLM-generated) mode, each field either a fixed value or an LLM prompt. |
| quickMenuConfig | object | 否 | Authoring config for QUICK\_MENU tools. Structured JSON describing the persistent input-bar menu rendered by the web chat only: layout (grid / list), default open state, and 2-6 items each carrying a d... |
| category | string (enum: knowledge\_base, web\_search, web\_fetch, code\_execution, file\_processing, image\_video\_generation, database\_query, third\_party\_integration, browser\_operation, agent\_collaboration, other) | 否 | `knowledge_base`: Knowledge base retrieval ; `web_search`: Web search ; `web_fetch`: Web page fetch ; `code_execution`: Code execution ; `file_processing`: File processing ; `image_video_generation`: ... |
| displayCopyByLocale | object | 否 | |
| outputRenderTemplateByLocale | object | 否 | |
| toolDisplayMode | object | 否 | |
| groups | array\[IdName] | 否 | Groups this tool is assigned to. Non-owner members must pick at least one group they belong to. |
**請求結構範例**
```typescript
{
"name"?: // 可能有不同的類型 (非必填)
string // Tool name may only contain letters, digits, underscores (_) and hyphens (-). Not required for MCP tools; for API tools it is the tool name given to the LLM. (非必填)
"displayName"?: string // A name with any characters, used by users for configuration and management. (非必填)
"description"?: string // Tool description shown to users. Not required for MCP tools. (非必填)
"prompt"?: string // Tool description/prompt given to the LLM. If empty, the description field is used. Not required for MCP tools. (非必填)
"toolType"?: string (enum: api, function, mcp, desktop, flex, quick_reply, quick_menu) // * `api` - API
* `function` - Function
* `mcp` - MCP
* `desktop` - Desktop
* `flex` - Flex Message
* `quick_reply` - Quick Reply
* `quick_menu` - Quick Menu (非必填)
"apiUrl"?: string // 非必填
"httpMethod"?: // 可能有不同的類型 (非必填)
string (enum: get, post, put, delete, patch) // 非必填
"rawHeaders"?: object // 非必填
"sensitiveHeaders"?: [ // 非必填
string
]
"rawQueryParams"?: object // Query string parameters appended to every request of this API tool. Values support the same {{variable}} template rendering as raw_headers. On key collision with LLM-generated arguments, these values win — use this field for API keys that must travel in the query string. (非必填)
"rawParametersSchema"?: object // 非必填
"functionCode"?: string // 非必填
"mcpUrl"?: string // 非必填
"mcpRegistry"?: string (uuid) // Registry backing this MCP tool. Null for manual-URL MCP tools. (非必填)
"mcpAllowedTools"?: object // 非必填
"rawMcpHeader"?: object // Default headers used when the Contact has no matching MCP Credential. (非必填)
"authSubject"?: // Shared uses the tool level token plus per contact credentials; contact requires per contact authentication only; caller mints a short-lived token for the conversation-bound member (falls back to per contact credentials when the conversation has no bound member). MCP tools only.
* `shared` - Shared
* `contact` - Contact
* `caller` - Caller (非必填)
{
}
"flexTemplateJson"?: object // FlexMessage JSON template. Required for FLEX_MESSAGE tools. Stores the full LINE FlexMessage JSON structure (bubble / carousel / box / text / image / button etc.). (非必填)
"flexSchema"?: object // AI dynamic field schema for FlexMessage. JSON object whose keys are field paths parsed from flex_template_json (e.g. text / image url / button label / button uri / button message). Each value may be either a plain string (the AI prompt) or an object carrying additional metadata such as a field tag, e.g. {"prompt": "...", "tag": "title"}. Empty values fall back to the template default. (非必填)
"quickReplyConfig"?: object // Authoring config for QUICK_REPLY tools. Structured JSON describing the chip buttons: static list or dynamic (LLM-generated) mode, each field either a fixed value or an LLM prompt. (非必填)
"quickMenuConfig"?: object // Authoring config for QUICK_MENU tools. Structured JSON describing the persistent input-bar menu rendered by the web chat only: layout (grid / list), default open state, and 2-6 items each carrying a display label plus an action payload (send prompt / prefill text / open http(s) link). (非必填)
"category"?: string (enum: knowledge_base, web_search, web_fetch, code_execution, file_processing, image_video_generation, database_query, third_party_integration, browser_operation, agent_collaboration, other) // * `knowledge_base` - Knowledge base retrieval
* `web_search` - Web search
* `web_fetch` - Web page fetch
* `code_execution` - Code execution
* `file_processing` - File processing
* `image_video_generation` - Image/video generation
* `database_query` - Database query
* `third_party_integration` - Third-party integration
* `browser_operation` - Browser operation
* `agent_collaboration` - Agent collaboration
* `other` - Other (catch-all) (非必填)
"displayCopyByLocale"?: object // 非必填
"outputRenderTemplateByLocale"?: object // 非必填
"toolDisplayMode"?: // 可能有不同的類型 (非必填)
string (enum: full, compact, hidden) // 非必填
"groups"?: [ // Groups this tool is assigned to. Non-owner members must pick at least one group they belong to. (非必填)
{
"id": string (uuid)
}
]
}
```
**請求範例值**
```json
{
"name": null,
"displayName": "範例字串",
"description": "範例字串",
"prompt": "範例字串",
"toolType": "api",
"apiUrl": "範例字串",
"httpMethod": null,
"rawHeaders": null,
"sensitiveHeaders": [
"範例字串"
],
"rawQueryParams": null,
"rawParametersSchema": null,
"functionCode": "範例字串",
"mcpUrl": "範例字串",
"mcpRegistry": "550e8400-e29b-41d4-a716-446655440000",
"mcpAllowedTools": null,
"rawMcpHeader": null,
"authSubject": {},
"flexTemplateJson": null,
"flexSchema": null,
"quickReplyConfig": null,
"quickMenuConfig": null,
"category": "knowledge_base",
"displayCopyByLocale": null,
"outputRenderTemplateByLocale": null,
"toolDisplayMode": null,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
]
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": null,
"displayName": "範例字串",
"description": "範例字串",
"prompt": "範例字串",
"toolType": "api",
"apiUrl": "範例字串",
"httpMethod": null,
"rawHeaders": null,
"sensitiveHeaders": [
"範例字串"
],
"rawQueryParams": null,
"rawParametersSchema": null,
"functionCode": "範例字串",
"mcpUrl": "範例字串",
"mcpRegistry": "550e8400-e29b-41d4-a716-446655440000",
"mcpAllowedTools": null,
"rawMcpHeader": null,
"authSubject": {},
"flexTemplateJson": null,
"flexSchema": null,
"quickReplyConfig": null,
"quickMenuConfig": null,
"category": "knowledge_base",
"displayCopyByLocale": null,
"outputRenderTemplateByLocale": null,
"toolDisplayMode": null,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
]
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"name": null,
"displayName": "範例字串",
"description": "範例字串",
"prompt": "範例字串",
"toolType": "api",
"apiUrl": "範例字串",
"httpMethod": null,
"rawHeaders": null,
"sensitiveHeaders": [
"範例字串"
],
"rawQueryParams": null,
"rawParametersSchema": null,
"functionCode": "範例字串",
"mcpUrl": "範例字串",
"mcpRegistry": "550e8400-e29b-41d4-a716-446655440000",
"mcpAllowedTools": null,
"rawMcpHeader": null,
"authSubject": {},
"flexTemplateJson": null,
"flexSchema": null,
"quickReplyConfig": null,
"quickMenuConfig": null,
"category": "knowledge_base",
"displayCopyByLocale": null,
"outputRenderTemplateByLocale": null,
"toolDisplayMode": null,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
]
};
axios.patch("https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"name": None,
"displayName": "範例字串",
"description": "範例字串",
"prompt": "範例字串",
"toolType": "api",
"apiUrl": "範例字串",
"httpMethod": None,
"rawHeaders": None,
"sensitiveHeaders": [
"範例字串"
],
"rawQueryParams": None,
"rawParametersSchema": None,
"functionCode": "範例字串",
"mcpUrl": "範例字串",
"mcpRegistry": "550e8400-e29b-41d4-a716-446655440000",
"mcpAllowedTools": None,
"rawMcpHeader": None,
"authSubject": {},
"flexTemplateJson": None,
"flexSchema": None,
"quickReplyConfig": None,
"quickMenuConfig": None,
"category": "knowledge_base",
"displayCopyByLocale": None,
"outputRenderTemplateByLocale": None,
"toolDisplayMode": None,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000"
}
]
}
response = requests.patch(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
patch("https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'name' => null,
'displayName' => '範例字串',
'description' => '範例字串',
'prompt' => '範例字串',
'toolType' => 'api',
'apiUrl' => '範例字串',
'httpMethod' => null,
'rawHeaders' => null,
'sensitiveHeaders' => [
'範例字串'
],
'rawQueryParams' => null,
'rawParametersSchema' => null,
'functionCode' => '範例字串',
'mcpUrl' => '範例字串',
'mcpRegistry' => '550e8400-e29b-41d4-a716-446655440000',
'mcpAllowedTools' => null,
'rawMcpHeader' => null,
'authSubject' => new \stdClass(),
'flexTemplateJson' => null,
'flexSchema' => null,
'quickReplyConfig' => null,
'quickMenuConfig' => null,
'category' => 'knowledge_base',
'displayCopyByLocale' => null,
'outputRenderTemplateByLocale' => null,
'toolDisplayMode' => null,
'groups' => [
[
'id' => '550e8400-e29b-41d4-a716-446655440000'
]
]
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"name"?: // 可能有不同的類型 (非必填)
string // Tool name may only contain letters, digits, underscores (_) and hyphens (-). Not required for MCP tools; for API tools it is the tool name given to the LLM. (非必填)
"displayName": string // A name with any characters, used by users for configuration and management.
"description"?: string // Tool description shown to users. Not required for MCP tools. (非必填)
"prompt"?: string // Tool description/prompt given to the LLM. If empty, the description field is used. Not required for MCP tools. (非必填)
"toolType"?: string (enum: api, function, mcp, desktop, flex, quick_reply, quick_menu) // * `api` - API
* `function` - Function
* `mcp` - MCP
* `desktop` - Desktop
* `flex` - Flex Message
* `quick_reply` - Quick Reply
* `quick_menu` - Quick Menu (非必填)
"apiUrl"?: string // 非必填
"httpMethod"?: // 可能有不同的類型 (非必填)
string (enum: get, post, put, delete, patch) // 非必填
"rawHeaders"?: object // 非必填
"rawHeadersMasked": object
"sensitiveHeaders"?: [ // 非必填
string
]
"globalSensitiveHeaders": [ // Expose platform defaults as read-only authoring guidance.
string
]
"rawQueryParams"?: object // Query string parameters appended to every request of this API tool. Values support the same {{variable}} template rendering as raw_headers. On key collision with LLM-generated arguments, these values win — use this field for API keys that must travel in the query string. (非必填)
"rawQueryParamsMasked": object
"rawParametersSchema"?: object // 非必填
"functionCode"?: string // 非必填
"organization": string (uuid)
"createdBy": string (uuid)
"isGlobal": boolean // If set as global tool, all organizations can use this tool
"mcpUrl"?: string // 非必填
"mcpRegistry"?: string (uuid) // Registry backing this MCP tool. Null for manual-URL MCP tools. (非必填)
"mcpAllowedTools"?: object // 非必填
"rawMcpHeader"?: object // Default headers used when the Contact has no matching MCP Credential. (非必填)
"rawMcpHeaderMasked": object
"authSubject"?: // Shared uses the tool level token plus per contact credentials; contact requires per contact authentication only; caller mints a short-lived token for the conversation-bound member (falls back to per contact credentials when the conversation has no bound member). MCP tools only.
* `shared` - Shared
* `contact` - Contact
* `caller` - Caller (非必填)
{
}
"flexTemplateJson"?: object // FlexMessage JSON template. Required for FLEX_MESSAGE tools. Stores the full LINE FlexMessage JSON structure (bubble / carousel / box / text / image / button etc.). (非必填)
"flexSchema"?: object // AI dynamic field schema for FlexMessage. JSON object whose keys are field paths parsed from flex_template_json (e.g. text / image url / button label / button uri / button message). Each value may be either a plain string (the AI prompt) or an object carrying additional metadata such as a field tag, e.g. {"prompt": "...", "tag": "title"}. Empty values fall back to the template default. (非必填)
"quickReplyConfig"?: object // Authoring config for QUICK_REPLY tools. Structured JSON describing the chip buttons: static list or dynamic (LLM-generated) mode, each field either a fixed value or an LLM prompt. (非必填)
"quickMenuConfig"?: object // Authoring config for QUICK_MENU tools. Structured JSON describing the persistent input-bar menu rendered by the web chat only: layout (grid / list), default open state, and 2-6 items each carrying a display label plus an action payload (send prompt / prefill text / open http(s) link). (非必填)
"category"?: string (enum: knowledge_base, web_search, web_fetch, code_execution, file_processing, image_video_generation, database_query, third_party_integration, browser_operation, agent_collaboration, other) // * `knowledge_base` - Knowledge base retrieval
* `web_search` - Web search
* `web_fetch` - Web page fetch
* `code_execution` - Code execution
* `file_processing` - File processing
* `image_video_generation` - Image/video generation
* `database_query` - Database query
* `third_party_integration` - Third-party integration
* `browser_operation` - Browser operation
* `agent_collaboration` - Agent collaboration
* `other` - Other (catch-all) (非必填)
"displayCopyByLocale"?: object // 非必填
"outputRenderTemplateByLocale"?: object // 非必填
"toolDisplayMode"?: // 可能有不同的類型 (非必填)
string (enum: full, compact, hidden) // 非必填
"groups"?: [ // Groups this tool is assigned to. Non-owner members must pick at least one group they belong to. (非必填)
{
"id": string (uuid)
"name": string
}
]
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
"canUpdate": boolean // Return whether the current user can update this resource.
"canDelete": boolean // Return whether the current user can delete this resource.
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"displayName": "回應字串",
"description": "回應字串",
"prompt": "回應字串",
"toolType": "api",
"apiUrl": "回應字串",
"httpMethod": "get",
"rawHeaders": null,
"rawHeadersMasked": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"sensitiveHeaders": [
"回應字串"
],
"globalSensitiveHeaders": [
"回應字串"
],
"rawQueryParams": null,
"rawQueryParamsMasked": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"rawParametersSchema": null,
"functionCode": "回應字串",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"createdBy": "550e8400-e29b-41d4-a716-446655440000",
"isGlobal": false,
"mcpUrl": "回應字串",
"mcpRegistry": "550e8400-e29b-41d4-a716-446655440000",
"mcpAllowedTools": null,
"rawMcpHeader": null,
"rawMcpHeaderMasked": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"authSubject": {},
"flexTemplateJson": null,
"flexSchema": null,
"quickReplyConfig": null,
"quickMenuConfig": null,
"category": "knowledge_base",
"displayCopyByLocale": null,
"outputRenderTemplateByLocale": null,
"toolDisplayMode": "full",
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"createdAt": "回應字串",
"updatedAt": "回應字串",
"canUpdate": false,
"canDelete": false
}
```
***
### 刪除工具
DELETE `/api/v1/tools/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ------------------------------------ |
| `id` | ✅ | string | A UUID string identifying this Tool. |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// 請求內容 (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ---------------- |
| 204 | No response body |
***
### 列出可用工具
GET `/api/v1/tools/available-tools/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ----------------- | -- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `availableTools` | ✅ | array | 所有可用的MCP工具列表 |
| `error` | ✅ | | 取得工具失敗的原因：{code, message}；code 為 url\_rejected／invalid\_header／dns\_error／connect\_error／tls\_error／auth\_error／timeout\_error／handshake\_error／unknown\_error。連線成功（含伺服器沒有工具）時為 null；已棄用的 GET 入口一律為 null |
| `mcpAllowedTools` | ❌ | array | MCP 允許使用的工具列表 |
| `mcpUrl` | ✅ | string | MCP 伺服器 URL（必填） |
| `rawMcpHeader` | ❌ | | MCP Header（JSON 格式） |
| `toolId` | ❌ | string | Tool ID for per-member OAuth token lookup |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/tools/available-tools/?availableTools=example&error=example&mcpAllowedTools=example&mcpUrl=example&rawMcpHeader=example&toolId=550e8400-e29b-41d4-a716-446655440000" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/tools/available-tools/?availableTools=example&error=example&mcpAllowedTools=example&mcpUrl=example&rawMcpHeader=example&toolId=550e8400-e29b-41d4-a716-446655440000", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/tools/available-tools/?availableTools=example&error=example&mcpAllowedTools=example&mcpUrl=example&rawMcpHeader=example&toolId=550e8400-e29b-41d4-a716-446655440000"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/tools/available-tools/?availableTools=example&error=example&mcpAllowedTools=example&mcpUrl=example&rawMcpHeader=example&toolId=550e8400-e29b-41d4-a716-446655440000", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"mcpUrl": string // MCP 伺服器 URL（必填）
"rawMcpHeader"?: object // MCP Header（JSON 格式） (非必填)
"mcpAllowedTools"?: [ // MCP 允許使用的工具列表 (非必填)
string
]
"toolId"?: string (uuid) // Tool ID for per-member OAuth token lookup (非必填)
"availableTools": [ // 所有可用的MCP工具列表
string
]
"error": // 取得工具失敗的原因：{code, message}；code 為 url_rejected／invalid_header／dns_error／connect_error／tls_error／auth_error／timeout_error／handshake_error／unknown_error。連線成功（含伺服器沒有工具）時為 null；已棄用的 GET 入口一律為 null
{
"code": string // url_rejected / invalid_header / dns_error / connect_error / tls_error / auth_error / timeout_error / handshake_error / unknown_error
"message": string // 依使用者語系翻譯好的原因，可直接顯示
}
}
```
**回應範例值**
```json
{
"mcpUrl": "回應字串",
"rawMcpHeader": null,
"mcpAllowedTools": [
"回應字串"
],
"toolId": "550e8400-e29b-41d4-a716-446655440000",
"availableTools": [
"回應字串"
],
"error": {
"code": "回應字串",
"message": "回應字串"
}
}
```
**狀態碼: 400**
**回應結構範例**
```typescript
{
"detail"?: string // 非必填
}
```
**回應範例值**
```json
{
"detail": "回應字串"
}
```
***
### 建立連接器
POST `/api/v1/connectors/`
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ------------------------------- | ------------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| mcpRegistryId | string (uuid) | 是 | |
| displayName | string | 否 | Custom display name for this connector (defaults to MCP Registry name) |
| description | string | 否 | Custom description for this connector (defaults to MCP Registry description) |
| defaultCategory | object | 否 | Org-level override of the MCP Registry default category for this connector's dynamic tools. Empty = use the MCP Registry default\_category. `knowledge_base`: Knowledge base retrieval ; `web_search`: We... |
| defaultDisplayGroupNameByLocale | object | 否 | Locale-keyed server-level default group headline shown in chat for this connector's dynamic MCP tools (those without an individual Tool row). Shape: {"": str}. The headline for the conversatio... |
| defaultToolIcon | string | 否 | Server-level default icon identifier (a frontend icon key, not an uploaded image) for this connector's dynamic MCP tools. Empty = frontend uses its default MCP icon. Streamed as toolIcon. |
| authHeaders | object | 否 | |
| allowedContextDataKeys | object | 否 | Allowlist of webchat contextData keys this connector may render into auth\_headers through {{context\_data.}}. An empty list disables the feature for this connector: the placeholder is left verbati... |
| exposedMcpTools | object | 否 | Allowlist of MCP tool names this connector exposes (to the agent and to SEP-1865 UI cards). Empty list = expose all of the server tools. Use this to limit a connector to a safe subset (e.g. read-only ... |
| isEnabled | boolean | 否 | Whether this connector is enabled for contacts in the organization |
**請求結構範例**
```typescript
{
"mcpRegistryId": string (uuid)
"displayName"?: string // Custom display name for this connector (defaults to MCP Registry name) (非必填)
"description"?: string // Custom description for this connector (defaults to MCP Registry description) (非必填)
"defaultCategory"?: // 可能有不同的類型 (非必填)
string (enum: knowledge_base, web_search, web_fetch, code_execution, file_processing, image_video_generation, database_query, third_party_integration, browser_operation, agent_collaboration, other) // Org-level override of the MCP Registry default category for this connector's dynamic tools. Empty = use the MCP Registry default_category.
* `knowledge_base` - Knowledge base retrieval
* `web_search` - Web search
* `web_fetch` - Web page fetch
* `code_execution` - Code execution
* `file_processing` - File processing
* `image_video_generation` - Image/video generation
* `database_query` - Database query
* `third_party_integration` - Third-party integration
* `browser_operation` - Browser operation
* `agent_collaboration` - Agent collaboration
* `other` - Other (catch-all) (非必填)
"defaultDisplayGroupNameByLocale"?: object // Locale-keyed server-level default group headline shown in chat for this connector's dynamic MCP tools (those without an individual Tool row). Shape: {"": str}. The headline for the conversation locale is resolved server-side (see whizchat.tools.services.tool_category.resolve_localized_text): requested locale -> settings.LANGUAGE_CODE locale -> empty, then streamed verbatim as displayGroupName. Empty = frontend falls back to its name-based heuristic. An individual Tool row overrides this. (非必填)
"defaultToolIcon"?: string // Server-level default icon identifier (a frontend icon key, not an uploaded image) for this connector's dynamic MCP tools. Empty = frontend uses its default MCP icon. Streamed as toolIcon. (非必填)
"authHeaders"?: object // 非必填
"allowedContextDataKeys"?: object // Allowlist of webchat contextData keys this connector may render into auth_headers through {{context_data.}}. An empty list disables the feature for this connector: the placeholder is left verbatim, exactly as before the feature existed. Keys are matched literally and are case-sensitive; at most 20 keys of letters, digits and underscores. (非必填)
"exposedMcpTools"?: object // Allowlist of MCP tool names this connector exposes (to the agent and to SEP-1865 UI cards). Empty list = expose all of the server tools. Use this to limit a connector to a safe subset (e.g. read-only tools). (非必填)
"isEnabled"?: boolean // Whether this connector is enabled for contacts in the organization (非必填)
}
```
**請求範例值**
```json
{
"mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
"displayName": "範例字串",
"description": "範例字串",
"defaultCategory": null,
"defaultDisplayGroupNameByLocale": null,
"defaultToolIcon": "範例字串",
"authHeaders": null,
"allowedContextDataKeys": null,
"exposedMcpTools": null,
"isEnabled": true
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/connectors/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
"displayName": "範例字串",
"description": "範例字串",
"defaultCategory": null,
"defaultDisplayGroupNameByLocale": null,
"defaultToolIcon": "範例字串",
"authHeaders": null,
"allowedContextDataKeys": null,
"exposedMcpTools": null,
"isEnabled": true
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
"displayName": "範例字串",
"description": "範例字串",
"defaultCategory": null,
"defaultDisplayGroupNameByLocale": null,
"defaultToolIcon": "範例字串",
"authHeaders": null,
"allowedContextDataKeys": null,
"exposedMcpTools": null,
"isEnabled": true
};
axios.post("https://api.maiagent.ai/api/v1/connectors/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/connectors/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
"displayName": "範例字串",
"description": "範例字串",
"defaultCategory": None,
"defaultDisplayGroupNameByLocale": None,
"defaultToolIcon": "範例字串",
"authHeaders": None,
"allowedContextDataKeys": None,
"exposedMcpTools": None,
"isEnabled": True
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/connectors/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'mcpRegistryId' => '550e8400-e29b-41d4-a716-446655440000',
'displayName' => '範例字串',
'description' => '範例字串',
'defaultCategory' => null,
'defaultDisplayGroupNameByLocale' => null,
'defaultToolIcon' => '範例字串',
'authHeaders' => null,
'allowedContextDataKeys' => null,
'exposedMcpTools' => null,
'isEnabled' => true
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
{
"id": string (uuid)
"mcpRegistry":
{
"id": string (uuid)
"name": string // MCP service name (e.g., Supabase, Sentry). Only alphanumeric, underscore and hyphen allowed.
"displayName"?: string // Human-readable display name (defaults to name if empty) (非必填)
"description"?: string // Brief description of the MCP service (非必填)
"remoteMcpUrl": string (uri) // The URL of the Remote MCP service
"oauthServerUrl"?: // 可能有不同的類型 (非必填)
string (uri) // Manual override for the OAuth authorization server URL. Leave empty to auto-discover from the MCP server (RFC 9728 protected resource metadata). Only fill in when auto-discovery fails or the server advertises incorrect metadata. (e.g., Supabase MCP is at mcp.supabase.com but OAuth is at api.supabase.com) (非必填)
"logoUrl": string (uri)
"isActive"?: boolean // Whether this MCP service is currently available for use (非必填)
"isGlobal"?: boolean // Global registries are maintained by the platform and available to all organizations. (非必填)
"authType"?: // How to authenticate with this MCP server.
* `oauth` - OAuth 2.0
* `service_account` - Service Account
* `none` - No Authentication (非必填)
{
}
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
"mcpRegistryId": string (uuid)
"name": string
"displayName"?: string // Custom display name for this connector (defaults to MCP Registry name) (非必填)
"description"?: string // Custom description for this connector (defaults to MCP Registry description) (非必填)
"defaultCategory"?: // 可能有不同的類型 (非必填)
string (enum: knowledge_base, web_search, web_fetch, code_execution, file_processing, image_video_generation, database_query, third_party_integration, browser_operation, agent_collaboration, other) // Org-level override of the MCP Registry default category for this connector's dynamic tools. Empty = use the MCP Registry default_category.
* `knowledge_base` - Knowledge base retrieval
* `web_search` - Web search
* `web_fetch` - Web page fetch
* `code_execution` - Code execution
* `file_processing` - File processing
* `image_video_generation` - Image/video generation
* `database_query` - Database query
* `third_party_integration` - Third-party integration
* `browser_operation` - Browser operation
* `agent_collaboration` - Agent collaboration
* `other` - Other (catch-all) (非必填)
"defaultDisplayGroupNameByLocale"?: object // Locale-keyed server-level default group headline shown in chat for this connector's dynamic MCP tools (those without an individual Tool row). Shape: {"": str}. The headline for the conversation locale is resolved server-side (see whizchat.tools.services.tool_category.resolve_localized_text): requested locale -> settings.LANGUAGE_CODE locale -> empty, then streamed verbatim as displayGroupName. Empty = frontend falls back to its name-based heuristic. An individual Tool row overrides this. (非必填)
"defaultToolIcon"?: string // Server-level default icon identifier (a frontend icon key, not an uploaded image) for this connector's dynamic MCP tools. Empty = frontend uses its default MCP icon. Streamed as toolIcon. (非必填)
"effectiveDescription": string
"remoteMcpUrl": string
"oauthServerUrl": string
"logoUrl": string (uri)
"authType": string
"authHeaders"?: object // 非必填
"authHeadersMasked": object
"allowedContextDataKeys"?: object // Allowlist of webchat contextData keys this connector may render into auth_headers through {{context_data.}}. An empty list disables the feature for this connector: the placeholder is left verbatim, exactly as before the feature existed. Keys are matched literally and are case-sensitive; at most 20 keys of letters, digits and underscores. (非必填)
"exposedMcpTools"?: object // Allowlist of MCP tool names this connector exposes (to the agent and to SEP-1865 UI cards). Empty list = expose all of the server tools. Use this to limit a connector to a safe subset (e.g. read-only tools). (非必填)
"isEnabled"?: boolean // Whether this connector is enabled for contacts in the organization (非必填)
"organization": string (uuid)
"createdBy": string (uuid)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"mcpRegistry": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"displayName": "回應字串",
"description": "回應字串",
"remoteMcpUrl": "https://example.com/file.jpg",
"oauthServerUrl": "https://example.com/file.jpg",
"logoUrl": "https://example.com/file.jpg",
"isActive": false,
"isGlobal": false,
"authType": {},
"createdAt": "回應字串",
"updatedAt": "回應字串"
},
"mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"displayName": "回應字串",
"description": "回應字串",
"defaultCategory": "knowledge_base",
"defaultDisplayGroupNameByLocale": null,
"defaultToolIcon": "回應字串",
"effectiveDescription": "回應字串",
"remoteMcpUrl": "回應字串",
"oauthServerUrl": "回應字串",
"logoUrl": "https://example.com/file.jpg",
"authType": "回應字串",
"authHeaders": null,
"authHeadersMasked": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"allowedContextDataKeys": null,
"exposedMcpTools": null,
"isEnabled": false,
"organization": "550e8400-e29b-41d4-a716-446655440000",
"createdBy": "550e8400-e29b-41d4-a716-446655440000",
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
```
***
### 列出連接器
GET `/api/v1/connectors/`
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/connectors/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/connectors/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/connectors/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/connectors/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
[
{
"id": string (uuid)
"displayName"?: string // Custom display name for this connector (defaults to MCP Registry name) (非必填)
"mcpRegistryName": string
"mcpRegistryId": string
"mcpRegistryIsGlobal": boolean
"logoUrl": string (uri)
"defaultCategory"?: // 可能有不同的類型 (非必填)
string (enum: knowledge_base, web_search, web_fetch, code_execution, file_processing, image_video_generation, database_query, third_party_integration, browser_operation, agent_collaboration, other) // Org-level override of the MCP Registry default category for this connector's dynamic tools. Empty = use the MCP Registry default_category.
* `knowledge_base` - Knowledge base retrieval
* `web_search` - Web search
* `web_fetch` - Web page fetch
* `code_execution` - Code execution
* `file_processing` - File processing
* `image_video_generation` - Image/video generation
* `database_query` - Database query
* `third_party_integration` - Third-party integration
* `browser_operation` - Browser operation
* `agent_collaboration` - Agent collaboration
* `other` - Other (catch-all) (非必填)
"isEnabled"?: boolean // Whether this connector is enabled for contacts in the organization (非必填)
"authHeadersMasked": object
"allowedContextDataKeys": object // Allowlist of webchat contextData keys this connector may render into auth_headers through {{context_data.}}. An empty list disables the feature for this connector: the placeholder is left verbatim, exactly as before the feature existed. Keys are matched literally and are case-sensitive; at most 20 keys of letters, digits and underscores.
"authorizedMembersCount": integer
"createdBy":
{
"id": string (uuid)
"name": string
}
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
```
**回應範例值**
```json
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"displayName": "回應字串",
"mcpRegistryName": "回應字串",
"mcpRegistryId": "回應字串",
"mcpRegistryIsGlobal": false,
"logoUrl": "https://example.com/file.jpg",
"defaultCategory": "knowledge_base",
"isEnabled": false,
"authHeadersMasked": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"allowedContextDataKeys": null,
"authorizedMembersCount": 456,
"createdBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
]
```
***
### 取得特定連接器
GET `/api/v1/connectors/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | -- |
| `id` | ✅ | string | |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/connectors/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/connectors/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/connectors/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/connectors/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"mcpRegistry":
{
"id": string (uuid)
"name": string // MCP service name (e.g., Supabase, Sentry). Only alphanumeric, underscore and hyphen allowed.
"displayName"?: string // Human-readable display name (defaults to name if empty) (非必填)
"description"?: string // Brief description of the MCP service (非必填)
"remoteMcpUrl": string (uri) // The URL of the Remote MCP service
"oauthServerUrl"?: // 可能有不同的類型 (非必填)
string (uri) // Manual override for the OAuth authorization server URL. Leave empty to auto-discover from the MCP server (RFC 9728 protected resource metadata). Only fill in when auto-discovery fails or the server advertises incorrect metadata. (e.g., Supabase MCP is at mcp.supabase.com but OAuth is at api.supabase.com) (非必填)
"logoUrl": string (uri)
"isActive"?: boolean // Whether this MCP service is currently available for use (非必填)
"isGlobal"?: boolean // Global registries are maintained by the platform and available to all organizations. (非必填)
"authType"?: // How to authenticate with this MCP server.
* `oauth` - OAuth 2.0
* `service_account` - Service Account
* `none` - No Authentication (非必填)
{
}
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
"mcpRegistryId": string (uuid)
"name": string
"displayName"?: string // Custom display name for this connector (defaults to MCP Registry name) (非必填)
"description"?: string // Custom description for this connector (defaults to MCP Registry description) (非必填)
"defaultCategory"?: // 可能有不同的類型 (非必填)
string (enum: knowledge_base, web_search, web_fetch, code_execution, file_processing, image_video_generation, database_query, third_party_integration, browser_operation, agent_collaboration, other) // Org-level override of the MCP Registry default category for this connector's dynamic tools. Empty = use the MCP Registry default_category.
* `knowledge_base` - Knowledge base retrieval
* `web_search` - Web search
* `web_fetch` - Web page fetch
* `code_execution` - Code execution
* `file_processing` - File processing
* `image_video_generation` - Image/video generation
* `database_query` - Database query
* `third_party_integration` - Third-party integration
* `browser_operation` - Browser operation
* `agent_collaboration` - Agent collaboration
* `other` - Other (catch-all) (非必填)
"defaultDisplayGroupNameByLocale"?: object // Locale-keyed server-level default group headline shown in chat for this connector's dynamic MCP tools (those without an individual Tool row). Shape: {"": str}. The headline for the conversation locale is resolved server-side (see whizchat.tools.services.tool_category.resolve_localized_text): requested locale -> settings.LANGUAGE_CODE locale -> empty, then streamed verbatim as displayGroupName. Empty = frontend falls back to its name-based heuristic. An individual Tool row overrides this. (非必填)
"defaultToolIcon"?: string // Server-level default icon identifier (a frontend icon key, not an uploaded image) for this connector's dynamic MCP tools. Empty = frontend uses its default MCP icon. Streamed as toolIcon. (非必填)
"effectiveDescription": string
"remoteMcpUrl": string
"oauthServerUrl": string
"logoUrl": string (uri)
"authType": string
"authHeaders"?: object // 非必填
"authHeadersMasked": object
"allowedContextDataKeys"?: object // Allowlist of webchat contextData keys this connector may render into auth_headers through {{context_data.}}. An empty list disables the feature for this connector: the placeholder is left verbatim, exactly as before the feature existed. Keys are matched literally and are case-sensitive; at most 20 keys of letters, digits and underscores. (非必填)
"exposedMcpTools"?: object // Allowlist of MCP tool names this connector exposes (to the agent and to SEP-1865 UI cards). Empty list = expose all of the server tools. Use this to limit a connector to a safe subset (e.g. read-only tools). (非必填)
"isEnabled"?: boolean // Whether this connector is enabled for contacts in the organization (非必填)
"organization": string (uuid)
"createdBy": string (uuid)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"mcpRegistry": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"displayName": "回應字串",
"description": "回應字串",
"remoteMcpUrl": "https://example.com/file.jpg",
"oauthServerUrl": "https://example.com/file.jpg",
"logoUrl": "https://example.com/file.jpg",
"isActive": false,
"isGlobal": false,
"authType": {},
"createdAt": "回應字串",
"updatedAt": "回應字串"
},
"mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"displayName": "回應字串",
"description": "回應字串",
"defaultCategory": "knowledge_base",
"defaultDisplayGroupNameByLocale": null,
"defaultToolIcon": "回應字串",
"effectiveDescription": "回應字串",
"remoteMcpUrl": "回應字串",
"oauthServerUrl": "回應字串",
"logoUrl": "https://example.com/file.jpg",
"authType": "回應字串",
"authHeaders": null,
"authHeadersMasked": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"allowedContextDataKeys": null,
"exposedMcpTools": null,
"isEnabled": false,
"organization": "550e8400-e29b-41d4-a716-446655440000",
"createdBy": "550e8400-e29b-41d4-a716-446655440000",
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
```
***
### 更新連接器
PUT `/api/v1/connectors/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | -- |
| `id` | ✅ | string | |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ------------------------------- | ------------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| mcpRegistryId | string (uuid) | 是 | |
| displayName | string | 否 | Custom display name for this connector (defaults to MCP Registry name) |
| description | string | 否 | Custom description for this connector (defaults to MCP Registry description) |
| defaultCategory | object | 否 | Org-level override of the MCP Registry default category for this connector's dynamic tools. Empty = use the MCP Registry default\_category. `knowledge_base`: Knowledge base retrieval ; `web_search`: We... |
| defaultDisplayGroupNameByLocale | object | 否 | Locale-keyed server-level default group headline shown in chat for this connector's dynamic MCP tools (those without an individual Tool row). Shape: {"": str}. The headline for the conversatio... |
| defaultToolIcon | string | 否 | Server-level default icon identifier (a frontend icon key, not an uploaded image) for this connector's dynamic MCP tools. Empty = frontend uses its default MCP icon. Streamed as toolIcon. |
| authHeaders | object | 否 | |
| allowedContextDataKeys | object | 否 | Allowlist of webchat contextData keys this connector may render into auth\_headers through {{context\_data.}}. An empty list disables the feature for this connector: the placeholder is left verbati... |
| exposedMcpTools | object | 否 | Allowlist of MCP tool names this connector exposes (to the agent and to SEP-1865 UI cards). Empty list = expose all of the server tools. Use this to limit a connector to a safe subset (e.g. read-only ... |
| isEnabled | boolean | 否 | Whether this connector is enabled for contacts in the organization |
**請求結構範例**
```typescript
{
"mcpRegistryId": string (uuid)
"displayName"?: string // Custom display name for this connector (defaults to MCP Registry name) (非必填)
"description"?: string // Custom description for this connector (defaults to MCP Registry description) (非必填)
"defaultCategory"?: // 可能有不同的類型 (非必填)
string (enum: knowledge_base, web_search, web_fetch, code_execution, file_processing, image_video_generation, database_query, third_party_integration, browser_operation, agent_collaboration, other) // Org-level override of the MCP Registry default category for this connector's dynamic tools. Empty = use the MCP Registry default_category.
* `knowledge_base` - Knowledge base retrieval
* `web_search` - Web search
* `web_fetch` - Web page fetch
* `code_execution` - Code execution
* `file_processing` - File processing
* `image_video_generation` - Image/video generation
* `database_query` - Database query
* `third_party_integration` - Third-party integration
* `browser_operation` - Browser operation
* `agent_collaboration` - Agent collaboration
* `other` - Other (catch-all) (非必填)
"defaultDisplayGroupNameByLocale"?: object // Locale-keyed server-level default group headline shown in chat for this connector's dynamic MCP tools (those without an individual Tool row). Shape: {"": str}. The headline for the conversation locale is resolved server-side (see whizchat.tools.services.tool_category.resolve_localized_text): requested locale -> settings.LANGUAGE_CODE locale -> empty, then streamed verbatim as displayGroupName. Empty = frontend falls back to its name-based heuristic. An individual Tool row overrides this. (非必填)
"defaultToolIcon"?: string // Server-level default icon identifier (a frontend icon key, not an uploaded image) for this connector's dynamic MCP tools. Empty = frontend uses its default MCP icon. Streamed as toolIcon. (非必填)
"authHeaders"?: object // 非必填
"allowedContextDataKeys"?: object // Allowlist of webchat contextData keys this connector may render into auth_headers through {{context_data.}}. An empty list disables the feature for this connector: the placeholder is left verbatim, exactly as before the feature existed. Keys are matched literally and are case-sensitive; at most 20 keys of letters, digits and underscores. (非必填)
"exposedMcpTools"?: object // Allowlist of MCP tool names this connector exposes (to the agent and to SEP-1865 UI cards). Empty list = expose all of the server tools. Use this to limit a connector to a safe subset (e.g. read-only tools). (非必填)
"isEnabled"?: boolean // Whether this connector is enabled for contacts in the organization (非必填)
}
```
**請求範例值**
```json
{
"mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
"displayName": "範例字串",
"description": "範例字串",
"defaultCategory": null,
"defaultDisplayGroupNameByLocale": null,
"defaultToolIcon": "範例字串",
"authHeaders": null,
"allowedContextDataKeys": null,
"exposedMcpTools": null,
"isEnabled": true
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/connectors/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
"displayName": "範例字串",
"description": "範例字串",
"defaultCategory": null,
"defaultDisplayGroupNameByLocale": null,
"defaultToolIcon": "範例字串",
"authHeaders": null,
"allowedContextDataKeys": null,
"exposedMcpTools": null,
"isEnabled": true
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
"displayName": "範例字串",
"description": "範例字串",
"defaultCategory": null,
"defaultDisplayGroupNameByLocale": null,
"defaultToolIcon": "範例字串",
"authHeaders": null,
"allowedContextDataKeys": null,
"exposedMcpTools": null,
"isEnabled": true
};
axios.put("https://api.maiagent.ai/api/v1/connectors/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/connectors/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
"displayName": "範例字串",
"description": "範例字串",
"defaultCategory": None,
"defaultDisplayGroupNameByLocale": None,
"defaultToolIcon": "範例字串",
"authHeaders": None,
"allowedContextDataKeys": None,
"exposedMcpTools": None,
"isEnabled": True
}
response = requests.put(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
put("https://api.maiagent.ai/api/v1/connectors/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'mcpRegistryId' => '550e8400-e29b-41d4-a716-446655440000',
'displayName' => '範例字串',
'description' => '範例字串',
'defaultCategory' => null,
'defaultDisplayGroupNameByLocale' => null,
'defaultToolIcon' => '範例字串',
'authHeaders' => null,
'allowedContextDataKeys' => null,
'exposedMcpTools' => null,
'isEnabled' => true
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"mcpRegistry":
{
"id": string (uuid)
"name": string // MCP service name (e.g., Supabase, Sentry). Only alphanumeric, underscore and hyphen allowed.
"displayName"?: string // Human-readable display name (defaults to name if empty) (非必填)
"description"?: string // Brief description of the MCP service (非必填)
"remoteMcpUrl": string (uri) // The URL of the Remote MCP service
"oauthServerUrl"?: // 可能有不同的類型 (非必填)
string (uri) // Manual override for the OAuth authorization server URL. Leave empty to auto-discover from the MCP server (RFC 9728 protected resource metadata). Only fill in when auto-discovery fails or the server advertises incorrect metadata. (e.g., Supabase MCP is at mcp.supabase.com but OAuth is at api.supabase.com) (非必填)
"logoUrl": string (uri)
"isActive"?: boolean // Whether this MCP service is currently available for use (非必填)
"isGlobal"?: boolean // Global registries are maintained by the platform and available to all organizations. (非必填)
"authType"?: // How to authenticate with this MCP server.
* `oauth` - OAuth 2.0
* `service_account` - Service Account
* `none` - No Authentication (非必填)
{
}
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
"mcpRegistryId": string (uuid)
"name": string
"displayName"?: string // Custom display name for this connector (defaults to MCP Registry name) (非必填)
"description"?: string // Custom description for this connector (defaults to MCP Registry description) (非必填)
"defaultCategory"?: // 可能有不同的類型 (非必填)
string (enum: knowledge_base, web_search, web_fetch, code_execution, file_processing, image_video_generation, database_query, third_party_integration, browser_operation, agent_collaboration, other) // Org-level override of the MCP Registry default category for this connector's dynamic tools. Empty = use the MCP Registry default_category.
* `knowledge_base` - Knowledge base retrieval
* `web_search` - Web search
* `web_fetch` - Web page fetch
* `code_execution` - Code execution
* `file_processing` - File processing
* `image_video_generation` - Image/video generation
* `database_query` - Database query
* `third_party_integration` - Third-party integration
* `browser_operation` - Browser operation
* `agent_collaboration` - Agent collaboration
* `other` - Other (catch-all) (非必填)
"defaultDisplayGroupNameByLocale"?: object // Locale-keyed server-level default group headline shown in chat for this connector's dynamic MCP tools (those without an individual Tool row). Shape: {"": str}. The headline for the conversation locale is resolved server-side (see whizchat.tools.services.tool_category.resolve_localized_text): requested locale -> settings.LANGUAGE_CODE locale -> empty, then streamed verbatim as displayGroupName. Empty = frontend falls back to its name-based heuristic. An individual Tool row overrides this. (非必填)
"defaultToolIcon"?: string // Server-level default icon identifier (a frontend icon key, not an uploaded image) for this connector's dynamic MCP tools. Empty = frontend uses its default MCP icon. Streamed as toolIcon. (非必填)
"effectiveDescription": string
"remoteMcpUrl": string
"oauthServerUrl": string
"logoUrl": string (uri)
"authType": string
"authHeaders"?: object // 非必填
"authHeadersMasked": object
"allowedContextDataKeys"?: object // Allowlist of webchat contextData keys this connector may render into auth_headers through {{context_data.}}. An empty list disables the feature for this connector: the placeholder is left verbatim, exactly as before the feature existed. Keys are matched literally and are case-sensitive; at most 20 keys of letters, digits and underscores. (非必填)
"exposedMcpTools"?: object // Allowlist of MCP tool names this connector exposes (to the agent and to SEP-1865 UI cards). Empty list = expose all of the server tools. Use this to limit a connector to a safe subset (e.g. read-only tools). (非必填)
"isEnabled"?: boolean // Whether this connector is enabled for contacts in the organization (非必填)
"organization": string (uuid)
"createdBy": string (uuid)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"mcpRegistry": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"displayName": "回應字串",
"description": "回應字串",
"remoteMcpUrl": "https://example.com/file.jpg",
"oauthServerUrl": "https://example.com/file.jpg",
"logoUrl": "https://example.com/file.jpg",
"isActive": false,
"isGlobal": false,
"authType": {},
"createdAt": "回應字串",
"updatedAt": "回應字串"
},
"mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"displayName": "回應字串",
"description": "回應字串",
"defaultCategory": "knowledge_base",
"defaultDisplayGroupNameByLocale": null,
"defaultToolIcon": "回應字串",
"effectiveDescription": "回應字串",
"remoteMcpUrl": "回應字串",
"oauthServerUrl": "回應字串",
"logoUrl": "https://example.com/file.jpg",
"authType": "回應字串",
"authHeaders": null,
"authHeadersMasked": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"allowedContextDataKeys": null,
"exposedMcpTools": null,
"isEnabled": false,
"organization": "550e8400-e29b-41d4-a716-446655440000",
"createdBy": "550e8400-e29b-41d4-a716-446655440000",
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
```
***
### 部分更新連接器
PATCH `/api/v1/connectors/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | -- |
| `id` | ✅ | string | |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ------------------------------- | ------------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| mcpRegistryId | string (uuid) | 否 | |
| displayName | string | 否 | Custom display name for this connector (defaults to MCP Registry name) |
| description | string | 否 | Custom description for this connector (defaults to MCP Registry description) |
| defaultCategory | object | 否 | Org-level override of the MCP Registry default category for this connector's dynamic tools. Empty = use the MCP Registry default\_category. `knowledge_base`: Knowledge base retrieval ; `web_search`: We... |
| defaultDisplayGroupNameByLocale | object | 否 | Locale-keyed server-level default group headline shown in chat for this connector's dynamic MCP tools (those without an individual Tool row). Shape: {"": str}. The headline for the conversatio... |
| defaultToolIcon | string | 否 | Server-level default icon identifier (a frontend icon key, not an uploaded image) for this connector's dynamic MCP tools. Empty = frontend uses its default MCP icon. Streamed as toolIcon. |
| authHeaders | object | 否 | |
| allowedContextDataKeys | object | 否 | Allowlist of webchat contextData keys this connector may render into auth\_headers through {{context\_data.}}. An empty list disables the feature for this connector: the placeholder is left verbati... |
| exposedMcpTools | object | 否 | Allowlist of MCP tool names this connector exposes (to the agent and to SEP-1865 UI cards). Empty list = expose all of the server tools. Use this to limit a connector to a safe subset (e.g. read-only ... |
| isEnabled | boolean | 否 | Whether this connector is enabled for contacts in the organization |
**請求結構範例**
```typescript
{
"mcpRegistryId"?: string (uuid) // 非必填
"displayName"?: string // Custom display name for this connector (defaults to MCP Registry name) (非必填)
"description"?: string // Custom description for this connector (defaults to MCP Registry description) (非必填)
"defaultCategory"?: // 可能有不同的類型 (非必填)
string (enum: knowledge_base, web_search, web_fetch, code_execution, file_processing, image_video_generation, database_query, third_party_integration, browser_operation, agent_collaboration, other) // Org-level override of the MCP Registry default category for this connector's dynamic tools. Empty = use the MCP Registry default_category.
* `knowledge_base` - Knowledge base retrieval
* `web_search` - Web search
* `web_fetch` - Web page fetch
* `code_execution` - Code execution
* `file_processing` - File processing
* `image_video_generation` - Image/video generation
* `database_query` - Database query
* `third_party_integration` - Third-party integration
* `browser_operation` - Browser operation
* `agent_collaboration` - Agent collaboration
* `other` - Other (catch-all) (非必填)
"defaultDisplayGroupNameByLocale"?: object // Locale-keyed server-level default group headline shown in chat for this connector's dynamic MCP tools (those without an individual Tool row). Shape: {"": str}. The headline for the conversation locale is resolved server-side (see whizchat.tools.services.tool_category.resolve_localized_text): requested locale -> settings.LANGUAGE_CODE locale -> empty, then streamed verbatim as displayGroupName. Empty = frontend falls back to its name-based heuristic. An individual Tool row overrides this. (非必填)
"defaultToolIcon"?: string // Server-level default icon identifier (a frontend icon key, not an uploaded image) for this connector's dynamic MCP tools. Empty = frontend uses its default MCP icon. Streamed as toolIcon. (非必填)
"authHeaders"?: object // 非必填
"allowedContextDataKeys"?: object // Allowlist of webchat contextData keys this connector may render into auth_headers through {{context_data.}}. An empty list disables the feature for this connector: the placeholder is left verbatim, exactly as before the feature existed. Keys are matched literally and are case-sensitive; at most 20 keys of letters, digits and underscores. (非必填)
"exposedMcpTools"?: object // Allowlist of MCP tool names this connector exposes (to the agent and to SEP-1865 UI cards). Empty list = expose all of the server tools. Use this to limit a connector to a safe subset (e.g. read-only tools). (非必填)
"isEnabled"?: boolean // Whether this connector is enabled for contacts in the organization (非必填)
}
```
**請求範例值**
```json
{
"mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
"displayName": "範例字串",
"description": "範例字串",
"defaultCategory": null,
"defaultDisplayGroupNameByLocale": null,
"defaultToolIcon": "範例字串",
"authHeaders": null,
"allowedContextDataKeys": null,
"exposedMcpTools": null,
"isEnabled": true
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/connectors/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
"displayName": "範例字串",
"description": "範例字串",
"defaultCategory": null,
"defaultDisplayGroupNameByLocale": null,
"defaultToolIcon": "範例字串",
"authHeaders": null,
"allowedContextDataKeys": null,
"exposedMcpTools": null,
"isEnabled": true
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
"displayName": "範例字串",
"description": "範例字串",
"defaultCategory": null,
"defaultDisplayGroupNameByLocale": null,
"defaultToolIcon": "範例字串",
"authHeaders": null,
"allowedContextDataKeys": null,
"exposedMcpTools": null,
"isEnabled": true
};
axios.patch("https://api.maiagent.ai/api/v1/connectors/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/connectors/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
"displayName": "範例字串",
"description": "範例字串",
"defaultCategory": None,
"defaultDisplayGroupNameByLocale": None,
"defaultToolIcon": "範例字串",
"authHeaders": None,
"allowedContextDataKeys": None,
"exposedMcpTools": None,
"isEnabled": True
}
response = requests.patch(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
patch("https://api.maiagent.ai/api/v1/connectors/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'mcpRegistryId' => '550e8400-e29b-41d4-a716-446655440000',
'displayName' => '範例字串',
'description' => '範例字串',
'defaultCategory' => null,
'defaultDisplayGroupNameByLocale' => null,
'defaultToolIcon' => '範例字串',
'authHeaders' => null,
'allowedContextDataKeys' => null,
'exposedMcpTools' => null,
'isEnabled' => true
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"mcpRegistry":
{
"id": string (uuid)
"name": string // MCP service name (e.g., Supabase, Sentry). Only alphanumeric, underscore and hyphen allowed.
"displayName"?: string // Human-readable display name (defaults to name if empty) (非必填)
"description"?: string // Brief description of the MCP service (非必填)
"remoteMcpUrl": string (uri) // The URL of the Remote MCP service
"oauthServerUrl"?: // 可能有不同的類型 (非必填)
string (uri) // Manual override for the OAuth authorization server URL. Leave empty to auto-discover from the MCP server (RFC 9728 protected resource metadata). Only fill in when auto-discovery fails or the server advertises incorrect metadata. (e.g., Supabase MCP is at mcp.supabase.com but OAuth is at api.supabase.com) (非必填)
"logoUrl": string (uri)
"isActive"?: boolean // Whether this MCP service is currently available for use (非必填)
"isGlobal"?: boolean // Global registries are maintained by the platform and available to all organizations. (非必填)
"authType"?: // How to authenticate with this MCP server.
* `oauth` - OAuth 2.0
* `service_account` - Service Account
* `none` - No Authentication (非必填)
{
}
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
"mcpRegistryId": string (uuid)
"name": string
"displayName"?: string // Custom display name for this connector (defaults to MCP Registry name) (非必填)
"description"?: string // Custom description for this connector (defaults to MCP Registry description) (非必填)
"defaultCategory"?: // 可能有不同的類型 (非必填)
string (enum: knowledge_base, web_search, web_fetch, code_execution, file_processing, image_video_generation, database_query, third_party_integration, browser_operation, agent_collaboration, other) // Org-level override of the MCP Registry default category for this connector's dynamic tools. Empty = use the MCP Registry default_category.
* `knowledge_base` - Knowledge base retrieval
* `web_search` - Web search
* `web_fetch` - Web page fetch
* `code_execution` - Code execution
* `file_processing` - File processing
* `image_video_generation` - Image/video generation
* `database_query` - Database query
* `third_party_integration` - Third-party integration
* `browser_operation` - Browser operation
* `agent_collaboration` - Agent collaboration
* `other` - Other (catch-all) (非必填)
"defaultDisplayGroupNameByLocale"?: object // Locale-keyed server-level default group headline shown in chat for this connector's dynamic MCP tools (those without an individual Tool row). Shape: {"": str}. The headline for the conversation locale is resolved server-side (see whizchat.tools.services.tool_category.resolve_localized_text): requested locale -> settings.LANGUAGE_CODE locale -> empty, then streamed verbatim as displayGroupName. Empty = frontend falls back to its name-based heuristic. An individual Tool row overrides this. (非必填)
"defaultToolIcon"?: string // Server-level default icon identifier (a frontend icon key, not an uploaded image) for this connector's dynamic MCP tools. Empty = frontend uses its default MCP icon. Streamed as toolIcon. (非必填)
"effectiveDescription": string
"remoteMcpUrl": string
"oauthServerUrl": string
"logoUrl": string (uri)
"authType": string
"authHeaders"?: object // 非必填
"authHeadersMasked": object
"allowedContextDataKeys"?: object // Allowlist of webchat contextData keys this connector may render into auth_headers through {{context_data.}}. An empty list disables the feature for this connector: the placeholder is left verbatim, exactly as before the feature existed. Keys are matched literally and are case-sensitive; at most 20 keys of letters, digits and underscores. (非必填)
"exposedMcpTools"?: object // Allowlist of MCP tool names this connector exposes (to the agent and to SEP-1865 UI cards). Empty list = expose all of the server tools. Use this to limit a connector to a safe subset (e.g. read-only tools). (非必填)
"isEnabled"?: boolean // Whether this connector is enabled for contacts in the organization (非必填)
"organization": string (uuid)
"createdBy": string (uuid)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"mcpRegistry": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"displayName": "回應字串",
"description": "回應字串",
"remoteMcpUrl": "https://example.com/file.jpg",
"oauthServerUrl": "https://example.com/file.jpg",
"logoUrl": "https://example.com/file.jpg",
"isActive": false,
"isGlobal": false,
"authType": {},
"createdAt": "回應字串",
"updatedAt": "回應字串"
},
"mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"displayName": "回應字串",
"description": "回應字串",
"defaultCategory": "knowledge_base",
"defaultDisplayGroupNameByLocale": null,
"defaultToolIcon": "回應字串",
"effectiveDescription": "回應字串",
"remoteMcpUrl": "回應字串",
"oauthServerUrl": "回應字串",
"logoUrl": "https://example.com/file.jpg",
"authType": "回應字串",
"authHeaders": null,
"authHeadersMasked": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"allowedContextDataKeys": null,
"exposedMcpTools": null,
"isEnabled": false,
"organization": "550e8400-e29b-41d4-a716-446655440000",
"createdBy": "550e8400-e29b-41d4-a716-446655440000",
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
```
***
### 刪除連接器
DELETE `/api/v1/connectors/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | -- |
| `id` | ✅ | string | |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/connectors/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// 請求內容 (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/v1/connectors/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/connectors/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/v1/connectors/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ---------------- |
| 204 | No response body |
***
### 列出連接器授權成員
GET `/api/v1/connectors/{id}/authorized-members/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | -- |
| `id` | ✅ | string | |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/connectors/550e8400-e29b-41d4-a716-446655440000/authorized-members/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/connectors/550e8400-e29b-41d4-a716-446655440000/authorized-members/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/connectors/550e8400-e29b-41d4-a716-446655440000/authorized-members/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/connectors/550e8400-e29b-41d4-a716-446655440000/authorized-members/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"mcpRegistry":
{
"id": string (uuid)
"name": string // MCP service name (e.g., Supabase, Sentry). Only alphanumeric, underscore and hyphen allowed.
"displayName"?: string // Human-readable display name (defaults to name if empty) (非必填)
"description"?: string // Brief description of the MCP service (非必填)
"remoteMcpUrl": string (uri) // The URL of the Remote MCP service
"oauthServerUrl"?: // 可能有不同的類型 (非必填)
string (uri) // Manual override for the OAuth authorization server URL. Leave empty to auto-discover from the MCP server (RFC 9728 protected resource metadata). Only fill in when auto-discovery fails or the server advertises incorrect metadata. (e.g., Supabase MCP is at mcp.supabase.com but OAuth is at api.supabase.com) (非必填)
"logoUrl": string (uri)
"isActive"?: boolean // Whether this MCP service is currently available for use (非必填)
"isGlobal"?: boolean // Global registries are maintained by the platform and available to all organizations. (非必填)
"authType"?: // How to authenticate with this MCP server.
* `oauth` - OAuth 2.0
* `service_account` - Service Account
* `none` - No Authentication (非必填)
{
}
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
"mcpRegistryId": string (uuid)
"name": string
"displayName"?: string // Custom display name for this connector (defaults to MCP Registry name) (非必填)
"description"?: string // Custom description for this connector (defaults to MCP Registry description) (非必填)
"defaultCategory"?: // 可能有不同的類型 (非必填)
string (enum: knowledge_base, web_search, web_fetch, code_execution, file_processing, image_video_generation, database_query, third_party_integration, browser_operation, agent_collaboration, other) // Org-level override of the MCP Registry default category for this connector's dynamic tools. Empty = use the MCP Registry default_category.
* `knowledge_base` - Knowledge base retrieval
* `web_search` - Web search
* `web_fetch` - Web page fetch
* `code_execution` - Code execution
* `file_processing` - File processing
* `image_video_generation` - Image/video generation
* `database_query` - Database query
* `third_party_integration` - Third-party integration
* `browser_operation` - Browser operation
* `agent_collaboration` - Agent collaboration
* `other` - Other (catch-all) (非必填)
"defaultDisplayGroupNameByLocale"?: object // Locale-keyed server-level default group headline shown in chat for this connector's dynamic MCP tools (those without an individual Tool row). Shape: {"": str}. The headline for the conversation locale is resolved server-side (see whizchat.tools.services.tool_category.resolve_localized_text): requested locale -> settings.LANGUAGE_CODE locale -> empty, then streamed verbatim as displayGroupName. Empty = frontend falls back to its name-based heuristic. An individual Tool row overrides this. (非必填)
"defaultToolIcon"?: string // Server-level default icon identifier (a frontend icon key, not an uploaded image) for this connector's dynamic MCP tools. Empty = frontend uses its default MCP icon. Streamed as toolIcon. (非必填)
"effectiveDescription": string
"remoteMcpUrl": string
"oauthServerUrl": string
"logoUrl": string (uri)
"authType": string
"authHeaders"?: object // 非必填
"authHeadersMasked": object
"allowedContextDataKeys"?: object // Allowlist of webchat contextData keys this connector may render into auth_headers through {{context_data.}}. An empty list disables the feature for this connector: the placeholder is left verbatim, exactly as before the feature existed. Keys are matched literally and are case-sensitive; at most 20 keys of letters, digits and underscores. (非必填)
"exposedMcpTools"?: object // Allowlist of MCP tool names this connector exposes (to the agent and to SEP-1865 UI cards). Empty list = expose all of the server tools. Use this to limit a connector to a safe subset (e.g. read-only tools). (非必填)
"isEnabled"?: boolean // Whether this connector is enabled for contacts in the organization (非必填)
"organization": string (uuid)
"createdBy": string (uuid)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"mcpRegistry": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"displayName": "回應字串",
"description": "回應字串",
"remoteMcpUrl": "https://example.com/file.jpg",
"oauthServerUrl": "https://example.com/file.jpg",
"logoUrl": "https://example.com/file.jpg",
"isActive": false,
"isGlobal": false,
"authType": {},
"createdAt": "回應字串",
"updatedAt": "回應字串"
},
"mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"displayName": "回應字串",
"description": "回應字串",
"defaultCategory": "knowledge_base",
"defaultDisplayGroupNameByLocale": null,
"defaultToolIcon": "回應字串",
"effectiveDescription": "回應字串",
"remoteMcpUrl": "回應字串",
"oauthServerUrl": "回應字串",
"logoUrl": "https://example.com/file.jpg",
"authType": "回應字串",
"authHeaders": null,
"authHeadersMasked": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"allowedContextDataKeys": null,
"exposedMcpTools": null,
"isEnabled": false,
"organization": "550e8400-e29b-41d4-a716-446655440000",
"createdBy": "550e8400-e29b-41d4-a716-446655440000",
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
```
***
### 移除連接器授權成員
DELETE `/api/v1/connectors/{id}/authorized-members/{memberId}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------- | -- | ------ | -- |
| `id` | ✅ | string | |
| `memberId` | ✅ | string | |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/connectors/550e8400-e29b-41d4-a716-446655440000/authorized-members/{memberId}/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// 請求內容 (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/v1/connectors/550e8400-e29b-41d4-a716-446655440000/authorized-members/{memberId}/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/connectors/550e8400-e29b-41d4-a716-446655440000/authorized-members/{memberId}/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/v1/connectors/550e8400-e29b-41d4-a716-446655440000/authorized-members/{memberId}/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ---------------- |
| 204 | No response body |
***
### 列出 MCP 工具登錄
GET `/api/v1/mcp/registry/`
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/mcp/registry/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/mcp/registry/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/mcp/registry/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/mcp/registry/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
[
{
"id": string (uuid)
"name": string // MCP service name (e.g., Supabase, Sentry). Only alphanumeric, underscore and hyphen allowed.
"displayName"?: string // Human-readable display name (defaults to name if empty) (非必填)
"description"?: string // Brief description of the MCP service (非必填)
"remoteMcpUrl": string (uri) // The URL of the Remote MCP service
"oauthServerUrl"?: // 可能有不同的類型 (非必填)
string (uri) // Manual override for the OAuth authorization server URL. Leave empty to auto-discover from the MCP server (RFC 9728 protected resource metadata). Only fill in when auto-discovery fails or the server advertises incorrect metadata. (e.g., Supabase MCP is at mcp.supabase.com but OAuth is at api.supabase.com) (非必填)
"logoUrl": string (uri)
"isActive"?: boolean // Whether this MCP service is currently available for use (非必填)
"isGlobal"?: boolean // Global registries are maintained by the platform and available to all organizations. (非必填)
"authType"?: // How to authenticate with this MCP server.
* `oauth` - OAuth 2.0
* `service_account` - Service Account
* `none` - No Authentication (非必填)
{
}
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
```
**回應範例值**
```json
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"displayName": "回應字串",
"description": "回應字串",
"remoteMcpUrl": "https://example.com/file.jpg",
"oauthServerUrl": "https://example.com/file.jpg",
"logoUrl": "https://example.com/file.jpg",
"isActive": false,
"isGlobal": false,
"authType": {},
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
]
```
***
### 取得特定 MCP 工具登錄
GET `/api/v1/mcp/registry/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | -- |
| `id` | ✅ | string | |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/mcp/registry/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/mcp/registry/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/mcp/registry/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/mcp/registry/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"name": string // MCP service name (e.g., Supabase, Sentry). Only alphanumeric, underscore and hyphen allowed.
"displayName"?: string // Human-readable display name (defaults to name if empty) (非必填)
"description"?: string // Brief description of the MCP service (非必填)
"remoteMcpUrl": string (uri) // The URL of the Remote MCP service
"oauthServerUrl"?: // 可能有不同的類型 (非必填)
string (uri) // Manual override for the OAuth authorization server URL. Leave empty to auto-discover from the MCP server (RFC 9728 protected resource metadata). Only fill in when auto-discovery fails or the server advertises incorrect metadata. (e.g., Supabase MCP is at mcp.supabase.com but OAuth is at api.supabase.com) (非必填)
"logoUrl": string (uri)
"isActive"?: boolean // Whether this MCP service is currently available for use (非必填)
"isGlobal"?: boolean // Global registries are maintained by the platform and available to all organizations. (非必填)
"authType"?: // How to authenticate with this MCP server.
* `oauth` - OAuth 2.0
* `service_account` - Service Account
* `none` - No Authentication (非必填)
{
}
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"displayName": "回應字串",
"description": "回應字串",
"remoteMcpUrl": "https://example.com/file.jpg",
"oauthServerUrl": "https://example.com/file.jpg",
"logoUrl": "https://example.com/file.jpg",
"isActive": false,
"isGlobal": false,
"authType": {},
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
```
***
### 列出組織自架的 MCP Server
GET `/api/v1/mcp/private-registry/`
{% hint style="info" %}
需要連接器管理權限。接入方式見技術手冊[自架 MCP Server](https://docs.maiagent.ai/tech/advanced-genai-tech/self-hosted-mcp-server)。
{% endhint %}
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/mcp/private-registry/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/mcp/private-registry/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/mcp/private-registry/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/mcp/private-registry/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
[
{
"id": string (uuid)
"name": string // MCP service name (e.g., Supabase, Sentry). Only alphanumeric, underscore and hyphen allowed.
"displayName"?: string // Human-readable display name (defaults to name if empty) (非必填)
"description"?: string // Brief description of the MCP service (非必填)
"remoteMcpUrl": string (uri) // The URL of the Remote MCP service
"oauthServerUrl"?: // 可能有不同的類型 (非必填)
string (uri) // Manual override for the OAuth authorization server URL. Leave empty to auto-discover from the MCP server (RFC 9728 protected resource metadata). Only fill in when auto-discovery fails or the server advertises incorrect metadata. (e.g., Supabase MCP is at mcp.supabase.com but OAuth is at api.supabase.com) (非必填)
"resourceIdentifier"?: // 可能有不同的類型 (非必填)
string (uri) // Manual override for the OAuth resource identifier (RFC 9728 / RFC 8707). Leave empty to auto-discover from the MCP server's .well-known/oauth-protected-resource endpoint. Only fill in when auto-discovery fails or the metadata is incorrect. (e.g., Asana uses https://mcp.asana.com, Supabase uses https://mcp.supabase.com/mcp) (非必填)
"oauthClientId"?: string // Pre-registered OAuth client ID for MCP servers that do not support dynamic client registration (RFC 7591). Leave empty if the server supports dynamic registration. (非必填)
"oauthClientSecret"?: string // Pre-registered OAuth client secret. Required only if the MCP server requires a confidential client. Leave empty for public clients (token_endpoint_auth_method=none). (非必填)
"logoUrl"?: // 可能有不同的類型 (非必填)
string (uri) // Logo: the uploaded storage object key (media/...) or an external URL; read back as a signed URL. (非必填)
"authType"?: // How to authenticate with this MCP server.
* `oauth` - OAuth 2.0
* `service_account` - Service Account
* `none` - No Authentication (非必填)
{
}
"cspAllowedOrigins"?: object // Extra origins a SEP-1865 MCP App card from this server may load from (script-src/img-src/connect-src etc.), e.g. ['https://viewer.diagrams.net']. The sandboxed iframe denies all external origins by default; list only what the app genuinely needs. Empty = the host's strict default (self only). (非必填)
"isActive": boolean // Whether this MCP service is currently available for use
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
```
**回應範例值**
```json
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"displayName": "回應字串",
"description": "回應字串",
"remoteMcpUrl": "https://example.com/file.jpg",
"oauthServerUrl": "https://example.com/file.jpg",
"resourceIdentifier": "https://example.com/file.jpg",
"oauthClientId": "回應字串",
"oauthClientSecret": "回應字串",
"logoUrl": "https://example.com/file.jpg",
"authType": {},
"cspAllowedOrigins": null,
"isActive": false,
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
]
```
***
### 新增自架 MCP Server
POST `/api/v1/mcp/private-registry/`
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ------------------ | ------------ | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | string | 是 | MCP service name (e.g., Supabase, Sentry). Only alphanumeric, underscore and hyphen allowed. |
| displayName | string | 否 | Human-readable display name (defaults to name if empty) |
| description | string | 否 | Brief description of the MCP service |
| remoteMcpUrl | string (uri) | 是 | The URL of the Remote MCP service |
| oauthServerUrl | object | 否 | Manual override for the OAuth authorization server URL. Leave empty to auto-discover from the MCP server (RFC 9728 protected resource metadata). Only fill in when auto-discovery fails or the server ad... |
| resourceIdentifier | object | 否 | Manual override for the OAuth resource identifier (RFC 9728 / RFC 8707). Leave empty to auto-discover from the MCP server's .well-known/oauth-protected-resource endpoint. Only fill in when auto-discov... |
| oauthClientId | string | 否 | Pre-registered OAuth client ID for MCP servers that do not support dynamic client registration (RFC 7591). Leave empty if the server supports dynamic registration. |
| oauthClientSecret | string | 否 | Pre-registered OAuth client secret. Required only if the MCP server requires a confidential client. Leave empty for public clients (token\_endpoint\_auth\_method=none). |
| logoUrl | object | 否 | Logo: the uploaded storage object key (media/...) or an external URL; read back as a signed URL. |
| authType | object | 否 | How to authenticate with this MCP server. `oauth`: OAuth 2.0 ; `service_account`: Service Account ; `none`: No Authentication; |
| cspAllowedOrigins | object | 否 | Extra origins a SEP-1865 MCP App card from this server may load from (script-src/img-src/connect-src etc.), e.g. \['']. The sandboxed iframe denies all external origins by de... |
**請求結構範例**
```typescript
{
"name": string // MCP service name (e.g., Supabase, Sentry). Only alphanumeric, underscore and hyphen allowed.
"displayName"?: string // Human-readable display name (defaults to name if empty) (非必填)
"description"?: string // Brief description of the MCP service (非必填)
"remoteMcpUrl": string (uri) // The URL of the Remote MCP service
"oauthServerUrl"?: // 可能有不同的類型 (非必填)
string (uri) // Manual override for the OAuth authorization server URL. Leave empty to auto-discover from the MCP server (RFC 9728 protected resource metadata). Only fill in when auto-discovery fails or the server advertises incorrect metadata. (e.g., Supabase MCP is at mcp.supabase.com but OAuth is at api.supabase.com) (非必填)
"resourceIdentifier"?: // 可能有不同的類型 (非必填)
string (uri) // Manual override for the OAuth resource identifier (RFC 9728 / RFC 8707). Leave empty to auto-discover from the MCP server's .well-known/oauth-protected-resource endpoint. Only fill in when auto-discovery fails or the metadata is incorrect. (e.g., Asana uses https://mcp.asana.com, Supabase uses https://mcp.supabase.com/mcp) (非必填)
"oauthClientId"?: string // Pre-registered OAuth client ID for MCP servers that do not support dynamic client registration (RFC 7591). Leave empty if the server supports dynamic registration. (非必填)
"oauthClientSecret"?: string // Pre-registered OAuth client secret. Required only if the MCP server requires a confidential client. Leave empty for public clients (token_endpoint_auth_method=none). (非必填)
"logoUrl"?: // 可能有不同的類型 (非必填)
string (uri) // Logo: the uploaded storage object key (media/...) or an external URL; read back as a signed URL. (非必填)
"authType"?: // How to authenticate with this MCP server.
* `oauth` - OAuth 2.0
* `service_account` - Service Account
* `none` - No Authentication (非必填)
{
}
"cspAllowedOrigins"?: object // Extra origins a SEP-1865 MCP App card from this server may load from (script-src/img-src/connect-src etc.), e.g. ['https://viewer.diagrams.net']. The sandboxed iframe denies all external origins by default; list only what the app genuinely needs. Empty = the host's strict default (self only). (非必填)
}
```
**請求範例值**
```json
{
"name": "範例名稱",
"displayName": "範例字串",
"description": "範例字串",
"remoteMcpUrl": "https://example.com/file.jpg",
"oauthServerUrl": null,
"resourceIdentifier": null,
"oauthClientId": "範例字串",
"oauthClientSecret": "範例字串",
"logoUrl": null,
"authType": {},
"cspAllowedOrigins": null
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/mcp/private-registry/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "範例名稱",
"displayName": "範例字串",
"description": "範例字串",
"remoteMcpUrl": "https://example.com/file.jpg",
"oauthServerUrl": null,
"resourceIdentifier": null,
"oauthClientId": "範例字串",
"oauthClientSecret": "範例字串",
"logoUrl": null,
"authType": {},
"cspAllowedOrigins": null
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"name": "範例名稱",
"displayName": "範例字串",
"description": "範例字串",
"remoteMcpUrl": "https://example.com/file.jpg",
"oauthServerUrl": null,
"resourceIdentifier": null,
"oauthClientId": "範例字串",
"oauthClientSecret": "範例字串",
"logoUrl": null,
"authType": {},
"cspAllowedOrigins": null
};
axios.post("https://api.maiagent.ai/api/v1/mcp/private-registry/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/mcp/private-registry/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"name": "範例名稱",
"displayName": "範例字串",
"description": "範例字串",
"remoteMcpUrl": "https://example.com/file.jpg",
"oauthServerUrl": None,
"resourceIdentifier": None,
"oauthClientId": "範例字串",
"oauthClientSecret": "範例字串",
"logoUrl": None,
"authType": {},
"cspAllowedOrigins": None
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/mcp/private-registry/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'name' => '範例名稱',
'displayName' => '範例字串',
'description' => '範例字串',
'remoteMcpUrl' => 'https://example.com/file.jpg',
'oauthServerUrl' => null,
'resourceIdentifier' => null,
'oauthClientId' => '範例字串',
'oauthClientSecret' => '範例字串',
'logoUrl' => null,
'authType' => new \stdClass(),
'cspAllowedOrigins' => null
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
{
"id": string (uuid)
"name": string // MCP service name (e.g., Supabase, Sentry). Only alphanumeric, underscore and hyphen allowed.
"displayName"?: string // Human-readable display name (defaults to name if empty) (非必填)
"description"?: string // Brief description of the MCP service (非必填)
"remoteMcpUrl": string (uri) // The URL of the Remote MCP service
"oauthServerUrl"?: // 可能有不同的類型 (非必填)
string (uri) // Manual override for the OAuth authorization server URL. Leave empty to auto-discover from the MCP server (RFC 9728 protected resource metadata). Only fill in when auto-discovery fails or the server advertises incorrect metadata. (e.g., Supabase MCP is at mcp.supabase.com but OAuth is at api.supabase.com) (非必填)
"resourceIdentifier"?: // 可能有不同的類型 (非必填)
string (uri) // Manual override for the OAuth resource identifier (RFC 9728 / RFC 8707). Leave empty to auto-discover from the MCP server's .well-known/oauth-protected-resource endpoint. Only fill in when auto-discovery fails or the metadata is incorrect. (e.g., Asana uses https://mcp.asana.com, Supabase uses https://mcp.supabase.com/mcp) (非必填)
"oauthClientId"?: string // Pre-registered OAuth client ID for MCP servers that do not support dynamic client registration (RFC 7591). Leave empty if the server supports dynamic registration. (非必填)
"oauthClientSecret"?: string // Pre-registered OAuth client secret. Required only if the MCP server requires a confidential client. Leave empty for public clients (token_endpoint_auth_method=none). (非必填)
"logoUrl"?: // 可能有不同的類型 (非必填)
string (uri) // Logo: the uploaded storage object key (media/...) or an external URL; read back as a signed URL. (非必填)
"authType"?: // How to authenticate with this MCP server.
* `oauth` - OAuth 2.0
* `service_account` - Service Account
* `none` - No Authentication (非必填)
{
}
"cspAllowedOrigins"?: object // Extra origins a SEP-1865 MCP App card from this server may load from (script-src/img-src/connect-src etc.), e.g. ['https://viewer.diagrams.net']. The sandboxed iframe denies all external origins by default; list only what the app genuinely needs. Empty = the host's strict default (self only). (非必填)
"isActive": boolean // Whether this MCP service is currently available for use
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"displayName": "回應字串",
"description": "回應字串",
"remoteMcpUrl": "https://example.com/file.jpg",
"oauthServerUrl": "https://example.com/file.jpg",
"resourceIdentifier": "https://example.com/file.jpg",
"oauthClientId": "回應字串",
"oauthClientSecret": "回應字串",
"logoUrl": "https://example.com/file.jpg",
"authType": {},
"cspAllowedOrigins": null,
"isActive": false,
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
```
***
### 取得特定自架 MCP Server
GET `/api/v1/mcp/private-registry/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | -------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this MCP Registry. |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/mcp/private-registry/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/mcp/private-registry/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/mcp/private-registry/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/mcp/private-registry/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"name": string // MCP service name (e.g., Supabase, Sentry). Only alphanumeric, underscore and hyphen allowed.
"displayName"?: string // Human-readable display name (defaults to name if empty) (非必填)
"description"?: string // Brief description of the MCP service (非必填)
"remoteMcpUrl": string (uri) // The URL of the Remote MCP service
"oauthServerUrl"?: // 可能有不同的類型 (非必填)
string (uri) // Manual override for the OAuth authorization server URL. Leave empty to auto-discover from the MCP server (RFC 9728 protected resource metadata). Only fill in when auto-discovery fails or the server advertises incorrect metadata. (e.g., Supabase MCP is at mcp.supabase.com but OAuth is at api.supabase.com) (非必填)
"resourceIdentifier"?: // 可能有不同的類型 (非必填)
string (uri) // Manual override for the OAuth resource identifier (RFC 9728 / RFC 8707). Leave empty to auto-discover from the MCP server's .well-known/oauth-protected-resource endpoint. Only fill in when auto-discovery fails or the metadata is incorrect. (e.g., Asana uses https://mcp.asana.com, Supabase uses https://mcp.supabase.com/mcp) (非必填)
"oauthClientId"?: string // Pre-registered OAuth client ID for MCP servers that do not support dynamic client registration (RFC 7591). Leave empty if the server supports dynamic registration. (非必填)
"oauthClientSecret"?: string // Pre-registered OAuth client secret. Required only if the MCP server requires a confidential client. Leave empty for public clients (token_endpoint_auth_method=none). (非必填)
"logoUrl"?: // 可能有不同的類型 (非必填)
string (uri) // Logo: the uploaded storage object key (media/...) or an external URL; read back as a signed URL. (非必填)
"authType"?: // How to authenticate with this MCP server.
* `oauth` - OAuth 2.0
* `service_account` - Service Account
* `none` - No Authentication (非必填)
{
}
"cspAllowedOrigins"?: object // Extra origins a SEP-1865 MCP App card from this server may load from (script-src/img-src/connect-src etc.), e.g. ['https://viewer.diagrams.net']. The sandboxed iframe denies all external origins by default; list only what the app genuinely needs. Empty = the host's strict default (self only). (非必填)
"isActive": boolean // Whether this MCP service is currently available for use
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"displayName": "回應字串",
"description": "回應字串",
"remoteMcpUrl": "https://example.com/file.jpg",
"oauthServerUrl": "https://example.com/file.jpg",
"resourceIdentifier": "https://example.com/file.jpg",
"oauthClientId": "回應字串",
"oauthClientSecret": "回應字串",
"logoUrl": "https://example.com/file.jpg",
"authType": {},
"cspAllowedOrigins": null,
"isActive": false,
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
```
***
### 部分更新自架 MCP Server
PATCH `/api/v1/mcp/private-registry/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | -------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this MCP Registry. |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ------------------ | ------------ | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | string | 否 | MCP service name (e.g., Supabase, Sentry). Only alphanumeric, underscore and hyphen allowed. |
| displayName | string | 否 | Human-readable display name (defaults to name if empty) |
| description | string | 否 | Brief description of the MCP service |
| remoteMcpUrl | string (uri) | 否 | The URL of the Remote MCP service |
| oauthServerUrl | object | 否 | Manual override for the OAuth authorization server URL. Leave empty to auto-discover from the MCP server (RFC 9728 protected resource metadata). Only fill in when auto-discovery fails or the server ad... |
| resourceIdentifier | object | 否 | Manual override for the OAuth resource identifier (RFC 9728 / RFC 8707). Leave empty to auto-discover from the MCP server's .well-known/oauth-protected-resource endpoint. Only fill in when auto-discov... |
| oauthClientId | string | 否 | Pre-registered OAuth client ID for MCP servers that do not support dynamic client registration (RFC 7591). Leave empty if the server supports dynamic registration. |
| oauthClientSecret | string | 否 | Pre-registered OAuth client secret. Required only if the MCP server requires a confidential client. Leave empty for public clients (token\_endpoint\_auth\_method=none). |
| logoUrl | object | 否 | Logo: the uploaded storage object key (media/...) or an external URL; read back as a signed URL. |
| authType | object | 否 | How to authenticate with this MCP server. `oauth`: OAuth 2.0 ; `service_account`: Service Account ; `none`: No Authentication; |
| cspAllowedOrigins | object | 否 | Extra origins a SEP-1865 MCP App card from this server may load from (script-src/img-src/connect-src etc.), e.g. \['']. The sandboxed iframe denies all external origins by de... |
**請求結構範例**
```typescript
{
"name"?: string // MCP service name (e.g., Supabase, Sentry). Only alphanumeric, underscore and hyphen allowed. (非必填)
"displayName"?: string // Human-readable display name (defaults to name if empty) (非必填)
"description"?: string // Brief description of the MCP service (非必填)
"remoteMcpUrl"?: string (uri) // The URL of the Remote MCP service (非必填)
"oauthServerUrl"?: // 可能有不同的類型 (非必填)
string (uri) // Manual override for the OAuth authorization server URL. Leave empty to auto-discover from the MCP server (RFC 9728 protected resource metadata). Only fill in when auto-discovery fails or the server advertises incorrect metadata. (e.g., Supabase MCP is at mcp.supabase.com but OAuth is at api.supabase.com) (非必填)
"resourceIdentifier"?: // 可能有不同的類型 (非必填)
string (uri) // Manual override for the OAuth resource identifier (RFC 9728 / RFC 8707). Leave empty to auto-discover from the MCP server's .well-known/oauth-protected-resource endpoint. Only fill in when auto-discovery fails or the metadata is incorrect. (e.g., Asana uses https://mcp.asana.com, Supabase uses https://mcp.supabase.com/mcp) (非必填)
"oauthClientId"?: string // Pre-registered OAuth client ID for MCP servers that do not support dynamic client registration (RFC 7591). Leave empty if the server supports dynamic registration. (非必填)
"oauthClientSecret"?: string // Pre-registered OAuth client secret. Required only if the MCP server requires a confidential client. Leave empty for public clients (token_endpoint_auth_method=none). (非必填)
"logoUrl"?: // 可能有不同的類型 (非必填)
string (uri) // Logo: the uploaded storage object key (media/...) or an external URL; read back as a signed URL. (非必填)
"authType"?: // How to authenticate with this MCP server.
* `oauth` - OAuth 2.0
* `service_account` - Service Account
* `none` - No Authentication (非必填)
{
}
"cspAllowedOrigins"?: object // Extra origins a SEP-1865 MCP App card from this server may load from (script-src/img-src/connect-src etc.), e.g. ['https://viewer.diagrams.net']. The sandboxed iframe denies all external origins by default; list only what the app genuinely needs. Empty = the host's strict default (self only). (非必填)
}
```
**請求範例值**
```json
{
"name": "範例名稱",
"displayName": "範例字串",
"description": "範例字串",
"remoteMcpUrl": "https://example.com/file.jpg",
"oauthServerUrl": null,
"resourceIdentifier": null,
"oauthClientId": "範例字串",
"oauthClientSecret": "範例字串",
"logoUrl": null,
"authType": {},
"cspAllowedOrigins": null
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/mcp/private-registry/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "範例名稱",
"displayName": "範例字串",
"description": "範例字串",
"remoteMcpUrl": "https://example.com/file.jpg",
"oauthServerUrl": null,
"resourceIdentifier": null,
"oauthClientId": "範例字串",
"oauthClientSecret": "範例字串",
"logoUrl": null,
"authType": {},
"cspAllowedOrigins": null
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"name": "範例名稱",
"displayName": "範例字串",
"description": "範例字串",
"remoteMcpUrl": "https://example.com/file.jpg",
"oauthServerUrl": null,
"resourceIdentifier": null,
"oauthClientId": "範例字串",
"oauthClientSecret": "範例字串",
"logoUrl": null,
"authType": {},
"cspAllowedOrigins": null
};
axios.patch("https://api.maiagent.ai/api/v1/mcp/private-registry/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/mcp/private-registry/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"name": "範例名稱",
"displayName": "範例字串",
"description": "範例字串",
"remoteMcpUrl": "https://example.com/file.jpg",
"oauthServerUrl": None,
"resourceIdentifier": None,
"oauthClientId": "範例字串",
"oauthClientSecret": "範例字串",
"logoUrl": None,
"authType": {},
"cspAllowedOrigins": None
}
response = requests.patch(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
patch("https://api.maiagent.ai/api/v1/mcp/private-registry/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'name' => '範例名稱',
'displayName' => '範例字串',
'description' => '範例字串',
'remoteMcpUrl' => 'https://example.com/file.jpg',
'oauthServerUrl' => null,
'resourceIdentifier' => null,
'oauthClientId' => '範例字串',
'oauthClientSecret' => '範例字串',
'logoUrl' => null,
'authType' => new \stdClass(),
'cspAllowedOrigins' => null
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"name": string // MCP service name (e.g., Supabase, Sentry). Only alphanumeric, underscore and hyphen allowed.
"displayName"?: string // Human-readable display name (defaults to name if empty) (非必填)
"description"?: string // Brief description of the MCP service (非必填)
"remoteMcpUrl": string (uri) // The URL of the Remote MCP service
"oauthServerUrl"?: // 可能有不同的類型 (非必填)
string (uri) // Manual override for the OAuth authorization server URL. Leave empty to auto-discover from the MCP server (RFC 9728 protected resource metadata). Only fill in when auto-discovery fails or the server advertises incorrect metadata. (e.g., Supabase MCP is at mcp.supabase.com but OAuth is at api.supabase.com) (非必填)
"resourceIdentifier"?: // 可能有不同的類型 (非必填)
string (uri) // Manual override for the OAuth resource identifier (RFC 9728 / RFC 8707). Leave empty to auto-discover from the MCP server's .well-known/oauth-protected-resource endpoint. Only fill in when auto-discovery fails or the metadata is incorrect. (e.g., Asana uses https://mcp.asana.com, Supabase uses https://mcp.supabase.com/mcp) (非必填)
"oauthClientId"?: string // Pre-registered OAuth client ID for MCP servers that do not support dynamic client registration (RFC 7591). Leave empty if the server supports dynamic registration. (非必填)
"oauthClientSecret"?: string // Pre-registered OAuth client secret. Required only if the MCP server requires a confidential client. Leave empty for public clients (token_endpoint_auth_method=none). (非必填)
"logoUrl"?: // 可能有不同的類型 (非必填)
string (uri) // Logo: the uploaded storage object key (media/...) or an external URL; read back as a signed URL. (非必填)
"authType"?: // How to authenticate with this MCP server.
* `oauth` - OAuth 2.0
* `service_account` - Service Account
* `none` - No Authentication (非必填)
{
}
"cspAllowedOrigins"?: object // Extra origins a SEP-1865 MCP App card from this server may load from (script-src/img-src/connect-src etc.), e.g. ['https://viewer.diagrams.net']. The sandboxed iframe denies all external origins by default; list only what the app genuinely needs. Empty = the host's strict default (self only). (非必填)
"isActive": boolean // Whether this MCP service is currently available for use
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"displayName": "回應字串",
"description": "回應字串",
"remoteMcpUrl": "https://example.com/file.jpg",
"oauthServerUrl": "https://example.com/file.jpg",
"resourceIdentifier": "https://example.com/file.jpg",
"oauthClientId": "回應字串",
"oauthClientSecret": "回應字串",
"logoUrl": "https://example.com/file.jpg",
"authType": {},
"cspAllowedOrigins": null,
"isActive": false,
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
```
***
### 刪除自架 MCP Server
DELETE `/api/v1/mcp/private-registry/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | -------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this MCP Registry. |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/mcp/private-registry/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// 請求內容 (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/v1/mcp/private-registry/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/mcp/private-registry/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/v1/mcp/private-registry/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ---------------- |
| 204 | No response body |
***
### 測試 MCP Server 連線
POST `/api/v1/mcp/private-registry/test-connection/`
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ------------------ | ------------ | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | string | 是 | MCP service name (e.g., Supabase, Sentry). Only alphanumeric, underscore and hyphen allowed. |
| displayName | string | 否 | Human-readable display name (defaults to name if empty) |
| description | string | 否 | Brief description of the MCP service |
| remoteMcpUrl | string (uri) | 是 | The URL of the Remote MCP service |
| oauthServerUrl | object | 否 | Manual override for the OAuth authorization server URL. Leave empty to auto-discover from the MCP server (RFC 9728 protected resource metadata). Only fill in when auto-discovery fails or the server ad... |
| resourceIdentifier | object | 否 | Manual override for the OAuth resource identifier (RFC 9728 / RFC 8707). Leave empty to auto-discover from the MCP server's .well-known/oauth-protected-resource endpoint. Only fill in when auto-discov... |
| oauthClientId | string | 否 | Pre-registered OAuth client ID for MCP servers that do not support dynamic client registration (RFC 7591). Leave empty if the server supports dynamic registration. |
| oauthClientSecret | string | 否 | Pre-registered OAuth client secret. Required only if the MCP server requires a confidential client. Leave empty for public clients (token\_endpoint\_auth\_method=none). |
| logoUrl | object | 否 | Logo: the uploaded storage object key (media/...) or an external URL; read back as a signed URL. |
| authType | object | 否 | How to authenticate with this MCP server. `oauth`: OAuth 2.0 ; `service_account`: Service Account ; `none`: No Authentication; |
| cspAllowedOrigins | object | 否 | Extra origins a SEP-1865 MCP App card from this server may load from (script-src/img-src/connect-src etc.), e.g. \['']. The sandboxed iframe denies all external origins by de... |
**請求結構範例**
```typescript
{
"name": string // MCP service name (e.g., Supabase, Sentry). Only alphanumeric, underscore and hyphen allowed.
"displayName"?: string // Human-readable display name (defaults to name if empty) (非必填)
"description"?: string // Brief description of the MCP service (非必填)
"remoteMcpUrl": string (uri) // The URL of the Remote MCP service
"oauthServerUrl"?: // 可能有不同的類型 (非必填)
string (uri) // Manual override for the OAuth authorization server URL. Leave empty to auto-discover from the MCP server (RFC 9728 protected resource metadata). Only fill in when auto-discovery fails or the server advertises incorrect metadata. (e.g., Supabase MCP is at mcp.supabase.com but OAuth is at api.supabase.com) (非必填)
"resourceIdentifier"?: // 可能有不同的類型 (非必填)
string (uri) // Manual override for the OAuth resource identifier (RFC 9728 / RFC 8707). Leave empty to auto-discover from the MCP server's .well-known/oauth-protected-resource endpoint. Only fill in when auto-discovery fails or the metadata is incorrect. (e.g., Asana uses https://mcp.asana.com, Supabase uses https://mcp.supabase.com/mcp) (非必填)
"oauthClientId"?: string // Pre-registered OAuth client ID for MCP servers that do not support dynamic client registration (RFC 7591). Leave empty if the server supports dynamic registration. (非必填)
"oauthClientSecret"?: string // Pre-registered OAuth client secret. Required only if the MCP server requires a confidential client. Leave empty for public clients (token_endpoint_auth_method=none). (非必填)
"logoUrl"?: // 可能有不同的類型 (非必填)
string (uri) // Logo: the uploaded storage object key (media/...) or an external URL; read back as a signed URL. (非必填)
"authType"?: // How to authenticate with this MCP server.
* `oauth` - OAuth 2.0
* `service_account` - Service Account
* `none` - No Authentication (非必填)
{
}
"cspAllowedOrigins"?: object // Extra origins a SEP-1865 MCP App card from this server may load from (script-src/img-src/connect-src etc.), e.g. ['https://viewer.diagrams.net']. The sandboxed iframe denies all external origins by default; list only what the app genuinely needs. Empty = the host's strict default (self only). (非必填)
}
```
**請求範例值**
```json
{
"name": "範例名稱",
"displayName": "範例字串",
"description": "範例字串",
"remoteMcpUrl": "https://example.com/file.jpg",
"oauthServerUrl": null,
"resourceIdentifier": null,
"oauthClientId": "範例字串",
"oauthClientSecret": "範例字串",
"logoUrl": null,
"authType": {},
"cspAllowedOrigins": null
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/mcp/private-registry/test-connection/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "範例名稱",
"displayName": "範例字串",
"description": "範例字串",
"remoteMcpUrl": "https://example.com/file.jpg",
"oauthServerUrl": null,
"resourceIdentifier": null,
"oauthClientId": "範例字串",
"oauthClientSecret": "範例字串",
"logoUrl": null,
"authType": {},
"cspAllowedOrigins": null
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"name": "範例名稱",
"displayName": "範例字串",
"description": "範例字串",
"remoteMcpUrl": "https://example.com/file.jpg",
"oauthServerUrl": null,
"resourceIdentifier": null,
"oauthClientId": "範例字串",
"oauthClientSecret": "範例字串",
"logoUrl": null,
"authType": {},
"cspAllowedOrigins": null
};
axios.post("https://api.maiagent.ai/api/v1/mcp/private-registry/test-connection/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/mcp/private-registry/test-connection/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"name": "範例名稱",
"displayName": "範例字串",
"description": "範例字串",
"remoteMcpUrl": "https://example.com/file.jpg",
"oauthServerUrl": None,
"resourceIdentifier": None,
"oauthClientId": "範例字串",
"oauthClientSecret": "範例字串",
"logoUrl": None,
"authType": {},
"cspAllowedOrigins": None
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/mcp/private-registry/test-connection/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'name' => '範例名稱',
'displayName' => '範例字串',
'description' => '範例字串',
'remoteMcpUrl' => 'https://example.com/file.jpg',
'oauthServerUrl' => null,
'resourceIdentifier' => null,
'oauthClientId' => '範例字串',
'oauthClientSecret' => '範例字串',
'logoUrl' => null,
'authType' => new \stdClass(),
'cspAllowedOrigins' => null
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"name": string // MCP service name (e.g., Supabase, Sentry). Only alphanumeric, underscore and hyphen allowed.
"displayName"?: string // Human-readable display name (defaults to name if empty) (非必填)
"description"?: string // Brief description of the MCP service (非必填)
"remoteMcpUrl": string (uri) // The URL of the Remote MCP service
"oauthServerUrl"?: // 可能有不同的類型 (非必填)
string (uri) // Manual override for the OAuth authorization server URL. Leave empty to auto-discover from the MCP server (RFC 9728 protected resource metadata). Only fill in when auto-discovery fails or the server advertises incorrect metadata. (e.g., Supabase MCP is at mcp.supabase.com but OAuth is at api.supabase.com) (非必填)
"resourceIdentifier"?: // 可能有不同的類型 (非必填)
string (uri) // Manual override for the OAuth resource identifier (RFC 9728 / RFC 8707). Leave empty to auto-discover from the MCP server's .well-known/oauth-protected-resource endpoint. Only fill in when auto-discovery fails or the metadata is incorrect. (e.g., Asana uses https://mcp.asana.com, Supabase uses https://mcp.supabase.com/mcp) (非必填)
"oauthClientId"?: string // Pre-registered OAuth client ID for MCP servers that do not support dynamic client registration (RFC 7591). Leave empty if the server supports dynamic registration. (非必填)
"oauthClientSecret"?: string // Pre-registered OAuth client secret. Required only if the MCP server requires a confidential client. Leave empty for public clients (token_endpoint_auth_method=none). (非必填)
"logoUrl"?: // 可能有不同的類型 (非必填)
string (uri) // Logo: the uploaded storage object key (media/...) or an external URL; read back as a signed URL. (非必填)
"authType"?: // How to authenticate with this MCP server.
* `oauth` - OAuth 2.0
* `service_account` - Service Account
* `none` - No Authentication (非必填)
{
}
"cspAllowedOrigins"?: object // Extra origins a SEP-1865 MCP App card from this server may load from (script-src/img-src/connect-src etc.), e.g. ['https://viewer.diagrams.net']. The sandboxed iframe denies all external origins by default; list only what the app genuinely needs. Empty = the host's strict default (self only). (非必填)
"isActive": boolean // Whether this MCP service is currently available for use
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"displayName": "回應字串",
"description": "回應字串",
"remoteMcpUrl": "https://example.com/file.jpg",
"oauthServerUrl": "https://example.com/file.jpg",
"resourceIdentifier": "https://example.com/file.jpg",
"oauthClientId": "回應字串",
"oauthClientSecret": "回應字串",
"logoUrl": "https://example.com/file.jpg",
"authType": {},
"cspAllowedOrigins": null,
"isActive": false,
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
```
***
### 取得工具執行紀錄列表
GET `/api/v1/tool-execution-records/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ----------- | -- | ------- | ---------------------------------------------- |
| `chatbot` | ❌ | string | 通過 AI 助理 ID 過濾 |
| `endDate` | ❌ | string | 結束日期（包含當日），格式：YYYY-MM-DD |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | 搜尋 AI 助理名稱、工具名稱、訊息內容 |
| `startDate` | ❌ | string | 開始日期（包含當日），格式：YYYY-MM-DD |
| `status` | ❌ | string | 通過執行狀態過濾：success, failure, pending, timeout |
| `tool` | ❌ | string | 通過工具 ID 過濾 |
| `toolType` | ❌ | string | 通過工具類型過濾：api, function, mcp |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/tool-execution-records/?chatbot=example&endDate=example&page=1&pageSize=1&query=example&startDate=example&status=failure&tool=example&toolType=api" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/tool-execution-records/?chatbot=example&endDate=example&page=1&pageSize=1&query=example&startDate=example&status=failure&tool=example&toolType=api", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/tool-execution-records/?chatbot=example&endDate=example&page=1&pageSize=1&query=example&startDate=example&status=failure&tool=example&toolType=api"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/tool-execution-records/?chatbot=example&endDate=example&page=1&pageSize=1&query=example&startDate=example&status=failure&tool=example&toolType=api", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"tool": object // 獲取工具資訊
"chatbot": object // 獲取 AI 助理資訊
"messageContent": string // 獲取訊息內容
"status"?: string (enum: success, failure, pending, timeout) // * `success` - Success
* `failure` - Failed
* `pending` - Processing
* `timeout` - Timeout (非必填)
"executionTime": integer // 獲取執行時間（毫秒）
"errorMessage"?: string // 非必填
"retryCount"?: integer // How many times the platform auto-retried this tool call before the final outcome (0 = the first attempt was the final one). API tools count tenacity retries inside APIRequestService; MCP tools count transient-error retries (read-classified tools only). Function tools are never auto-retried. (非必填)
"createdAt": string (timestamp)
"source": string // Scheduled runs' tool calls are attributed via ChatbotScheduleExecution.user_message.
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"tool": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"chatbot": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"messageContent": "回應字串",
"status": "success",
"executionTime": 456,
"errorMessage": "回應字串",
"retryCount": 456,
"createdAt": "回應字串",
"source": "回應字串"
}
]
}
```
***
### 取得特定工具執行紀錄
GET `/api/v1/tool-execution-records/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ----------------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Tool Execution Record. |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/tool-execution-records/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/tool-execution-records/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/tool-execution-records/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/tool-execution-records/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"tool": object // 獲取工具資訊，並包含 operated_tool_name
"chatbot": object // 獲取 AI 助理資訊
"message":
{
"id": string (uuid)
"content": string
}
"inputParameters": object
"outputResult"?: object // 非必填
"errorMessage"?: string // 非必填
"status"?: string (enum: success, failure, pending, timeout) // * `success` - Success
* `failure` - Failed
* `pending` - Processing
* `timeout` - Timeout (非必填)
"executionTime": integer // 獲取執行時間（毫秒）
"retryCount"?: integer // How many times the platform auto-retried this tool call before the final outcome (0 = the first attempt was the final one). API tools count tenacity retries inside APIRequestService; MCP tools count transient-error retries (read-classified tools only). Function tools are never auto-retried. (非必填)
"requestUrl"?: // 可能有不同的類型 (非必填)
string (uri) // Final rendered URL used when calling an API tool. Null for non-API tools. (非必填)
"requestMethod"?: string // HTTP method (GET/POST/...) used when calling an API tool. Null for non-API tools. (非必填)
"requestHeaders": object // Return rendered request headers with sensitive values masked.
Three sources are unioned, any hit masks: ``settings.TOOL_API_SENSITIVE_HEADERS``,
APICredential keys for the (contact, tool) pair, and the tool's current
``sensitive_headers``. The tool list is applied at read time against the stored
value, so editing it changes how existing records render without rewriting them.
"requestBody"?: object // Final rendered body sent to the external API. Null for non-API tools or read-only methods. (非必填)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
"source": string // Scheduled runs' tool calls are attributed via ChatbotScheduleExecution.user_message.
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"tool": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"chatbot": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"message": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"content": "回應字串"
},
"inputParameters": null,
"outputResult": null,
"errorMessage": "回應字串",
"status": "success",
"executionTime": 456,
"retryCount": 456,
"requestUrl": "https://example.com/file.jpg",
"requestMethod": "回應字串",
"requestHeaders": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"requestBody": null,
"createdAt": "回應字串",
"updatedAt": "回應字串",
"source": "回應字串"
}
```
***
### 取得執行紀錄的 AI 助理過濾選項
GET `/api/v1/tool-execution-records/chatbots/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ----------- | -- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `chatbot` | ❌ | string | |
| `endDate` | ❌ | string | |
| `query` | ❌ | string | |
| `startDate` | ❌ | string | |
| `status` | ❌ | string | \`success\`: Success ; \`failure\`: Failed ; \`pending\`: Processing ; \`timeout\`: Timeout; |
| `tool` | ❌ | string | |
| `toolType` | ❌ | string | \`api\`: API ; \`function\`: Function ; \`mcp\`: MCP ; \`desktop\`: Desktop ; \`flex\`: Flex Message ; \`quick\_reply\`: Quick Reply ; \`quick\_menu\`: Quick Menu; |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/tool-execution-records/chatbots/?chatbot=550e8400-e29b-41d4-a716-446655440000&endDate=example&query=example&startDate=example&status=failure&tool=550e8400-e29b-41d4-a716-446655440000&toolType=api" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/tool-execution-records/chatbots/?chatbot=550e8400-e29b-41d4-a716-446655440000&endDate=example&query=example&startDate=example&status=failure&tool=550e8400-e29b-41d4-a716-446655440000&toolType=api", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/tool-execution-records/chatbots/?chatbot=550e8400-e29b-41d4-a716-446655440000&endDate=example&query=example&startDate=example&status=failure&tool=550e8400-e29b-41d4-a716-446655440000&toolType=api"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/tool-execution-records/chatbots/?chatbot=550e8400-e29b-41d4-a716-446655440000&endDate=example&query=example&startDate=example&status=failure&tool=550e8400-e29b-41d4-a716-446655440000&toolType=api", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
[
{
"id": string (uuid)
"name": string // Chatbot name. In Agent mode it carries semantic meaning; in other modes it only distinguishes chatbots.
"team":
{
"id": string (uuid)
"name": string
}
}
]
```
**回應範例值**
```json
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"team": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
}
]
```
***
### 取得執行紀錄的工具過濾選項
GET `/api/v1/tool-execution-records/tools/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ----------- | -- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `chatbot` | ❌ | string | |
| `endDate` | ❌ | string | |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | |
| `startDate` | ❌ | string | |
| `status` | ❌ | string | \`success\`: Success ; \`failure\`: Failed ; \`pending\`: Processing ; \`timeout\`: Timeout; |
| `tool` | ❌ | string | |
| `toolType` | ❌ | string | \`api\`: API ; \`function\`: Function ; \`mcp\`: MCP ; \`desktop\`: Desktop ; \`flex\`: Flex Message ; \`quick\_reply\`: Quick Reply ; \`quick\_menu\`: Quick Menu; |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/tool-execution-records/tools/?chatbot=550e8400-e29b-41d4-a716-446655440000&endDate=example&page=1&pageSize=1&query=example&startDate=example&status=failure&tool=550e8400-e29b-41d4-a716-446655440000&toolType=api" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/tool-execution-records/tools/?chatbot=550e8400-e29b-41d4-a716-446655440000&endDate=example&page=1&pageSize=1&query=example&startDate=example&status=failure&tool=550e8400-e29b-41d4-a716-446655440000&toolType=api", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/tool-execution-records/tools/?chatbot=550e8400-e29b-41d4-a716-446655440000&endDate=example&page=1&pageSize=1&query=example&startDate=example&status=failure&tool=550e8400-e29b-41d4-a716-446655440000&toolType=api"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/tool-execution-records/tools/?chatbot=550e8400-e29b-41d4-a716-446655440000&endDate=example&page=1&pageSize=1&query=example&startDate=example&status=failure&tool=550e8400-e29b-41d4-a716-446655440000&toolType=api", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"displayName": string
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"displayName": "回應字串"
}
]
}
```
***
### 取得特定工具的執行紀錄列表
GET `/api/v1/tools/{toolPk}/tool-execution-records/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ----------- | -- | ------- | ---------------------------------------------- |
| `toolPk` | ✅ | string | |
| `chatbot` | ❌ | string | 通過 AI 助理 ID 過濾 |
| `endDate` | ❌ | string | 結束日期（包含當日），格式：YYYY-MM-DD |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | 搜尋 AI 助理名稱、工具名稱、訊息內容 |
| `startDate` | ❌ | string | 開始日期（包含當日），格式：YYYY-MM-DD |
| `status` | ❌ | string | 通過執行狀態過濾：success, failure, pending, timeout |
| `tool` | ❌ | string | 通過工具 ID 過濾 |
| `toolType` | ❌ | string | 通過工具類型過濾：api, function, mcp |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/tool-execution-records/?chatbot=example&endDate=example&page=1&pageSize=1&query=example&startDate=example&status=failure&tool=example&toolType=api" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/tool-execution-records/?chatbot=example&endDate=example&page=1&pageSize=1&query=example&startDate=example&status=failure&tool=example&toolType=api", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/tool-execution-records/?chatbot=example&endDate=example&page=1&pageSize=1&query=example&startDate=example&status=failure&tool=example&toolType=api"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/tool-execution-records/?chatbot=example&endDate=example&page=1&pageSize=1&query=example&startDate=example&status=failure&tool=example&toolType=api", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"tool": object // 獲取工具資訊
"chatbot": object // 獲取 AI 助理資訊
"messageContent": string // 獲取訊息內容
"status"?: string (enum: success, failure, pending, timeout) // * `success` - Success
* `failure` - Failed
* `pending` - Processing
* `timeout` - Timeout (非必填)
"executionTime": integer // 獲取執行時間（毫秒）
"errorMessage"?: string // 非必填
"retryCount"?: integer // How many times the platform auto-retried this tool call before the final outcome (0 = the first attempt was the final one). API tools count tenacity retries inside APIRequestService; MCP tools count transient-error retries (read-classified tools only). Function tools are never auto-retried. (非必填)
"createdAt": string (timestamp)
"source": string // Scheduled runs' tool calls are attributed via ChatbotScheduleExecution.user_message.
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"tool": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"chatbot": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"messageContent": "回應字串",
"status": "success",
"executionTime": 456,
"errorMessage": "回應字串",
"retryCount": 456,
"createdAt": "回應字串",
"source": "回應字串"
}
]
}
```
***
### 取得特定工具的特定執行紀錄
GET `/api/v1/tools/{toolPk}/tool-execution-records/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| -------- | -- | ------ | ----------------------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Tool Execution Record. |
| `toolPk` | ✅ | string | |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/tool-execution-records/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/tool-execution-records/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/tool-execution-records/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/tool-execution-records/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"tool": object // 獲取工具資訊，並包含 operated_tool_name
"chatbot": object // 獲取 AI 助理資訊
"message":
{
"id": string (uuid)
"content": string
}
"inputParameters": object
"outputResult"?: object // 非必填
"errorMessage"?: string // 非必填
"status"?: string (enum: success, failure, pending, timeout) // * `success` - Success
* `failure` - Failed
* `pending` - Processing
* `timeout` - Timeout (非必填)
"executionTime": integer // 獲取執行時間（毫秒）
"retryCount"?: integer // How many times the platform auto-retried this tool call before the final outcome (0 = the first attempt was the final one). API tools count tenacity retries inside APIRequestService; MCP tools count transient-error retries (read-classified tools only). Function tools are never auto-retried. (非必填)
"requestUrl"?: // 可能有不同的類型 (非必填)
string (uri) // Final rendered URL used when calling an API tool. Null for non-API tools. (非必填)
"requestMethod"?: string // HTTP method (GET/POST/...) used when calling an API tool. Null for non-API tools. (非必填)
"requestHeaders": object // Return rendered request headers with sensitive values masked.
Three sources are unioned, any hit masks: ``settings.TOOL_API_SENSITIVE_HEADERS``,
APICredential keys for the (contact, tool) pair, and the tool's current
``sensitive_headers``. The tool list is applied at read time against the stored
value, so editing it changes how existing records render without rewriting them.
"requestBody"?: object // Final rendered body sent to the external API. Null for non-API tools or read-only methods. (非必填)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
"source": string // Scheduled runs' tool calls are attributed via ChatbotScheduleExecution.user_message.
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"tool": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"chatbot": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"message": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"content": "回應字串"
},
"inputParameters": null,
"outputResult": null,
"errorMessage": "回應字串",
"status": "success",
"executionTime": 456,
"retryCount": 456,
"requestUrl": "https://example.com/file.jpg",
"requestMethod": "回應字串",
"requestHeaders": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
},
"requestBody": null,
"createdAt": "回應字串",
"updatedAt": "回應字串",
"source": "回應字串"
}
```
***
### 取得特定工具執行紀錄的 AI 助理過濾選項
GET `/api/v1/tools/{toolPk}/tool-execution-records/chatbots/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ----------- | -- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `toolPk` | ✅ | string | |
| `chatbot` | ❌ | string | |
| `endDate` | ❌ | string | |
| `query` | ❌ | string | |
| `startDate` | ❌ | string | |
| `status` | ❌ | string | \`success\`: Success ; \`failure\`: Failed ; \`pending\`: Processing ; \`timeout\`: Timeout; |
| `tool` | ❌ | string | |
| `toolType` | ❌ | string | \`api\`: API ; \`function\`: Function ; \`mcp\`: MCP ; \`desktop\`: Desktop ; \`flex\`: Flex Message ; \`quick\_reply\`: Quick Reply ; \`quick\_menu\`: Quick Menu; |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/tool-execution-records/chatbots/?chatbot=550e8400-e29b-41d4-a716-446655440000&endDate=example&query=example&startDate=example&status=failure&tool=550e8400-e29b-41d4-a716-446655440000&toolType=api" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/tool-execution-records/chatbots/?chatbot=550e8400-e29b-41d4-a716-446655440000&endDate=example&query=example&startDate=example&status=failure&tool=550e8400-e29b-41d4-a716-446655440000&toolType=api", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/tool-execution-records/chatbots/?chatbot=550e8400-e29b-41d4-a716-446655440000&endDate=example&query=example&startDate=example&status=failure&tool=550e8400-e29b-41d4-a716-446655440000&toolType=api"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/tool-execution-records/chatbots/?chatbot=550e8400-e29b-41d4-a716-446655440000&endDate=example&query=example&startDate=example&status=failure&tool=550e8400-e29b-41d4-a716-446655440000&toolType=api", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
[
{
"id": string (uuid)
"name": string // Chatbot name. In Agent mode it carries semantic meaning; in other modes it only distinguishes chatbots.
"team":
{
"id": string (uuid)
"name": string
}
}
]
```
**回應範例值**
```json
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"team": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
}
]
```
***
### 取得特定工具執行紀錄的工具過濾選項
GET `/api/v1/tools/{toolPk}/tool-execution-records/tools/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ----------- | -- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `toolPk` | ✅ | string | |
| `chatbot` | ❌ | string | |
| `endDate` | ❌ | string | |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | |
| `startDate` | ❌ | string | |
| `status` | ❌ | string | \`success\`: Success ; \`failure\`: Failed ; \`pending\`: Processing ; \`timeout\`: Timeout; |
| `tool` | ❌ | string | |
| `toolType` | ❌ | string | \`api\`: API ; \`function\`: Function ; \`mcp\`: MCP ; \`desktop\`: Desktop ; \`flex\`: Flex Message ; \`quick\_reply\`: Quick Reply ; \`quick\_menu\`: Quick Menu; |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/tool-execution-records/tools/?chatbot=550e8400-e29b-41d4-a716-446655440000&endDate=example&page=1&pageSize=1&query=example&startDate=example&status=failure&tool=550e8400-e29b-41d4-a716-446655440000&toolType=api" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/tool-execution-records/tools/?chatbot=550e8400-e29b-41d4-a716-446655440000&endDate=example&page=1&pageSize=1&query=example&startDate=example&status=failure&tool=550e8400-e29b-41d4-a716-446655440000&toolType=api", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/tool-execution-records/tools/?chatbot=550e8400-e29b-41d4-a716-446655440000&endDate=example&page=1&pageSize=1&query=example&startDate=example&status=failure&tool=550e8400-e29b-41d4-a716-446655440000&toolType=api"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/tool-execution-records/tools/?chatbot=550e8400-e29b-41d4-a716-446655440000&endDate=example&page=1&pageSize=1&query=example&startDate=example&status=failure&tool=550e8400-e29b-41d4-a716-446655440000&toolType=api", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"displayName": string
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"displayName": "回應字串"
}
]
}
```
***
---
# 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 by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.maiagent.ai/api/api-reference/gong-ju-he-lian-jie-qi.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.