---
title: Feedback API
description: "Collect page and section-level feedback from doc site visitors."
---

# Feedback API

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

<Endpoint method="POST" path="/v1/projects/{projectId}/feedback/page" />

<ParamField body="pagePath" type="string" required>The page path.</ParamField>
<ParamField body="helpful" type="boolean" required>Whether the visitor found the page helpful.</ParamField>
<ParamField body="comment" type="string">Optional free-text comment (max 1000 chars).</ParamField>
<ParamField body="visitorId" type="string">Anonymous visitor ID.</ParamField>

```bash
curl -X POST https://api.syntext.dev/v1/projects/prj_abc123/feedback/page \
  -H "Content-Type: application/json" \
  -d '{ "pagePath": "/guides/quickstart", "helpful": true }'
```

Returns `201` with the created feedback record.

## Get Page Feedback Stats

<Endpoint method="GET" path="/v1/projects/{projectId}/feedback/page" />

<ParamField query="pagePath" type="string" required>The page to fetch stats for.</ParamField>

```json
{
  "data": { "helpful": 42, "notHelpful": 3, "total": 45 }
}
```

## Submit Section Feedback

<Endpoint method="POST" path="/v1/projects/{projectId}/feedback/section" />

<ParamField body="pagePath" type="string" required>The page path.</ParamField>
<ParamField body="sectionId" type="string" required>The heading anchor ID of the section.</ParamField>
<ParamField body="vote" type="string" required>`up` or `down`.</ParamField>
<ParamField body="comment" type="string">Optional comment (max 500 chars).</ParamField>

## Get Section Feedback Stats

<Endpoint method="GET" path="/v1/projects/{projectId}/feedback/section" />

<ParamField query="pagePath" type="string" required>The page to fetch stats for.</ParamField>

```json
{
  "data": [
    { "sectionId": "installation", "upvotes": 18, "downvotes": 1 },
    { "sectionId": "configuration", "upvotes": 9, "downvotes": 6 }
  ]
}
```

## Review Feedback in the Dashboard

An authenticated aggregate across all pages is available at:

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

Feedback with comments also appears in the dashboard and feeds [content health scores](/api-reference/analytics/content-health).

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