> 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/en/api-reference/gong-ju-he-lian-jie-qi.md).

# Tools and Connectors

### Create a tool <a href="#tools-create" id="tools-create"></a>

POST `/api/v1/tools/`

#### Request body

**Request parameters**

| Field                        | Type                                                                                                                                                                                                              | Required | Description                                                                                                                                                                                                   |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name                         | object                                                                                                                                                                                                            | No       | 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                                                                                                                                                                                                            | Yes      | A name with any characters, used by users for configuration and management.                                                                                                                                   |
| description                  | string                                                                                                                                                                                                            | No       | Tool description shown to users. Not required for MCP tools.                                                                                                                                                  |
| prompt                       | string                                                                                                                                                                                                            | No       | 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)                                                                                                                                       | No       | `api`: API ; `function`: Function ; `mcp`: MCP ; `desktop`: Desktop ; `flex`: Flex Message ; `quick_reply`: Quick Reply ; `quick_menu`: Quick Menu;                                                           |
| apiUrl                       | string                                                                                                                                                                                                            | No       |                                                                                                                                                                                                               |
| httpMethod                   | object                                                                                                                                                                                                            | No       |                                                                                                                                                                                                               |
| rawHeaders                   | object                                                                                                                                                                                                            | No       |                                                                                                                                                                                                               |
| sensitiveHeaders             | array\[string]                                                                                                                                                                                                    | No       |                                                                                                                                                                                                               |
| rawQueryParams               | object                                                                                                                                                                                                            | No       | 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                                                                                                                                                                                                            | No       |                                                                                                                                                                                                               |
| functionCode                 | string                                                                                                                                                                                                            | No       |                                                                                                                                                                                                               |
| mcpUrl                       | string                                                                                                                                                                                                            | No       |                                                                                                                                                                                                               |
| mcpRegistry                  | string (uuid)                                                                                                                                                                                                     | No       | Registry backing this MCP tool. Null for manual-URL MCP tools.                                                                                                                                                |
| mcpAllowedTools              | object                                                                                                                                                                                                            | No       |                                                                                                                                                                                                               |
| rawMcpHeader                 | object                                                                                                                                                                                                            | No       | Default headers used when the Contact has no matching MCP Credential.                                                                                                                                         |
| authSubject                  | object                                                                                                                                                                                                            | No       | 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                                                                                                                                                                                                            | No       | FlexMessage JSON template. Required for FLEX\_MESSAGE tools. Stores the full LINE FlexMessage JSON structure (bubble / carousel / box / text / image / button etc.).                                          |
| flexSchema                   | object                                                                                                                                                                                                            | No       | 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                                                                                                                                                                                                            | No       | 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                                                                                                                                                                                                            | No       | 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) | No       | `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                                                                                                                                                                                                            | No       |                                                                                                                                                                                                               |
| outputRenderTemplateByLocale | object                                                                                                                                                                                                            | No       |                                                                                                                                                                                                               |
| toolDisplayMode              | object                                                                                                                                                                                                            | No       |                                                                                                                                                                                                               |
| groups                       | array\[IdName]                                                                                                                                                                                                    | No       | Groups this tool is assigned to. Non-owner members must pick at least one group they belong to.                                                                                                               |

**Example request structure**

```typescript
{
  "name"?: // May have different types (optional)
  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. (optional)
  "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. (optional)
  "prompt"?: string // Tool description/prompt given to the LLM. If empty, the description field is used. Not required for MCP tools. (optional)
  "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 (optional)
  "apiUrl"?: string // optional
  "httpMethod"?: // May have different types (optional)
  string (enum: get, post, put, delete, patch) // optional
  "rawHeaders"?: object // optional
  "sensitiveHeaders"?: [ // optional
    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. (optional)
  "rawParametersSchema"?: object // optional
  "functionCode"?: string // optional
  "mcpUrl"?: string // optional
  "mcpRegistry"?: string (uuid) // Registry backing this MCP tool. Null for manual-URL MCP tools. (optional)
  "mcpAllowedTools"?: object // optional
  "rawMcpHeader"?: object // Default headers used when the Contact has no matching MCP Credential. (optional)
  "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 (optional)
  {
  }
  "flexTemplateJson"?: object // FlexMessage JSON template. Required for FLEX_MESSAGE tools. Stores the full LINE FlexMessage JSON structure (bubble / carousel / box / text / image / button etc.). (optional)
  "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. (optional)
  "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. (optional)
  "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). (optional)
  "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) (optional)
  "displayCopyByLocale"?: object // optional
  "outputRenderTemplateByLocale"?: object // optional
  "toolDisplayMode"?: // May have different types (optional)
  string (enum: full, compact, hidden) // optional
  "groups"?: [ // Groups this tool is assigned to. Non-owner members must pick at least one group they belong to. (optional)
    {
      "id": string (uuid)
    }
  ]
}
```

**Example request values**

```json
{
  "name": null,
  "displayName": "Example string",
  "description": "Example string",
  "prompt": "Example string",
  "toolType": "api",
  "apiUrl": "Example string",
  "httpMethod": null,
  "rawHeaders": null,
  "sensitiveHeaders": [
    "Example string"
  ],
  "rawQueryParams": null,
  "rawParametersSchema": null,
  "functionCode": "Example string",
  "mcpUrl": "Example string",
  "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"
    }
  ]
}
```

#### Code examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (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": "Example string",
    "description": "Example string",
    "prompt": "Example string",
    "toolType": "api",
    "apiUrl": "Example string",
    "httpMethod": null,
    "rawHeaders": null,
    "sensitiveHeaders": [
      "Example string"
    ],
    "rawQueryParams": null,
    "rawParametersSchema": null,
    "functionCode": "Example string",
    "mcpUrl": "Example string",
    "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"
      }
    ]
  }'

# Before running, replace YOUR_API_KEY and verify the request data.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// Request payload
const data = {
    "name": null,
    "displayName": "Example string",
    "description": "Example string",
    "prompt": "Example string",
    "toolType": "api",
    "apiUrl": "Example string",
    "httpMethod": null,
    "rawHeaders": null,
    "sensitiveHeaders": [
      "Example string"
    ],
    "rawQueryParams": null,
    "rawParametersSchema": null,
    "functionCode": "Example string",
    "mcpUrl": "Example string",
    "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('Response retrieved successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('An error occurred during the request:');
    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"
}

# Request payload
data = {
    "name": None,
    "displayName": "Example string",
    "description": "Example string",
    "prompt": "Example string",
    "toolType": "api",
    "apiUrl": "Example string",
    "httpMethod": None,
    "rawHeaders": None,
    "sensitiveHeaders": [
        "Example string"
    ],
    "rawQueryParams": None,
    "rawParametersSchema": None,
    "functionCode": "Example string",
    "mcpUrl": "Example string",
    "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("Response retrieved successfully:")
    print(response.json())
except Exception as e:
    print("An error occurred during the request:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/tools/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'name' => null,
            'displayName' => 'Example string',
            'description' => 'Example string',
            'prompt' => 'Example string',
            'toolType' => 'api',
            'apiUrl' => 'Example string',
            'httpMethod' => null,
            'rawHeaders' => null,
            'sensitiveHeaders' => [
                'Example string'
            ],
            'rawQueryParams' => null,
            'rawParametersSchema' => null,
            'functionCode' => 'Example string',
            'mcpUrl' => 'Example string',
            '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 "Response retrieved successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'An error occurred during the request: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response body

**Status code: 201**

**Example response structure**

```typescript
{
  "id": string (uuid)
  "name"?: // May have different types (optional)
  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. (optional)
  "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. (optional)
  "prompt"?: string // Tool description/prompt given to the LLM. If empty, the description field is used. Not required for MCP tools. (optional)
  "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 (optional)
  "apiUrl"?: string // optional
  "httpMethod"?: // May have different types (optional)
  string (enum: get, post, put, delete, patch) // optional
  "rawHeaders"?: object // optional
  "rawHeadersMasked": object
  "sensitiveHeaders"?: [ // optional
    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. (optional)
  "rawQueryParamsMasked": object
  "rawParametersSchema"?: object // optional
  "functionCode"?: string // optional
  "organization": string (uuid)
  "createdBy": string (uuid)
  "isGlobal": boolean // If set as global tool, all organizations can use this tool
  "mcpUrl"?: string // optional
  "mcpRegistry"?: string (uuid) // Registry backing this MCP tool. Null for manual-URL MCP tools. (optional)
  "mcpAllowedTools"?: object // optional
  "rawMcpHeader"?: object // Default headers used when the Contact has no matching MCP Credential. (optional)
  "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 (optional)
  {
  }
  "flexTemplateJson"?: object // FlexMessage JSON template. Required for FLEX_MESSAGE tools. Stores the full LINE FlexMessage JSON structure (bubble / carousel / box / text / image / button etc.). (optional)
  "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. (optional)
  "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. (optional)
  "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). (optional)
  "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) (optional)
  "displayCopyByLocale"?: object // optional
  "outputRenderTemplateByLocale"?: object // optional
  "toolDisplayMode"?: // May have different types (optional)
  string (enum: full, compact, hidden) // optional
  "groups"?: [ // Groups this tool is assigned to. Non-owner members must pick at least one group they belong to. (optional)
    {
      "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.
}
```

**Example response values**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Response string",
  "displayName": "Response string",
  "description": "Response string",
  "prompt": "Response string",
  "toolType": "api",
  "apiUrl": "Response string",
  "httpMethod": "get",
  "rawHeaders": null,
  "rawHeadersMasked": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example response name",
    "description": "Example response description"
  },
  "sensitiveHeaders": [
    "Response string"
  ],
  "globalSensitiveHeaders": [
    "Response string"
  ],
  "rawQueryParams": null,
  "rawQueryParamsMasked": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example response name",
    "description": "Example response description"
  },
  "rawParametersSchema": null,
  "functionCode": "Response string",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": "550e8400-e29b-41d4-a716-446655440000",
  "isGlobal": false,
  "mcpUrl": "Response string",
  "mcpRegistry": "550e8400-e29b-41d4-a716-446655440000",
  "mcpAllowedTools": null,
  "rawMcpHeader": null,
  "rawMcpHeaderMasked": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example response name",
    "description": "Example response 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": "Response string"
    }
  ],
  "createdAt": "Response string",
  "updatedAt": "Response string",
  "canUpdate": false,
  "canDelete": false
}
```

***

### List tools <a href="#tools-list" id="tools-list"></a>

GET `/api/v1/tools/`

#### Parameters

| Parameter name   | Required | Type    | Description                                                                                                                               |
| ---------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `clientPlatform` | ❌        | string  | Calling client platform. Pass "desktop" to include desktop-type tools; any other value, or omitting it, excludes desktop tools by default |
| `isGlobal`       | ❌        | boolean | Set to "true" to retrieve global tools; otherwise organization tools are retrieved                                                        |
| `page`           | ❌        | integer | A page number within the paginated result set.                                                                                            |
| `pageSize`       | ❌        | integer | Number of results to return per page.                                                                                                     |
| `toolType`       | ❌        | string  | Filter by tool type: api, function, mcp, desktop                                                                                          |

#### Code examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (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"

# Before running, replace YOUR_API_KEY and verify the request data.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
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('Successfully retrieved response:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('An error occurred during the request:');
    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("Successfully retrieved response:")
    print(response.json())
except Exception as e:
    print("An error occurred during the request:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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 "Successfully retrieved response:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'An error occurred during the request: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response Content

**Status Code: 200**

**Example Response Schema**

```typescript
{
  "count": integer
  "next"?: string (uri) // Optional
  "previous"?: string (uri) // Optional
  "results": [
    {
      "id": string (uuid)
      "name"?: // May have different types (Optional)
      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. (Optional)
      "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. (Optional)
      "prompt"?: string // Tool description/prompt given to the LLM. If empty, the description field is used. Not required for MCP tools. (Optional)
      "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 (Optional)
      "apiUrl"?: string // Optional
      "httpMethod"?: // May have different types (Optional)
      string (enum: get, post, put, delete, patch) // Optional
      "rawHeaders"?: object // Optional
      "rawHeadersMasked": object
      "sensitiveHeaders"?: [ // Optional
        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. (Optional)
      "rawQueryParamsMasked": object
      "rawParametersSchema"?: object // Optional
      "functionCode"?: string // Optional
      "organization": string (uuid)
      "createdBy": string (uuid)
      "isGlobal": boolean // If set as global tool, all organizations can use this tool
      "mcpUrl"?: string // Optional
      "mcpRegistry"?: string (uuid) // Registry backing this MCP tool. Null for manual-URL MCP tools. (Optional)
      "mcpAllowedTools"?: object // Optional
      "rawMcpHeader"?: object // Default headers used when the Contact has no matching MCP Credential. (Optional)
      "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 (Optional)
      {
      }
      "flexTemplateJson"?: object // FlexMessage JSON template. Required for FLEX_MESSAGE tools. Stores the full LINE FlexMessage JSON structure (bubble / carousel / box / text / image / button etc.). (Optional)
      "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. (Optional)
      "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. (Optional)
      "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). (Optional)
      "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) (Optional)
      "displayCopyByLocale"?: object // Optional
      "outputRenderTemplateByLocale"?: object // Optional
      "toolDisplayMode"?: // May have different types (Optional)
      string (enum: full, compact, hidden) // Optional
      "groups"?: [ // Groups this tool is assigned to. Non-owner members must pick at least one group they belong to. (Optional)
        {
          "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.
    }
  ]
}
```

**Example Response Values**

```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": "Response String",
      "displayName": "Response String",
      "description": "Response String",
      "prompt": "Response String",
      "toolType": "api",
      "apiUrl": "Response String",
      "httpMethod": "get",
      "rawHeaders": null,
      "rawHeadersMasked": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Example response name",
        "description": "Example response description"
      },
      "sensitiveHeaders": [
        "Response String"
      ],
      "globalSensitiveHeaders": [
        "Response String"
      ],
      "rawQueryParams": null,
      "rawQueryParamsMasked": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Example response name",
        "description": "Example response description"
      },
      "rawParametersSchema": null,
      "functionCode": "Response String",
      "organization": "550e8400-e29b-41d4-a716-446655440000",
      "createdBy": "550e8400-e29b-41d4-a716-446655440000",
      "isGlobal": false,
      "mcpUrl": "Response String",
      "mcpRegistry": "550e8400-e29b-41d4-a716-446655440000",
      "mcpAllowedTools": null,
      "rawMcpHeader": null,
      "rawMcpHeaderMasked": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Example response name",
        "description": "Example response 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": "Response String"
        }
      ],
      "createdAt": "Response String",
      "updatedAt": "Response String",
      "canUpdate": false,
      "canDelete": false
    }
  ]
}
```

***

### Retrieve a Specific Tool <a href="#tools-retrieve" id="tools-retrieve"></a>

GET `/api/v1/tools/{id}/`

#### Parameters

| Parameter Name | Required | Type   | Description                          |
| -------------- | -------- | ------ | ------------------------------------ |
| `id`           | ✅        | string | A UUID string identifying this Tool. |

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API Call Example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
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('Successfully retrieved response:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('An error occurred during the request:');
    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("Successfully retrieved response:")
    print(response.json())
except Exception as e:
    print("An error occurred during the request:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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 "Successfully retrieved response:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'An error occurred during the request: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response Content

**Status Code: 200**

**Example Response Schema**

```typescript
{
  "id": string (uuid)
  "name"?: // May have different types (Optional)
  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. (Optional)
  "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. (Optional)
  "prompt"?: string // Tool description/prompt given to the LLM. If empty, the description field is used. Not required for MCP tools. (Optional)
  "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 (Optional)
  "apiUrl"?: string // Optional
  "httpMethod"?: // May have different types (Optional)
  string (enum: get, post, put, delete, patch) // Optional
  "rawHeaders"?: object // Optional
  "rawHeadersMasked": object
  "sensitiveHeaders"?: [ // Optional
    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. (Optional)
  "rawQueryParamsMasked": object
  "rawParametersSchema"?: object // Optional
  "functionCode"?: string // Optional
  "organization": string (uuid)
  "createdBy": string (uuid)
  "isGlobal": boolean // If set as global tool, all organizations can use this tool
  "mcpUrl"?: string // Optional
  "mcpRegistry"?: string (uuid) // Registry backing this MCP tool. Null for manual-URL MCP tools. (Optional)
  "mcpAllowedTools"?: object // Optional
  "rawMcpHeader"?: object // Default headers used when the Contact has no matching MCP Credential. (Optional)
  "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 (Optional)
  {
  }
  "flexTemplateJson"?: object // FlexMessage JSON template. Required for FLEX_MESSAGE tools. Stores the full LINE FlexMessage JSON structure (bubble / carousel / box / text / image / button etc.). (Optional)
  "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. (Optional)
  "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. (Optional)
  "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). (Optional)
  "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) (Optional)
  "displayCopyByLocale"?: object // Optional
  "outputRenderTemplateByLocale"?: object // Optional
  "toolDisplayMode"?: // May have different types (Optional)
  string (enum: full, compact, hidden) // Optional
  "groups"?: [ // Groups this tool is assigned to. Non-owner members must pick at least one group they belong to. (Optional)
    {
      "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.
}
```

**Example Response Values**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Response String",
  "displayName": "Response String",
  "description": "Response String",
  "prompt": "Response String",
  "toolType": "api",
  "apiUrl": "Response String",
  "httpMethod": "get",
  "rawHeaders": null,
  "rawHeadersMasked": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example response name",
    "description": "Example response description"
  },
  "sensitiveHeaders": [
    "Response String"
  ],
  "globalSensitiveHeaders": [
    "Response String"
  ],
  "rawQueryParams": null,
  "rawQueryParamsMasked": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example response name",
    "description": "Example response description"
  },
  "rawParametersSchema": null,
  "functionCode": "Response String",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": "550e8400-e29b-41d4-a716-446655440000",
  "isGlobal": false,
  "mcpUrl": "Response String",
  "mcpRegistry": "550e8400-e29b-41d4-a716-446655440000",
  "mcpAllowedTools": null,
  "rawMcpHeader": null,
  "rawMcpHeaderMasked": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example response name",
    "description": "Example response 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": "Response String"
    }
  ],
  "createdAt": "Response String",
  "updatedAt": "Response String",
  "canUpdate": false,
  "canDelete": false
}
```

***

### Update a Tool <a href="#tools-update" id="tools-update"></a>

PUT `/api/v1/tools/{id}/`

#### Parameters

| Parameter Name | Required | Type   | Description                          |
| -------------- | -------- | ------ | ------------------------------------ |
| `id`           | ✅        | string | A UUID string identifying this Tool. |

#### Request Body

**Request Parameters**

| Field                        | Type                                                                                                                                                                                                              | Required | Description                                                                                                                                                                                                   |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name                         | object                                                                                                                                                                                                            | No       | 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                                                                                                                                                                                                            | Yes      | A name with any characters, used by users for configuration and management.                                                                                                                                   |
| description                  | string                                                                                                                                                                                                            | No       | Tool description shown to users. Not required for MCP tools.                                                                                                                                                  |
| prompt                       | string                                                                                                                                                                                                            | No       | 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)                                                                                                                                       | No       | `api`: API ; `function`: Function ; `mcp`: MCP ; `desktop`: Desktop ; `flex`: Flex Message ; `quick_reply`: Quick Reply ; `quick_menu`: Quick Menu;                                                           |
| apiUrl                       | string                                                                                                                                                                                                            | No       |                                                                                                                                                                                                               |
| httpMethod                   | object                                                                                                                                                                                                            | No       |                                                                                                                                                                                                               |
| rawHeaders                   | object                                                                                                                                                                                                            | No       |                                                                                                                                                                                                               |
| sensitiveHeaders             | array\[string]                                                                                                                                                                                                    | No       |                                                                                                                                                                                                               |
| rawQueryParams               | object                                                                                                                                                                                                            | No       | 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                                                                                                                                                                                                            | No       |                                                                                                                                                                                                               |
| functionCode                 | string                                                                                                                                                                                                            | No       |                                                                                                                                                                                                               |
| mcpUrl                       | string                                                                                                                                                                                                            | No       |                                                                                                                                                                                                               |
| mcpRegistry                  | string (uuid)                                                                                                                                                                                                     | No       | Registry backing this MCP tool. Null for manual-URL MCP tools.                                                                                                                                                |
| mcpAllowedTools              | object                                                                                                                                                                                                            | No       |                                                                                                                                                                                                               |
| rawMcpHeader                 | object                                                                                                                                                                                                            | No       | Default headers used when the Contact has no matching MCP Credential.                                                                                                                                         |
| authSubject                  | object                                                                                                                                                                                                            | No       | 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                                                                                                                                                                                                            | No       | FlexMessage JSON template. Required for FLEX\_MESSAGE tools. Stores the full LINE FlexMessage JSON structure (bubble / carousel / box / text / image / button etc.).                                          |
| flexSchema                   | object                                                                                                                                                                                                            | No       | 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                                                                                                                                                                                                            | No       | 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                                                                                                                                                                                                            | No       | 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) | No       | `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                                                                                                                                                                                                            | No       |                                                                                                                                                                                                               |
| outputRenderTemplateByLocale | object                                                                                                                                                                                                            | No       |                                                                                                                                                                                                               |
| toolDisplayMode              | object                                                                                                                                                                                                            | No       |                                                                                                                                                                                                               |
| groups                       | array\[IdName]                                                                                                                                                                                                    | No       | Groups this tool is assigned to. Non-owner members must pick at least one group they belong to.                                                                                                               |

**Example Request Schema**

```typescript
{
  "name"?: // May have different types (Optional)
  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. (Optional)
  "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. (Optional)
  "prompt"?: string // Tool description/prompt given to the LLM. If empty, the description field is used. Not required for MCP tools. (Optional)
  "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 (Optional)
  "apiUrl"?: string // Optional
  "httpMethod"?: // May have different types (Optional)
  string (enum: get, post, put, delete, patch) // Optional
  "rawHeaders"?: object // Optional
  "sensitiveHeaders"?: [ // Optional
    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. (Optional)
  "rawParametersSchema"?: object // Optional
  "functionCode"?: string // Optional
  "mcpUrl"?: string // Optional
  "mcpRegistry"?: string (uuid) // Registry backing this MCP tool. Null for manual-URL MCP tools. (Optional)
  "mcpAllowedTools"?: object // Optional
  "rawMcpHeader"?: object // Default headers used when the Contact has no matching MCP Credential. (Optional)
  "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 (Optional)
  {
  }
  "flexTemplateJson"?: object // FlexMessage JSON template. Required for FLEX_MESSAGE tools. Stores the full LINE FlexMessage JSON structure (bubble / carousel / box / text / image / button etc.). (Optional)
  "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. (Optional)
  "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. (Optional)
  "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). (Optional)
  "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) (Optional)
  "displayCopyByLocale"?: object // Optional
  "outputRenderTemplateByLocale"?: object // Optional
  "toolDisplayMode"?: // May have different types (Optional)
  string (enum: full, compact, hidden) // Optional
  "groups"?: [ // Groups this tool is assigned to. Non-owner members must pick at least one group they belong to. (Optional)
    {
      "id": string (uuid)
    }
  ]
}
```

**Example request values**

```json
{
  "name": null,
  "displayName": "Example string",
  "description": "Example string",
  "prompt": "Example string",
  "toolType": "api",
  "apiUrl": "Example string",
  "httpMethod": null,
  "rawHeaders": null,
  "sensitiveHeaders": [
    "Example string"
  ],
  "rawQueryParams": null,
  "rawParametersSchema": null,
  "functionCode": "Example string",
  "mcpUrl": "Example string",
  "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"
    }
  ]
}
```

#### Code examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (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": "Example string",
    "description": "Example string",
    "prompt": "Example string",
    "toolType": "api",
    "apiUrl": "Example string",
    "httpMethod": null,
    "rawHeaders": null,
    "sensitiveHeaders": [
      "Example string"
    ],
    "rawQueryParams": null,
    "rawParametersSchema": null,
    "functionCode": "Example string",
    "mcpUrl": "Example string",
    "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"
      }
    ]
  }'

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// Request body (payload)
const data = {
    "name": null,
    "displayName": "Example string",
    "description": "Example string",
    "prompt": "Example string",
    "toolType": "api",
    "apiUrl": "Example string",
    "httpMethod": null,
    "rawHeaders": null,
    "sensitiveHeaders": [
      "Example string"
    ],
    "rawQueryParams": null,
    "rawParametersSchema": null,
    "functionCode": "Example string",
    "mcpUrl": "Example string",
    "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('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('An error occurred during the request:');
    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"
}

