Comparing SBOM Versions with the API

The version comparison endpoints return what changed between two versions of the same asset. They are the API equivalent of the Version Comparison drawer on an asset's Versions tab, described in Comparing SBOM Versions. That page also explains what counts as an added or removed component, vulnerability, or license.

All paths are relative to https://api.manifestcyber.com.

Before you start

Version comparison must be enabled for your organization

Version comparison is enabled per organization. Until it is enabled, every endpoint on this page returns HTTP 403 with the plain-text body Forbidden: Feature Not Enabled. To enable it, contact [email protected].

Use a user API token

These endpoints only accept user API tokens. Legacy organization tokens are rejected with HTTP 403 and the message Organization tokens are not allowed for this path. To create a user token, go to Settings → Account → API Tokens (see Managing API Tokens).

Send the token in the Authorization header:

Authorization: Bearer <API_TOKEN>

Give the token the right scopes

Each endpoint checks its own set of permissions:

The view-all scope, which every token has, grants all of these permissions. See the API Token Scopes Reference.

Find the two version IDs

Each version of an asset has its own asset ID. Pass the older version as baselineAssetId and the newer one as comparisonAssetId. Added means present in the comparison version only, and Removed means present in the baseline only. Swapping the IDs swaps added and removed.

To list an asset's versions and their IDs, call the versions endpoint with the ID of any version of the asset:

curl "https://api.manifestcyber.com/v1/asset/<ASSET_ID>/versions" \
  -H "Authorization: Bearer <API_TOKEN>"

Versions are returned newest first. Each item's _id is the asset ID of that version, and version is its version string.

Both IDs must be different versions of the same asset in your organization. See Errors for what is returned otherwise.

Get the summary

GET /v1/asset/compare/{baselineAssetId}/{comparisonAssetId} returns the stored totals of both versions, as shown on the summary cards in the app.

curl "https://api.manifestcyber.com/v1/asset/compare/<BASELINE_ASSET_ID>/<COMPARISON_ASSET_ID>" \
  -H "Authorization: Bearer <API_TOKEN>"

{
  "success": true,
  "data": {
    "baseline": {
      "organizationAssetId": "<BASELINE_ASSET_ID>",
      "name": "my-service",
      "version": "2.3.0",
      "dateCreated": "2026-09-14T10:21:05.000Z",
      "isActive": true,
      "riskScore": "medium",
      "countComponents": 412,
      "countVulnerabilities": {
        "total": 37,
        "critical": 2,
        "high": 9,
        "medium": 18,
        "low": 8,
        "info": 0,
        "inKEV": 1
      },
      "countLicenseIssues": 3
    },
    "comparison": {
      "organizationAssetId": "<COMPARISON_ASSET_ID>",
      "name": "my-service",
      "version": "2.4.0",
      "dateCreated": "2026-10-20T08:02:44.000Z",
      "isActive": true,
      "riskScore": "low",
      "countComponents": 419,
      "countVulnerabilities": {
        "total": 21,
        "critical": 0,
        "high": 4,
        "medium": 12,
        "low": 5,
        "info": 0,
        "inKEV": 0
      },
      "countLicenseIssues": 3
    }
  }
}

data is an object, not an array. baseline and comparison have the same fields:

The vulnerability totals are each version's own counts. The vulnerabilities endpoint lists only the CVEs caused by component changes, so the difference between the two totals is usually not the number of rows it returns. A CVE that affects both versions is counted in both totals but is not a change.

List the changes

The components, vulnerabilities, and licenses endpoints share the same query parameters and response shape. Each request computes the comparison and returns one page of rows.

Query parameters

Unknown parameters are ignored. An invalid value returns HTTP 400 (see Errors).

Filters combine: a row is returned only when it matches change, severity, and search.

Sorting

Without sortBy, rows are returned in the default order of each endpoint, listed below. With sortBy, rows are sorted by that field first and ties fall back to the default order. In both directions:

• Missing (null) values sort last.
• Text is compared with numbers in order, so version 1.10 sorts after 1.9.

The order is stable, so paging through the same comparison returns each row once as long as the underlying data does not change between requests.

Response

{
  "success": true,
  "data": [],
  "queryInfo": {
    "page": 1,
    "limit": 50,
    "totalReturn": 50,
    "totalCount": 132
  }
}

Component reference

Rows on all three endpoints describe components with the same object:

Components

GET /v1/asset/compare/{baselineAssetId}/{comparisonAssetId}/components lists each component version that is present in one version of the asset and not the other. An upgraded package appears twice: its old version as removed and its new version as added.

curl -G "https://api.manifestcyber.com/v1/asset/compare/<BASELINE_ASSET_ID>/<COMPARISON_ASSET_ID>/components" \
  -H "Authorization: Bearer <API_TOKEN>" \
  --data-urlencode "change=added" \
  --data-urlencode "sortBy=name" \
  --data-urlencode "limit=100"

