API reference.

One HTTPS API, called with curl from any pipeline. Nothing to install, nothing to run: the CI integration is this API and a copy-paste example (ADR-0017).

BitHive Reporting Desk API · 0.4.1

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.

Servers

https://app.bithive-it.com Production
http://localhost:8080 Local development

Endpoints

GET`/healthz`

Liveness probe

Reports that the process is running. Checks no dependencies.

Answers

200 Process is alive. Liveness

Example

curl --fail-with-body -sS \
  -H "Authorization: Bearer $BITHIVE_TOKEN" \
  "https://app.bithive-it.com/healthz"

GET`/readyz`

Readiness probe

Reports whether all dependencies can serve traffic, as a status and nothing else: no dependency is named, and no version or error text is returned. The external uptime monitor polls it. Failure details are logged.

Answers

200 Ready to serve traffic. Readiness
503 At least one dependency is unavailable. Readiness

Example

curl --fail-with-body -sS \
  -H "Authorization: Bearer $BITHIVE_TOKEN" \
  "https://app.bithive-it.com/readyz"

GET`/v1/products`

List the products of the account

Returns the products the token may see: all products of the account, or only the one the token is limited to. Archived products are included and marked.

Answers

200 The products the token may see. ProductList
401 The API token is missing, unknown, expired or revoked.
403 The API token does not carry the required scope.
405 The resource does not support this method.

Example

curl --fail-with-body -sS \
  -H "Authorization: Bearer $BITHIVE_TOKEN" \
  "https://app.bithive-it.com/v1/products"

GET`/v1/products/{productId}`

Read one product

Returns the product. A product of another account, and a product the token is not limited to, are reported as not found.

Parameters

productId path, string (uuid), required Identifier of the product.

Answers

200 The product. Product
401 The API token is missing, unknown, expired or revoked.
403 The API token does not carry the required scope.
404 The resource does not exist, or the token may not see it.
405 The resource does not support this method.

Example

curl --fail-with-body -sS \
  -H "Authorization: Bearer $BITHIVE_TOKEN" \
  "https://app.bithive-it.com/v1/products/$PRODUCTID"

GET`/v1/products/{productId}/sboms`

List the uploads of one product

Returns the product's uploads, newest first. Requires the scope sboms:read.

Parameters

productId path, string (uuid), required Identifier of the product.

Answers

200 The uploads of the product. SBOMList
401 The API token is missing, unknown, expired or revoked.
403 The API token does not carry the required scope.
404 The resource does not exist, or the token may not see it.
405 The resource does not support this method.

Example

curl --fail-with-body -sS \
  -H "Authorization: Bearer $BITHIVE_TOKEN" \
  "https://app.bithive-it.com/v1/products/$PRODUCTID/sboms"

POST`/v1/products/{productId}/sboms`

Upload a bill of materials for a product

Stores a CycloneDX or SPDX document in JSON, at most 10 MiB, and indexes its components. The format is read from the document, not from the content type. Uploading the same bytes for the same product again answers 200 with the existing upload instead of storing a second one, so a build pipeline that runs twice on an unchanged tree is harmless.

Requires the scope sboms:write.

Parameters

productId path, string (uuid), required Identifier of the product.

Request body

The document itself, as sent by the build tool.

application/json
application/vnd.cyclonedx+json
application/spdx+json

Answers

200 The same document was already stored for this product; nothing changed. SBOM
201 The document was stored. SBOM
400 The document is empty, not JSON, in neither format, or lists something unusable.
401 The API token is missing, unknown, expired or revoked.
403 The API token does not carry the required scope.
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.
415 The content type is not one of the accepted JSON types.

Example

curl --fail-with-body -sS -X POST \
  -H "Authorization: Bearer $BITHIVE_TOKEN" \
  -H "Content-Type: application/vnd.cyclonedx+json" \
  --data-binary @sbom.json \
  "https://app.bithive-it.com/v1/products/$PRODUCTID/sboms"

GET`/v1/sboms/{sbomId}`

Read one upload

