REST API
BugBrain REST API reference — the /v1 base path, authenticating with a session token or an sk_live_ API key, rate limiting, and the main resource areas you can call programmatically.
The BugBrain REST API lets you drive the platform programmatically — start runs, read results, manage test cases, and pull issues and reports — from scripts, CI, or your own tooling. This page is the overview and authentication guide; the full, current endpoint list is available in-app.
Base path#
Every endpoint is served under the /v1 prefix on your BugBrain host. For example, …/v1/projects. The API speaks JSON.
Authentication#
There are two principal types. Use the one that fits the caller.
| Method | Credential | Sent as | Used by |
|---|---|---|---|
| Session token | An HS256 session JWT minted at login | Authorization: Bearer <jwt> | The BugBrain web app |
| API key | A secret that starts with sk_live_ | x-api-key: sk_live_… or Authorization: Bearer sk_live_… | Scripts, CI, the MCP server |
For programmatic access, always use an API key. Create and revoke keys from the workspace settings — see API keys. A real session JWT never starts with sk_live_, so the API tells the two apart automatically.
What an API key can do#
- An API-key principal acts with Admin-level access within the workspace the key belongs to. Owner-only operations (such as workspace deletion or ownership transfer) stay out of reach.
- Access is further constrained by the key's scopes. An empty scope list means full access; otherwise the key can only reach the areas its scopes permit. The privilege-escalation scopes (managing keys, managing webhooks) are hard-enforced server-side.
- Suspended-workspace enforcement applies to keys exactly as it does to members.
See the Permissions catalog for how member access is modeled, and API keys for the scope presets.
Example request#
Read your projects with an API key:
curl https://app.bugbrain.tech/v1/projects \
-H "x-api-key: sk_live_your_key_here"
The same call with a Bearer header:
curl https://app.bugbrain.tech/v1/projects \
-H "Authorization: Bearer sk_live_your_key_here"
Keep keys secret
An sk_live_ key carries Admin-level access to your workspace. Store it in a secrets manager or CI secret, never in source control. If a key leaks, revoke it immediately and mint a new one.
Rate limiting#
The API is rate limited per principal. If you exceed the limit you'll receive an HTTP 429 response. Back off and retry rather than polling in a tight loop — a poll storm only counts against your own limit and slows you down. Where a result takes time to produce, prefer the resource's status field over rapid re-fetching.
Resource areas#
The API is organized around the same objects you see in the app. The main areas you'll call:
| Area | What you do with it |
|---|---|
| Projects | List and manage projects (the unit a run targets). |
| Test runs | Start exploratory runs, read status, and pull results. |
| Test cases | List, create, and execute saved test cases. |
| Test plans | List and run grouped sets of test cases. |
| Issues | List issues a run found and update their triage state. |
| Reports | Read report definitions and snapshots. |
The app is the source of truth
This is a representative overview, not an exhaustive dump. Exact paths, query parameters, and the complete endpoint set are deployment-specific and evolve with the product — consult the in-app reference for the authoritative, current list.
Related#
Frequently asked questions
What is the API base path?
Every endpoint lives under /v1. Build requests against your BugBrain host plus /v1, for example https://app.bugbrain.tech/v1/projects.
How do I authenticate a programmatic request?
Mint an API key (it looks like sk_live_…) and send it on every request, either as an x-api-key header or as an Authorization Bearer token. Session JWTs are for the web app; API keys are for scripts, CI, and the MCP server.
What can an API key do?
An API-key principal acts with Admin-level access inside its own workspace, further narrowed by the key's scopes. An empty scope list means full access; otherwise the key can only reach the areas its scopes permit. Owner-only operations are always out of reach.
Where is the full, exhaustive list of endpoints?
This page is an overview and auth guide. The complete, current endpoint list for your deployment is available in-app — the endpoint set evolves with the product, so the app is the authoritative source.
Is the API rate limited?
Yes. Requests are rate limited per principal. Pace your calls and handle 429 responses by backing off and retrying; do not poll in a tight loop.