Look up risk scores, alerts, capabilities, license, and supply-chain metadata for any open-source package by Package URL (purl). Supports npm, PyPI, Go, Maven, Cargo, NuGet, RubyGems, and other ecosystems. The /purl endpoint accepts a list of package URLs and returns Socket's enriched package facts including capability use, telemetry, alert categories, and depscore.
openapi: 3.0.0
info:
description: Socket packages API endpoints.
title: Socket Packages API
version: '0'
servers:
- url: https://api.socket.dev/v0
paths:
/purl:
post:
tags:
- packages
summary: Get Packages by PURL
deprecated: true
externalDocs:
description: Socket Package URLs (purl)
url: https://docs.socket.dev/reference/socket-package-urls-purl
operationId: batchPackageFetch
parameters:
- name: alerts
in: query
required: false
description: Include alert metadata.
schema:
type: boolean
default: false
- name: actions
in: query
required: false
description: Include only alerts with comma separated actions defined by security policy.
schema:
type: array
items:
type: string
enum:
- error
- monitor
- warn
- ignore
explode: false
style: form
- name: compact
in: query
required: false
description: 'Compact metadata. When enabled, excludes metadata fields like author, scores, size, dependencies, and manifest files. Always includes: id, type, name, version, release, namespace,
subpath, alerts, and alertPriorities.'
schema:
type: boolean
default: false
- name: fixable
in: query
required: false
description: Include only fixable alerts.
schema:
type: boolean
default: false
- name: licenseattrib
in: query
required: false
description: Include license attribution data, including license text and author information. Maps attribution/license text to a list of data objects to which that attribution info applies.
schema:
type: boolean
default: false
- name: licensedetails
in: query
required: false
description: Include detailed license information, including location and match strength, for each license datum.
schema:
type: boolean
default: false
- name: purlErrors
in: query
required: false
description: Return errors found with handling PURLs as error objects in the stream.
schema:
type: boolean
default: false
- name: poll
in: query
required: false
description: When true, wait up to timeoutSec for pending analysis to complete before returning. When false (default), return the current known state immediately, including synthesized pendingScan
and notFound alerts when alerts=true unless purlErrors=true keeps legacy not-found errors.
schema:
type: boolean
default: false
- name: cachedResultsOnly
in: query
required: false
description: 'Legacy fallback for older clients. Only used when poll is omitted: cachedResultsOnly=true behaves like poll=false, while cachedResultsOnly=false preserves the older blocking behavior.'
schema:
type: boolean
default: false
- name: summary
in: query
required: false
description: Include a summary object at the end of the stream with counts of malformed, resolved, and not found PURLs.
schema:
type: boolean
default: false
- name: timeoutSec
in: query
required: false
description: Maximum time in seconds to wait for package resolution and, when poll=true, pending analysis. Inputs that have not completed processing when the timeout is reached return pendingScan
alerts when alerts=true, or errors when purlErrors=true.
schema:
type: integer
minimum: 1
maximum: 1200
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SocketOrgBatchPURLFetch'
required: false
security:
- bearerAuth:
- packages:list
- basicAuth:
- packages:list
description: "**This endpoint is deprecated.** Deprecated since 2026-01-05.\n\nBatch retrieval of package metadata and alerts by PURL strings. Compatible with CycloneDX reports.\n\nPackage URLs (PURLs)\
\ are an ecosystem agnostic way to identify packages.\nCycloneDX SBOMs use the purl format to identify components.\nThis 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.\n\n**Note:** This endpoint has a batch size limit (default: 1024 PURLs per request). Requests exceeding this limit\
\ will return a 400 Bad Request error.\n\nMore information on purl and CycloneDX:\n\n- [`purl` Spec](https://github.com/package-url/purl-spec)\n- [CycloneDX Spec](https://cyclonedx.org/specification/overview/#components)\n\
\nThis endpoint returns the latest available alert data for artifacts in the batch (stale while revalidate).\nActively running analysis will be returned when available on subsequent runs.\n\nWhen\
\ `alerts=true`, Socket may synthesize two alert types to make partial\nresults actionable:\n\n- `pendingScan`: the package is known but analysis has not completed yet\n- `notFound`: Socket could\
\ not resolve the package/version metadata\n\nWhen `purlErrors=true`, unresolved `notFound` inputs keep the legacy\n`purlError` stream shape instead of emitting synthetic `notFound`\nartifacts.\n\
\nUse `poll=false` (default) to fail open and return the current known state\nquickly. Use `poll=true` to fail closed and wait up to `timeoutSec` for\npending analysis before returning.\n\n## Examples:\n\
\n### Looking up an npm package:\n\n```json\n{\n \"components\": [\n {\n \"purl\": \"pkg:npm/express@4.19.2\"\n }\n ]\n}\n```\n\n### Looking up an PyPi package:\n\n```json\n{\n \"\
components\": [\n {\n \"purl\": \"pkg:pypi/django@5.0.6\"\n }\n ]\n}\n```\n\n### Looking up a Maven package:\n\n```json\n{\n \"components\": [\n {\n \"purl\": \"pkg:maven/log4j/log4j@1.2.17\"\
\n }\n ]\n}\n```\n\n### Batch lookup\n\n```json\n{\n \"components\": [\n {\n \"purl\": \"pkg:npm/express@4.19.2\"\n },\n {\n \"purl\": \"pkg:pypi/django@5.0.6\"\n },\n\
\ {\n \"purl\": \"pkg:maven/log4j/log4j@1.2.17\"\n }\n ]\n}\n```\n\nThis endpoint consumes 100 units of your quota.\n\nThis endpoint requires the following org token scopes:\n- packages:list"
responses:
'200':
content:
application/x-ndjson:
schema:
$ref: '#/components/schemas/BatchPurlStreamSchema'
description: Socket issue lists and scores for all packages, and optional metadata objects
'400':
$ref: '#/components/responses/SocketBadRequest'
'401':
$ref: '#/components/responses/SocketUnauthorized'
'403':
$ref: '#/components/responses/SocketForbidden'
'404':
$ref: '#/components/responses/SocketNotFoundResponse'
'429':
$ref: '#/components/responses/SocketTooManyRequestsResponse'
x-readme: {}
/orgs/{org_slug}/purl:
post:
tags:
- packages
summary: Get Packages by PURL (Org Scoped)
externalDocs:
description: Socket Package URLs (purl)
url: https://docs.socket.dev/reference/socket-package-urls-purl
operationId: batchPackageFetchByOrg
parameters:
- name: org_slug
in: path
required: true
description: The slug of the organization
schema:
type: string
- name: labels
in: query
required: false
description: Repository label slugs to apply policies. Only one label is supported currently; the parameter is an array to allow future support for multiple labels.
schema:
type: array
items:
type: string
explode: false
style: form
- name: alerts
in: query
required: false
description: Include alert metadata.
schema:
type: boolean
default: false
- name: actions
in: query
required: false
description: Include only alerts with comma separated actions defined by security policy.
schema:
type: array
items:
type: string
enum:
- error
- monitor
- warn
- ignore
explode: false
style: form
- name: compact
in: query
required: false
description: 'Compact metadata. When enabled, excludes metadata fields like author, scores, size, dependencies, and manifest files. Always includes: id, type, name, version, release, namespace,
subpath, alerts, and alertPriorities.'
schema:
type: boolean
default: false
- name: fixable
in: query
required: false
description: Include only fixable alerts.
schema:
type: boolean
default: false
- name: licenseattrib
in: query
required: false
description: Include license attribution data, including license text and author information. Maps attribution/license text to a list of data objects to which that attribution info applies.
schema:
type: boolean
default: false
- name: licensedetails
in: query
required: false
description: Include detailed license information, including location and match strength, for each license datum.
schema:
type: boolean
default: false
- name: purlErrors
in: query
required: false
description: Return errors found with handling PURLs as error objects in the stream.
schema:
type: boolean
default: false
- name: poll
in: query
required: false
description: When true, wait up to timeoutSec for pending analysis to complete before returning. When false (default), return the current known state immediately, including synthesized pendingScan
and notFound alerts when alerts=true unless purlErrors=true keeps legacy not-found errors.
schema:
type: boolean
default: false
- name: cachedResultsOnly
in: query
required: false
description: 'Legacy fallback for older clients. Only used when poll is omitted: cachedResultsOnly=true behaves like poll=false, while cachedResultsOnly=false preserves the older blocking behavior.'
schema:
type: boolean
default: false
- name: summary
in: query
required: false
description: Include a summary object at the end of the stream with counts of malformed, resolved, and not found PURLs.
schema:
type: boolean
default: false
- name: timeoutSec
in: query
required: false
description: Maximum time in seconds to wait for package resolution and, when poll=true, pending analysis. Inputs that have not completed processing when the timeout is reached return pendingScan
alerts when alerts=true, or errors when purlErrors=true.
schema:
type: integer
minimum: 1
maximum: 1200
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SocketOrgBatchPURLFetch'
required: false
security:
- bearerAuth:
- packages:list
- basicAuth:
- packages:list
description: "Batch retrieval of package metadata and alerts by PURL strings for a specific organization. Compatible with CycloneDX reports.\n\nPackage URLs (PURLs) are an ecosystem agnostic way to\
\ identify packages.\nCycloneDX SBOMs use the purl format to identify components.\nThis 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.\n\n**Note:** This endpoint has a batch size limit (default: 1024 PURLs per request). Requests exceeding this limit will return a 400 Bad Request error.\n\
\nMore information on purl and CycloneDX:\n\n- [`purl` Spec](https://github.com/package-url/purl-spec)\n- [CycloneDX Spec](https://cyclonedx.org/specification/overview/#components)\n\nThis endpoint\
\ returns the latest available alert data for artifacts in the batch (stale while revalidate).\nActively running analysis will be returned when available on subsequent runs.\n\nWhen `alerts=true`,\
\ Socket may synthesize two alert types to make partial\nresults actionable:\n\n- `pendingScan`: the package is known but analysis has not completed yet\n- `notFound`: Socket could not resolve the\
\ package/version metadata\n\nWhen `purlErrors=true`, unresolved `notFound` inputs keep the legacy\n`purlError` stream shape instead of emitting synthetic `notFound`\nartifacts.\n\nUse `poll=false`\
\ (default) to fail open and return the current known state\nquickly. Use `poll=true` to fail closed and wait up to `timeoutSec` for\npending analysis before returning.\n\n## Query Parameters\n\n\
This endpoint supports all query parameters from `POST /v0/purl` including: `alerts`, `actions`, `compact`, `fixable`, `licenseattrib`, `licensedetails`, `purlErrors`, `poll`, `cachedResultsOnly`,\
\ and `summary`.\n\nAdditionally, 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.\n\n## Examples:\n\n### Looking up an npm package:\n\n```json\n{\n \"components\": [\n {\n \"purl\": \"pkg:npm/express@4.19.2\"\n }\n ]\n}\n```\n\n\
### Looking up a PyPi package:\n\n```json\n{\n \"components\": [\n {\n \"purl\": \"pkg:pypi/django@5.0.6\"\n }\n ]\n}\n```\n\n### Looking up a Maven package:\n\n```json\n{\n \"components\"\
: [\n {\n \"purl\": \"pkg:maven/log4j/log4j@1.2.17\"\n }\n ]\n}\n```\n\n### Batch lookup\n\n```json\n{\n \"components\": [\n {\n \"purl\": \"pkg:npm/express@4.19.2\"\n },\n\
\ {\n \"purl\": \"pkg:pypi/django@5.0.6\"\n },\n {\n \"purl\": \"pkg:maven/log4j/log4j@1.2.17\"\n }\n ]\n}\n```\n\n### With label and options (query parameters):\n\n```\n\
POST /v0/orgs/{org_slug}/purl?labels=production&alerts=true&compact=true\n{\n \"components\": [\n {\n \"purl\": \"pkg:npm/express@4.19.2\"\n }\n ]\n}\n```\n\nThis endpoint consumes\
\ 100 units of your quota.\n\nThis endpoint requires the following org token scopes:\n- packages:list"
responses:
'200':
content:
application/x-ndjson:
schema:
$ref: '#/components/schemas/BatchPurlStreamSchema'
description: Socket issue lists and scores for all packages, and optional metadata objects
'400':
$ref: '#/components/responses/SocketBadRequest'
'401':
$ref: '#/components/responses/SocketUnauthorized'
'403':
$ref: '#/components/responses/SocketForbidden'
'404':
$ref: '#/components/responses/SocketNotFoundResponse'
'429':
$ref: '#/components/responses/SocketTooManyRequestsResponse'
x-readme: {}
components:
requestBodies: {}
responses:
SocketBadRequest:
content:
application/json:
schema:
type: object
additionalProperties: false
description: ''
properties:
error:
type: object
additionalProperties: false
description: ''
properties:
message:
type: string
description: ''
default: ''
details:
type: object
description: ''
default: null
nullable: true
required:
- details
- message
required:
- error
description: Bad request
SocketUnauthorized:
content:
application/json:
schema:
type: object
additionalProperties: false
description: ''
properties:
error:
type: object
additionalProperties: false
description: ''
properties:
message:
type: string
description: ''
default: ''
details:
type: object
description: ''
default: null
nullable: true
required:
- details
- message
required:
- error
description: Unauthorized
SocketForbidden:
content:
application/json:
schema:
type: object
additionalProperties: false
description: ''
properties:
error:
type: object
additionalProperties: false
description: ''
properties:
message:
type: string
description: ''
default: ''
details:
type: object
description: ''
default: null
nullable: true
required:
- details
- message
required:
- error
description: Insufficient max_quota for API method
SocketNotFoundResponse:
content:
application/json:
schema:
type: object
additionalProperties: false
description: ''
properties:
error:
type: object
additionalProperties: false
description: ''
properties:
message:
type: string
description: ''
default: ''
details:
type: object
description: ''
default: null
nullable: true
required:
- details
- message
required:
- error
description: Resource not found
SocketTooManyRequestsResponse:
description: Insufficient quota for API route
headers:
Retry-After:
description: 'Retry contacting the endpoint *at least* after seconds.
See https://tools.ietf.org/html/rfc7231#section-7.1.3'
schema:
format: int32
type: integer
content:
application/json:
schema:
type: object
additionalProperties: false
description: ''
properties:
error:
type: object
additionalProperties: false
description: ''
properties:
message:
type: string
description: ''
default: ''
details:
type: object
description: ''
default: null
nullable: true
required:
- details
- message
required:
- error
SocketInternalServerError:
content:
application/json:
schema:
type: object
additionalProperties: false
description: ''
properties:
error:
type: object
additionalProperties: false
description: ''
properties:
message:
type: string
description: ''
default: ''
details:
type: object
description: ''
default: null
nullable: true
required:
- details
- message
required:
- error
description: Internal server error
SocketConflict:
content:
application/json:
schema:
type: object
additionalProperties: false
description: ''
properties:
error:
type: object
additionalProperties: false
description: ''
properties:
message:
type: string
description: ''
default: ''
details:
type: object
description: ''
default: null
nullable: true
required:
- details
- message
required:
- error
description: Resource already exists
SocketGone:
content:
application/json:
schema:
type: object
additionalProperties: false
description: ''
properties:
error:
type: object
additionalProperties: false
description: ''
properties:
message:
type: string
description: ''
default: ''
details:
type: object
description: ''
default: null
nullable: true
required:
- details
- message
required:
- error
description: Gone
schemas:
PurlSummarySchema:
type: object
additionalProperties: false
description: ''
properties:
purl_input:
type: integer
description: ''
default: 0
resolved:
type: integer
description: ''
default: 0
errors:
type: object
additionalProperties: false
description: ''
properties:
purl_malformed:
type: integer
description: ''
default: 0
package_not_found:
type: integer
description: ''
default: 0
required:
- package_not_found
- purl_malformed
required:
- errors
- purl_input
- resolved
ReachabilityResultItem:
type: object
additionalProperties: false
properties:
type:
$ref: '#/components/schemas/ReachabilityType'
truncated:
type: boolean
default: false
description: Indicates if the reachability analysis was stopped early due to depth or complexity limits
error:
type: string
description: Error message if reachability analysis failed
default: ''
matches:
anyOf:
- type: object
additionalProperties: false
properties:
type:
type: string
enum:
- function-level
value:
type: array
items:
type: array
items:
$ref: '#/components/schemas/CallStackItem'
description: ''
description: ''
- type: object
additionalProperties: false
properties:
type:
type: string
enum:
- class-level
value:
type: array
items:
type: array
items:
$ref: '#/components/schemas/ClassStackItem'
description: ''
description: ''
workspacePath:
type: string
description: Path to the workspace root for multi-workspace projects
default: ''
subprojectPath:
type: string
description: Path to the subproject within the workspace
default: ''
required:
- type
SocketArtifactPatch:
type: object
additionalProperties: false
properties:
appliedPatch:
$ref: '#/components/schemas/SocketPatch'
availablePatches:
type: array
items:
$ref: '#/components/schemas/SocketPatch'
description: List of available patches that can be applied to fix vulnerabilities
description: ''
SocketScore:
type: object
additionalProperties: false
description: ''
properties:
license:
type: number
description: Score from 0.0 to 1.0 evaluating license permissiveness and compatibility
default: 0
maintenance:
type: number
description: Score from 0.0 to 1.0 evaluating project maintenance health and activity
default: 0
overall:
type: number
description: Combined score from 0.0 to 1.0 representing overall package health and safety
default: 0
quality:
type: number
description: Score from 0.0 to 1.0 evaluating code quality, testing, and documentation
default: 0
supplyChain:
type: number
description: Score from 0.0 to 1.0 evaluating supply chain security and provenance
default: 0
vulnerability:
type: number
description: Score from 0.0 to 1.0 based on known vulnerabilities and their severity
default: 0
required:
- license
- maintenance
- overall
- quality
- supplyChain
- vulnerability
ClassStackItem:
type: object
additionalProperties: false
properties:
purl:
type: string
description: Package URL (PURL) of the dependency containing this class
default: ''
class:
type: string
description: Name of the class in the dependency
default: ''
confidence:
type: number
description: Confidence score from 0.0 to 1.0 indicating how certain the reachability analysis is about this result
default: 0
description: ''
SocketOrgBatchPURLFetch:
type: object
additionalProperties: false
properties:
components:
type: array
items:
$ref: '#/components/schemas/SocketBatchPURLRequest'
description: ''
required:
- components
SAttrib1_N:
type: array
items:
type: object
additionalProperties: false
description: ''
properties:
attribText:
type: string
description: Full text of the license attribution or copyright notice found in the package
default: ''
attribData:
type: array
items:
type: object
additionalProperties: false
description: ''
properties:
purl:
type: string
description: Package URL this attribution applies to
default: ''
foundInFilepath:
type: string
description: File path where this attribution was found
default: ''
spdxExpr:
type: string
description: SPDX license expression parsed from the attribution text
default: ''
foundAuthors:
type: array
items:
type: string
description: ''
default: ''
description: Authors mentioned in this attribution
required:
- foundAuthors
- foundInFilepath
- purl
- spdxExpr
description: ''
required:
- attribData
- attribText
description: ''
SocketAlert:
type: object
additionalProperties: false
properties:
key:
type: string
description: Unique identifier for this alert instance, used for deduplication and tracking across scans
default: ''
type:
type: string
description: Alert type identifier referencing the alert type definition
default: ''
severity:
$ref: '#/components/schemas/SocketIssueSeverity'
category:
$ref: '#/components/schemas/SocketCategory'
file:
type: string
description: File path where this alert was detected
default: ''
start:
type: integer
description: Starting position of the alert in the file
default: 0
end:
type: integer
description: Ending position of the alert in the file
default: 0
props:
type: object
description: Additional alert-specific properties and metadata that vary by alert type
default: null
action:
type: string
description: Action to take for this alert (e.g., error, warn, ignore)
default: ''
actionSource:
type: object
additionalProperties: false
description: ''
properties:
type:
type: string
description: Type of action source (e.g., policy, override)
default: ''
candidates:
type: array
items:
type: object
additionalProperties: false
description: ''
properties:
type:
type: string
description: Type of action candidate
default: ''
action:
type: string
description: Proposed action for this candidate
default: ''
actionPolicyIndex:
type: integer
description: Index of the policy rule for this candidate
default: 0
repoLabelId:
type: string
description: Repository label ID associated with this candidate
default: ''
required:
- action
- actionPolicyIndex
- repoLabelId
- type
description: ''
required:
- candidates
- type
actionPolicyIndex:
type: integer
description: Index of the policy rule that triggered this action, for traceability to security policies
default: 0
fix:
type: object
additionalProperties: false
properties:
type:
type: string
description: Type of fix available (e.g., upgrade, remove, cve)
default: ''
description:
type: string
description: Human-readable description of how to fix this issue
default: ''
patch:
type: array
items:
type: object
additionalProperties: false
properties:
uuid:
type: string
description: Unique identifier for this patch
default: ''
tier:
type: string
enum:
- free
- paid
description: Access tier required for this patch (free or paid)
default: free
deprecated:
type: boolean
# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/socket-dev/refs/heads/main/openapi/socket-packages-api-openapi.yml