A feedback session deploys a review preview of your AI-built store and collects pinned comments from reviewers. Feedback sessions are only available for **AI-built stores**, and only one session can be active at a time.

Session `status` is one of: `created`, `in_progress`, `task_review`, `processing`, `in_review`, `done`, `canceled`, or `interrupted`.

## List Feedback Sessions

```
GET /api/v1/feedback-sessions
```

Returns a paginated list of feedback sessions, newest first. Each item includes the shareable `feedbackUrl`.

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | `number` | 50 | Sessions per page (1-100) |
| `offset` | `number` | 0 | Sessions to skip |
| `status` | `string` | – | Filter by status (e.g. `in_review`, `done`) |

```bash
curl \
  -H "Authorization: Bearer your_api_key" \
  "https://your-store.yns.store/api/v1/feedback-sessions?limit=20"
```

### Response

```json
{
  "data": [
    {
      "id": "0191abc0-1234-7def-8000-000000000001",
      "status": "in_review",
      "feedbackUrl": "https://my-store-preview.yns.store",
      "deploymentUrl": "https://my-store-abc123-preview.vercel.app",
      "errorMessage": null,
      "createdAt": "2024-06-15T10:30:00.000Z",
      "updatedAt": "2024-06-15T11:05:00.000Z"
    }
  ],
  "meta": {
    "count": 1,
    "offset": 0,
    "limit": 50
  }
}
```

---

## Start Feedback Session

```
POST /api/v1/feedback-sessions
```

Creates a feedback round and deploys a review preview in the background. Returns the new session plus a `feedbackUrl` to share with reviewers. No request body is required.

```bash
curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/feedback-sessions
```

### Response (201)

```json
{
  "id": "0191abc0-1234-7def-8000-000000000002",
  "status": "created",
  "feedbackUrl": "https://my-store-preview.yns.store",
  "deploymentUrl": null,
  "errorMessage": null,
  "createdAt": "2024-06-15T12:00:00.000Z",
  "updatedAt": "2024-06-15T12:00:00.000Z"
}
```

| Status | Meaning |
|--------|---------|
| `400` | Store is not AI-built |
| `409` | A feedback session is already in progress |

---

## Get Feedback Session

```
GET /api/v1/feedback-sessions/:id
```

Returns a single session with its status, review `progress`, the shareable `feedbackUrl`, and the deployment preview URL. The `progress` object reports total/resolved comment counts, a fill percentage with a human-readable label, and an estimated completion time.

```bash
curl \
  -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/feedback-sessions/0191abc0-1234-7def-8000-000000000001
```

### Response

```json
{
  "id": "0191abc0-1234-7def-8000-000000000001",
  "status": "in_review",
  "feedbackUrl": "https://my-store-preview.yns.store",
  "deploymentUrl": "https://my-store-abc123-preview.vercel.app",
  "errorMessage": null,
  "createdAt": "2024-06-15T10:30:00.000Z",
  "updatedAt": "2024-06-15T11:05:00.000Z",
  "progress": {
    "total": 4,
    "done": 1,
    "fillPct": 22.5,
    "label": "1/4 resolved",
    "eta": "2024-06-15T11:20:00.000Z"
  }
}
```

A `404` is returned when the session does not exist or belongs to another store.

---

## List Feedback Comments

```
GET /api/v1/feedback-sessions/:id/comments
```

Returns the comments left on the review preview for a session. The reviewer-facing positioning fields (selectors, offsets, pin coordinates) are omitted – the response carries the content, page, resolution status, and any generated task instruction.

```bash
curl \
  -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/feedback-sessions/0191abc0-1234-7def-8000-000000000001/comments
```

### Response

```json
{
  "data": [
    {
      "id": "0191abc0-5678-7def-8000-000000000010",
      "content": "Make the hero heading larger and bold.",
      "pagePath": "/",
      "status": "open",
      "taskInstruction": "Increase the hero heading font size and set font-weight to bold.",
      "createdAt": "2024-06-15T10:45:00.000Z"
    }
  ],
  "meta": {
    "count": 1
  }
}
```

A `404` is returned when the session does not exist or belongs to another store.

---

## Cancel Feedback Session

```
POST /api/v1/feedback-sessions/:id/cancel
```

Cancels a session that is still in the `created` (preparing) phase. Once reviewers can comment, the session must be **finalized** instead – canceling past the preparing phase returns `409`.

```bash
curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/feedback-sessions/0191abc0-1234-7def-8000-000000000002/cancel
```

### Response

```json
{
  "id": "0191abc0-1234-7def-8000-000000000002",
  "status": "canceled",
  "feedbackUrl": "https://my-store-preview.yns.store",
  "deploymentUrl": null,
  "errorMessage": null,
  "createdAt": "2024-06-15T12:00:00.000Z",
  "updatedAt": "2024-06-15T12:01:00.000Z"
}
```

| Status | Meaning |
|--------|---------|
| `404` | Session not found |
| `409` | Session is past the preparing phase (finalize instead) |

---

## Finalize Feedback Session

```
POST /api/v1/feedback-sessions/:id/finalize
```

Closes the review round (status → `done`) and unlocks the builder.

```bash
curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/feedback-sessions/0191abc0-1234-7def-8000-000000000001/finalize
```

### Response

```json
{
  "id": "0191abc0-1234-7def-8000-000000000001",
  "status": "done",
  "feedbackUrl": "https://my-store-preview.yns.store",
  "deploymentUrl": "https://my-store-abc123-preview.vercel.app",
  "errorMessage": null,
  "createdAt": "2024-06-15T10:30:00.000Z",
  "updatedAt": "2024-06-15T12:30:00.000Z"
}
```

A `404` is returned when the session does not exist or belongs to another store.