# Request body (payload)
data = {
    "name": None,
    "displayName": "Example string",
    "description": "Example string",
    "prompt": "Example string",
    "toolType": "api",
    "apiUrl": "Example string",
    "httpMethod": None,
    "rawHeaders": None,
    "sensitiveHeaders": [
        "Example string"
    ],
    "rawQueryParams": None,
    "rawParametersSchema": None,
    "functionCode": "Example string",
    "mcpUrl": "Example string",
    "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("Response received successfully:")
    print(response.json())
except Exception as e:
    print("An error occurred during the request:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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' => 'Example string',
            'description' => 'Example string',
            'prompt' => 'Example string',
            'toolType' => 'api',
            'apiUrl' => 'Example string',
            'httpMethod' => null,
            'rawHeaders' => null,
            'sensitiveHeaders' => [
                'Example string'
            ],
            'rawQueryParams' => null,
            'rawParametersSchema' => null,
            'functionCode' => 'Example string',
            'mcpUrl' => 'Example string',
            '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 "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'An error occurred during the request: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response body

**Status code: 200**

**Example response structure**

```typescript
{
  "id": string (uuid)
  "name"?: // May have different types (Optional)
  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. (Optional)
  "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. (Optional)
  "prompt"?: string // Tool description/prompt given to the LLM. If empty, the description field is used. Not required for MCP tools. (Optional)
  "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 (Optional)
  "apiUrl"?: string // Optional
  "httpMethod"?: // May have different types (Optional)
  string (enum: get, post, put, delete, patch) // Optional
  "rawHeaders"?: object // Optional
  "rawHeadersMasked": object
  "sensitiveHeaders"?: [ // Optional
    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. (Optional)
  "rawQueryParamsMasked": object
  "rawParametersSchema"?: object // Optional
  "functionCode"?: string // Optional
  "organization": string (uuid)
  "createdBy": string (uuid)
  "isGlobal": boolean // If set as global tool, all organizations can use this tool
  "mcpUrl"?: string // Optional
  "mcpRegistry"?: string (uuid) // Registry backing this MCP tool. Null for manual-URL MCP tools. (Optional)
  "mcpAllowedTools"?: object // Optional
  "rawMcpHeader"?: object // Default headers used when the Contact has no matching MCP Credential. (Optional)
  "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 (Optional)
  {
  }
  "flexTemplateJson"?: object // FlexMessage JSON template. Required for FLEX_MESSAGE tools. Stores the full LINE FlexMessage JSON structure (bubble / carousel / box / text / image / button etc.). (Optional)
  "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. (Optional)
  "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. (Optional)
  "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). (Optional)
  "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) (Optional)
  "displayCopyByLocale"?: object // Optional
  "outputRenderTemplateByLocale"?: object // Optional
  "toolDisplayMode"?: // May have different types (Optional)
  string (enum: full, compact, hidden) // Optional
  "groups"?: [ // Groups this tool is assigned to. Non-owner members must pick at least one group they belong to. (Optional)
    {
      "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.
}
```

**Example response values**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Response string",
  "displayName": "Response string",
  "description": "Response string",
  "prompt": "Response string",
  "toolType": "api",
  "apiUrl": "Response string",
  "httpMethod": "get",
  "rawHeaders": null,
  "rawHeadersMasked": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example response name",
    "description": "Example response description"
  },
  "sensitiveHeaders": [
    "Response string"
  ],
  "globalSensitiveHeaders": [
    "Response string"
  ],
  "rawQueryParams": null,
  "rawQueryParamsMasked": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example response name",
    "description": "Example response description"
  },
  "rawParametersSchema": null,
  "functionCode": "Response string",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": "550e8400-e29b-41d4-a716-446655440000",
  "isGlobal": false,
  "mcpUrl": "Response string",
  "mcpRegistry": "550e8400-e29b-41d4-a716-446655440000",
  "mcpAllowedTools": null,
  "rawMcpHeader": null,
  "rawMcpHeaderMasked": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example response name",
    "description": "Example response 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": "Response string"
    }
  ],
  "createdAt": "Response string",
  "updatedAt": "Response string",
  "canUpdate": false,
  "canDelete": false
}
```

***

### Partially update a tool <a href="#tools-partial-update" id="tools-partial-update"></a>

PATCH `/api/v1/tools/{id}/`

#### Parameters

| Parameter name | Required | Type   | Description                          |
| -------------- | -------- | ------ | ------------------------------------ |
| `id`           | ✅        | string | A UUID string identifying this Tool. |

#### Request body

**Request parameters**

| Field                        | Type                                                                                                                                                                                                              | Required | Description                                                                                                                                                                                                   |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name                         | object                                                                                                                                                                                                            | No       | 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                                                                                                                                                                                                            | No       | A name with any characters, used by users for configuration and management.                                                                                                                                   |
| description                  | string                                                                                                                                                                                                            | No       | Tool description shown to users. Not required for MCP tools.                                                                                                                                                  |
| prompt                       | string                                                                                                                                                                                                            | No       | 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)                                                                                                                                       | No       | `api`: API ; `function`: Function ; `mcp`: MCP ; `desktop`: Desktop ; `flex`: Flex Message ; `quick_reply`: Quick Reply ; `quick_menu`: Quick Menu;                                                           |
| apiUrl                       | string                                                                                                                                                                                                            | No       |                                                                                                                                                                                                               |
| httpMethod                   | object                                                                                                                                                                                                            | No       |                                                                                                                                                                                                               |
| rawHeaders                   | object                                                                                                                                                                                                            | No       |                                                                                                                                                                                                               |
| sensitiveHeaders             | array\[string]                                                                                                                                                                                                    | No       |                                                                                                                                                                                                               |
| rawQueryParams               | object                                                                                                                                                                                                            | No       | 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                                                                                                                                                                                                            | No       |                                                                                                                                                                                                               |
| functionCode                 | string                                                                                                                                                                                                            | No       |                                                                                                                                                                                                               |
| mcpUrl                       | string                                                                                                                                                                                                            | No       |                                                                                                                                                                                                               |
| mcpRegistry                  | string (uuid)                                                                                                                                                                                                     | No       | Registry backing this MCP tool. Null for manual-URL MCP tools.                                                                                                                                                |
| mcpAllowedTools              | object                                                                                                                                                                                                            | No       |                                                                                                                                                                                                               |
| rawMcpHeader                 | object                                                                                                                                                                                                            | No       | Default headers used when the Contact has no matching MCP Credential.                                                                                                                                         |
| authSubject                  | object                                                                                                                                                                                                            | No       | 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                                                                                                                                                                                                            | No       | FlexMessage JSON template. Required for FLEX\_MESSAGE tools. Stores the full LINE FlexMessage JSON structure (bubble / carousel / box / text / image / button etc.).                                          |
| flexSchema                   | object                                                                                                                                                                                                            | No       | 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                                                                                                                                                                                                            | No       | 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                                                                                                                                                                                                            | No       | 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) | No       | `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                                                                                                                                                                                                            | No       |                                                                                                                                                                                                               |
| outputRenderTemplateByLocale | object                                                                                                                                                                                                            | No       |                                                                                                                                                                                                               |
| toolDisplayMode              | object                                                                                                                                                                                                            | No       |                                                                                                                                                                                                               |
| groups                       | array\[IdName]                                                                                                                                                                                                    | No       | Groups this tool is assigned to. Non-owner members must pick at least one group they belong to.                                                                                                               |

