Developers

Program against the review queue without guessing routes.

Use these endpoints to inspect pending deploy requests, approve or reject them, unblock merges, and fetch the signed receipt your downstream systems can verify.

Quickstart Jump to curl examples

Authentication

API key

Use Authorization: Bearer pp_key_... for server-to-server reads and receipt fetches.

Dashboard session

Browser-based approve, reject, merge, rerun, and branch update calls can rely on the authenticated app session cookie.

GitHub App token

Automation that acts on repository state should use an installation token scoped to review and merge permissions.

Endpoints

Each route below includes the expected method, path, example request or response schema, and the status codes clients should handle.

GET/api/reviews

List deploy requests

Returns the current deploy review queue with status, author, branch, and summary metadata.

#list-review-requests

Authentication

Accepts API key or authenticated dashboard session.

Request Body

No request body.

Status Codes

200: Queue returned successfully.
401: Missing or invalid credentials.
429: Too many polling requests.

Response Body

{  "requests": [    {      "id": "req_7f3d9a2c",      "status": "pending",      "repo": "permission-protocol/site",      "prNumber": 214,      "prTitle": "Harden production deploy gate",      "author": "marco",      "branch": "marco/deploy-gate-hardening",      "summary": "Touches receipt verification and production policy enforcement."    }  ],  "generatedAt": "2025-01-18T18:42:11.224Z"}

GET/api/review/[id]

Get request details

Fetches a single deploy request with the review metadata needed to render the approval screen.

#get-review-request

Authentication

Accepts API key, session cookie, or GitHub App token.

Request Body

No request body.

Status Codes

200: Request found.
404: Unknown request id.
429: Request detail polling too frequently.

Response Body

{  "id": "req_7f3d9a2c",  "status": "pending",  "repo": "permission-protocol/site",  "prNumber": 214,  "prTitle": "Harden production deploy gate",  "author": "marco",  "summary": "Touches receipt verification and production policy enforcement.",  "filesChanged": 7,  "riskLevel": "high"}

GET/api/review/[id]/summary

Get AI summary

Returns the generated natural-language summary used in the reviewer dashboard.

#get-review-summary

Authentication

Accepts API key or authenticated session.

Request Body

No request body.

Status Codes

200: Summary available.
404: Request or summary not found.
503: Summary generation still pending.

Response Body

{  "id": "req_7f3d9a2c",  "summary": "This change modifies receipt verification, blocks bypass paths, and adds stricter audit metadata.",  "generatedAt": "2025-01-18T18:41:05.908Z"}

POST/api/review/[id]/approve

Approve a deploy request

Authorizes the action, records the approver, and unblocks downstream merge or deploy steps.

#approve-review-request

Authentication

Requires an authenticated human session or GitHub App token acting on behalf of an approver.

Request Body

{  "comment": "Approved for the production hotfix window.",  "reason": "risk-reviewed",  "metadata": {    "environment": "production"  }}

Status Codes

200: Request approved and receipt issued.
409: Request already decided.
422: Approval payload failed validation.

Response Body

{  "ok": true,  "status": "approved",  "receiptId": "pp_r_8f91c2",  "approvedAt": "2025-01-18T18:44:02.204Z"}

POST/api/review/[id]/reject

Reject a deploy request

Denies the request and keeps the protected action blocked.

#reject-review-request

Authentication

Requires an authenticated human session or GitHub App token with review permissions.

Request Body

{  "comment": "Blocking until rollback testing finishes.",  "reason": "missing-verification"}

Status Codes

200: Request denied.
409: Request already approved or denied.
422: Reason or comment is invalid.

Response Body

{  "ok": true,  "status": "denied",  "rejectedAt": "2025-01-18T18:46:55.921Z"}

POST/api/review/[id]/merge

Merge after approval

Executes the merge step for an approved request once all required checks have passed.

#merge-review-request

Authentication

Requires dashboard session or GitHub App token with merge permission.

Request Body

{  "expectedHeadSha": "a8fd11d9e9ab0f0d3a7cb3f241d2a7144855f2d7"}

Status Codes

