API reference.

One HTTPS API, called with curl from any pipeline. Nothing to install and nothing to run: the CI integration is this API and an example to copy.

BitHive Reporting Desk API · 0.11.0

Authentication

Every request carries an API token as a bearer token: "Authorization: Bearer <token>". Tokens are created in the application, carry scopes, may be limited to one product, and expire. A token that is unknown, expired or revoked is answered with 401 and a problem document.

Scopes

A token carries the scopes it was given, and nothing else. An endpoint that needs a scope the token does not carry answers 403; the scope each one needs is named with it below.

Scope	Allows
`products:read`	Read the account's products.
`sboms:read`	Read uploaded bills of materials, their components and the stored document.
`sboms:write`	Upload bills of materials, name their releases and put them on the market or take them off.
`findings:read`	Read a product's findings and its coverage.
`sboms:upload`	Upload bills of materials and nothing else; the upload also accepts sboms:write.
`cases:read`	Read the CRA cases with their deadlines and the state of each stage's report.
`records:read`	Read the incident records with their obligations and deadlines, as the token's creator sees them.
`records:write`	Create incident records and record reports as submitted; beta accounts only.
`findings:decide`	Record VEX statements on a product's findings, as the token's creator may.

Rate limits

Two limits, both counted per hour. A token may make 600 requests in an hour; an address that presents tokens that do not work is turned away after 20 failures. Over either one, the answer is 429 with a Retry-After header saying how long the window is.

Errors

Every endpoint can answer with these, so they are here once rather than on each. The body is a problem document (RFC 9457), and the content type is application/problem+json. Only the answers particular to an endpoint are listed with it.

Status	What it means
`401`	The API token is missing, unknown, expired or revoked.
`403`	The API token does not carry the required scope, or, for a write, the account is suspended because a payment is outstanding or its subscription has ended. Reading continues in both cases; the detail says which applies.
`404`	The resource does not exist, or the token may not see it.
`405`	The resource does not support this method.
`413`	The document is larger than 10 MiB.
`429`	The caller is over one of the two limits: requests for this token, or failed authentications from this address. Retry-After says how long the window is.

Example

{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "The API token is unknown, expired or revoked."
}

Servers

https://app.bithive-it.com Production

Products

GET List the products of the account /v1/products
GET Read one product /v1/products/{productId}

Bills of materials

GET List the uploads of one product /v1/products/{productId}/sboms
POST Upload a bill of materials for a product /v1/products/{productId}/sboms
GET Read one upload /v1/sboms/{sbomId}
PATCH Name a release, or put it on the market or take it off /v1/sboms/{sbomId}
GET Read the component index of one upload /v1/sboms/{sbomId}/components
GET Download the document as it was uploaded /v1/sboms/{sbomId}/document

Findings and coverage

GET List what was found in a product /v1/products/{productId}/findings
POST Record a VEX statement on a product's findings /v1/products/{productId}/decisions
GET Read the statements on one release and vulnerability /v1/products/{productId}/decisions/history
GET Download a product's VEX document /v1/products/{productId}/vex
GET Read how much of a product can be checked /v1/products/{productId}/coverage

Cases

GET List the CRA cases /v1/cases
GET Read one CRA case with its deadlines and the state of its reports /v1/cases/{caseId}

Incident records

GET List the incident records /v1/records
POST Create an incident record /v1/records
GET Read one incident record with its obligations and deadlines /v1/records/{recordId}
POST Record a stage's report as submitted /v1/records/{recordId}/submissions
POST Archive a contract /v1/contracts/{contractId}/archive
POST Restore an archived contract /v1/contracts/{contractId}/restore

What comes back

The contract itself. This page is built from the OpenAPI document of the service. It is published as a file, so a client generator can read the same contract this page describes. Download openapi.yaml

Docs

Start free 14-day trial