Organization API: Org Staff Assistant
Every Organization API operation tagged 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.
Operations
Section titled Operations| Method | Path | Summary |
|---|---|---|
| GET | /api/v1/orgs/{org_slug}/staff/assistant/conversations |
Staff assistant conversations |
| GET | /api/v1/orgs/{org_slug}/staff/assistant/conversations/{conversation_uuid} |
Staff assistant conversation |
| GET | /api/v1/orgs/{org_slug}/staff/assistant/insights |
Staff assistant insights |
| 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 |
Replace the team's notes |
| POST | /api/v1/orgs/{org_slug}/staff/assistant/purge |
Staff assistant purge |
Staff assistant conversations
Section titled Staff assistant conversationsGET /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
Section titled 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. 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. |
cursor |
query | string or null | no | next_cursor from the previous page. |
limit |
query | integer | no | Default: 50. |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Staff assistant conversation
Section titled Staff assistant conversationGET /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
Section titled 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
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Staff assistant insights
Section titled Staff assistant insightsGET /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
Section titled 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
Section titled 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
Section titled The team's notes to the assistant, how many tokens they take and the most they may takeGET /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
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
org_slug |
path | string | yes |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Replace the team's notes
Section titled Replace the team's notesPUT /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
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
org_slug |
path | string | yes |
Request body
Section titled Request bodyapplication/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
notes |
string | no | What the assistant should know or do, in plain sentences. |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Staff assistant purge
Section titled Staff assistant purgePOST /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
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
org_slug |
path | string | yes |
Request body
Section titled Request bodyapplication/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
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |