Interaction runs

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

`interactionRuns.list`

GET /interactions/processes

EVERY interaction run of the tenant, each with its whole conversation: unbounded and potentially very large. Prefer runs.list({ types: ["Interaction"] }) (paged, summaries).

Who can call it: Admins and members, with an API key or a portal session. Try it in the API playground.

Response: InteractionProcess[] (200)

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

const everyRun = await mt.interactionRuns.list(); // unbounded: prefer mt.runs.list()

mt.interaction_runs.list()

`interactionRuns.get`

GET /interactions/processes/by-id/{id}

The run 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: InteractionProcess (200)

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

const run = await mt.interactionRuns.get("e4c2a1b3-9d8f-4e7a-b6c5-d4e3f2a1b0c9");

mt.interaction_runs.get("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f")

`interactionRuns.addMessage`

POST /interactions/processes/by-id/{id}/add-message

Adds a person’s message: answers a run waiting in HumanInteractionRequired, or is queued (queued: true) when the run is mid-turn.

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: InteractionAddMessageRequest

Field	Type	Required	Description
`messageAuthorName`	`string \| null`		The name to record as the author. Used only when you call with an API key, so an integration can post for the people it serves; with a signed-in session the message is always recorded as you. Left out, an API-key call is recorded as the key’s user.
`messageAuthorId`	`uuid`		The author’s id, used with `messageAuthorName` under the same rule.
`message`	`string`	yes	The message text.

Response: AddMessageResult (200)

curl -X POST "https://api.maitento.com/interactions/processes/by-id/<id>/add-message" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"message":"..."}'

const { queued } = await mt.interactionRuns.addMessage("e4c2a1b3-9d8f-4e7a-b6c5-d4e3f2a1b0c9", { message: "Make it shorter, please." });

mt.interaction_runs.add_message("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", "Make it shorter, please.")

`interactionRuns.approve`

POST /interactions/processes/by-id/{id}/approve

Approves the tool call a run is waiting on (run.pendingApproval.id): the call is made.

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: InteractionApproveToolCallRequest

Field	Type	Required	Description
`toolCallApprovalId`	`uuid`	yes	The `id` of the run’s `pendingApproval`.

Response: no body (204)

curl -X POST "https://api.maitento.com/interactions/processes/by-id/<id>/approve" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"toolCallApprovalId":"..."}'

await mt.interactionRuns.approve("e4c2a1b3-9d8f-4e7a-b6c5-d4e3f2a1b0c9", { approvalId: run.pendingApproval!.id });

mt.interaction_runs.approve("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f")

`interactionRuns.reject`

POST /interactions/processes/by-id/{id}/reject

Rejects the tool call a run is waiting on; the model is told reason.

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: InteractionRejectToolCallRequest

Field	Type	Required	Description
`toolCallApprovalId`	`uuid`	yes	The `id` of the run’s `pendingApproval`.
`reason`	`string`	yes	Why the call was rejected. The agent reads it in place of the call’s result.

Response: no body (204)

curl -X POST "https://api.maitento.com/interactions/processes/by-id/<id>/reject" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"toolCallApprovalId":"...","reason":"..."}'

await mt.interactionRuns.reject("e4c2a1b3-9d8f-4e7a-b6c5-d4e3f2a1b0c9", { approvalId: run.pendingApproval!.id, reason: "Refunds over $500 need a manager." });

mt.interaction_runs.reject("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "Refunds over $100 need a manager.")

`interactionRuns.addSystemMessage`

POST /interactions/processes/by-id/{id}/system-message

Injects a system message into the running conversation.

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: InteractionAddSystemMessageRequest

Field	Type	Required	Description
`content`	`string`	yes	The text of the system message.

Response: no body (204)

curl -X POST "https://api.maitento.com/interactions/processes/by-id/<id>/system-message" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"content":"..."}'

await mt.interactionRuns.addSystemMessage("e4c2a1b3-9d8f-4e7a-b6c5-d4e3f2a1b0c9", { content: "Wrap up within two turns." });

mt.interaction_runs.add_system_message("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", "Answer in French from now on.")

`interactionRuns.toolResult`

GET /interactions/processes/by-id/{id}/tool-results/{sequence}

The full result of one tool call (when the context item’s result was moved off the 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
`sequence`	`integer`	yes

Response: InteractionProcessToolResult (200)

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

const result = await mt.interactionRuns.toolResult("e4c2a1b3-9d8f-4e7a-b6c5-d4e3f2a1b0c9", 7);

mt.interaction_runs.tool_result("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", 7)

`interactionRuns.voteNo`

POST /interactions/processes/by-id/{id}/vote/no

Votes no on the solution proposal, with the reason the agents see.

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: InteractionVoteNoRequest

Field	Type	Required	Description
`messageAuthorName`	`string \| null`		The name to record as the voter. Used only when you call with an API key, so an integration can vote for the people it serves; with a signed-in session the vote is always recorded as you. Left out, an API-key call is recorded as the key’s user.
`messageAuthorId`	`uuid`		The voter’s id, used with `messageAuthorName` under the same rule.
`reason`	`string`	yes	Why the person disagrees. The agents read it.

Response: no body (204)

curl -X POST "https://api.maitento.com/interactions/processes/by-id/<id>/vote/no" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"reason":"..."}'

await mt.interactionRuns.voteNo("e4c2a1b3-9d8f-4e7a-b6c5-d4e3f2a1b0c9", { reason: "The total is missing VAT." });

mt.interaction_runs.vote_no("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", "The plan skips the budget.")

`interactionRuns.voteYes`

POST /interactions/processes/by-id/{id}/vote/yes

Votes yes on the solution proposal.

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: InteractionVoteYesRequest

Field	Type	Required	Description
`messageAuthorName`	`string \| null`		The name to record as the voter. Used only when you call with an API key, so an integration can vote for the people it serves; with a signed-in session the vote is always recorded as you. Left out, an API-key call is recorded as the key’s user.
`messageAuthorId`	`uuid`		The voter’s id, used with `messageAuthorName` under the same rule.

Response: no body (204)

curl -X POST "https://api.maitento.com/interactions/processes/by-id/<id>/vote/yes" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"messageAuthorName":"...","messageAuthorId":"..."}'

await mt.interactionRuns.voteYes("e4c2a1b3-9d8f-4e7a-b6c5-d4e3f2a1b0c9");

mt.interaction_runs.vote_yes("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f")

`interactionRuns.listActive`

GET /namespaces/{namespaceName}/interactions/processes

The runs of the namespace that have not finished.

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: InteractionProcessWithDetails[] (200)

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

const active = await mt.interactionRuns.listActive({ namespace: "support" });

mt.interaction_runs.list_active(namespace="demo")