Each row is a component reference with a change field:

{
  "change": "added",
  "organizationComponentId": "<COMPONENT_ID>",
  "name": "lodash",
  "version": "4.17.21",
  "packageUrl": "pkg:npm/[email protected]",
  "relationship": "transitive"
}

Vulnerabilities

GET /v1/asset/compare/{baselineAssetId}/{comparisonAssetId}/vulnerabilities lists the CVEs caused by component changes: CVEs that affect an added or removed component and are found in only one of the two versions. A CVE that is still present in the other version through any component is not returned. A CVE that affects several changed components returns one row per component.

curl -G "https://api.manifestcyber.com/v1/asset/compare/<BASELINE_ASSET_ID>/<COMPARISON_ASSET_ID>/vulnerabilities" \
  -H "Authorization: Bearer <API_TOKEN>" \
  --data-urlencode "change=added" \
  --data-urlencode "severity=CRITICAL,HIGH" \
  --data-urlencode "sortBy=cvssScore" \
  --data-urlencode "sortOrder=desc"

{
  "change": "added",
  "cveId": "CVE-2026-12345",
  "vulnerabilityId": "<VULNERABILITY_ID>",
  "severity": "HIGH",
  "cvssScore": 8.1,
  "epssScore": 0.0213,
  "inKEV": false,
  "recommendedAction": "mitigate",
  "affectedComponent": {
    "organizationComponentId": "<COMPONENT_ID>",
    "name": "example-parser",
    "version": "1.4.0",
    "packageUrl": "pkg:npm/[email protected]",
    "relationship": "direct"
  }
}

sortBy=severity sorts from NONE to CRITICAL in ascending order, so use sortOrder=desc to list the most severe first. sortBy=inKEV sorts false before true in ascending order.

Older versions are not re-scanned. Each version's vulnerabilities come from the last time that version was scanned. A recently published CVE can be returned as added on an upgraded package even if the old version of the package was also affected, because the older asset version was scanned before the CVE was published.

Licenses

GET /v1/asset/compare/{baselineAssetId}/{comparisonAssetId}/licenses lists license changes on the components that changed: a license that an added or removed component carries in one version and that the same package does not carry in the other version. A package that is upgraded and keeps the same license returns no row.

curl -G "https://api.manifestcyber.com/v1/asset/compare/<BASELINE_ASSET_ID>/<COMPARISON_ASSET_ID>/licenses" \
  -H "Authorization: Bearer <API_TOKEN>" \
  --data-urlencode "sortBy=risk" \
  --data-urlencode "sortOrder=desc"

{
  "change": "added",
  "component": {
    "organizationComponentId": "<COMPONENT_ID>",
    "name": "example-crypto",
    "version": "3.0.0",
    "packageUrl": "pkg:npm/[email protected]",
    "relationship": "transitive"
  },
  "license": {
    "licenseId": "<LICENSE_ID>",
    "name": "GPL-3.0-only"
  },
  "risk": "denied"
}

sortBy=risk sorts allowed, review, denied in ascending order.

Export to XLSX

GET /v1/asset/compare/{baselineAssetId}/{comparisonAssetId}/export?format=xlsx returns every change between the two versions as an XLSX file. format is required, and xlsx is the only supported value. The other query parameters on this page do not apply: the file always contains every row.

curl -o comparison.xlsx \
  -H "Authorization: Bearer <API_TOKEN>" \
  "https://api.manifestcyber.com/v1/asset/compare/<BASELINE_ASSET_ID>/<COMPARISON_ASSET_ID>/export?format=xlsx"

The response is the file itself, sent as an attachment named <asset>_<baseline version>_vs_<comparison version>.xlsx. Use curl -OJ instead of -o to save it under that name. It has three sheets, each in the default order of the matching endpoint:

The file is sent only once it is complete, so a failed export never returns a partial file. When several exports are being built at the same time, the request returns HTTP 503. Wait a few seconds and retry.

Errors

Errors return "success": false and an errorDetails array. Each entry has a code and a message. Check the HTTP status and errorDetails[].code, not the message text.

{
  "success": false,
  "errorDetails": [
    {
      "code": "ASSET_COMPARISON_DIFFERENT_ASSETS",
      "message": "Both versions must belong to the same asset."
    }
  ]
}

Validation errors (INVALID_PARAMETERS) and the organization token error also include an errors array with the same messages. Validation messages have the form <parameter>: <reason>, for example baselineAssetId: Invalid asset ID format, with one entry per invalid parameter.

Authentication, feature, token, and permission errors are returned before the errors above. Except for the plain-text feature error, they put the message in the errors array:

The checks run in this order, so only the first problem is reported: authentication, feature enabled, token type, permissions, query parameters, path IDs, same version, versions found, same asset.

Related docs

• Comparing SBOM Versions
• Getting Started: Manifest API
• Managing API Tokens
• API Token Scopes Reference
• Manifest API Documentation