Review

For instructions on how to authenticate to use this endpoint, see API overview.

Endpoints

GET
PATCH
GET
PATCH
GET
PATCH
GET
GET
GET
POST
GET
PATCH

List all review hog blind spots

List the review-hog-blind-spots-* skills visible to the requesting user — the canonical skill plus the customs they authored — flagging the one active for them. The canonical skill is auto-seeded active on the first read; a custom skill the user has not selected shows as inactive.

Required API key scopes

llm_skill:read

Example request

GET /api/projects/:project_id/review_hog/blind_spots
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/review_hog/blind_spots/

Example response

Status 200 Every blind-spots skill on this project, flagging the one active for the user.
RESPONSE
{
  "skill_name": "string",
  "active": true,
  "description": "string",
  "body": "string"
}

Update review hog blind spots

Make a review-hog-blind-spots-* skill the single sweep that runs on the requesting user's PR reviews, switching the user's other blind-spots skills off in the same call. Only skills visible to the user — the canonical plus the customs they authored — can be selected; anything else 404s. Upserts the per-user config row, so selecting a freshly authored custom skill works in one call.

Required API key scopes

llm_skill:write

Path parameters

  • skill_name
    string

Request parameters

  • active
    boolean

Response


Example request

PATCH /api/projects/:project_id/review_hog/blind_spots/:skill_name
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/review_hog/blind_spots/:skill_name/\
	-d active="boolean"

Example response

Status 200 The blind-spots skill now active for the user.
RESPONSE
{
  "skill_name": "string",
  "active": true,
  "description": "string",
  "body": "string"
}
Status 400 Not a blind-spots skill, or `active` was not true.
Status 404 No such blind-spots skill visible to the user on this project.

List all review hog perspectives

List the review-hog-perspective-* skills visible to the requesting user — the canonical perspectives plus the customs they authored — joined with their enable state. The 3 canonical perspectives are auto-seeded enabled on the first read; a custom perspective the user has not switched on shows as disabled.

Required API key scopes

llm_skill:read

Example request

GET /api/projects/:project_id/review_hog/perspectives
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/review_hog/perspectives/

Example response

Status 200 Every review perspective on this project with the user's enable state, by skill name.
RESPONSE
{
  "skill_name": "string",
  "enabled": true,
  "description": "string",
  "body": "string"
}

Update review hog perspectives

Toggle whether a review-hog-perspective-* skill runs on the requesting user's PR reviews. Only skills visible to the user — the canonicals plus the customs they authored — can be toggled; anything else 404s. Upserts the per-user config row, so enabling a freshly authored custom perspective works in one call. Rejected if it would leave the user with no enabled perspective.

Required API key scopes

llm_skill:write

Path parameters

  • skill_name
    string

Request parameters

  • enabled
    boolean

Response


Example request

PATCH /api/projects/:project_id/review_hog/perspectives/:skill_name
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/review_hog/perspectives/:skill_name/\
	-d enabled="boolean"

Example response

Status 200 The perspective's updated enable state.
RESPONSE
{
  "skill_name": "string",
  "enabled": true,
  "description": "string",
  "body": "string"
}
Status 400 Not a perspective skill, or disabling the user's last enabled one.
Status 404 No such perspective skill visible to the user on this project.

List all review hog resolution

List the review-hog-resolution-* skills visible to the requesting user — the canonical criteria plus the customs they authored — flagging the one active for them. The canonical skill is auto-seeded active on the first read; a custom skill the user has not selected shows as inactive.

Required API key scopes

llm_skill:read

Example request

GET /api/projects/:project_id/review_hog/resolution
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/review_hog/resolution/

Example response

Status 200 Every resolution-criteria skill on this project, flagging the one active for the user.
RESPONSE
{
  "skill_name": "string",
  "active": true,
  "description": "string",
  "body": "string"
}

Update review hog resolution

Make a review-hog-resolution-* skill the single criteria the resolution stage applies on the requesting user's PRs, switching the user's other resolution skills off in the same call. Only skills visible to the user — the canonical plus the customs they authored — can be selected; anything else 404s. Upserts the per-user config row, so selecting a freshly authored custom skill works in one call.

Required API key scopes

llm_skill:write

Path parameters

  • skill_name
    string

Request parameters

  • active
    boolean

Response


Example request

PATCH /api/projects/:project_id/review_hog/resolution/:skill_name
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/review_hog/resolution/:skill_name/\
	-d active="boolean"