**Example request structure**

```typescript
{
  "name"?: // May have different types (optional)
  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. (optional)
  "displayName"?: string // A name with any characters, used by users for configuration and management. (optional)
  "description"?: string // Tool description shown to users. Not required for MCP tools. (optional)
  "prompt"?: string // Tool description/prompt given to the LLM. If empty, the description field is used. Not required for MCP tools. (optional)
  "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 (optional)
  "apiUrl"?: string // optional
  "httpMethod"?: // May have different types (optional)
  string (enum: get, post, put, delete, patch) // optional
  "rawHeaders"?: object // optional
  "sensitiveHeaders"?: [ // optional
    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. (optional)
  "rawParametersSchema"?: object // optional
  "functionCode"?: string // optional
  "mcpUrl"?: string // optional
  "mcpRegistry"?: string (uuid) // Registry backing this MCP tool. Null for manual-URL MCP tools. (optional)
  "mcpAllowedTools"?: object // optional
  "rawMcpHeader"?: object // Default headers used when the Contact has no matching MCP Credential. (optional)
  "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 (optional)
  {
  }
  "flexTemplateJson"?: object // FlexMessage JSON template. Required for FLEX_MESSAGE tools. Stores the full LINE FlexMessage JSON structure (bubble / carousel / box / text / image / button etc.). (optional)
  "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. (optional)
  "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. (optional)
  "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). (optional)
  "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) (optional)
  "displayCopyByLocale"?: object // optional
  "outputRenderTemplateByLocale"?: object // optional
  "toolDisplayMode"?: // May have different types (optional)
  string (enum: full, compact, hidden) // optional
  "groups"?: [ // Groups this tool is assigned to. Non-owner members must pick at least one group they belong to. (optional)
    {
      "id": string (uuid)
    }
  ]
}
```

**Example request values**

```json
{
  "name": null,
  "displayName": "Example string",
  "description": "Example string",
  "prompt": "Example string",
  "toolType": "api",
  "apiUrl": "Example string",
  "httpMethod": null,
  "rawHeaders": null,
  "sensitiveHeaders": [
    "Example string"
  ],
  "rawQueryParams": null,
  "rawParametersSchema": null,
  "functionCode": "Example string",
  "mcpUrl": "Example string",
  "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"
    }
  ]
}
```

#### Code examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (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": "Example string",
    "description": "Example string",
    "prompt": "Example string",
    "toolType": "api",
    "apiUrl": "Example string",
    "httpMethod": null,
    "rawHeaders": null,
    "sensitiveHeaders": [
      "Example string"
    ],
    "rawQueryParams": null,
    "rawParametersSchema": null,
    "functionCode": "Example string",
    "mcpUrl": "Example string",
    "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"
      }
    ]
  }'

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// Request payload
const data = {
    "name": null,
    "displayName": "Example string",
    "description": "Example string",
    "prompt": "Example string",
    "toolType": "api",
    "apiUrl": "Example string",
    "httpMethod": null,
    "rawHeaders": null,
    "sensitiveHeaders": [
      "Example string"
    ],
    "rawQueryParams": null,
    "rawParametersSchema": null,
    "functionCode": "Example string",
    "mcpUrl": "Example string",
    "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('Response retrieved successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('An error occurred during the request:');
    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"
}

