# Interactions

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

## `interactions.list`

```http
GET /interactions
```

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

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

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

## `interactions.delete`

```http
DELETE /interactions/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%2Finteractions%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/interactions/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
await mt.interactions.delete("0e7d9b3c-2f1a-4c5e-9d8b-7a6f5e4d3c2b");
```
```python title="Python"
mt.interactions.delete("8c3b2a1d-4e5f-4a6b-9c7d-0e1f2a3b4c5d")
```

## `interactions.get`

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

**Path parameters**

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

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

```bash title="curl"
curl -X GET "https://api.maitento.com/interactions/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const interaction = await mt.interactions.get("0e7d9b3c-2f1a-4c5e-9d8b-7a6f5e4d3c2b");
```
```python title="Python"
mt.interactions.get("8c3b2a1d-4e5f-4a6b-9c7d-0e1f2a3b4c5d")
```

## `interactions.updateManaged`

```http
PUT /interactions/managed/by-id/{id}
```

Updates a managed interaction.

**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=PUT%20%2Finteractions%2Fmanaged%2Fby-id%2F%7Bid%7D).

**Path parameters**

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

**Request body:** [`ManagedInteractionUpdateRequest`](https://docs.maitento.com/reference/types/managed-interaction-update-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `managerAgent` | [`InteractionAgentBindingInput`](https://docs.maitento.com/reference/types/interaction-agent-binding.md#in-a-request) | yes | The manager: the agent that runs the conversation and dispatches work to the others. |
| `agents` | [`ManagedInteractionAgentBindingInput`](https://docs.maitento.com/reference/types/managed-interaction-agent-binding.md#in-a-request)`[]` | yes | The agents the manager can dispatch to, each with what it sees when it is dispatched to. |
| `humanSettings` | [`RoundRobinInteractionHumanSettingsInput`](https://docs.maitento.com/reference/types/round-robin-interaction-human-settings.md#in-a-request)`\| null` |  | Whether a person talks with the manager, and who speaks first. Null: no one does. |
| `maxDispatches` | `integer \| null` |  | The most dispatches one run may make, 1 to 200. Null: 30. |
| `name` | `string` | yes | The interaction's name, unique within its namespace. |
| `prompt` | `string` | yes | What the agents are asked to do. A run's inputs are filled in wherever it says `%%name%%`. |
| `solutionSchema` | `string \| null` |  | The JSON Schema the answer must match, as JSON text: the run's output is then JSON of that shape. Null: the output is free text. |
| `systemPromptMode` | [`InteractionSystemPromptMode`](https://docs.maitento.com/reference/types/interaction-system-prompt-mode.md) | yes | How `systemPrompts` combine with the instructions Maitento gives every agent. |
| `systemPrompts` | `string[]` | yes | Extra system instructions for every agent in the interaction. |
| `durationWarningToAi` | `timespan \| null` |  | How long into a run the agents are told that time is running short. Null: they are not told. |
| `durationAutoTermination` | `timespan \| null` |  | The longest a run may take. The run stops with an error when it is reached; time spent waiting for a person does not count. Null: no limit. |
| `contextSettings` | [`InteractionContextSettingsInput`](https://docs.maitento.com/reference/types/interaction-context-settings.md#in-a-request)`\| null` |  | How the conversation is kept within the model's context window, and how many rounds of tool calls an agent may make in one turn. Null: the defaults. |
| `swarm` | [`InteractionSwarmSettingsInput`](https://docs.maitento.com/reference/types/interaction-swarm-settings.md#in-a-request)`\| null` |  | The sub-interactions its participants may start. Null: none. |
| `credentialStack` | `string \| null` |  | The credential stack its runs use, by id or name, when their start doesn't name one. Null: the namespace's default stack, then your tenant's. A stack that doesn't exist when a run starts refuses the run. |
| `externalOperationsOpenApi` | [`OpenApiExternalOperationBindingInput`](https://docs.maitento.com/reference/types/open-api-external-operation-binding.md#in-a-request)`[]` | yes | Tools from OpenAPI connectors that every agent in the interaction can call, as well as its own tools. |
| `externalOperationsMcp` | [`McpExternalOperationBindingInput`](https://docs.maitento.com/reference/types/mcp-external-operation-binding.md#in-a-request)`[]` | yes | Tools from MCP connectors that every agent in the interaction can call, as well as its own tools. |
| `inputsConnectorAuthenticationSecret` | [`ConnectorAuthenticationSecretInputInput`](https://docs.maitento.com/reference/types/connector-authentication-secret-input.md#in-a-request)`[]` | yes | Run inputs that choose the secret a tool sends with its calls. |
| `inputsConnectorBinding` | [`ConnectorBindingInputInput`](https://docs.maitento.com/reference/types/connector-binding-input.md#in-a-request)`[]` | yes | Run inputs whose values go straight into a tool's calls, so the model never sees or chooses them. |
| `inputsPrompt` | [`PromptInputInput`](https://docs.maitento.com/reference/types/prompt-input.md#in-a-request)`[]` | yes | The inputs a run is started with, which the prompt uses as `%%name%%`. |
| `loom` | [`LoomConfigurationInput`](https://docs.maitento.com/reference/types/loom-configuration.md#in-a-request)`\| null` |  | Long-term memory for the interaction's agents. Null: no memory. |

**Response:** [`ManagedInteraction`](https://docs.maitento.com/reference/types/managed-interaction.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/interactions/managed/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"managerAgent":{"name":"...","agent":{},"externalOperationsMcp":[],"externalOperationsOpenApi":[],"loomId":"...","webAccess":{}},"agents":[],"name":"...","prompt":"...","systemPromptMode":"AppendToDefault","systemPrompts":[],"externalOperationsOpenApi":[],"externalOperationsMcp":[],"inputsConnectorAuthenticationSecret":[],"inputsConnectorBinding":[],"inputsPrompt":[]}'
```
```ts title="TypeScript"
await mt.interactions.updateManaged("0e7d9b3c-2f1a-4c5e-9d8b-7a6f5e4d3c2b", { ...definition, maxDispatches: 12 });
```
```python title="Python"
mt.interactions.update_managed("8c3b2a1d-4e5f-4a6b-9c7d-0e1f2a3b4c5d", name="desk", prompt="Route the question to the right expert.", system_prompt_mode="AppendToDefault", manager_agent={"name": "Router", "agent": {"id": "2f1e8c4a-7b3d-4e9f-a1c2-5d6e7f809a1b", "version": 2}}, agents=[{"mode": "OneTime", "name": "Cook", "agent": {"id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f", "version": 1}}])
```

## `interactions.updateOneShot`

```http
PUT /interactions/one-shot/by-id/{id}
```

Updates a one-shot interaction (a new version when anything changed).

**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=PUT%20%2Finteractions%2Fone-shot%2Fby-id%2F%7Bid%7D).

**Path parameters**

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

**Request body:** [`OneShotInteractionUpdateRequest`](https://docs.maitento.com/reference/types/one-shot-interaction-update-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `agent` | [`InteractionAgentBindingInput`](https://docs.maitento.com/reference/types/interaction-agent-binding.md#in-a-request) | yes | The agent that takes the task. |
| `name` | `string` | yes | The interaction's name, unique within its namespace. |
| `prompt` | `string` | yes | What the agents are asked to do. A run's inputs are filled in wherever it says `%%name%%`. |
| `solutionSchema` | `string \| null` |  | The JSON Schema the answer must match, as JSON text: the run's output is then JSON of that shape. Null: the output is free text. |
| `systemPromptMode` | [`InteractionSystemPromptMode`](https://docs.maitento.com/reference/types/interaction-system-prompt-mode.md) | yes | How `systemPrompts` combine with the instructions Maitento gives every agent. |
| `systemPrompts` | `string[]` | yes | Extra system instructions for every agent in the interaction. |
| `durationWarningToAi` | `timespan \| null` |  | How long into a run the agents are told that time is running short. Null: they are not told. |
| `durationAutoTermination` | `timespan \| null` |  | The longest a run may take. The run stops with an error when it is reached; time spent waiting for a person does not count. Null: no limit. |
| `contextSettings` | [`InteractionContextSettingsInput`](https://docs.maitento.com/reference/types/interaction-context-settings.md#in-a-request)`\| null` |  | How the conversation is kept within the model's context window, and how many rounds of tool calls an agent may make in one turn. Null: the defaults. |
| `swarm` | [`InteractionSwarmSettingsInput`](https://docs.maitento.com/reference/types/interaction-swarm-settings.md#in-a-request)`\| null` |  | The sub-interactions its participants may start. Null: none. |
| `credentialStack` | `string \| null` |  | The credential stack its runs use, by id or name, when their start doesn't name one. Null: the namespace's default stack, then your tenant's. A stack that doesn't exist when a run starts refuses the run. |
| `externalOperationsOpenApi` | [`OpenApiExternalOperationBindingInput`](https://docs.maitento.com/reference/types/open-api-external-operation-binding.md#in-a-request)`[]` | yes | Tools from OpenAPI connectors that every agent in the interaction can call, as well as its own tools. |
| `externalOperationsMcp` | [`McpExternalOperationBindingInput`](https://docs.maitento.com/reference/types/mcp-external-operation-binding.md#in-a-request)`[]` | yes | Tools from MCP connectors that every agent in the interaction can call, as well as its own tools. |
| `inputsConnectorAuthenticationSecret` | [`ConnectorAuthenticationSecretInputInput`](https://docs.maitento.com/reference/types/connector-authentication-secret-input.md#in-a-request)`[]` | yes | Run inputs that choose the secret a tool sends with its calls. |
| `inputsConnectorBinding` | [`ConnectorBindingInputInput`](https://docs.maitento.com/reference/types/connector-binding-input.md#in-a-request)`[]` | yes | Run inputs whose values go straight into a tool's calls, so the model never sees or chooses them. |
| `inputsPrompt` | [`PromptInputInput`](https://docs.maitento.com/reference/types/prompt-input.md#in-a-request)`[]` | yes | The inputs a run is started with, which the prompt uses as `%%name%%`. |
| `loom` | [`LoomConfigurationInput`](https://docs.maitento.com/reference/types/loom-configuration.md#in-a-request)`\| null` |  | Long-term memory for the interaction's agents. Null: no memory. |

**Response:** [`OneShotInteraction`](https://docs.maitento.com/reference/types/one-shot-interaction.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/interactions/one-shot/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"agent":{"name":"...","agent":{},"externalOperationsMcp":[],"externalOperationsOpenApi":[],"loomId":"...","webAccess":{}},"name":"...","prompt":"...","systemPromptMode":"AppendToDefault","systemPrompts":[],"externalOperationsOpenApi":[],"externalOperationsMcp":[],"inputsConnectorAuthenticationSecret":[],"inputsConnectorBinding":[],"inputsPrompt":[]}'
```
```ts title="TypeScript"
await mt.interactions.updateOneShot("0e7d9b3c-2f1a-4c5e-9d8b-7a6f5e4d3c2b", { ...definition, prompt: "Say hello in French." });
```
```python title="Python"
mt.interactions.update_one_shot("8c3b2a1d-4e5f-4a6b-9c7d-0e1f2a3b4c5d", name="hello", prompt="Say hello to %%name%% warmly.", system_prompt_mode="AppendToDefault", agent={"name": "Greeter", "agent": {"id": "2f1e8c4a-7b3d-4e9f-a1c2-5d6e7f809a1b", "version": 2}})
```

## `interactions.start`

```http
PUT /interactions/processes/by-id/{id}/start
```

Starts a run of the interaction's latest enabled version and returns it (status `New`). Starts work, so it is never retried. To wait for the answer, use {@link run}.

**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=PUT%20%2Finteractions%2Fprocesses%2Fby-id%2F%7Bid%7D%2Fstart).

**Path parameters**

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

**Request body:** [`InteractionProcessStartRequest`](https://docs.maitento.com/reference/types/interaction-process-start-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `inputs` | [`NameValuePair`](https://docs.maitento.com/reference/types/name-value-pair.md)`[]` | yes | The run's inputs, by name. Every required input must be given. |
| `loomMappings` | [`LoomMappingRequest`](https://docs.maitento.com/reference/types/loom-mapping-request.md)`[] \| null` |  | The loom particular agents wake up with in this run, in place of the one the interaction would choose. |
| `loomGifts` | [`LoomStartGiftRequest`](https://docs.maitento.com/reference/types/loom-start-gift-request.md)`[] \| null` |  | Threads to hand to agents as they start, so they wake up knowing them, and knowing they were told. |
| `aiModelOverrides` | [`AiModelOverrideRequestInput`](https://docs.maitento.com/reference/types/ai-model-override-request.md#in-a-request)`[] \| null` |  | Agents to run on a different model in this run. |
| `responseJsonSchema` | `string \| null` |  | A JSON Schema the run's answer must match, in place of the interaction's own. Must be a valid JSON Schema. |
| `disabledTools` | `string[] \| null` |  | The names of tools this run's agents are not given. |
| `credentials` | [`InteractionProcessCredentialRequest`](https://docs.maitento.com/reference/types/interaction-process-credential-request.md)`[] \| null` |  | Model provider keys of yours for this run. Calls use these first, then your tenant's model keys. |
| `allowMaitentoFallback` | `boolean \| null` |  | Whether an agent may fall back to Maitento's own key once your keys for its provider are used up or have failed (and only when your tenant allows it). Null or false: it may not, and the turn fails instead. |
| `credentialStack` | `string \| null` |  | The credential stack the run uses, by id or name. Its credentials serve every model call, in the stack's order, and Maitento's own keys are never used. Leave it out to use the interaction's own stack, then the namespace's default, then your tenant's. Can't be combined with `credentials`. |
| `durationAutoTerminationOverride` | `timespan \| null` |  | The longest this run may take, in place of the interaction's own limit. Null: the interaction's. |
| `durationWarningOverride` | `timespan \| null` |  | How long into this run the agents are told that time is running short, in place of the interaction's own setting. Null: the interaction's. |
| `swarmLimits` | [`InteractionSwarmLimitsRequestInput`](https://docs.maitento.com/reference/types/interaction-swarm-limits-request.md#in-a-request)`\| null` |  | Narrows how far the sub-interactions this run's participants start may spread: each limit given becomes the lesser of it and the definition's, and each left out is not narrowed. It can never widen them. Null: the definition's limits. |
| `webDownloadPartitionId` | `uuid \| null` |  | The temporary knowledge base (partition) the run's web fetches are kept in. Null: the namespace's default, then the tenant's. A run whose agents may fetch, with none of the three, is refused (`api:web:download-partition-required`). Runs it starts use it too. |
| `webAccessOverrides` | [`WebAccessOverrideInput`](https://docs.maitento.com/reference/types/web-access-override.md#in-a-request)`[] \| null` |  | Per-agent overrides of the agents' web tools for this run. |

**Response:** [`InteractionProcess`](https://docs.maitento.com/reference/types/interaction-process.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/interactions/processes/by-id/<id>/start" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"inputs":[]}'
```
```ts title="TypeScript"
const run = await mt.interactions.start({ id: "0e7d9b3c-2f1a-4c5e-9d8b-7a6f5e4d3c2b" }, { inputs: { message: "Hello!" } });
```
```python title="Python"
mt.interactions.start(id="8c3b2a1d-4e5f-4a6b-9c7d-0e1f2a3b4c5d", inputs={"name": "Ada"})
```

## `interactions.updateRoundRobin`

```http
PUT /interactions/round-robin/by-id/{id}
```

Updates a round-robin interaction.

**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=PUT%20%2Finteractions%2Fround-robin%2Fby-id%2F%7Bid%7D).

**Path parameters**

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

**Request body:** [`RoundRobinInteractionUpdateRequest`](https://docs.maitento.com/reference/types/round-robin-interaction-update-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `agents` | [`InteractionAgentBindingInput`](https://docs.maitento.com/reference/types/interaction-agent-binding.md#in-a-request)`[]` | yes | The participants, in the order they take turns. |
| `isNoActionAllowed` | `boolean` |  | Whether an agent may pass its turn without saying anything. |
| `isVotingAllowed` | `boolean` |  | Whether an agent may put something to a vote. |
| `isDirectQuestioningAllowed` | `boolean` |  | Whether an agent may ask another a question directly. |
| `isSolutionProposalAllowed` | `boolean` |  | Whether an agent may propose a final answer for the others to vote on. With no one able to, a conversation with a person carries on until it is stopped. |
| `humanSettings` | [`RoundRobinInteractionHumanSettingsInput`](https://docs.maitento.com/reference/types/round-robin-interaction-human-settings.md#in-a-request)`\| null` |  | Whether a person takes part in the conversation, and how. Null: no one does. |
| `maximumNoActionLoops` | `integer \| null` |  | How many rounds in which every agent passes end the run. Null: no limit. |
| `name` | `string` | yes | The interaction's name, unique within its namespace. |
| `prompt` | `string` | yes | What the agents are asked to do. A run's inputs are filled in wherever it says `%%name%%`. |
| `solutionSchema` | `string \| null` |  | The JSON Schema the answer must match, as JSON text: the run's output is then JSON of that shape. Null: the output is free text. |
| `systemPromptMode` | [`InteractionSystemPromptMode`](https://docs.maitento.com/reference/types/interaction-system-prompt-mode.md) | yes | How `systemPrompts` combine with the instructions Maitento gives every agent. |
| `systemPrompts` | `string[]` | yes | Extra system instructions for every agent in the interaction. |
| `durationWarningToAi` | `timespan \| null` |  | How long into a run the agents are told that time is running short. Null: they are not told. |
| `durationAutoTermination` | `timespan \| null` |  | The longest a run may take. The run stops with an error when it is reached; time spent waiting for a person does not count. Null: no limit. |
| `contextSettings` | [`InteractionContextSettingsInput`](https://docs.maitento.com/reference/types/interaction-context-settings.md#in-a-request)`\| null` |  | How the conversation is kept within the model's context window, and how many rounds of tool calls an agent may make in one turn. Null: the defaults. |
| `swarm` | [`InteractionSwarmSettingsInput`](https://docs.maitento.com/reference/types/interaction-swarm-settings.md#in-a-request)`\| null` |  | The sub-interactions its participants may start. Null: none. |
| `credentialStack` | `string \| null` |  | The credential stack its runs use, by id or name, when their start doesn't name one. Null: the namespace's default stack, then your tenant's. A stack that doesn't exist when a run starts refuses the run. |
| `externalOperationsOpenApi` | [`OpenApiExternalOperationBindingInput`](https://docs.maitento.com/reference/types/open-api-external-operation-binding.md#in-a-request)`[]` | yes | Tools from OpenAPI connectors that every agent in the interaction can call, as well as its own tools. |
| `externalOperationsMcp` | [`McpExternalOperationBindingInput`](https://docs.maitento.com/reference/types/mcp-external-operation-binding.md#in-a-request)`[]` | yes | Tools from MCP connectors that every agent in the interaction can call, as well as its own tools. |
| `inputsConnectorAuthenticationSecret` | [`ConnectorAuthenticationSecretInputInput`](https://docs.maitento.com/reference/types/connector-authentication-secret-input.md#in-a-request)`[]` | yes | Run inputs that choose the secret a tool sends with its calls. |
| `inputsConnectorBinding` | [`ConnectorBindingInputInput`](https://docs.maitento.com/reference/types/connector-binding-input.md#in-a-request)`[]` | yes | Run inputs whose values go straight into a tool's calls, so the model never sees or chooses them. |
| `inputsPrompt` | [`PromptInputInput`](https://docs.maitento.com/reference/types/prompt-input.md#in-a-request)`[]` | yes | The inputs a run is started with, which the prompt uses as `%%name%%`. |
| `loom` | [`LoomConfigurationInput`](https://docs.maitento.com/reference/types/loom-configuration.md#in-a-request)`\| null` |  | Long-term memory for the interaction's agents. Null: no memory. |

**Response:** [`RoundRobinInteraction`](https://docs.maitento.com/reference/types/round-robin-interaction.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/interactions/round-robin/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"agents":[],"name":"...","prompt":"...","systemPromptMode":"AppendToDefault","systemPrompts":[],"externalOperationsOpenApi":[],"externalOperationsMcp":[],"inputsConnectorAuthenticationSecret":[],"inputsConnectorBinding":[],"inputsPrompt":[]}'
```
```ts title="TypeScript"
await mt.interactions.updateRoundRobin("0e7d9b3c-2f1a-4c5e-9d8b-7a6f5e4d3c2b", { ...definition, isVotingAllowed: true });
```
```python title="Python"
mt.interactions.update_round_robin("8c3b2a1d-4e5f-4a6b-9c7d-0e1f2a3b4c5d", name="chat", prompt="Help the user plan a trip.", system_prompt_mode="AppendToDefault", agents=[{"name": "Planner", "agent": {"id": "2f1e8c4a-7b3d-4e9f-a1c2-5d6e7f809a1b", "version": 2}}])
```

## `interactions.list`

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

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

**Path parameters**

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

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

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

## `interactions.getByName`

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

**Path parameters**

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

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

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

## `interactions.start`

```http
PUT /namespaces/{namespaceName}/interactions/by-name/{name}/start
```

Starts a run of the interaction's latest enabled version and returns it (status `New`). Starts work, so it is never retried. To wait for the answer, use {@link run}.

**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=PUT%20%2Fnamespaces%2F%7BnamespaceName%7D%2Finteractions%2Fby-name%2F%7Bname%7D%2Fstart).

**Path parameters**

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

**Request body:** [`InteractionProcessStartRequest`](https://docs.maitento.com/reference/types/interaction-process-start-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `inputs` | [`NameValuePair`](https://docs.maitento.com/reference/types/name-value-pair.md)`[]` | yes | The run's inputs, by name. Every required input must be given. |
| `loomMappings` | [`LoomMappingRequest`](https://docs.maitento.com/reference/types/loom-mapping-request.md)`[] \| null` |  | The loom particular agents wake up with in this run, in place of the one the interaction would choose. |
| `loomGifts` | [`LoomStartGiftRequest`](https://docs.maitento.com/reference/types/loom-start-gift-request.md)`[] \| null` |  | Threads to hand to agents as they start, so they wake up knowing them, and knowing they were told. |
| `aiModelOverrides` | [`AiModelOverrideRequestInput`](https://docs.maitento.com/reference/types/ai-model-override-request.md#in-a-request)`[] \| null` |  | Agents to run on a different model in this run. |
| `responseJsonSchema` | `string \| null` |  | A JSON Schema the run's answer must match, in place of the interaction's own. Must be a valid JSON Schema. |
| `disabledTools` | `string[] \| null` |  | The names of tools this run's agents are not given. |
| `credentials` | [`InteractionProcessCredentialRequest`](https://docs.maitento.com/reference/types/interaction-process-credential-request.md)`[] \| null` |  | Model provider keys of yours for this run. Calls use these first, then your tenant's model keys. |
| `allowMaitentoFallback` | `boolean \| null` |  | Whether an agent may fall back to Maitento's own key once your keys for its provider are used up or have failed (and only when your tenant allows it). Null or false: it may not, and the turn fails instead. |
| `credentialStack` | `string \| null` |  | The credential stack the run uses, by id or name. Its credentials serve every model call, in the stack's order, and Maitento's own keys are never used. Leave it out to use the interaction's own stack, then the namespace's default, then your tenant's. Can't be combined with `credentials`. |
| `durationAutoTerminationOverride` | `timespan \| null` |  | The longest this run may take, in place of the interaction's own limit. Null: the interaction's. |
| `durationWarningOverride` | `timespan \| null` |  | How long into this run the agents are told that time is running short, in place of the interaction's own setting. Null: the interaction's. |
| `swarmLimits` | [`InteractionSwarmLimitsRequestInput`](https://docs.maitento.com/reference/types/interaction-swarm-limits-request.md#in-a-request)`\| null` |  | Narrows how far the sub-interactions this run's participants start may spread: each limit given becomes the lesser of it and the definition's, and each left out is not narrowed. It can never widen them. Null: the definition's limits. |
| `webDownloadPartitionId` | `uuid \| null` |  | The temporary knowledge base (partition) the run's web fetches are kept in. Null: the namespace's default, then the tenant's. A run whose agents may fetch, with none of the three, is refused (`api:web:download-partition-required`). Runs it starts use it too. |
| `webAccessOverrides` | [`WebAccessOverrideInput`](https://docs.maitento.com/reference/types/web-access-override.md#in-a-request)`[] \| null` |  | Per-agent overrides of the agents' web tools for this run. |

**Response:** [`InteractionProcess`](https://docs.maitento.com/reference/types/interaction-process.md) (200)

```bash title="curl"
curl -X PUT "https://api.maitento.com/namespaces/<namespaceName>/interactions/by-name/<name>/start" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"inputs":[]}'
```
```ts title="TypeScript"
const run = await mt.interactions.start("hello", { inputs: { message: "Hello!" } }); // or mt.interactions.run(...)
```
```python title="Python"
mt.interactions.start("hello", inputs={"name": "Ada"}, namespace="demo")
```

## `interactions.createManaged`

```http
POST /namespaces/{namespaceName}/interactions/managed
```

Creates a managed interaction (a manager agent hands work to a team).

**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%2Finteractions%2Fmanaged).

**Path parameters**

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

**Request body:** [`ManagedInteractionCreateRequest`](https://docs.maitento.com/reference/types/managed-interaction-create-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `managerAgent` | [`InteractionAgentBindingInput`](https://docs.maitento.com/reference/types/interaction-agent-binding.md#in-a-request) | yes | The manager: the agent that runs the conversation and dispatches work to the others. |
| `agents` | [`ManagedInteractionAgentBindingInput`](https://docs.maitento.com/reference/types/managed-interaction-agent-binding.md#in-a-request)`[]` | yes | The agents the manager can dispatch to, each with what it sees when it is dispatched to. |
| `humanSettings` | [`RoundRobinInteractionHumanSettingsInput`](https://docs.maitento.com/reference/types/round-robin-interaction-human-settings.md#in-a-request)`\| null` |  | Whether a person talks with the manager, and who speaks first. Null: no one does. |
| `maxDispatches` | `integer \| null` |  | The most dispatches one run may make, 1 to 200. Null: 30. |
| `name` | `string` | yes | The interaction's name, unique within its namespace. |
| `prompt` | `string` | yes | What the agents are asked to do. A run's inputs are filled in wherever it says `%%name%%`. |
| `solutionSchema` | `string \| null` |  | The JSON Schema the answer must match, as JSON text: the run's output is then JSON of that shape. Null: the output is free text. |
| `systemPromptMode` | [`InteractionSystemPromptMode`](https://docs.maitento.com/reference/types/interaction-system-prompt-mode.md) | yes | How `systemPrompts` combine with the instructions Maitento gives every agent. |
| `systemPrompts` | `string[]` | yes | Extra system instructions for every agent in the interaction. |
| `durationWarningToAi` | `timespan \| null` |  | How long into a run the agents are told that time is running short. Null: they are not told. |
| `durationAutoTermination` | `timespan \| null` |  | The longest a run may take. The run stops with an error when it is reached; time spent waiting for a person does not count. Null: no limit. |
| `contextSettings` | [`InteractionContextSettingsInput`](https://docs.maitento.com/reference/types/interaction-context-settings.md#in-a-request)`\| null` |  | How the conversation is kept within the model's context window, and how many rounds of tool calls an agent may make in one turn. Null: the defaults. |
| `swarm` | [`InteractionSwarmSettingsInput`](https://docs.maitento.com/reference/types/interaction-swarm-settings.md#in-a-request)`\| null` |  | The sub-interactions its participants may start. Null: none. |
| `credentialStack` | `string \| null` |  | The credential stack its runs use, by id or name, when their start doesn't name one. Null: the namespace's default stack, then your tenant's. A stack that doesn't exist when a run starts refuses the run. |
| `externalOperationsOpenApi` | [`OpenApiExternalOperationBindingInput`](https://docs.maitento.com/reference/types/open-api-external-operation-binding.md#in-a-request)`[]` | yes | Tools from OpenAPI connectors that every agent in the interaction can call, as well as its own tools. |
| `externalOperationsMcp` | [`McpExternalOperationBindingInput`](https://docs.maitento.com/reference/types/mcp-external-operation-binding.md#in-a-request)`[]` | yes | Tools from MCP connectors that every agent in the interaction can call, as well as its own tools. |
| `inputsConnectorAuthenticationSecret` | [`ConnectorAuthenticationSecretInputInput`](https://docs.maitento.com/reference/types/connector-authentication-secret-input.md#in-a-request)`[]` | yes | Run inputs that choose the secret a tool sends with its calls. |
| `inputsConnectorBinding` | [`ConnectorBindingInputInput`](https://docs.maitento.com/reference/types/connector-binding-input.md#in-a-request)`[]` | yes | Run inputs whose values go straight into a tool's calls, so the model never sees or chooses them. |
| `inputsPrompt` | [`PromptInputInput`](https://docs.maitento.com/reference/types/prompt-input.md#in-a-request)`[]` | yes | The inputs a run is started with, which the prompt uses as `%%name%%`. |
| `loom` | [`LoomConfigurationInput`](https://docs.maitento.com/reference/types/loom-configuration.md#in-a-request)`\| null` |  | Long-term memory for the interaction's agents. Null: no memory. |

**Response:** [`ManagedInteraction`](https://docs.maitento.com/reference/types/managed-interaction.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/namespaces/<namespaceName>/interactions/managed" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"managerAgent":{"name":"...","agent":{},"externalOperationsMcp":[],"externalOperationsOpenApi":[],"loomId":"...","webAccess":{}},"agents":[],"name":"...","prompt":"...","systemPromptMode":"AppendToDefault","systemPrompts":[],"externalOperationsOpenApi":[],"externalOperationsMcp":[],"inputsConnectorAuthenticationSecret":[],"inputsConnectorBinding":[],"inputsPrompt":[]}'
```
```ts title="TypeScript"
const interaction = await mt.interactions.createManaged(definition, { namespace: "support" });
```
```python title="Python"
mt.interactions.create_managed(name="desk", prompt="Route the question to the right expert.", system_prompt_mode="AppendToDefault", manager_agent={"name": "Router", "agent": {"id": "2f1e8c4a-7b3d-4e9f-a1c2-5d6e7f809a1b", "version": 1}}, agents=[{"mode": "OneTime", "name": "Cook", "agent": {"id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f", "version": 1}}], namespace="demo")
```

## `interactions.createOneShot`

```http
POST /namespaces/{namespaceName}/interactions/one-shot
```

Creates a one-shot interaction (one agent, one answer).

**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%2Finteractions%2Fone-shot).

**Path parameters**

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

**Request body:** [`OneShotInteractionCreateRequest`](https://docs.maitento.com/reference/types/one-shot-interaction-create-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `agent` | [`InteractionAgentBindingInput`](https://docs.maitento.com/reference/types/interaction-agent-binding.md#in-a-request) | yes | The agent that takes the task. |
| `name` | `string` | yes | The interaction's name, unique within its namespace. |
| `prompt` | `string` | yes | What the agents are asked to do. A run's inputs are filled in wherever it says `%%name%%`. |
| `solutionSchema` | `string \| null` |  | The JSON Schema the answer must match, as JSON text: the run's output is then JSON of that shape. Null: the output is free text. |
| `systemPromptMode` | [`InteractionSystemPromptMode`](https://docs.maitento.com/reference/types/interaction-system-prompt-mode.md) | yes | How `systemPrompts` combine with the instructions Maitento gives every agent. |
| `systemPrompts` | `string[]` | yes | Extra system instructions for every agent in the interaction. |
| `durationWarningToAi` | `timespan \| null` |  | How long into a run the agents are told that time is running short. Null: they are not told. |
| `durationAutoTermination` | `timespan \| null` |  | The longest a run may take. The run stops with an error when it is reached; time spent waiting for a person does not count. Null: no limit. |
| `contextSettings` | [`InteractionContextSettingsInput`](https://docs.maitento.com/reference/types/interaction-context-settings.md#in-a-request)`\| null` |  | How the conversation is kept within the model's context window, and how many rounds of tool calls an agent may make in one turn. Null: the defaults. |
| `swarm` | [`InteractionSwarmSettingsInput`](https://docs.maitento.com/reference/types/interaction-swarm-settings.md#in-a-request)`\| null` |  | The sub-interactions its participants may start. Null: none. |
| `credentialStack` | `string \| null` |  | The credential stack its runs use, by id or name, when their start doesn't name one. Null: the namespace's default stack, then your tenant's. A stack that doesn't exist when a run starts refuses the run. |
| `externalOperationsOpenApi` | [`OpenApiExternalOperationBindingInput`](https://docs.maitento.com/reference/types/open-api-external-operation-binding.md#in-a-request)`[]` | yes | Tools from OpenAPI connectors that every agent in the interaction can call, as well as its own tools. |
| `externalOperationsMcp` | [`McpExternalOperationBindingInput`](https://docs.maitento.com/reference/types/mcp-external-operation-binding.md#in-a-request)`[]` | yes | Tools from MCP connectors that every agent in the interaction can call, as well as its own tools. |
| `inputsConnectorAuthenticationSecret` | [`ConnectorAuthenticationSecretInputInput`](https://docs.maitento.com/reference/types/connector-authentication-secret-input.md#in-a-request)`[]` | yes | Run inputs that choose the secret a tool sends with its calls. |
| `inputsConnectorBinding` | [`ConnectorBindingInputInput`](https://docs.maitento.com/reference/types/connector-binding-input.md#in-a-request)`[]` | yes | Run inputs whose values go straight into a tool's calls, so the model never sees or chooses them. |
| `inputsPrompt` | [`PromptInputInput`](https://docs.maitento.com/reference/types/prompt-input.md#in-a-request)`[]` | yes | The inputs a run is started with, which the prompt uses as `%%name%%`. |
| `loom` | [`LoomConfigurationInput`](https://docs.maitento.com/reference/types/loom-configuration.md#in-a-request)`\| null` |  | Long-term memory for the interaction's agents. Null: no memory. |

**Response:** [`OneShotInteraction`](https://docs.maitento.com/reference/types/one-shot-interaction.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/namespaces/<namespaceName>/interactions/one-shot" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"agent":{"name":"...","agent":{},"externalOperationsMcp":[],"externalOperationsOpenApi":[],"loomId":"...","webAccess":{}},"name":"...","prompt":"...","systemPromptMode":"AppendToDefault","systemPrompts":[],"externalOperationsOpenApi":[],"externalOperationsMcp":[],"inputsConnectorAuthenticationSecret":[],"inputsConnectorBinding":[],"inputsPrompt":[]}'
```
```ts title="TypeScript"
const interaction = await mt.interactions.createOneShot(definition, { namespace: "support" });
```
```python title="Python"
mt.interactions.create_one_shot(name="hello", prompt="Say hello to %%name%%.", system_prompt_mode="AppendToDefault", agent={"name": "Greeter", "agent": {"id": "2f1e8c4a-7b3d-4e9f-a1c2-5d6e7f809a1b", "version": 1}}, namespace="demo")
```

## `interactions.createRoundRobin`

```http
POST /namespaces/{namespaceName}/interactions/round-robin
```

Creates a round-robin interaction (agents, and optionally a person, take turns).

**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%2Finteractions%2Fround-robin).

**Path parameters**

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

**Request body:** [`RoundRobinInteractionCreateRequest`](https://docs.maitento.com/reference/types/round-robin-interaction-create-request.md)

| Field | Type | Required | Description |
|---|---|---|---|
| `agents` | [`InteractionAgentBindingInput`](https://docs.maitento.com/reference/types/interaction-agent-binding.md#in-a-request)`[]` | yes | The participants, in the order they take turns. |
| `isNoActionAllowed` | `boolean` |  | Whether an agent may pass its turn without saying anything. |
| `isVotingAllowed` | `boolean` |  | Whether an agent may put something to a vote. |
| `isDirectQuestioningAllowed` | `boolean` |  | Whether an agent may ask another a question directly. |
| `isSolutionProposalAllowed` | `boolean` |  | Whether an agent may propose a final answer for the others to vote on. With no one able to, a conversation with a person carries on until it is stopped. |
| `humanSettings` | [`RoundRobinInteractionHumanSettingsInput`](https://docs.maitento.com/reference/types/round-robin-interaction-human-settings.md#in-a-request)`\| null` |  | Whether a person takes part in the conversation, and how. Null: no one does. |
| `maximumNoActionLoops` | `integer \| null` |  | How many rounds in which every agent passes end the run. Null: no limit. |
| `name` | `string` | yes | The interaction's name, unique within its namespace. |
| `prompt` | `string` | yes | What the agents are asked to do. A run's inputs are filled in wherever it says `%%name%%`. |
| `solutionSchema` | `string \| null` |  | The JSON Schema the answer must match, as JSON text: the run's output is then JSON of that shape. Null: the output is free text. |
| `systemPromptMode` | [`InteractionSystemPromptMode`](https://docs.maitento.com/reference/types/interaction-system-prompt-mode.md) | yes | How `systemPrompts` combine with the instructions Maitento gives every agent. |
| `systemPrompts` | `string[]` | yes | Extra system instructions for every agent in the interaction. |
| `durationWarningToAi` | `timespan \| null` |  | How long into a run the agents are told that time is running short. Null: they are not told. |
| `durationAutoTermination` | `timespan \| null` |  | The longest a run may take. The run stops with an error when it is reached; time spent waiting for a person does not count. Null: no limit. |
| `contextSettings` | [`InteractionContextSettingsInput`](https://docs.maitento.com/reference/types/interaction-context-settings.md#in-a-request)`\| null` |  | How the conversation is kept within the model's context window, and how many rounds of tool calls an agent may make in one turn. Null: the defaults. |
| `swarm` | [`InteractionSwarmSettingsInput`](https://docs.maitento.com/reference/types/interaction-swarm-settings.md#in-a-request)`\| null` |  | The sub-interactions its participants may start. Null: none. |
| `credentialStack` | `string \| null` |  | The credential stack its runs use, by id or name, when their start doesn't name one. Null: the namespace's default stack, then your tenant's. A stack that doesn't exist when a run starts refuses the run. |
| `externalOperationsOpenApi` | [`OpenApiExternalOperationBindingInput`](https://docs.maitento.com/reference/types/open-api-external-operation-binding.md#in-a-request)`[]` | yes | Tools from OpenAPI connectors that every agent in the interaction can call, as well as its own tools. |
| `externalOperationsMcp` | [`McpExternalOperationBindingInput`](https://docs.maitento.com/reference/types/mcp-external-operation-binding.md#in-a-request)`[]` | yes | Tools from MCP connectors that every agent in the interaction can call, as well as its own tools. |
| `inputsConnectorAuthenticationSecret` | [`ConnectorAuthenticationSecretInputInput`](https://docs.maitento.com/reference/types/connector-authentication-secret-input.md#in-a-request)`[]` | yes | Run inputs that choose the secret a tool sends with its calls. |
| `inputsConnectorBinding` | [`ConnectorBindingInputInput`](https://docs.maitento.com/reference/types/connector-binding-input.md#in-a-request)`[]` | yes | Run inputs whose values go straight into a tool's calls, so the model never sees or chooses them. |
| `inputsPrompt` | [`PromptInputInput`](https://docs.maitento.com/reference/types/prompt-input.md#in-a-request)`[]` | yes | The inputs a run is started with, which the prompt uses as `%%name%%`. |
| `loom` | [`LoomConfigurationInput`](https://docs.maitento.com/reference/types/loom-configuration.md#in-a-request)`\| null` |  | Long-term memory for the interaction's agents. Null: no memory. |

**Response:** [`RoundRobinInteraction`](https://docs.maitento.com/reference/types/round-robin-interaction.md) (200)

```bash title="curl"
curl -X POST "https://api.maitento.com/namespaces/<namespaceName>/interactions/round-robin" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"agents":[],"name":"...","prompt":"...","systemPromptMode":"AppendToDefault","systemPrompts":[],"externalOperationsOpenApi":[],"externalOperationsMcp":[],"inputsConnectorAuthenticationSecret":[],"inputsConnectorBinding":[],"inputsPrompt":[]}'
```
```ts title="TypeScript"
const interaction = await mt.interactions.createRoundRobin(definition, { namespace: "support" });
```
```python title="Python"
mt.interactions.create_round_robin(name="chat", prompt="Help the user plan a trip.", system_prompt_mode="AppendToDefault", agents=[{"name": "Planner", "agent": {"id": "2f1e8c4a-7b3d-4e9f-a1c2-5d6e7f809a1b", "version": 1}}], namespace="demo")
```