/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
Guides Platform AI Assistant

AI Assistant

The AI assistant that answers questions from your docs — on your doc site, embeddable anywhere, and connected to AI IDEs.

18 min read

Every Syntext doc site ships with an AI assistant that answers only from your published documentation. It answers with citations, refuses to invent features, and reports what it couldn't answer as documentation gaps.

How It Works

After each production deploy:

1.
The assistant learns your newly published content, section by section (one section per heading)
2.
When a visitor asks a question, it finds the sections most relevant to it
3.
It answers only from those sections, with source citations. Only pages used for that answer become citation links
4.
When nothing in your docs matches, the assistant says it couldn't find the answer and suggests rephrasing or searching, instead of answering from general knowledge

If updating the assistant fails during a build, it keeps answering from your last successful build, and the next build catches it up.

Your content is isolated per project — it's never used to answer questions on anyone else's site, and never used for model training.

On Your Doc Site

The assistant appears automatically on deployed sites — the search bar doubles as an "ask" box, and visitors can open a full chat panel. No configuration required.

Every code block also has an Ask AI button — clicking it attaches the snippet to the chat input as a removable chip, and the code is sent along with the visitor's question so the assistant answers with the snippet in context.

Ask about this page (under On this page) opens the assistant with the page attached as a chip. While the chip is on, every question in that chat is answered about the page, and the answer cites it. × on the chip, or a new chat, removes it.

While the assistant works, it shows its progress as thinking states ("Searching docs for…", "Found results for…") before streaming the answer, so visitors always know something is happening. Each conversation can be cleared with the trash button in the panel header, and every answer carries source citations plus an AI disclaimer.

Customization

Under Integrations › Chat widget in your project you set up the embeddable widget:

•
Position of the launcher on the page
•
Accent colour — used for the header, launcher, and send button
•
Welcome message
•
Allowed origins — the sites the widget may be embedded on

A live preview updates as you edit; embedded widgets pick up saved changes within five minutes. The assistant's persona and per-visitor rate limit (details) are project settings that aren't editable in the dashboard. The exceptions are memory, sharing, Send to support, the gated pages notice and running API requests, which are set under Integrations › Agentic mode — see Agent mode settings.

Memory

In agentic mode, the assistant remembers a few durable facts about each reader across conversations — their tech stack, what they're building, their experience level, or preferences such as "Prefers code examples" — and uses them to tailor later answers.

What is stored: at most 12 short facts per reader, distilled from their questions and the assistant's answers after each exchange. Facts are tied to the anonymous visitor ID kept in the reader's own browser and to your project — no account, name, or email is involved, and facts are never shared across readers or projects. A reader without a visitor ID has nothing remembered.

Reader controls: each reader manages their own memory, through the visitor-scoped Assistant Memory endpoints:

•
See what the assistant remembers
•
Forget one fact, or forget everything
•
Turn memory off for themselves — stored facts are kept but neither used nor added to, until they turn it back on

On your doc site, readers do this from the /ask page:

•
v1 sites — a Memory section at the bottom of the chat history sidebar. Expand it for a Remember things about me switch, the remembered facts with Forget on each, and Clear all, which asks for confirmation.
•
Doc engine v2 sites — the Memory panel, opened from Memory in the chat header (the top bar on phones). The on/off switch is inside the panel, with Forget and Clear all. On the home screen, before a conversation starts, What I remember · Manage opens it. A Remembered: … note under an answer shows when the assistant learnt something new. See Memory controls.

The controls are hidden when you've turned memory off for the project.

Readers can also rename and delete their own conversations (Conversation History); deleting a conversation removes its messages.

Project switch: to turn memory off for every reader, switch off Remember things about readers in the Privacy panel under Integrations › Agentic mode, or set aiPersona.memory to "off" with Update Project:

json
{
"settings": {
"aiPersona": { "memory": "off" }
}
}

With memory off, nothing is extracted or used, and readers don't get memory controls. aiPersona.memory defaults to "on".

Note

Turning the project switch off stops memory from being read or written, but doesn't delete facts already stored. They aren't shown or used while memory is off, and come back into use if you turn it on again. A reader can still clear their own facts with Forget Everything.

Agent mode

With the Agentic mode integration on, your doc site gets a full-page assistant at /ask (details). On doc engine v2 sites, /ask also lets readers report a docs gap, share a conversation and send it to support, and shows the steps the agent took with real page titles. Two more actions are off until you turn them on: a notice when pages for signed-in readers matched, and API requests the reader runs from an answer.

Note

