/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API Reference List Documentation Gaps

List Documentation Gaps

Open documentation gaps detected from AI assistant questions, most asked first.

GET/v1/projects/{projectId}/analytics/gapsTry it
Session token

Returns the project's open documentation gaps — topics visitors asked the AI assistant about that the docs could not answer well, or that readers reported from agent mode — most asked first, with where each was seen and a link to dismiss it.

Note

Session JWT and org membership required. Any role can read it — an API key gets 401, a non-member 403. Any plan.

Path Parameters

NameDescription
projectId:stringpathRequired
The project ID.

Query Parameters

NameDescription
limit:integerquery
Gaps per page, 1–100. Values outside the range are clamped.
Default20
offset:integerquery
Gaps to skip. Negative values count as 0.
Default0
source:stringquery
reported lists only gaps readers reported with Report a docs gap; inferred only gaps inferred from low-confidence answers. Omit it for both. total counts the filtered list. Any other value is a 400.

Response Fields

NameDescription
total:integer
How many open gaps match source, across every page — all open gaps when source is omitted. Top level, next to data.
data[].topic:string
The normalized question (lower-cased, whitespace collapsed) that identifies the gap.
data[].sampleQuestions:string[]
Up to five questions as visitors asked them.
data[].frequency:integer
How many times the gap was asked since createdAt.
data[].avgConfidence:number | null
Average answer confidence for those questions, 0–1.
data[].source:string
reported when at least one reader reported this topic from agent mode, otherwise inferred (seen only in low-confidence answers). A reader's report turns an inferred gap into a reported one; it never turns back. In the dashboard, reported gaps carry a Reported badge, and Insights › Content health can show only those with Reported by readers.
data[].period:string
The window frequency counts over, "since YYYY-MM-DD" (the gap's createdAt).
data[].sources:string[]
["Assistant"], plus "Search" when a search from the last 30 days that found nothing is part of the topic — for example the search "rotate api key" inside the question above — plus "Readers" when source is reported. Searches under 4 characters are ignored.
data[].signal:string
A one-line summary of the evidence, ready to display.
data[].dismissUrl:string
Path to Dismiss Gap for this gap, relative to https://api.syntext.dev.

Rows do not include resolved: every row this endpoint returns is open.

Note

total, period, sources, signal and dismissUrl are optional. If they cannot be computed, the response falls back to { "data": [...] } with the stored gap rows as they are — those rows do include projectId, resolved, dismissedBy and dismissedAt, and there is no total.

Dismissed gaps come back

Dismissing a gap removes it from this list. If visitors ask the same question again, the gap reopens with fresh counts: frequency starts at 1 and createdAt (and so period) is the moment it reopened. A reader's report never reopens a dismissed gap — only a new low-confidence answer does.

Error Responses

400 Bad Request

source is not reported or inferred (INVALID_REQUEST).

401 Unauthorized

Missing, invalid or expired session JWT, or an API key.

403 Forbidden

You are not a member of the organization that owns the project.

404 Not Found

The project does not exist or has been deleted.

Was this page helpful? Yes No
Request
cURLJavaScriptPythonGoRubyPHPJavaC#cURL
curl "https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/analytics/gaps?limit=20&offset=0" \
-H "Authorization: Bearer $SYNTEXT_JWT"
Responseapplication/json
200OK
{
"data": [
{
"id": "0c8e4a7d-2b1f-4e3a-9d6c-5f7a8b9c0d12",
"topic": "how do i rotate an api key without downtime",
"sampleQuestions": [
"How do I rotate an API key without downtime?",
"rotate api key zero downtime"
],
"frequency": 41,
"avgConfidence": 0.32,
"suggestedSymbol": null,
"source": "inferred",
"createdAt": "2026-10-02T14:20:00.000Z",
"updatedAt": "2026-11-08T09:41:12.000Z",
"period": "since 2026-10-02",
"sources": ["Assistant", "Search"],
"signal": "41 assistant questions · 28 zero-result searches in 30 days",
"dismissUrl": "/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/analytics/gaps/0c8e4a7d-2b1f-4e3a-9d6c-5f7a8b9c0d12/dismiss"
}
],
"total": 37
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext