# Connectors

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

## `connectors.list`

```http
GET /connectors
```

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%2Fconnectors).

**Response:** [`Connector`](https://docs.maitento.com/reference/types/connector.md)`[]` (200)

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

## `connectors.delete`

```http
DELETE /connectors/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%2Fconnectors%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/connectors/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.connectors.delete("9b2f1c4e-6d3a-4e8b-a5c7-0f1e2d3c4b5a");
```
```python title="Python"
mt.connectors.delete("e5f6a7b8-c9d0-4e1f-a2b3-c4d5e6f7a8b9")
```

## `connectors.get`

```http
GET /connectors/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%2Fconnectors%2Fby-id%2F%7Bid%7D).

**Path parameters**

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

**Response:** [`Connector`](https://docs.maitento.com/reference/types/connector.md) (200)

```bash title="curl"
curl -X GET "https://api.maitento.com/connectors/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const connector = await mt.connectors.get("9b2f1c4e-6d3a-4e8b-a5c7-0f1e2d3c4b5a");
```
```python title="Python"
mt.connectors.get("e5f6a7b8-c9d0-4e1f-a2b3-c4d5e6f7a8b9")
```

## `connectors.disableVersion`

```http
POST /connectors/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%2Fconnectors%2Fby-id%2F%7Bid%7D%2Fversions%2F%7Bversion%7D%2Fdisable).

**Path parameters**

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

**Response:** [`Connector`](https://docs.maitento.com/reference/types/connector.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/connectors/by-id/<id>/versions/<version>/disable" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.connectors.disableVersion("9b2f1c4e-6d3a-4e8b-a5c7-0f1e2d3c4b5a", 2);
```
```python title="Python"
mt.connectors.disable_version("e5f6a7b8-c9d0-4e1f-a2b3-c4d5e6f7a8b9", 2)
```

## `connectors.enableVersion`

```http
POST /connectors/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%2Fconnectors%2Fby-id%2F%7Bid%7D%2Fversions%2F%7Bversion%7D%2Fenable).

**Path parameters**

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

**Response:** [`Connector`](https://docs.maitento.com/reference/types/connector.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/connectors/by-id/<id>/versions/<version>/enable" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.connectors.enableVersion("9b2f1c4e-6d3a-4e8b-a5c7-0f1e2d3c4b5a", 2);
```
```python title="Python"
mt.connectors.enable_version("e5f6a7b8-c9d0-4e1f-a2b3-c4d5e6f7a8b9", 2)
```

## `connectors.list`

```http
GET /namespaces/{namespaceName}/connectors
```

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%2Fconnectors).

**Path parameters**

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

**Response:** [`Connector`](https://docs.maitento.com/reference/types/connector.md)`[]` (200)

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

## `connectors.getByName`

```http
GET /namespaces/{namespaceName}/connectors/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%2Fconnectors%2Fby-name%2F%7Bname%7D).

**Path parameters**

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

**Response:** [`Connector`](https://docs.maitento.com/reference/types/connector.md) (200)

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

## `connectors.createMcp`

```http
POST /namespaces/{namespaceName}/connectors/mcp
```

Creates an MCP connector (it can be described and bound, but interactions cannot execute it today).

**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%2Fconnectors%2Fmcp).

**Path parameters**

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

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

