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.