> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neariq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Feature Feedback

> Session-authenticated endpoints for usage-triggered feature ratings and admin product health summaries.

Feature feedback endpoints are used by the signed-in dashboard. They are not public API-key endpoints and do not use `X-NearIQ-Key`.

Use them to decide when the app should ask for a lightweight feature rating, record the user's rating or dismissal, and review aggregate feedback in admin.

## Check prompt eligibility

`GET /api/feedback/should-prompt`

Returns whether the current user should see a feedback prompt for one feature. The backend checks usage thresholds, the global cooldown, per-feature rating cooldowns, and dismissal cooldowns.

### Response

```json theme={null}
{
  "shouldPrompt": true,
  "feature": {
    "key": "content_studio",
    "displayName": "Content Studio",
    "question": "How useful was Content Studio?"
  }
}
```

When no prompt is due:

```json theme={null}
{
  "shouldPrompt": false
}
```

## Record usage

`POST /api/feedback/usage`

Records meaningful use of a feature for the signed-in user and active workspace. Use this for dashboard interactions that happen outside a server route.

### Request body

```json theme={null}
{
  "featureKey": "ai_chat",
  "amount": 1
}
```

`amount` defaults to `1`. Valid feature keys are controlled by the app config and include dashboard surfaces such as `content_studio`, `ai_visibility`, `reviews`, `rank_tracker`, `reports`, and `ai_chat`.

## Submit feedback

`POST /api/feedback`

Stores a rating, optional text feedback, or a dismissal. A rating must be between `1` and `5` unless the prompt was dismissed.

### Request body

```json theme={null}
{
  "featureKey": "content_studio",
  "rating": 5,
  "text": "The draft saved me time."
}
```

Dismissal example:

```json theme={null}
{
  "featureKey": "content_studio",
  "dismissed": true
}
```

### Response

```json theme={null}
{
  "success": true
}
```

## Admin summary

`GET /api/admin/feedback`

Admin-only route that returns existing generic feedback plus feature-level aggregates.

### Response shape

```json theme={null}
{
  "features": [
    {
      "key": "content_studio",
      "displayName": "Content Studio",
      "avgRating": 4.7,
      "count": 32,
      "recentTrend": "improving",
      "lowestRated": false
    }
  ],
  "npsScore": 82,
  "totalResponses": 143
}
```

Weekly aggregation refreshes the summary table and labels text sentiment for admin review.