Returns the upload. An upload of another account, and one belonging to a product the token is not limited to, are reported as not found. Requires the scope sboms:read.

Parameters

sbomId path, string (uuid), required Identifier of the upload.

Answers

200 The upload. SBOM
401 The API token is missing, unknown, expired or revoked.
403 The API token does not carry the required scope.
404 The resource does not exist, or the token may not see it.
405 The resource does not support this method.

Example

curl --fail-with-body -sS \
  -H "Authorization: Bearer $BITHIVE_TOKEN" \
  "https://app.bithive-it.com/v1/sboms/$SBOMID"

GET`/v1/sboms/{sbomId}/components`

Read the component index of one upload

Returns every component the document listed, by name. The list is complete and needs no paging: a document may not carry more than 50,000 components. Requires the scope sboms:read.

Parameters

sbomId path, string (uuid), required Identifier of the upload.

Answers

200 The components of the upload. ComponentList
401 The API token is missing, unknown, expired or revoked.
403 The API token does not carry the required scope.
404 The resource does not exist, or the token may not see it.
405 The resource does not support this method.

Example

curl --fail-with-body -sS \
  -H "Authorization: Bearer $BITHIVE_TOKEN" \
  "https://app.bithive-it.com/v1/sboms/$SBOMID/components"

GET`/v1/sboms/{sbomId}/document`

Download the document as it was uploaded

Returns the stored bytes unchanged, which is what an audit or a report attachment needs. Requires the scope sboms:read.

Parameters

sbomId path, string (uuid), required Identifier of the upload.

Answers

200 The document, byte for byte as uploaded.
401 The API token is missing, unknown, expired or revoked.
403 The API token does not carry the required scope.
404 The resource does not exist, or the token may not see it.
405 The resource does not support this method.

Example

curl --fail-with-body -sS \
  -H "Authorization: Bearer $BITHIVE_TOKEN" \
  "https://app.bithive-it.com/v1/sboms/$SBOMID/document"

GET`/v1/products/{productId}/findings`

List what was found in a product

Returns the product's findings, the ones for vulnerabilities known to be exploited first, then by severity, then newest. That order is the order to work in: an actively exploited vulnerability is what starts the Cyber Resilience Act's 24-hour report.

Whether a vulnerability is exploited is resolved when the request is answered, not stored on the finding, because a vulnerability becomes exploited later and that moment is what matters.

Requires the scope findings:read.

Parameters

productId path, string (uuid), required Identifier of the product.

Answers

200 The product's findings. FindingList
401 The API token is missing, unknown, expired or revoked.
403 The API token does not carry the required scope.
404 The resource does not exist, or the token may not see it.
405 The resource does not support this method.

Example

curl --fail-with-body -sS \
  -H "Authorization: Bearer $BITHIVE_TOKEN" \
  "https://app.bithive-it.com/v1/products/$PRODUCTID/findings"

GET`/v1/products/{productId}/coverage`

Read how much of a product can be checked

Returns how many components of the product's latest upload we can check, and names what it cannot. Results depend on the completeness of the bill of materials, so the uncovered part is named rather than merely subtracted: a client can see which ecosystems are not covered and why.

A component is not monitored when it carries no package identifier (common in firmware built with Yocto or Buildroot), when it names no version, or when it belongs to an ecosystem whose matching is not yet proven.

Requires the scope findings:read.

Parameters

productId path, string (uuid), required Identifier of the product.

Answers

200 What the product's latest upload could be checked against. Coverage
401 The API token is missing, unknown, expired or revoked.
403 The API token does not carry the required scope.
404 The resource does not exist, or the token may not see it.
405 The resource does not support this method.

Example

curl --fail-with-body -sS \
  -H "Authorization: Bearer $BITHIVE_TOKEN" \
  "https://app.bithive-it.com/v1/products/$PRODUCTID/coverage"

What comes back

Liveness

Field	Type	Description
`status` required	string

Readiness

Field	Type	Description
`status` required	string

Product

Field	Type	Description
`id` required	string (uuid)
`name` required	string
`created_at` required	string (date-time)
`archived` required	boolean	An archived product is no longer monitored.

