openapi: 3.0.0
info:
description: Socket alerts API endpoints.
title: Socket alerts packages API
version: '0'
servers:
- url: https://api.socket.dev/v0
tags:
- name: packages
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\nThis 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```\nPOST /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:
schemas:
SocketOrgBatchPURLFetch:
type: object
additionalProperties: false
properties:
components:
type: array
items:
$ref: '#/components/schemas/SocketBatchPURLRequest'
description: ''
required:
- components
SocketPURL_Type:
type: string
enum:
- alpm
- apk
- bitbucket
- cocoapods
- cargo
- chrome
- clawhub
- composer
- conan
- conda
- cran
- deb
- docker
- gem
- generic
- github
- golang
- hackage
- hex
- huggingface
- maven
- mlflow
- npm
- nuget
- qpkg
- oci
- pub
- pypi
- rpm
- socket
- swid
- swift
- vscode
- unknown
description: Package ecosystem type identifier based on the PURL specification
default: unknown
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: ''
ReachabilityType:
type: string
enum:
- missing_support
- undeterminable_reachability
- pending
- unreachable
- unknown
- direct_dependency
- error
- maybe_reachable
- reachable
description: Status of reachability analysis for vulnerable code paths
default: unknown
SocketIssueSeverity:
type: string
enum:
- low
- middle
- high
- critical
description: ''
default: low
SocketManifestReference:
type: object
additionalProperties: false
properties:
file:
type: string
description: Path to the manifest file (e.g., package.json, pom.xml)
default: ''
start:
type: integer
description: Starting line or position in the manifest file
default: 0
end:
type: integer
description: Ending line or position in the manifest file
default: 0
required:
- file
SocketCategory:
type: string
enum:
- supplyChainRisk
- quality
- maintenance
- vulnerability
- license
- other
description: ''
default: other
SocketId:
type: string
description: ''
default: ''
SocketArtifactLink:
type: object
additionalProperties: false
properties:
direct:
type: boolean
default: false
description: Indicates if this is a direct dependency (not transitive)
dev:
type: boolean
default: false
description: Indicates if this is a development-only dependency not used in production
dead:
type: boolean
default: false
description: Indicates if this package is deprecated, abandoned, or no longer maintained
manifestFiles:
type: array
items:
$ref: '#/components/schemas/SocketManifestReference'
description: ''
topLevelAncestors:
type: array
items:
$ref: '#/components/schemas/SocketId'
description: IDs of the root-level packages in the dependency tree that depend on this package
dependencies:
type: array
items:
$ref: '#/components/schemas/SocketId'
description: IDs of packages that this package directly depends on
alertPriorities:
type: object
additionalProperties:
type: object
additionalProperties: false
properties:
result:
type: integer
description: Computed priority score for this alert
default: 0
components:
type: object
additionalProperties: false
description: ''
properties:
isFixable:
type: object
additionalProperties: false
description: ''
properties:
result:
type: number
description: Contribution of fixability to the priority score
default: 0
value:
type: boolean
default: false
description: Whether a fix is available for this alert
required:
- result
- value
isReachable:
type: object
additionalProperties: false
description: ''
properties:
result:
type: number
description: Contribution of reachability to the priority score
default: 0
value:
type: boolean
default: false
description: Whether the vulnerable code is reachable
specificValue:
type: string
description: Specific reachability type value such as 'unreachable', 'maybe_reachable', or 'reachable'
default: ''
required:
- result
- specificValue
- value
severity:
type: object
additionalProperties: false
description: ''
properties:
result:
type: number
description: Contribution of severity to the priority score
default: 0
value:
type: integer
description: Numeric severity level
default: 0
required:
- result
- value
required:
- isFixable
- isReachable
- severity
formula:
type: string
description: Formula used to calculate the priority score
default: ''
required:
- result
properties: {}
description: Computed priority scores for each alert type based on severity, reachability, and fixability factors
artifact:
allOf:
- $ref: '#/components/schemas/SocketPURL'
- type: object
additionalProperties: false
properties:
id:
$ref: '#/components/schemas/SocketId'
required:
- id
alertKeysToReachabilityTypes:
type: object
additionalProperties:
type: array
items:
type: string
description: ''
default: ''
description: ''
properties: {}
description: 'Deprecated: mapping of alert keys to arrays of reachability types found across different manifest files or code locations. This field is derived from alertKeysToReachabilitySummaries for backward compatibility; use that property instead.'
alertKeysToReachabilitySummaries:
type: object
additionalProperties:
type: array
items:
type: object
additionalProperties: false
description: ''
properties:
type:
type: string
description: ''
default: ''
required:
- type
description: ''
properties: {}
description: Mapping of alert keys to arrays of reachability summaries. Each summary contains a reachability type indicating the result of reachability analysis for the corresponding vulnerability alert.
description: ''
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: ''
PurlErrorSchema:
type: object
additionalProperties: false
description: ''
properties:
error:
type: string
description: ''
default: ''
inputPurl:
type: string
description: ''
default: ''
required:
- error
- inputPurl
CallStackItem:
type: object
additionalProperties: false
properties:
purl:
type: string
description: Package URL (PURL) of the dependency containing this code
default: ''
sourceLocation:
$ref: '#/components/schemas/SourceLocation'
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: ''
SocketPatch:
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
default: false
description: Indicates if this patch is deprecated and should not be used
required:
- tier
- uuid
SocketPURL:
type: object
additionalProperties: false
properties:
type:
$ref: '#/components/schemas/SocketPURL_Type'
namespace:
type: string
description: Package namespace or scope, such as npm organizations (@angular), Maven groupIds, or Docker image owners
default: ''
name:
type: string
description: Package name within its ecosystem
default: ''
version:
type: string
description: Package version string
default: ''
subpath:
type: string
description: Path within the package to a specific file or directory, used to reference nested components
default: ''
release:
type: string
description: Package-specific release identifier, such as PyPI's artifact ID or the specific build/release version
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: ''
SocketArtifact:
allOf:
- $ref: '#/components/schemas/SocketPURL'
- $ref: '#/components/schemas/SocketArtifactLink'
- type: object
additionalProperties: false
properties:
id:
$ref: '#/components/schemas/SocketId'
author:
type: array
items:
type: string
description: ''
default: ''
description: List of package authors or maintainers
size:
type: number
description: Total size of the package artifact in bytes
default: 0
repositoryType:
type: string
description: Hugging Face model, dataset, or space type
default: ''
alerts:
type: array
items:
$ref: '#/components/schemas/SocketAlert'
description: ''
score:
$ref: '#/components/schemas/SocketScore'
patch:
$ref: '#/components/schemas/SocketArtifactPatch'
inputPurl:
type: string
description: Original unmodified PURL input string before normalization
default: ''
batchIndex:
type: integer
description: 'Deprecated: Always 0. Previously used for batch ordering but replaced by inputPurl for better tracking.'
default: 0
license:
type: string
description: ''
default: ''
licenseDetails:
$ref: '#/components/schemas/LicenseDetails'
licenseAttrib:
$ref: '#/components/schemas/SAttrib1_N'
LicenseDetails:
type: array
items:
type: object
additionalProperties: false
description: ''
properties:
spdxDisj:
type: string
description: SPDX license expression in disjunctive normal form (e.g., '(MIT OR Apache-2.0)')
default: ''
authors:
type: array
items:
type: string
description: ''
default: ''
description: List of authors found in the license text
errorData:
type: string
description: Error details if license parsing failed
default: ''
provenance:
type: string
description: Source where this license information was detected (e.g., 'package.json', 'LICENSE file', 'README')
default: ''
filepath:
type: string
description: Path to the file containing this license information
default: ''
match_strength:
type: number
description: Confidence score from 0.0 to 1.0 indicating how well the detected license matches the source text
default: 0
required:
- authors
- errorData
- filepath
- match_strength
- provenance
- spdxDisj
description: ''
SourceLocation:
type: object
additionalProperties: false
description: ''
properties:
start:
type: object
additionalProperties: false
description: ''
properties:
# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/socket-dev/refs/heads/main/openapi/socket-dev-packages-api-openapi.yml