| Field | Type | Required | Description |
|---|---|---|---|
| `destructiveHint` | `boolean \| null` |  | The MCP tool annotation `destructiveHint`: whether the tool may destroy or overwrite data. |
| `idempotentHint` | `boolean \| null` |  | The MCP tool annotation `idempotentHint`: whether repeating a call with the same arguments has no further effect. |
| `openWorldHint` | `boolean \| null` |  | The MCP tool annotation `openWorldHint`: whether the tool reaches systems outside the server. |
| `readOnlyHint` | `boolean \| null` |  | The MCP tool annotation `readOnlyHint`: whether the tool only reads and changes nothing. |
| `name` | `string` | yes | The connector's name, unique within its namespace (under 150 characters). |
| `url` | `string` | yes | The endpoint's URL. For an HTTP connector, `{name}` in it marks a path parameter; for an MCP connector, it is the MCP server's URL. |
| `description` | `string` | yes | What the endpoint does, in a sentence (under 500 characters). |
| `requestSchemaJson` | `string \| null` |  | The JSON Schema of the request body, as text. The model's arguments are checked against it before a call is made. Omitted: no body is sent. |
| `responseSchemaJson` | `string \| null` |  | The JSON Schema the endpoint's response must match, as text. Omitted: the response is not checked. |
| `authenticationType` | [`ConnectorAuthenticationType`](https://docs.maitento.com/reference/types/connector-authentication-type.md) | yes | The kind of credential the endpoint needs. The credential itself is given where a tool uses the connector. |
| `postProcessResponseUnicodeCharacters` | `boolean` |  | Whether to replace typographic characters in the response (curly quotes, dashes, bullets, the ellipsis) with plain ones before it is read. Defaults to false. |

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

```bash title="curl"
curl -X POST "https://api.maitento.com/namespaces/<namespaceName>/connectors/mcp" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"name":"...","url":"...","description":"...","authenticationType":"None"}'
```
```ts title="TypeScript"
await mt.connectors.createMcp({ name: "search-docs", url: "https://mcp.example.com/search", description: "Searches the docs", authenticationType: "None" }, { namespace: "support" });
```
```python title="Python"
mt.connectors.create_mcp(name="docs-search", url="https://mcp.example.com/sse", description="Searches the product docs", authentication_type="None", namespace="demo")
```

## `connectors.createOpenApi`

```http
POST /namespaces/{namespaceName}/connectors/open-api
```

Creates an OpenAPI connector: one HTTP endpoint Maitento may call.

**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%2Fconnectors%2Fopen-api).

**Path parameters**

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

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

| Field | Type | Required | Description |
|---|---|---|---|
| `httpMethod` | [`HttpMethod`](https://docs.maitento.com/reference/types/http-method.md) | yes | The HTTP method. |
| `pathParameters` | [`OpenApiParameterInput`](https://docs.maitento.com/reference/types/open-api-parameter.md#in-a-request)`[]` | yes | The parameters in the URL's path, one for each `{name}` in `url` (`[]` for none). |
| `queryParameters` | [`OpenApiParameterInput`](https://docs.maitento.com/reference/types/open-api-parameter.md#in-a-request)`[]` | yes | The query-string parameters (`[]` for none). |
| `name` | `string` | yes | The connector's name, unique within its namespace (under 150 characters). |
| `url` | `string` | yes | The endpoint's URL. For an HTTP connector, `{name}` in it marks a path parameter; for an MCP connector, it is the MCP server's URL. |
| `description` | `string` | yes | What the endpoint does, in a sentence (under 500 characters). |
| `requestSchemaJson` | `string \| null` |  | The JSON Schema of the request body, as text. The model's arguments are checked against it before a call is made. Omitted: no body is sent. |
| `responseSchemaJson` | `string \| null` |  | The JSON Schema the endpoint's response must match, as text. Omitted: the response is not checked. |
| `authenticationType` | [`ConnectorAuthenticationType`](https://docs.maitento.com/reference/types/connector-authentication-type.md) | yes | The kind of credential the endpoint needs. The credential itself is given where a tool uses the connector. |
| `postProcessResponseUnicodeCharacters` | `boolean` |  | Whether to replace typographic characters in the response (curly quotes, dashes, bullets, the ellipsis) with plain ones before it is read. Defaults to false. |

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

```bash title="curl"
curl -X POST "https://api.maitento.com/namespaces/<namespaceName>/connectors/open-api" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"httpMethod":{"method":"..."},"pathParameters":[],"queryParameters":[],"name":"...","url":"...","description":"...","authenticationType":"None"}'
```
```ts title="TypeScript"
await mt.connectors.createOpenApi({ name: "orders-get", url: "https://api.example.com/orders/{orderId}", description: "Reads an order", httpMethod: "GET", authenticationType: "Header", pathParameters: [{ name: "orderId", description: "The order number", dataType: "String", isRequired: true }], queryParameters: [] }, { namespace: "support" });
```
```python title="Python"
mt.connectors.create_open_api(name="orders-get", url="https://api.example.com/orders/{orderId}", description="Reads one order", http_method="GET", authentication_type="Header", path_parameters=[{"name": "orderId", "description": "The order number", "dataType": "String", "isRequired": True}], namespace="demo")
```