Example response

Status 200 The resolution criteria now active for the user.
RESPONSE
{
  "skill_name": "string",
  "active": true,
  "description": "string",
  "body": "string"
}
Status 400 Not a resolution skill, or `active` was not true.
Status 404 No such resolution skill visible to the user on this project.

List all review hog reviews

Recent ReviewHog reviews on this project: actively running reviews first (with the in-flight turn's stage), then the most recent completed ones — at most limit rows (default 5), plus has_more for whether a larger limit would reveal more. By default only the requesting user's reviews; scope=everyone lists every review on the project.

Required API key scopes

review_hog:read

Query parameters

  • limit
    integer
    Default: 5
  • scope
    string
    Default: mine
    One of: "mine""everyone"

Response


Example request

GET /api/projects/:project_id/review_hog/reviews
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/review_hog/reviews/

Example response

Status 200 The scoped reviews: in-progress runs first, then completed newest first, with a flag for whether more exist beyond `limit`.
RESPONSE
{
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "repository": "string",
      "pr_number": 0,
      "pr_title": "string",
      "pr_author": "string",
      "additions": 0,
      "deletions": 0,
      "changed_files": 0,
      "head_branch": "string",
      "github_url": "string",
      "run_count": 0,
      "last_run_at": "2019-08-24T14:15:22Z",
      "published": true,
      "in_progress": true,
      "progress": {
        "review_stage": "fetching",
        "done": 0,
        "total": 0
      },
      "resolution": {
        "resolution_status": "resolving",
        "done": 0,
        "total": 0,
        "fixed": 0,
        "needs_attention": 0
      },
      "must_fix_count": 0,
      "should_fix_count": 0,
      "consider_count": 0,
      "candidate_count": 0,
      "dismissed_count": 0,
      "files_reviewed": 0,
      "chunk_count": 0,
      "perspective_count": 0,
      "perspective_issue_count": 0,
      "blind_spot_issue_count": 0
    }
  ],
  "has_more": true
}

Retrieve review hog reviews

One completed ReviewHog review on this project, with the latest turn's validated findings, the findings the validator dismissed (and why), and the review body published to GitHub. Project-wide, so reviews listed under scope=everyone can be opened too.

Required API key scopes

review_hog:read

Path parameters

  • id
    string

Response


Example request

GET /api/projects/:project_id/review_hog/reviews/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/review_hog/reviews/:id/

Example response

Status 200 The review's detail: findings (valid and dismissed) and the published body.
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "repository": "string",
  "pr_number": 0,
  "pr_title": "string",
  "pr_author": "string",
  "additions": 0,
  "deletions": 0,
  "changed_files": 0,
  "head_branch": "string",
  "github_url": "string",
  "run_count": 0,
  "last_run_at": "2019-08-24T14:15:22Z",
  "published": true,
  "in_progress": true,
  "progress": {
    "review_stage": "fetching",
    "done": 0,
    "total": 0
  },
  "resolution": {
    "resolution_status": "resolving",
    "done": 0,
    "total": 0,
    "fixed": 0,
    "needs_attention": 0
  },
  "must_fix_count": 0,
  "should_fix_count": 0,
  "consider_count": 0,
  "candidate_count": 0,
  "dismissed_count": 0,
  "files_reviewed": 0,
  "chunk_count": 0,
  "perspective_count": 0,
  "perspective_issue_count": 0,
  "blind_spot_issue_count": 0,
  "head_sha": "string",
  "perspective_selection": {
    "roster": [
      "string"
    ],
    "chunks": [
      {
        "chunk_id": 0,
        "chunk_type": "string",
        "files": [
          "string"
        ],
        "perspectives": [
          "string"
        ],
        "skipped": [
          "string"
        ],
        "reason": "string"
      }
    ]
  },
  "report_markdown": "string",
  "run_urgency_threshold": "must_fix",
  "findings": [
    {
      "title": "string",
      "file": "string",
      "lines": [
        {
          "start": 0,
          "end": 0
        }
      ],
      "body": "string",
      "suggestion": "string",
      "effective_priority": "must_fix",
      "reviewer_priority": "must_fix",
      "source_perspective": "string",
      "validator_category": "bug",
      "validator_note": "string"
    }
  ],
  "dismissed_findings": [
    {
      "title": "string",
      "file": "string",
      "lines": [
        {
          "start": 0,
          "end": 0
        }
      ],
      "body": "string",
      "suggestion": "string",
      "effective_priority": "must_fix",
      "reviewer_priority": "must_fix",
      "source_perspective": "string",
      "validator_category": "bug",
      "validator_note": "string"
    }
  ]
}
Status 404 No such review on this project.

