Knowledge Base widget API
Ask a knowledge base a question from a web page and get back a grounded answer with citations, from the same engine and under the same access rules the workspace uses. A widget token never widens what a question can reach.
These endpoints use a scoped widget token, issued by a signed-in person for one knowledge base and meant for a browser embed. There is no way for a server to renew one.
If you are integrating server to server, you want the Knowledge Base partner API instead: an account-level API key, no person in the loop, and a wider surface covering ingestion, conversations and per-document access. The two credentials are not interchangeable in either direction.
What you can call
| Endpoint | What it does |
|---|---|
POST /kb-api/api/v1/kb/{kbId}/widget/query | Ask a question, get an answer with citations |
POST /kb-api/api/v1/kb/{kbId}/widget/query/stream | The same, streamed back as it is written |
Both take the same request body. Add them to your base URL, for example
https://api.example.com/kb-api/api/v1/kb/{kbId}/widget/query.
How a request is authenticated
You issue a scoped token from the knowledge base's Developers tab, under Embeddable widget, and send it on every call in either header:
Authorization: Bearer <token>
X-Widget-Token: <token>
The token is bound to one knowledge base and to the domains you listed under Embedding
domains. A browser request must come from one of those domains. A request from your own server
sends no Origin header at all, and is accepted on that basis.
A widget token reaches only the knowledge base's Public documents. Documents restricted to roles, departments or groups never appear in its answers or citations.
Three limits to plan around
- A token lasts 60 minutes by default, and that is also the most you can ask for. The cap is a platform setting, so trust the minutes shown when you issue the token rather than this number.
- Issuing one needs a signed-in person whose role grants Knowledge Base · Setup - Create on that knowledge base. Revoking one needs Knowledge Base · Setup - Delete. A server cannot renew its own token, so a backend integration has to be handed a fresh one each time.
- A browser embed also needs the page's domain on the knowledge base's own allow-list, shown as Allowed origins (CORS) on the Embeddable widget tab. The browser checks that list before it sends the token, so a domain that is on the token but not on this list fails. The workspace has no control to edit the list today: ask your Elie contact to add your domain.
Together, these make the widget right for a demo, a pilot page or an internal site, and awkward for an unattended production integration.
Next
- Developer access and widget tokens - issue and revoke a token.
- Query endpoints - request and response fields.
- Embed the chat widget - the snippet that does it for you.
- Errors - status codes and the error body.