ProductList

Field	Type	Description
`products` required	array of object

SBOM

Field	Type	Description
`id` required	string (uuid)
`product_id` required	string (uuid)
`format` required	string
`spec_version` required	string	Version of the specification the document follows, for example 1.6 or SPDX-2.3.
`sha256` required	string	SHA-256 of the stored document, in lower-case hexadecimal. It addresses the document.
`component_count` required	integer	Components the document listed, after repetitions were dropped.
`source` required	string	Whether the upload came through the interface or this API.
`created_at` required	string (date-time)

SBOMList

Field	Type	Description
`sboms` required	array of object

Component

Field	Type	Description
`name` required	string
`version` required	string	Empty when the document stated no version; such a component cannot be matched.
`purl` required	string	Package URL as the document carried it, empty when it carried none.

ComponentList

Field	Type	Description
`components` required	array of object
`total` required	integer

Finding

Field	Type	Description
`id` required	string (uuid)
`component` required	object
`vulnerability` required	object
`evidence` required	string	Whether the feed stated the affected version outright, or the version was compared against a published range.
`matched_range`	string	The range that decided a compared match.
`state` required	string
`exploited` required	boolean	The vulnerability is known to be exploited, which starts the 24-hour report.
`exploited_cve`	string	The identifier the exploitation catalogue lists it under.
`exploited_since`	string (date)	The day the catalogue added it.
`ransomware` required	boolean	The catalogue has linked it to a ransomware campaign.
`first_seen_at` required	string (date-time)	When the Reporting Desk first saw this finding. Reporting deadlines are measured from our own knowledge.
`last_seen_at` required	string (date-time)

FindingList

Field	Type	Description
`findings` required	array of object
`total` required	integer
`exploited` required	integer	How many of them start a reporting deadline.

NotMonitoredGroup

Field	Type	Description
`reason` required	string
`ecosystem`	string	The ecosystem, when the reason is about one, so a client can see that it is Alpine rather than only that something is unsupported.
`explanation`	string	What specifically is unsolved. For "version could not be read": these versions cannot be ordered, so they are not checked against advisories that give a range of affected versions; they are still matched against advisories that list their exact version, which means such a component can have findings and still be counted here as not monitored.
`components` required	integer

Coverage

Field	Type	Description
`sbom_id`	string (uuid)	The upload this describes; absent when the product has none.
`components` required	integer
`monitored` required	integer
`monitored_percent` required	number	The monitored share, rounded to one decimal place.
`not_monitored` required	array of object

Problem

RFC 9457 problem details.

Field	Type	Description
`type` required	string
`title` required	string
`status` required	integer
`detail`	string

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 trial

API reference.

Authentication

Servers

Endpoints

GET/healthz

Answers

Example

GET/readyz

Answers

Example

GET/v1/products

Answers

Example

GET/v1/products/{productId}

Parameters

Answers

Example

GET/v1/products/{productId}/sboms

Parameters

Answers

Example

POST/v1/products/{productId}/sboms

Parameters

Request body

Answers

Example

GET/v1/sboms/{sbomId}

Parameters

Answers

Example

GET/v1/sboms/{sbomId}/components

Parameters

Answers

Example

GET/v1/sboms/{sbomId}/document

Parameters

Answers

Example

GET/v1/products/{productId}/findings

Parameters

Answers

Example

GET/v1/products/{productId}/coverage

Parameters

Answers

Example

What comes back

Liveness

Readiness

Product

ProductList

SBOM

SBOMList

Component

ComponentList

Finding

FindingList

NotMonitoredGroup

Coverage

Problem

GET`/healthz`

GET`/readyz`

GET`/v1/products`

GET`/v1/products/{productId}`

GET`/v1/products/{productId}/sboms`

POST`/v1/products/{productId}/sboms`

GET`/v1/sboms/{sbomId}`

GET`/v1/sboms/{sbomId}/components`

GET`/v1/sboms/{sbomId}/document`

GET`/v1/products/{productId}/findings`

GET`/v1/products/{productId}/coverage`