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

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.

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