# Organization API: Org Assistant

> Every Organization API operation tagged Org Assistant.

Source: https://www.coritan.com/docs/api/reference/organizations/org-assistant/

Base URL: `https://api.coritan.com/api/v1`. Paths below are complete.

To try these requests in the browser, open the [interactive Organization API reference](https://api.coritan.com/docs/org).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/assistant/config`](#op-get-api-v1-orgs-org-slug-assistant-config) | Whether this store has the assistant, what it is called and what it may do for the caller |
| POST | [`/api/v1/orgs/{org_slug}/assistant/conversations`](#op-post-api-v1-orgs-org-slug-assistant-conversations) | Start a chat with the assistant |
| GET | [`/api/v1/orgs/{org_slug}/assistant/conversations/{conversation_uuid}`](#op-get-api-v1-orgs-org-slug-assistant-conversations-conversation-uuid) | Get assistant conversation |
| POST | [`/api/v1/orgs/{org_slug}/assistant/conversations/{conversation_uuid}/actions/{action_id}`](#op-post-api-v1-orgs-org-slug-assistant-conversations-conversation-uuid-actions-acti) | Confirm or cancel a change the assistant proposed |
| POST | [`/api/v1/orgs/{org_slug}/assistant/conversations/{conversation_uuid}/messages`](#op-post-api-v1-orgs-org-slug-assistant-conversations-conversation-uuid-messages) | Send the customer's message and stream the assistant's answer |

### Whether this store has the assistant, what it is called and what it may do for the caller {#op-get-api-v1-orgs-org-slug-assistant-config}

`GET /api/v1/orgs/{org_slug}/assistant/config`

Whether this store has the assistant, what it is called and what it may do for the caller.

Answers 404 when the store has no assistant. Send the customer's bearer
token to learn whether the assistant can use their account; without one
the assistant answers product questions only.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type | Description |
| --- | --- | --- |
| `enabled` | boolean | Whether this store shows the assistant. |
| `name` | string | What the assistant calls itself. |
| `signed_in` | boolean | Whether the request carried a valid customer token, so the assistant can use the account. |
| `can_change` | boolean | Whether the assistant may propose changes to the account. False for a visitor and in a support session. |

### Start a chat with the assistant {#op-post-api-v1-orgs-org-slug-assistant-conversations}

`POST /api/v1/orgs/{org_slug}/assistant/conversations`

Start a chat with the assistant.

A signed-in customer's chat belongs to their account. A visitor's chat
belongs to the `visitor_key` this answers once: send it as the
`X-Assistant-Key` header on every later request about the chat, or the
chat answers 404.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `201` response:

| Field | Type | Description |
| --- | --- | --- |
| `uuid` | string |  |
| `visitor_key` | string or null | For a visitor who is not signed in: the key that opens this chat. Send it as the `X-Assistant-Key` header on every later request about the chat. It is shown once. Null for a signed-in customer, whose chat belongs to their account. |

### Get assistant conversation {#op-get-api-v1-orgs-org-slug-assistant-conversations-conversation-uuid}

`GET /api/v1/orgs/{org_slug}/assistant/conversations/{conversation_uuid}`

One chat: its messages as the customer saw them (the newest 100), the changes still waiting for a confirm, and whether it is paused. Another customer's chat, or a visitor's chat without its `X-Assistant-Key`, answers 404.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `conversation_uuid` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `uuid` | string |
| `messages` | array of ShownMessage |
| `messages[].role` | string, one of `user`, `assistant` |
| `messages[].text` | string |
| `pending` | array of ShownAction |
| `pending[].id` | string |
| `pending[].tool` | string |
| `pending[].summary` | string |
| `locked` | boolean |

### Confirm or cancel a change the assistant proposed {#op-post-api-v1-orgs-org-slug-assistant-conversations-conversation-uuid-actions-acti}

`POST /api/v1/orgs/{org_slug}/assistant/conversations/{conversation_uuid}/actions/{action_id}`

Confirm or cancel a change the assistant proposed.

`confirm` runs it as the signed-in customer, with the same checks as the
panel (a shared server without the permission answers that it is not
allowed), and the assistant then says how it went. `cancel` drops it. The
stream starts with `decided` (`id`, and `state`: `done`, `failed` or
`cancelled`); a ticket the change opened adds `ticket` (`id`). A
change is waiting for 30 minutes; after that, or once decided, the route
answers with an `error` event. Only a signed-in customer outside a support
session can confirm (403).

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `conversation_uuid` | path | string | yes |
| `action_id` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `decision` | string, one of `confirm`, `cancel` | yes | `confirm` runs the change, `cancel` drops it. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Server-sent events: `decided`, then the assistant's answer as for a message, then `done`. |
| `422` | The request is not valid. `detail` lists each problem. |

### Send the customer's message and stream the assistant's answer {#op-post-api-v1-orgs-org-slug-assistant-conversations-conversation-uuid-messages}

`POST /api/v1/orgs/{org_slug}/assistant/conversations/{conversation_uuid}/messages`

Send the customer's message and stream the assistant's answer.

Events: `text` (`text`, a piece of the reply), `tool` (`name`, the
assistant is looking something up), `confirm` (`id`, `tool`, `summary`,
`detail`: a change waiting for the customer, see the decision route),
`link` (`url`, a path to an order page on the storefront), `locked`
(the chat is paused after off-topic messages), `error`
(`message`, a sentence for the customer) and last `done`. A paused chat
answers 423. Messages are limited per minute and per day for each customer
and each visitor's address (429).

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `conversation_uuid` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `text` | string | yes | What the customer wrote. |
| `page` | string or null | no | The storefront path the customer is on, such as /servers/abc. Ignored when it is not a path. |
| `server` | string or null | no | The id of the server the page shows, if any. Ignored when it is not a server id. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Server-sent events: `text`, `tool`, `confirm`, `link`, `locked`, `error`, then `done`. |
| `422` | The request is not valid. `detail` lists each problem. |