/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API Reference Ask the AI Assistant

Ask the AI Assistant

Ask the project's AI assistant a question and stream the answer.

POST/v1/projects/{projectId}/chatTry it

Ask a question against a project's documentation. The answer is grounded in the project's published documentation and streamed back as Server-Sent Events with citations.

This is the endpoint the embeddable chat widget uses — it's public (no API key required) but subject to visitor rate limits and the organization's monthly AI query quota.

Note

On your doc site this endpoint is also served same-origin at POST /_chat. The project comes from the site's hostname, so the path takes no projectId.

Warning

Private sites answer only through the doc site. For a site behind a password or SSO, or behind access control in password or invite-only mode, this endpoint answers only requests that come through the doc site (/_chat), which signs them. A direct call gets 403 FORBIDDEN, so a custom chat UI that calls the API straight from another page no longer works for such a site. Public sites are unaffected.

Path Parameters

NameDescription
projectId:stringpathRequired
The project ID.

Request Body

NameDescription
question:stringbodyRequired
The question to ask. 1–2000 characters.
sessionId:stringbody

UUID of an existing chat session for multi-turn context. Omit to start a new session — the response returns the session ID in the X-Session-Id header.

A session is only continued when it belongs to this project and to the same visitor: send the same visitorId that started it (or none, if it was started without one). Any other sessionId — another project's, another visitor's, or one that doesn't exist — starts a new session instead, and its history is never read. Always use the X-Session-Id you get back.

visitorId:stringbody

Anonymous visitor identifier (max 100 chars). Used for per-visitor rate limiting and analytics, and — in agentic mode — for the visitor's conversation history and cross-conversation memory: the assistant distills durable facts from each exchange and uses them to tailor future answers for the same visitor.

Memory is skipped — nothing is read or saved — when the project has turned it off (aiPersona.memory: "off") or the visitor has turned it off through Assistant Memory. Without a visitorId, no memory is kept.

pageContext:stringbody
The doc page path the visitor is currently on (max 500 chars). Improves retrieval for inline "ask about this page" experiences.
attachedPage:stringbody
A doc page path the question is about, such as /cli/init (max 500 chars). The assistant reads that page first, answers about it and cites it. A page the visitor isn't allowed to read is never loaded; the assistant says it couldn't read the page instead. Leave it out when the question isn't about one page.
codeSnippet:stringbody
A code block the visitor attached with a code block's Ask AI button (max 50,000 chars). The question is answered about this code. Shared conversations and support handoffs leave it out and show only what the visitor typed.
format:stringbody
How the answer is streamed: text (the default) or events. With events, the body is a stream of server-sent events that carry the steps the assistant took, the answer, its message ID, follow-up questions and what it remembered. With text or no format, the response is unchanged. The X-Stream-Format header says which one you got.
Default"text"
runResult:objectbody

The result of a request the reader ran from a run card and chose to send with Send result to assistant. Only read with format: "events" when the project has agent.runRequests on; otherwise ignored. Never include the reader's key.

{ method, url, status, statusText?, timeMs?, body? } — method is GET, POST, PUT, PATCH or DELETE; url up to 2000 characters; status an integer 0–999; statusText up to 100 characters; body up to 200,000 characters.

