工具與連接器

建立工具

POST /api/v1/tools/

請求內容

請求參數

欄位	類型	必填	說明
name	string	否	工具名稱只能包含英文字母、數字、底線(_)和連字符(-)。MCP 類型工具不需要此欄位，此欄位將用於 API 類型工具給 LLM 使用。
displayName	string	是	可包含任何字符的名稱，供使用者設定使用和管理。
description	string	否	給用戶展示的工具描述。MCP 類型工具不需要此欄位。
prompt	string	否	給 LLM 使用的工具描述/提示詞。若為空，系統將使用 description 欄位。MCP 類型工具不需要此欄位。
toolType	object	否
apiUrl	string (uri)	否
httpMethod	object	否
rawHeaders	object	否
rawParametersSchema	object	否
functionCode	string	否
mcpUrl	string	否
mcpAllowedTools	object	否
rawMcpHeader	object	否	當 Contact 沒有對應的 MCP Credential 時，將使用此預設標頭
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.
groups	array[IdName]	否	Groups this tool is assigned to. Non-owner members must pick at least one group they belong to.

請求結構範例

{
  "name"?: string // 工具名稱只能包含英文字母、數字、底線(_)和連字符(-)。MCP 類型工具不需要此欄位，此欄位將用於 API 類型工具給 LLM 使用。 (非必填)
  "displayName": string // 可包含任何字符的名稱，供使用者設定使用和管理。
  "description"?: string // 給用戶展示的工具描述。MCP 類型工具不需要此欄位。 (非必填)
  "prompt"?: string // 給 LLM 使用的工具描述/提示詞。若為空，系統將使用 description 欄位。MCP 類型工具不需要此欄位。 (非必填)
  "toolType"?:  // 非必填
  {
  }
  "apiUrl"?: string (uri) // 非必填
  "httpMethod"?: // 可能有不同的類型 (非必填)
  string (enum: get, post, put, delete, patch) // 非必填
  "rawHeaders"?: object // 非必填
  "rawParametersSchema"?: object // 非必填
  "functionCode"?: string // 非必填
  "mcpUrl"?: string // 非必填
  "mcpAllowedTools"?: object // 非必填
  "rawMcpHeader"?: object // 當 Contact 沒有對應的 MCP Credential 時，將使用此預設標頭 (非必填)
  "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. (非必填)
  "groups"?: [ // Groups this tool is assigned to. Non-owner members must pick at least one group they belong to. (非必填)
    {
      "id": string (uuid)
    }
  ]
}

請求範例值

{
  "name": "範例名稱",
  "displayName": "範例字串",
  "description": "範例字串",
  "prompt": "範例字串",
  "toolType": {},
  "apiUrl": "https://example.com/file.jpg",
  "httpMethod": null,
  "rawHeaders": null,
  "rawParametersSchema": null,
  "functionCode": "範例字串",
  "mcpUrl": "範例字串",
  "mcpAllowedTools": null,
  "rawMcpHeader": null,
  "flexTemplateJson": null,
  "flexSchema": null,
  "quickReplyConfig": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ]
}

程式碼範例

Shell/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": "範例名稱",
    "displayName": "範例字串",
    "description": "範例字串",
    "prompt": "範例字串",
    "toolType": {},
    "apiUrl": "https://example.com/file.jpg",
    "httpMethod": null,
    "rawHeaders": null,
    "rawParametersSchema": null,
    "functionCode": "範例字串",
    "mcpUrl": "範例字串",
    "mcpAllowedTools": null,
    "rawMcpHeader": null,
    "flexTemplateJson": null,
    "flexSchema": null,
    "quickReplyConfig": null,
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ]
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 201

回應結構範例

