/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API Reference Report a Docs Gap

Report a Docs Gap

A doc-site reader reports that the docs don't cover a question they asked the assistant.

POST/v1/projects/{projectId}/chat/gapsTry it

Records that the docs don't answer a question a reader asked the assistant. On doc engine v2 sites with agent mode, this is the Report a docs gap button on an answer the docs had nothing for. See Report a gap.

The question is read from the reader's own conversation on the server, never from the request body, so a report can only name something that was really asked. It is added to the project's documentation gaps with source: "reported".

Public (no API key required) and scoped to the project and the visitorId: a reader can only report from their own conversation.

Note

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

Path Parameters

NameDescription
projectId:stringpathRequired
The project ID.

Request Body

NameDescription
visitorId:stringbodyRequired
The anonymous visitor identifier (1–100 chars) that owns the conversation.
sessionId:stringbodyRequired
The conversation's UUID — the X-Session-Id from Ask the AI Assistant.
messageId:stringbody
The UUID of the answer being reported (X-Message-Id, or id on the message event). The reported question is the reader's last question at or before that answer. Without it, the conversation's latest question is reported.

How a report is recorded

•
The question is reduced to the same topic key the assistant uses for gaps it infers from low-confidence answers. A code block the reader attached is left out.
•
No open gap on that topic: a new gap is created with frequency: 1 and source: "reported".
•
An open gap on that topic: its frequency goes up by one, the question joins its sample questions (up to five), and its source becomes "reported".
•
A gap your team dismissed: left dismissed. A reader's report never reopens it.
•
The same question from the same conversation counts once for 30 days. Repeat reports get 200 and change nothing.

Response — 201 Created

201 when the report was recorded; 200 with the same body when this question was already reported from this conversation.

Rate Limits

PerLimit
Visitor5 reports an hour
Client IP20 reports an hour — only for requests through your doc site
Project200 reports an hour

A request is only counted once the conversation is found to be the visitor's, so a request for someone else's conversation never uses up the allowance. Over a limit, the response is 429 with a Retry-After header — see Agent mode action limits.

Error Responses

StatusCodeWhen
400validation_errorvisitorId or sessionId missing or malformed, or messageId not a UUID
403FORBIDDENThe site is private (password, invite-only or SSO) and the request didn't come through the doc site ("Ask from the docs site")
404NOT_FOUNDThe project doesn't exist, or the conversation (or the answer messageId names) isn't this visitor's in this project, or has no question
429RATE_LIMITEDA limit above was reached. retryAfterSeconds says when to try again
500internal_errorThe report could not be saved
•
List Documentation Gaps — filter with ?source=reported
•
Report a gap — how readers see it
Was this page helpful? Yes No
Request
bashJavaScriptPythonGoRubyPHPJavaC#bash
curl -X POST https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/chat/gaps \
-H "Content-Type: application/json" \
-d '{
"visitorId": "vis_9f8e7d",
"sessionId": "b2e9a1c4-5d3f-4e7a-9b08-6c2f1d4e8a93",
"messageId": "7f0c2d4e-91a3-4b6e-8f25-3c1d9e0a6b47"
}'
Responseapplication/json
201Created
{
"data": { "reported": true }
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext