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, mode, 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/express@4.19.2"
    }
  ]
}

Looking up a PyPi package:

{
  "components": [
    {
      "purl": "pkg:pypi/django@5.0.6"
    }
  ]
}

Looking up a Maven package:

{
  "components": [
    {
      "purl": "pkg:maven/log4j/log4j@1.2.17"
    }
  ]
}

Batch lookup

{
  "components": [
    {
      "purl": "pkg:npm/express@4.19.2"
    },
    {
      "purl": "pkg:pypi/django@5.0.6"
    },
    {
      "purl": "pkg:maven/log4j/log4j@1.2.17"
    }
  ]
}

With label and options (query parameters):

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

This endpoint consumes 100 units of your quota.

This endpoint requires the following org token scopes:

• packages:list