{
  "id": string (uuid)
  "name"?: string // 工具名稱只能包含英文字母、數字、底線(_)和連字符(-)。MCP 類型工具不需要此欄位，此欄位將用於 API 類型工具給 LLM 使用。 (非必填)
  "displayName": string // 可包含任何字符的名稱，供使用者設定使用和管理。
  "description"?: string // 給用戶展示的工具描述。MCP 類型工具不需要此欄位。 (非必填)
  "prompt"?: string // 給 LLM 使用的工具描述/提示詞。若為空，系統將使用 description 欄位。MCP 類型工具不需要此欄位。 (非必填)
  "toolType"?:  // 非必填
  {
  }
  "apiUrl"?: string (uri) // 非必填
  "httpMethod"?: // 可能有不同的類型 (非必填)
  string (enum: get, post, put, delete, patch) // 非必填
  "rawHeaders"?: 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 // 非必填
  "mcpAllowedTools"?: object // 非必填
  "rawMcpHeader"?: object // 當 Contact 沒有對應的 MCP Credential 時，將使用此預設標頭 (非必填)
  "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. (非必填)
  "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.
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "displayName": "回應字串",
  "description": "回應字串",
  "prompt": "回應字串",
  "toolType": {},
  "apiUrl": "https://example.com/file.jpg",
  "httpMethod": "get",
  "rawHeaders": null,
  "rawParametersSchema": null,
  "functionCode": "回應字串",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": "550e8400-e29b-41d4-a716-446655440000",
  "isGlobal": false,
  "mcpUrl": "回應字串",
  "mcpAllowedTools": null,
  "rawMcpHeader": null,
  "flexTemplateJson": null,
  "flexSchema": null,
  "quickReplyConfig": null,
  "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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "name"?: string // 工具名稱只能包含英文字母、數字、底線(_)和連字符(-)。MCP 類型工具不需要此欄位，此欄位將用於 API 類型工具給 LLM 使用。 (非必填)
      "displayName": string // 可包含任何字符的名稱，供使用者設定使用和管理。
      "description"?: string // 給用戶展示的工具描述。MCP 類型工具不需要此欄位。 (非必填)
      "prompt"?: string // 給 LLM 使用的工具描述/提示詞。若為空，系統將使用 description 欄位。MCP 類型工具不需要此欄位。 (非必填)
      "toolType"?:  // 非必填
      {
      }
      "apiUrl"?: string (uri) // 非必填
      "httpMethod"?: // 可能有不同的類型 (非必填)
      string (enum: get, post, put, delete, patch) // 非必填
      "rawHeaders"?: 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 // 非必填
      "mcpAllowedTools"?: object // 非必填
      "rawMcpHeader"?: object // 當 Contact 沒有對應的 MCP Credential 時，將使用此預設標頭 (非必填)
      "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. (非必填)
      "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.
    }
  ]
}

回應範例值