# Request payload
data = {
    "name": None,
    "displayName": "Example string",
    "description": "Example string",
    "prompt": "Example string",
    "toolType": "api",
    "apiUrl": "Example string",
    "httpMethod": None,
    "rawHeaders": None,
    "sensitiveHeaders": [
        "Example string"
    ],
    "rawQueryParams": None,
    "rawParametersSchema": None,
    "functionCode": "Example string",
    "mcpUrl": "Example string",
    "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("Response retrieved successfully:")
    print(response.json())
except Exception as e:
    print("An error occurred during the request:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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' => 'Example string',
            'description' => 'Example string',
            'prompt' => 'Example string',
            'toolType' => 'api',
            'apiUrl' => 'Example string',
            'httpMethod' => null,
            'rawHeaders' => null,
            'sensitiveHeaders' => [
                'Example string'
            ],
            'rawQueryParams' => null,
            'rawParametersSchema' => null,
            'functionCode' => 'Example string',
            'mcpUrl' => 'Example string',
            '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 "Response retrieved successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'An error occurred during the request: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response body

**Status code: 200**

**Example response structure**

```typescript
{
  "id": string (uuid)
  "name"?: // May have different types (optional)
  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. (optional)
  "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. (optional)
  "prompt"?: string // Tool description/prompt given to the LLM. If empty, the description field is used. Not required for MCP tools. (optional)
  "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 (optional)
  "apiUrl"?: string // optional
  "httpMethod"?: // May have different types (optional)
  string (enum: get, post, put, delete, patch) // optional
  "rawHeaders"?: object // optional
  "rawHeadersMasked": object
  "sensitiveHeaders"?: [ // optional
    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. (optional)
  "rawQueryParamsMasked": object
  "rawParametersSchema"?: object // optional
  "functionCode"?: string // optional
  "organization": string (uuid)
  "createdBy": string (uuid)
  "isGlobal": boolean // If set as global tool, all organizations can use this tool
  "mcpUrl"?: string // optional
  "mcpRegistry"?: string (uuid) // Registry backing this MCP tool. Null for manual-URL MCP tools. (optional)
  "mcpAllowedTools"?: object // optional
  "rawMcpHeader"?: object // Default headers used when the Contact has no matching MCP Credential. (optional)
  "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 (optional)
  {
  }
  "flexTemplateJson"?: object // FlexMessage JSON template. Required for FLEX_MESSAGE tools. Stores the full LINE FlexMessage JSON structure (bubble / carousel / box / text / image / button etc.). (optional)
  "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. (optional)
  "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. (optional)
  "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). (optional)
  "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) (optional)
  "displayCopyByLocale"?: object // optional
  "outputRenderTemplateByLocale"?: object // optional
  "toolDisplayMode"?: // May have different types (optional)
  string (enum: full, compact, hidden) // optional
  "groups"?: [ // Groups this tool is assigned to. Non-owner members must pick at least one group they belong to. (optional)
    {
      "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.
}
```

**Example response values**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Response string",
  "displayName": "Response string",
  "description": "Response string",
  "prompt": "Response string",
  "toolType": "api",
  "apiUrl": "Response string",
  "httpMethod": "get",
  "rawHeaders": null,
  "rawHeadersMasked": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example response name",
    "description": "Example response description"
  },
  "sensitiveHeaders": [
    "Response string"
  ],
  "globalSensitiveHeaders": [
    "Response string"
  ],
  "rawQueryParams": null,
  "rawQueryParamsMasked": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example response name",
    "description": "Example response description"
  },
  "rawParametersSchema": null,
  "functionCode": "Response string",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": "550e8400-e29b-41d4-a716-446655440000",
  "isGlobal": false,
  "mcpUrl": "Response string",
  "mcpRegistry": "550e8400-e29b-41d4-a716-446655440000",
  "mcpAllowedTools": null,
  "rawMcpHeader": null,
  "rawMcpHeaderMasked": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example response name",
    "description": "Example response 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": "Response string"
    }
  ],
  "createdAt": "Response string",
  "updatedAt": "Response string",
  "canUpdate": false,
  "canDelete": false
}
```

***

### Delete a tool <a href="#tools-destroy" id="tools-destroy"></a>

DELETE `/api/v1/tools/{id}/`

#### Parameters

| Parameter name | Required | Type   | Description                          |
| -------------- | -------- | ------ | ------------------------------------ |
| `id`           | ✅        | string | A UUID string identifying this Tool. |

#### Code examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

// Request payload
const data = null;

axios.delete("https://api.maiagent.ai/api/v1/tools/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('Response retrieved successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('An error occurred during the request:');
    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("Response retrieved successfully:")
    print(response.json())
except Exception as e:
    print("An error occurred during the request:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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 "Response retrieved successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'An error occurred during the request: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response body

| Status code | Description      |
| ----------- | ---------------- |
| 204         | No response body |

***

### List Available Tools <a href="#tools-available-tools-create" id="tools-available-tools-create"></a>

POST `/api/v1/tools/available-tools/`

#### Request Body

**Request Parameters**

| Field           | Type           | Required | Description                               |
| --------------- | -------------- | -------- | ----------------------------------------- |
| mcpUrl          | string         | Yes      | MCP server URL (required)                 |
| rawMcpHeader    | object         | No       | MCP Header (JSON format)                  |
| mcpAllowedTools | array\[string] | No       | List of tools allowed for MCP             |
| toolId          | string (uuid)  | No       | Tool ID for per-member OAuth token lookup |

**Example Request Schema**

```typescript
{
  "mcpUrl": string // MCP server URL (required)
  "rawMcpHeader"?: object // MCP Header (JSON format) (Optional)
  "mcpAllowedTools"?: [ // List of tools allowed for MCP (Optional)
    string
  ]
  "toolId"?: string (uuid) // Tool ID for per-member OAuth token lookup (Optional)
}
```

**Example Request Values**

```json
{
  "mcpUrl": "Example string",
  "rawMcpHeader": null,
  "mcpAllowedTools": [
    "Example string"
  ],
  "toolId": "550e8400-e29b-41d4-a716-446655440000"
}
```

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# Example API call (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/tools/available-tools/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mcpUrl": "Example string",
    "rawMcpHeader": null,
    "mcpAllowedTools": [
      "Example string"
    ],
    "toolId": "550e8400-e29b-41d4-a716-446655440000"
  }'

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// Request body (payload)
const data = {
    "mcpUrl": "Example string",
    "rawMcpHeader": null,
    "mcpAllowedTools": [
      "Example string"
    ],
    "toolId": "550e8400-e29b-41d4-a716-446655440000"
  };

axios.post("https://api.maiagent.ai/api/v1/tools/available-tools/", data, config)
  .then(response => {
    console.log('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# Request body (payload)
data = {
    "mcpUrl": "Example string",
    "rawMcpHeader": None,
    "mcpAllowedTools": [
        "Example string"
    ],
    "toolId": "550e8400-e29b-41d4-a716-446655440000"
}

response = requests.post(url, json=data, headers=headers)
try:
    print("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/tools/available-tools/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'mcpUrl' => 'Example string',
            'rawMcpHeader' => null,
            'mcpAllowedTools' => [
                'Example string'
            ],
            'toolId' => '550e8400-e29b-41d4-a716-446655440000'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response Body

**Status Code: 200**

**Example Response Schema**

```typescript
{
  "mcpUrl": string // MCP server URL (required)
  "rawMcpHeader"?: object // MCP Header (JSON format) (Optional)
  "mcpAllowedTools"?: [ // List of tools allowed for MCP (Optional)
    string
  ]
  "toolId"?: string (uuid) // Tool ID for per-member OAuth token lookup (Optional)
  "availableTools": [ // List of all available MCP tools
    string
  ]
  "error":  // Reason for failure to retrieve tools: {code, message}; code is url_rejected／invalid_header／dns_error／connect_error／tls_error／auth_error／timeout_error／handshake_error／unknown_error. This is null when the connection succeeds (including when the server has no tools); it is always null for the deprecated GET endpoint
  {
    "code": string // url_rejected / invalid_header / dns_error / connect_error / tls_error / auth_error / timeout_error / handshake_error / unknown_error
    "message": string // Reason translated into the user’s locale, ready for display
  }
}
```

**Example Response Values**

```json
{
  "mcpUrl": "Response string",
  "rawMcpHeader": null,
  "mcpAllowedTools": [
    "Response string"
  ],
  "toolId": "550e8400-e29b-41d4-a716-446655440000",
  "availableTools": [
    "Response string"
  ],
  "error": {
    "code": "Response string",
    "message": "Response string"
  }
}
```

**Status Code: 400**

**Example Response Schema**

```typescript
{
  "detail"?: string // Optional
}
```

**Example Response Values**

```json
{
  "detail": "Response string"
}
```

***

### Create connector <a href="#connectors-create" id="connectors-create"></a>

POST `/api/v1/connectors/`

#### Request body

**Request parameters**

| Field                           | Type          | Required | Description                                                                                                                                                                                                  |
| ------------------------------- | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| mcpRegistryId                   | string (uuid) | Yes      |                                                                                                                                                                                                              |
| displayName                     | string        | No       | Custom display name for this connector (defaults to MCP Registry name)                                                                                                                                       |
| description                     | string        | No       | Custom description for this connector (defaults to MCP Registry description)                                                                                                                                 |
| defaultCategory                 | object        | No       | 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        | No       | 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        | No       | 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        | No       |                                                                                                                                                                                                              |
| allowedContextDataKeys          | object        | No       | 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        | No       | 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       | No       | Whether this connector is enabled for contacts in the organization                                                                                                                                           |

**Example request schema**

```typescript
{
  "mcpRegistryId": string (uuid)
  "displayName"?: string // Custom display name for this connector (defaults to MCP Registry name) (Optional)
  "description"?: string // Custom description for this connector (defaults to MCP Registry description) (Optional)
  "defaultCategory"?: // May have different types (Optional)
  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) (Optional)
  "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: {"<locale>": 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. (Optional)
  "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. (Optional)
  "authHeaders"?: object // Optional
  "allowedContextDataKeys"?: object // Allowlist of webchat contextData keys this connector may render into auth_headers through {{context_data.<key>}}. 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. (Optional)
  "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). (Optional)
  "isEnabled"?: boolean // Whether this connector is enabled for contacts in the organization (Optional)
}
```

**Example request values**

```json
{
  "mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
  "displayName": "Example string",
  "description": "Example string",
  "defaultCategory": null,
  "defaultDisplayGroupNameByLocale": null,
  "defaultToolIcon": "Example string",
  "authHeaders": null,
  "allowedContextDataKeys": null,
  "exposedMcpTools": null,
  "isEnabled": true
}
```

#### Code examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (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": "Example string",
    "description": "Example string",
    "defaultCategory": null,
    "defaultDisplayGroupNameByLocale": null,
    "defaultToolIcon": "Example string",
    "authHeaders": null,
    "allowedContextDataKeys": null,
    "exposedMcpTools": null,
    "isEnabled": true
  }'

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// Request body (payload)
const data = {
    "mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
    "displayName": "Example string",
    "description": "Example string",
    "defaultCategory": null,
    "defaultDisplayGroupNameByLocale": null,
    "defaultToolIcon": "Example string",
    "authHeaders": null,
    "allowedContextDataKeys": null,
    "exposedMcpTools": null,
    "isEnabled": true
  };

axios.post("https://api.maiagent.ai/api/v1/connectors/", data, config)
  .then(response => {
    console.log('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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"
}

# Request body (payload)
data = {
    "mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
    "displayName": "Example string",
    "description": "Example string",
    "defaultCategory": None,
    "defaultDisplayGroupNameByLocale": None,
    "defaultToolIcon": "Example string",
    "authHeaders": None,
    "allowedContextDataKeys": None,
    "exposedMcpTools": None,
    "isEnabled": True
}

response = requests.post(url, json=data, headers=headers)
try:
    print("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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' => 'Example string',
            'description' => 'Example string',
            'defaultCategory' => null,
            'defaultDisplayGroupNameByLocale' => null,
            'defaultToolIcon' => 'Example string',
            'authHeaders' => null,
            'allowedContextDataKeys' => null,
            'exposedMcpTools' => null,
            'isEnabled' => true
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response body

**Status code: 201**

**Example response schema**

```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) (Optional)
    "description"?: string // Brief description of the MCP service (Optional)
    "remoteMcpUrl": string (uri) // The URL of the Remote MCP service
    "oauthServerUrl"?: // May have different types (Optional)
    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) (Optional)
    "logoUrl": string (uri)
    "isActive"?: boolean // Whether this MCP service is currently available for use (Optional)
    "isGlobal"?: boolean // Global registries are maintained by the platform and available to all organizations. (Optional)
    "authType"?:  // How to authenticate with this MCP server.

* `oauth` - OAuth 2.0
* `service_account` - Service Account
* `none` - No Authentication (Optional)
    {
    }
    "createdAt": string (timestamp)
    "updatedAt": string (timestamp)
  }
  "mcpRegistryId": string (uuid)
  "name": string
  "displayName"?: string // Custom display name for this connector (defaults to MCP Registry name) (Optional)
  "description"?: string // Custom description for this connector (defaults to MCP Registry description) (Optional)
  "defaultCategory"?: // May have different types (Optional)
  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) (Optional)
  "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: {"<locale>": 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. (Optional)
  "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. (Optional)
  "effectiveDescription": string
  "remoteMcpUrl": string
  "oauthServerUrl": string
  "logoUrl": string (uri)
  "authType": string
  "authHeaders"?: object // Optional
  "authHeadersMasked": object
  "allowedContextDataKeys"?: object // Allowlist of webchat contextData keys this connector may render into auth_headers through {{context_data.<key>}}. 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. (Optional)
  "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). (Optional)
  "isEnabled"?: boolean // Whether this connector is enabled for contacts in the organization (Optional)
  "organization": string (uuid)
  "createdBy": string (uuid)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**Example response values**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "mcpRegistry": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Response string",
    "displayName": "Response string",
    "description": "Response string",
    "remoteMcpUrl": "https://example.com/file.jpg",
    "oauthServerUrl": "https://example.com/file.jpg",
    "logoUrl": "https://example.com/file.jpg",
    "isActive": false,
    "isGlobal": false,
    "authType": {},
    "createdAt": "Response string",
    "updatedAt": "Response string"
  },
  "mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Response string",
  "displayName": "Response string",
  "description": "Response string",
  "defaultCategory": "knowledge_base",
  "defaultDisplayGroupNameByLocale": null,
  "defaultToolIcon": "Response string",
  "effectiveDescription": "Response string",
  "remoteMcpUrl": "Response string",
  "oauthServerUrl": "Response string",
  "logoUrl": "https://example.com/file.jpg",
  "authType": "Response string",
  "authHeaders": null,
  "authHeadersMasked": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example response name",
    "description": "Example response description"
  },
  "allowedContextDataKeys": null,
  "exposedMcpTools": null,
  "isEnabled": false,
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": "550e8400-e29b-41d4-a716-446655440000",
  "createdAt": "Response string",
  "updatedAt": "Response string"
}
```

***

### List connectors <a href="#connectors-list" id="connectors-list"></a>

GET `/api/v1/connectors/`

#### Code examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/connectors/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/connectors/", config)
  .then(response => {
    console.log('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/connectors/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response body

**Status code: 200**

**Example response schema**

```typescript
[
  {
    "id": string (uuid)
    "displayName"?: string // Custom display name for this connector (defaults to MCP Registry name) (Optional)
    "mcpRegistryName": string
    "mcpRegistryId": string
    "mcpRegistryIsGlobal": boolean
    "logoUrl": string (uri)
    "defaultCategory"?: // May have different types (Optional)
    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) (Optional)
    "isEnabled"?: boolean // Whether this connector is enabled for contacts in the organization (Optional)
    "authHeadersMasked": object
    "allowedContextDataKeys": object // Allowlist of webchat contextData keys this connector may render into auth_headers through {{context_data.<key>}}. 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)
  }
]
```

**Example response values**

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "displayName": "Response string",
    "mcpRegistryName": "Response string",
    "mcpRegistryId": "Response string",
    "mcpRegistryIsGlobal": false,
    "logoUrl": "https://example.com/file.jpg",
    "defaultCategory": "knowledge_base",
    "isEnabled": false,
    "authHeadersMasked": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Example response name",
      "description": "Example response description"
    },
    "allowedContextDataKeys": null,
    "authorizedMembersCount": 456,
    "createdBy": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Response string"
    },
    "createdAt": "Response string",
    "updatedAt": "Response string"
  }
]
```

***

### Retrieve a specific connector <a href="#connectors-retrieve" id="connectors-retrieve"></a>

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

#### Parameters

| Parameter name | Required | Type   | Description |
| -------------- | -------- | ------ | ----------- |
| `id`           | ✅        | string |             |

