AI Assistant
The AI assistant that answers questions from your docs — on your doc site, embeddable anywhere, and connected to AI IDEs.
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:
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:
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:
On your doc site, readers do this from the /ask page:
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:
With memory off, nothing is extracted or used, and readers don't get memory controls. aiPersona.memory defaults to "on".
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.
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.
/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.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.
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:
When sharing is refused:
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:
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.
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:
/_audience-auth, and brings them back to /ask afterwards.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:
/_chat), in the v2 /ask page. Direct API calls and the embeddable widget never get it.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:
POST, PUT and PATCH need that confirming click.DELETE also needs the reader to type DELETE.$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.
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:
3xx comes back as the result.Agent mode settings
Under Integrations › Agentic mode:
| Dashboard | Setting | Default |
|---|---|---|
| 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 null | not set |
| Send a support.handoff webhook (Send to support) | support.webhook: true or false — counts only while an active webhook endpoint subscribes to support.handoff | false |
| Tell readers about gated pages (Answers) | agent.gatedDetection: true or false | false |
| Name the audience (Answers) — only with the switch above on | agent.gatedDetectionShowAudiences: true or false | false |
| Run API requests from answers (Answers) | agent.runRequests: true or false | false |
The same settings through Update Project:
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 site | API |
|---|---|
POST /_chat | Ask the AI Assistant, with format: "events" for the steps, answer, follow-ups and memory as server-sent events |
GET /_chat/config | Get Widget Config — features says which actions the site offers |
POST /_chat/gaps | Report a Docs Gap |
POST, DELETE /_chat/sessions/{sessionId}/share | Share a Conversation |
GET /_chat/shared/{token} | Get a Shared Conversation |
POST /_chat/handoff/summary | Draft a Support Handoff |
POST /_chat/handoff | Send to Support |
POST /_chat/run | Run 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 |
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:
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.
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
X-Message-Id headerLimits & 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.