{
  "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": {},
      "apiUrl": "https://example.com/file.jpg",
      "httpMethod": "get",
      "rawHeaders": null,
      "rawParametersSchema": null,
      "functionCode": "回應字串",
      "organization": "550e8400-e29b-41d4-a716-446655440000",
      "createdBy": "550e8400-e29b-41d4-a716-446655440000",
      "isGlobal": false,
      "mcpUrl": "回應字串",
      "mcpAllowedTools": null,
      "rawMcpHeader": null,
      "flexTemplateJson": null,
      "flexSchema": null,
      "quickReplyConfig": null,
      "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 工具.

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "name"?: string // 工具名稱只能包含英文字母、數字、底線(_)和連字符(-)。MCP 類型工具不需要此欄位，此欄位將用於 API 類型工具給 LLM 使用。 (非必填)
  "displayName": string // 可包含任何字符的名稱，供使用者設定使用和管理。
  "description"?: string // 給用戶展示的工具描述。MCP 類型工具不需要此欄位。 (非必填)
  "prompt"?: string // 給 LLM 使用的工具描述/提示詞。若為空，系統將使用 description 欄位。MCP 類型工具不需要此欄位。 (非必填)
  "toolType"?:  // 非必填
  {
  }
  "apiUrl"?: string (uri) // 非必填
  "httpMethod"?: // 可能有不同的類型 (非必填)
  string (enum: get, post, put, delete, patch) // 非必填
  "rawHeaders"?: 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 // 非必填
  "mcpAllowedTools"?: object // 非必填
  "rawMcpHeader"?: object // 當 Contact 沒有對應的 MCP Credential 時，將使用此預設標頭 (非必填)
  "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. (非必填)
  "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.
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "displayName": "回應字串",
  "description": "回應字串",
  "prompt": "回應字串",
  "toolType": {},
  "apiUrl": "https://example.com/file.jpg",
  "httpMethod": "get",
  "rawHeaders": null,
  "rawParametersSchema": null,
  "functionCode": "回應字串",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": "550e8400-e29b-41d4-a716-446655440000",
  "isGlobal": false,
  "mcpUrl": "回應字串",
  "mcpAllowedTools": null,
  "rawMcpHeader": null,
  "flexTemplateJson": null,
  "flexSchema": null,
  "quickReplyConfig": null,
  "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 工具.

請求內容

請求參數

欄位	類型	必填	說明
name	string	否	工具名稱只能包含英文字母、數字、底線(_)和連字符(-)。MCP 類型工具不需要此欄位，此欄位將用於 API 類型工具給 LLM 使用。
displayName	string	是	可包含任何字符的名稱，供使用者設定使用和管理。
description	string	否	給用戶展示的工具描述。MCP 類型工具不需要此欄位。
prompt	string	否	給 LLM 使用的工具描述/提示詞。若為空，系統將使用 description 欄位。MCP 類型工具不需要此欄位。
toolType	object	否
apiUrl	string (uri)	否
httpMethod	object	否
rawHeaders	object	否
rawParametersSchema	object	否
functionCode	string	否
mcpUrl	string	否
mcpAllowedTools	object	否
rawMcpHeader	object	否	當 Contact 沒有對應的 MCP Credential 時，將使用此預設標頭
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.
groups	array[IdName]	否	Groups this tool is assigned to. Non-owner members must pick at least one group they belong to.

請求結構範例

{
  "name"?: string // 工具名稱只能包含英文字母、數字、底線(_)和連字符(-)。MCP 類型工具不需要此欄位，此欄位將用於 API 類型工具給 LLM 使用。 (非必填)
  "displayName": string // 可包含任何字符的名稱，供使用者設定使用和管理。
  "description"?: string // 給用戶展示的工具描述。MCP 類型工具不需要此欄位。 (非必填)
  "prompt"?: string // 給 LLM 使用的工具描述/提示詞。若為空，系統將使用 description 欄位。MCP 類型工具不需要此欄位。 (非必填)
  "toolType"?:  // 非必填
  {
  }
  "apiUrl"?: string (uri) // 非必填
  "httpMethod"?: // 可能有不同的類型 (非必填)
  string (enum: get, post, put, delete, patch) // 非必填
  "rawHeaders"?: object // 非必填
  "rawParametersSchema"?: object // 非必填
  "functionCode"?: string // 非必填
  "mcpUrl"?: string // 非必填
  "mcpAllowedTools"?: object // 非必填
  "rawMcpHeader"?: object // 當 Contact 沒有對應的 MCP Credential 時，將使用此預設標頭 (非必填)
  "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. (非必填)
  "groups"?: [ // Groups this tool is assigned to. Non-owner members must pick at least one group they belong to. (非必填)
    {
      "id": string (uuid)
    }
  ]
}

請求範例值

{
  "name": "範例名稱",
  "displayName": "範例字串",
  "description": "範例字串",
  "prompt": "範例字串",
  "toolType": {},
  "apiUrl": "https://example.com/file.jpg",
  "httpMethod": null,
  "rawHeaders": null,
  "rawParametersSchema": null,
  "functionCode": "範例字串",
  "mcpUrl": "範例字串",
  "mcpAllowedTools": null,
  "rawMcpHeader": null,
  "flexTemplateJson": null,
  "flexSchema": null,
  "quickReplyConfig": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ]
}

程式碼範例