#### Code examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/connectors/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
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('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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 "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response body

**Status code: 200**

**Example response schema**

```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) (Optional)
    "description"?: string // Brief description of the MCP service (Optional)
    "remoteMcpUrl": string (uri) // The URL of the Remote MCP service
    "oauthServerUrl"?: // May have different types (Optional)
    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) (Optional)
    "logoUrl": string (uri)
    "isActive"?: boolean // Whether this MCP service is currently available for use (Optional)
    "isGlobal"?: boolean // Global registries are maintained by the platform and available to all organizations. (Optional)
    "authType"?:  // How to authenticate with this MCP server.

* `oauth` - OAuth 2.0
* `service_account` - Service Account
* `none` - No Authentication (Optional)
    {
    }
    "createdAt": string (timestamp)
    "updatedAt": string (timestamp)
  }
  "mcpRegistryId": string (uuid)
  "name": string
  "displayName"?: string // Custom display name for this connector (defaults to MCP Registry name) (Optional)
  "description"?: string // Custom description for this connector (defaults to MCP Registry description) (Optional)
  "defaultCategory"?: // May have different types (Optional)
  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) (Optional)
  "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: {"<locale>": 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. (Optional)
  "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. (Optional)
  "effectiveDescription": string
  "remoteMcpUrl": string
  "oauthServerUrl": string
  "logoUrl": string (uri)
  "authType": string
  "authHeaders"?: object // Optional
  "authHeadersMasked": object
  "allowedContextDataKeys"?: object // Allowlist of webchat contextData keys this connector may render into auth_headers through {{context_data.<key>}}. 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. (Optional)
  "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). (Optional)
  "isEnabled"?: boolean // Whether this connector is enabled for contacts in the organization (Optional)
  "organization": string (uuid)
  "createdBy": string (uuid)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**Example Response Values**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "mcpRegistry": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Response string",
    "displayName": "Response string",
    "description": "Response string",
    "remoteMcpUrl": "https://example.com/file.jpg",
    "oauthServerUrl": "https://example.com/file.jpg",
    "logoUrl": "https://example.com/file.jpg",
    "isActive": false,
    "isGlobal": false,
    "authType": {},
    "createdAt": "Response string",
    "updatedAt": "Response string"
  },
  "mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Response string",
  "displayName": "Response string",
  "description": "Response string",
  "defaultCategory": "knowledge_base",
  "defaultDisplayGroupNameByLocale": null,
  "defaultToolIcon": "Response string",
  "effectiveDescription": "Response string",
  "remoteMcpUrl": "Response string",
  "oauthServerUrl": "Response string",
  "logoUrl": "https://example.com/file.jpg",
  "authType": "Response string",
  "authHeaders": null,
  "authHeadersMasked": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example response name",
    "description": "Example response description"
  },
  "allowedContextDataKeys": null,
  "exposedMcpTools": null,
  "isEnabled": false,
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": "550e8400-e29b-41d4-a716-446655440000",
  "createdAt": "Response string",
  "updatedAt": "Response string"
}
```

***

### Update Connector <a href="#connectors-update" id="connectors-update"></a>

PUT `/api/v1/connectors/{id}/`

#### Parameters

| Parameter Name | Required | Type   | Description |
| -------------- | -------- | ------ | ----------- |
| `id`           | ✅        | string |             |

#### Request Body

**Request Parameters**

| Field                           | Type          | Required | Description                                                                                                                                                                                                  |
| ------------------------------- | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| mcpRegistryId                   | string (uuid) | Yes      |                                                                                                                                                                                                              |
| displayName                     | string        | No       | Custom display name for this connector (defaults to MCP Registry name)                                                                                                                                       |
| description                     | string        | No       | Custom description for this connector (defaults to MCP Registry description)                                                                                                                                 |
| defaultCategory                 | object        | No       | 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        | No       | 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        | No       | 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        | No       |                                                                                                                                                                                                              |
| allowedContextDataKeys          | object        | No       | 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        | No       | 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       | No       | Whether this connector is enabled for contacts in the organization                                                                                                                                           |

**Request Schema Example**

```typescript
{
  "mcpRegistryId": string (uuid)
  "displayName"?: string // Custom display name for this connector (defaults to MCP Registry name) (Optional)
  "description"?: string // Custom description for this connector (defaults to MCP Registry description) (Optional)
  "defaultCategory"?: // May have different types (Optional)
  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) (Optional)
  "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: {"<locale>": 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. (Optional)
  "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. (Optional)
  "authHeaders"?: object // Optional
  "allowedContextDataKeys"?: object // Allowlist of webchat contextData keys this connector may render into auth_headers through {{context_data.<key>}}. 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. (Optional)
  "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). (Optional)
  "isEnabled"?: boolean // Whether this connector is enabled for contacts in the organization (Optional)
}
```

**Example Request Values**

```json
{
  "mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
  "displayName": "Example string",
  "description": "Example string",
  "defaultCategory": null,
  "defaultDisplayGroupNameByLocale": null,
  "defaultToolIcon": "Example string",
  "authHeaders": null,
  "allowedContextDataKeys": null,
  "exposedMcpTools": null,
  "isEnabled": true
}
```

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (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": "Example string",
    "description": "Example string",
    "defaultCategory": null,
    "defaultDisplayGroupNameByLocale": null,
    "defaultToolIcon": "Example string",
    "authHeaders": null,
    "allowedContextDataKeys": null,
    "exposedMcpTools": null,
    "isEnabled": true
  }'

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// Request Body (payload)
const data = {
    "mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
    "displayName": "Example string",
    "description": "Example string",
    "defaultCategory": null,
    "defaultDisplayGroupNameByLocale": null,
    "defaultToolIcon": "Example string",
    "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('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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"
}

# Request Body (payload)
data = {
    "mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
    "displayName": "Example string",
    "description": "Example string",
    "defaultCategory": None,
    "defaultDisplayGroupNameByLocale": None,
    "defaultToolIcon": "Example string",
    "authHeaders": None,
    "allowedContextDataKeys": None,
    "exposedMcpTools": None,
    "isEnabled": True
}

response = requests.put(url, json=data, headers=headers)
try:
    print("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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' => 'Example string',
            'description' => 'Example string',
            'defaultCategory' => null,
            'defaultDisplayGroupNameByLocale' => null,
            'defaultToolIcon' => 'Example string',
            'authHeaders' => null,
            'allowedContextDataKeys' => null,
            'exposedMcpTools' => null,
            'isEnabled' => true
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response Body

**Status Code: 200**

**Response Schema Example**

```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) (Optional)
    "description"?: string // Brief description of the MCP service (Optional)
    "remoteMcpUrl": string (uri) // The URL of the Remote MCP service
    "oauthServerUrl"?: // May have different types (Optional)
    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) (Optional)
    "logoUrl": string (uri)
    "isActive"?: boolean // Whether this MCP service is currently available for use (Optional)
    "isGlobal"?: boolean // Global registries are maintained by the platform and available to all organizations. (Optional)
    "authType"?:  // How to authenticate with this MCP server.

* `oauth` - OAuth 2.0
* `service_account` - Service Account
* `none` - No Authentication (Optional)
    {
    }
    "createdAt": string (timestamp)
    "updatedAt": string (timestamp)
  }
  "mcpRegistryId": string (uuid)
  "name": string
  "displayName"?: string // Custom display name for this connector (defaults to MCP Registry name) (Optional)
  "description"?: string // Custom description for this connector (defaults to MCP Registry description) (Optional)
  "defaultCategory"?: // May have different types (Optional)
  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) (Optional)
  "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: {"<locale>": 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. (Optional)
  "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. (Optional)
  "effectiveDescription": string
  "remoteMcpUrl": string
  "oauthServerUrl": string
  "logoUrl": string (uri)
  "authType": string
  "authHeaders"?: object // Optional
  "authHeadersMasked": object
  "allowedContextDataKeys"?: object // Allowlist of webchat contextData keys this connector may render into auth_headers through {{context_data.<key>}}. 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. (Optional)
  "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). (Optional)
  "isEnabled"?: boolean // Whether this connector is enabled for contacts in the organization (Optional)
  "organization": string (uuid)
  "createdBy": string (uuid)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**Example Response Values**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "mcpRegistry": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Response string",
    "displayName": "Response string",
    "description": "Response string",
    "remoteMcpUrl": "https://example.com/file.jpg",
    "oauthServerUrl": "https://example.com/file.jpg",
    "logoUrl": "https://example.com/file.jpg",
    "isActive": false,
    "isGlobal": false,
    "authType": {},
    "createdAt": "Response string",
    "updatedAt": "Response string"
  },
  "mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Response string",
  "displayName": "Response string",
  "description": "Response string",
  "defaultCategory": "knowledge_base",
  "defaultDisplayGroupNameByLocale": null,
  "defaultToolIcon": "Response string",
  "effectiveDescription": "Response string",
  "remoteMcpUrl": "Response string",
  "oauthServerUrl": "Response string",
  "logoUrl": "https://example.com/file.jpg",
  "authType": "Response string",
  "authHeaders": null,
  "authHeadersMasked": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example response name",
    "description": "Example response description"
  },
  "allowedContextDataKeys": null,
  "exposedMcpTools": null,
  "isEnabled": false,
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": "550e8400-e29b-41d4-a716-446655440000",
  "createdAt": "Response string",
  "updatedAt": "Response string"
}
```

***

### Partially Update Connector <a href="#connectors-partial-update" id="connectors-partial-update"></a>

PATCH `/api/v1/connectors/{id}/`

#### Parameters

| Parameter Name | Required | Type   | Description |
| -------------- | -------- | ------ | ----------- |
| `id`           | ✅        | string |             |

#### Request Body

**Request Parameters**

| Field                           | Type          | Required | Description                                                                                                                                                                                                  |
| ------------------------------- | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| mcpRegistryId                   | string (uuid) | No       |                                                                                                                                                                                                              |
| displayName                     | string        | No       | Custom display name for this connector (defaults to MCP Registry name)                                                                                                                                       |
| description                     | string        | No       | Custom description for this connector (defaults to MCP Registry description)                                                                                                                                 |
| defaultCategory                 | object        | No       | 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        | No       | 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        | No       | 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        | No       |                                                                                                                                                                                                              |
| allowedContextDataKeys          | object        | No       | 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        | No       | 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       | No       | Whether this connector is enabled for contacts in the organization                                                                                                                                           |

**Request Schema Example**

```typescript
{
  "mcpRegistryId"?: string (uuid) // Optional
  "displayName"?: string // Custom display name for this connector (defaults to MCP Registry name) (Optional)
  "description"?: string // Custom description for this connector (defaults to MCP Registry description) (Optional)
  "defaultCategory"?: // May have different types (Optional)
  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) (Optional)
  "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: {"<locale>": 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. (Optional)
  "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. (Optional)
  "authHeaders"?: object // Optional
  "allowedContextDataKeys"?: object // Allowlist of webchat contextData keys this connector may render into auth_headers through {{context_data.<key>}}. 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. (Optional)
  "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). (Optional)
  "isEnabled"?: boolean // Whether this connector is enabled for contacts in the organization (Optional)
}
```

**Example Request Values**

```json
{
  "mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
  "displayName": "Example string",
  "description": "Example string",
  "defaultCategory": null,
  "defaultDisplayGroupNameByLocale": null,
  "defaultToolIcon": "Example string",
  "authHeaders": null,
  "allowedContextDataKeys": null,
  "exposedMcpTools": null,
  "isEnabled": true
}
```

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (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": "Example string",
    "description": "Example string",
    "defaultCategory": null,
    "defaultDisplayGroupNameByLocale": null,
    "defaultToolIcon": "Example string",
    "authHeaders": null,
    "allowedContextDataKeys": null,
    "exposedMcpTools": null,
    "isEnabled": true
  }'

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// Request body (payload)
const data = {
    "mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
    "displayName": "Example string",
    "description": "Example string",
    "defaultCategory": null,
    "defaultDisplayGroupNameByLocale": null,
    "defaultToolIcon": "Example string",
    "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('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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"
}

# Request body (payload)
data = {
    "mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
    "displayName": "Example string",
    "description": "Example string",
    "defaultCategory": None,
    "defaultDisplayGroupNameByLocale": None,
    "defaultToolIcon": "Example string",
    "authHeaders": None,
    "allowedContextDataKeys": None,
    "exposedMcpTools": None,
    "isEnabled": True
}

response = requests.patch(url, json=data, headers=headers)
try:
    print("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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' => 'Example string',
            'description' => 'Example string',
            'defaultCategory' => null,
            'defaultDisplayGroupNameByLocale' => null,
            'defaultToolIcon' => 'Example string',
            'authHeaders' => null,
            'allowedContextDataKeys' => null,
            'exposedMcpTools' => null,
            'isEnabled' => true
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response Body

**Status Code: 200**

**Example Response Schema**

```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) (Optional)
    "description"?: string // Brief description of the MCP service (Optional)
    "remoteMcpUrl": string (uri) // The URL of the Remote MCP service
    "oauthServerUrl"?: // May have different types (Optional)
    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) (Optional)
    "logoUrl": string (uri)
    "isActive"?: boolean // Whether this MCP service is currently available for use (Optional)
    "isGlobal"?: boolean // Global registries are maintained by the platform and available to all organizations. (Optional)
    "authType"?:  // How to authenticate with this MCP server.

* `oauth` - OAuth 2.0
* `service_account` - Service Account
* `none` - No Authentication (Optional)
    {
    }
    "createdAt": string (timestamp)
    "updatedAt": string (timestamp)
  }
  "mcpRegistryId": string (uuid)
  "name": string
  "displayName"?: string // Custom display name for this connector (defaults to MCP Registry name) (Optional)
  "description"?: string // Custom description for this connector (defaults to MCP Registry description) (Optional)
  "defaultCategory"?: // May have different types (Optional)
  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) (Optional)
  "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: {"<locale>": 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. (Optional)
  "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. (Optional)
  "effectiveDescription": string
  "remoteMcpUrl": string
  "oauthServerUrl": string
  "logoUrl": string (uri)
  "authType": string
  "authHeaders"?: object // Optional
  "authHeadersMasked": object
  "allowedContextDataKeys"?: object // Allowlist of webchat contextData keys this connector may render into auth_headers through {{context_data.<key>}}. 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. (Optional)
  "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). (Optional)
  "isEnabled"?: boolean // Whether this connector is enabled for contacts in the organization (Optional)
  "organization": string (uuid)
  "createdBy": string (uuid)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**Example Response Values**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "mcpRegistry": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Response string",
    "displayName": "Response string",
    "description": "Response string",
    "remoteMcpUrl": "https://example.com/file.jpg",
    "oauthServerUrl": "https://example.com/file.jpg",
    "logoUrl": "https://example.com/file.jpg",
    "isActive": false,
    "isGlobal": false,
    "authType": {},
    "createdAt": "Response string",
    "updatedAt": "Response string"
  },
  "mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Response string",
  "displayName": "Response string",
  "description": "Response string",
  "defaultCategory": "knowledge_base",
  "defaultDisplayGroupNameByLocale": null,
  "defaultToolIcon": "Response string",
  "effectiveDescription": "Response string",
  "remoteMcpUrl": "Response string",
  "oauthServerUrl": "Response string",
  "logoUrl": "https://example.com/file.jpg",
  "authType": "Response string",
  "authHeaders": null,
  "authHeadersMasked": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example response name",
    "description": "Example response description"
  },
  "allowedContextDataKeys": null,
  "exposedMcpTools": null,
  "isEnabled": false,
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": "550e8400-e29b-41d4-a716-446655440000",
  "createdAt": "Response string",
  "updatedAt": "Response string"
}
```

***

### Delete Connector <a href="#connectors-destroy" id="connectors-destroy"></a>

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

#### Parameters

| Parameter Name | Required | Type   | Description |
| -------------- | -------- | ------ | ----------- |
| `id`           | ✅        | string |             |

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/connectors/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

// Request body (payload)
const data = null;

axios.delete("https://api.maiagent.ai/api/v1/connectors/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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 "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response Body

| Status Code | Description      |
| ----------- | ---------------- |
| 204         | No response body |

***

### List Authorized Connector Members <a href="#connectors-authorized-members-retrieve" id="connectors-authorized-members-retrieve"></a>

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

#### Parameters

| Parameter Name | Required | Type   | Description |
| -------------- | -------- | ------ | ----------- |
| `id`           | ✅        | string |             |

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (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"

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
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('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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 "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response Body

**Status Code: 200**

**Example Response Schema**

```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) (Optional)
    "description"?: string // Brief description of the MCP service (Optional)
    "remoteMcpUrl": string (uri) // The URL of the Remote MCP service
    "oauthServerUrl"?: // May have different types (Optional)
    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) (Optional)
    "logoUrl": string (uri)
    "isActive"?: boolean // Whether this MCP service is currently available for use (Optional)
    "isGlobal"?: boolean // Global registries are maintained by the platform and available to all organizations. (Optional)
    "authType"?:  // How to authenticate with this MCP server.

* `oauth` - OAuth 2.0
* `service_account` - Service Account
* `none` - No Authentication (Optional)
    {
    }
    "createdAt": string (timestamp)
    "updatedAt": string (timestamp)
  }
  "mcpRegistryId": string (uuid)
  "name": string
  "displayName"?: string // Custom display name for this connector (defaults to MCP Registry name) (Optional)
  "description"?: string // Custom description for this connector (defaults to MCP Registry description) (Optional)
  "defaultCategory"?: // May have different types (Optional)
  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) (Optional)
  "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: {"<locale>": 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. (Optional)
  "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. (Optional)
  "effectiveDescription": string
  "remoteMcpUrl": string
  "oauthServerUrl": string
  "logoUrl": string (uri)
  "authType": string
  "authHeaders"?: object // Optional
  "authHeadersMasked": object
  "allowedContextDataKeys"?: object // Allowlist of webchat contextData keys this connector may render into auth_headers through {{context_data.<key>}}. 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. (Optional)
  "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). (Optional)
  "isEnabled"?: boolean // Whether this connector is enabled for contacts in the organization (Optional)
  "organization": string (uuid)
  "createdBy": string (uuid)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**Example Response Values**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "mcpRegistry": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Response string",
    "displayName": "Response string",
    "description": "Response string",
    "remoteMcpUrl": "https://example.com/file.jpg",
    "oauthServerUrl": "https://example.com/file.jpg",
    "logoUrl": "https://example.com/file.jpg",
    "isActive": false,
    "isGlobal": false,
    "authType": {},
    "createdAt": "Response string",
    "updatedAt": "Response string"
  },
  "mcpRegistryId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Response string",
  "displayName": "Response string",
  "description": "Response string",
  "defaultCategory": "knowledge_base",
  "defaultDisplayGroupNameByLocale": null,
  "defaultToolIcon": "Response string",
  "effectiveDescription": "Response string",
  "remoteMcpUrl": "Response string",
  "oauthServerUrl": "Response string",
  "logoUrl": "https://example.com/file.jpg",
  "authType": "Response string",
  "authHeaders": null,
  "authHeadersMasked": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example response name",
    "description": "Example response description"
  },
  "allowedContextDataKeys": null,
  "exposedMcpTools": null,
  "isEnabled": false,
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": "550e8400-e29b-41d4-a716-446655440000",
  "createdAt": "Response string",
  "updatedAt": "Response string"
}
```

***

### Remove Authorized Connector Member <a href="#connectors-authorized-members-destroy" id="connectors-authorized-members-destroy"></a>

DELETE `/api/v1/connectors/{id}/authorized-members/{memberId}/`

#### Parameters

| Parameter name | Required | Type   | Description |
| -------------- | -------- | ------ | ----------- |
| `id`           | ✅        | string |             |
| `memberId`     | ✅        | string |             |

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (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"

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

// Request body (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('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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 "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response Body

| Status code | Description      |
| ----------- | ---------------- |
| 204         | No response body |

***

### List MCP Tool Registries <a href="#mcp-registry-list" id="mcp-registry-list"></a>

GET `/api/v1/mcp/registry/`

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/mcp/registry/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/mcp/registry/", config)
  .then(response => {
    console.log('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/mcp/registry/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response Body

**Status code: 200**

**Example Response Schema**

```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) (Optional)
    "description"?: string // Brief description of the MCP service (Optional)
    "remoteMcpUrl": string (uri) // The URL of the Remote MCP service
    "oauthServerUrl"?: // May have different types (Optional)
    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) (Optional)
    "logoUrl": string (uri)
    "isActive"?: boolean // Whether this MCP service is currently available for use (Optional)
    "isGlobal"?: boolean // Global registries are maintained by the platform and available to all organizations. (Optional)
    "authType"?:  // How to authenticate with this MCP server.

* `oauth` - OAuth 2.0
* `service_account` - Service Account
* `none` - No Authentication (Optional)
    {
    }
    "createdAt": string (timestamp)
    "updatedAt": string (timestamp)
  }
]
```

**Example Response Values**

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Response string",
    "displayName": "Response string",
    "description": "Response string",
    "remoteMcpUrl": "https://example.com/file.jpg",
    "oauthServerUrl": "https://example.com/file.jpg",
    "logoUrl": "https://example.com/file.jpg",
    "isActive": false,
    "isGlobal": false,
    "authType": {},
    "createdAt": "Response string",
    "updatedAt": "Response string"
  }
]
```

***

### Retrieve a Specific MCP Tool Registry <a href="#mcp-registry-retrieve" id="mcp-registry-retrieve"></a>

GET `/api/v1/mcp/registry/{id}/`

#### Parameters

| Parameter name | Required | Type   | Description |
| -------------- | -------- | ------ | ----------- |
| `id`           | ✅        | string |             |

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/mcp/registry/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
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('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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 "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response Body

**Status code: 200**

**Example Response Schema**

```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) (Optional)
  "description"?: string // Brief description of the MCP service (Optional)
  "remoteMcpUrl": string (uri) // The URL of the Remote MCP service
  "oauthServerUrl"?: // May have different types (Optional)
  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) (Optional)
  "logoUrl": string (uri)
  "isActive"?: boolean // Whether this MCP service is currently available for use (Optional)
  "isGlobal"?: boolean // Global registries are maintained by the platform and available to all organizations. (Optional)
  "authType"?:  // How to authenticate with this MCP server.

* `oauth` - OAuth 2.0
* `service_account` - Service Account
* `none` - No Authentication (Optional)
  {
  }
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**Example Response Values**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Response string",
  "displayName": "Response string",
  "description": "Response string",
  "remoteMcpUrl": "https://example.com/file.jpg",
  "oauthServerUrl": "https://example.com/file.jpg",
  "logoUrl": "https://example.com/file.jpg",
  "isActive": false,
  "isGlobal": false,
  "authType": {},
  "createdAt": "Response string",
  "updatedAt": "Response string"
}
```

***

### List the Organization’s Self-hosted MCP Servers <a href="#mcp-private-registry-list" id="mcp-private-registry-list"></a>

GET `/api/v1/mcp/private-registry/`

{% hint style="info" %}
Connector management permission is required. For connection instructions, see [Self-hosted MCP Server](https://docs.maiagent.ai/tech/advanced-genai-tech/self-hosted-mcp-server) in the technical manual.
{% endhint %}

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/mcp/private-registry/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
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('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/mcp/private-registry/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response Body

**Status code: 200**

**Example Response Schema**

```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) (Optional)
    "description"?: string // Brief description of the MCP service (Optional)
    "remoteMcpUrl": string (uri) // The URL of the Remote MCP service
    "oauthServerUrl"?: // May have different types (Optional)
    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) (Optional)
    "resourceIdentifier"?: // May have different types (Optional)
    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) (Optional)
    "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. (Optional)
    "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). (Optional)
    "logoUrl"?: // May have different types (Optional)
    string (uri) // Logo: the uploaded storage object key (media/...) or an external URL; read back as a signed URL. (Optional)
    "authType"?:  // How to authenticate with this MCP server.

* `oauth` - OAuth 2.0
* `service_account` - Service Account
* `none` - No Authentication (Optional)
    {
    }
    "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). (Optional)
    "isActive": boolean // Whether this MCP service is currently available for use
    "createdAt": string (timestamp)
    "updatedAt": string (timestamp)
  }
]
```

**Example Response Values**

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Response string",
    "displayName": "Response string",
    "description": "Response string",
    "remoteMcpUrl": "https://example.com/file.jpg",
    "oauthServerUrl": "https://example.com/file.jpg",
    "resourceIdentifier": "https://example.com/file.jpg",
    "oauthClientId": "Response string",
    "oauthClientSecret": "Response string",
    "logoUrl": "https://example.com/file.jpg",
    "authType": {},
    "cspAllowedOrigins": null,
    "isActive": false,
    "createdAt": "Response string",
    "updatedAt": "Response string"
  }
]
```

