---
title: "Review API"
description: "Use when you list the fixes and reader requests that wait on you in team books, send a fix for a chapter you cannot edit, add a fix or say why it is not added, or read a version diff over HTTP."
url: https://docs.heytrove.ai/reference/api/review
updated: 2026-11-03
---

# Review API

> Load this page when: you need to send, read, add or turn down a suggested fix over HTTP, or list what waits on a person in team books

## For agents

- GET /review lists what waits on the caller. Use scope=all for read-only items and scope=sent for the caller's own fixes.
- POST /items/{itemId}/suggestions sends a fix for one chapter. It answers 201.
- Add a fix with POST /suggestions/{id}/approve. Say why it is not added with POST /suggestions/{id}/decline. On SUGGESTION_STALE, redo the fix on the current text and send expectedVersion with it.
- GET /items/{itemId}/versions/{version}/diff shows what one version changed.

These routes are for team books. A fix is a new text for one chapter, sent by a person who cannot edit that chapter. All routes need `Authorization: Bearer trove_your_key`. See [trove items: review](https://docs.heytrove.ai/reference/cli/items-review.md).

## List what waits on you

`GET https://heytrove.ai/api/v1/review`

**Parameters**

| Name | In | Type | Required | Meaning |
| --- | --- | --- | --- | --- |
| `scope` | query | string | no | `mine` (default), `all` or `sent`. |
| `book` | query | string | no | Show one book only. |
| `counts` | query | `1` | no | Return only the counts. The call always answers 200. On an error, all counts are zero. |

With `mine` and `all`, the call marks the caller's new items as seen: without `book`, every new item; with `book`, only the items of that book. With `sent`, it does not.

**Response**

```json
{
  "scope": "mine",
  "hasTab": true,
  "rows": [
    {
      "kind": "suggestion",
      "id": "cmfix01",
      "book": { "itemId": "cmabc123", "title": "Team Handbook", "teamName": null },
      "chapter": { "slug": "deploying-to-production", "title": "Deploying to Production", "pageNum": 3 },
      "reason": "Add the rollback command we use",
      "proposer": { "id": "cmu01", "name": "Noa Helper" },
      "stale": false,
      "mine": true,
      "canAct": true,
      "waitingOn": []
    }
  ],
  "counts": { "forMe": 4, "all": 5, "tab": 3 }
}
```

A row with `kind` `request` has `gapIds`, `subcategory`, `readerCount` and `claimedBy`. With `scope=sent`, the reply has `rows` of `kind` `sent`, each with `statusText` such as `Waiting on Dana` or `Added by Dana`. With `counts=1`, the reply is `{ "waiting", "requests", "suggestions", "oldestDays", "new" }`.

## Send a fix

`POST https://heytrove.ai/api/v1/items/{itemId}/suggestions`

**Parameters**

| Name | In | Type | Required | Constraints | Meaning |
| --- | --- | --- | --- | --- | --- |
| `itemId` | path | string | yes | team book you can read | The book. |
| `page` | body | integer | one of `page` or `chapter` | 1 or more | The chapter page. |
| `chapter` | body | string | one of `page` or `chapter` | chapter slug | The chapter. |
| `text` | body | string | yes | one or more pages, each starting with its own `# ` heading, each up to 20,000 bytes | The new text of the whole chapter. Adding the fix replaces the chapter with these pages, and the pages after it move up. |
| `reason` | body | string | yes | 1 to 1,000 characters | Why the chapter needs the change. |
| `fixes` | body | string array | see meaning | up to 20 open request ids on this book | Reader requests that the fix answers. Send `[]` when it answers none. If you leave `fixes` out and the chapter has open requests you can see, nothing is sent and the call fails with `FIXES_UNDECIDED`. |

**Errors**

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `FIXES_UNDECIDED` | `fixes` was left out and the chapter has open requests you can see. Nothing was sent. The body has `openRequests`, a list of up to 10 objects with `gapId`, `subcategory` and `yours`. Send the fix again with the ids it answers, or with `fixes: []`. |

**Response** (201)

```json
{
  "id": "cmfix01",
  "status": "OPEN",
  "book": { "itemId": "cmabc123", "title": "Team Handbook" },
  "chapter": { "slug": "deploying-to-production", "title": "Deploying to Production", "pageNum": 3 },
  "owner": { "id": "cmu02", "name": "Dana" },
  "sentTo": [{ "id": "cmu02", "name": "Dana" }],
  "linkedRequests": 1,
  "line": "I sent Dana a fix for \"Deploying to Production\" in \"Team Handbook\"."
}
```

## Show a fix

`GET https://heytrove.ai/api/v1/suggestions/{id}`

Returns the state, the reason, the current text, the proposed text, a `diff`, the linked requests and a `viewer` object with `canDecide` and `canWithdraw`.

## Add a fix

`POST https://heytrove.ai/api/v1/suggestions/{id}/approve`

| Name | In | Type | Required | Meaning |
| --- | --- | --- | --- | --- |
| `text` | body | string | no | Your own text for the chapter, one page or several. It skips the stale check. The reply has `pagesWritten` and `pageCount`. A heading that matches a chapter with its own caretakers is refused with `HEADING_IN_USE`. |
| `expectedVersion` | body | integer | no | The book version that you based your text on. |
| `note` | body | string | no | A note for the person who sent the fix. Up to 1,000 characters. |

**Response**

```json
{ "id": "cmfix01", "status": "APPROVED", "statusText": "Added by Dana", "version": 4, "pageNum": 3, "fulfilledRequests": 1 }
```

## Say why a fix is not added

`POST https://heytrove.ai/api/v1/suggestions/{id}/decline`

Body: `{ "reason": "text" }`. The reason is required and up to 1,000 characters. The person who sent the fix sees it.

## Withdraw a fix

`POST https://heytrove.ai/api/v1/suggestions/{id}/withdraw`

Body: `{}`. Only the person who sent an open fix can withdraw it.

## Show what one version changed

`GET https://heytrove.ai/api/v1/items/{itemId}/versions/{version}/diff`

Returns `{ id, version, previousVersion, chapters, diff, note }`. The `diff` is null, with a `note`, when the text of a version is not stored. People who look after chapters only see the changes in their own chapters.

## Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 409 | `SUGGESTION_STALE` | The chapter changed after the fix was written. The body has `currentText`, `proposedText`, `currentVersion` and `baseVersion`. |
| 409 | `ALREADY_DECIDED` | Someone already decided the fix. The body has `status`. |
| 409 | `CHAPTER_GONE` | The chapter no longer exists. |
| 403 | `OWN_SUGGESTION` | You cannot add your own fix. |
| 403 | `NOT_PROPOSER` | Only the person who sent the fix can withdraw it. |
| 403 | `CARETAKER_REQUIRED` | You do not look after this chapter. The body names the people who do. |
| 403 | `HISTORY_DENIED` | You cannot read the history of this book. |

**CLI equivalent**: [trove items: review](https://docs.heytrove.ai/reference/cli/items-review.md).
