The Merge Gate API: Why Agent Teams Need a Judge That Is Not the Writer
v6.1 does not invent a new product — it names and hardens the contract agent orchestrators were already missing: queue review, receive PASS / WARN / FAIL with structured findings, and wire a fix loop without scraping GitHub comments.
Merge Gate API
Writer proposes · Critique judges · orchestrator decides
critique.sh
v6.1 packages what v6.0 already shipped — same crt_ keys and /api/v1 routes — into one contract: POST /api/v1/reviews, GET /api/v1/review-runs/:id?findings=all, signed webhooks, and MCP tools scoped like REST. Product page: /merge-gate-api. Full reference: /docs/platform/merge-gate-api.
The bottleneck moved — again
For three years the industry optimized generation: autocomplete, chat, agents, sandboxes, draft PRs. That work succeeded faster than most teams planned for. PR volume did not stay flat while output rose — it scaled with the agents. The constraint relocated to the merge boundary: who reads the diff, who records evidence, who says no when the branch is green in CI but wrong for the product.
Human reviewers feel this first. Senior engineers who used to see four pull requests a week now see twenty, many opened by tools they also use to ship faster. Line-by-line review becomes theater when the diff is three percent of the blast radius. The naive fix — “just ask the same agent to review its own PR” — recreates the oldest failure mode in engineering: confirmation bias at machine speed.
Critique exists on the other side of that line. Not as another coding host. Not as a comment bot that paraphrases the diff. As change control: passports, checkpoint gates, merge policy, evidence runs, and a verdict a release train can trust. v6.1 names the programmatic surface for that job the Merge Gate API — because “Platform API v1” was accurate for integrators and too vague for the agent supervisor wiring CI at 2 a.m.
Writer, judge, fixer — three jobs, not one
The strongest agent stacks treat implementation, judgment, and repair as separate steps with separate budgets and separate failure modes.
| Role | Success metric | Typical failure |
|---|---|---|
| Writer (coding agent) | Ship the requested change; make CI green. | Plausible but incomplete code; missed edge cases; auth drift. |
| Judge (merge gate) | Evidence-backed PASS / WARN / FAIL before merge. | Missed blast radius; weak findings; un-auditable approve. |
| Fixer (Remedy / BYOA) | Resolve localized findings with verification. | Over-edit; scope creep; unbounded agent loops. |
Critique already shipped the Coding Agent API for teams that need a sandboxed writer (POST /api/v1/coding-agent/runs). v6.1 completes the story for teams that bring their own writer — Cursor, Devin, Codex, internal bots — and need a judge they can call over HTTP. Same installation. Same credits for review depth. Different contract: you are not buying patch output; you are buying merge permission with proof.
What v6.1 actually ships (packaging, not reinvention)
Honesty matters here. `POST /api/v1/reviews` landed in v6.0. Scoped MCP tools and installation lifecycle webhooks landed in v6.0. v6.1 is the release where we stop making orchestrators discover that by accident and start treating agent merge loops as a first-class integration story.
`?findings=all` on review-run reads — no five-finding cap for automation keys. `findings[]` on `review.run.completed` lifecycle payloads so blockers arrive in the webhook. Per-run `webhook` on queue requests (Critique-Review-Webhook/1.0) for single CI jobs. Structured finding objects — severity, confidence, file path, line range, fingerprint — designed for fix agents, not dashboard cards.
GET /api/v1/review-runs/:id?findings=all[/merge-gate-api](/merge-gate-api) product page with cookbooks. [/docs/platform/merge-gate-api](/docs/platform/merge-gate-api) operator reference. Cross-links from Checkpoint, change control, connections, and `/api` hub so “how do I gate agent PRs?” has one canonical answer instead of three partial ones.
Writer → gate → fix loopNothing here replaces the Change Passport, Checkpoint firewall, or merge policy evaluator. The merge gate feeds them. Automatic GitHub reviews still create passports and check runs. Programmatic queueing is how your orchestrator participates in the same evidence graph — not a shadow path with different rules.
Benefits — if you supervise agents for a living
- 1Stop polling HTML and comment threadsSubscribe to `review.run.completed` on an installation endpoint, or pass `webhook` on `POST /api/v1/reviews`. Verdict, risk band, head SHA, and `findings[]` arrive as JSON — signed, filterable, log-friendly.
- 2Close the fix loop without human copy-pasteFeed `findings[]` to your fix agent (Remedy, BYOA, or internal tool). Re-queue on the new `headSha`. Repeat until PASS or your policy cap. The orchestrator owns the loop; Critique owns the judgment.
- 3Spend review credits deliberatelyRun Checkpoint first on agent PR floods (
checkpoint.gate.evaluated). Block cheaply. Queue `POST /api/v1/reviews` only when the PR deserves sandbox depth — not on every draft typo. - 4Keep audit and compliance alignedReview runs link to Change Passports. Export signed bundles with `GET /api/v1/passports/:id/export`. The merge gate is how agents enter the same record humans see in the dashboard — not a side channel.
- 5Use the IDE path when the supervisor is localMCP `queue_review` and `get_review_run` (all findings) let Cursor or Claude Desktop participate without bespoke REST glue — same scopes as `crt_` keys on REST.
The agent merge loop — end to end
Notice where humans sit: not on every finding parse, but on policy — when WARN is acceptable, when override is recorded, when a passport export goes to compliance. The API automates judgment delivery; your org still owns judgment authority.
Structured findings — why prose is not enough
GitHub check summaries were built for humans scanning a paragraph. Agents need records: severity, specialist lane, confidence, file coordinates, stable fingerprint for memory and dedupe. That is what `StructuredReviewFinding` encodes in API and webhook payloads.
Queue with a per-run webhook
Replace crt_… and URLs. Secret must be at least 32 characters. Events: review.completed, review.failed, review.queued.
curl https://critique.sh/api/v1/reviews \
-H "Authorization: Bearer crt_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"repositoryFullName": "acme/web",
"pullRequestNumber": 42,
"headSha": "abc123def4567890abcdef1234567890abcdef12",
"webhook": {
"url": "https://orchestrator.example/hooks/critique",
"secret": "replace-with-at-least-32-random-characters",
"events": ["review.completed", "review.failed"]
}
}'Default `GET /api/v1/review-runs/:id` responses still cap at five findings — sized for chat and quick polls. Automation should use `?findings=all` or read `findings[]` from the completion webhook. `findingsTotal` and `findingsTruncated` tell you when you are looking at a partial slice.
Two webhook channels — on purpose
Coding Agent runs taught us that one webhook shape does not fit every buyer. Installation lifecycle subscriptions (Critique-Lifecycle-Webhook/1.0) fire for all reviews on an installation — ideal for platform teams wiring Slack, deploy gates, and passport backfill. Per-run webhooks on queue requests (Critique-Review-Webhook/1.0) mirror a single CI job — ideal when only that pipeline cares about that SHA. They can fire in parallel for the same run; your receiver should dedupe on `reviewRunId`.
v1 delivery is single-attempt with an eight-second timeout and audit rows. Treat webhooks as latency savers, not guaranteed delivery — poll `GET /api/v1/review-runs/:id` when your receiver misses an event until automatic retries ship.
Why this is not “just use Bugbot”
IDE-embedded reviewers are valuable for local feedback while the author types. Merge gate infrastructure is valuable for org-wide discipline: merge policy checks, passport history, checkpoint blocks, incident learnings promoted into rules, signed exports for auditors, and a verdict that branch protection can reference. The Merge Gate API is how external orchestrators — the supervisor above the IDE — participate in that graph without pretending to be a human clicking refresh on a checks page.
If you only need a one-off “scan this diff” call, Inference API or a skill file may suffice. If you need durable merge state tied to GitHub checks, passports, and remediation handoffs, you need the review pipeline — and v6.1 gives it a name agents can integrate against.
Where Critique sits in the agent infrastructure wave
2026 is the year agent platforms stop apologizing for existing. Hosts compete on sandboxes, models, and git UX. That is necessary infrastructure — and it is not where Critique chooses to fight. Our bet unchanged since v4: the scarce resource is trusted merge decisions at scale. The Merge Gate API is that bet expressed as HTTP — so the team running fifty agent workers does not need fifty bespoke scrapers of the same check run.
We wrote the longer arc on writer/judge separation in Stop Letting the Agent That Wrote the Code Review It Too. v4’s passport essay is still the control-plane framing: Critique v4 — The AI Change Control Platform. This post is the automation appendix: what to call, what to POST, and what you get back when the writer is not the judge.
FAQ
Judge PRs programmatically
Queue reviews, poll verdicts, subscribe to webhooks, read structured findings — writer/judge separation for agent stacks.
REST + MCP reference
Full endpoint tables, webhook schemas, Checkpoint-first orchestration, error codes, and security notes.
When you need a writer
OpenCode in E2B — patches and draft PRs. Pair with the merge gate when the same stack must both implement and prove.
Wire your orchestrator to a judge that is not the writer.
Create a crt_ key with write:reviews, read the merge gate docs, and queue your first agent PR through POST /api/v1/reviews — or open the product page for copy-paste cookbooks.
Open Merge Gate API →