***

### Add a Self-hosted MCP Server <a href="#mcp-private-registry-create" id="mcp-private-registry-create"></a>

POST `/api/v1/mcp/private-registry/`

#### Request Body

**Request Parameters**

| Field              | Type         | Required | Description                                                                                                                                                                                                    |
| ------------------ | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name               | string       | Yes      | MCP service name (e.g., Supabase, Sentry). Only alphanumeric, underscore and hyphen allowed.                                                                                                                   |
| displayName        | string       | No       | Human-readable display name (defaults to name if empty)                                                                                                                                                        |
| description        | string       | No       | Brief description of the MCP service                                                                                                                                                                           |
| remoteMcpUrl       | string (uri) | Yes      | The URL of the Remote MCP service                                                                                                                                                                              |
| oauthServerUrl     | object       | No       | 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       | No       | 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       | No       | 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       | No       | 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       | No       | Logo: the uploaded storage object key (media/...) or an external URL; read back as a signed URL.                                                                                                               |
| authType           | object       | No       | How to authenticate with this MCP server. `oauth`: OAuth 2.0 ; `service_account`: Service Account ; `none`: No Authentication;                                                                                 |
| cspAllowedOrigins  | object       | No       | 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 de... |

**Example Request Schema**

```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) (Optional)
  "description"?: string // Brief description of the MCP service (Optional)
  "remoteMcpUrl": string (uri) // The URL of the Remote MCP service
  "oauthServerUrl"?: // May have different types (Optional)
  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) (Optional)
  "resourceIdentifier"?: // May have different types (Optional)
  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) (Optional)
  "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. (Optional)
  "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). (Optional)
  "logoUrl"?: // May have different types (Optional)
  string (uri) // Logo: the uploaded storage object key (media/...) or an external URL; read back as a signed URL. (Optional)
  "authType"?:  // How to authenticate with this MCP server.

* `oauth` - OAuth 2.0
* `service_account` - Service Account
* `none` - No Authentication (Optional)
  {
  }
  "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). (Optional)
}
```

**Example Request Values**

```json
{
  "name": "Example name",
  "displayName": "Example string",
  "description": "Example string",
  "remoteMcpUrl": "https://example.com/file.jpg",
  "oauthServerUrl": null,
  "resourceIdentifier": null,
  "oauthClientId": "Example string",
  "oauthClientSecret": "Example string",
  "logoUrl": null,
  "authType": {},
  "cspAllowedOrigins": null
}
```

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (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": "Example name",
    "displayName": "Example string",
    "description": "Example string",
    "remoteMcpUrl": "https://example.com/file.jpg",
    "oauthServerUrl": null,
    "resourceIdentifier": null,
    "oauthClientId": "Example string",
    "oauthClientSecret": "Example string",
    "logoUrl": null,
    "authType": {},
    "cspAllowedOrigins": null
  }'

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// Request body (payload)
const data = {
    "name": "Example name",
    "displayName": "Example string",
    "description": "Example string",
    "remoteMcpUrl": "https://example.com/file.jpg",
    "oauthServerUrl": null,
    "resourceIdentifier": null,
    "oauthClientId": "Example string",
    "oauthClientSecret": "Example string",
    "logoUrl": null,
    "authType": {},
    "cspAllowedOrigins": null
  };

