Reference
Every embed method, option, attribute and event, plus Content Security Policy rules, proxying the AI Assistant API, and versions.
The script tag adds a global DocumentationAI object. With npm, import it: import { DocumentationAI } from '@documentation.ai/embed'.
Methods
| Method | What it does |
|---|---|
init(options) | Starts the embed with your publishable key. Call it once, in the browser. |
Widget(options) | Places a widget and returns it. See Widget options. |
identify(token) | Signs the user in with a reader token or, on JWT sites, a JWT. See Private docs. |
signOut() | Signs the user out. Docs show public pages only. |
setTheme(mode) | Switches to 'light', 'dark' or 'system'. |
on(event, handler) | Listens for an event. Returns a function that stops listening. |
version | The script's version, such as 1.0.1. |
Calls can come in any order. Widgets created before init() finishes appear once it has loaded your site's settings.
init() options
Your publishable key, pk_..., from Settings > Embed.
The color scheme. Defaults to 'system', which follows the user's device. Change it later with setTheme().
lightdarksystemYour brand color for the AI Assistant, such as '#4f46e5'. Defaults to your docs site's brand color.
A reader token. The same as calling identify() before any page loads. See Private docs.
Widget options
All widgets
Where the widget shows. inline (the default) shows inside target. floating opens over your page from a launcher.
inlinefloatingWhat the widget shows first. Defaults to home: a greeting, a box to ask, starter questions and your collections.
homeassistantdocsThe page a docs widget starts on. Defaults to your docs' first page. See Paths.
false makes the widget docs only, with no box to ask and no Ask AI. Defaults to true.
The greeting on home and in an empty chat. Defaults to "How can I help you today?".
Lists of links on home. A link with path opens a docs page in the widget. A link with href opens in a new tab.
Inline widgets
The element the widget goes in: a CSS selector or an element.
For a docs page, a bar above it with the page title, a Back button and search. Defaults to false.
For a docs page, where its AI Assistant opens: a panel in the corner (the default), or over the whole visible page, which suits docs in a small box.
cornercoverIn pixels. Home grows with its content from this height. Defaults to 400. A docs page keeps this much space free while it loads (480 by default), so your page doesn't jump.
In pixels. Home grows up to this height, then scrolls. Defaults to 640.
Floating widgets
What opens the widget. Defaults to a Help button. See Launcher options. false shows no launcher: open the widget from help links or its methods instead.
The panel grows wider and taller to show a docs page. Defaults to true. Users can expand or collapse it either way.
The stacking order of the launcher and panel. Defaults to 2147483000.
Launcher options
The button text, or the bar's placeholder. Defaults to Help, or Ask AI when defaultView is assistant. The bar shows Ask AI a question...
Where the launcher sits. Defaults to bottom-right.
bottom-rightbottom-leftbottom-centertop-righttop-leftDistance from the screen's edges, in pixels. Defaults to 20 for each.
Widget methods
Widget() returns an object with these methods:
| Method | Floating widget | Inline widget |
|---|---|---|
navigate(path) | Opens on that docs page. | Shows that docs page. |
ask(question) | Opens the chat and asks. | Switches to the chat and asks. On a docs page, asks its AI Assistant. |
open(view) | Opens, on view if given: 'home', 'assistant' or 'docs'. | Switches to view, or back to how it was set up. |
close() | Closes the panel. | Closes a docs page's AI Assistant. |
destroy() | Removes the widget. | Removes the widget. |
A page opened with navigate() becomes the widget's starting point, so it has no Back button.
Paths
path and navigate() take a path on your docs site, such as /guide/install or /guide/install#requirements, or a full URL on your docs site. Links to anywhere else are ignored, with a warning in the console.
Help link attributes
A question. A click opens the AI Assistant and asks it.
A click opens the widget as you set it up. With a value, it opens on that view.
homeassistantdocsSee Help links for how the panel behaves.
Events
const stopListening = DocumentationAI.on('navigate', (event) => {
// Open answer citations in your own help center instead of the widget.
if (event.source === 'citation') {
event.preventDefault();
window.location.assign(`/help${event.path}`);
}
});
| Event | When it fires | Details |
|---|---|---|
ready | init() has loaded your site's settings. | docsUrl: your docs site's address. |
navigate | A user clicks a link inside the docs (source: 'docs') or a citation in an answer (source: 'citation'). | url, path, source, and preventDefault() to handle the link yourself. |
auth-required | A private page needs a signed-in user. | path |
access-denied | The signed-in user's roles don't include the page. | path |
identity-required | The user's docs session has ended. Call identify() with a new token. | reason: 'expired' |
error | Something went wrong. See Troubleshooting. | code, message |
Content Security Policy
If your site sends a Content Security Policy, allow:
script-src https://embed-cdn.documentation.aiconnect-src https://assistant-api.documentation.aiand your docs site's addressframe-srcyour docs site's address
Your docs site only lets itself be framed by the origins on the key. On any other site, the browser refuses to show embedded docs.
Serve the AI Assistant API from your domain
To load the AI Assistant API from your own domain, for a single-domain Content Security Policy or to avoid ad blockers, proxy https://assistant-api.documentation.ai/* and pass your proxy's base URL:
DocumentationAI.init({ publishableKey: 'pk_...', apiHost: 'https://example.com/docs-ai' });
Your proxy must forward the Origin, Referer and X-Forwarded-For headers. The API checks the origin against the key's allowed origins and rate-limits by the user's IP address.
Versions
https://embed-cdn.documentation.ai/v1/embed.js always serves the latest 1.x release, so fixes reach you automatically.
To stay on one version, load it by number instead, such as https://embed-cdn.documentation.ai/1.0.1/embed.js. Subresource Integrity (integrity="...") works only with a version number, because an integrity hash matches one exact file.
The npm package is @documentation.ai/embed.