Shell/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": "範例名稱",
    "displayName": "範例字串",
    "description": "範例字串",
    "prompt": "範例字串",
    "toolType": {},
    "apiUrl": "https://example.com/file.jpg",
    "httpMethod": null,
    "rawHeaders": null,
    "rawParametersSchema": null,
    "functionCode": "範例字串",
    "mcpUrl": "範例字串",
    "mcpAllowedTools": null,
    "rawMcpHeader": null,
    "flexTemplateJson": null,
    "flexSchema": null,
    "quickReplyConfig": null,
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ]
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "name"?: string // 工具名稱只能包含英文字母、數字、底線(_)和連字符(-)。MCP 類型工具不需要此欄位，此欄位將用於 API 類型工具給 LLM 使用。 (非必填)
  "displayName": string // 可包含任何字符的名稱，供使用者設定使用和管理。
  "description"?: string // 給用戶展示的工具描述。MCP 類型工具不需要此欄位。 (非必填)
  "prompt"?: string // 給 LLM 使用的工具描述/提示詞。若為空，系統將使用 description 欄位。MCP 類型工具不需要此欄位。 (非必填)
  "toolType"?:  // 非必填
  {
  }
  "apiUrl"?: string (uri) // 非必填
  "httpMethod"?: // 可能有不同的類型 (非必填)
  string (enum: get, post, put, delete, patch) // 非必填
  "rawHeaders"?: 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 // 非必填
  "mcpAllowedTools"?: object // 非必填
  "rawMcpHeader"?: object // 當 Contact 沒有對應的 MCP Credential 時，將使用此預設標頭 (非必填)
  "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. (非必填)
  "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.
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "displayName": "回應字串",
  "description": "回應字串",
  "prompt": "回應字串",
  "toolType": {},
  "apiUrl": "https://example.com/file.jpg",
  "httpMethod": "get",
  "rawHeaders": null,
  "rawParametersSchema": null,
  "functionCode": "回應字串",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": "550e8400-e29b-41d4-a716-446655440000",
  "isGlobal": false,
  "mcpUrl": "回應字串",
  "mcpAllowedTools": null,
  "rawMcpHeader": null,
  "flexTemplateJson": null,
  "flexSchema": null,
  "quickReplyConfig": null,
  "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 工具.

請求內容

請求參數

欄位	類型	必填	說明
name	string	否	工具名稱只能包含英文字母、數字、底線(_)和連字符(-)。MCP 類型工具不需要此欄位，此欄位將用於 API 類型工具給 LLM 使用。
displayName	string	否	可包含任何字符的名稱，供使用者設定使用和管理。
description	string	否	給用戶展示的工具描述。MCP 類型工具不需要此欄位。
prompt	string	否	給 LLM 使用的工具描述/提示詞。若為空，系統將使用 description 欄位。MCP 類型工具不需要此欄位。
toolType	object	否
apiUrl	string (uri)	否
httpMethod	object	否
rawHeaders	object	否
rawParametersSchema	object	否
functionCode	string	否
mcpUrl	string	否
mcpAllowedTools	object	否
rawMcpHeader	object	否	當 Contact 沒有對應的 MCP Credential 時，將使用此預設標頭
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.
groups	array[IdName]	否	Groups this tool is assigned to. Non-owner members must pick at least one group they belong to.

請求結構範例

{
  "name"?: string // 工具名稱只能包含英文字母、數字、底線(_)和連字符(-)。MCP 類型工具不需要此欄位，此欄位將用於 API 類型工具給 LLM 使用。 (非必填)
  "displayName"?: string // 可包含任何字符的名稱，供使用者設定使用和管理。 (非必填)
  "description"?: string // 給用戶展示的工具描述。MCP 類型工具不需要此欄位。 (非必填)
  "prompt"?: string // 給 LLM 使用的工具描述/提示詞。若為空，系統將使用 description 欄位。MCP 類型工具不需要此欄位。 (非必填)
  "toolType"?:  // 非必填
  {
  }
  "apiUrl"?: string (uri) // 非必填
  "httpMethod"?: // 可能有不同的類型 (非必填)
  string (enum: get, post, put, delete, patch) // 非必填
  "rawHeaders"?: object // 非必填
  "rawParametersSchema"?: object // 非必填
  "functionCode"?: string // 非必填
  "mcpUrl"?: string // 非必填
  "mcpAllowedTools"?: object // 非必填
  "rawMcpHeader"?: object // 當 Contact 沒有對應的 MCP Credential 時，將使用此預設標頭 (非必填)
  "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. (非必填)
  "groups"?: [ // Groups this tool is assigned to. Non-owner members must pick at least one group they belong to. (非必填)
    {
      "id": string (uuid)
    }
  ]
}

請求範例值

