# Assistants

> List assistants, publish, pause and resume them, send test messages in the sandbox, and manage the web pages they learn from.

Source: https://www.ordstage.com/docs/assistants/

Assistants are built in **Studio**. The API lets your systems operate them: see their state, publish the current
setup, pause and resume them, try them in the sandbox, and keep their knowledge pages fresh.

| Scope | Lets a key |
|---|---|
| `assistants:read` | List assistants, get one with its lifecycle, list its knowledge sources. |
| `assistants:write` | Publish, pause, resume, send test messages, add, refresh and remove knowledge pages. |

Changes are made as the key's creator, who must still be an owner, admin or manager (or hold the assistants
permission); otherwise the answer is `403 key_creator_not_allowed`.

## Publishing, pausing and resuming

`POST /v1/assistants/{assistant_id}/publish` does what **Publish** does in Studio and needs an `Idempotency-Key`.
It is refused with Studio's reason while setup is incomplete, for example `assistant_release_not_ready`,
`brand_identity_unapproved` or `flow_validation_failed`.

```bash [curl]
curl -X POST https://api.ordstage.com/v1/assistants/6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f/publish \
  -H "Authorization: Bearer $ORDSTAGE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

`pause` stops the assistant answering (new messages go to the team); `resume` makes it answer again, and is
refused (`assistant_not_resumable`) until the current setup is published and nothing blocks it.

Events: `assistant.published`, `assistant.paused`, `assistant.resumed`.

## Test messages

`POST /v1/assistants/{assistant_id}/test_messages` works with **test keys only** (live keys answer
`409 test_key_required`). The message runs against the sandbox's sample assistant, like the test chat in Studio:
nothing reaches a customer, and it uses the sandbox's AI allowance. Pass the returned `session_id` with the next
message to continue the conversation.

```json
{ "message": "Do you open on Fridays?" }
```

## Knowledge pages

`GET /v1/assistants/{assistant_id}/knowledge_sources` lists what the assistant learns from (pages, files,
sheets). With the API you can add a public web page, refresh a source, or remove one:

- `POST .../knowledge_sources` with `{"url": "https://…", "name": "Prices"}` adds a page and reads it right away
  (`status` goes from `processing` to `ready`, or `error`). Publish the assistant for customers to get it.
- `POST .../knowledge_sources/{source_id}/refresh` reads it again; the previous text stays in use until then.
- `DELETE .../knowledge_sources/{source_id}` stops using it at once.

Only public `http`/`https` pages are read. Adding and refreshing pages isn't available in the sandbox.