openapi: 3.0.0
info:
  description: Socket packages API endpoints.
  title: Socket Packages API
  version: '0'
servers:
- url: https://api.socket.dev/v0
paths:
  /purl:
    post:
      tags:
      - packages
      summary: Get Packages by PURL
      deprecated: true
      externalDocs:
        description: Socket Package URLs (purl)
        url: https://docs.socket.dev/reference/socket-package-urls-purl
      operationId: batchPackageFetch
      parameters:
      - name: alerts
        in: query
        required: false
        description: Include alert metadata.
        schema:
          type: boolean
          default: false
      - name: actions
        in: query
        required: false
        description: Include only alerts with comma separated actions defined by security policy.
        schema:
          type: array
          items:
            type: string
            enum:
            - error
            - monitor
            - warn
            - ignore
        explode: false
        style: form
      - name: compact
        in: query
        required: false
        description: 'Compact metadata. When enabled, excludes metadata fields like author, scores, size, dependencies, and manifest files. Always includes: id, type, name, version, release, namespace,
          subpath, alerts, and alertPriorities.'
        schema:
          type: boolean
          default: false
      - name: fixable
        in: query
        required: false
        description: Include only fixable alerts.
        schema:
          type: boolean
          default: false
      - name: licenseattrib
        in: query
        required: false
        description: Include license attribution data, including license text and author information. Maps attribution/license text to a list of data objects to which that attribution info applies.
        schema:
          type: boolean
          default: false
      - name: licensedetails
        in: query
        required: false
        description: Include detailed license information, including location and match strength, for each license datum.
        schema:
          type: boolean
          default: false
      - name: purlErrors
        in: query
        required: false
        description: Return errors found with handling PURLs as error objects in the stream.
        schema:
          type: boolean
          default: false
      - name: poll
        in: query
        required: false
        description: When true, wait up to timeoutSec for pending analysis to complete before returning. When false (default), return the current known state immediately, including synthesized pendingScan
          and notFound alerts when alerts=true unless purlErrors=true keeps legacy not-found errors.
        schema:
          type: boolean
          default: false
      - name: cachedResultsOnly
        in: query
        required: false
        description: 'Legacy fallback for older clients. Only used when poll is omitted: cachedResultsOnly=true behaves like poll=false, while cachedResultsOnly=false preserves the older blocking behavior.'
        schema:
          type: boolean
          default: false
      - name: summary
        in: query
        required: false
        description: Include a summary object at the end of the stream with counts of malformed, resolved, and not found PURLs.
        schema:
          type: boolean
          default: false
      - name: timeoutSec
        in: query
        required: false
        description: Maximum time in seconds to wait for package resolution and, when poll=true, pending analysis. Inputs that have not completed processing when the timeout is reached return pendingScan
          alerts when alerts=true, or errors when purlErrors=true.
        schema:
          type: integer
          minimum: 1
          maximum: 1200
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SocketOrgBatchPURLFetch'
        required: false
      security:
      - bearerAuth:
        - packages:list
      - basicAuth:
        - packages:list
      description: "**This endpoint is deprecated.** Deprecated since 2026-01-05.\n\nBatch retrieval of package metadata and alerts by PURL strings. Compatible with CycloneDX reports.\n\nPackage URLs (PURLs)\
        \ are an ecosystem agnostic way to identify packages.\nCycloneDX SBOMs use the purl format to identify components.\nThis endpoint supports fetching metadata and alerts for multiple packages at once\
        \ by passing an array of purl strings, or by passing an entire CycloneDX report.\n\n**Note:** This endpoint has a batch size limit (default: 1024 PURLs per request). Requests exceeding this limit\
        \ will return a 400 Bad Request error.\n\nMore information on purl and CycloneDX:\n\n- [`purl` Spec](https://github.com/package-url/purl-spec)\n- [CycloneDX Spec](https://cyclonedx.org/specification/overview/#components)\n\
        \nThis endpoint returns the latest available alert data for artifacts in the batch (stale while revalidate).\nActively running analysis will be returned when available on subsequent runs.\n\nWhen\
        \ `alerts=true`, Socket may synthesize two alert types to make partial\nresults actionable:\n\n- `pendingScan`: the package is known but analysis has not completed yet\n- `notFound`: Socket could\
        \ not resolve the package/version metadata\n\nWhen `purlErrors=true`, unresolved `notFound` inputs keep the legacy\n`purlError` stream shape instead of emitting synthetic `notFound`\nartifacts.\n\
        \nUse `poll=false` (default) to fail open and return the current known state\nquickly. Use `poll=true` to fail closed and wait up to `timeoutSec` for\npending analysis before returning.\n\n## Examples:\n\
        \n### Looking up an npm package:\n\n```json\n{\n  \"components\": [\n    {\n      \"purl\": \"pkg:npm/express@4.19.2\"\n    }\n  ]\n}\n```\n\n### Looking up an PyPi package:\n\n```json\n{\n  \"\
        components\": [\n    {\n      \"purl\": \"pkg:pypi/django@5.0.6\"\n    }\n  ]\n}\n```\n\n### Looking up a Maven package:\n\n```json\n{\n  \"components\": [\n    {\n      \"purl\": \"pkg:maven/log4j/log4j@1.2.17\"\
        \n    }\n  ]\n}\n```\n\n### Batch lookup\n\n```json\n{\n  \"components\": [\n    {\n      \"purl\": \"pkg:npm/express@4.19.2\"\n    },\n    {\n      \"purl\": \"pkg:pypi/django@5.0.6\"\n    },\n\
        \    {\n      \"purl\": \"pkg:maven/log4j/log4j@1.2.17\"\n    }\n  ]\n}\n```\n\nThis endpoint consumes 100 units of your quota.\n\nThis endpoint requires the following org token scopes:\n- packages:list"
      responses:
        '200':
          content:
            application/x-ndjson:
              schema:
                $ref: '#/components/schemas/BatchPurlStreamSchema'
          description: Socket issue lists and scores for all packages, and optional metadata objects
        '400':
          $ref: '#/components/responses/SocketBadRequest'
        '401':
          $ref: '#/components/responses/SocketUnauthorized'
        '403':
          $ref: '#/components/responses/SocketForbidden'
        '404':
          $ref: '#/components/responses/SocketNotFoundResponse'
        '429':
          $ref: '#/components/responses/SocketTooManyRequestsResponse'
      x-readme: {}
  /orgs/{org_slug}/purl:
    post:
      tags:
      - packages
      summary: Get Packages by PURL (Org Scoped)
      externalDocs:
        description: Socket Package URLs (purl)
        url: https://docs.socket.dev/reference/socket-package-urls-purl
      operationId: batchPackageFetchByOrg
      parameters:
      - name: org_slug
        in: path
        required: true
        description: The slug of the organization
        schema:
          type: string
      - name: labels
        in: query
        required: false
        description: Repository label slugs to apply policies. Only one label is supported currently; the parameter is an array to allow future support for multiple labels.
        schema:
          type: array
          items:
            type: string
        explode: false
        style: form
      - name: alerts
        in: query
        required: false
        description: Include alert metadata.
        schema:
          type: boolean
          default: false
      - name: actions
        in: query
        required: false
        description: Include only alerts with comma separated actions defined by security policy.
        schema:
          type: array
          items:
            type: string
            enum:
            - error
            - monitor
            - warn
            - ignore
        explode: false
        style: form
      - name: compact
        in: query
        required: false
        description: 'Compact metadata. When enabled, excludes metadata fields like author, scores, size, dependencies, and manifest files. Always includes: id, type, name, version, release, namespace,
          subpath, alerts, and alertPriorities.'
        schema:
          type: boolean
          default: false
      - name: fixable
        in: query
        required: false
        description: Include only fixable alerts.
        schema:
          type: boolean
          default: false
      - name: licenseattrib
        in: query
        required: false
        description: Include license attribution data, including license text and author information. Maps attribution/license text to a list of data objects to which that attribution info applies.
        schema:
          type: boolean
          default: false
      - name: licensedetails
        in: query
        required: false
        description: Include detailed license information, including location and match strength, for each license datum.
        schema:
          type: boolean
          default: false
      - name: purlErrors
        in: query
        required: false
        description: Return errors found with handling PURLs as error objects in the stream.
        schema:
          type: boolean
          default: false
      - name: poll
        in: query
        required: false
        description: When true, wait up to timeoutSec for pending analysis to complete before returning. When false (default), return the current known state immediately, including synthesized pendingScan
          and notFound alerts when alerts=true unless purlErrors=true keeps legacy not-found errors.
        schema:
          type: boolean
          default: false
      - name: cachedResultsOnly
        in: query
        required: false
        description: 'Legacy fallback for older clients. Only used when poll is omitted: cachedResultsOnly=true behaves like poll=false, while cachedResultsOnly=false preserves the older blocking behavior.'
        schema:
          type: boolean
          default: false
      - name: summary
        in: query
        required: false
        description: Include a summary object at the end of the stream with counts of malformed, resolved, and not found PURLs.
        schema:
          type: boolean
          default: false
      - name: timeoutSec
        in: query
        required: false
        description: Maximum time in seconds to wait for package resolution and, when poll=true, pending analysis. Inputs that have not completed processing when the timeout is reached return pendingScan
          alerts when alerts=true, or errors when purlErrors=true.
        schema:
          type: integer
          minimum: 1
          maximum: 1200
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SocketOrgBatchPURLFetch'
        required: false
      security:
      - bearerAuth:
        - packages:list
      - basicAuth:
        - packages:list
      description: "Batch retrieval of package metadata and alerts by PURL strings for a specific organization. Compatible with CycloneDX reports.\n\nPackage URLs (PURLs) are an ecosystem agnostic way to\
        \ identify packages.\nCycloneDX SBOMs use the purl format to identify components.\nThis endpoint supports fetching metadata and alerts for multiple packages at once by passing an array of purl strings,\
        \ or by passing an entire CycloneDX report.\n\n**Note:** This endpoint has a batch size limit (default: 1024 PURLs per request). Requests exceeding this limit will return a 400 Bad Request error.\n\
        \nMore information on purl and CycloneDX:\n\n- [`purl` Spec](https://github.com/package-url/purl-spec)\n- [CycloneDX Spec](https://cyclonedx.org/specification/overview/#components)\n\nThis endpoint\
        \ returns the latest available alert data for artifacts in the batch (stale while revalidate).\nActively running analysis will be returned when available on subsequent runs.\n\nWhen `alerts=true`,\
        \ Socket may synthesize two alert types to make partial\nresults actionable:\n\n- `pendingScan`: the package is known but analysis has not completed yet\n- `notFound`: Socket could not resolve the\
        \ package/version metadata\n\nWhen `purlErrors=true`, unresolved `notFound` inputs keep the legacy\n`purlError` stream shape instead of emitting synthetic `notFound`\nartifacts.\n\nUse `poll=false`\
        \ (default) to fail open and return the current known state\nquickly. Use `poll=true` to fail closed and wait up to `timeoutSec` for\npending analysis before returning.\n\n## Query Parameters\n\n\
        This endpoint supports all query parameters from `POST /v0/purl` including: `alerts`, `actions`, `compact`, `fixable`, `licenseattrib`, `licensedetails`, `purlErrors`, `poll`, `cachedResultsOnly`,\
        \ and `summary`.\n\nAdditionally, you may provide a `labels` query parameter to apply a repository label's security policies. Pass the label slug as the value (e.g., `?labels=production`). Only\
        \ one label is currently supported.\n\n## Examples:\n\n### Looking up an npm package:\n\n```json\n{\n  \"components\": [\n    {\n      \"purl\": \"pkg:npm/express@4.19.2\"\n    }\n  ]\n}\n```\n\n\
        ### Looking up a PyPi package:\n\n```json\n{\n  \"components\": [\n    {\n      \"purl\": \"pkg:pypi/django@5.0.6\"\n    }\n  ]\n}\n```\n\n### Looking up a Maven package:\n\n```json\n{\n  \"components\"\
        : [\n    {\n      \"purl\": \"pkg:maven/log4j/log4j@1.2.17\"\n    }\n  ]\n}\n```\n\n### Batch lookup\n\n```json\n{\n  \"components\": [\n    {\n      \"purl\": \"pkg:npm/express@4.19.2\"\n    },\n\
        \    {\n      \"purl\": \"pkg:pypi/django@5.0.6\"\n    },\n    {\n      \"purl\": \"pkg:maven/log4j/log4j@1.2.17\"\n    }\n  ]\n}\n```\n\n### With label and options (query parameters):\n\n```\n\
        POST /v0/orgs/{org_slug}/purl?labels=production&alerts=true&compact=true\n{\n  \"components\": [\n    {\n      \"purl\": \"pkg:npm/express@4.19.2\"\n    }\n  ]\n}\n```\n\nThis endpoint consumes\
        \ 100 units of your quota.\n\nThis endpoint requires the following org token scopes:\n- packages:list"
      responses:
        '200':
          content:
            application/x-ndjson:
              schema:
                $ref: '#/components/schemas/BatchPurlStreamSchema'
          description: Socket issue lists and scores for all packages, and optional metadata objects
        '400':
          $ref: '#/components/responses/SocketBadRequest'
        '401':
          $ref: '#/components/responses/SocketUnauthorized'
        '403':
          $ref: '#/components/responses/SocketForbidden'
        '404':
          $ref: '#/components/responses/SocketNotFoundResponse'
        '429':
          $ref: '#/components/responses/SocketTooManyRequestsResponse'
      x-readme: {}