{
  "name": "範例名稱",
  "displayName": "範例字串",
  "description": "範例字串",
  "prompt": "範例字串",
  "toolType": {},
  "apiUrl": "https://example.com/file.jpg",
  "httpMethod": null,
  "rawHeaders": null,
  "rawParametersSchema": null,
  "functionCode": "範例字串",
  "mcpUrl": "範例字串",
  "mcpAllowedTools": null,
  "rawMcpHeader": null,
  "flexTemplateJson": null,
  "flexSchema": null,
  "quickReplyConfig": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ]
}

程式碼範例

Shell/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": "範例名稱",
    "displayName": "範例字串",
    "description": "範例字串",
    "prompt": "範例字串",
    "toolType": {},
    "apiUrl": "https://example.com/file.jpg",
    "httpMethod": null,
    "rawHeaders": null,
    "rawParametersSchema": null,
    "functionCode": "範例字串",
    "mcpUrl": "範例字串",
    "mcpAllowedTools": null,
    "rawMcpHeader": null,
    "flexTemplateJson": null,
    "flexSchema": null,
    "quickReplyConfig": null,
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ]
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "name"?: string // 工具名稱只能包含英文字母、數字、底線(_)和連字符(-)。MCP 類型工具不需要此欄位，此欄位將用於 API 類型工具給 LLM 使用。 (非必填)
  "displayName": string // 可包含任何字符的名稱，供使用者設定使用和管理。
  "description"?: string // 給用戶展示的工具描述。MCP 類型工具不需要此欄位。 (非必填)
  "prompt"?: string // 給 LLM 使用的工具描述/提示詞。若為空，系統將使用 description 欄位。MCP 類型工具不需要此欄位。 (非必填)
  "toolType"?:  // 非必填
  {
  }
  "apiUrl"?: string (uri) // 非必填
  "httpMethod"?: // 可能有不同的類型 (非必填)
  string (enum: get, post, put, delete, patch) // 非必填
  "rawHeaders"?: 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 // 非必填
  "mcpAllowedTools"?: object // 非必填
  "rawMcpHeader"?: object // 當 Contact 沒有對應的 MCP Credential 時，將使用此預設標頭 (非必填)
  "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. (非必填)
  "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.
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "displayName": "回應字串",
  "description": "回應字串",
  "prompt": "回應字串",
  "toolType": {},
  "apiUrl": "https://example.com/file.jpg",
  "httpMethod": "get",
  "rawHeaders": null,
  "rawParametersSchema": null,
  "functionCode": "回應字串",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": "550e8400-e29b-41d4-a716-446655440000",
  "isGlobal": false,
  "mcpUrl": "回應字串",
  "mcpAllowedTools": null,
  "rawMcpHeader": null,
  "flexTemplateJson": null,
  "flexSchema": null,
  "quickReplyConfig": null,
  "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 工具.

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼	說明
204	No response body

---

列出可用工具

GET /api/v1/tools/available-tools/

參數

參數名稱	必填	類型	說明
availableTools	✅	array	所有可用的MCP工具列表
mcpAllowedTools	❌	array	MCP 允許使用的工具列表
mcpUrl	✅	string	MCP 伺服器 URL（必填）
rawMcpHeader	❌		MCP Header（JSON 格式）
toolId	❌	string	Tool ID for per-member OAuth token lookup

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/tools/available-tools/?availableTools=example&mcpAllowedTools=example&mcpUrl=example&rawMcpHeader=example&toolId=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

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

回應範例值

{
  "mcpUrl": "回應字串",
  "rawMcpHeader": null,
  "mcpAllowedTools": [
    "回應字串"
  ],
  "toolId": "550e8400-e29b-41d4-a716-446655440000",
  "availableTools": [
    "回應字串"
  ]
}

狀態碼: 400

回應結構範例

{
  "detail"?: string // 非必填
}

回應範例值

