Interactions

13 calls. Every request needs the Authorization header: see the overview.

`interactions.list`

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.

Response: Interaction[] (200)

curl -X GET "https://api.maitento.com/interactions" \
  -H "Authorization: $MAITENTO_AUTH"

const interactions = await mt.interactions.list();

mt.interactions.list()

`interactions.delete`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Response: no body (204)

curl -X DELETE "https://api.maitento.com/interactions/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"

await mt.interactions.delete("0e7d9b3c-2f1a-4c5e-9d8b-7a6f5e4d3c2b");

mt.interactions.delete("8c3b2a1d-4e5f-4a6b-9c7d-0e1f2a3b4c5d")

`interactions.get`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Response: Interaction (200)

curl -X GET "https://api.maitento.com/interactions/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"

const interaction = await mt.interactions.get("0e7d9b3c-2f1a-4c5e-9d8b-7a6f5e4d3c2b");

mt.interactions.get("8c3b2a1d-4e5f-4a6b-9c7d-0e1f2a3b4c5d")

`interactions.updateManaged`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Request body: ManagedInteractionUpdateRequest

Field	Type	Required	Description
`managerAgent`	`InteractionAgentBindingInput`	yes	The manager: the agent that runs the conversation and dispatches work to the others.
`agents`	`ManagedInteractionAgentBindingInput[]`	yes	The agents the manager can dispatch to, each with what it sees when it is dispatched to.
`humanSettings`	`RoundRobinInteractionHumanSettingsInput\| 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`	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\| 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\| 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[]`	yes	Tools from OpenAPI connectors that every agent in the interaction can call, as well as its own tools.
`externalOperationsMcp`	`McpExternalOperationBindingInput[]`	yes	Tools from MCP connectors that every agent in the interaction can call, as well as its own tools.
`inputsConnectorAuthenticationSecret`	`ConnectorAuthenticationSecretInputInput[]`	yes	Run inputs that choose the secret a tool sends with its calls.
`inputsConnectorBinding`	`ConnectorBindingInputInput[]`	yes	Run inputs whose values go straight into a tool’s calls, so the model never sees or chooses them.
`inputsPrompt`	`PromptInputInput[]`	yes	The inputs a run is started with, which the prompt uses as `%%name%%`.
`loom`	`LoomConfigurationInput\| null`		Long-term memory for the interaction’s agents. Null: no memory.

Response: ManagedInteraction (200)

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":[]}'

await mt.interactions.updateManaged("0e7d9b3c-2f1a-4c5e-9d8b-7a6f5e4d3c2b", { ...definition, maxDispatches: 12 });

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`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Request body: OneShotInteractionUpdateRequest

Field	Type	Required	Description
`agent`	`InteractionAgentBindingInput`	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`	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\| 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\| 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[]`	yes	Tools from OpenAPI connectors that every agent in the interaction can call, as well as its own tools.
`externalOperationsMcp`	`McpExternalOperationBindingInput[]`	yes	Tools from MCP connectors that every agent in the interaction can call, as well as its own tools.
`inputsConnectorAuthenticationSecret`	`ConnectorAuthenticationSecretInputInput[]`	yes	Run inputs that choose the secret a tool sends with its calls.
`inputsConnectorBinding`	`ConnectorBindingInputInput[]`	yes	Run inputs whose values go straight into a tool’s calls, so the model never sees or chooses them.
`inputsPrompt`	`PromptInputInput[]`	yes	The inputs a run is started with, which the prompt uses as `%%name%%`.
`loom`	`LoomConfigurationInput\| null`		Long-term memory for the interaction’s agents. Null: no memory.

Response: OneShotInteraction (200)

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":[]}'

await mt.interactions.updateOneShot("0e7d9b3c-2f1a-4c5e-9d8b-7a6f5e4d3c2b", { ...definition, prompt: "Say hello in French." });

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`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Request body: InteractionProcessStartRequest

Field	Type	Required	Description
`inputs`	`NameValuePair[]`	yes	The run’s inputs, by name. Every required input must be given.
`loomMappings`	`LoomMappingRequest[] \| null`		The loom particular agents wake up with in this run, in place of the one the interaction would choose.
`loomGifts`	`LoomStartGiftRequest[] \| null`		Threads to hand to agents as they start, so they wake up knowing them, and knowing they were told.
`aiModelOverrides`	`AiModelOverrideRequestInput[] \| 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[] \| 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\| 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[] \| null`		Per-agent overrides of the agents’ web tools for this run.

Response: InteractionProcess (200)

curl -X PUT "https://api.maitento.com/interactions/processes/by-id/<id>/start" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"inputs":[]}'

const run = await mt.interactions.start({ id: "0e7d9b3c-2f1a-4c5e-9d8b-7a6f5e4d3c2b" }, { inputs: { message: "Hello!" } });

mt.interactions.start(id="8c3b2a1d-4e5f-4a6b-9c7d-0e1f2a3b4c5d", inputs={"name": "Ada"})

`interactions.updateRoundRobin`

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.

Path parameters

Name	Type	Required	Description
`id`	`uuid`	yes

Request body: RoundRobinInteractionUpdateRequest

Field	Type	Required	Description
`agents`	`InteractionAgentBindingInput[]`	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\| 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`	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\| 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\| 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[]`	yes	Tools from OpenAPI connectors that every agent in the interaction can call, as well as its own tools.
`externalOperationsMcp`	`McpExternalOperationBindingInput[]`	yes	Tools from MCP connectors that every agent in the interaction can call, as well as its own tools.
`inputsConnectorAuthenticationSecret`	`ConnectorAuthenticationSecretInputInput[]`	yes	Run inputs that choose the secret a tool sends with its calls.
`inputsConnectorBinding`	`ConnectorBindingInputInput[]`	yes	Run inputs whose values go straight into a tool’s calls, so the model never sees or chooses them.
`inputsPrompt`	`PromptInputInput[]`	yes	The inputs a run is started with, which the prompt uses as `%%name%%`.
`loom`	`LoomConfigurationInput\| null`		Long-term memory for the interaction’s agents. Null: no memory.

Response: RoundRobinInteraction (200)

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":[]}'

await mt.interactions.updateRoundRobin("0e7d9b3c-2f1a-4c5e-9d8b-7a6f5e4d3c2b", { ...definition, isVotingAllowed: true });

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`

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.

Path parameters

Name	Type	Required	Description
`namespaceName`	`string`	yes

Response: Interaction[] (200)

curl -X GET "https://api.maitento.com/namespaces/<namespaceName>/interactions" \
  -H "Authorization: $MAITENTO_AUTH"

const interactions = await mt.interactions.list({ namespace: "support" });

mt.interactions.list(namespace="demo")

`interactions.getByName`

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.

Path parameters

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

Response: Interaction (200)

curl -X GET "https://api.maitento.com/namespaces/<namespaceName>/interactions/by-name/<name>" \
  -H "Authorization: $MAITENTO_AUTH"

const interaction = await mt.interactions.getByName("hello", { namespace: "support" });

mt.interactions.get_by_name("hello", namespace="demo")

`interactions.start`

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.

Path parameters

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

Request body: InteractionProcessStartRequest

Field	Type	Required	Description
`inputs`	`NameValuePair[]`	yes	The run’s inputs, by name. Every required input must be given.
`loomMappings`	`LoomMappingRequest[] \| null`		The loom particular agents wake up with in this run, in place of the one the interaction would choose.
`loomGifts`	`LoomStartGiftRequest[] \| null`		Threads to hand to agents as they start, so they wake up knowing them, and knowing they were told.
`aiModelOverrides`	`AiModelOverrideRequestInput[] \| 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[] \| 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\| 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[] \| null`		Per-agent overrides of the agents’ web tools for this run.

Response: InteractionProcess (200)

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":[]}'

const run = await mt.interactions.start("hello", { inputs: { message: "Hello!" } }); // or mt.interactions.run(...)

mt.interactions.start("hello", inputs={"name": "Ada"}, namespace="demo")