components:
  requestBodies: {}
  responses:
    SocketBadRequest:
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
      description: Bad request
    SocketUnauthorized:
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
      description: Unauthorized
    SocketForbidden:
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
      description: Insufficient max_quota for API method
    SocketNotFoundResponse:
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
      description: Resource not found
    SocketTooManyRequestsResponse:
      description: Insufficient quota for API route
      headers:
        Retry-After:
          description: 'Retry contacting the endpoint *at least* after seconds.

            See https://tools.ietf.org/html/rfc7231#section-7.1.3'
          schema:
            format: int32
            type: integer
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
    SocketInternalServerError:
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
      description: Internal server error
    SocketConflict:
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
      description: Resource already exists
    SocketGone:
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
      description: Gone
  schemas:
    PurlSummarySchema:
      type: object
      additionalProperties: false
      description: ''
      properties:
        purl_input:
          type: integer
          description: ''
          default: 0
        resolved:
          type: integer
          description: ''
          default: 0
        errors:
          type: object
          additionalProperties: false
          description: ''
          properties:
            purl_malformed:
              type: integer
              description: ''
              default: 0
            package_not_found:
              type: integer
              description: ''
              default: 0
          required:
          - package_not_found
          - purl_malformed
      required:
      - errors
      - purl_input
      - resolved
    ReachabilityResultItem:
      type: object
      additionalProperties: false
      properties:
        type:
          $ref: '#/components/schemas/ReachabilityType'
        truncated:
          type: boolean
          default: false
          description: Indicates if the reachability analysis was stopped early due to depth or complexity limits
        error:
          type: string
          description: Error message if reachability analysis failed
          default: ''
        matches:
          anyOf:
          - type: object
            additionalProperties: false
            properties:
              type:
                type: string
                enum:
                - function-level
              value:
                type: array
                items:
                  type: array
                  items:
                    $ref: '#/components/schemas/CallStackItem'
                  description: ''
                description: ''
          - type: object
            additionalProperties: false
            properties:
              type:
                type: string
                enum:
                - class-level
              value:
                type: array
                items:
                  type: array
                  items:
                    $ref: '#/components/schemas/ClassStackItem'
                  description: ''
                description: ''
        workspacePath:
          type: string
          description: Path to the workspace root for multi-workspace projects
          default: ''
        subprojectPath:
          type: string
          description: Path to the subproject within the workspace
          default: ''
      required:
      - type
    SocketArtifactPatch:
      type: object
      additionalProperties: false
      properties:
        appliedPatch:
          $ref: '#/components/schemas/SocketPatch'
        availablePatches:
          type: array
          items:
            $ref: '#/components/schemas/SocketPatch'
          description: List of available patches that can be applied to fix vulnerabilities
      description: ''
    SocketScore:
      type: object
      additionalProperties: false
      description: ''
      properties:
        license:
          type: number
          description: Score from 0.0 to 1.0 evaluating license permissiveness and compatibility
          default: 0
        maintenance:
          type: number
          description: Score from 0.0 to 1.0 evaluating project maintenance health and activity
          default: 0
        overall:
          type: number
          description: Combined score from 0.0 to 1.0 representing overall package health and safety
          default: 0
        quality:
          type: number
          description: Score from 0.0 to 1.0 evaluating code quality, testing, and documentation
          default: 0
        supplyChain:
          type: number
          description: Score from 0.0 to 1.0 evaluating supply chain security and provenance
          default: 0
        vulnerability:
          type: number
          description: Score from 0.0 to 1.0 based on known vulnerabilities and their severity
          default: 0
      required:
      - license
      - maintenance
      - overall
      - quality
      - supplyChain
      - vulnerability
    ClassStackItem:
      type: object
      additionalProperties: false
      properties:
        purl:
          type: string
          description: Package URL (PURL) of the dependency containing this class
          default: ''
        class:
          type: string
          description: Name of the class in the dependency
          default: ''
        confidence:
          type: number
          description: Confidence score from 0.0 to 1.0 indicating how certain the reachability analysis is about this result
          default: 0
      description: ''
    SocketOrgBatchPURLFetch:
      type: object
      additionalProperties: false
      properties:
        components:
          type: array
          items:
            $ref: '#/components/schemas/SocketBatchPURLRequest'
          description: ''
      required:
      - components
    SAttrib1_N:
      type: array
      items:
        type: object
        additionalProperties: false
        description: ''
        properties:
          attribText:
            type: string
            description: Full text of the license attribution or copyright notice found in the package
            default: ''
          attribData:
            type: array
            items:
              type: object
              additionalProperties: false
              description: ''
              properties:
                purl:
                  type: string
                  description: Package URL this attribution applies to
                  default: ''
                foundInFilepath:
                  type: string
                  description: File path where this attribution was found
                  default: ''
                spdxExpr:
                  type: string
                  description: SPDX license expression parsed from the attribution text
                  default: ''
                foundAuthors:
                  type: array
                  items:
                    type: string
                    description: ''
                    default: ''
                  description: Authors mentioned in this attribution
              required:
              - foundAuthors
              - foundInFilepath
              - purl
              - spdxExpr
            description: ''
        required:
        - attribData
        - attribText
      description: ''
    SocketAlert:
      type: object
      additionalProperties: false
      properties:
        key:
          type: string
          description: Unique identifier for this alert instance, used for deduplication and tracking across scans
          default: ''
        type:
          type: string
          description: Alert type identifier referencing the alert type definition
          default: ''
        severity:
          $ref: '#/components/schemas/SocketIssueSeverity'
        category:
          $ref: '#/components/schemas/SocketCategory'
        file:
          type: string
          description: File path where this alert was detected
          default: ''
        start:
          type: integer
          description: Starting position of the alert in the file
          default: 0
        end:
          type: integer
          description: Ending position of the alert in the file
          default: 0
        props:
          type: object
          description: Additional alert-specific properties and metadata that vary by alert type
          default: null
        action:
          type: string
          description: Action to take for this alert (e.g., error, warn, ignore)
          default: ''
        actionSource:
          type: object
          additionalProperties: false
          description: ''
          properties:
            type:
              type: string
              description: Type of action source (e.g., policy, override)
              default: ''
            candidates:
              type: array
              items:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  type:
                    type: string
                    description: Type of action candidate
                    default: ''
                  action:
                    type: string
                    description: Proposed action for this candidate
                    default: ''
                  actionPolicyIndex:
                    type: integer
                    description: Index of the policy rule for this candidate
                    default: 0
                  repoLabelId:
                    type: string
                    description: Repository label ID associated with this candidate
                    default: ''
                required:
                - action
                - actionPolicyIndex
                - repoLabelId
                - type
              description: ''
          required:
          - candidates
          - type
        actionPolicyIndex:
          type: integer
          description: Index of the policy rule that triggered this action, for traceability to security policies
          default: 0
        fix:
          type: object
          additionalProperties: false
          properties:
            type:
              type: string
              description: Type of fix available (e.g., upgrade, remove, cve)
              default: ''
            description:
              type: string
              description: Human-readable description of how to fix this issue
              default: ''
            patch:
              type: array
              items:
                type: object
                additionalProperties: false
                properties:
                  uuid:
                    type: string
                    description: Unique identifier for this patch
                    default: ''
                  tier:
                    type: string
                    enum:
                    - free
                    - paid
                    description: Access tier required for this patch (free or paid)
                    default: free
                  deprecated:
                    type: boolean
                    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
    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
    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
    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
    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: ''
    SocketCategory:
      type: string
      enum:
      - supplyChainRisk
      - quality
      - maintenance
      - vulnerability
      - license
      - other
      description: ''
      default: other
    SocketIssueSeverity:
      type: string
      enum:
      - low
      - middle
      - high
      - critical
      description: ''
      default: low
    SocketId:
      type: string
      description: ''
      default: ''
    PurlErrorSchema:
      type: object
      additionalProperties: false
      description: ''
      properties:
        error:
          type: string
          description: ''
          default: ''
        inputPurl:
          type: string
          description: ''
          default: ''
      required:
      - error
      - inputPurl
    SocketBatchPURLRequest:
      type: object
      additionalProperties: false
      description: ''
      properties:
        purl:
          type: string
          description: ''
          default: ''
      required:
      - purl
    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
    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: ''
    SocketArtifact:
      allOf:
      - $ref: '#/components/schemas/SocketPURL'
      - $ref: '#/components/schemas/SocketArtifactLink'
      - type: object
        additionalProperties: false
        properties:
          id:
            $ref: '#/components/schemas/SocketId'
          author:
            type: array
            items:
              type: string
              description: ''
              default: ''
            description: List of package authors or maintainers
          size:
            type: number
            description: Total size of the package artifact in bytes
            default: 0
          repositoryType:
            type: string
            description: Hugging Face model, dataset, or space type
            default: ''
          alerts:
            type: array
            items:
              $ref: '#/components/schemas/SocketAlert'
            description: ''
          score:
            $ref: '#/components/schemas/SocketScore'
          patch:
            $ref: '#/components/schemas/SocketArtifactPatch'
          inputPurl:
            type: string
            description: Original unmodified PURL input string before normalization
            default: ''
          batchIndex:
            type: integer
            description: 'Deprecated: Always 0. Previously used for batch ordering but replaced by inputPurl for better tracking.'
            default: 0
          license:
            type: string
            description: ''
            default: ''
          licenseDetails:
            $ref: '#/components/schemas/LicenseDetails'
          licenseAttrib:
            $ref: '#/components/schemas/SAttrib1_N'
    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
    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
    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
    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: ''
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Organization Tokens can be passed as a Bearer token
    basicAuth:
      type: http
      scheme: basic
      description: Organization Tokens can be passed as the user field in basic auth