Bill of Materials API - Coverbase API

A bill of materials (cbbom_...) is a machine-readable inventory of the components that make up a vendor’s product or a specific service. Upload one as a document, and Coverbase parses it in the background into a searchable list of components (cbbomc_...) — each traceable back to the exact source file and vendor it came from. Supported BOM kinds: SBOM (software), AIBOM (AI/ML models and datasets), HBOM (hardware), SaaSBOM, and other. Supported formats are CycloneDX (JSON) and SPDX (JSON); files in any other format are still stored, but are not parsed into components. All endpoints are org-scoped to the API key and require the bill-of-materials entitlement. See Availability below. See API conventions for authentication, IDs, timestamps, and the error envelope.

Method	Path	Idempotent
`POST`	`/v1/bill_of_materials`	No
`GET`	`/v1/bill_of_materials/latest`	—
`GET`	`/v1/bill_of_materials`	—
`GET`	`/v1/bill_of_materials/{bom_id}`	—
`GET`	`/v1/bill_of_materials/{bom_id}/components`	—
`GET`	`/v1/bill_of_materials/components`	—
`POST`	`/v1/bill_of_materials/{bom_id}/archive`	No

How BOMs are versioned

A BOM is uploaded as a document and can be linked to a vendor, a single service, multiple services, or the vendor only — the same linking model as vendor documents. Many BOMs can be uploaded over time for the same vendor or service, and the platform keeps all of them as history. Only the latest (most recently uploaded, non-archived) BOM is “applied” — it is the one shown as current on the vendor or service page and returned by GET /v1/bill_of_materials/latest. Older BOMs remain viewable and downloadable as history via GET /v1/bill_of_materials. Archiving a BOM drops it from “latest” but keeps it in history.

Parse lifecycle

On upload a BOM starts at parse_status: "pending" and is parsed asynchronously. Poll the BOM (or the latest/list endpoints) to watch it move through the lifecycle:

`parse_status`	Meaning
`pending`	Registered, not yet picked up by the parser.
`parsing`	Parse in progress.
`parsed`	Parsed successfully; `components` are available.
`failed`	Parsing was attempted but failed (see `parse_error`).
`unsupported`	File format is not CycloneDX or SPDX JSON; the file is stored but not parsed.

The bill of materials object

string

Bill of materials ID (cbbom_...).

vendor_id

string

The owning vendor (cbvndr_...).

vendor_document_id

string

The stored source file (cbvdoc_...), downloadable via the document object.

format

string

One of cyclonedx, spdx, or unknown.

bom_type

string

One of sbom, aibom, hbom, saasbom, or other.

parse_status

string

One of pending, parsing, parsed, failed, unsupported. See parse lifecycle.

spec_version

string | null

Spec version of the source document, e.g. 1.5 (CycloneDX) or SPDX-2.3.

serial_number

string | null

Document serial number, if present in the source.

component_count

integer

Number of parsed components.

name

string | null

BOM subject / primary component name.

parse_error

string | null

Set when parse_status is failed or unsupported.

parsed_at

integer | null

Unix timestamp (seconds) when parsing completed.

is_archived

boolean

Whether the BOM has been archived.

created_at

integer

Unix timestamp (seconds) of upload.

updated_at

integer

Unix timestamp (seconds) of last update.

document

object | null

The stored source file: { id, name, s3_url, size, extension, created_at }.

components

object[] | null

The parsed components. Present on detail responses only (/latest and /{bom_id}); null on list summaries.

The component object

string

Component ID (cbbomc_...).

bill_of_materials_id

string

The BOM this component belongs to (cbbom_...).

vendor_document_id

string

The source file the component was parsed from (cbvdoc_...).

name

string

Component name. Required — the one field always present.

version

string | null

Component version.

purl

string | null

Package URL (PURL).

cpe

string | null

Common Platform Enumeration identifier.

group

string | null

Namespace / group (e.g. Maven groupId).

supplier

string | null

Supplier or publisher.

author

string | null

Author.

description

string | null

Free-text description.

bom_ref

string | null

The source document’s internal reference for this component.

component_type

string

One of application, library, framework, container, operating-system, device, firmware, file, machine-learning-model, data, other.

licenses

string[]

Declared licenses.

hashes

object

Map of hash algorithm to value (e.g. { "SHA-256": "..." }).

external_references

array

External references from the source document.

properties

object

Arbitrary key/value properties from the source document.

