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_...).

string

The owning vendor (cbvndr_...).

string

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

string

One of cyclonedx, spdx, or unknown.

string

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

string

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

string | null

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

string | null

Document serial number, if present in the source.

integer

Number of parsed components.

string | null

BOM subject / primary component name.

string | null

Set when parse_status is failed or unsupported.

integer | null

Unix timestamp (seconds) when parsing completed.

boolean

Whether the BOM has been archived.

integer

Unix timestamp (seconds) of upload.

integer

Unix timestamp (seconds) of last update.

object | null

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

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_...).

string

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

string

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

string

Component name. Required — the one field always present.

string | null

Component version.

string | null

Package URL (PURL).

string | null

Common Platform Enumeration identifier.

string | null

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

string | null

Supplier or publisher.

string | null

Author.

string | null

Free-text description.

string | null

The source document’s internal reference for this component.

string

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

string[]

Declared licenses.

object

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

array

External references from the source document.

object

Arbitrary key/value properties from the source document.

integer

Unix timestamp (seconds).

Upload a BOM

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

string

required

The owning vendor (cbvndr_...).

string

required

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

integer

required

File size in bytes.

string

required

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

string

required

File extension (e.g. json).

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

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

string

A vendor (cbvndr_...). Provide exactly one of vendor_id or 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

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

string

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

string

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

boolean

Include archived BOMs in the history. Defaults to false.

integer

Page size.

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

GET

GET /v1/bill_of_materials/{bom_id}

Returns one BOM with its full components list.

Path parameters

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

GET

GET /v1/bill_of_materials/{bom_id}/components

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

Path parameters

string

required

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

Query parameters

string

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

string

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

integer

Page size.

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

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

string

required

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

string

Free-text match against component fields.

string

Filter to a single component_type.

string

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

string

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

integer

Page size.

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

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

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