BuildPulse Flaky API

openapi: 3.2.0
info:
  title: BuildPulse Platform Flaky 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: Flaky
  description: Cross-repo flaky test inventory with optional field expansion.
paths:
  /api/v1/flaky/tests:
    get:
      operationId: listFlakyTests
      tags:
      - Flaky
      summary: List flaky tests with optional field expansion
      description: 'Returns flaky tests for the named repository. Exactly one of

        `repository` (name) or `repository_id` (legacy numeric ID from

        the Rails API era) must be supplied; omitting both returns

        `400`.


        ### Optional fields


        By default the response is a minimal shape: `id`, `name`,

        `suite`, `class`, `file`. Pass `include=field1,field2,…` to

        expand any of:


        - `disruptiveness_ratio`

        - `nondeterministic_negative_result_count`

        - `nondeterminism_first_recorded_at`

        - `recent_nondeterministic_commit_oid`

        - `recent_nondeterministic_negative_result`

        - `recent_nondeterministic_positive_result`

        - `tags`

        - `quarantine_date`

        - `quarantined_by`

        - `quarantine_type`

        - `time_consumed`

        - `pass_rate`

        - `avg_duration_ms`


        Unknown fields are silently dropped.


        ### Quarantine


        **This endpoint returns quarantined tests by default.** Pass

        `quarantine=false` to get non-quarantined flaky tests instead.

        The two modes are mutually exclusive — a test is either

        quarantined or it isn''t — and together they cover every flaky

        test on the repository.


        | Request | Returns |

        | --- | --- |

        | `?repository=widgets` | Quarantined tests (**default**) |

        | `?repository=widgets&quarantine=false` | Non-quarantined tests, within the reporting window |


        Only the literal value `false` selects the non-quarantined view;

        any other value (including `0`) is treated as `true`, matching

        the legacy API. `quarantined` is accepted as an alias for

        `quarantine`.


        ### Reporting window


        The **non-quarantined** view only returns tests that were

        disruptive within your plan''s reporting period (default 14

        days). This bounds the response to currently-relevant flakes

        rather than every flake ever recorded.


        The **quarantined** view is deliberately *not* windowed: a test

        quarantined a year ago is still quarantined, so it is still

        returned.


        ### Per-occurrence history


        Each returned `id` is a test (disruptor) ID that can be passed

        to `GET /api/tests/{id}/results` to fetch that test''s recent

        disruption events (build URL, commit, failure message,

        timestamp) — the typical pattern for scripted triage reports:

        list the inventory here, then fetch history per test.'
      parameters:
      - in: query
        name: repository
        schema:
          type: string
        description: 'Repository name (case-insensitive). Required unless

          `repository_id` is supplied. Omitting both returns `400`.

          '
        example: widgets
      - in: query
        name: repository_id
        schema:
          type: string
        description: 'Legacy numeric repository ID (from the Rails era). Used when

          migrating older integrations that didn''t have repo names

          available at call time.

          '
      - $ref: '#/components/parameters/Limit25'
      - $ref: '#/components/parameters/AfterCursor'
      - in: query
        name: include
        schema:
          type: string
        description: 'Comma-separated list of optional fields to include. See

          description above for the allowed set.

          '
        example: disruptiveness_ratio,tags,recent_nondeterministic_negative_result
      - in: query
        name: quarantine
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
          default: 'true'
        description: 'Which set of flaky tests to return. Defaults to `true`

          (quarantined tests only). Set to `false` to return

          non-quarantined tests from the reporting window instead.


          Only the literal `false` selects the non-quarantined view;

          any other value is treated as `true`.

          '
        example: 'true'
      - in: query
        name: quarantined
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
        description: 'Alias for `quarantine`. If both are supplied, `quarantine`

          wins.

          '
      - $ref: '#/components/parameters/Sort'
      - $ref: '#/components/parameters/Q'
      responses:
        '200':
          description: Paginated flaky tests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlakyTestsResponse'
              example:
                count: 1
                tests:
                - id: 65d4f1a8b3c2d1e0f9a8b7c6
                  name: test_login
                  suite: auth
                  class: AuthTest
                  file: test/auth.rb
                  disruptiveness_ratio: 0.375
                  tags:
                  - network
                  - auth
                metadata:
                  after: null
                  limit: 25
        '400':
          $ref: '#/components/responses/BadCursor'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PlanLimitExceeded'
        '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/tests?repository=widgets&include=disruptiveness_ratio,tags\"\n"
      - lang: javascript
        label: Node
        source: "const url = new URL(\"https://platform.buildpulse.io/api/v1/flaky/tests\");\nurl.searchParams.set(\"repository\", \"widgets\");\nurl.searchParams.set(\"include\", \"disruptiveness_ratio,tags\");\nconst res = await fetch(url, {\n  headers: { Authorization: `token ${process.env.BUILDPULSE_TOKEN}` },\n});\n"
      - lang: python
        label: Python
        source: "import os, requests\nr = requests.get(\n  \"https://platform.buildpulse.io/api/v1/flaky/tests\",\n  headers={\"Authorization\": f\"token {os.environ['BUILDPULSE_TOKEN']}\"},\n  params={\n    \"repository\": \"widgets\",\n    \"include\": \"disruptiveness_ratio,tags\",\n  },\n)\ndata = r.json()\n"
