API reference / Knowledge
Knowledge
There is no knowledge base on this service: no document store, no chunking, no embedding, no vector index and no similarity search. Nothing of the kind exists to call.
What an avatar knows comes from two places, and both are small enough to describe in a paragraph each. Neither is a retrieval system, and neither will scale to a corpus, so plan your grounding on your own side.
What to use instead
The system prompt
The entire persistent knowledge surface is one free text field, system_prompt,
on the settings record. Write it with
POST /api/settings and read it back with
GET /api/settings. It is per calling credential, it persists, and it is applied
to every turn that credential drives.
That is the right place for standing facts: who the avatar is, what it is for, the handful of things it must always know. It is the wrong place for a document set, and there is no fallback when the prompt gets long.
Per session facts about the person
POST /connect accepts a client_context object carrying sanitized facts about
the listener for that session only. Four fields are accepted and each is
validated on its own:
An IANA zone. Also decides which zone the time tool answers in.
What to call the person.
Where they are, so the avatar can phrase things for the surface.
Their locale.
A field that fails validation is dropped on its own and the rest survive, so a malformed payload costs a nicety rather than the session. Nothing here is persisted: it lives for the length of the connection and is gone with it. See Engine.
Retrieval, on your side
For anything larger, run retrieval in your own application and put the retrieved passage into the turn. Both paths accept it:
POST /api/chatwith the passage inlined inmessage.- The control WebSocket's
messageevent, same idea, with the streaming reply coming back over the socket.
That keeps your corpus in your own store, with your own access rules, which is usually where a compliance conversation ends up anyway.
Not served in this group
Every knowledge operation a comparable API offers. Named individually so nobody
has to discover them one 404 at a time:
- Create, list, read, update and delete a knowledge group.
- Search within a group.
- Create, list, read, update, delete and download a document.
- An upload token as an alternative credential.
The one adjacent mechanism that does exist is expiring presigned download URLs, used for avatar media. The mechanism is proven; it is simply not wired to documents, because there are none.