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

# List Reviews

> List the reviews the caller can read, newest first.

> [!NOTE]
>
> **Preview.** This endpoint is available to organisations in the Wordsmith MCP pilot. Other organisations receive `403 mcp_not_enabled`. See the [preview overview](/preview).

Returns a page of reviews, newest first, each in the shape [Get Review](/api-reference/reviews/get-review) returns. It lists the reviews the Wordsmith app's review list shows you, started in the app as well as through the API.

The filters apply to each page after it is read, so a page can hold fewer than `limit` reviews, or none, and still have a `cursor` to the rest. Keep paging until `cursor` is `null`.

## Authentication

Requires an API key, or an OAuth token with `reviews:read`.

## Query parameters

**type** `string`

Only reviews of this type: `playbook`, `instructions` or `counterparty_edits`.

**status** `string`

Only reviews in this status: `queued`, `running`, `completed`, `failed` or `cancelled`.

**file\_id** `string`

Only reviews whose `file_ids` include this file. A review lists its own copies of the files it reviewed, so pass an id from a review, not the id you started it with.

**query** `string`

Search the reviews as the Wordsmith app's review search does, up to 200 characters. It matches the reviewed files' names and content, not the review's `name`.

**cursor** `string`

The `cursor` from the previous page. Omit it for the first page.

**limit** `integer` (default: 20)

Reviews to read per page, from `1` to `100`.

## Response

Returns `200` with `{"items": [...], "cursor": "..."}`. `cursor` is `null` on the last page.

```bash cURL theme={null}
curl "https://api.wordsmith.ai/api/v1/reviews?type=playbook&status=completed&limit=2" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"
```

```json Response theme={null}
{
  "items": [
    {
      "id": "5f0c9a12-8e3b-4d71-a6c4-0b2e9f7d3c58",
      "name": "Customer: NDA Review",
      "type": "playbook",
      "status": "completed",
      "file_ids": ["4d2e6f81-3a5b-4c7d-9e0f-1a2b3c4d5e6f"],
      "playbook_id": "2c4b8f90-5d1e-4a37-b6e2-c8f0a3d71e45",
      "instructions": null,
      "party": "Customer",
      "findings": { "total": 32, "issues": 7, "high": 2, "medium": 3, "low": 2 },
      "redline_file_id": "c71e2a90-4b3d-4f68-9e15-8d0a6b2f3c47",
      "operation_id": "3b8e0f1c-6a2d-4e57-9c1b-2f7d8a4e6b90",
      "url": "https://app.wordsmith.ai/reviews/5f0c9a12-8e3b-4d71-a6c4-0b2e9f7d3c58",
      "created_at": "2026-10-13T09:00:00Z",
      "updated_at": "2026-10-13T09:03:41Z"
    },
    {
      "id": "03bfe50d-2546-4cd1-b82c-2f891b4d946f",
      "name": "NDA Review",
      "type": "playbook",
      "status": "completed",
      "file_ids": ["206fef15-de59-4234-a43a-abde4d527e6e"],
      "playbook_id": "2c4b8f90-5d1e-4a37-b6e2-c8f0a3d71e45",
      "instructions": null,
      "party": null,
      "findings": { "total": 32, "issues": 3, "high": 0, "medium": 1, "low": 2 },
      "redline_file_id": null,
      "operation_id": null,
      "url": "https://app.wordsmith.ai/reviews/03bfe50d-2546-4cd1-b82c-2f891b4d946f",
      "created_at": "2026-10-13T08:12:05Z",
      "updated_at": "2026-10-13T08:15:30Z"
    }
  ],
  "cursor": "eyJwYWdlIjogIntcInBrXCI6IC4uLn0ifQ=="
}
```

## Errors

| Status | `error_code` | When |
| - | - | - |
| 400 | `bad_request` | A filter value is not allowed, `limit` is outside `1`–`100`, or `cursor` is not one this endpoint returned. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.