{
  "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)
authHeaders	object	否	Authentication headers for Service Account MCP servers (auth_type=service_account).
isEnabled	boolean	否	Whether this connector is enabled for contacts in the organization

請求結構範例

{
  "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) (非必填)
  "authHeaders"?: object // Authentication headers for Service Account MCP servers (auth_type=service_account). (非必填)
  "isEnabled"?: boolean // Whether this connector is enabled for contacts in the organization (非必填)
}

請求範例值

{
  "mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
  "displayName": "範例字串",
  "description": "範例字串",
  "authHeaders": null,
  "isEnabled": true
}

程式碼範例

Shell/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": "範例字串",
    "authHeaders": null,
    "isEnabled": true
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 201

回應結構範例

{
  "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) // CDN URL for the MCP service logo (for frontend rendering) (非必填)
    "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) (非必填)
  "effectiveDescription": string
  "remoteMcpUrl": string
  "oauthServerUrl": string
  "logoUrl": string
  "authType": string
  "authHeaders"?: object // Authentication headers for Service Account MCP servers (auth_type=service_account). (非必填)
  "isEnabled"?: boolean // Whether this connector is enabled for contacts in the organization (非必填)
  "organization": string (uuid)
  "createdBy": string (uuid)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "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": "回應字串",
  "effectiveDescription": "回應字串",
  "remoteMcpUrl": "回應字串",
  "oauthServerUrl": "回應字串",
  "logoUrl": "回應字串",
  "authType": "回應字串",
  "authHeaders": null,
  "isEnabled": false,
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": "550e8400-e29b-41d4-a716-446655440000",
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}

---

列出連接器

GET /api/v1/connectors/

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/connectors/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

[
  {
    "id": string (uuid)
    "displayName"?: string // Custom display name for this connector (defaults to MCP Registry name) (非必填)
    "mcpRegistryName": string
    "mcpRegistryId": string
    "logoUrl": string
    "isEnabled"?: boolean // Whether this connector is enabled for contacts in the organization (非必填)
    "authHeadersMasked": object
    "authorizedMembersCount": integer
    "createdBy": 
    {
      "id": string (uuid)
      "name": string
    }
    "createdAt": string (timestamp)
    "updatedAt": string (timestamp)
  }
]

回應範例值

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "displayName": "回應字串",
    "mcpRegistryName": "回應字串",
    "mcpRegistryId": "回應字串",
    "logoUrl": "回應字串",
    "isEnabled": false,
    "authHeadersMasked": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應範例名稱",
      "description": "回應範例描述"
    },
    "authorizedMembersCount": 456,
    "createdBy": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    },
    "createdAt": "回應字串",
    "updatedAt": "回應字串"
  }
]

---

取得特定連接器

GET /api/v1/connectors/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "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) // CDN URL for the MCP service logo (for frontend rendering) (非必填)
    "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) (非必填)
  "effectiveDescription": string
  "remoteMcpUrl": string
  "oauthServerUrl": string
  "logoUrl": string
  "authType": string
  "authHeaders"?: object // Authentication headers for Service Account MCP servers (auth_type=service_account). (非必填)
  "isEnabled"?: boolean // Whether this connector is enabled for contacts in the organization (非必填)
  "organization": string (uuid)
  "createdBy": string (uuid)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "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": "回應字串",
  "effectiveDescription": "回應字串",
  "remoteMcpUrl": "回應字串",
  "oauthServerUrl": "回應字串",
  "logoUrl": "回應字串",
  "authType": "回應字串",
  "authHeaders": 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)
authHeaders	object	否	Authentication headers for Service Account MCP servers (auth_type=service_account).
isEnabled	boolean	否	Whether this connector is enabled for contacts in the organization

請求結構範例

{
  "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) (非必填)
  "authHeaders"?: object // Authentication headers for Service Account MCP servers (auth_type=service_account). (非必填)
  "isEnabled"?: boolean // Whether this connector is enabled for contacts in the organization (非必填)
}

請求範例值

{
  "mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
  "displayName": "範例字串",
  "description": "範例字串",
  "authHeaders": null,
  "isEnabled": true
}

程式碼範例

