Review

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

Endpoints

GET
GET
PATCH
GET
GET
GET
GET
GET
POST
GET
PATCH
← Previous page

Retrieve review hog repository overview

Every repository the GitHub installation can see, with the project that reviews it, this project's settings, the requesting user's choice, and the automatic review the requesting user gets.

Query parameters

  • installation_id
    string
  • limit
    integer
    Default: 50
  • offset
    integer
    Default: 0
  • search
    string
    Default:
  • view
    string
    Default: all
    One of: "all""in_project""exceptions""mine""differs"

Response


Example request

GET /api/projects/:project_id/review_hog/repository_overview
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/repository_overview/

Example response

Status 200
RESPONSE
{
  "installation_id": "string",
  "claim_scope": "all",
  "results": [
    {
      "full_name": "string",
      "github_repo_id": 0,
      "owner": "this_project",
      "owner_project": {
        "id": 0,
        "name": "string"
      },
      "in_project": true,
      "selected": true,
      "repository_id": "b349ae61-b973-4c6c-a5e0-89183ba99ff3",
      "exception": {
        "flash_for": "everyone",
        "people": [
          {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "user": {
              "id": 0,
              "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
              "distinct_id": "string",
              "first_name": "string",
              "last_name": "string",
              "email": "user@example.com",
              "is_email_verified": true,
              "hedgehog_config": {},
              "role_at_organization": "engineering"
            },
            "kind": "listed"
          }
        ]
      },
      "my_choice": "flash",
      "my_choice_id": "d360aaf1-bd6f-4ffb-b0c3-e04defc20c38",
      "my_result": {
        "flash": true,
        "reason": "own_repository_choice"
      },
      "inherited_result": {
        "flash": true,
        "reason": "own_repository_choice"
      },
      "repository_result": {
        "flash": true,
        "reason": "own_repository_choice"
      }
    }
  ],
  "total": 0,
  "has_more": true,
  "next_offset": 0,
  "folded": 0,
  "folded_preview": [
    "string"
  ],
  "folded_result": {
    "flash": true,
    "reason": "own_repository_choice"
  },
  "my_choices_unlike_default": 0
}
Status 400 The installation is not connected here.
RESPONSE
{
  "error": "string",
  "conflicting_project": {
    "id": 0,
    "name": "string"
  }
}

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 code 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,
      "turn_published": true,
      "review_mode": "full",
      "review_design": "pipeline",
      "status_comment_url": "string",
      "full_review_published": true,
      "in_progress": true,
      "progress": {
        "review_stage": "fetching",
        "done": 0,
        "total": 0,
        "review_mode": "full"
      },
      "resolution": {
        "resolution_status": "resolving",
        "done": 0,
        "total": 0,
        "fixed": 0,
        "needs_attention": 0
      },
      "latest_resolution": {
        "status": "resolving",
        "started_at": "2019-08-24T14:15:22Z",
        "completed_at": "2019-08-24T14:15:22Z",
        "total": 0,
        "fixed": 0,
        "needs_attention": 0,
        "commits": [
          "string"
        ]
      },
      "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 code review on this project, with one turn's validated findings, the findings the validator dismissed (and why), and the review body published to GitHub. The latest completed turn by default; run_index reads an older one. in_progress, progress, and the resolution fields describe the report now, whatever the turn. Project-wide, so reviews listed under scope=everyone can be opened too.

Required API key scopes

review_hog:read

Path parameters

  • id
    string

Query parameters

  • run_index
    integer

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,
  "turn_published": true,
  "review_mode": "full",
  "review_design": "pipeline",
  "status_comment_url": "string",
  "full_review_published": true,
  "in_progress": true,
  "progress": {
    "review_stage": "fetching",
    "done": 0,
    "total": 0,
    "review_mode": "full"
  },
  "resolution": {
    "resolution_status": "resolving",
    "done": 0,
    "total": 0,
    "fixed": 0,
    "needs_attention": 0
  },
  "latest_resolution": {
    "status": "resolving",
    "started_at": "2019-08-24T14:15:22Z",
    "completed_at": "2019-08-24T14:15:22Z",
    "total": 0,
    "fixed": 0,
    "needs_attention": 0,
    "commits": [
      "string"
    ]
  },
  "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,
  "run_index": 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": "consider",
  "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"
    }
  ],
  "dropped_findings": [
    {
      "title": "string",
      "file": "string",
      "lines": [
        {
          "start": 0,
          "end": 0
        }
      ],
      "body": "string",
      "suggestion": "string",
      "priority": "must_fix",
      "source_perspective": "string",
      "disposition": "old_code",
      "duplicate_of": "string",
      "comment_url": "string",
      "rank": 0
    }
  ]
}
Status 404 No such review on this project, or no such completed turn.

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, the user's own last Deep reviews with scope=own_deep — 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""own_deep"

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
    }
  ]
}

Retrieve review hog reviews pr status

Where a pull request's review runs stand: state, the latest completed review turn, and the latest Resolve run. Works for any pull request on the project, also ones the caller did not trigger. Pass the requested_at and head_sha the trigger returned, and the run_mode it was called with, to get request_outcome, which says when that request is done.

Required API key scopes

review_hog:read

Query parameters

  • head_sha
    string
  • pr_url
    string
  • requested_at
    string
  • run_mode
    string
    Default: review
    One of: "review""review_only""resolve_only""flash"

