Skip to content
Critique
Critique Platform API

Merge gate for agents

Your coding agent writes the PR. Critique returns a machine-readable PASS, WARN, or FAIL with structured findings — over REST, webhooks, or MCP. Host-agnostic merge governance for Cursor, Devin, Codex, or any agent stack on GitHub.

Sign in for API keyMerge Gate API docsAll Developer APIs
MethodPathPurpose
POST/api/v1/reviewsQueue PR review (optional per-run webhook)
GET/api/v1/review-runs/{id}Verdict + findings (?findings=all)
GET/api/v1/passportsChange passport queue
POST/api/v1/webhook-endpointsInstallation lifecycle subscriptions
POST/api/mcpMCP tools for IDE agents (queue_review, get_review_run)
GET/api/v1/openapiOpenAPI contract

Why this is not a coding agent API

Critique does not compete with Cursor or Devin on writing code. The merge gate answers one question: should this PR merge? Separate the agent that writes from the layer that judges — then wire the blockers back into your fix loop.

Any writer agent

Cursor, Codex, Devin, internal bots — Critique reviews the PR they open.

Structured gate

Verdict, risk band, findings[] with file/line — not GitHub comment scraping.

Push or poll

Per-run webhooks on POST /reviews, installation subscriptions, or GET with ?findings=all.

Need a sandbox that writes code? Use the Coding Agent API separately — most teams already have a writer agent and only need the gate.

Agent contract

  • POST /api/v1/reviews — queue review; optional webhook on the request body
  • review.run.completed lifecycle events include findings[] inline
  • GET /api/v1/review-runs/:id?findings=all — full findings for orchestrators (default caps at 5 for chat-sized payloads)
  • checkpoint.gate.evaluated — cheap pre-filter before full review on agent PR floods
  • Scopes: write:reviews, read:reviews, manage:webhooks

Quickstart

Queue → webhook or poll → act on findings.

1. Queue review

curl https://critique.sh/api/v1/reviews \
  -H "Authorization: Bearer crt_..." \
  -H "Content-Type: application/json" \
  -d '{
    "repositoryFullName": "acme/web",
    "pullRequestNumber": 42,
    "headSha": "abc123def4567890abcdef1234567890abcdef12",
    "webhook": {
      "url": "https://example.com/hooks/critique",
      "secret": "replace-with-at-least-32-random-characters"
    }
  }'

2. Fetch full findings

curl "https://critique.sh/api/v1/review-runs/RUN_ID?findings=all" \
  -H "Authorization: Bearer crt_..."

Cookbooks

Copy-paste patterns for CI, Cursor MCP, and agent orchestration loops.

Queue a review and poll for verdict

The core agent loop: POST a PR review, poll GET /review-runs/:id until completed, read verdict + findings.

QuickstartAgents
REVIEW=$(curl -s https://critique.sh/api/v1/reviews \
  -H "Authorization: Bearer $CRITIQUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "repositoryFullName": "acme/web",
    "pullRequestNumber": 42,
    "headSha": "abc123def4567890abcdef1234567890abcdef12"
  }')

RUN_ID=$(echo "$REVIEW" | jq -r '.review.reviewRunId')

until true; do
  BODY=$(curl -s "https://critique.sh/api/v1/review-runs/$RUN_ID?findings=all" \
    -H "Authorization: Bearer $CRITIQUE_API_KEY")
  STATUS=$(echo "$BODY" | jq -r '.reviewRun.status')
  echo "status=$STATUS"
  case "$STATUS" in
    COMPLETED|FAILED)
      echo "$BODY" | jq '{verdict: .reviewRun.verdict, findingsCount: .reviewRun.findingsTotal, findings: .reviewRun.findings}'
      break
      ;;
  esac
  sleep 20
done

Per-run webhook on queue

Pass webhook on POST /reviews for a single callback URL — same pattern as Coding Agent runs, separate from installation subscriptions.

WebhooksCI
curl https://critique.sh/api/v1/reviews \
  -H "Authorization: Bearer $CRITIQUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "repositoryFullName": "acme/web",
    "pullRequestNumber": 42,
    "headSha": "abc123def4567890abcdef1234567890abcdef12",
    "webhook": {
      "url": "https://example.com/hooks/critique-review",
      "secret": "replace-with-at-least-32-random-characters",
      "events": ["review.completed", "review.failed"]
    }
  }'

Installation lifecycle webhook

Subscribe once per GitHub App installation — Critique pushes review.run.completed with structured findings for every PR.

WebhooksPlatform
curl https://critique.sh/api/v1/webhook-endpoints \
  -H "Authorization: Bearer $CRITIQUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "installationId": "YOUR_INSTALLATION_ID",
    "url": "https://example.com/hooks/critique-lifecycle",
    "secret": "replace-with-at-least-32-random-characters",
    "events": [
      "review.run.completed",
      "review.run.failed",
      "checkpoint.gate.evaluated"
    ]
  }'

Checkpoint before full review

Listen for checkpoint.gate.evaluated — cheap trust filter before you queue expensive multi-agent review on agent PR floods.

CheckpointAgents
# Webhook payload (checkpoint.gate.evaluated):
# { "outcome": "pass|warn|block", "mode": "...", "actionTaken": "..." }
#
# Orchestrator pseudocode:
# if outcome == "block": stop agent merge loop
# if outcome == "warn": queue full review via POST /api/v1/reviews
# if outcome == "pass" && policy.requiresReview: queue review anyway

MCP from Cursor or Claude Desktop

Point your MCP client at POST /api/mcp with a crt_ key — queue_review and get_review_run return full findings JSON.

MCPCursor
# MCP server URL
https://critique.sh/api/mcp

# Authorization header
Authorization: Bearer crt_...

# Tools (scoped):
# - queue_review(repositoryFullName, pullRequestNumber, headSha)
# - get_review_run(reviewRunId)  → all findings
# - list_passports(limit?)
# - queue_remedy(reviewRunId)

Writer agent → Critique gate → fix agent

Separate the agent that writes code from the agent that judges it. Critique returns machine-readable blockers for the fix loop.

ArchitectureAgents
# 1) Your coding agent opens a PR (Cursor, Devin, Codex, etc.)
# 2) Orchestrator queues Critique review
curl -s https://critique.sh/api/v1/reviews ... > /tmp/review.json
RUN_ID=$(jq -r '.review.reviewRunId' /tmp/review.json)

# 3) Wait for FAIL/WARN/PASS
# 4) On FAIL, hand findings[] to your fix agent — not the same model that wrote the PR
curl -s "https://critique.sh/api/v1/review-runs/$RUN_ID?findings=all" \
  -H "Authorization: Bearer $CRITIQUE_API_KEY" | jq '.reviewRun.findings'

API keys

Default crt_ keys include review, passport, webhook, and MCP scopes. Same key works across Platform API surfaces.

Create your Cloud Coding Agent API key

Keys use the crt_ prefix with read:builder, write:builder, and write:inference scopes. Sign in to generate a key here — the full secret is shown once.

Sign in to generate a key