Create a chat completion
Creates a chat completion: one request, one reply. Nabu does not store the conversation. Send the full messages array on every follow-up.
When hubIds are provided, Nabu retrieves relevant content from those knowledge hubs and uses it to answer. Each ID must be allowed for the API key.
Last message
The last message in messages must be from the user role with non-empty text
(plain string or text parts). Requests that end with an assistant message,
a blank user message, or whitespace-only content return 400.
Instructions
Set system guidance with instructions. When knowledge hubs are included, Nabu
appends retrieval instructions after this value. Do not send role: system
in messages; that returns 400. Roles in messages are user and
assistant only.
Streaming
Set "stream": true in the JSON body to receive a text/event-stream of
JSON events (not text/plain). Each event is one SSE data: line. The stream
ends with data: [DONE].
Event types:
| Event | Meaning |
|---|---|
start | Reply begins. messageMetadata has model, organizationId, webSearch, and hubIds. |
text-start / text-delta / text-end | Assistant text |
reasoning-start / reasoning-delta / reasoning-end | Model reasoning, when the model emits it |
source-url | Citation. sourceId, url, and title are always present. hubId and hubFileId are present for knowledge hub files; ignore them if you only need the URL fields. |
finish | Reply complete (finishReason only) |
error | Stream error |
Web search
When webSearch is true, the model may use the open web as well as
knowledge hub files. The model field in the JSON response (and
start.messageMetadata.model when streaming) is the model that was used
and may differ from the request.
Empty retrieval
When knowledge hub retrieval runs but finds no relevant files (and there is no usable conversation history), the API returns a fixed assistant message instead of guessing. Streaming still uses the same event sequence as a short text reply.
Authorization
bearerAuth Nabu API key from Organization settings → API keys. Keys are prefixed with key_.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Chat completion request. The last message must be from the user with non-empty text. Every hubId must be allowed for the API key.
Response Body
application/json
application/json
application/json
curl -X POST "https://example.com/chats" \ -H "Content-Type: application/json" \ -d '{ "messages": [ { "role": "user", "content": "What is the capital of France?" } ] }'{ "model": "openai/gpt-5-nano", "organizationId": "org_01234567-89ab-cdef-0123-456789abcdef", "webSearch": false, "hubIds": [ "hub_01234567-89ab-cdef-0123-456789abcdef" ], "messages": [ { "role": "user", "content": "What is our refund policy?" }, { "role": "assistant", "content": "Customers may request a full refund within 30 days of purchase [1].", "parts": [ { "type": "text", "text": "Customers may request a full refund within 30 days of purchase [1]." }, { "type": "source-url", "sourceId": "file_01234567-89ab-cdef-0123-456789abcdef", "url": "https://app.example/hubs/hub_.../files/file_...", "title": "[1] refund-policy.pdf", "hubId": "hub_01234567-89ab-cdef-0123-456789abcdef", "hubFileId": "file_01234567-89ab-cdef-0123-456789abcdef" } ] } ]}