BuildPulse Badges API

openapi: 3.2.0
info:
  title: BuildPulse Platform Badges API
  version: 1.0.0
  summary: Public REST API for BuildPulse CI analytics.
  termsOfService: https://buildpulse.io/terms
  description: 'The BuildPulse Platform API exposes read-only test analytics for any

    repository onboarded to BuildPulse: paginated test submissions,

    disruptive/flaky test inventory, per-test disruption history, and SVG

    badges for flakiness and coverage. This API is the drop-in replacement for the legacy Rails API at

    `https://buildpulse.io/api`. Endpoint paths, query parameters, and

    response JSON shapes are intentionally identical so existing

    integrations migrate by changing only the base URL. ## Base URLs


    - Production: `https://platform.buildpulse.io`

    - Development: `https://platform.dev.buildpulse.io`


    ## Authentication


    All endpoints except `/health` require an API token in the

    `Authorization` header. Both `token ` and `Bearer `

    prefixes are accepted. Two token shapes are accepted:


    - **New** (`bp_`) — minted by the BuildPulse web app under

    Organization Settings → API Tokens. SHA256-hashed (lowercase hex)

    and stored in `apiTokens` as

    `{ type: "api_token", tokenPrefix, tokenHash, expiresAt }`. Plan-gated: the organization needs an active plan that includes

    API access (Team, Growth, custom, or a paid legacy Marketplace

    plan; the 14-day trial counts). The same gate applies to the

    hosted MCP''s `mcpSessions`. - **Legacy** (``) — Rails-era format, stored as

    `{ hashedToken: base64(SHA256(token)) }`. Gated against

    `marketplacePurchases.unitCount > 0` for parity with the legacy

    API. Production currently holds zero of these; the path is

    retained for any future migrated tokens. The plaintext token is shown only once at creation time. Example values (do not use):


    ```

    Authorization: Bearer bp_14f56e0c2a8b4d1f9e6a3c7b8d2e5f1a0b9c4d7e6f3a2b1c0d9e8f7a6b5c4d3e

    Authorization: token a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0

    ```


    ## Response shapes


    JSON timestamps are ISO 8601 with second precision in UTC

    (e.g. `2026-05-17T12:34:56Z`). List endpoints always return an array

    for the data field, never `null`. Empty results return `[]`. ## Errors


    | Status | Body |

    |--------|------|

    | 401 | empty |

    | 404 | `{"message":"Not Found"}` |

    | 400 | `{"errors":{"after":[""]}}` |

    | 500 | empty |


    The empty-body 401/500 contract matches the legacy Rails behavior

    (`render body: nil`) and is preserved deliberately. ## Pagination


    Two cursor styles are in use, both base64-encoded so consumers should

    treat them as opaque:


    - **Keyset (submissions only)** — cursor is `base64("id:")`. Stable under inserts. - **Offset (tests, flaky tests)** — cursor is `base64("offset:")`. The next-page cursor is returned as `metadata.after`. When there is

    no next page, `metadata.after` is `null`. ## Reporting window


    Time-bounded endpoints use a rolling window ending now. Which window

    depends on the endpoint:


    | Endpoint | Window |

    |---|---|

    | `GET /api/v1/flaky/tests?quarantine=false` | Your plan''s reporting period (default 14 days) |

    | `GET /api/tests/{id}/results` | Your plan''s reporting period (default 14 days) |

    | `GET /api/v1/flaky/tests` (quarantined view, the default) | Not windowed — every quarantined test is returned |

    | `GET /api/repos/{owner}/{name}/tests` | Not windowed — every test with a disruptiveness ratio above 0 |

    | `GET /api/repos/{owner}/{name}/submissions` | Fixed 14 days |

    | `GET /api/v1/flaky/badges` | Fixed 14 days |


    The plan''s reporting period is resolved per organization from its

    active plan, so it follows plan changes automatically; there is no

    request parameter to override it. Organizations without a resolvable

    plan get the 14-day default. Don''t hardcode a window client-side —

    treat the returned rows as the source of truth. ## For AI agents (MCP)


    The BuildPulse MCP server exposes this API as nine read-only tools

    for Claude, ChatGPT, Cursor, VS Code, and any Model Context

    Protocol client. Hosted: `https://mcp.buildpulse.io/mcp`

    (Streamable HTTP, OAuth sign-in with your BuildPulse account). Stdio: `npx -y @buildpulse/mcp` with `BUILDPULSE_TOKEN` set to an

    API token. Setup and tool list:

    https://platform.buildpulse.io/docs/mcp.'
  license:
    name: Proprietary
    url: https://buildpulse.io/terms
  contact:
    name: BuildPulse Support
    email: support@buildpulse.io
    url: https://buildpulse.io