Before the model sees it, secret-looking values are stripped (key, token, secret and password fields and query parameters, your API's declared auth parameter, Bearer/Basic values and known token shapes) and the body is cut to 4000 characters. It's stored apart from the question, so it never appears in shared conversations, transcripts, support handoffs or reported gaps. Retrieval uses the question only.

Response

200 with Content-Type: text/event-stream. With format unset or text, the body streams the answer text as it is generated. Citations appear inline as bracketed source paths, such as [guides/custom-domains#Verify your domain].

HeaderContents
X-Session-IdThe session UUID. Pass it as sessionId on the next question to continue the conversation
X-Message-IdThe answer's message ID, sent before the answer streams. Pass it to Submit Chat Feedback for a thumbs up/down
X-Retrieved-CountHow many documentation sections were found for the answer
X-Retrieved-PagesURL-encoded, comma-separated list of every distinct page retrieved, in retrieval order — the only pages the answer may cite
X-Stream-FormatHow to read the body: events when you sent format: "events", otherwise text

Read X-Message-Id from the headers, not the body. The answer is saved under that ID when the stream finishes, so rate it after the stream completes.

Structured events (format: "events")

With format: "events", the body is a stream of server-sent events. Each event is an event: line and one data: line of JSON, followed by a blank line:

text
event: step
data: {"kind":"search","query":"How do I add a custom domain?","count":8}
event: step
data: {"kind":"read","pages":[{"path":"guides/custom-domains","title":"Custom domains"},{"path":"deployment/dns","title":null}]}
event: text
data: {"delta":"Add the domain under "}
event: text
data: {"delta":"**Settings › Domains** [guides/custom-domains#Add a domain]…"}
event: message
data: {"id":"7f0c2d4e-91a3-4b6e-8f25-3c1d9e0a6b47","sessionId":"b2e9a1c4-5d3f-4e7a-9b08-6c2f1d4e8a93","lowConfidence":false,"smallTalk":false}
event: followups
data: {"questions":["How long does DNS verification take?","Can I use an apex domain?"]}
event: remembered
data: {"fact":"Hosts DNS on Cloudflare"}
event: done
data: {}

Events arrive in this order. Only step (search), text, message and done always appear; the others are left out when they have nothing to say. gated comes after the steps and before the first text. With agent.runRequests on, the assistant can search the docs again, look up endpoints and prepare a request while it answers: those step (search, read, api) and run events arrive as they happen, between text events.

EventdataWhen
step{ "kind": "search", "query", "count" }First. query is the question (up to 200 characters); count is how many documentation sections were found. 0 means the docs had nothing on it
step{ "kind": "read", "pages": [{ "path", "title" }] }Every distinct page retrieved, in retrieval order. title is the page's frontmatter title, or null for a page the site's last build did not record a title for (titles are recorded from the first build after 13 November 2026)
step{ "kind": "mem", "fact" }The remembered fact most related to the question, when memory is on and one shares words with the question. Every remembered fact is still given to the model; this names the one that likely mattered
step{ "kind": "api", "method", "path", "count" }With agent.runRequests on: the assistant looked up endpoints in the project's API reference. method and path are the first match, count how many matched
gated{ "signInUrl", "audiences"? }With agent.gatedDetection on: pages for signed-in readers matched the question closely. Only for a reader with no audience, and only through the doc site. A yes only — no titles, text or counts. signInUrl is /_audience-auth; audiences (up to 3 names) only with agent.gatedDetectionShowAudiences on. See Gated pages notice
run{ "id", "state": "confirm", "method", "url", "headers", "body"?, "server", "auth", "endpoint", "confirm" }With agent.runRequests on: a request the assistant prepared for the reader to check and run — never already sent. At most one per answer. headers holds no credentials; server is { url, description?, sandbox }; auth says where the reader's key goes ({ label, name, in, prefix }, or null); endpoint is { method, path, summary?, page? }; confirm is typed for DELETE and click otherwise. Send it with Run an API Request
text{ "delta" }A piece of the answer. Join the deltas in order for the full answer, with the same inline citations as the text format
message{ "id", "sessionId", "lowConfidence", "smallTalk" }After the last text. id is the answer's message ID (the same value as X-Message-Id), sessionId the conversation's. lowConfidence is true when the docs found matched the question poorly — the answer counts as a documentation gap. smallTalk is true for a greeting, thanks, goodbye or question about the assistant itself; such a question is never low confidence and never recorded as a gap
followups{ "questions" }Up to 3 suggested next questions, from this exchange. Replaces a separate call to Suggest Follow-up Questions
remembered{ "fact" }A new fact the assistant saved about the visitor from this exchange. Only when memory is on for the project and the visitor, and a visitorId was sent
error{ "message" }The answer failed part-way. message is always The assistant is unavailable right now. Please try again later. — underlying error details are never passed on. The stream ends after it, with no done
done{}The answer, follow-ups and memory are finished. The stream closes

Because follow-ups and memory are worked out before done, an events stream stays open a little longer after the last text than a text stream. Ignore event names you don't recognise.

Error Responses

429 Rate Limited

The visitor asked too many questions in a short window. Configurable per project.

json
{
"error": {
"code": "RATE_LIMITED",
"message": "Too many requests. Please wait before asking another question.",
"retryAfterSeconds": 30
}
}

402 Usage Limit Exceeded

The organization's monthly AI query quota is exhausted. (Earlier releases returned 403; match on the code.)

json
{
"error": {
"code": "USAGE_LIMIT_EXCEEDED",
"message": "Monthly AI query limit reached (1000/1000). Upgrade your plan for more AI queries.",
"current": 1000,
"limit": 1000
}
}

503 Service Unavailable

The AI assistant is not configured for this deployment.

403 Forbidden

The site is private — behind a password, SSO, or access control in password or invite-only mode — and the request didn't come through the doc site (FORBIDDEN, "Ask from the docs site").

404 Not Found

The project doesn't exist or was deleted (NOT_FOUND).

Note

Unanswered and low-confidence questions are tracked as documentation gaps — see Analytics.

Was this page helpful? Yes No
Request
cURLJavaScriptPythonGoRubyPHPJavaC#cURL
curl -N https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/chat \
-H "Content-Type: application/json" \
-d '{
"question": "How do I add a custom domain?",
"visitorId": "vis_9f8e7d"
}'
Product
Resources
Company
© 2026 SyntextBuilt with Syntext