# BuildPulse Platform API

> Public REST API for BuildPulse CI analytics. Returns paginated test
> submissions, per-run test results, disruptive/flaky test inventory,
> per-test disruption history, organization usage, and SVG status
> badges. Drop-in replacement for the legacy Rails API at
> https://buildpulse.io/api — same paths, same JSON shapes.

The API is read-only and token-authenticated. Flaky-test endpoints are
windowed by your plan's reporting period (default 14 days); submissions
and badges use a fixed 14 days. Two
token shapes are accepted, sent as either `Authorization: token <token>`
or `Authorization: Bearer <token>`:

- **New** (`bp_<64-hex>`) — the format minted by the BuildPulse web app
  under Organization Settings → API Tokens (e.g.
  `bp_14f56e0c2a8b4d1f9e6a3c7b8d2e5f1a0b9c4d7e6f3a2b1c0d9e8f7a6b5c4d3e`).
  Requires an active plan with API access (Team, Growth, custom, or a
  paid legacy Marketplace plan; the 14-day trial counts).
- **Legacy** (`<40-hex>`) — Rails-era format
  (e.g. `a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0`). Gated against
  `marketplacePurchases.unitCount > 0`. Retained for any future
  migrated tokens.

Base URL is `https://platform.buildpulse.io`.

## Spec

- [OpenAPI 3.1 spec](https://platform.buildpulse.io/openapi.yaml)
- [Rendered docs (Scalar)](https://platform.buildpulse.io/docs/)

## Reference

- [llms-full.txt](https://platform.buildpulse.io/llms-full.txt): Full prose reference with all endpoints, parameters, response shapes, and worked examples in curl/Node/Python.

## Endpoints (summary)

- `GET /health` — Liveness probe; no auth; returns `{"status":"ok"}`.
- `GET /api` — Validates the token; returns 204.
- `GET /api/me/organizations` — Organizations the current token may scope requests to (one entry for API tokens; every accessible org for hosted-MCP OAuth sessions).
- `GET /api/me/repositories` — Repositories scoped to the caller's current organization (`?organization_id=` selects the org for multi-org sessions).
- `GET /api/v1/usage` — Current UTC-month test-result usage for the organization against its plan limit, with the staged-overage `status`; always open, never returns 402.
- `GET /api/repos/{owner}/{name}/submissions` — Paginated CI runs (test result sets) for one repo, last 14 days, keyset-paginated.
- `GET /api/repos/{owner}/{name}/submissions/{submission_id}/tests` — Per-test results recorded against one submission (one CI run); `status=failed` filters to failures and errors.
- `GET /api/repos/{owner}/{name}/tests` — Disruptive/flaky tests for one repo (disruptiveness ratio above 0), offset-paginated, with structured `q=` filter.
- `GET /api/tests/{id}/results` — Last 10 disruption events for a specific test; `id` comes from `/api/repos/{owner}/{name}/tests` or `/api/v1/flaky/tests`.
- `GET /api/v1/flaky/tests` — Flaky-test inventory for one repo (quarantined by default; `quarantine=false` for the rest) with optional field expansion via `include=`.
- `GET /api/v1/flaky/badges` — SVG flakiness badge.
- `GET /api/v1/coverage/badges` — SVG coverage badge.
- `POST /webhooks/github` — GitHub App webhook ingress (HMAC-verified); not a customer-callable endpoint.

## MCP server

A Model Context Protocol server exposes this API as nine tools for
Claude, ChatGPT, Cursor, VS Code, and any MCP-aware agent.

- Hosted endpoint: `https://mcp.buildpulse.io/mcp` (Streamable HTTP; OAuth 2.1 sign-in via the BuildPulse Cognito account, no token to copy)
- Claude Code: `claude mcp add --transport http buildpulse https://mcp.buildpulse.io/mcp`
- Stdio package: `npx -y @buildpulse/mcp` (npm: https://www.npmjs.com/package/@buildpulse/mcp)
- MCP Registry name: `io.github.BuildPulseLLC/buildpulse-mcp`
- Source: https://github.com/BuildPulseLLC/buildpulse-mcp
- [BuildPulse MCP setup and tool list](https://platform.buildpulse.io/docs/mcp)

## About BuildPulse

BuildPulse (https://buildpulse.io) is a CI analytics platform for
engineering teams on GitHub Actions and other CI providers. It detects
and quarantines flaky tests, runs faster and cheaper GitHub Actions
runners, tracks code coverage, reports engineering metrics from
existing CI data, and reviews pull requests with AI. This API is the
programmatic surface for the test-analytics data.

- [Flaky test detection](https://buildpulse.io/products/flaky-tests): automatic detection across every PR and branch, quarantine, Jira-linked triage.
- [Runners](https://buildpulse.io/products/runners): drop-in GitHub Actions runners that finish faster at lower cost.
- [Code coverage](https://buildpulse.io/products/code-coverage): coverage trends per branch and per file; LCOV and Cobertura.
- [Engineering metrics](https://buildpulse.io/products/engineering-metrics): pass rate, build duration, and flaky-test disruption.
- [Pricing](https://buildpulse.io/pricing): API and MCP access are included on Team, Growth, and custom plans.
- [Blog](https://buildpulse.io/blog)
- [Product docs and guides](https://docs.buildpulse.io)

## Optional

- [Landing page](https://platform.buildpulse.io/): human-readable overview of this API.
- [BuildPulse llms.txt](https://buildpulse.io/llms.txt): company-wide index covering products, pricing, and blog posts.
- [Terms of service](https://buildpulse.io/terms)
- Support: support@buildpulse.io