BugViper Repository and Pull Request API Reference

REST endpoints for listing repositories, pull requests, and review runs. Retrieve PR metadata and full review run details with issues and findings.

The repositories endpoints let you query all repos connected to your BugViper account, list their pull requests, and fetch detailed review run data. Every endpoint requires a valid Firebase ID Token in the Authorization header and returns JSON.

---

GET /api/v1/repos/overview

Returns all repositories connected to your account with aggregate statistics in a single call. Use this endpoint to populate a high-level summary view across all repos.

Authentication required: Yes

curl https://your-domain.com/api/v1/repos/overview \
  -H "Authorization: Bearer <token>"

Response

Returns an array of repository summary objects.

owner · string

GitHub organization name or username that owns the repository.

repo · string

Repository name.

totalIssues · integer

Total number of issues BugViper has raised across all PRs in this repository.

totalResolved · integer

Number of issues that have been marked as resolved or fixed.

prsReviewed · integer

Count of distinct pull requests that have received at least one BugViper review.

reviewsRun · integer

Total number of individual review runs executed across all PRs in this repository.

---

GET /api/v1/repos/{owner}/{repo}/prs

Lists all pull requests that have been reviewed for a given repository, ordered by most recently reviewed.

Authentication required: Yes

Path Parameters

owner · string · required

GitHub organization name or username that owns the repository.

repo · string · required

Repository name.

curl https://your-domain.com/api/v1/repos/acme-org/my-repo/prs \
  -H "Authorization: Bearer <token>"

Response

Returns an array of PR summary objects.

prNumber · integer

The GitHub pull request number.

title · string

Title of the pull request as it appears on GitHub.

state · string

Current state of the PR: open, closed, or merged.

mergedAt · string

ISO 8601 timestamp of when the PR was merged, or null if not yet merged.

reviewsCount · integer

Number of BugViper review runs that have been executed against this PR.

---

GET /api/v1/repos/{owner}/{repo}/prs/{pr_number}/reviews

Lists all review runs for a specific pull request. Each run corresponds to a single invocation of BugViper — for example, a full review triggered by @bugviper full review or a lint run triggered by @bugviper run lint.

Authentication required: Yes

Path Parameters

owner · string · required

GitHub organization name or username that owns the repository.

repo · string · required

Repository name.

pr_number · integer · required

The GitHub pull request number.

curl https://your-domain.com/api/v1/repos/acme-org/my-repo/prs/42/reviews \
  -H "Authorization: Bearer <token>"

Response

Returns an array of review run summary objects, ordered from most recent to oldest.

runNumber · integer

Sequential run number within this PR, starting at 1.

createdAt · string

ISO 8601 timestamp of when this review run was triggered.

issuesCount · integer

Number of issues (bugs, security findings, etc.) reported in this run.

positiveCount · integer

Number of positive findings — areas of code the agent highlighted as well-written or correct.

mode · string

Review mode used for this run: normal (single generalist agent) or deep (three specialized sub-agents running in parallel).

---

GET /api/v1/repos/{owner}/{repo}/prs/{pr_number}/reviews/{run_number}

Returns the full detail of a single review run, including the walkthrough summary, every issue found, and all positive findings. Use this endpoint to render a complete run detail view.

Authentication required: Yes

Path Parameters

owner · string · required

GitHub organization name or username that owns the repository.

repo · string · required

Repository name.

pr_number · integer · required

The GitHub pull request number.

run_number · integer · required

The sequential review run number to retrieve.

curl https://your-domain.com/api/v1/repos/acme-org/my-repo/prs/42/reviews/1 \
  -H "Authorization: Bearer <token>"

Response

runNumber · integer

Sequential run number within this PR.

mode · string

Review mode: normal or deep.

createdAt · string

ISO 8601 timestamp of when this review run was triggered.

summary · string

Walkthrough summary generated by the agent — describes which files were modified and the overall scope of the change.

positives · array

Array of positive finding strings. Each entry is a short description of something the agent considered correct, well-structured, or otherwise praiseworthy in the diff.

issues · array

Array of issue objects. Each object contains the following fields:

Show Issue object fields

issueId · string

Unique identifier for this issue within the run.

title · string

Short title summarizing the issue.

severity · string

Severity level assigned by the agent: critical, high, medium, or low.

confidence · integer

Agent confidence score from 1 (lowest) to 10 (highest) that this finding is a genuine problem.

status · string

Verifier classification: valid (high-confidence, genuine issue in the diff), nitpick (low-confidence or style concern), or outside_diff (finding falls outside the changed lines).

filePath · string

Relative path to the file containing the issue.

lineNumber · integer

Line number within the file where the issue was found.

codeSnippet · string

Relevant code snippet extracted from the diff.

impact · string

Description of the potential impact if this issue is not addressed.

suggestion · string

Agent-generated suggestion for how to fix or improve the code.

resolutionStatus · string

Lifecycle status of the issue: open, resolved (acknowledged/dismissed), or fixed (BugViper detected the fix in a later PR).