API: Checks ​

Check what changed between two versions.

Check a connected GitHub pull request ​

POST /v1/github/pull-request-checks requests a live check using the workspace's GitHub App installation:

{"repository":"acme/shop","pull_request":7}

Requires a key tied to an active workspace member who can run checks. Machine keys are refused. The workspace and actor come from the authenticated key; request fields cannot select another workspace or user. The GitHub installation must be linked to that workspace and grant repository access.

A 200 response contains status (completed, waiting, or error), message, repository, pull_request, head_sha, base_sha, and, when available, check_id, gate_id, outcome, details_url, github_check_id and github_check_url. Inspect status and outcome: HTTP success does not mean the release passed. Waiting for CI saves no gate decision; retry explicitly when CI finishes. Publication errors can include a saved decision link.

This runs the full release gate, saves the decision and publishes the GitHub check. It doesn't post a pull request comment.

Changelog & semver ​

These three endpoints take the same request: commit messages in, a version bump and changelog out.

POST /v1/analyze ​

Returns a version recommendation and a changelog. A successful call also saves the release and fires your outbound notifications.

POST /v1/changelog ​

Returns the changelog only. Use it if you handle versioning separately.

POST /v1/semver ​

Returns the version recommendation only. Use it if you generate changelogs elsewhere.

Request ​

{
  "commits": [
    { "message": "feat: add dark mode toggle", "author": "paul", "timestamp": "2026-05-20T10:00:00Z", "hash": "a1b2c3d" },
    { "message": "fix: resolve null pointer in auth flow", "hash": "b2c3d4e" },
    { "message": "wip", "hash": "c3d4e5f" }
  ],
  "previous_version": "1.4.2",
  "repository": { "url": "https://github.com/org/repo" },
  "options": { "format": "markdown" }
}

Response ​

Entries in breaking to security have message (cleaned and capitalized), and hash, author, timestamp and url when known. Entries in uncategorized have message, hash and reason.

When the commits carry too little detail, the call fails with 422 INSUFFICIENT_SIGNAL.

{
  "status": "success",
  "signal": 0.92,
  "meta": { "commits_received": 3, "commits_used": 2, "commits_ignored": 1, "warnings": [] },
  "version": {
    "previous": "1.4.2",
    "suggested": "1.5.0",
    "bump": "minor",
    "reasoning": "1 new feature added, 1 bug fixed, no breaking changes detected"
  },
  "changelog": {
    "formatted": "## [1.5.0] - 2026-05-20\n### Added\n- Dark mode toggle ([a1b2c3d](https://github.com/org/repo/commit/a1b2c3d))\n...",
    "sections": {
      "breaking": [],
      "added": [{ "message": "Dark mode toggle", "hash": "a1b2c3d", "author": "paul", "timestamp": "2026-05-20T10:00:00Z", "url": "https://github.com/org/repo/commit/a1b2c3d" }],
      "changed": [],
      "fixed": [{ "message": "Resolve null pointer in auth flow", "hash": "b2c3d4e", "url": "https://github.com/org/repo/commit/b2c3d4e" }],
      "deprecated": [],
      "removed": [],
      "security": [],
      "uncategorized": [{ "message": "wip", "hash": "c3d4e5f", "reason": "insufficient signal" }]
    }
  }
}

Validation codes ​

All of these are 400. field names the offending field.

GET /v1/formats ​

Lists the output formats. No API key needed.

{ "formats": ["markdown", "json", "keepachangelog", "slack"] }

Releases & checks ​

A release check reads what changed between two versions and reports evidence-backed findings. See Release Checks & Blast Radius.

POST /v1/checks ​

Checks a release. Send either repository (Bumpkit fetches the diff from GitHub) or diff.

With the regression catchers feature (Beta, flag behavior_checks), each commit can also carry diff, and findings gain commit_sha and commit_subject.

Returns 200 with a check:

Errors: 400 VALIDATION_ERROR (missing base, bad source, neither diff nor repository), 404 REPOSITORY_NOT_FOUND (GitHub has no such repository or refs, or it is private and the GitHub App isn't installed).

GET /v1/checks ​

Lists checks, newest first.

With recorded=true, checks of the same commits are grouped into one release, working-tree previews are left out, and the response also has decisions (check ID to gate outcome).

Returns {"checks": [Check]}.

GET /v1/checks/queue ​

Lists GitHub pull request checks that are queued, running or retrying, plus any whose Bumpkit release gate check failed after retries, most recently updated first.

Returns {"queue": [{"repository", "pull_request", "head_sha", "state", "message", "updated_at"}]}. state is queued, running, retrying or failed; message says what's happening in the words the dashboard uses. pull_request is left out when the event named only a commit.

GET /v1/checks/{id} ​

Returns one check, with server_fetched when it has a gate decision: true when Bumpkit read the diff from your repository, false when your CI sent it. 404 CHECK_NOT_FOUND if it doesn't exist.

GET /v1/checks/{id}/radar.svg ​

Beta, early access. A workspace without access gets 403 FEATURE_EARLY_ACCESS and a link to request it. Flag: blast_radar.

The check's blast radius drawn as an SVG radar: rings are hops from the changed symbol, slices are product areas, and each affected place shows what the gate decided there. Returns image/svg+xml. Limited to 60 per minute per key. 404 CHECK_NOT_FOUND for an unknown check.

GET /v1/history ​

What Bumpkit remembers about a repository's releases.

Returns {"repository", "path", "checks": [Check]}.

GET /v1/history/tree ​

A repository's version tree: every release Bumpkit checked, newest first, with where each one is live. Query repository (required, owner/name); up to the 100 newest checks are read.

Returns repository, environments (what is live now: [{environment, version, sha, deployed_at, current}], production first) and releases, each with name, check_id, previous (the release before it in the tree), base, head, head_sha, commits, checked_at, verdict, gate (the latest gate outcome), deploys (every environment it was deployed to, current when it is still the live one there), incidents ([{id, title, started_at, resolved_at}]) and rollbacks (closed-loop rollback items that undo it).

A redeploy counts: deploy v1.0.0 again after v1.2.0 and v1.0.0 is current again.

GET /v1/features ​

Lists the features that are on for your workspace: {"features": ["release_checks", "release_gate", ...], "early_access": {...}}, where early_access maps each Beta feature you don't have yet to a message with its request link. Clients such as the MCP server use it to offer only tools that work.

POST /v1/findings/{id}/feedback ​

Beta, early access. A workspace without access gets 403 FEATURE_EARLY_ACCESS and a link to request it. Flag: finding_feedback.

Marks a finding real or a false positive.

Returns 204. 404 FINDING_NOT_FOUND if the finding isn't in your workspace.

GET /v1/scorecards ​

Beta, early access. A workspace without access gets 403 FEATURE_EARLY_ACCESS and a link to request it. Flag: agent_scorecards.

How each coding agent's releases fare. Query days: 1 to 365, default 30.

Returns {"since", "days", "agents": [...]}. Each agent has agent, checks, ship, review, blocked, gated, needs_approval, gate_failed, proven_high, lines_changed, ship_rate, top_findings ([{kind, count}]) and committers ([{committer, releases}]).

GET /v1/proven ​

Beta, early access. A workspace without access gets 403 FEATURE_EARLY_ACCESS and a link to request it. Flag: proven_changes.

Which kinds of change, in which part of each repository, ship without problems over the last 90 days. Query repository limits it to one owner/name.

Returns {"window_days", "settle_days", "generated_at", "capped", "repositories": [...]}. Each repository has repository, outcome_source_connected, areas, kinds, classes, backtest and notes. Each class has area, kind, state (proven, earning, paused, excluded or not_enough_signal), label, why, clean, pending, problems, need, problem_rate (left out until a change has settled), authors ([{name, changes}]) and explanation. backtest has days, decided, asked_for_review, would_skip, caused_problems, skipped, caused_by, summary and definition. See Proven changes.

GET /v1/proven/class ​

Beta, early access. A workspace without access gets 403 FEATURE_EARLY_ACCESS and a link to request it. Flag: proven_changes.

One class's changes and problems. Query repository, area and kind, all required.

Returns repository, class, changes ([{number, check_id, shipped_at, shipped_by, merge_commit, status, authors}], with status clean, pending or problem, and shipped_by merge or deploy) and problems ([{number, kind, note, at, reverted_by}]). 404 PROVEN_CLASS_NOT_FOUND if no merged pull request falls in that class.

GET /v1/checks/{id}/confidence ​

Beta, early access. A workspace without access gets 403 FEATURE_EARLY_ACCESS and a link to request it. Flag: confidence_score.

The release's confidence score. Returns check_id, score (0 to 100), failure_probability, note, factors ([{key, label, detail, value}]), teams and scored_at. Until Bumpkit has enough of your release outcomes, score and failure_probability are left out and note says what is needed. 404 CHECK_NOT_FOUND for an unknown check. See Confidence Score & Leadership.

POST /v1/checks/{id}/outcomes ​

Beta, early access. A workspace without access gets 403 FEATURE_EARLY_ACCESS and a link to request it. Flag: confidence_score.

Records what happened after a release, so your confidence scores reflect it. Needs a key tied to a person whose role can make changes; viewers and auditors get 403 FORBIDDEN.

Returns 204. 404 NOT_FOUND for an unknown check, 409 CONFLICT if that outcome is already recorded. The gate records reverts on its own.

Compatibility matrix ​

Beta, early access. A workspace without access gets 403 FEATURE_EARLY_ACCESS and a link to request it. Flag: compatibility_matrix.

See Compatibility matrix.

GET /v1/compatibility ​

Returns {"pairs": [...], "counts": {"compatible", "breaking", "not_checked"}, "method", "generated_at"}. Each pair has key, consumer, consumer_role, consumer_versions, provider, provider_role, provider_repository, provider_versions, verdict, reason, breaks, versions, declared_in, source, synced_at and explanation. Query repository: only pairs this repository declares or provides.

GET /v1/compatibility/pairs/{key} ​

Returns one pair. 404 COMPATIBILITY_PAIR_NOT_FOUND when no declared pair has that key.

GET /v1/compatibility/export ​

Downloads the matrix. Query format: csv or json, required. Query repository: as above. 400 VALIDATION_ERROR for another format.

POST /v1/compatibility/sync ​

Owner or admin. Body {"repository": "owner/name", "policy": "..."}. Reads the compatibility section into the matrix. With the GitHub App on the repository, Bumpkit reads bumpkit.yml from the default branch and ignores policy. Otherwise it uses policy, and the pair's source is client. Returns {"repository", "source", "components", "pairs", "removed"}. A file with no section removes the repository's pairs. 400 COMPATIBILITY_POLICY_NOT_FOUND when there's no file to read, and 400 INVALID_POLICY when the section is invalid. Writes an audit record.

Cross-repo impact ​

Beta, early access. A workspace without access gets 403 FEATURE_EARLY_ACCESS and a link to request it. Flags: cross_repo_impact, dependency_autopilot.

See Cross-Repo Impact. These endpoints need a key tied to a person. With cross_repo_impact on, the gate can also return the rules cross_repo.block_on_consumer_break and cross_repo.require_approval.

GET /v1/service-graph ​

Flag cross_repo_impact. Returns {"repositories": [...]}. Each repository has repository, default_branch, head_sha, truncated, refreshed_at, provides and consumes ([{kind, name, version, path, line, direct}]), and consumers.

POST /v1/service-graph/refresh ​

Flag cross_repo_impact. Owner only. Rebuilds the graph from the workspace's repositories. Returns {"repositories": n}, with error when some repositories failed. 502 UPSTREAM_ERROR when nothing could be read.

GET /v1/autopilot/proposals ​

Flag dependency_autopilot. Lists dependency upgrade proposals, pending and failed first. Query limit: 1 to 200, default 50.

Each proposal has id, repository, ecosystem, name, from, to, priority, breaking, reasons, advisories, edits ([{path, line, old, new, why}]), todos ([{path, line, code, why}]), status, pull_request_url, error, decided_by, decided_at and created_at.

POST /v1/autopilot/scan ​

Flag dependency_autopilot. Owner only. Scans dependencies and creates proposals. Returns {"checked": n, "proposed": n}.

POST /v1/autopilot/proposals/{id}/approve ​

Flag dependency_autopilot. Owner only. Opens the upgrade pull request; Bumpkit never merges it. Returns 200 with the proposal, status opened. 404 NOT_FOUND, 409 CONFLICT if already decided, 502 UPSTREAM_ERROR if the pull request couldn't be opened.

POST /v1/autopilot/proposals/{id}/dismiss ​

Flag dependency_autopilot. Owner only. Returns 204. Same errors as approve.