components:
  schemas:
    NotFoundError:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          enum:
          - Not Found
    FlakyTest:
      type: object
      description: 'Base shape (no `include` param). Add fields by listing them in

        the `include` query parameter — see endpoint description for the

        whitelist.

        '
      required:
      - id
      - name
      - suite
      - class
      - file
      properties:
        id:
          type: string
        name:
          type: string
        suite:
          type: string
        class:
          type: string
        file:
          type: string
        disruptiveness_ratio:
          type: number
          format: float
          description: Only present when `include` lists `disruptiveness_ratio`.
        disruption_count:
          type: integer
          description: Only present when `include` lists `nondeterministic_negative_result_count`.
        first_disruption_at:
          type: string
          format: date-time
          description: Only present when `include` lists `nondeterminism_first_recorded_at`.
        recent_disruption_commit_oid:
          type: string
          description: Only present when `include` lists `recent_nondeterministic_commit_oid`.
        recent_nondeterministic_negative_result:
          $ref: '#/components/schemas/Result'
        recent_nondeterministic_positive_result:
          $ref: '#/components/schemas/Result'
        tags:
          type: array
          items:
            type: string
        quarantine_date:
          type:
          - string
          - 'null'
          format: date-time
        quarantined_by:
          type:
          - string
          - 'null'
        quarantine_type:
          type:
          - string
          - 'null'
        time_consumed:
          type: integer
          format: int64
        pass_rate:
          type: number
          format: float
          description: 'Fraction of runs in which this test passed (0.0–1.0). Only

            present when `include` lists `pass_rate`.

            '
        avg_duration_ms:
          type: number
          format: float
          description: 'Average per-attempt duration in milliseconds across all

            recorded runs of this test. Only present when `include`

            lists `avg_duration_ms`.

            '
    FlakyTestsResponse:
      type: object
      required:
      - count
      - tests
      - metadata
      properties:
        count:
          type: integer
          format: int64
        tests:
          type: array
          items:
            $ref: '#/components/schemas/FlakyTest'
        metadata:
          $ref: '#/components/schemas/Metadata'
    Result:
      type: object
      required:
      - recorded_at
      - build_url
      - message
      properties:
        recorded_at:
          type: string
          format: date-time
        build_url:
          type: string
          format: uri
        message:
          type:
          - string
          - 'null'
          description: 'Failure message (negative result) or always `null`

            (positive result, to match legacy behavior).

            '
    PlanLimitError:
      type: object
      required:
      - code
      - message
      - upgradeUrl
      properties:
        code:
          type: string
          enum:
          - plan_limit_exceeded
          description: Stable machine-readable code; consumers key off this, not the message.
        message:
          type: string
          description: Human-readable explanation.
        upgradeUrl:
          type: string
          format: uri
          description: Deep link to billing/upgrade so access can be restored.
    CursorError:
      type: object
      required:
      - errors
      properties:
        errors:
          type: object
          required:
          - after
          properties:
            after:
              type: array
              items:
                type: string
    Metadata:
      type: object
      required:
      - after
      - limit
      properties:
        after:
          type:
          - string
          - 'null'
          description: Opaque cursor for the next page; `null` if there is no next page.
        limit:
          type: integer
  responses:
    BadCursor:
      description: Cursor failed to decode.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CursorError'
          example:
            errors:
              after:
              - invalid cursor format
    PlanLimitExceeded:
      description: 'The organization is over its plan''s monthly test-result limit and

        data-read access is restricted (staged-overage stage `soft` or

        `hard`). At `soft` the data is locked but safe — ingestion keeps

        recording. At `hard` ingestion is also paused (raw retained ~30

        days) and an upgrade resumes processing. Read `GET /api/v1/usage`

        for the current stage and usage, and visit `upgradeUrl` to restore

        access. Only returned for organizations positively identified as

        over the enforced limit while enforcement is enabled.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlanLimitError'
          example:
            code: plan_limit_exceeded
            message: Your organization has exceeded its plan's monthly test-result limit. Your data is safe but locked — upgrade your plan to restore access.
            upgradeUrl: https://buildpulse.io/settings/billing
    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
  parameters:
    Limit25:
      in: query
      name: limit
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
      description: Page size. Clamped to `[1, 100]`.
    Sort:
      in: query
      name: sort
      schema:
        type: string
        enum:
        - disruptivenessRatio
        - recency
        default: disruptivenessRatio
      description: 'Sort order. `recency` sorts by `latestDisruptionAt` descending.

        '
    Q:
      in: query
      name: q
      schema:
        type: string
      description: 'Structured query string. See `/api/repos/{owner}/{name}/tests`

        description for the full grammar.

        '
      example: last-seen:>=2026-05-01 tags:auth login
    AfterCursor:
      in: query
      name: after
      schema:
        type: string
      description: 'Opaque pagination cursor from a previous response''s

        `metadata.after`. Pass back verbatim.

        '
  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