Assistant API

The Assistant API lets the tools your team already uses ask your docs assistant. A support inbox, a Slack bot or a workflow sends a question and gets back the answer, the pages it came from, and whether the assistant could answer at all. Answers follow the same rules as your docs site: a key never reads a page your settings keep from it.

Create a key

How to create a key

Open the Assistant API settings

Go to Settings > Assistant API and click Create key.

Name the key and pick the tool

Enter a Name, such as Support inbox, and choose the tool in Connected to. Usage analytics are grouped by this choice.

Choose what the key answers from

What you can choose depends on your Access Control settings. See What a key can read.

Leave Allowed origins empty for server tools

Leave Allowed origins empty for Intercom, Zendesk, Zapier or your server. Add a site only if its pages call the API directly. See Use the API from a website.

Create the key and copy the secret key

Choose when the key Expires (1 year by default), then click Create key. Copy the Secret key from the dialog. It is shown only once.

To check the key, copy the Try it command and run it in a terminal. It asks your docs a real question, so it uses a credit when it gets an answer.

How to ask your first question

Send the secret key as a bearer token:

curl https://api.documentation.ai/api/v1/assistant/answers \
  -H "Authorization: Bearer asst_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"message": "How do I reset my password?"}'

The answer comes back with full links to the pages it used:

{
  "id": "ans_7f3c2a9e41b84d0e9a1c6b5d2e8f0a13",
  "conversation_id": null,
  "answered": true,
  "reason": null,
  "answer": "Open **Account > Security** and choose **Reset password**. See [Reset your password](https://docs.acme.com/account/reset-password).",
  "format": "markdown",
  "confidence": 0.92,
  "sources": [
    { "title": "Reset your password", "url": "https://docs.acme.com/account/reset-password" }
  ],
  "follow_up_questions": ["How do I turn on two-factor authentication?"],
  "created_at": "2026-11-06T09:30:00.000Z"
}

When answered is false, the assistant found nothing in your docs to answer with, or ran out of time. answer is empty, so your tool can hand the conversation to a person. A greeting or thanks, such as "hi", is the exception: reason is small_talk, and answer holds a short reply to send instead. Neither is charged. See the API reference for every field.

What a key can read

Every request is checked against your site's settings as they are published. Changing Access Control applies to keys once you publish, the same as it does for your docs site.

• On a public site, keys answer from every published page and you don't choose. The dialog says This key answers from every published page.
• If some pages need sign-in, choose Public pages only or All pages, including protected ones under Answers from.
• If every page needs sign-in, keys read protected pages. The dialog says This key reads protected pages.
• A key's access is never raised for you, nor changed when you edit its name, tool or origins. A public-pages key keeps reading public pages if you later put more pages behind sign-in, and is refused once every page needs sign-in, until you choose All pages, including protected ones in its Edit dialog.

How to limit a key to some roles

Roles appear when your site signs readers in with JWT, OAuth, or email verification where you approve each request, and role-based access is on.

1. Under Access roles, keep the roles the key may read. Every role you have declared is selected.
2. If new roles should be included automatically, select All roles, including ones added later. Otherwise a role you add later is not given to existing keys.
3. With no roles selected, the key reads only pages that are not limited to a role.

A key created before you turned on role-based access has no roles, so it reads only pages without a role until you edit it and choose some. If you remove a role from your site, keys keep it until you change their roles; the Edit dialog says which ones do.

How to answer for one reader

If your tool knows who is asking, send reader with the request. It only ever narrows what the key reads:

{
  "message": "How do I export invoices?",
  "reader": { "signed_in": true, "roles": ["billing"] }
}

• "signed_in": false answers from public pages only. On a site where every page needs sign-in, the request is refused with reader_sign_in_required.
• roles keeps only the roles the key also has.

Connect your tools

Each tool sends a POST request to https://api.documentation.ai/api/v1/assistant/answers with the secret key in the Authorization header. Set timeout_seconds below your tool's own time limit, so a slow answer comes back as not answered instead of failing.

An answer usually takes 10 to 20 seconds, because the assistant searches your docs and reads the pages it found. When a tool waits less than that, take its request, reply to it at once, and post the answer from your own server when it arrives, as the Intercom and Zendesk tabs show.

How to keep a conversation

• From a server or tool, send the same conversation_id with each message. The assistant keeps the earlier messages for you, separately for each key, and deletes a conversation 30 days after its last message.
• From a web page, or if you keep messages yourself, send the earlier messages in history and leave out conversation_id.

How to report whether an answer helped

Send the answer's id to POST /api/v1/assistant/feedback with "rating": "up" or "rating": "down". Ratings show with your docs site's in Analytics.

Use the API from a website

If your own website or product calls the API from its pages, add the site under Allowed origins, for example https://app.acme.com. Origins are exact: scheme, host and port, with no path and no wildcards.

• Pages on an allowed origin use the key's Publishable key, shown when you create the key. It answers from public pages only.
• For answers from protected pages, your server creates a short-lived reader credential for each visitor with POST /api/v1/assistant/reader-credentials, and the page uses it instead of the publishable key. A credential works only from the origin it was created for, never reads more than its key, and cannot create more credentials.

See the API reference for the request.

Manage keys

You must have the Admin role. Changes apply on the next request.

Each key's actions are in the menu at the end of its row.

• Edit: change the name, the tool, what the key answers from, its roles and its allowed origins. Tools using the key keep working, because the key itself doesn't change.
• Rotate secret key: get a new secret key. The old one stops working at once. The key's settings and usage history stay.
• Revoke: the tool using the key stops getting answers at once. This cannot be undone.

Analytics

Questions asked through the API appear in Analytics > AI Assistant with your docs site's. Use Type to show All, Docs site, Embed or API questions. Totals include API questions unless you filter them out. Embedded questions are counted as Embed from the embed SDK release that reports them; earlier ones count as Docs site.

Credits used by API answers show as Assistant API in Settings > AI Usage.

Common questions

If a request fails

Every refusal has an error code and a message saying what to do. The API reference lists them all. The ones you are most likely to see:

• browser_not_allowed: a secret key was sent from a web page. Rotate the key, and use the publishable key or a reader credential in pages.
• key_access_insufficient: the key reads public pages only and every page of the site now needs sign-in. Open the key's Edit dialog, choose All pages, including protected ones and save, and it reads protected pages from then on.
• origin_not_allowed: add the page's origin under Allowed origins, written exactly as the browser sends it.
• rate_limited: wait the number of seconds in retry_after_seconds, then retry.
• credits_exhausted: add credits or turn on overage in Settings > Billing.

Limits

Every request with a valid key counts towards the per-key limit, and its response, a refusal included, carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. If you need more requests per minute, contact support.

Related