created_at

integer

Unix timestamp (seconds).

Upload a BOM

method

POST

POST /v1/bill_of_materials

Registers a BOM against a vendor (and optionally one or more services), then parses it asynchronously. Returns the new BOM with parse_status: "pending". Upload the file to the presigned URL from GET /v1/file/uploadable_url first, then pass the resulting s3_url here.

Request body

vendor_id

string

required

The owning vendor (cbvndr_...).

s3_url

string

required

The s3://... URL of the uploaded file, from GET /v1/file/uploadable_url.

size

integer

required

File size in bytes.

name

string

required

File name (e.g. acme-sbom.cdx.json).

extension

string

required

File extension (e.g. json).

service_ids

string[]

Optional. Link the BOM to one or more services (cbsvc_...) under the vendor. Omit to link the BOM to the vendor only.

Example request

cURL

curl -X POST "https://sandbox.api.coverbase.app/v1/bill_of_materials" \
  -H "Authorization: Bearer ak_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_id": "cbvndr_e448ba62882143f3ba0c140bb2e30162",
    "s3_url": "s3://coverbase-uploads/acme/sbom.json",
    "size": 20480,
    "name": "acme-sbom.cdx.json",
    "extension": "json",
    "service_ids": ["cbsvc_3c2b1a098f7e6d5c4b3a2918374655ab"]
  }'

Example response

200 OK — the new bill of materials object, freshly registered:

{
  "id": "cbbom_9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c",
  "vendor_id": "cbvndr_e448ba62882143f3ba0c140bb2e30162",
  "vendor_document_id": "cbvdoc_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "format": "unknown",
  "bom_type": "other",
  "parse_status": "pending",
  "spec_version": null,
  "serial_number": null,
  "component_count": 0,
  "name": null,
  "parse_error": null,
  "parsed_at": null,
  "is_archived": false,
  "created_at": 1748822400,
  "updated_at": 1748822400,
  "document": {
    "id": "cbvdoc_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
    "name": "acme-sbom.cdx.json",
    "s3_url": "s3://coverbase-uploads/acme/sbom.json",
    "size": 20480,
    "extension": "json",
    "created_at": 1748822400
  },
  "components": null
}

format, bom_type, spec_version, and component_count are populated once parsing completes.

Error responses

Status	Body	When
404	`{"detail": {"code": "vendor_not_found", "message": "Vendor not found."}}`	`vendor_id` not found / not in org, or the `bill-of-materials` gate is off.
422	Standard validation error	A required field is missing or the body is malformed.

Get the current applied BOM

method

GET

GET /v1/bill_of_materials/latest

Returns the latest applied BOM — with its components — for a vendor or a service. Returns null if none has been uploaded.

Query parameters

vendor_id

string

A vendor (cbvndr_...). Provide exactly one of vendor_id or service_id.

service_id

string

A service (cbsvc_...). Provide exactly one of vendor_id or service_id.

Supplying both vendor_id and service_id, or neither, returns 422.

Example request

cURL

# The current applied BOM for a vendor (with components):
curl -X GET "https://sandbox.api.coverbase.app/v1/bill_of_materials/latest?vendor_id=cbvndr_e448ba62882143f3ba0c140bb2e30162" \
  -H "Authorization: Bearer ak_live_xxx"

# The current applied BOM for a specific service:
curl -X GET "https://sandbox.api.coverbase.app/v1/bill_of_materials/latest?service_id=cbsvc_3c2b1a098f7e6d5c4b3a2918374655ab" \
  -H "Authorization: Bearer ak_live_xxx"

Example response

200 OK — a bill of materials object with components, or null:

