> ## 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 REST API Reference — Overview and Quick Start

> Overview of the BugViper REST API: base URL, versioning, authentication, content types, and links to the interactive API documentation.

BugViper exposes a REST API that powers the dashboard and can be called directly to query review data, manage tools configuration, trigger support queries, and more. Whether you're building a custom integration or exploring what data BugViper collects, this reference gives you everything you need to start making requests.

## Base URL

BugViper is self-hosted, so your base URL is the domain where you've deployed the service. All examples in this documentation use the placeholder:

```
https://your-bugviper-domain.com
```

Replace `your-bugviper-domain.com` with your actual deployment domain (or `localhost:8000` during local development). Every API endpoint is served under the `/api/v1/` prefix.

## API Versioning

The current API version is **v1**. Prefix every endpoint path with `/api/v1/`. For example, to fetch your profile, you call:

```
GET https://your-bugviper-domain.com/api/v1/auth/me
```

Future breaking changes will be introduced under a new version prefix (e.g., `/api/v2/`) so existing integrations remain stable.

## Authentication

BugViper uses Firebase Authentication with GitHub OAuth. Most endpoints are protected and require you to pass a valid **Firebase ID Token** as a Bearer token in the `Authorization` header:

```
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...
```

You obtain this token by completing the GitHub OAuth login flow — either through the BugViper dashboard or by calling `POST /api/v1/auth/login` directly with a GitHub access token. Firebase ID Tokens are JWTs that expire after **1 hour**; the BugViper frontend refreshes them automatically.

The following endpoints are **public** and do not require an `Authorization` header:

| Public Endpoint              | Description                     |
| ---------------------------- | ------------------------------- |
| `GET /health`                | Service health check            |
| `POST /api/v1/webhook`       | GitHub webhook receiver         |
| `POST /api/v1/support/query` | Submit a customer support query |
| `GET /docs`                  | Swagger UI (interactive docs)   |
| `GET /redoc`                 | ReDoc documentation             |
| `GET /openapi.json`          | Raw OpenAPI schema              |

<Note>
  If you're building an integration against the BugViper API, the dashboard's auth flow issues Firebase ID Tokens automatically. You can extract the current token from the Firebase SDK (`getIdToken()`) and pass it directly in your requests without implementing a separate OAuth flow.
</Note>

## Content Type

All request and response bodies are JSON. Include the following header on every request that sends a body:

```
Content-Type: application/json
```

## Interactive Documentation

BugViper ships with two interactive API explorers at your deployment URL:

* **Swagger UI** — `https://your-bugviper-domain.com/docs` — try requests directly in the browser with a built-in form interface.
* **ReDoc** — `https://your-bugviper-domain.com/redoc` — a clean, three-panel reference layout ideal for reading.

Both reflect the live OpenAPI schema at `https://your-bugviper-domain.com/openapi.json`.

## Quick Reference

The table below lists every available endpoint grouped by resource. All routes except those marked **Public** require an `Authorization: Bearer <token>` header.

### Auth

| Method | Endpoint                    | Description                                                           |
| ------ | --------------------------- | --------------------------------------------------------------------- |
| `POST` | `/api/v1/auth/login`        | Sign in with a GitHub OAuth token; creates or updates the user record |
| `POST` | `/api/v1/auth/ensure`       | Ensure user record exists for a returning session                     |
| `GET`  | `/api/v1/auth/me`           | Return the authenticated user's profile                               |
| `GET`  | `/api/v1/auth/github/repos` | List the authenticated user's GitHub repositories                     |
| `GET`  | `/api/v1/auth/installation` | Return GitHub App installation status                                 |

### Repos

| Method | Endpoint                                                            | Description                                      |
| ------ | ------------------------------------------------------------------- | ------------------------------------------------ |
| `GET`  | `/api/v1/repos/overview`                                            | Combined repo list and aggregate dashboard stats |
| `GET`  | `/api/v1/repos/dashboard/stats`                                     | Aggregate stats across all repos                 |
| `GET`  | `/api/v1/repos/dashboard/analytics`                                 | Per-repo analytics with daily breakdowns         |
| `GET`  | `/api/v1/repos/{owner}/{repo}/analytics`                            | Analytics detail for a single repo               |
| `GET`  | `/api/v1/repos/{owner}/{repo}/prs`                                  | List reviewed PRs for a repo                     |
| `GET`  | `/api/v1/repos/{owner}/{repo}/prs/{pr_number}/reviews`              | List review runs for a PR                        |
| `GET`  | `/api/v1/repos/{owner}/{repo}/prs/{pr_number}/reviews/{run_number}` | Full detail for a single review run              |

### Tools

| Method | Endpoint               | Description                         |
| ------ | ---------------------- | ----------------------------------- |
| `GET`  | `/api/v1/tools/config` | Retrieve linter tools configuration |
| `PUT`  | `/api/v1/tools/config` | Save linter tools configuration     |

### Webhook

| Method | Endpoint          | Description                                        | Auth   |
| ------ | ----------------- | -------------------------------------------------- | ------ |
| `POST` | `/api/v1/webhook` | GitHub webhook receiver for PR events and comments | Public |

### Support

| Method | Endpoint                | Description                     | Auth   |
| ------ | ----------------------- | ------------------------------- | ------ |
| `POST` | `/api/v1/support/query` | Submit a customer support query | Public |