Cr Review

GitBook CR Review (direct API)

Review documentation change requests against a GitBook space or org entirely through the GitBook REST API (https://api.gitbook.com/v1, hit with curl), so a reviewer never has to leave Claude Code to find what needs review, understand what changed, and respond. This is the reviewer-side companion to cr-create (the authoring side over the same API). The reviewer flow is: discover → understand → comment → decide.

Because every step is a real HTTP call, never fake an output: if a call returns nothing, says nothing changed, or errors, report exactly that.

Auth and the gbapi helper

Every call is a Bearer-authenticated request to https://api.gitbook.com/v1. The token lives in `GITBOOK_TOKEN` in the repo-root .env (create one at https://app.gitbook.com/account/developer). Never print the token; never write it to a tracked file. Define this helper once per session and use it for every call below — it fails loudly on any non-2xx and prints the API's error body (curl --fail-with-body, curl ≥ 7.76 / stock on current macOS):

set -a; [ -f .env ] && . ./.env; set +a          # load GITBOOK_TOKEN
gbapi() {                                          # gbapi METHOD /path [extra curl args…]
  local method="$1" apipath="$2"; shift 2   # NB: not `path` — in zsh that is tied to $PATH
  curl -sS --fail-with-body -X "$method" \
    "https://api.gitbook.com/v1${apipath}" \
    -H "Authorization: Bearer ${GITBOOK_TOKEN}" \
    -H "Content-Type: application/json" "$@"
}

Every response is JSON — pipe it through jq and read whole objects. Never hand-parse by grepping/line-pairing fields — bind the wrong title↔id and every downstream call runs against the wrong space/CR (a confident "0 comments" from a space that isn't the one you meant). If gbapi exits non-zero, surface the printed error — do not report success.

Endpoint map (verified against api.gitbook.com/openapi.json)

<org>, <space>, <cr>, <pageId> are the relevant IDs. Base URL is https://api.gitbook.com/v1; paths are relative to it.

status on a review submission accepts exactly `approved` or `changes-requested` (verified against the API enum ChangeRequestReviewStatus). This skill does not merge a CR (POST …/merge) — merging changes shared state and is out of scope here.

CR-list filters and the authors note

• The CR-list filters (status, creator, space, site, requestedReviewer, contributor, orderBy) are scalar query params and work directly. status takes a single value (draft/open/archived/merged) — for "any state," union client-side. Omitting status returns an empty list rather than everything, so always pass one. Default triage discovery to status=open, but never filter to open when the user asks for the "latest" or "most recent" CR — a space's newest CR is often a draft.
• The comments authors filter does work over the raw API (…/comments?authors=<id>, repeatable). Even so, to split human vs agent you pull all comments and classify on postedBy.id (a filter narrows, it doesn't classify).

API behaviors to watch

• Every endpoint returns JSON. GET /user yields your .id directly — pipe every response through jq.
• The `authors` server-side filter is available (see above).
• Pagination is invisible. List responses return a capped page with no total or next-cursor. Raise limit, and paginate with the response's next.page cursor passed as page= — it is not an integer offset, so page=1 returns HTTP 400. Do this before concluding "not found."

Prerequisites

• `curl` and `jq` on your PATH, and network access to api.gitbook.com.
• `GITBOOK_TOKEN` in the repo-root .env (see "Auth"). Confirm with gbapi GET /user before running actions.
• The scope IDs you want to review: an org ID (org-wide discovery), a space ID (single space), and the CR ID once chosen. GET /orgs and GET /orgs/<org>/spaces give IDs.
• To filter by a person you need their user ID — creator/requestedReviewer take IDs, not names. Resolve a name/email with GET /orgs/<org>/members?search=… first.

Hard rules

• Never invent IDs, URLs, CR subjects, change summaries, comment text, or "success." Run the call and report exactly what the API returns. If gbapi errors, surface the error body. The diff link must be the API's urls.app, not a hand-built URL.
• Always prefer GitBook's own diff over a hand-built one. urls.app opens the diff GitBook itself renders (word-level, syntax-aware, split-view where the org has it enabled) — treat it as the diff of record for the CR. The per-page markdown fetch-and-compare in "Summarizing a CR" exists only to inform a prose summary of what changed — never paste a raw unified / line-by-line diff into chat as a substitute for it.
• Surface the site preview link alongside the diff link, not just urls.app — it lives on the Site object (urls.preview), not on the change request, so it's easy to forget it