# BuildPulse Platform API

> Public REST API for BuildPulse CI analytics. Returns paginated test
> submissions, disruptive/flaky test inventory, per-test disruption
> history, 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, token-authenticated, and 14-day windowed. Tokens
are 40-char hex, sent as either `Authorization: token <hex>` or
`Authorization: Bearer <hex>`. 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/repos/{owner}/{name}/submissions` — Paginated CI runs (test result sets) for one repo, last 14 days, keyset-paginated.
- `GET /api/repos/{owner}/{name}/tests` — Disruptive/flaky tests for one repo, last 14 days, offset-paginated, with structured `q=` filter.
- `GET /api/tests/{id}/results` — Last 10 disruption events for a specific test.
- `GET /api/v1/flaky/tests` — Cross-repo flaky inventory with optional field expansion via `include=`.
- `GET /api/v1/flaky/badges` — SVG flakiness badge.
- `GET /api/v1/coverage/badges` — SVG coverage badge.

## MCP server

A Model Context Protocol server is available so agents (Claude Desktop, Cursor, Cline, etc.) can call this API directly. See:

- [BuildPulse MCP setup](https://platform.buildpulse.io/docs#mcp)
- npm: `npx @buildpulse/mcp`