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

# Feedback

> Collect and triage visitor feedback left on a pod's pages.

InstaPods can inject a pinned-comment widget into the HTML your pod serves. Visitors leave notes anchored to a spot on the page; you read and triage them through these endpoints.

The owner endpoints below are authenticated and scoped to the pod's team. The submission endpoint the widget itself uses is public and keyed by the pod's feedback token.

## List Feedback

```
GET /api/pods/{name}/feedback
```

**Query parameters:**

| Name     | Description                                                   |
| -------- | ------------------------------------------------------------- |
| `status` | Only return feedback in this state: `new`, `read`, `resolved` |

**Response: `200 OK`**

```json theme={null}
{
  "feedback": [
    {
      "id": "fb_a1b2c3",
      "pod_name": "my-app",
      "submitter_id": "sub_9f2c",
      "name": "Dana",
      "email": "dana@acme.io",
      "comment": "The pricing table overflows on mobile",
      "page_path": "/pricing",
      "pin_selector": "main > section.pricing > table",
      "pin_x": 0.42,
      "pin_y": 0.13,
      "viewport_w": 390,
      "viewport_h": 844,
      "element_text": "Pro — $29/mo",
      "status": "new",
      "created_at": "2026-08-08T10:00:00Z"
    }
  ],
  "counts": { "new": 1, "read": 0, "resolved": 0 },
  "enabled": true,
  "token": "8f3c...",
  "visibility": "link",
  "share_url": "https://my-app.nbg1-1.instapods.app/?fb=8f3c..."
}
```

`counts` totals every status regardless of the `status` filter. `feedback` is `[]` when nothing has been submitted.

## Update Collection Settings

```
POST /api/pods/{name}/feedback/settings
```

**Request Body:** every field is optional; omitted fields are left unchanged.

```json theme={null}
{
  "enabled": true,
  "visibility": "link",
  "rotate": false
}
```

| Field        | Description                                                                                                                                                                                        |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`    | Turn the widget on or off                                                                                                                                                                          |
| `visibility` | `everyone` — the widget shows for every visitor of the pod URL. `link` — it stays hidden unless the visitor opens the `share_url`, which carries the token. Defaults to `everyone` on first enable |
| `rotate`     | Mint a new share token, invalidating links already handed out                                                                                                                                      |

Enabling re-renders the pod's nginx vhost so injection turns on live, without restarting the pod. If that render fails the pod is rolled back to its previous state, so a pod is never left half-configured.

**Response: `200 OK`**

```json theme={null}
{
  "enabled": true,
  "token": "8f3c...",
  "visibility": "link",
  "share_url": "https://my-app.nbg1-1.instapods.app/?fb=8f3c..."
}
```

**Errors:**

| Code  | Reason                                                                                  |
| ----- | --------------------------------------------------------------------------------------- |
| `400` | `visibility` is not `everyone` or `link`                                                |
| `500` | The pod's vhost could not be re-rendered (e.g. the pod has no IP because it is stopped) |

## Update One Comment

```
PATCH /api/pods/{name}/feedback/{id}
```

**Request Body:**

```json theme={null}
{ "status": "resolved" }
```

Valid statuses: `new`, `read`, `resolved`.

**Response: `200 OK`** — `{"ok": true}`. Returns `404` if the id doesn't belong to that pod.

## Delete One Comment

```
DELETE /api/pods/{name}/feedback/{id}
```

**Response: `200 OK`** — `{"ok": true}`.

## Submit Feedback (public)

Used by the injected widget, not by your own integrations. Keyed by the pod's feedback token — no authentication.

```
POST /api/feedback/{token}
```

```json theme={null}
{
  "submitter_id": "sub_9f2c",
  "name": "Dana",
  "email": "dana@acme.io",
  "comment": "The pricing table overflows on mobile",
  "page_path": "/pricing"
}
```

`comment` is required, plus at least one of `name` or `email`. Returns `404` when the token is unknown or collection is disabled — the two cases are deliberately indistinguishable.

```
GET /api/feedback/{token}/mine?submitter=<submitter_id>
```

Returns only the comments that submitter left. Visibility is private per submitter: a visitor never sees anyone else's feedback, while the pod owner sees all of it through the endpoints above.