Shell/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": "範例字串",
    "authHeaders": null,
    "isEnabled": true
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "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) // CDN URL for the MCP service logo (for frontend rendering) (非必填)
    "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) (非必填)
  "effectiveDescription": string
  "remoteMcpUrl": string
  "oauthServerUrl": string
  "logoUrl": string
  "authType": string
  "authHeaders"?: object // Authentication headers for Service Account MCP servers (auth_type=service_account). (非必填)
  "isEnabled"?: boolean // Whether this connector is enabled for contacts in the organization (非必填)
  "organization": string (uuid)
  "createdBy": string (uuid)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "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": "回應字串",
  "effectiveDescription": "回應字串",
  "remoteMcpUrl": "回應字串",
  "oauthServerUrl": "回應字串",
  "logoUrl": "回應字串",
  "authType": "回應字串",
  "authHeaders": 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)
authHeaders	object	否	Authentication headers for Service Account MCP servers (auth_type=service_account).
isEnabled	boolean	否	Whether this connector is enabled for contacts in the organization

請求結構範例

{
  "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) (非必填)
  "authHeaders"?: object // Authentication headers for Service Account MCP servers (auth_type=service_account). (非必填)
  "isEnabled"?: boolean // Whether this connector is enabled for contacts in the organization (非必填)
}

請求範例值

{
  "mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
  "displayName": "範例字串",
  "description": "範例字串",
  "authHeaders": null,
  "isEnabled": true
}

程式碼範例

Shell/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": "範例字串",
    "authHeaders": null,
    "isEnabled": true
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "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) // CDN URL for the MCP service logo (for frontend rendering) (非必填)
    "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) (非必填)
  "effectiveDescription": string
  "remoteMcpUrl": string
  "oauthServerUrl": string
  "logoUrl": string
  "authType": string
  "authHeaders"?: object // Authentication headers for Service Account MCP servers (auth_type=service_account). (非必填)
  "isEnabled"?: boolean // Whether this connector is enabled for contacts in the organization (非必填)
  "organization": string (uuid)
  "createdBy": string (uuid)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "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": "回應字串",
  "effectiveDescription": "回應字串",
  "remoteMcpUrl": "回應字串",
  "oauthServerUrl": "回應字串",
  "logoUrl": "回應字串",
  "authType": "回應字串",
  "authHeaders": null,
  "isEnabled": false,
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": "550e8400-e29b-41d4-a716-446655440000",
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}

---

刪除連接器

DELETE /api/v1/connectors/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼	說明
204	No response body

---

列出連接器授權成員

GET /api/v1/connectors/{id}/authorized-members/

參數

參數名稱	必填	類型	說明
id	✅	string

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "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) // CDN URL for the MCP service logo (for frontend rendering) (非必填)
    "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) (非必填)
  "effectiveDescription": string
  "remoteMcpUrl": string
  "oauthServerUrl": string
  "logoUrl": string
  "authType": string
  "authHeaders"?: object // Authentication headers for Service Account MCP servers (auth_type=service_account). (非必填)
  "isEnabled"?: boolean // Whether this connector is enabled for contacts in the organization (非必填)
  "organization": string (uuid)
  "createdBy": string (uuid)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}

回應範例值

{
  "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": "回應字串",
  "effectiveDescription": "回應字串",
  "remoteMcpUrl": "回應字串",
  "oauthServerUrl": "回應字串",
  "logoUrl": "回應字串",
  "authType": "回應字串",
  "authHeaders": 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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼	說明
204	No response body

---

列出 MCP 工具登錄

GET /api/v1/mcp/registry/

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/mcp/registry/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

[
  {
    "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) // CDN URL for the MCP service logo (for frontend rendering) (非必填)
    "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)
  }
]

回應範例值

[
  {
    "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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "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) // CDN URL for the MCP service logo (for frontend rendering) (非必填)
  "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)
}

回應範例值

{
  "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": "回應字串"
}

---

取得工具執行紀錄列表

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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "tool": object // 獲取工具資訊
      "chatbot": object // 獲取 AI 助理資訊
      "messageContent": string // 獲取訊息內容
      "status"?:  // 非必填
      {
      }
      "executionTime": integer // 獲取執行時間（毫秒）
      "errorMessage"?: string // 非必填
      "createdAt": string (timestamp)
    }
  ]
}

回應範例值

{
  "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": {},
      "executionTime": 456,
      "errorMessage": "回應字串",
      "createdAt": "回應字串"
    }
  ]
}

---

取得特定工具執行紀錄