200: Merge completed.
409: Approval missing or head SHA changed.
424: Required checks have not completed.

Response Body

{  "ok": true,  "status": "merged",  "mergedAt": "2025-01-18T18:48:10.501Z"}

POST/api/review/[id]/rerun

Re-run CI checks

Triggers a fresh CI run for a blocked review request without changing its approval state.

#rerun-review-request

Authentication

Requires dashboard session or GitHub App token with workflow control permissions.

Request Body

{  "workflow": "deploy-gate",  "reason": "flake-retry"}

Status Codes

200: Rerun queued.
404: Unknown request id.
409: Request can no longer be rerun.

Response Body

{  "ok": true,  "status": "pending",  "rerunQueuedAt": "2025-01-18T18:49:31.102Z"}

POST/api/review/[id]/update-branch

Update PR branch

Brings the review branch up to date with the base branch before approval or merge.

#update-review-branch

Authentication

Requires dashboard session or GitHub App token with repository write permission.

Request Body

{  "baseRef": "main"}

Status Codes

200: Branch update completed.
409: Merge conflict or branch protection failure.
422: Base branch is invalid.

Response Body

{  "ok": true,  "status": "pending",  "headSha": "d1d26d8f6f7c708ed807b0c76250ed2e779a5e5e"}

GET/api/review/author/[username]

Get author track record

Returns historical review outcomes for a specific author to help reviewers assess risk quickly.

#author-track-record

Authentication

Accepts API key or authenticated session.

Request Body

No request body.

Status Codes

200: Track record returned.
404: Author has no review history.
429: Too many analytics requests.

Response Body

{  "author": "marco",  "approved": 18,  "denied": 2,  "merged": 14,  "recentRequests": [    "req_7f3d9a2c",    "req_65c1dafe"  ]}

POST/api/contact

Submit contact request

Captures an email, optional name, and UTM metadata for inbound access or sales requests.

#contact-form

Authentication

No auth required. Intended for the public website contact flow.

Request Body

{  "name": "Marco Rivera",  "email": "marco@example.com",  "utm": {    "utm_source": "github",    "utm_medium": "docs",    "utm_campaign": "api-reference"  }}

Status Codes

200: Lead captured.
400: Malformed payload or invalid email.
500: Downstream delivery failed after validation.

Response Body

{  "ok": true}

GET/api/r/[id]

Get receipt

Fetches the signed authority receipt returned after approval so downstream systems can verify it.

#get-receipt

Authentication

Accepts API key, session cookie, or signed receipt share link.

Request Body

No request body.

Status Codes

200: Receipt returned.
404: Unknown receipt id.
500: Receipt fetch failed.

Response Body

{  "id": "pp_r_8f91c2",  "status": "approved",  "approved_by": "Sarah Kim",  "approved_at": "2025-01-18T18:44:02.204Z",  "merge_unblocked_at": "2025-01-18T18:48:10.501Z",  "request": {    "repo": "permission-protocol/site",    "action": "deploy_service -> billing-api"  }}

Rate limits

The public site does not publish a formal per-route quota. In practice, treat queue polling and receipt fetches as low-volume control plane calls: back off on 429, avoid tight polling loops, and keep review list refreshes to roughly once every 5 to 10 seconds per active operator.

Examples

List pending requests

Read the queue first, then filter for pending requests in your client.

$ curl https://www.permissionprotocol.com/api/reviews \  -H "Authorization: Bearer pp_key_test_123" \  -H "Accept: application/json"

Approve a request

Use an authenticated approver context, provide a short decision comment, and persist the returned receipt id.

$ curl -X POST https://www.permissionprotocol.com/api/review/req_7f3d9a2c/approve \  -H "Authorization: Bearer ghu_approver_token" \  -H "Content-Type: application/json" \  -d '{    "comment": "Approved for prod hotfix window.",    "reason": "risk-reviewed"  }'

Get a receipt

Fetch the receipt after approval or merge to verify who authorized the action and when it became valid.

$ curl https://www.permissionprotocol.com/api/r/pp_r_8f91c2 \  -H "Authorization: Bearer pp_key_test_123" \  -H "Accept: application/json"