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

NameInTypeRequiredMeaning
scopequerystringnomine (default), all or sent.
bookquerystringnoShow one book only.
countsquery1noReturn 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

NameInTypeRequiredConstraintsMeaning
itemIdpathstringyesteam book you can readThe book.
pagebodyintegerone of page or chapter1 or moreThe chapter page.
chapterbodystringone of page or chapterchapter slugThe chapter.
textbodystringyesone or more pages, each starting with its own # heading, each up to 20,000 bytesThe new text of the whole chapter. Adding the fix replaces the chapter with these pages, and the pages after it move up.
reasonbodystringyes1 to 1,000 charactersWhy the chapter needs the change.
fixesbodystring arraysee meaningup to 20 open request ids on this bookReader 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

StatusCodeMeaning
400FIXES_UNDECIDEDfixes 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

NameInTypeRequiredMeaning
textbodystringnoYour 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.
expectedVersionbodyintegernoThe book version that you based your text on.
notebodystringnoA 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

StatusCodeMeaning
409SUGGESTION_STALEThe chapter changed after the fix was written. The body has currentText, proposedText, currentVersion and baseVersion.
409ALREADY_DECIDEDSomeone already decided the fix. The body has status.
409CHAPTER_GONEThe chapter no longer exists.
403OWN_SUGGESTIONYou cannot add your own fix.
403NOT_PROPOSEROnly the person who sent the fix can withdraw it.
403CARETAKER_REQUIREDYou do not look after this chapter. The body names the people who do.
403HISTORY_DENIEDYou cannot read the history of this book.

CLI equivalent: trove items: review.

    Review API — Trove docs