Batch retrieval of package metadata and alerts by PURL strings for a specific organization. Compatible with CycloneDX reports.

Package URLs (PURLs) are an ecosystem agnostic way to identify packages. CycloneDX SBOMs use the purl format to identify components. This endpoint supports fetching metadata and alerts for multiple packages at once by passing an array of purl strings, or by passing an entire CycloneDX report.

Note: This endpoint has a batch size limit (default: 1024 PURLs per request). Requests exceeding this limit will return a 400 Bad Request error.

More information on purl and CycloneDX:

• purl Spec
• CycloneDX Spec

This endpoint returns the latest available alert data for artifacts in the batch (stale while revalidate). Actively running analysis will be returned when available on subsequent runs.

Query Parameters

This endpoint supports all query parameters from POST /v0/purl including: alerts, actions, compact, fixable, licenseattrib, licensedetails, purlErrors, cachedResultsOnly, and summary.

Additionally, you may provide a labels query parameter to apply a repository label's security policies. Pass the label slug as the value (e.g., ?labels=production). Only one label is currently supported.

Examples:

Looking up an npm package:

{
  "components": [
    {
      "purl": "pkg:npm/[email protected]"
    }
  ]
}

Looking up a PyPi package:

{
  "components": [
    {
      "purl": "pkg:pypi/[email protected]"
    }
  ]
}

Looking up a Maven package:

{
  "components": [
    {
      "purl": "pkg:maven/log4j/[email protected]"
    }
  ]
}

Batch lookup

{
  "components": [
    {
      "purl": "pkg:npm/[email protected]"
    },
    {
      "purl": "pkg:pypi/[email protected]"
    },
    {
      "purl": "pkg:maven/log4j/[email protected]"
    }
  ]
}

With label and options (query parameters):

POST /v0/orgs/{org_slug}/purl?labels=production&alerts=true&compact=true
{
  "components": [
    {
      "purl": "pkg:npm/[email protected]"
    }
  ]
}

This endpoint consumes 100 units of your quota.

This endpoint requires the following org token scopes:

• packages:list