v1 sites: none of this applies to the v1 /ask page. It has no sharing, Report a docs gap, Send to support, gated pages notice or run cards, and its steps show pages by their path. The API endpoints work for any project.

What the agent shows while it works

Each answer starts with a trail of the steps behind it: the search, the pages it read, and — when memory is on — Used memory: "…" with the remembered fact that bore on the question. Follow-up questions and any Remembered: … note arrive with the answer.

•
What I did — the trail is open and updates live while the assistant works. When the answer starts arriving it folds to one line, such as Worked through 3 steps · 2 s; click it to expand it again, even while the answer is still streaming. Steps that found nothing (a search with 0 results, an API lookup with no endpoints) are left out, and a trail with no steps left isn't shown.
•
Saved and shared conversations — a reloaded or shared answer shows a folded summary of the pages it cites, which expands on click.
•
Small talk — greetings, thanks, goodbyes and questions about the assistant itself ("Who are you?") get a plain answer: no trail, no actions, no follow-ups and no gap buttons. They're never recorded as a documentation gap. A message that also asks something ("Hi, how do I add a domain?") is a normal question.
•
Citations and sources — citations are numbered links in the answer, numbered across the whole conversation, so a page keeps one number. Sources in the chat header shows how many pages were cited and opens a panel listing only those pages. The panel is closed until the reader opens it; their choice is remembered for the browser tab. With nothing cited, there's no Sources button. On phones, the numbered sources under an answer open the page.
•
The page the reader came from — when a reader opens /ask from a page, that page is a chip in their question and in the composer. While the chip is on, the assistant reads that page first, answers about it and cites it, so "What does this page cover?" is about that page. × on the composer chip removes it, so follow-ups aren't about that page. A page the reader isn't allowed to see is never read. An attached code block works the same way: the question is answered about that code.
•
Scrolling — the conversation scrolls freely, also while an answer is arriving; it follows the end only while you're at the end. Long code lines scroll sideways. Back to the page is a small link in the chat header (an icon on narrower screens).

Titles in the trail: pages in the trail and in the sources are named by their frontmatter title. Titles are recorded when your site builds, so they appear after the site's next build; until then, pages are named from their path.

Report a gap

Search for "…" and Report a docs gap appear only under an answer the docs couldn't give — nothing found, or a low-confidence answer — below the answer text. They aren't shown for small talk, or on answers reloaded from history. A click reports it: the button changes to Reported to the docs team, and the question lands in your documentation gaps as a Reported gap.

•
The question is taken from the reader's own conversation on the server — a report can't name something nobody asked. A code block they attached is left out.
•
It joins the open gap on the same topic, if there is one, adding to its count and sample questions, and marks it reported. Otherwise it creates one.
•
A gap your team dismissed stays dismissed.
•
The same question from the same conversation counts once.

In Insights › Content health, choose Reported by readers to see only these, or filter the gaps API with ?source=reported. Reporting is always available; it can't be turned off.

Sharing

Share in the chat header — or Share link in a conversation's menu in the history sidebar — creates a read-only link to the conversation and copies it. The link opens at /ask/s/<token> on your site, marked Shared by a reader · not reviewed by your site · read only, with Start your own chat. Stop sharing turns the link off at once.

What a link contains:

•
A snapshot — the conversation up to the moment it was shared. Anything asked afterwards is never added. Sharing again gives the same link; to share newer messages, stop sharing and share again, which makes a new link.
•
Every question and answer — answers keep their numbered citations, with a folded summary of the pages they cite. Links shared before 13 November 2026 that showed only the questions now show the answers too.
•
Nothing private — never the reader's memory, and never the code snippets they attached to a question. Their visitor ID and votes aren't included either.
•
Unlisted — anyone with the link can read it. The page isn't indexed by search engines, isn't cached, and doesn't send the link as a referrer to pages it links to.

When sharing is refused:

•
Gated content — a conversation where any answer used audience-gated pages can't be shared ("It used pages only signed-in readers can see"). This is checked again every time the link is opened. Conversations from before 13 November 2026 count as gated, so they can't be shared.
•
Private sites — on a site behind a password, or behind access control in password or invite-only mode, sharing is off and there's no Share button. If a site becomes private, its links stop working.
•
Turned off — with aiPersona.sharing: "off", there's no Share button and links already shared stop working (they work again if you turn sharing back on).

Send to support

When it's offered: after two answers in a conversation that the docs couldn't give — nothing found, or a low-confidence answer — or as soon as the reader asks for a person ("contact support", "talk to a human", "open a ticket"). A Contact support card appears under the conversation, with Not now to dismiss it. It's only offered when you've set up a support email or the support webhook.

