List Reviews

List the reviews the caller can read, newest first.

GET /api/v1/reviews

cURL

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

Response

{
  "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=="
}

Preview. This endpoint is available to organisations in the Wordsmith MCP pilot. Other organisations receive 403 mcp_not_enabled. See the preview overview.

Returns a page of reviews, newest first, each in the shape 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.

cURL

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

Response

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