API¶
Everything the UI and the CLI do goes through the HTTP API at /api/v1. It is described by OpenAPI:
- API reference (Swagger UI) for the current release, on this site;
GET /api/openapi.jsonand the Swagger UI at/api/docson your own server, matching its version exactly.
Conventions¶
- Authentication:
Authorization: Bearer <token>with a managed token (fp_...), a static token or an OIDC access token (whenFASTPROOF_OIDC_API_AUDIENCEis set). Browser sessions use cookies plus theX-FransHub-Request: 1header on writes. - JSON field names are camelCase. Ids are UUIDs (version 7). Project keys match
^[a-z0-9][a-z0-9-]{1,62}$. - Errors have one shape:
{"code": "...", "message": "...", "details": {...}}.401never tells why a credential was refused;403names the missing permission indetails.required. - Lists return
{"items": [...], "next": "..."}. Passnextasbeforeto get the next page;limitdefaults to 50, at most 500.
Main resources¶
| Resource | Endpoints |
|---|---|
| Projects | GET/POST /api/v1/projects, GET/PATCH/DELETE /api/v1/projects/{key} |
| Launches | POST /api/v1/projects/{key}/launches (idempotent by externalId), GET .../launches with filters branch, environment, status, attr=k:v, q, debug; GET/DELETE .../launches/{id}, POST .../launches/{id}/finish |
| Uploads | POST .../launches/{id}/uploads?format=auto\|allure\|junit\|ctrf\|playwright&fileName= (raw body or multipart field file, answers 202), GET .../launches/{id}/uploads |
| Streaming results | POST .../launches/{id}/results (FastProof JSON: one object, an array, or NDJSON) |
| Attachments | POST .../launches/{id}/attachments, GET /api/v1/projects/{key}/attachments/{id}/content |
| Results | GET .../launches/{id}/results with status, q, suite, label=k:v, flaky, fingerprint; GET .../launches/{id}/tree?groupBy=suite\|feature\|package; GET /api/v1/projects/{key}/results/{id} |
| History | GET /api/v1/projects/{key}/test-cases/{testCaseId}/history?branch=&environment= |
| Live events | GET /api/v1/projects/{key}/events (Server-Sent Events: launch.updated, upload.updated) |
| Identity and tokens | GET /api/v1/me, /api/v1/tokens |
| Audit | GET /api/v1/audit |
Example: a launch with two shards¶
api=https://fastproof.example.com/api/v1/projects/web
auth="Authorization: Bearer $FASTPROOF_TOKEN"
launch=$(curl -fsS -X POST "$api/launches" -H "$auth" -H 'Content-Type: application/json' \
-d '{"externalId":"pipeline-4711","name":"e2e","vcs":{"repository":"shop","branch":"main","commit":"3f2c1e0"}}' \
| jq -r .id)
tar -czf shard1.tar.gz -C shard1 allure-results
curl -fsS -X POST "$api/launches/$launch/uploads?format=allure&fileName=shard1.tar.gz" \
-H "$auth" -H 'Content-Type: application/gzip' --data-binary @shard1.tar.gz
curl -fsS -X POST "$api/launches/$launch/uploads?fileName=junit.xml" \
-H "$auth" -H 'Content-Type: application/xml' --data-binary @shard2/junit.xml
curl -fsS -X POST "$api/launches/$launch/finish" -H "$auth" -H 'Content-Type: application/json' -d '{}'
Starting the launch again with the same externalId returns the existing launch (200 instead of 201),
so every shard can run the first call safely.