Retrieve review hog reviews perspective stats

How many findings each review skill (perspective or blind-spot sweep) raised across the recent completed reviews in scope — the requesting user's by default, every review on this project with scope=everyone — and how many of those the validator kept vs dismissed.

Required API key scopes

review_hog:read

Query parameters

  • scope
    string
    Default: mine
    One of: "mine""everyone"

Response


Example request

GET /api/projects/:project_id/review_hog/reviews/perspective_stats
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/review_hog/reviews/perspective_stats/

Example response

Status 200 Per-skill effectiveness across the recent completed reviews in scope.
RESPONSE
{
  "report_count": 0,
  "perspectives": [
    {
      "skill_name": "string",
      "raised": 0,
      "kept": 0,
      "dismissed": 0
    }
  ]
}

Create review hog reviews trigger

Start a ReviewHog review of any pull request the project's GitHub App installation can access, and publish it back to the PR. The requesting user is the review's acting user: their enabled perspectives, blind-spot check, validator, urgency threshold, and resolution criteria drive the run, and it appears under their recent reviews. run_mode picks the variant: a review (which chains the resolution stage per the user's resolve_comments setting), a review without resolving, resolution only, or a lower-cost Flash review that never resolves comments. Nonexistent, closed, and fork PRs are rejected synchronously; a PR whose current commit already has a published review returns 'already_reviewed' without starting a run (resolve_only skips that check — settling threads on a reviewed head is its whole point), and triggering a PR whose run is currently in flight joins that run. Otherwise non-blocking: returns the Temporal workflow id immediately while the run executes in the worker.

Required API key scopes

review_hog:write

Request parameters

  • pr_url
    string
  • run_mode
    Default: review

Response


Example request

POST /api/projects/:project_id/review_hog/reviews/trigger
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/review_hog/reviews/trigger/\
	-d pr_url="string"

Example response

Status 200 No new run needed: the PR's current commit already has a published review.
RESPONSE
{
  "workflow_id": "string",
  "status": "string"
}
Status 202 Review run started.
RESPONSE
{
  "workflow_id": "string",
  "status": "string"
}
Status 400 Invalid PR URL, inaccessible repository, or a nonexistent, closed, or fork PR.
RESPONSE
{
  "error": "string"
}
Status 403 The review-hog feature flag is off for this project, or Flash was requested in a project without internal features (see show_internal_features in the settings response).
RESPONSE
{
  "error": "string"
}
Status 409 The pull request's cycle is busy (busy-guard): reviews are blocked while its comments are being resolved, and resolve-only runs are blocked while a review is running.
RESPONSE
{
  "error": "string"
}
Status 429 GitHub rate-limited the App's token; retry after the Retry-After delay.

List all review hog validators

List the review-hog-validation-* skills visible to the requesting user — the canonical validator plus the customs they authored — flagging the one active for them. The canonical validator is auto-seeded active on the first read; a custom validator the user has not selected shows as inactive.

Required API key scopes

llm_skill:read

Example request

GET /api/projects/:project_id/review_hog/validators
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/review_hog/validators/

Example response

Status 200 Every review validator on this project, flagging the one active for the user.
RESPONSE
{
  "skill_name": "string",
  "active": true,
  "description": "string",
  "body": "string"
}

Update review hog validators

Make a review-hog-validation-* skill the single validator that runs on the requesting user's PR reviews, switching the user's other validators off in the same call. Only skills visible to the user — the canonical plus the customs they authored — can be selected; anything else 404s. Upserts the per-user config row, so selecting a freshly authored custom validator works in one call.

Required API key scopes

llm_skill:write

Path parameters

  • skill_name
    string

Request parameters

  • active
    boolean

Response


Example request

PATCH /api/projects/:project_id/review_hog/validators/:skill_name
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/review_hog/validators/:skill_name/\
	-d active="boolean"

Example response

Status 200 The validator now active for the user.
RESPONSE
{
  "skill_name": "string",
  "active": true,
  "description": "string",
  "body": "string"
}
Status 400 Not a validator skill, or `active` was not true.
Status 404 No such validator skill visible to the user on this project.