{
  "id": "cbbom_9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c",
  "vendor_id": "cbvndr_e448ba62882143f3ba0c140bb2e30162",
  "vendor_document_id": "cbvdoc_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "format": "cyclonedx",
  "bom_type": "sbom",
  "parse_status": "parsed",
  "spec_version": "1.5",
  "serial_number": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79",
  "component_count": 142,
  "name": "acme-platform",
  "parse_error": null,
  "parsed_at": 1748822460,
  "is_archived": false,
  "created_at": 1748822400,
  "updated_at": 1748822460,
  "document": {
    "id": "cbvdoc_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
    "name": "acme-sbom.cdx.json",
    "s3_url": "s3://coverbase-uploads/acme/sbom.json",
    "size": 20480,
    "extension": "json",
    "created_at": 1748822400
  },
  "components": [
    {
      "id": "cbbomc_4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f",
      "bill_of_materials_id": "cbbom_9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c",
      "vendor_document_id": "cbvdoc_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
      "name": "log4j-core",
      "version": "2.17.1",
      "purl": "pkg:maven/org.apache.logging.log4j/log4j-core@2.17.1",
      "cpe": null,
      "group": "org.apache.logging.log4j",
      "supplier": "The Apache Software Foundation",
      "author": null,
      "description": null,
      "bom_ref": "pkg:maven/org.apache.logging.log4j/log4j-core@2.17.1",
      "component_type": "library",
      "licenses": ["Apache-2.0"],
      "hashes": { "SHA-256": "8d3e1..." },
      "external_references": [],
      "properties": {},
      "created_at": 1748822460
    }
  ]
}

List the upload history

method

GET

GET /v1/bill_of_materials

Returns the full upload history for a vendor or service, newest first. The first item is the currently applied BOM. Items are summaries — components is null; use Retrieve a BOM or List components of a BOM to pull components.

Query parameters

vendor_id

string

A vendor (cbvndr_...). Provide exactly one of vendor_id or service_id.

service_id

string

A service (cbsvc_...). Provide exactly one of vendor_id or service_id.

include_archived

boolean

Include archived BOMs in the history. Defaults to false.

limit

integer

Page size.

offset

integer

Page offset.

Example request

cURL

curl -X GET "https://sandbox.api.coverbase.app/v1/bill_of_materials?vendor_id=cbvndr_e448ba62882143f3ba0c140bb2e30162&limit=25" \
  -H "Authorization: Bearer ak_live_xxx"

Example response

200 OK — a page of bill of materials objects (summaries, no components):

{
  "data": [
    {
      "id": "cbbom_9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c",
      "vendor_id": "cbvndr_e448ba62882143f3ba0c140bb2e30162",
      "vendor_document_id": "cbvdoc_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
      "format": "cyclonedx",
      "bom_type": "sbom",
      "parse_status": "parsed",
      "spec_version": "1.5",
      "serial_number": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79",
      "component_count": 142,
      "name": "acme-platform",
      "parse_error": null,
      "parsed_at": 1748822460,
      "is_archived": false,
      "created_at": 1748822400,
      "updated_at": 1748822460,
      "document": { "id": "cbvdoc_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d", "name": "acme-sbom.cdx.json", "s3_url": "s3://coverbase-uploads/acme/sbom.json", "size": 20480, "extension": "json", "created_at": 1748822400 },
      "components": null
    }
  ],
  "total_count": 3
}

Retrieve a BOM

method

GET

GET /v1/bill_of_materials/{bom_id}

Returns one BOM with its full components list.

Path parameters

bom_id

string

required

The bill of materials ID (cbbom_...).

Example request

cURL

curl -X GET "https://sandbox.api.coverbase.app/v1/bill_of_materials/cbbom_9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c" \
  -H "Authorization: Bearer ak_live_xxx"

The response is a bill of materials object with components populated (same shape as the current applied BOM).

Error responses

Status	Body	When
404	`{"detail": {"code": "bom_not_found", "message": "Bill of materials not found."}}`	`bom_id` not found / not in org, or the gate is off.

List components of a BOM

method

GET

GET /v1/bill_of_materials/{bom_id}/components

Returns the components of a single BOM, searchable and filterable.

Path parameters

bom_id

string

required

The bill of materials ID (cbbom_...).

Query parameters

string

Free-text match against component fields (name, PURL, etc.).

component_type

string

Filter to a single component_type (e.g. machine-learning-model).

limit

integer

Page size.

offset

integer

Page offset.

Example request

cURL

# List components of one BOM, filtered to ML models (AIBOM use case):
curl -X GET "https://sandbox.api.coverbase.app/v1/bill_of_materials/cbbom_9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c/components?component_type=machine-learning-model" \
  -H "Authorization: Bearer ak_live_xxx"

Example response

200 OK — a page of component objects:

{
  "data": [
    {
      "id": "cbbomc_4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f",
      "bill_of_materials_id": "cbbom_9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c",
      "vendor_document_id": "cbvdoc_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
      "name": "log4j-core",
      "version": "2.17.1",
      "purl": "pkg:maven/org.apache.logging.log4j/log4j-core@2.17.1",
      "cpe": null,
      "group": "org.apache.logging.log4j",
      "supplier": "The Apache Software Foundation",
      "author": null,
      "description": null,
      "bom_ref": "pkg:maven/org.apache.logging.log4j/log4j-core@2.17.1",
      "component_type": "library",
      "licenses": ["Apache-2.0"],
      "hashes": { "SHA-256": "8d3e1..." },
      "external_references": [],
      "properties": {},
      "created_at": 1748822460
    }
  ],
  "total_count": 142
}

Search components across a vendor

method

GET

GET /v1/bill_of_materials/components

Search components across all of a vendor’s BOMs at once. Because every component carries its bill_of_materials_id and vendor_document_id, each match traces straight back to the source file it came from — answering questions like “has this vendor ever shipped a BOM containing log4j?”

Query parameters

vendor_id

string

required

The vendor to search within (cbvndr_...).

string

Free-text match against component fields.

component_type

string

Filter to a single component_type.

bill_of_materials_id

string

Restrict to a single BOM (cbbom_...).

vendor_document_id

string

Restrict to components from a single source file (cbvdoc_...).

limit

integer

Page size.

offset

integer

Page offset.

Example request

cURL

# Find every BOM across the vendor that contains a component (e.g. log4j):
curl -X GET "https://sandbox.api.coverbase.app/v1/bill_of_materials/components?vendor_id=cbvndr_e448ba62882143f3ba0c140bb2e30162&search=log4j" \
  -H "Authorization: Bearer ak_live_xxx"

The response is a page of component objects ({ "data": [...], "total_count": <int> }), spanning every matching BOM for the vendor.

Archive a BOM

method

POST

POST /v1/bill_of_materials/{bom_id}/archive

Archives a BOM. It drops out of “latest” — the next most recent non-archived BOM becomes the applied one — but stays in history and remains retrievable (and shows in the history list when include_archived=true).

Path parameters

bom_id

string

required

The bill of materials ID (cbbom_...).

Example request

cURL

curl -X POST "https://sandbox.api.coverbase.app/v1/bill_of_materials/cbbom_9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c/archive" \
  -H "Authorization: Bearer ak_live_xxx"

The response is the updated bill of materials object with is_archived: true.

Error responses

Status	Body	When
404	`{"detail": {"code": "bom_not_found", "message": "Bill of materials not found."}}`	`bom_id` not found / not in org, or the gate is off.

MCP / assistant access

The Coverbase MCP server exposes BOMs read-only through the query_vendors dispatcher tool — no new top-level tools. Two new kind values join the existing ones (documents, document_summary, risk_summary, …):

`kind`	Returns	Args
`bill_of_materials`	The latest applied BOM for a vendor, plus its components	`vendor_id` (required), `limit` (max components, default `100`)
`bill_of_materials_history`	All uploaded BOMs for a vendor, newest first (the first is the applied one)	`vendor_id` (required), `limit` (default `20`)

Both are user- and org-scoped. See example prompts for natural-language phrasings.

Availability

The Bill of Materials feature is gated by the org-level bill-of-materials entitlement. When it is off, the Bill of Materials tab is hidden in the dashboard and every /v1/bill_of_materials route returns 404. Ask your Coverbase administrator (or your account manager) to enable it for your organization.

​How BOMs are versioned

​Parse lifecycle

​The bill of materials object

​The component object

​Upload a BOM

​Request body

​Example request

​Example response

​Error responses

​Get the current applied BOM

​Query parameters

​Example request

​Example response

​List the upload history

​Query parameters

​Example request

​Example response

​Retrieve a BOM

​Path parameters

​Example request

​Error responses

​List components of a BOM

​Path parameters

​Query parameters

​Example request

​Example response

​Search components across a vendor

​Query parameters

​Example request

​Archive a BOM

​Path parameters

​Example request

​Error responses

​MCP / assistant access

​Availability

How BOMs are versioned

Parse lifecycle

The bill of materials object

The component object

Upload a BOM

Request body

Example request

Example response

Error responses

Get the current applied BOM

Query parameters

Example request

Example response

List the upload history

Query parameters

Example request

Example response

Retrieve a BOM

Path parameters

Example request

Error responses

List components of a BOM

Path parameters

Query parameters

Example request

Example response

Search components across a vendor

Query parameters

Example request

Archive a BOM

Path parameters

Example request

Error responses

MCP / assistant access

Availability