Feedback Sessions API

REST API endpoints for managing storefront feedback review rounds.

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`)

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

Response

{
  "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.

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

Response (201)

{
  "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.

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

Response

{
  "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.

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

Response

{
  "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.

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

{
  "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.

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

{
  "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.

PreviousLegal PagesAPI Reference