What the reader confirms: the form shows where it goes, a summary of the conversation written from the chat for them to edit, a field for their email, and the transcript that will be attached, which they can preview. When the assistant remembers something about them, an Include what the assistant remembers switch is there too, off by default. Nothing is sent until they click Send to support. They then see Sent to your site support · Ticket ticket and that you'll reply to their email.

What is sent:

•
the ticket, the reader's email and their summary, exactly as they confirmed it
•
the transcript — the questions and answers, at most 100 messages, without attached code snippets
•
what the assistant remembers about them — only if they switched it on

It goes to your support email — with Reply-To set to the reader, so you can reply directly — and to the support.handoff webhook if you turned it on. If neither takes it, the reader is told it couldn't be sent.

Warning

The support email must be the address of a verified member of your organization. Any other address is ignored, so Syntext's mail can't be pointed at someone else. If you only use the webhook, subscribe an endpoint to support.handoff under Integrations › Webhooks — a webhook with no subscriber doesn't count as delivered.

Limits: each reader can send 3 handoffs a day; each project 50 a day; each organization 200 a day across all its projects. Drafting the summary counts as one AI query. See Agent mode action limits.

Gated pages notice

Off by default. With Tell readers about gated pages on, a reader who isn't signed in to an audience is told when pages they can't see matched their question closely. Above the answer they see Part of the answer is in pages for signed-in customers, with two buttons:

•
Sign in opens your site's audience sign-in form at /_audience-auth, and brings them back to /ask afterwards.
•
Answer from public pages dismisses the notice.

The answer itself is always built from public pages only.

What it never reveals: the notice is a yes, nothing more — no page titles, text, paths, scores or counts. Its line reads "Some matching pages are only for signed-in readers. Sign in to include them." With Name the audience also on, it names up to three audiences instead ("Matching pages are in the partners audience…"). Without that second switch, audience names never leave the server.

When it shows:

•
Only for readers who aren't signed in to any audience. A reader who already holds one is never told about others.
•
Only when a gated page is a close match, and would have ranked among the pages the answer used had it been visible.
•
Only on questions asked through your doc site (/_chat), in the v2 /ask page. Direct API calls and the embeddable widget never get it.
•
It's rate limited per reader, per IP, per project and per day — see Agent mode action limits. Over a limit, the notice simply doesn't appear; nothing tells the reader a limit was hit.
Note

The notice tells anyone who isn't signed in that some private topic matched their question. Leave it off if even that is too much for your site.

Running API requests from answers

Off by default. With Run API requests from answers on, the assistant can prepare a request to your API from your API reference. The reader checks it, pastes their own key and runs it, right in the answer.

This switch only covers the doc site's assistant. The hosted MCP connector doesn't run requests: its API reference tools read your endpoint docs and send nothing to your API.

What it needs: an OpenAPI spec in the project. Each production build saves the spec's endpoints and servers as the project's endpoint catalog — so after turning this on, the catalog is there from your next production build (a build with no spec removes it). Without a catalog, the switch does nothing and the assistant only explains endpoints.

How a run works:

1.
The assistant proposes at most one request per answer, only for an endpoint and server in your API reference. It never sends anything itself, and it never sees or asks for a key.
2.
A run card shows the exact request: method, host and path, every header (the key masked) and the body. Where the request goes is always shown — Sandbox or Live API, with the host — and a note says whether it reads or changes data.
3.
The reader pastes their key into the card's key field and presses Run request. Edit first lets them change the body.
◦
POST, PUT and PATCH need that confirming click.
◦
DELETE also needs the reader to type DELETE.
4.
The response appears in the card, with Copy as cURL (the key as $API_KEY), Run again and, when the endpoint has a page, Open in playground.

The key: it lives in a password field in that tab only — never in local storage, never in the page's markup. When the reader runs the request, the key passes through Syntext to your API for that request only. It's never stored, never logged and never given to the assistant.

Results go back only when the reader says so. Send result to assistant sends the status and body with the reader's next question, so the assistant can explain them. Nothing is sent without that click. The key is removed first, and secret-looking values are stripped before the assistant sees it. A result is never part of shared links, transcripts or support handoffs.

Where requests go: only a server you mark as a sandbox with x-syntext-sandbox: true is treated as one — in your OpenAPI servers, or in syntext.json baseUrls or an openapi entry's servers (details). Server descriptions and URLs are never guessed from.

Warning

