# Tools

9 calls. Every request needs the `Authorization` header: see [the overview](https://docs.maitento.com/reference.md).

## `tools.list`

```http
GET /external-operations
```

Every definition of the tenant, or of one namespace with `{ namespace }`.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fexternal-operations).

**Response:** [`ExternalOperation`](https://docs.maitento.com/reference/types/external-operation.md)`[]` (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/external-operations" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const tools = await mt.tools.list();
```
```python title="Python"
mt.tools.list()
```

## `tools.delete`

```http
DELETE /external-operations/by-id/{id}
```

Deletes the definition (refused with a 400 while something still uses it or a run of it is going).

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=DELETE%20%2Fexternal-operations%2Fby-id%2F%7Bid%7D).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Response:** no body (204)

```bash title="curl"
curl -X DELETE "https://api.maitento.com/external-operations/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.tools.delete("1f2e3d4c-5b6a-4798-8a9b-cdef01234567");
```
```python title="Python"
mt.tools.delete("f0a1b2c3-d4e5-4f6a-b7c8-d9e0f1a2b3c4")
```

## `tools.get`

```http
GET /external-operations/by-id/{id}
```

The definition with this id. Throws `NotFoundError` when there is none.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fexternal-operations%2Fby-id%2F%7Bid%7D).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |

**Response:** [`ExternalOperation`](https://docs.maitento.com/reference/types/external-operation.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/external-operations/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const tool = await mt.tools.get("1f2e3d4c-5b6a-4798-8a9b-cdef01234567");
```
```python title="Python"
mt.tools.get("f0a1b2c3-d4e5-4f6a-b7c8-d9e0f1a2b3c4")
```

## `tools.disableVersion`

```http
POST /external-operations/by-id/{id}/versions/{version}/disable
```

Disables one version: everything pinned to it fails closed.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=POST%20%2Fexternal-operations%2Fby-id%2F%7Bid%7D%2Fversions%2F%7Bversion%7D%2Fdisable).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |
| `version` | `integer` | yes |  |

**Response:** [`ExternalOperation`](https://docs.maitento.com/reference/types/external-operation.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/external-operations/by-id/<id>/versions/<version>/disable" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.tools.disableVersion("1f2e3d4c-5b6a-4798-8a9b-cdef01234567", 1);
```
```python title="Python"
mt.tools.disable_version("f0a1b2c3-d4e5-4f6a-b7c8-d9e0f1a2b3c4", 3)
```

## `tools.enableVersion`

```http
POST /external-operations/by-id/{id}/versions/{version}/enable
```

Enables a disabled version again.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=POST%20%2Fexternal-operations%2Fby-id%2F%7Bid%7D%2Fversions%2F%7Bversion%7D%2Fenable).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `id` | `uuid` | yes |  |
| `version` | `integer` | yes |  |

**Response:** [`ExternalOperation`](https://docs.maitento.com/reference/types/external-operation.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/external-operations/by-id/<id>/versions/<version>/enable" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.tools.enableVersion("1f2e3d4c-5b6a-4798-8a9b-cdef01234567", 1);
```
```python title="Python"
mt.tools.enable_version("f0a1b2c3-d4e5-4f6a-b7c8-d9e0f1a2b3c4", 3)
```

## `tools.list`

```http
GET /namespaces/{namespaceName}/external-operations
```

Every definition of the tenant, or of one namespace with `{ namespace }`.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fexternal-operations).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |

**Response:** [`ExternalOperation`](https://docs.maitento.com/reference/types/external-operation.md)`[]` (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/namespaces/<namespaceName>/external-operations" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const tools = await mt.tools.list({ namespace: "support" });
```
```python title="Python"
mt.tools.list(namespace="demo")
```

## `tools.getByName`

```http
GET /namespaces/{namespaceName}/external-operations/by-name/{name}
```

The definition with this name in the namespace. Throws `NotFoundError` when there is none.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=GET%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fexternal-operations%2Fby-name%2F%7Bname%7D).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |
| `name` | `string` | yes |  |

**Response:** [`ExternalOperation`](https://docs.maitento.com/reference/types/external-operation.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/namespaces/<namespaceName>/external-operations/by-name/<name>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const tool = await mt.tools.getByName("get-order", { namespace: "support" });
```
```python title="Python"
mt.tools.get_by_name("get-order", namespace="demo")
```

## `tools.createMcp`

```http
POST /namespaces/{namespaceName}/external-operations/mcp
```

Creates a tool over an MCP connector.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=POST%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fexternal-operations%2Fmcp).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |

**Request body:** [`McpExternalOperationCreateRequest`](https://docs.maitento.com/reference/types/mcp-external-operation-create-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | yes | The tool's name, unique within its namespace (under 150 characters). The model calls the tool by it. |
| `connectorId` | `uuid` | yes | The id of the connector the tool calls. |
| `connectorVersion` | `integer \| null` |  | The connector version to build on. Omitted: the connector's latest enabled version when the tool is saved. A tool version always calls one exact connector version. |
| `requestBindings` | [`ConnectorBinding`](https://docs.maitento.com/reference/types/connector-binding.md)`[]` | yes | Fixed values for fields of the request body, which the model never sees or chooses (`[]` for none). |
| `authenticationHeader` | [`ConnectorAuthenticationHeader`](https://docs.maitento.com/reference/types/connector-authentication-header.md)`\| null` |  | The credential sent with every call, from a secret. The connector needs `Header` authentication. |
| `promptGuidance` | `string \| null` |  | When and how to use the tool, written for the model (under 10,000 characters). Omitted: the connector's description. |
| `requiresApproval` | `boolean` |  | Whether a person must approve each call before it is made. The run waits with status `PendingApproval`. |

**Response:** [`McpExternalOperation`](https://docs.maitento.com/reference/types/mcp-external-operation.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/namespaces/<namespaceName>/external-operations/mcp" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"name":"...","connectorId":"...","requestBindings":[]}'
```
```ts title="TypeScript"
await mt.tools.createMcp({ name: "search-docs", connectorId: "9b2f1c4e-6d3a-4e8b-a5c7-0f1e2d3c4b5a", requestBindings: [] }, { namespace: "support" });
```
```python title="Python"
mt.tools.create_mcp(name="search-docs", connector_id="e5f6a7b8-c9d0-4e1f-a2b3-c4d5e6f7a8b9", namespace="demo")
```

## `tools.createOpenApi`

```http
POST /namespaces/{namespaceName}/external-operations/open-api
```

Creates a tool over an OpenAPI connector.

**Who can call it:** Admins and members, with an API key or a portal session. [Try it in the API playground](https://docs.maitento.com/playground/?call=POST%20%2Fnamespaces%2F%7BnamespaceName%7D%2Fexternal-operations%2Fopen-api).

**Path parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `namespaceName` | `string` | yes |  |

**Request body:** [`OpenApiExternalOperationCreateRequest`](https://docs.maitento.com/reference/types/open-api-external-operation-create-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `pathBindings` | [`ConnectorBinding`](https://docs.maitento.com/reference/types/connector-binding.md)`[]` | yes | Fixed values for the connector's path parameters (`[]` for none). |
| `queryBindings` | [`ConnectorBinding`](https://docs.maitento.com/reference/types/connector-binding.md)`[]` | yes | Fixed values for the connector's query parameters (`[]` for none). |
| `name` | `string` | yes | The tool's name, unique within its namespace (under 150 characters). The model calls the tool by it. |
| `connectorId` | `uuid` | yes | The id of the connector the tool calls. |
| `connectorVersion` | `integer \| null` |  | The connector version to build on. Omitted: the connector's latest enabled version when the tool is saved. A tool version always calls one exact connector version. |
| `requestBindings` | [`ConnectorBinding`](https://docs.maitento.com/reference/types/connector-binding.md)`[]` | yes | Fixed values for fields of the request body, which the model never sees or chooses (`[]` for none). |
| `authenticationHeader` | [`ConnectorAuthenticationHeader`](https://docs.maitento.com/reference/types/connector-authentication-header.md)`\| null` |  | The credential sent with every call, from a secret. The connector needs `Header` authentication. |
| `promptGuidance` | `string \| null` |  | When and how to use the tool, written for the model (under 10,000 characters). Omitted: the connector's description. |
| `requiresApproval` | `boolean` |  | Whether a person must approve each call before it is made. The run waits with status `PendingApproval`. |

**Response:** [`OpenApiExternalOperation`](https://docs.maitento.com/reference/types/open-api-external-operation.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/namespaces/<namespaceName>/external-operations/open-api" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"pathBindings":[],"queryBindings":[],"name":"...","connectorId":"...","requestBindings":[]}'
```
```ts title="TypeScript"
await mt.tools.createOpenApi({ name: "get-order", connectorId: "9b2f1c4e-6d3a-4e8b-a5c7-0f1e2d3c4b5a", promptGuidance: "Look up an order by its number.", requestBindings: [], pathBindings: [], queryBindings: [] }, { namespace: "support" });
```
```python title="Python"
mt.tools.create_open_api(name="get-order", connector_id="e5f6a7b8-c9d0-4e1f-a2b3-c4d5e6f7a8b9", prompt_guidance="Look up an order by its number.", authentication_header={"headerName": "X-Api-Key", "secretId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"}, namespace="demo")
```