GET /api/v1/tool-execution-records/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this 工具執行記錄.

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "tool": object // 獲取工具資訊，並包含 operated_tool_name
  "chatbot": object // 獲取 AI 助理資訊
  "message": 
  {
    "id": string (uuid)
    "content": string
  }
  "inputParameters": object
  "outputResult"?: object // 非必填
  "errorMessage"?: string // 非必填
  "status"?:  // 非必填
  {
  }
  "executionTime": integer // 獲取執行時間（毫秒）
  "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.

APICredential keys for the (contact, tool) pair are masked automatically
in addition to ``settings.TOOL_API_SENSITIVE_HEADERS``.
  "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)
}

回應範例值

{
  "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": {},
  "executionTime": 456,
  "requestUrl": "https://example.com/file.jpg",
  "requestMethod": "回應字串",
  "requestHeaders": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  },
  "requestBody": null,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}

---

取得執行紀錄的 AI 助理過濾選項

GET /api/v1/tool-execution-records/chatbots/

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/tool-execution-records/chatbots/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

[
  {
    "id"?: string (uuid) // 非必填
    "name"?: string // 非必填
  }
]

回應範例值

[
  {
    "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`: 成功 ; `failure`: 失敗 ; `pending`: 處理中 ; `timeout`: 逾時;
tool	❌	string
toolType	❌	string	`api`: API ; `function`: Function ; `mcp`: MCP ; `desktop`: Desktop ; `flex`: Flex Message ; `quick_reply`: Quick Reply;

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "displayName": string
    }
  ]
}

回應範例值

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

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "tool": object // 獲取工具資訊
      "chatbot": object // 獲取 AI 助理資訊
      "messageContent": string // 獲取訊息內容
      "status"?:  // 非必填
      {
      }
      "executionTime": integer // 獲取執行時間（毫秒）
      "errorMessage"?: string // 非必填
      "createdAt": string (timestamp)
    }
  ]
}

回應範例值

{
  "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": {},
      "executionTime": 456,
      "errorMessage": "回應字串",
      "createdAt": "回應字串"
    }
  ]
}

---

取得特定工具的特定執行紀錄

GET /api/v1/tools/{toolPk}/tool-execution-records/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this 工具執行記錄.
toolPk	✅	string

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "tool": object // 獲取工具資訊，並包含 operated_tool_name
  "chatbot": object // 獲取 AI 助理資訊
  "message": 
  {
    "id": string (uuid)
    "content": string
  }
  "inputParameters": object
  "outputResult"?: object // 非必填
  "errorMessage"?: string // 非必填
  "status"?:  // 非必填
  {
  }
  "executionTime": integer // 獲取執行時間（毫秒）
  "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.

APICredential keys for the (contact, tool) pair are masked automatically
in addition to ``settings.TOOL_API_SENSITIVE_HEADERS``.
  "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)
}

回應範例值

{
  "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": {},
  "executionTime": 456,
  "requestUrl": "https://example.com/file.jpg",
  "requestMethod": "回應字串",
  "requestHeaders": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應範例名稱",
    "description": "回應範例描述"
  },
  "requestBody": null,
  "createdAt": "回應字串",
  "updatedAt": "回應字串"
}

---

取得特定工具執行紀錄的 AI 助理過濾選項

GET /api/v1/tools/{toolPk}/tool-execution-records/chatbots/

參數

參數名稱	必填	類型	說明
toolPk	✅	string

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/tool-execution-records/chatbots/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

[
  {
    "id"?: string (uuid) // 非必填
    "name"?: string // 非必填
  }
]

回應範例值

[
  {
    "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`: 成功 ; `failure`: 失敗 ; `pending`: 處理中 ; `timeout`: 逾時;
tool	❌	string
toolType	❌	string	`api`: API ; `function`: Function ; `mcp`: MCP ; `desktop`: Desktop ; `flex`: Flex Message ; `quick_reply`: Quick Reply;

程式碼範例

Shell/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 並核對請求資料。

JavaScript

Python

PHP

回應內容

狀態碼: 200

回應結構範例

{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "displayName": string
    }
  ]
}

回應範例值

{
  "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": "回應字串"
    }
  ]
}

---