Using the API
The API reference lists every operation, with its parameters, request bodies and answers. This page covers what they all share.
Base URL
Section titled “Base URL”Every route starts with /v1. For collectors, CI pipelines, scripts and integrations, use the API host: https://api.affectra.eu/v1. The web app host forwards /v1 to the same API for the browser, so https://app.affectra.eu/v1 answers too. Only the app host serves the sign-in routes under /v1/auth/.
Most routes name your organization in the path: /v1/orgs/{org}/.... A key can only act in its own organization. A request for another organization’s object answers 404, the same as for one that does not exist. The organization is never read from the request body.
Credentials
Section titled “Credentials”Send an API key as a bearer token:
curl --fail-with-body --silent --show-error \ --header "Authorization: Bearer $AFFECTRA_API_KEY" \ "https://api.affectra.eu/v1/orgs/acme/products"A key is either Read only or Can propose changes. A read-only key reads. A key that can propose changes also uploads SBOMs and build provenance, sends collector reports, records VEX statements and files proposals. It never manages members, keys or settings. A key that is not allowed to do something gets 403. Roles and what each may do has the full table.
An uploading CI job may use the GitHub Actions token of a trusted publisher instead of a key, on the upload routes only. Without a credential, a route answers 401. The routes that need none say so in the reference.
Errors
Section titled “Errors”An error answers with a JSON body of type application/problem+json (RFC 9457):
| Field | What it holds |
|---|---|
status |
The HTTP status again. |
code |
A stable code such as request.invalid or auth.roleTooLow. |
detail |
An English sentence for people reading logs. Its wording can change. |
params |
Values the message needs, such as {"field": "version"}. Empty if none. |
Match on code, never on detail. A code is never renamed. New codes can appear, so treat one you do not know by its HTTP status.
A query parameter with a value the route doesn’t take is refused with 400 and request.invalid, the parameter in params.field. Yes-or-no parameters such as history and open take true or false (1 and 0 work too). include takes only resolved.
Rate limits
Section titled “Rate limits”Every route belongs to a budget, counted per credential: report, upload, write, read or public. Each operation page names its budget. When a request is over its budget, the API answers 429 Too Many Requests with the code request.rateLimited, the budget in params.budget, and a Retry-After header with the seconds to wait. Wait at least that long.
The public budget is counted per client address, not per credential. It covers the routes that need no credential, and requests whose credential the API refuses, such as a revoked or mistyped key. If requests from one address keep sending refused credentials, the API answers 429 with budget public to every request from that address that carries a credential, a valid key too, until Retry-After has passed. So when a key stops working, fix it before retrying in a loop: the retries can hold up your other keys on the same machine.
Requests that were checked against a budget carry two more headers, whether they were allowed or not: RateLimit-Policy (for example "read";q=600;w=60: 600 requests at once, refilled over 60 seconds) and RateLimit (for example "read";r=599;t=1: 599 more are allowed now). They follow an IETF draft and can change with it. Retry-After is the part you can rely on. The numbers differ between deployments.
Pagination
Section titled “Pagination”Most lists return everything they have. The list of proposals is paged: pass limit (1 to 200, 50 by default), and before with the next value of the previous page. next is null on the last page.
Versioning
Section titled “Versioning”The paths carry the major version, /v1. The API description has its own version, shown on the API reference overview. GET /v1/version answers with the version and commit of the running build.
Some routes are left out of this reference because they are not announced yet. Do not build on routes that are not described here.