Bill of Materials API - Coverbase Docs

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. They are the endpoints the dashboard’s Bill of Materials tab uses, so they take a signed-in user’s dashboard session token (a JWT): an ak_ API key is rejected with 401 Unauthorized role. See Availability below, and API conventions for 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}/promote`	No
`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. One non-archived BOM is “applied”: the one uploaded or promoted most recently. It is 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, for example, 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.

object

Free-form metadata from the source document header (tools, authors, timestamp, lifecycle). Empty until parsed.

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, /{bom_id}, and the upload response); omitted from list summaries and from the promote and archive responses.

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 (for example, 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 (for example, { "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 first with the presigned POST from GET /v1/file/uploadable_url?extension=json, then pass the uploaded file’s URL here.

Request body

string

required

The owning vendor (cbvndr_...).

string

required

The URL of the uploaded file: the presigned url from GET /v1/file/uploadable_url followed by the key it returned in fields.

integer

required

File size in bytes.

string

required

File name (for example, acme-sbom.cdx.json).

string

required

File extension (for example, 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://api.coverbase.app/v1/bill_of_materials" \
  -H "Authorization: Bearer <user-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_id": "cbvndr_e448ba62882143f3ba0c140bb2e30162",
    "s3_url": "https://coverbase-uploads.s3.amazonaws.com/7c1d9e2b41f04c5e8a3b6d0f9e2c4a71",
    "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,
  "bom_metadata": {},
  "is_archived": false,
  "created_at": 1748822400,
  "updated_at": 1748822400,
  "document": {
    "id": "cbvdoc_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
    "name": "acme-sbom.cdx.json",
    "s3_url": "https://coverbase-uploads.s3.amazonaws.com/7c1d9e2b41f04c5e8a3b6d0f9e2c4a71",
    "size": 20480,
    "extension": "json",
    "created_at": 1748822400
  },
  "components": []
}

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

Error responses

Status	Body	When
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://api.coverbase.app/v1/bill_of_materials/latest?vendor_id=cbvndr_e448ba62882143f3ba0c140bb2e30162" \
  -H "Authorization: Bearer <user-jwt>"

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

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,
  "bom_metadata": {},
  "is_archived": false,
  "created_at": 1748822400,
  "updated_at": 1748822460,
  "document": {
    "id": "cbvdoc_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
    "name": "acme-sbom.cdx.json",
    "s3_url": "https://coverbase-uploads.s3.amazonaws.com/7c1d9e2b41f04c5e8a3b6d0f9e2c4a71",
    "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 upload first. The first item is the currently applied BOM unless an older upload has been promoted since. Items are summaries without components; 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. Default 25, range 1-500.

integer

Page offset. Default 0.

Example request

cURL

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

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,
      "bom_metadata": {},
      "is_archived": false,
      "created_at": 1748822400,
      "updated_at": 1748822460,
      "document": { "id": "cbvdoc_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d", "name": "acme-sbom.cdx.json", "s3_url": "https://coverbase-uploads.s3.amazonaws.com/7c1d9e2b41f04c5e8a3b6d0f9e2c4a71", "size": 20480, "extension": "json", "created_at": 1748822400 }
    }
  ],
  "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://api.coverbase.app/v1/bill_of_materials/cbbom_9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c" \
  -H "Authorization: Bearer <user-jwt>"

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": "Bill of materials not found"}`	`bom_id` not found or not in your org.

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 (for example, machine-learning-model).

integer

Page size. Default 50, range 1-200.

integer

Page offset. Default 0.

Example request

cURL

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

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. Default 50, range 1-200.

integer

Page offset. Default 0.

Example request

cURL

# Find every BOM across the vendor that contains a component (for example, log4j):
curl -X GET "https://api.coverbase.app/v1/bill_of_materials/components?vendor_id=cbvndr_e448ba62882143f3ba0c140bb2e30162&search=log4j" \
  -H "Authorization: Bearer <user-jwt>"

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

Promote a historical BOM

POST

POST /v1/bill_of_materials/{bom_id}/promote

Makes an older, non-archived upload the applied BOM for its vendor and for every service it is linked to, until a newer upload or another promotion replaces it. The change is recorded in the vendor’s (and each linked service’s) activity log.

Path parameters

string

required

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

The response is the promoted bill of materials object, without components. An unknown or archived bom_id returns 404 with {"detail": "Bill of materials not found"}.

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://api.coverbase.app/v1/bill_of_materials/cbbom_9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c/archive" \
  -H "Authorization: Bearer <user-jwt>"

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

Error responses

Status	Body	When
404	`{"detail": "Bill of materials not found"}`	`bom_id` not found or not in your org.

MCP / assistant access

The Coverbase MCP server exposes BOMs read-only through the query_vendors dispatcher tool, with 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

Bill of Materials is available to every organization: the Bill of Materials tab appears on each vendor and service page, and no entitlement is required. Because these are dashboard endpoints, call them with a signed-in user’s session token rather than an ak_ API key.

​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

​Promote a historical BOM

​Path parameters

​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

Promote a historical BOM

Path parameters

Archive a BOM

Path parameters

Example request

Error responses

MCP / assistant access

Availability