servers:
- url: https://platform.buildpulse.io
  description: Production
- url: https://platform.dev.buildpulse.io
  description: Development
security:
- TokenAuth: []
- BearerAuth: []
tags:
- name: Badges
  description: SVG status badges (flakiness, coverage).
paths:
  /api/v1/flaky/badges:
    get:
      operationId: flakyBadge
      tags:
      - Badges
      summary: Render a flakiness SVG badge for a repository
      description: 'Returns an SVG status badge showing the flakiness percentage for

        the named repository over the last 14 days.


        Color thresholds: 0% = green, 1–20% = yellow, >20% = red.


        Embed in a README:


        ```markdown

        !flakiness

        ```


        Note: badge endpoints require the same token authentication as

        the rest of the API. The legacy badge endpoints were

        unauthenticated; that was an oversight and is fixed here.'
      parameters:
      - in: query
        name: repository
        required: true
        schema:
          type: string
        description: Repository name (case-insensitive).
        example: widgets
      responses:
        '200':
          description: SVG badge image.
          content:
            image/svg+xml:
              schema:
                type: string
                format: binary
              example: '<svg xmlns="http://www.w3.org/2000/svg" width="210" height="20">…</svg>

                '
        '400':
          description: Missing `repository` parameter.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-codeSamples:
      - lang: shell
        label: curl
        source: "curl -H \"Authorization: token $BUILDPULSE_TOKEN\" \\\n  \"https://platform.buildpulse.io/api/v1/flaky/badges?repository=widgets\" \\\n  -o flakiness.svg\n"
  /api/v1/coverage/badges:
    get:
      operationId: coverageBadge
      tags:
      - Badges
      summary: Render a coverage SVG badge for a repository
      description: 'Returns an SVG status badge showing the latest coverage

        percentage for the named repository. The most-recently-uploaded

        coverage report is used, regardless of branch.


        Color thresholds: 100% = green, 90–99% = light green, 70–89% =

        yellow, <70% = red.


        Embed in a README:


        ```markdown

        !coverage

        ```'
      parameters:
      - in: query
        name: repository
        required: true
        schema:
          type: string
        description: Repository name (case-insensitive).
        example: widgets
      - in: query
        name: branch_or_pr
        schema:
          type: string
        description: 'Reserved for future branch-/PR-specific coverage selection.

          Currently ignored; the most recent report is always used.

          '
      responses:
        '200':
          description: SVG badge image.
          content:
            image/svg+xml:
              schema:
                type: string
                format: binary
        '400':
          description: Missing `repository` parameter.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-codeSamples:
      - lang: shell
        label: curl
        source: "curl -H \"Authorization: token $BUILDPULSE_TOKEN\" \\\n  \"https://platform.buildpulse.io/api/v1/coverage/badges?repository=widgets\" \\\n  -o coverage.svg\n"
components:
  schemas:
    NotFoundError:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          enum:
          - Not Found
  responses:
    Unauthorized:
      description: 'Missing, malformed, or invalid token; or — for legacy 40-hex

        tokens only — the organization has no active plan

        (`marketplacePurchases.unitCount > 0`). The new `bp_<64-hex>`

        path has no plan gate, so a 401 there means the token shape

        was wrong, the hash didn''t match, or the token has expired.

        Response body is empty (matches legacy Rails).

        '
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFoundError'
          example:
            message: Not Found
  securitySchemes:
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: "Send `Authorization: token <token>`. Two token shapes are\naccepted:\n\n- **New** (`bp_<64-hex>`) — minted by the refactored web-client\n  today (`web-client/src/app/_services/apiTokens.ts`). Stored as\n  `{ type: \"api_token\", tokenPrefix, tokenHash (hex SHA256),\n  expiresAt }`. No active-plan gate; issuance is the\n  entitlement check.\n- **Legacy** (`<40-hex>`) — Rails-era format, stored as\n  `{ hashedToken: base64(SHA256(token)) }`. Plan-gated against\n  `marketplacePurchases.unitCount > 0`. Retained for any future\n  migrated tokens.\n\nThe legacy API only accepted `token`, so existing integrations\nneed no changes.\n"
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: bp_<64-hex> or <40-hex>
      description: 'Send `Authorization: Bearer <token>`. Functionally identical to

        `TokenAuth`; both header forms are accepted. Same two token

        shapes apply — see `TokenAuth` for the format and plan-gate

        details.

        '
externalDocs:
  description: BuildPulse docs, MCP server and guides
  url: https://platform.buildpulse.io/docs/mcp