Without a marked sandbox, runs go to the first server — your live API. The card says "It changes real data" before a POST, PUT, PATCH or DELETE. Mark a sandbox server if you have one.

Limits on what can be sent:

•
Only to a server, path and method in your endpoint catalog. Endpoints documented on pages a reader's audience can't see are never proposed or run for them.
•
Only to public addresses: private and local addresses are refused, including names that resolve to them. Redirects are not followed — a 3xx comes back as the result.
•
Each run waits at most 10 seconds for your API, and the response is cut at 512 KB.
•
Runs are rate limited per reader, per IP, per project and per organization — see Agent mode action limits.

Agent mode settings

Under Integrations › Agentic mode:

DashboardSettingDefault
Remember things about readers (Privacy)aiPersona.memory: "on" or "off""on"
Let readers share conversations (Privacy)aiPersona.sharing: "on" or "off""on"
Support email (Send to support)support.email: an address or nullnot set
Send a support.handoff webhook (Send to support)support.webhook: true or false — counts only while an active webhook endpoint subscribes to support.handofffalse
Tell readers about gated pages (Answers)agent.gatedDetection: true or falsefalse
Name the audience (Answers) — only with the switch above onagent.gatedDetectionShowAudiences: true or falsefalse
Run API requests from answers (Answers)agent.runRequests: true or falsefalse

The same settings through Update Project:

json
{
"settings": {
"aiPersona": { "memory": "on", "sharing": "off" },
"support": { "email": "support@acme.dev", "webhook": true },
"agent": { "gatedDetection": true, "gatedDetectionShowAudiences": false, "runRequests": true }
}
}

aiPersona, support and agent are each replaced as a whole, so send every key you want to keep — including your other persona keys. These settings take effect immediately, without a rebuild. Send to support is offered only when support.email belongs to a verified member of your organization or support.webhook is true.

For developers

The /ask page uses public endpoints that you can call yourself. On your doc site they're served same-origin under /_chat/..., with the project taken from the hostname:

Doc siteAPI
POST /_chatAsk the AI Assistant, with format: "events" for the steps, answer, follow-ups and memory as server-sent events
GET /_chat/configGet Widget Config — features says which actions the site offers
POST /_chat/gapsReport a Docs Gap
POST, DELETE /_chat/sessions/{sessionId}/shareShare a Conversation
GET /_chat/shared/{token}Get a Shared Conversation
POST /_chat/handoff/summaryDraft a Support Handoff
POST /_chat/handoffSend to Support
POST /_chat/runRun an API Request — reached only through the doc site
GET /_audience-auth?redirect=Your site's audience sign-in form on its own page — the gated notice's Sign in. Same-site redirect paths only
Note

On a site behind a password, or behind access control in password or invite-only mode, the assistant answers only through the doc site. Calls straight to Ask the AI Assistant get 403, and the embeddable widget isn't available.

Embedding Anywhere

The chat widget can be embedded on any site — your marketing pages, your app, your support portal:

html
<script
src="https://api.syntext.dev/v1/widget/<project-id>.js"
defer>
</script>

Copy the snippet from Integrations › Chat widget › Embed — it carries your project's ID (a UUID). Turn the widget on there and list each site that embeds it under Allowed origins: the loader answers 404 while the widget is off and 403 on a site that isn't listed. The loader inlines your saved settings, and the widget talks to /v1/widget/<project-id>/… on the Syntext API.

Warning

The widget isn't available for a site behind a password, or behind access control in password or invite-only mode: its chat answers 403 PRIVATE_SITE. Readers of a private site use the assistant on the site itself. Public sites are unaffected.

In AI IDEs (MCP)

Connect your docs to Cursor, VS Code, Claude, and other MCP clients so their AI can answer from your docs. The fastest path is the hosted connector — one URL (https://api.syntext.dev/mcp), OAuth sign-in, no API keys — see MCP Integration.

Feedback & Gap Detection

•
Visitors rate answers 👍/👎 (feedback endpoint) — the answer's ID comes from the chat endpoint's X-Message-Id header
•
Low-confidence and unanswered questions are recorded as documentation gaps, ranked by frequency, in Insights › Assistant — each with a Draft page action that opens the editor seeded with the question
•
On doc engine v2 sites with agent mode, readers can also report a gap themselves

Limits & Billing

AI queries are metered per organization per month. When the quota is reached, the assistant returns a friendly limit message and the API returns 402 USAGE_LIMIT_EXCEEDED — see Rate Limits.

Was this page helpful? Yes No
Product
Resources
Company
© 2026 SyntextBuilt with Syntext