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

Feedback API

Collect page and section-level feedback from doc site visitors.

4 min read

Doc sites collect visitor feedback at two granularities: page-level ("Was this page helpful?") and section-level (per-heading votes). Deployed sites include these widgets automatically — the API is public so custom frontends can integrate too.

Submit Page Feedback

POST/v1/projects/{projectId}/feedback/page
NameDescription
pagePath:stringbodyRequired
The page path.
helpful:booleanbodyRequired
Whether the visitor found the page helpful.
comment:stringbody
Optional free-text comment (max 1000 chars).
visitorId:stringbody
Anonymous visitor ID.
bash
curl -X POST https://api.syntext.dev/v1/projects/$PROJECT_ID/feedback/page \
-H "Content-Type: application/json" \
-d '{ "pagePath": "/guides/quickstart", "helpful": true }'

Returns 201 with the created feedback record, and sends a feedback.submitted event to any outbound webhook subscribed to it.

Get Page Feedback Stats

GET/v1/projects/{projectId}/feedback/page
NameDescription
pagePath:stringqueryRequired
The page to fetch stats for.
json
{
"data": { "helpful": "42", "notHelpful": "3", "total": "45" }
}

The counts are sent as numeric strings — convert them with Number().

Submit Section Feedback

POST/v1/projects/{projectId}/feedback/section
NameDescription
pagePath:stringbodyRequired
The page path.
sectionId:stringbodyRequired
The heading anchor ID of the section.
vote:stringbodyRequired
up or down.
comment:stringbody
Optional comment (max 500 chars).
visitorId:stringbody
Anonymous visitor ID.

Get Section Feedback Stats

GET/v1/projects/{projectId}/feedback/section
NameDescription
pagePath:stringqueryRequired
The page to fetch stats for.
json
{
"data": [
{ "sectionId": "installation", "upvotes": "18", "downvotes": "1" },
{ "sectionId": "configuration", "upvotes": "9", "downvotes": "6" }
]
}

As above, the counts are numeric strings.

Errors for the stats endpoints

StatusCodeWhen
400VALIDATIONpagePath is missing (pagePath query param required)
403FORBIDDENThe site is private (password, invite-only or SSO) and the request didn't come through the doc site (Open this from the docs site)

Review feedback in the dashboard

GET/v1/projects/{projectId}/feedback/pages

An authenticated aggregate of page-level feedback: per-page vote counts, the latest comments with their read state, and the helpful rate over a window compared with the window before it.

Note

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

NameDescription
period:stringquery
24h, 7d, 30d or 90d. Takes precedence over days.
days:integerquery
Window for trend, totals and changes, 1–365. Out-of-range values are clamped; anything that is not a number counts as 7.
Default7
bash
curl "https://api.syntext.dev/v1/projects/$PROJECT_ID/feedback/pages?period=30d" \
-H "Authorization: Bearer $SYNTEXT_JWT"
json
{
"data": {
"pages": [
{
"pagePath": "/guides/quickstart",
"helpful": "42",
"notHelpful": "3",
"total": "45",
"comments": "6",
"lastFeedbackAt": "2026-11-08T09:02:11.000Z"
}
],
"recentComments": [
{
"id": "5a2f7c1e-9b3d-4e8a-a6f0-1c2d3e4f5a6b",
"pagePath": "/guides/quickstart",
"helpful": false,
"comment": "The install step assumes Bun is already installed.",
"readAt": null,
"createdAt": "2026-11-08T09:02:11.000Z"
}
],
"trend": [
{ "date": "2026-11-07", "current": 88, "previous": 91 },
{ "date": "2026-11-08", "current": null, "previous": 80 }
],
"totals": { "helpfulRate": 87, "ratings": 214, "comments": 19, "unread": 4 },
"changes": { "helpful": -2, "ratings": 15 }
}
}
NameDescription
data.pages:array
Every page with feedback, most rated first, over all time: helpful, notHelpful, total, comments (ratings that came with a comment) and lastFeedbackAt. The counts are currently sent as numeric strings — convert them with Number().
data.recentComments:array
The 50 newest feedback entries with a comment, over all time. readAt is when the comment was marked read, or null while it is unread.
data.trend:array
One entry per UTC calendar day in the window, oldest first, ending today: current is that day's helpful rate (0–100) and previous the rate on the matching day one window earlier. Either is null on a day with no votes.
data.totals:object
For the window: helpfulRate (0–100, null with no votes), ratings and comments. unread is every comment not yet marked read, over all time.
data.changes:object
helpful (points) and ratings (percent) against the previous window. A key is left out when there is nothing to compare with.

The window covers whole UTC calendar days ending today, so ?days=7 means today and the six days before it. trend, totals and changes are optional: if they cannot be computed, the response has pages and recentComments only.

To clear the unread count, mark comments read. Nothing marks them read automatically.

Feedback with comments also appears in the dashboard under Insights › Feedback and feeds content health scores.

Note

If a visitor is signed in (Bearer token present), feedback is associated with their account; otherwise it's anonymous.

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