# Interaction runs

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

## `interactionRuns.list`

```http
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](https://docs.maitento.com/playground/?call=GET%20%2Finteractions%2Fprocesses).

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

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

## `interactionRuns.get`

```http
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](https://docs.maitento.com/playground/?call=GET%20%2Finteractions%2Fprocesses%2Fby-id%2F%7Bid%7D).

**Path parameters**

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

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

```bash title="curl"
curl -X GET "https://api.maitento.com/interactions/processes/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const run = await mt.interactionRuns.get("e4c2a1b3-9d8f-4e7a-b6c5-d4e3f2a1b0c9");
```
```python title="Python"
mt.interaction_runs.get("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f")
```

## `interactionRuns.addMessage`

```http
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](https://docs.maitento.com/playground/?call=POST%20%2Finteractions%2Fprocesses%2Fby-id%2F%7Bid%7D%2Fadd-message).

**Path parameters**

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

**Request body:** [`InteractionAddMessageRequest`](https://docs.maitento.com/reference/types/interaction-add-message-request.md)

| 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`](https://docs.maitento.com/reference/types/add-message-result.md) (200)

```bash title="curl"
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":"..."}'
```
```ts title="TypeScript"
const { queued } = await mt.interactionRuns.addMessage("e4c2a1b3-9d8f-4e7a-b6c5-d4e3f2a1b0c9", { message: "Make it shorter, please." });
```
```python title="Python"
mt.interaction_runs.add_message("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", "Make it shorter, please.")
```

## `interactionRuns.approve`

```http
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](https://docs.maitento.com/playground/?call=POST%20%2Finteractions%2Fprocesses%2Fby-id%2F%7Bid%7D%2Fapprove).

**Path parameters**

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

**Request body:** [`InteractionApproveToolCallRequest`](https://docs.maitento.com/reference/types/interaction-approve-tool-call-request.md)

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

**Response:** no body (204)

```bash title="curl"
curl -X POST "https://api.maitento.com/interactions/processes/by-id/<id>/approve" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"toolCallApprovalId":"..."}'
```
```ts title="TypeScript"
await mt.interactionRuns.approve("e4c2a1b3-9d8f-4e7a-b6c5-d4e3f2a1b0c9", { approvalId: run.pendingApproval!.id });
```
```python title="Python"
mt.interaction_runs.approve("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f")
```

## `interactionRuns.reject`

```http
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](https://docs.maitento.com/playground/?call=POST%20%2Finteractions%2Fprocesses%2Fby-id%2F%7Bid%7D%2Freject).

**Path parameters**

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

**Request body:** [`InteractionRejectToolCallRequest`](https://docs.maitento.com/reference/types/interaction-reject-tool-call-request.md)

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

```bash title="curl"
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":"..."}'
```
```ts title="TypeScript"
await mt.interactionRuns.reject("e4c2a1b3-9d8f-4e7a-b6c5-d4e3f2a1b0c9", { approvalId: run.pendingApproval!.id, reason: "Refunds over $500 need a manager." });
```
```python title="Python"
mt.interaction_runs.reject("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "Refunds over $100 need a manager.")
```

## `interactionRuns.addSystemMessage`

```http
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](https://docs.maitento.com/playground/?call=POST%20%2Finteractions%2Fprocesses%2Fby-id%2F%7Bid%7D%2Fsystem-message).

**Path parameters**

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

**Request body:** [`InteractionAddSystemMessageRequest`](https://docs.maitento.com/reference/types/interaction-add-system-message-request.md)

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

**Response:** no body (204)

```bash title="curl"
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":"..."}'
```
```ts title="TypeScript"
await mt.interactionRuns.addSystemMessage("e4c2a1b3-9d8f-4e7a-b6c5-d4e3f2a1b0c9", { content: "Wrap up within two turns." });
```
```python title="Python"
mt.interaction_runs.add_system_message("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", "Answer in French from now on.")
```

## `interactionRuns.toolResult`

```http
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](https://docs.maitento.com/playground/?call=GET%20%2Finteractions%2Fprocesses%2Fby-id%2F%7Bid%7D%2Ftool-results%2F%7Bsequence%7D).

**Path parameters**

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

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

```bash title="curl"
curl -X GET "https://api.maitento.com/interactions/processes/by-id/<id>/tool-results/<sequence>" \
  -H "Authorization: $MAITENTO_AUTH"
```
```ts title="TypeScript"
const result = await mt.interactionRuns.toolResult("e4c2a1b3-9d8f-4e7a-b6c5-d4e3f2a1b0c9", 7);
```
```python title="Python"
mt.interaction_runs.tool_result("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", 7)
```

## `interactionRuns.voteNo`

```http
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](https://docs.maitento.com/playground/?call=POST%20%2Finteractions%2Fprocesses%2Fby-id%2F%7Bid%7D%2Fvote%2Fno).

**Path parameters**

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

**Request body:** [`InteractionVoteNoRequest`](https://docs.maitento.com/reference/types/interaction-vote-no-request.md)

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

```bash title="curl"
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":"..."}'
```
```ts title="TypeScript"
await mt.interactionRuns.voteNo("e4c2a1b3-9d8f-4e7a-b6c5-d4e3f2a1b0c9", { reason: "The total is missing VAT." });
```
```python title="Python"
mt.interaction_runs.vote_no("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", "The plan skips the budget.")
```

## `interactionRuns.voteYes`

```http
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](https://docs.maitento.com/playground/?call=POST%20%2Finteractions%2Fprocesses%2Fby-id%2F%7Bid%7D%2Fvote%2Fyes).

**Path parameters**

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

**Request body:** [`InteractionVoteYesRequest`](https://docs.maitento.com/reference/types/interaction-vote-yes-request.md)

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

```bash title="curl"
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":"..."}'
```
```ts title="TypeScript"
await mt.interactionRuns.voteYes("e4c2a1b3-9d8f-4e7a-b6c5-d4e3f2a1b0c9");
```
```python title="Python"
mt.interaction_runs.vote_yes("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f")
```

## `interactionRuns.listActive`

```http
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](https://docs.maitento.com/playground/?call=GET%20%2Fnamespaces%2F%7BnamespaceName%7D%2Finteractions%2Fprocesses).

**Path parameters**

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

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

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