Feedback API
Collect page and section-level feedback from doc site visitors.
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
/v1/projects/{projectId}/feedback/pagepagePathhelpfulcommentvisitorIdReturns 201 with the created feedback record, and sends a feedback.submitted event to any outbound webhook subscribed to it.
Get Page Feedback Stats
/v1/projects/{projectId}/feedback/pagepagePathThe counts are sent as numeric strings — convert them with Number().
Submit Section Feedback
/v1/projects/{projectId}/feedback/sectionpagePathsectionIdvoteup or down.commentvisitorIdGet Section Feedback Stats
/v1/projects/{projectId}/feedback/sectionpagePathAs above, the counts are numeric strings.
Errors for the stats endpoints
| Status | Code | When |
|---|---|---|
| 400 | VALIDATION | pagePath is missing (pagePath query param required) |
| 403 | FORBIDDEN | The 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
/v1/projects/{projectId}/feedback/pagesAn 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.
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.
period24h, 7d, 30d or 90d. Takes precedence over days.daystrend, totals and changes, 1–365. Out-of-range values are clamped; anything that is not a number counts as 7.7data.pageshelpful, notHelpful, total, comments (ratings that came with a comment) and lastFeedbackAt. The counts are currently sent as numeric strings — convert them with Number().data.recentCommentsreadAt is when the comment was marked read, or null while it is unread.data.trendcurrent 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.totalshelpfulRate (0–100, null with no votes), ratings and comments. unread is every comment not yet marked read, over all time.data.changeshelpful (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.
If a visitor is signed in (Bearer token present), feedback is associated with their account; otherwise it's anonymous.