Response


Example request

GET /api/projects/:project_id/review_hog/reviews/pr_status
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/pr_status/

Example response

Status 200 The pull request's review status.
RESPONSE
{
  "repository": "string",
  "pr_number": 0,
  "report_id": "5ed7905a-4735-4cf7-b1ab-521e066fb971",
  "state": "not_reviewed",
  "latest_review": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "review_mode": "full",
    "head_sha": "string",
    "run_index": 0,
    "completed_at": "2019-08-24T14:15:22Z",
    "must_fix_count": 0,
    "should_fix_count": 0,
    "consider_count": 0,
    "turn_published": true,
    "status_comment_url": "string"
  },
  "latest_resolution": {
    "status": "resolving",
    "started_at": "2019-08-24T14:15:22Z",
    "completed_at": "2019-08-24T14:15:22Z",
    "total": 0,
    "fixed": 0,
    "needs_attention": 0,
    "commits": [
      "string"
    ]
  },
  "request_outcome": {
    "status": "pending",
    "reason": "string",
    "review_id": "30a1a187-4023-4077-a8f3-f5ec83d3ab6b",
    "run_index": 0
  }
}
Status 400 Not a GitHub pull request URL, or an invalid parameter.

Retrieve review hog reviews table

Code reviews on this project as a paginated table: reviews with a completed turn plus reviews with a run in flight, ordered by last activity, so a review that starts or finishes moves to the top. Pages with limit and offset; count is the total across pages. Filters by repository, review_mode, status, and published. running_count counts the running reviews under every filter except status. 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: 25
  • offset
    integer
    Default: 0
  • published
    boolean | null
  • repository
    string
  • review_mode
    string
    One of: "full""flash"
  • scope
    string
    Default: mine
    One of: "mine""everyone"
  • status
    string
    One of: "running""completed"

Response


Example request

GET /api/projects/:project_id/review_hog/reviews/table
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/table/

Example response

Status 200 One page of reviews, most recent activity first, with the total and running counts.
RESPONSE
{
  "count": 0,
  "running_count": 0,
  "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,
      "turn_published": true,
      "review_mode": "full",
      "review_design": "pipeline",
      "status_comment_url": "string",
      "full_review_published": true,
      "in_progress": true,
      "progress": {
        "review_stage": "fetching",
        "done": 0,
        "total": 0,
        "review_mode": "full"
      },
      "resolution": {
        "resolution_status": "resolving",
        "done": 0,
        "total": 0,
        "fixed": 0,
        "needs_attention": 0
      },
      "latest_resolution": {
        "status": "resolving",
        "started_at": "2019-08-24T14:15:22Z",
        "completed_at": "2019-08-24T14:15:22Z",
        "total": 0,
        "fixed": 0,
        "needs_attention": 0,
        "commits": [
          "string"
        ]
      },
      "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
    }
  ]
}

Create review hog reviews trigger

Start a PostHog Review run on any pull request the project's GitHub App installation can access, and publish it back to the PR. The run appears under the requesting user's recent reviews. A Deep review uses the requester's enabled perspectives, blind-spot check, validator, and urgency threshold; a Standard review uses none of them. Resolution writes to the branch only when the pull request owner opted in, whoever asks. run_mode picks the variant: 'review' is a Deep review that chains the resolution stage per the owner's resolve_comments setting, 'review_only' is a Deep review without resolving, 'resolve_only' runs resolution only, and 'flash' is a lower-cost Standard review that never resolves comments and is refused after a published Deep review. Nonexistent, closed, and fork PRs are rejected synchronously. A PR whose current commit already has a published review in the requested mode returns 'already_reviewed' without starting a run (resolve_only skips that check, because settling threads on a reviewed head is its whole point). A request while a review runs is queued on that PR's run. Otherwise non-blocking: returns immediately with the PR's head, the review's id when one exists, and whether resolution will run, 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",
  "repository": "string",
  "pr_number": 0,
  "head_sha": "string",
  "review_mode": "full",
  "report_id": "5ed7905a-4735-4cf7-b1ab-521e066fb971",
  "requested_at": "2019-08-24T14:15:22Z",
  "resolve_will_run": true,
  "resolve_skip_reason": "run_mode_excludes_resolve"
}
Status 202 Review run started.
RESPONSE
{
  "workflow_id": "string",
  "status": "string",
  "repository": "string",
  "pr_number": 0,
  "head_sha": "string",
  "review_mode": "full",
  "report_id": "5ed7905a-4735-4cf7-b1ab-521e066fb971",
  "requested_at": "2019-08-24T14:15:22Z",
  "resolve_will_run": true,
  "resolve_skip_reason": "run_mode_excludes_resolve"
}
Status 400 Invalid PR URL, inaccessible repository, or a nonexistent, closed, or fork PR.
RESPONSE
{
  "error": "string",
  "code": "flash_after_full"
}
Status 403 The review-hog feature flag is off for this project.
RESPONSE
{
  "error": "string",
  "code": "flash_after_full"
}
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. Also returned with a code when a Standard review follows a published Deep review ('flash_after_full') or the PR owner has not opted in to resolution ('resolution_not_opted_in').
RESPONSE
{
  "error": "string",
  "code": "flash_after_full"
}
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.
← Previous page