Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Verifieddanny/BurnGuard/llms.txt

Use this file to discover all available pages before exploring further.

The BurnGuard REST API is a JSON-over-HTTP API consumed by two clients: the BurnGuard dashboard frontend (which reads analytics, manages tokens, and updates settings) and the local proxy daemon (which posts usage records after each intercepted AI call). Every response body is wrapped in a consistent envelope so callers never need to guess the shape of a successful or failed response.

​
Base URL

https://api.burnguard.run
All versioned endpoints are nested under /v1: 
https://api.burnguard.run/v1
The bare /health and /welcome endpoints live outside the version prefix and require no authentication.

​
Authentication

The API uses two authentication mechanisms depending on the caller. Dashboard session (users) After a successful OAuth or passkey login, the backend returns a session_id string. All protected dashboard endpoints require this value sent as a Bearer token: 
Authorization: Bearer session_<your_session_id>
The session middleware checks for the Bearer session_ prefix specifically — any other prefix is rejected with 401 Unauthorized. Sync token (proxy) The local BurnGuard proxy authenticates to POST /v1/usage with a bg_... sync token created from the dashboard: 
Authorization: Bearer bg_<your_sync_token>
Sync tokens are hashed before storage; the raw value is shown only once at creation time.

​
Response format

All responses — success and error — return Content-Type: application/json. Success 
{
  "data": { ... }
}
The data field holds the endpoint-specific payload (object, array, or null for 204 responses). Error 
{
  "error": "Human-readable error message"
}

​
HTTP status codes

CodeMeaning
200 OKRequest succeeded; body contains data
201 CreatedResource created; body contains data
204 No ContentRequest succeeded; no response body
400 Bad RequestMalformed request body or missing required fields
401 UnauthorizedMissing, expired, or invalid session / sync token
403 ForbiddenAuthenticated but not permitted to access this resource
404 Not FoundResource does not exist
500 Internal Server ErrorUnexpected server-side failure

​
Available endpoints

GroupEndpoints
HealthGET /health, GET /welcome
Auth — OAuthGET /v1/auth/github, GET /v1/auth/github/callback, GET /v1/auth/google, GET /v1/auth/google/callback
Auth — ProfileGET /v1/auth/me
Auth — PasskeysPOST /v1/auth/passkey/login/begin, POST /v1/auth/passkey/login/finish, POST /v1/auth/passkey/register/begin, POST /v1/auth/passkey/register/finish
Usage SyncPOST /v1/usage
TokensGET /v1/tokens, POST /v1/tokens
DashboardGET /v1/dashboard/summary, GET /v1/dashboard/chart, GET /v1/dashboard/providers, GET /v1/dashboard/requests
BudgetGET /v1/budget, POST /v1/budget, PUT /v1/budget
AlertsGET /v1/alerts/config, PUT /v1/alerts/config

​
Endpoint group pages

Auth

OAuth sign-in via GitHub and Google, WebAuthn passkey registration and login, and the /auth/me profile endpoint.

Dashboard

Spend summary, daily chart data, per-provider cost breakdown, and the paginated request log.

Tokens

Create and list sync tokens that authenticate the local proxy to push usage records.

Budget

Read and update the cloud-stored monthly budget limit used for threshold alerts.

Alerts

Read and update Slack and Discord webhook URLs and per-threshold alert flags.

Build docs developers (and LLMs) love

Get started for freeTalk to us