Pull Requests

All paths under /api/v1/repos/{repo_id}/prs. PRs are numbered per repo.

List / create / get / update

Create body — target_branch defaults to the repo’s default branch:

{
  "title": "Add hello",
  "body": "Introduces hello.txt",
  "source_branch": "feature/hello",
  "target_branch": "main"
}

The PR object carries number, state, source_branch, target_branch, head_sha, author, timestamps, the reviews array, a checks_state rollup for the head commit (unspecified = no checks reported), and — once merged — merged_sha, merged_with, merged_by, merged_at.

Reviews (sha-pinned)

POST …/prs/{number}/reviews

{ "verdict": "approve", "body": "LGTM", "approved_sha": "9f2c41d…" }

• verdict — approve or request_changes (required).
• approved_sha — the head sha the verdict applies to, its freshness stamp. Fetch the PR first and pass its current head_sha; if commits land afterwards the approval no longer matches the head, and a protection rule with dismiss_stale_approvals discards it.

Each review in the PR’s reviews array records reviewer, verdict, body, sha, created_at.

Merge / close

POST …/prs/{number}/merge

{ "method": "squash", "message": "Add hello (#1)", "expected_head_sha": "9f2c41d…" }

• method — merge_commit, fast_forward, or squash (server default when omitted).
• expected_head_sha — optimistic concurrency: the merge fails if the head moved since you looked.
• The merge is refused while the target branch’s protection rule is unsatisfied (approvals, green checks). Conflicts come back as a typed JSON error body.

POST …/prs/{number}/close    # close without merging (empty body)

Both return the updated PR object.

Comments

PR diff

GET …/prs/{number}/diff?stats_only=false

Same shape as the commit-range diff — the PR’s target..head, with per-file patches unless stats_only=true.

See also

• CLI Guide — Branches, PRs & Checks — the same flow from the terminal
• Checks & CI Secrets — the rollup behind checks_state