axios.post("https://api.maiagent.ai/api/v1/mcp/private-registry/", data, config)
  .then(response => {
    console.log('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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"
}

# Request body (payload)
data = {
    "name": "Example name",
    "displayName": "Example string",
    "description": "Example string",
    "remoteMcpUrl": "https://example.com/file.jpg",
    "oauthServerUrl": None,
    "resourceIdentifier": None,
    "oauthClientId": "Example string",
    "oauthClientSecret": "Example string",
    "logoUrl": None,
    "authType": {},
    "cspAllowedOrigins": None
}

response = requests.post(url, json=data, headers=headers)
try:
    print("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request failed:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/mcp/private-registry/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'name' => 'Example name',
            'displayName' => 'Example string',
            'description' => 'Example string',
            'remoteMcpUrl' => 'https://example.com/file.jpg',
            'oauthServerUrl' => null,
            'resourceIdentifier' => null,
            'oauthClientId' => 'Example string',
            'oauthClientSecret' => 'Example string',
            'logoUrl' => null,
            'authType' => new \stdClass(),
            'cspAllowedOrigins' => null
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request failed: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response Body

**Status Code: 201**

**Example Response Schema**

```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) (Optional)
  "description"?: string // Brief description of the MCP service (Optional)
  "remoteMcpUrl": string (uri) // The URL of the Remote MCP service
  "oauthServerUrl"?: // May have different types (Optional)
  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) (Optional)
  "resourceIdentifier"?: // May have different types (Optional)
  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) (Optional)
  "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. (Optional)
  "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). (Optional)
  "logoUrl"?: // May have different types (Optional)
  string (uri) // Logo: the uploaded storage object key (media/...) or an external URL; read back as a signed URL. (Optional)
  "authType"?:  // How to authenticate with this MCP server.

* `oauth` - OAuth 2.0
* `service_account` - Service Account
* `none` - No Authentication (Optional)
  {
  }
  "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). (Optional)
  "isActive": boolean // Whether this MCP service is currently available for use
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**Example Response Values**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Response string",
  "displayName": "Response string",
  "description": "Response string",
  "remoteMcpUrl": "https://example.com/file.jpg",
  "oauthServerUrl": "https://example.com/file.jpg",
  "resourceIdentifier": "https://example.com/file.jpg",
  "oauthClientId": "Response string",
  "oauthClientSecret": "Response string",
  "logoUrl": "https://example.com/file.jpg",
  "authType": {},
  "cspAllowedOrigins": null,
  "isActive": false,
  "createdAt": "Response string",
  "updatedAt": "Response string"
}
```

***

### Retrieve a Specific Self-hosted MCP Server <a href="#mcp-private-registry-retrieve" id="mcp-private-registry-retrieve"></a>

GET `/api/v1/mcp/private-registry/{id}/`

#### Parameters

| Parameter Name | Required | Type   | Description                                  |
| -------------- | -------- | ------ | -------------------------------------------- |
| `id`           | ✅        | string | A UUID string identifying this MCP Registry. |

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API Call Example (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"

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
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('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request failed:');
    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("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request failed:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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 "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request failed: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response Body

**Status Code: 200**

**Example Response Schema**

```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) (Optional)
  "description"?: string // Brief description of the MCP service (Optional)
  "remoteMcpUrl": string (uri) // The URL of the Remote MCP service
  "oauthServerUrl"?: // May have different types (Optional)
  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) (Optional)
  "resourceIdentifier"?: // May have different types (Optional)
  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) (Optional)
  "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. (Optional)
  "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). (Optional)
  "logoUrl"?: // May have different types (Optional)
  string (uri) // Logo: the uploaded storage object key (media/...) or an external URL; read back as a signed URL. (Optional)
  "authType"?:  // How to authenticate with this MCP server.

* `oauth` - OAuth 2.0
* `service_account` - Service Account
* `none` - No Authentication (Optional)
  {
  }
  "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). (Optional)
  "isActive": boolean // Whether this MCP service is currently available for use
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**Example Response Values**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Response string",
  "displayName": "Response string",
  "description": "Response string",
  "remoteMcpUrl": "https://example.com/file.jpg",
  "oauthServerUrl": "https://example.com/file.jpg",
  "resourceIdentifier": "https://example.com/file.jpg",
  "oauthClientId": "Response string",
  "oauthClientSecret": "Response string",
  "logoUrl": "https://example.com/file.jpg",
  "authType": {},
  "cspAllowedOrigins": null,
  "isActive": false,
  "createdAt": "Response string",
  "updatedAt": "Response string"
}
```

***

### Partially Update a Self-hosted MCP Server <a href="#mcp-private-registry-partial-update" id="mcp-private-registry-partial-update"></a>

PATCH `/api/v1/mcp/private-registry/{id}/`

#### Parameters

| Parameter Name | Required | Type   | Description                                  |
| -------------- | -------- | ------ | -------------------------------------------- |
| `id`           | ✅        | string | A UUID string identifying this MCP Registry. |

#### Request Body

**Request Parameters**

| Field              | Type         | Required | Description                                                                                                                                                                                                    |
| ------------------ | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name               | string       | No       | MCP service name (e.g., Supabase, Sentry). Only alphanumeric, underscore and hyphen allowed.                                                                                                                   |
| displayName        | string       | No       | Human-readable display name (defaults to name if empty)                                                                                                                                                        |
| description        | string       | No       | Brief description of the MCP service                                                                                                                                                                           |
| remoteMcpUrl       | string (uri) | No       | The URL of the Remote MCP service                                                                                                                                                                              |
| oauthServerUrl     | object       | No       | 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       | No       | 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       | No       | 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       | No       | 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       | No       | Logo: the uploaded storage object key (media/...) or an external URL; read back as a signed URL.                                                                                                               |
| authType           | object       | No       | How to authenticate with this MCP server. `oauth`: OAuth 2.0 ; `service_account`: Service Account ; `none`: No Authentication;                                                                                 |
| cspAllowedOrigins  | object       | No       | 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 de... |

**Example Request Schema**

```typescript
{
  "name"?: string // MCP service name (e.g., Supabase, Sentry). Only alphanumeric, underscore and hyphen allowed. (Optional)
  "displayName"?: string // Human-readable display name (defaults to name if empty) (Optional)
  "description"?: string // Brief description of the MCP service (Optional)
  "remoteMcpUrl"?: string (uri) // The URL of the Remote MCP service (Optional)
  "oauthServerUrl"?: // May have different types (Optional)
  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) (Optional)
  "resourceIdentifier"?: // May have different types (Optional)
  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) (Optional)
  "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. (Optional)
  "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). (Optional)
  "logoUrl"?: // May have different types (Optional)
  string (uri) // Logo: the uploaded storage object key (media/...) or an external URL; read back as a signed URL. (Optional)
  "authType"?:  // How to authenticate with this MCP server.

* `oauth` - OAuth 2.0
* `service_account` - Service Account
* `none` - No Authentication (Optional)
  {
  }
  "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). (Optional)
}
```

**Example Request Values**

```json
{
  "name": "Example name",
  "displayName": "Example string",
  "description": "Example string",
  "remoteMcpUrl": "https://example.com/file.jpg",
  "oauthServerUrl": null,
  "resourceIdentifier": null,
  "oauthClientId": "Example string",
  "oauthClientSecret": "Example string",
  "logoUrl": null,
  "authType": {},
  "cspAllowedOrigins": null
}
```

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API Call Example (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": "Example name",
    "displayName": "Example string",
    "description": "Example string",
    "remoteMcpUrl": "https://example.com/file.jpg",
    "oauthServerUrl": null,
    "resourceIdentifier": null,
    "oauthClientId": "Example string",
    "oauthClientSecret": "Example string",
    "logoUrl": null,
    "authType": {},
    "cspAllowedOrigins": null
  }'

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// Request body (payload)
const data = {
    "name": "Example name",
    "displayName": "Example string",
    "description": "Example string",
    "remoteMcpUrl": "https://example.com/file.jpg",
    "oauthServerUrl": null,
    "resourceIdentifier": null,
    "oauthClientId": "Example string",
    "oauthClientSecret": "Example string",
    "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('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request failed:');
    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"
}

# Request body (payload)
data = {
    "name": "Example name",
    "displayName": "Example string",
    "description": "Example string",
    "remoteMcpUrl": "https://example.com/file.jpg",
    "oauthServerUrl": None,
    "resourceIdentifier": None,
    "oauthClientId": "Example string",
    "oauthClientSecret": "Example string",
    "logoUrl": None,
    "authType": {},
    "cspAllowedOrigins": None
}

response = requests.patch(url, json=data, headers=headers)
try:
    print("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request failed:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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' => 'Example name',
            'displayName' => 'Example string',
            'description' => 'Example string',
            'remoteMcpUrl' => 'https://example.com/file.jpg',
            'oauthServerUrl' => null,
            'resourceIdentifier' => null,
            'oauthClientId' => 'Example string',
            'oauthClientSecret' => 'Example string',
            'logoUrl' => null,
            'authType' => new \stdClass(),
            'cspAllowedOrigins' => null
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request failed: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response Body

**Status Code: 200**

**Example Response Schema**

```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) (Optional)
  "description"?: string // Brief description of the MCP service (Optional)
  "remoteMcpUrl": string (uri) // The URL of the Remote MCP service
  "oauthServerUrl"?: // May have different types (Optional)
  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) (Optional)
  "resourceIdentifier"?: // May have different types (Optional)
  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) (Optional)
  "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. (Optional)
  "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). (Optional)
  "logoUrl"?: // May have different types (Optional)
  string (uri) // Logo: the uploaded storage object key (media/...) or an external URL; read back as a signed URL. (Optional)
  "authType"?:  // How to authenticate with this MCP server.

* `oauth` - OAuth 2.0
* `service_account` - Service Account
* `none` - No Authentication (Optional)
  {
  }
  "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). (Optional)
  "isActive": boolean // Whether this MCP service is currently available for use
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**Example Response Values**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Response string",
  "displayName": "Response string",
  "description": "Response string",
  "remoteMcpUrl": "https://example.com/file.jpg",
  "oauthServerUrl": "https://example.com/file.jpg",
  "resourceIdentifier": "https://example.com/file.jpg",
  "oauthClientId": "Response string",
  "oauthClientSecret": "Response string",
  "logoUrl": "https://example.com/file.jpg",
  "authType": {},
  "cspAllowedOrigins": null,
  "isActive": false,
  "createdAt": "Response string",
  "updatedAt": "Response string"
}
```

***

### Delete a Self-hosted MCP Server <a href="#mcp-private-registry-destroy" id="mcp-private-registry-destroy"></a>

DELETE `/api/v1/mcp/private-registry/{id}/`

#### Parameters

| Parameter Name | Required | Type   | Description                                  |
| -------------- | -------- | ------ | -------------------------------------------- |
| `id`           | ✅        | string | A UUID string identifying this MCP Registry. |

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (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"

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

// Request body (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('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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 "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response Body

| Status Code | Description      |
| ----------- | ---------------- |
| 204         | No response body |

***

### Test MCP Server Connection <a href="#mcp-private-registry-test-connection-create" id="mcp-private-registry-test-connection-create"></a>

POST `/api/v1/mcp/private-registry/test-connection/`

#### Request Body

**Request Parameters**

| Field              | Type         | Required | Description                                                                                                                                                                                                    |
| ------------------ | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name               | string       | Yes      | MCP service name (e.g., Supabase, Sentry). Only alphanumeric, underscore and hyphen allowed.                                                                                                                   |
| displayName        | string       | No       | Human-readable display name (defaults to name if empty)                                                                                                                                                        |
| description        | string       | No       | Brief description of the MCP service                                                                                                                                                                           |
| remoteMcpUrl       | string (uri) | Yes      | The URL of the Remote MCP service                                                                                                                                                                              |
| oauthServerUrl     | object       | No       | 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       | No       | 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       | No       | 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       | No       | 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       | No       | Logo: the uploaded storage object key (media/...) or an external URL; read back as a signed URL.                                                                                                               |
| authType           | object       | No       | How to authenticate with this MCP server. `oauth`: OAuth 2.0 ; `service_account`: Service Account ; `none`: No Authentication;                                                                                 |
| cspAllowedOrigins  | object       | No       | 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 de... |

**Example Request Schema**

```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) (Optional)
  "description"?: string // Brief description of the MCP service (Optional)
  "remoteMcpUrl": string (uri) // The URL of the Remote MCP service
  "oauthServerUrl"?: // May have different types (Optional)
  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) (Optional)
  "resourceIdentifier"?: // May have different types (Optional)
  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) (Optional)
  "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. (Optional)
  "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). (Optional)
  "logoUrl"?: // May have different types (Optional)
  string (uri) // Logo: the uploaded storage object key (media/...) or an external URL; read back as a signed URL. (Optional)
  "authType"?:  // How to authenticate with this MCP server.

* `oauth` - OAuth 2.0
* `service_account` - Service Account
* `none` - No Authentication (Optional)
  {
  }
  "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). (Optional)
}
```

**Example Request Values**

```json
{
  "name": "Example name",
  "displayName": "Example string",
  "description": "Example string",
  "remoteMcpUrl": "https://example.com/file.jpg",
  "oauthServerUrl": null,
  "resourceIdentifier": null,
  "oauthClientId": "Example string",
  "oauthClientSecret": "Example string",
  "logoUrl": null,
  "authType": {},
  "cspAllowedOrigins": null
}
```

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (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": "Example name",
    "displayName": "Example string",
    "description": "Example string",
    "remoteMcpUrl": "https://example.com/file.jpg",
    "oauthServerUrl": null,
    "resourceIdentifier": null,
    "oauthClientId": "Example string",
    "oauthClientSecret": "Example string",
    "logoUrl": null,
    "authType": {},
    "cspAllowedOrigins": null
  }'

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// Request body (payload)
const data = {
    "name": "Example name",
    "displayName": "Example string",
    "description": "Example string",
    "remoteMcpUrl": "https://example.com/file.jpg",
    "oauthServerUrl": null,
    "resourceIdentifier": null,
    "oauthClientId": "Example string",
    "oauthClientSecret": "Example string",
    "logoUrl": null,
    "authType": {},
    "cspAllowedOrigins": null
  };

axios.post("https://api.maiagent.ai/api/v1/mcp/private-registry/test-connection/", data, config)
  .then(response => {
    console.log('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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"
}

# Request body (payload)
data = {
    "name": "Example name",
    "displayName": "Example string",
    "description": "Example string",
    "remoteMcpUrl": "https://example.com/file.jpg",
    "oauthServerUrl": None,
    "resourceIdentifier": None,
    "oauthClientId": "Example string",
    "oauthClientSecret": "Example string",
    "logoUrl": None,
    "authType": {},
    "cspAllowedOrigins": None
}

response = requests.post(url, json=data, headers=headers)
try:
    print("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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' => 'Example name',
            'displayName' => 'Example string',
            'description' => 'Example string',
            'remoteMcpUrl' => 'https://example.com/file.jpg',
            'oauthServerUrl' => null,
            'resourceIdentifier' => null,
            'oauthClientId' => 'Example string',
            'oauthClientSecret' => 'Example string',
            'logoUrl' => null,
            'authType' => new \stdClass(),
            'cspAllowedOrigins' => null
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response Body

**Status Code: 200**

**Example Response Schema**

```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) (Optional)
  "description"?: string // Brief description of the MCP service (Optional)
  "remoteMcpUrl": string (uri) // The URL of the Remote MCP service
  "oauthServerUrl"?: // May have different types (Optional)
  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) (Optional)
  "resourceIdentifier"?: // May have different types (Optional)
  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) (Optional)
  "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. (Optional)
  "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). (Optional)
  "logoUrl"?: // May have different types (Optional)
  string (uri) // Logo: the uploaded storage object key (media/...) or an external URL; read back as a signed URL. (Optional)
  "authType"?:  // How to authenticate with this MCP server.

* `oauth` - OAuth 2.0
* `service_account` - Service Account
* `none` - No Authentication (Optional)
  {
  }
  "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). (Optional)
  "isActive": boolean // Whether this MCP service is currently available for use
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
}
```

**Example Response Values**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Response string",
  "displayName": "Response string",
  "description": "Response string",
  "remoteMcpUrl": "https://example.com/file.jpg",
  "oauthServerUrl": "https://example.com/file.jpg",
  "resourceIdentifier": "https://example.com/file.jpg",
  "oauthClientId": "Response string",
  "oauthClientSecret": "Response string",
  "logoUrl": "https://example.com/file.jpg",
  "authType": {},
  "cspAllowedOrigins": null,
  "isActive": false,
  "createdAt": "Response string",
  "updatedAt": "Response string"
}
```

***

### List tool execution records <a href="#tool-execution-records-list" id="tool-execution-records-list"></a>

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

#### Parameters

| Parameter name | Required | Type    | Description                                                    |
| -------------- | -------- | ------- | -------------------------------------------------------------- |
| `chatbot`      | ❌        | string  | Filter by AI assistant ID                                      |
| `endDate`      | ❌        | string  | End date (inclusive), format: YYYY-MM-DD                       |
| `page`         | ❌        | integer | A page number within the paginated result set.                 |
| `pageSize`     | ❌        | integer | Number of results to return per page.                          |
| `query`        | ❌        | string  | Search by AI assistant name, tool name, or message content     |
| `startDate`    | ❌        | string  | Start date (inclusive), format: YYYY-MM-DD                     |
| `status`       | ❌        | string  | Filter by execution status: success, failure, pending, timeout |
| `tool`         | ❌        | string  | Filter by tool ID                                              |
| `toolType`     | ❌        | string  | Filter by tool type: api, function, mcp                        |

#### Code examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (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"

# Before running, replace YOUR_API_KEY and verify the request data.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
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('Successfully retrieved response:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('An error occurred during the request:');
    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("Response retrieved successfully:")
    print(response.json())
except Exception as e:
    print("An error occurred during the request:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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 "Response retrieved successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'An error occurred during the request: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response body

**Status code: 200**

**Example response structure**

```typescript
{
  "count": integer
  "next"?: string (uri) // Optional
  "previous"?: string (uri) // Optional
  "results": [
    {
      "id": string (uuid)
      "tool": object // Tool information
      "chatbot": object // AI assistant information
      "messageContent": string // Message content
      "status"?: string (enum: success, failure, pending, timeout) // * `success` - Success
* `failure` - Failed
* `pending` - Processing
* `timeout` - Timeout (Optional)
      "executionTime": integer // Execution time (milliseconds)
      "errorMessage"?: string // Optional
      "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. (Optional)
      "createdAt": string (timestamp)
      "source": string // Scheduled runs' tool calls are attributed via ChatbotScheduleExecution.user_message.
    }
  ]
}
```

**Example response values**

```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": "Example response name",
        "description": "Example response description"
      },
      "chatbot": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Example response name",
        "description": "Example response description"
      },
      "messageContent": "Response string",
      "status": "success",
      "executionTime": 456,
      "errorMessage": "Response string",
      "retryCount": 456,
      "createdAt": "Response string",
      "source": "Response string"
    }
  ]
}
```

***

### Retrieve a specific tool execution record <a href="#tool-execution-records-retrieve" id="tool-execution-records-retrieve"></a>

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

#### Parameters

| Parameter name | Required | Type   | Description                                           |
| -------------- | -------- | ------ | ----------------------------------------------------- |
| `id`           | ✅        | string | A UUID string identifying this Tool Execution Record. |

#### Code examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (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"

# Before running, replace YOUR_API_KEY and verify the request data.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
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('Successfully retrieved response:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('An error occurred during the request:');
    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("Response retrieved successfully:")
    print(response.json())
except Exception as e:
    print("An error occurred during the request:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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 "Response retrieved successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'An error occurred during the request: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response body

**Status code: 200**

**Example response structure**

```typescript
{
  "id": string (uuid)
  "tool": object // Tool information, including operated_tool_name
  "chatbot": object // AI assistant information
  "message": 
  {
    "id": string (uuid)
    "content": string
  }
  "inputParameters": object
  "outputResult"?: object // Optional
  "errorMessage"?: string // Optional
  "status"?: string (enum: success, failure, pending, timeout) // * `success` - Success
* `failure` - Failed
* `pending` - Processing
* `timeout` - Timeout (Optional)
  "executionTime": integer // Execution time (milliseconds)
  "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. (Optional)
  "requestUrl"?: // Can be of different types (Optional)
  string (uri) // Final rendered URL used when calling an API tool. Null for non-API tools. (Optional)
  "requestMethod"?: string // HTTP method (GET/POST/...) used when calling an API tool. Null for non-API tools. (Optional)
  "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. (Optional)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
  "source": string // Scheduled runs' tool calls are attributed via ChatbotScheduleExecution.user_message.
}
```

**Example response values**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tool": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example response name",
    "description": "Example response description"
  },
  "chatbot": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example response name",
    "description": "Example response description"
  },
  "message": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "content": "Response string"
  },
  "inputParameters": null,
  "outputResult": null,
  "errorMessage": "Response string",
  "status": "success",
  "executionTime": 456,
  "retryCount": 456,
  "requestUrl": "https://example.com/file.jpg",
  "requestMethod": "Response string",
  "requestHeaders": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example response name",
    "description": "Example response description"
  },
  "requestBody": null,
  "createdAt": "Response string",
  "updatedAt": "Response string",
  "source": "Response string"
}
```

***

### Get AI assistant filter options for execution records <a href="#tool-execution-records-chatbots-list" id="tool-execution-records-chatbots-list"></a>

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

#### Parameters

| Parameter Name | Required | Type   | Description                                                                                                                                                         |
| -------------- | -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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; |

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (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"

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
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('Response retrieved successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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("Response retrieved successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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 "Response retrieved successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response Content

**Status Code: 200**

**Response Schema Example**

```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
    }
  }
]
```

**Example Response Values**

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Response string",
    "team": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Response string"
    }
  }
]
```

***

### Get tool filter options for execution records <a href="#tool-execution-records-tools-list" id="tool-execution-records-tools-list"></a>

GET `/api/v1/tool-execution-records/tools/`

#### Parameters

| Parameter name | Required | Type    | Description                                                                                                                                                         |
| -------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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; |

#### Code examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (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"

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
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('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request failed:');
    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("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request failed:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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 "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request failed: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response body

**Status code: 200**

**Example Response Schema**

```typescript
{
  "count": integer
  "next"?: string (uri) // Optional
  "previous"?: string (uri) // Optional
  "results": [
    {
      "id": string (uuid)
      "displayName": string
    }
  ]
}
```

**Example Response Values**

```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": "Response string"
    }
  ]
}
```

***

### List execution records for a specific tool <a href="#tools-tool-execution-records-list" id="tools-tool-execution-records-list"></a>

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

#### Parameters

| Parameter name | Required | Type    | Description                                                    |
| -------------- | -------- | ------- | -------------------------------------------------------------- |
| `toolPk`       | ✅        | string  |                                                                |
| `chatbot`      | ❌        | string  | Filter by AI assistant ID                                      |
| `endDate`      | ❌        | string  | End date (inclusive), format: YYYY-MM-DD                       |
| `page`         | ❌        | integer | A page number within the paginated result set.                 |
| `pageSize`     | ❌        | integer | Number of results to return per page.                          |
| `query`        | ❌        | string  | Search by AI assistant name, tool name, or message content     |
| `startDate`    | ❌        | string  | Start date (inclusive), format: YYYY-MM-DD                     |
| `status`       | ❌        | string  | Filter by execution status: success, failure, pending, timeout |
| `tool`         | ❌        | string  | Filter by tool ID                                              |
| `toolType`     | ❌        | string  | Filter by tool type: api, function, mcp                        |

#### Code examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (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"

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
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('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request failed:');
    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("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request failed:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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 "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request failed: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response body

**Status code: 200**

**Example Response Schema**

```typescript
{
  "count": integer
  "next"?: string (uri) // Optional
  "previous"?: string (uri) // Optional
  "results": [
    {
      "id": string (uuid)
      "tool": object // Tool information
      "chatbot": object // AI assistant information
      "messageContent": string // Message content
      "status"?: string (enum: success, failure, pending, timeout) // * `success` - Success
* `failure` - Failed
* `pending` - Processing
* `timeout` - Timeout (Optional)
      "executionTime": integer // Execution time (milliseconds)
      "errorMessage"?: string // Optional
      "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. (Optional)
      "createdAt": string (timestamp)
      "source": string // Scheduled runs' tool calls are attributed via ChatbotScheduleExecution.user_message.
    }
  ]
}
```

**Example Response Values**

```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": "Example response name",
        "description": "Example response description"
      },
      "chatbot": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Example response name",
        "description": "Example response description"
      },
      "messageContent": "Response string",
      "status": "success",
      "executionTime": 456,
      "errorMessage": "Response string",
      "retryCount": 456,
      "createdAt": "Response string",
      "source": "Response string"
    }
  ]
}
```

***

### Get a specific execution record for a specific tool <a href="#tools-tool-execution-records-retrieve" id="tools-tool-execution-records-retrieve"></a>

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

#### Parameters

| Parameter name | Required | Type   | Description                                           |
| -------------- | -------- | ------ | ----------------------------------------------------- |
| `id`           | ✅        | string | A UUID string identifying this Tool Execution Record. |
| `toolPk`       | ✅        | string |                                                       |

#### Code examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (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"

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
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('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request failed:');
    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("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request failed:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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 "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request failed: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response body

**Status code: 200**

**Example Response Schema**

```typescript
{
  "id": string (uuid)
  "tool": object // Tool information, including operated_tool_name
  "chatbot": object // AI assistant information
  "message": 
  {
    "id": string (uuid)
    "content": string
  }
  "inputParameters": object
  "outputResult"?: object // Optional
  "errorMessage"?: string // Optional
  "status"?: string (enum: success, failure, pending, timeout) // * `success` - Success
* `failure` - Failed
* `pending` - Processing
* `timeout` - Timeout (Optional)
  "executionTime": integer // Execution time (milliseconds)
  "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. (Optional)
  "requestUrl"?: // May have different types (Optional)
  string (uri) // Final rendered URL used when calling an API tool. Null for non-API tools. (Optional)
  "requestMethod"?: string // HTTP method (GET/POST/...) used when calling an API tool. Null for non-API tools. (Optional)
  "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. (Optional)
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
  "source": string // Scheduled runs' tool calls are attributed via ChatbotScheduleExecution.user_message.
}
```

**Example Response Values**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tool": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example response name",
    "description": "Example response description"
  },
  "chatbot": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example response name",
    "description": "Example response description"
  },
  "message": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "content": "Response string"
  },
  "inputParameters": null,
  "outputResult": null,
  "errorMessage": "Response string",
  "status": "success",
  "executionTime": 456,
  "retryCount": 456,
  "requestUrl": "https://example.com/file.jpg",
  "requestMethod": "Response string",
  "requestHeaders": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example response name",
    "description": "Example response description"
  },
  "requestBody": null,
  "createdAt": "Response string",
  "updatedAt": "Response string",
  "source": "Response string"
}
```

