Socket packages API

openapi: 3.2.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:
  responses:
    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
                    - 'null'
                    description: ''
                    default: null
                required:
                - details
                - message
            required:
            - error
    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
                    - 'null'
                    description: ''
                    default: null
                required:
                - details
                - message
            required:
            - error
      description: Insufficient max_quota for API method
    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
                    - 'null'
                    description: ''
                    default: null
                required:
                - details
                - message
            required:
            - error
      description: Unauthorized
    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
                    - 'null'
                    description: ''
                    default: null
                required:
                - details
                - message
            required:
            - error
      description: Resource not found
    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
                    - 'null'
                    description: ''
                    default: null
                required:
                - details
                - message
            required:
            - error
      description: Bad request
  schemas:
    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: ''
    SocketOrgBatchPURLFetch:
      type: object
      additionalProperties: false
      properties:
        components:
          type: array
          items:
            $ref: '#/components/schemas/SocketBatchPURLRequest'
          description: ''
      required:
      - components
    ReachabilityResult:
      type: object
      additionalProperties: false
      description: ''
      properties:
        type:
          type: string
          enum:
          - precomputed
          - full-scan
          description: Type of reachability analysis performed
          default: precomputed
        results:
          type: array
          items:
            $ref: '#/components/schemas/ReachabilityResultItem'
          description: Reachability analysis results for each vulnerability
      required:
      - results
      - type
    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
    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
    SocketIssueSeverity:
      type: string
      enum:
      - low
      - middle
      - high
      - critical
      description: ''
      default: low
    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: ''
    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: ''
    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: ''
    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
    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
    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
    SocketId:
      type: string
      description: ''
      default: ''
    SocketCategory:
      type: string
      enum:
      - supplyChainRisk
      - quality
      - maintenance
      - vulnerability
      - license
      - other
      description: ''
      default: other
    PurlErrorSchema:
      type: object
      additionalProperties: false
      description: ''
      properties:
        error:
          type: string
          description: ''
          default: ''
        inputPurl:
          type: string
          description: ''
          default: ''
      required:
      - error
      - inputPurl
    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
    SocketBatchPURLRequest:
      type: object
      additionalProperties: false
      description: ''
      properties:
        purl:
          type: string
          description: ''
          default: ''
      required:
      - purl
    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
    SocketArtifact:
      allOf:
      - $ref: '#/components/schemas/SocketPURL'
      - 

# --- 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