# List reviews

`GET /reviews`

Returns reviews for one shop (`shop_id`) or all your shops, sorted by
the date the review entered Dokaa, descending. Includes both external platform reviews
(Google, TripAdvisor, Deliveroo, Uber Eats, TheFork) and internal Dokaa
feedback (`platform: dokaa`, satisfaction forms rated 1 to 5; NPS
surveys rated on 10 are excluded from this endpoint).

Requires the `reviews:read` scope.

**Returns** a `data` array of up to `limit` reviews and a
`pagination` object. Fetch the next page by passing
`pagination.next_cursor` back as `cursor`, until `has_more` is
`false`. `data` is empty when nothing matches the filters.

Replies sent automatically by Dokaa are flagged with
`reply.is_auto_reply`; a review without a reply has `reply: null`. For
counts, averages and distributions computed server-side, prefer
`/analytics/reviews` over paginating this endpoint.

## Example request

```bash
curl "https://api.dokaa.app/v1/reviews" \
  -H "Authorization: Bearer dk_live_..."
```

## Query parameters

- `shop_id` (string) – Restrict to a single shop (omit to query all your shops)
- `platform` (string) (one of: google, deliveroo, ubereats, tripadvisor, fork, dokaa) – Filter by review platform
- `from` (string) (format: date) – Only reviews posted on or after this date
- `to` (string) (format: date) – Only reviews posted on or before this date
- `rating` (integer) (min: 1; max: 5) – Filter by exact rating
- `cursor` (string) – Opaque cursor from the previous response's `pagination.next_cursor`
- `limit` (integer) (default: 25; min: 1; max: 100) – Number of items per page

## Responses

### 200 – Paginated list of reviews

```json
{
  "data": [
    {
      "id": "66a1b2c3d4e5f6a7b8c9d0e1",
      "shop_id": "64f1a2b3c4d5e6f7a8b9c0d1",
      "platform": "google",
      "rating": 5,
      "comment": "Super accueil, pizzas excellentes !",
      "translated_comment": null,
      "date": "2026-07-28T18:32:00Z",
      "reply": {
        "comment": "Merci beaucoup pour votre retour !",
        "date": "2026-07-29T09:15:00Z",
        "is_auto_reply": true
      },
      "semantic_tags": [
        "accueil",
        "qualite-produits"
      ]
    }
  ],
  "pagination": {
    "next_cursor": "eyJkIjoiMjAyNi0wNy0yOFQxODozMjowMFoifQ",
    "has_more": true
  }
}
```

### 401 – Missing, invalid, or revoked API key

### 403 – The API key does not grant access to this resource

### 422 – Invalid request parameters

Errors are `application/problem+json` (RFC 9457) with `type`, `title`, `status` and `detail` fields.