# Organization API: Org Staff Assistant

> Every Organization API operation tagged Org Staff Assistant.

Source: https://www.coritan.com/docs/api/reference/organizations/org-staff-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}/staff/assistant/conversations`](#op-get-api-v1-orgs-org-slug-staff-assistant-conversations) | Staff assistant conversations |
| GET | [`/api/v1/orgs/{org_slug}/staff/assistant/conversations/{conversation_uuid}`](#op-get-api-v1-orgs-org-slug-staff-assistant-conversations-conversation-uuid) | Staff assistant conversation |
| GET | [`/api/v1/orgs/{org_slug}/staff/assistant/insights`](#op-get-api-v1-orgs-org-slug-staff-assistant-insights) | Staff assistant insights |
| GET | [`/api/v1/orgs/{org_slug}/staff/assistant/notes`](#op-get-api-v1-orgs-org-slug-staff-assistant-notes) | The team's notes to the assistant, how many tokens they take and the most they may take |
| PUT | [`/api/v1/orgs/{org_slug}/staff/assistant/notes`](#op-put-api-v1-orgs-org-slug-staff-assistant-notes) | Replace the team's notes |
| POST | [`/api/v1/orgs/{org_slug}/staff/assistant/purge`](#op-post-api-v1-orgs-org-slug-staff-assistant-purge) | Staff assistant purge |

### Staff assistant conversations {#op-get-api-v1-orgs-org-slug-staff-assistant-conversations}

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

The brand's assistant chats, newest activity first: the customer (null for a visitor), the first message, the
counters (errors, tool errors, gaps, thumbs), whether it needs a look and the ticket a hand-off opened. `total`
counts what the filter matches. Owner only (403).

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `kind` | query | string or null | no | Keep only: `needs_review` chats with an error, a tool error, a refused call, a gap, a thumbs down, a hand-off or a lock; `gap` chats where the assistant reported something it could not do; `error` chats where a reply failed; `tool_error` chats where a tool call was answered with an error; `refused` chats where a tool call was refused before it was sent; `thumbs_down` chats with a reply the customer rated down; `thumbs_up` chats with a reply the customer rated up; `handoff` chats that opened a support ticket; `locked` chats paused for off-topic messages; `sale` chats where the customer confirmed a purchase; `offer` chats where the assistant showed a purchase card or an order link. Any other word is 422. |
| `who` | query | string or null | no | `signed_in` or `visitor`. Any other word is 422. |
| `customer_id` | query | integer or null | no | One customer's chats. |
| `from` | query | string or null | no | Active on or after this day, YYYY-MM-DD (UTC). |
| `to` | query | string or null | no | Started on or before this day, YYYY-MM-DD (UTC). |
| `audience` | query | string or null | no | `paid` (customers with a paid service), `free` (everyone else, visitors included) or `all`. |
| `offset` | query | integer | no | How many chats to skip, for the next page: the previous `offset` plus `limit`. Default: `0`. |
| `limit` | query | integer | no | Default: `50`. |

#### Responses

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

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

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

One chat in reading order: the customer's messages with the page they were on, the replies with their thumbs,
each tool call with its result, the confirm cards and what became of them, and the events. Another
organization's chat answers 404. Owner only (403).

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `conversation_uuid` | path | string | yes |  |
| `org_slug` | path | string | yes |  |
| `full` | query | boolean | no | Tool inputs and results in full; otherwise each is cut to 1,500 characters. Default: `False`. |

#### Responses

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

### Staff assistant insights {#op-get-api-v1-orgs-org-slug-staff-assistant-insights}

`GET /api/v1/orgs/{org_slug}/staff/assistant/insights`

What to look at over a period: chats, how many need a look, hand-offs, thumbs, tokens, the gaps the assistant
reported, the tools that fail, what was refused, the replies rated down and the failed replies with their refs.
Owner only (403).

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `from` | query | string or null | no | From this day, YYYY-MM-DD (UTC). |
| `to` | query | string or null | no | To this day, YYYY-MM-DD (UTC), inclusive. |
| `audience` | query | string or null | no | `paid` (customers with a paid service), `free` (everyone else, visitors included) or `all`. |

#### Responses

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

### The team's notes to the assistant, how many tokens they take and the most they may take {#op-get-api-v1-orgs-org-slug-staff-assistant-notes}

`GET /api/v1/orgs/{org_slug}/staff/assistant/notes`

The team's notes to the assistant, how many tokens they take and the most they may take. Owner only (403).

#### 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. |

### Replace the team's notes {#op-put-api-v1-orgs-org-slug-staff-assistant-notes}

`PUT /api/v1/orgs/{org_slug}/staff/assistant/notes`

Replace the team's notes. The assistant reads them in its next chats (this server at once, the others within
10 minutes); they rank above the rest of its knowledge and below its safety rules. Over 2,000 tokens is 422.
An empty text removes them. Written to the audit log. Owner only (403).

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `notes` | string | no | What the assistant should know or do, in plain sentences. |

#### Responses

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

### Staff assistant purge {#op-post-api-v1-orgs-org-slug-staff-assistant-purge}

`POST /api/v1/orgs/{org_slug}/staff/assistant/purge`

Delete the brand's assistant chats with their messages, waiting changes and events: one chat, one customer's,
every chat last active before a day, or `everything`. With `confirm` false it answers `{count}` and deletes
nothing; with `confirm` true it deletes and answers `{count, deleted: true}`. Deleting needs the owner to have
stepped up in the last ten minutes (403 `reauth_required`), and it is written to the audit log. Owner only.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `conversation` | string or null | no | One chat's uuid. |
| `customer_id` | integer or null | no | Every chat of this customer. |
| `before` | string or null | no | Every chat last active before this day, YYYY-MM-DD (UTC). |
| `everything` | boolean | no | Every chat of the brand; needed when none of the other fields is set. |
| `confirm` | boolean | no | False answers how many would go and deletes nothing; true deletes them. |

#### Responses

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