PR Reviews
Read automated pull-request reviews, their findings, and the verdict posted back to GitHub.
A PR review is the agent run against one pull request's diff. Reviews are triggered by GitHub webhooks on connected repositories — the API reads them, it does not start them.
Read-only over the API
There is no endpoint to start a PR review. Reviews begin when GitHub tells Vulnix a pull
request opened or changed, governed by that repository's auto_review_enabled and
effective_rereview_on_push. Only pr_reviews:read exists — there is no pr_reviews:write.
The PR review object
Prop
Type
Status and verdict are different questions
status is whether the review ran. verdict is what it concluded. Check both:
Prop
Type
Do not treat a non-`failed` verdict as approval
A CI gate written as if verdict != "failed" lets inconclusive and broken reviews through.
Gate on verdict == "passed" and decide deliberately what to do with everything else.
github_posted can be false on a real verdict
The verdict is recorded in Vulnix whether or not GitHub accepted the review — a revoked
installation or a protected branch can reject the post. When github_posted is false, the
pull request shows no review even though a verdict exists. If you rely on the GitHub check
alone, that case is invisible; reading verdict over the API is what closes the gap.
List PR reviews
GET /pr-reviews · scope pr_reviews:read · role analyst
Every review in the organization, each with two fields beyond the object above:
Prop
Type
{ "pr_reviews": [] }Get a PR review
GET /pr-reviews/{pr_review_id} · scope pr_reviews:read · role analyst
The review object plus repository_full_name. A missing or foreign id returns
404 pr_review_not_found.
Findings from a PR review
GET /pr-reviews/{pr_review_id}/findings · scope pr_reviews:read · role analyst
{
"findings": [],
"severity_breakdown": { "critical": 0, "high": 0, "medium": 0, "low": 0, "info": 0 }
}Holds finding objects. PR-review findings carry
code_locations — file and line — because the agent worked from a diff.
Only critical and high can fail a check
When block_on_findings is on, the GitHub check fails on critical or high findings.
Lower severities are reported but never block a merge. Read severity_breakdown if you want
a stricter gate of your own.
Agent trace
GET /pr-reviews/{pr_review_id}/agent-trace · scope pr_reviews:read · role analyst
Identical shape to a run's — see
agent trace for the node fields and the free-trial locked behavior.
Live events
GET /pr-reviews/{pr_review_id}/events · scope pr_reviews:read · role analyst
Server-Sent Events while the review executes. See live event streams.
Policy
What gets reviewed, whether a clean PR is approved, and whether findings block the merge are per-repository settings with an organization-wide default:
- Per repository —
PATCH /repositories/{repository_id} - Organization defaults —
PATCH /org/pr-review-defaults
