Reference
Review API
Updated 3 Nov 2026
On this page
For agents
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
- 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.
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
{
"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)
{
"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
{ "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.