Socket packages API

openapi: 3.2.0
info:
  description: Specification of the Socket API endpoints
  title: Endpoints 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:
    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: ''
    BatchPurlStreamSchema:
      anyOf:
      - $ref: '#/components/schemas/SocketArtifact'
      - type: object
        additionalProperties: false
        properties:
          _type:
            type: string
            enum:
            - purlError
          value:
            $ref: '#/components/schemas/PurlErrorSchema'
        required:
        - _type
        - value
      - type: object
        additionalProperties: false
        properties:
          _type:
            type: string
            enum:
            - summary
          value:
            $ref: '#/components/schemas/PurlSummarySchema'
        required:
        - _type
        - value
    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. For vulnerability alerts this includes the `cveId` and `ghsaId` identifiers, either of which may be an empty string when GitHub has not assigned that identifier to the advisory.
          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
                    default: false
                    description: Indicates if this patch is deprecated and should not be used
                required:
                - tier
                - uuid
              description: Patches available to fix this specific alert
          required:
          - description
          - type
        patch:
          $ref: '#/components/schemas/SocketPatch'
        reachability:
          type: object
          additionalProperties: false
          properties:
            head:
              $ref: '#/components/schemas/ReachabilityResult'
            base:
              $ref: '#/components/schemas/ReachabilityResult'
          description: ''
        subType:
          type: string
          description: Generic alert sub-type
          default: ''
      required:
      - key
      - type
    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: ''
          publishedAt:
            type: string
            description: ISO-8601 timestamp of when this package version was published, when known
            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'
    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: ''
    SourceLocation:
      type: object
      additionalProperties: false
      description: ''
      properties:
        start:
          type: object
          additionalProperties: false
          description: ''
          properties:
            line:
              type: integer
              description: Line number in the source file
              default: 0
            column:
              type: integer
              description: Column number in the source file
              default: 0
            byteOffset:
              type: integer
              description: Absolute byte position from the beginning of the file, used for precise location tracking
              default: 0
          required:
          - byteOffset
          - column
          - line
        end:
          type: object
          additionalProperties: false
          properties:
            line:
              type: integer
              description: Line number in the source file
              default: 0
            column:
              type: integer
              description: Column number in the source file
              default: 0
            byteOffset:
              type: integer
              description: Absolute byte position from the beginning of the file, used for precise location tracking
              default: 0
          description: ''
        filename:
          type: string
          description: Path to the source file
          default: ''
        fileHash:
          type: string
          description: Hash of the source file for integrity verification
          default: ''
      required:
      - end
      - fileHash
      - filename
      - start
    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
    SocketId:
      type: string
      description: ''
      default: ''
    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:
      

# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/socket/refs/heads/main/openapi/socket-packages-api-openapi.yml