Socket packages API

openapi: 3.0.0
info:
  description: Specification of the Socket API endpoints
  title: API 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:
    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: ''
    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: ''
    SocketBatchPURLRequest:
      type: object
      additionalProperties: false
      description: ''
      properties:
        purl:
          type: string
          description: ''
          default: ''
      required:
      - purl
    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: ''
    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
    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
    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
    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
    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
    SocketOrgBatchPURLFetch:
      type: object
      additionalProperties: false
      properties:
        components:
          type: array
          items:
            $ref: '#/components/schemas/SocketBatchPURLRequest'
          description: ''
      required:
      - components
    PurlErrorSchema:
      type: object
      additionalProperties: false
      description: ''
      properties:
        error:
          type: string
          description: ''
          default: ''
        inputPurl:
          type: string
          description: ''
          default: ''
      required:
      - error
      - inputPurl
    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
    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'
    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:

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