`interactions.createManaged`

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.

Path parameters

Name	Type	Required	Description
`namespaceName`	`string`	yes

Request body: ManagedInteractionCreateRequest

Field	Type	Required	Description
`managerAgent`	`InteractionAgentBindingInput`	yes	The manager: the agent that runs the conversation and dispatches work to the others.
`agents`	`ManagedInteractionAgentBindingInput[]`	yes	The agents the manager can dispatch to, each with what it sees when it is dispatched to.
`humanSettings`	`RoundRobinInteractionHumanSettingsInput\| 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`	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\| 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\| 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[]`	yes	Tools from OpenAPI connectors that every agent in the interaction can call, as well as its own tools.
`externalOperationsMcp`	`McpExternalOperationBindingInput[]`	yes	Tools from MCP connectors that every agent in the interaction can call, as well as its own tools.
`inputsConnectorAuthenticationSecret`	`ConnectorAuthenticationSecretInputInput[]`	yes	Run inputs that choose the secret a tool sends with its calls.
`inputsConnectorBinding`	`ConnectorBindingInputInput[]`	yes	Run inputs whose values go straight into a tool’s calls, so the model never sees or chooses them.
`inputsPrompt`	`PromptInputInput[]`	yes	The inputs a run is started with, which the prompt uses as `%%name%%`.
`loom`	`LoomConfigurationInput\| null`		Long-term memory for the interaction’s agents. Null: no memory.

Response: ManagedInteraction (200)

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":[]}'

const interaction = await mt.interactions.createManaged(definition, { namespace: "support" });

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`

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.

Path parameters

Name	Type	Required	Description
`namespaceName`	`string`	yes

Request body: OneShotInteractionCreateRequest

Field	Type	Required	Description
`agent`	`InteractionAgentBindingInput`	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`	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\| 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\| 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[]`	yes	Tools from OpenAPI connectors that every agent in the interaction can call, as well as its own tools.
`externalOperationsMcp`	`McpExternalOperationBindingInput[]`	yes	Tools from MCP connectors that every agent in the interaction can call, as well as its own tools.
`inputsConnectorAuthenticationSecret`	`ConnectorAuthenticationSecretInputInput[]`	yes	Run inputs that choose the secret a tool sends with its calls.
`inputsConnectorBinding`	`ConnectorBindingInputInput[]`	yes	Run inputs whose values go straight into a tool’s calls, so the model never sees or chooses them.
`inputsPrompt`	`PromptInputInput[]`	yes	The inputs a run is started with, which the prompt uses as `%%name%%`.
`loom`	`LoomConfigurationInput\| null`		Long-term memory for the interaction’s agents. Null: no memory.

Response: OneShotInteraction (200)

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":[]}'

const interaction = await mt.interactions.createOneShot(definition, { namespace: "support" });

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`

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.

Path parameters

Name	Type	Required	Description
`namespaceName`	`string`	yes

Request body: RoundRobinInteractionCreateRequest

Field	Type	Required	Description
`agents`	`InteractionAgentBindingInput[]`	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\| 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`	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\| 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\| 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[]`	yes	Tools from OpenAPI connectors that every agent in the interaction can call, as well as its own tools.
`externalOperationsMcp`	`McpExternalOperationBindingInput[]`	yes	Tools from MCP connectors that every agent in the interaction can call, as well as its own tools.
`inputsConnectorAuthenticationSecret`	`ConnectorAuthenticationSecretInputInput[]`	yes	Run inputs that choose the secret a tool sends with its calls.
`inputsConnectorBinding`	`ConnectorBindingInputInput[]`	yes	Run inputs whose values go straight into a tool’s calls, so the model never sees or chooses them.
`inputsPrompt`	`PromptInputInput[]`	yes	The inputs a run is started with, which the prompt uses as `%%name%%`.
`loom`	`LoomConfigurationInput\| null`		Long-term memory for the interaction’s agents. Null: no memory.

Response: RoundRobinInteraction (200)

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":[]}'

const interaction = await mt.interactions.createRoundRobin(definition, { namespace: "support" });

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