Assistants (RAG)

An assistant answers questions from one or more of your collections. On every turn it retrieves matching documents, hands them to the model and returns the answer together with the documents it was based on. It is retrieval-augmented generation (RAG) you configure rather than build.

Because the answer is grounded in retrieved documents, it is only as good as what retrieval found — the returned sources are the first thing to check when an answer looks wrong.

Creating and changing assistants needs a full key. Asking one also works with a search key from a browser (see From a browser). For query understanding inside a normal search request instead of a chat — parsing plain language into filters, or a refinement loop with your own model — see natural-language search and conversation models.

Create an assistant

createAssistant — POST /assistants:

const assistant = await client.assistants.createAssistant({
  name: "Store help",
  system_prompt: "You help shoppers choose tools. Answer only from the sources.",
  collections: [
    {
      name: "products",
      query_by: "name,description",
      filter_by: "in_stock:true",
      k: 5,
      include_fields: "id,name,price,url",
    },
  ],
  max_sources: 6,
  retrieval_mode: "single",
});
// assistant.id — use it for every chat call

listAssistants, getAssistant and deleteAssistant do what their names say. updateAssistant (PUT /assistants/{assistantId}) takes the same body as create, so send the whole configuration.

Ask

createChatCompletion — POST /assistants/{assistantId}/chat/completions:

curl -X POST "https://api.aacsearch.com/v1/assistants/$ASSISTANT_ID/chat/completions" \
  -H "X-NOVA-API-KEY: $NOVA_API_KEY" -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Which drill is best for concrete?"}]}'

The request:

The answer:

{
  "id": "…",
  "conversation_id": "…",
  "message": { "role": "assistant", "content": "For concrete, pick a hammer drill [1] …" },
  "sources": [
    { "collection": "products", "document": { "id": "42", "name": "Hammer drill, 18V" }, "score": 0.91, "snippet": "…" }
  ],
  "usage": { "input_tokens": 1830, "output_tokens": 164 },
  "model": "@cf/meta/llama-3.3-70b-instruct-fp8-fast"
}

sources are in the order the model saw them, so [1], [2] in the answer point at sources[0], sources[1]. Render them as links: they are what makes an answer checkable.

Stream the answer

streamChatCompletion — POST /assistants/{assistantId}/chat/completions/stream — takes the same body and answers with Server-Sent Events. Each event is a ChatChunk with a type:

const stream = await client.assistants.streamChatCompletion({
  assistantId: assistant.id,
  body: { messages: [{ role: "user", content: question }] },
});
let conversationId: string | undefined;
for await (const chunk of stream) {
  if (chunk.type === "delta") process.stdout.write(chunk.delta ?? "");
  if (chunk.type === "done") conversationId = chunk.conversation_id;
}

Conversations

Send the conversation_id from the previous answer (or the done chunk) with the next turn, and only the new message — the assistant loads the history itself. A conversation can be continued for memory_ttl_seconds after it was last used.

• getConversation — GET /assistants/{assistantId}/conversations/{conversationId} returns the history.
• deleteConversation — the same path with DELETE, for example when the shopper clicks "start over".

From a browser

createChatCompletion, streamChatCompletion, getConversation and deleteConversation are search-scoped, so a storefront calls them directly with a search key or a short-lived browser key minted by your server (see the widget's keys). With a search key:

• X-NOVA-SESSION-ID is required (400 without it) — one id per browser tab.
• A conversation belongs to the session that started it; another session gets 403.
• AI calls are limited per visitor session; past the allowance the API answers 429, with Retry-After when it knows how long to wait.

The aacsearch-ui support chat and the light widget send the session header for you.

Cost

Every turn is paid in credits from the organization's wallet by tokens in and out, whichever key made the request (see credits). When the wallet cannot cover a turn the API answers 402 with message, available and requested. To spend less per turn, lower max_sources or model.max_output_tokens, trim include_fields to what the answer needs, and keep retrieval_mode: "single".