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.

When alerts=true, Socket may synthesize two alert types to make partial
results actionable:

• pendingScan: the package is known but analysis has not completed yet
• notFound: Socket could not resolve the package/version metadata

When purlErrors=true, unresolved notFound inputs keep the legacy
purlError stream shape instead of emitting synthetic notFound
artifacts.

Use poll=false (default) to fail open and return the current known state
quickly. Use poll=true to fail closed and wait up to timeoutSec for
pending analysis before returning.

Conda (temporary compatibility): pkg:conda inputs are served from the
already-scanned PyPI package with the same normalized name and version when
one exists; the response row keeps the original conda PURL in inputPurl
but reports type: pypi. Conda build, subdir, type, and channel
qualifiers are ignored, and conda packages without a scanned PyPI
counterpart return the normal notFound result. This mapping will be
replaced by native conda support.

Query Parameters

This endpoint supports all query parameters from POST /v0/purl including: alerts, actions, compact, fixable, licenseattrib, licensedetails, purlErrors, poll, 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