***

### Get AI Assistant Filter Options for a Specific Tool’s Execution Records <a href="#tools-tool-execution-records-chatbots-list" id="tools-tool-execution-records-chatbots-list"></a>

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

#### Parameters

| Parameter Name | Required | Type   | Description                                                                                                                                                         |
| -------------- | -------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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; |

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API Call Example (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"

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
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('Response retrieved successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request failed:');
    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("Response retrieved successfully:")
    print(response.json())
except Exception as e:
    print("Request failed:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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 "Response retrieved successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request failed: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response Body

**Status Code: 200**

**Example Response Structure**

```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
    }
  }
]
```

**Example Response Values**

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Response string",
    "team": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Response string"
    }
  }
]
```

***

### Get Tool Filter Options for a Specific Tool's Execution Records <a href="#tools-tool-execution-records-tools-list" id="tools-tool-execution-records-tools-list"></a>

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

#### Parameters

| Parameter Name | Required | Type    | Description                                                                                                                                                         |
| -------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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; |

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API Call Example (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"

# Make sure to replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
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('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('An error occurred during the request:');
    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("Response received successfully:")
    print(response.json())
except Exception as e:
    print("An error occurred during the request:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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 "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'An error occurred during the request: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response Body

**Status Code: 200**

**Example Response Schema**

```typescript
{
  "count": integer
  "next"?: string (uri) // Optional
  "previous"?: string (uri) // Optional
  "results": [
    {
      "id": string (uuid)
      "displayName": string
    }
  ]
}
```

**Example Response Values**

```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": "Response string"
    }
  ]
}
```

***


---

# 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/en/api-reference/gong-ju-he-lian-jie-qi.md?ask=<question>&goal=<user_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.