API reference

Generated file

This page is generated from the zod contracts and the router definitions at build time. Edit packages/contracts/src/rest.ts or the schemas themselves, not this page.

Flakemetry exposes two surfaces: a REST API for ingestion and CI integrations, authenticated with a per-project ingest token, and a tRPC API for dashboard queries.

REST

All request and response bodies are JSON. Write endpoints validate against the schemas below and reject anything that does not match, so a malformed upload fails fast rather than corrupting history.

GET /health

Liveness probe. Used by containers and load balancers.

Auth: none

Returns: { status: "ok", service: "api" }

POST /v1/ingest

Ingest one test run. Validated and enqueued, then acknowledged immediately — this never blocks CI.

Auth: project token with the ingest scope (Authorization: Bearer …)

Returns: 202 with { receiptId, acceptedExecutions }

IngestRunBatch

Field	Type	Required	Notes
contractVersion	string	yes
idempotencyKey	string	yes
resource	object	yes
run	object	yes
executions	object[]	yes

POST /v1/ingest/junit

Ingest a JUnit XML report directly, for CI that cannot run the CLI. Parsed server-side into the same run batch the CLI would have sent.

Auth: project token with the ingest scope (Authorization: Bearer …)

Returns: 202 with { receiptId, acceptedExecutions }

JunitIngestRequest

Field	Type	Required	Notes
idempotencyKey	string	yes
resource	object	yes
xml	string	yes

POST /v1/traces

OTLP-HTTP trace ingestion for reporters that emit spans directly.

Auth: project token with the ingest scope (Authorization: Bearer …)

Returns: 202 with { receiptId, acceptedExecutions }

OtlpTraceRequest

Field	Type	Required	Notes
resourceSpans	object[]	no

POST /v1/artifacts/presign

Request a presigned upload URL so a reporter can push screenshots, video and traces straight to object storage.

Auth: project token with the ingest scope (Authorization: Bearer …)

Returns: { url, key, headers }, or 404 when artifact storage is disabled

ArtifactPresignRequest

Field	Type	Required	Notes
idempotencyKey	string	yes
artifacts	object[]	yes

GET /v1/runs/summary

Roll-up for one commit, used by the PR comment action.

Auth: project token with the ingest scope (Authorization: Bearer …)

Returns: Run summary for the commit, or 404 when it has not been ingested

GET /v1/runs/gate

Quality-gate verdict for a commit: which failures are new versus already flaky on the base branch.

Auth: project token with the ingest scope (Authorization: Bearer …)

Returns: Gate verdict with per-test classification

PUT /v1/codeowners

Upload the repository CODEOWNERS file so tests can be attributed to their owners.

Auth: project token with the ingest scope (Authorization: Bearer …)

Returns: { ok: true }

CodeownersUpload

Field	Type	Required	Notes
content	string	yes

PUT /v1/notifications/routing

Upload notification routing from flakemetry.yml, replacing the config-managed channels.

Auth: project token with the ingest scope (Authorization: Bearer …)

Returns: { ok: true, channels }

POST /v1/tests/:testIdentityId/quarantine

Quarantine a test, release it, or hand it back to the scorer. A quarantined or released decision is a person overriding the automation, and the scorer stops moving that test until auto returns it.

Auth: project token with the quarantine scope (Authorization: Bearer …)

Returns: { quarantined, override, changed }, or 404 when the test is not in this project

QuarantineSetRequest

Field	Type	Required	Notes
decision	"quarantined" | "released" | "auto"	yes	quarantined and released are a person deciding; auto returns the test to the scorer
reason	string	no	Why, shown beside the test

GET /openapi.json

Machine-readable description of the read API, generated from the route table.

Auth: none

Returns: An OpenAPI 3.1 document

GET /v1/runs

List runs newest first, cursor-paginated.

Auth: project token with the read scope (Authorization: Bearer …)

Returns: { items, nextCursor }

GET /v1/runs/:runId

One run with its execution counts.

Auth: project token with the read scope (Authorization: Bearer …)

Returns: A run, or 404

GET /v1/tests/:testIdentityId

One test identity with its recent execution history.

Auth: project token with the read scope (Authorization: Bearer …)

Returns: A test identity, or 404

GET /v1/flaky

The flaky board: scored tests, worst first.

Auth: project token with the read scope (Authorization: Bearer …)

Returns: { items }

GET /v1/executions/:executionId/rca

Root-cause analysis for one execution, when there is one.

Auth: project token with the read scope (Authorization: Bearer …)

Returns: An RCA report, or null

GET /v1/health

Project health metrics over a window.

Auth: project token with the read scope (Authorization: Bearer …)

Returns: Health metrics

GET /v1/export

Every row this project holds, streamed as a gzipped NDJSON archive: a manifest line, one line per row, an artifact inventory and a closing summary. Ingest token hashes and webhook signing secrets are left out.

Auth: project token with the read scope (Authorization: Bearer …)

Returns: application/gzip, saved as flakemetry-<project>-<date>.ndjson.gz

tRPC

The dashboard query API. Every procedure is scoped to the project the token belongs to.

runs.list

Paginated run history, filterable by branch, status and time range.

RunsListInput

Field	Type	Required	Notes
branch	string	no
status	"running" | "passed" | "failed" | "canceled"	no
since	string (date-time)	no
until	string (date-time)	no
cursor	string	no
limit	integer	no

run.get

One run with its executions.

RunGetInput

Field	Type	Required	Notes
runId	string	yes

test.get

One test identity: score, reason codes, stitch history and recent executions.

TestGetInput

Field	Type	Required	Notes
testIdentityId	string	yes
historyLimit	integer	no

flaky.board

The flaky board — tests ranked by score, optionally scoped to an owner.

FlakyBoardInput

Field	Type	Required	Notes
limit	integer	no
minScore	number	no
includeQuarantined	boolean	no
owner	string	no

rca.get

The root-cause report for one execution, when one exists.

RcaGetInput

Field	Type	Required	Notes
executionId	string	yes

health.metrics

Flaky MTTR, introduced-versus-resolved and quarantine backlog, optionally per team.

TestHealthInput

Field	Type	Required	Notes
days	integer	no
owner	string	no