> ## Documentation Index
> Fetch the complete documentation index at: https://personal-ce79cb71.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
curl https://your-domain.com/api/v1/repos/overview \
  -H "Authorization: Bearer <token>"
```

### Response

Returns an array of repository summary objects.

<ResponseField name="owner" type="string">
  GitHub organization name or username that owns the repository.
</ResponseField>

<ResponseField name="repo" type="string">
  Repository name.
</ResponseField>

<ResponseField name="totalIssues" type="integer">
  Total number of issues BugViper has raised across all PRs in this repository.
</ResponseField>

<ResponseField name="totalResolved" type="integer">
  Number of issues that have been marked as resolved or fixed.
</ResponseField>

<ResponseField name="prsReviewed" type="integer">
  Count of distinct pull requests that have received at least one BugViper review.
</ResponseField>

<ResponseField name="reviewsRun" type="integer">
  Total number of individual review runs executed across all PRs in this repository.
</ResponseField>

***

## 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

<ParamField path="owner" type="string" required>
  GitHub organization name or username that owns the repository.
</ParamField>

<ParamField path="repo" type="string" required>
  Repository name.
</ParamField>

```bash theme={null}
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.

<ResponseField name="prNumber" type="integer">
  The GitHub pull request number.
</ResponseField>

<ResponseField name="title" type="string">
  Title of the pull request as it appears on GitHub.
</ResponseField>

<ResponseField name="state" type="string">
  Current state of the PR: `open`, `closed`, or `merged`.
</ResponseField>

<ResponseField name="mergedAt" type="string">
  ISO 8601 timestamp of when the PR was merged, or `null` if not yet merged.
</ResponseField>

<ResponseField name="reviewsCount" type="integer">
  Number of BugViper review runs that have been executed against this PR.
</ResponseField>

***

## 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

<ParamField path="owner" type="string" required>
  GitHub organization name or username that owns the repository.
</ParamField>

<ParamField path="repo" type="string" required>
  Repository name.
</ParamField>

<ParamField path="pr_number" type="integer" required>
  The GitHub pull request number.
</ParamField>

```bash theme={null}
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.

<ResponseField name="runNumber" type="integer">
  Sequential run number within this PR, starting at 1.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of when this review run was triggered.
</ResponseField>

<ResponseField name="issuesCount" type="integer">
  Number of issues (bugs, security findings, etc.) reported in this run.
</ResponseField>

<ResponseField name="positiveCount" type="integer">
  Number of positive findings — areas of code the agent highlighted as well-written or correct.
</ResponseField>

<ResponseField name="mode" type="string">
  Review mode used for this run: `normal` (single generalist agent) or `deep` (three specialized sub-agents running in parallel).
</ResponseField>

***

## 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

<ParamField path="owner" type="string" required>
  GitHub organization name or username that owns the repository.
</ParamField>

<ParamField path="repo" type="string" required>
  Repository name.
</ParamField>

<ParamField path="pr_number" type="integer" required>
  The GitHub pull request number.
</ParamField>

<ParamField path="run_number" type="integer" required>
  The sequential review run number to retrieve.
</ParamField>

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

### Response

<ResponseField name="runNumber" type="integer">
  Sequential run number within this PR.
</ResponseField>

<ResponseField name="mode" type="string">
  Review mode: `normal` or `deep`.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of when this review run was triggered.
</ResponseField>

<ResponseField name="summary" type="string">
  Walkthrough summary generated by the agent — describes which files were modified and the overall scope of the change.
</ResponseField>

<ResponseField name="positives" type="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.
</ResponseField>

<ResponseField name="issues" type="array">
  Array of issue objects. Each object contains the following fields:

  <Expandable title="Issue object fields">
    <ResponseField name="issueId" type="string">
      Unique identifier for this issue within the run.
    </ResponseField>

    <ResponseField name="title" type="string">
      Short title summarizing the issue.
    </ResponseField>

    <ResponseField name="severity" type="string">
      Severity level assigned by the agent: `critical`, `high`, `medium`, or `low`.
    </ResponseField>

    <ResponseField name="confidence" type="integer">
      Agent confidence score from 1 (lowest) to 10 (highest) that this finding is a genuine problem.
    </ResponseField>

    <ResponseField name="status" type="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).
    </ResponseField>

    <ResponseField name="filePath" type="string">
      Relative path to the file containing the issue.
    </ResponseField>

    <ResponseField name="lineNumber" type="integer">
      Line number within the file where the issue was found.
    </ResponseField>

    <ResponseField name="codeSnippet" type="string">
      Relevant code snippet extracted from the diff.
    </ResponseField>

    <ResponseField name="impact" type="string">
      Description of the potential impact if this issue is not addressed.
    </ResponseField>

    <ResponseField name="suggestion" type="string">
      Agent-generated suggestion for how to fix or improve the code.
    </ResponseField>

    <ResponseField name="resolutionStatus" type="string">
      Lifecycle status of the issue: `open`, `resolved` (acknowledged/dismissed), or `fixed` (BugViper detected the fix in a later PR).
    </ResponseField>
  </Expandable>
</ResponseField>