---
updatedAt: 2026-09-19T00:21:21.000Z
agentTools:
  projectIndex: https://docs.socket.dev/llms.txt
---

# Get Packages by PURL

**This endpoint is deprecated.** Deprecated since 2026-01-05.

Batch retrieval of package metadata and alerts by PURL strings. Compatible with CycloneDX reports.

Package URLs (PURLs) are an ecosystem agnostic way to identify packages.
CycloneDX SBOMs use the purl format to identify components.
This 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.

**Note:** This endpoint has a batch size limit (default: 1024 PURLs per request). Requests exceeding this limit will return a 400 Bad Request error.

More information on purl and CycloneDX:

- [`purl` Spec](https://github.com/package-url/purl-spec)
- [CycloneDX Spec](https://cyclonedx.org/specification/overview/#components)

This endpoint returns the latest available alert data for artifacts in the batch (stale while revalidate).
Actively running analysis will be returned when available on subsequent runs.

When `alerts=true`, Socket may synthesize two alert types to make partial
results actionable:

- `pendingScan`: the package is known but analysis has not completed yet
- `notFound`: Socket could not resolve the package/version metadata

When `purlErrors=true`, unresolved `notFound` inputs keep the legacy
`purlError` stream shape instead of emitting synthetic `notFound`
artifacts.

Use `poll=false` (default) to fail open and return the current known state
quickly. Use `poll=true` to fail closed and wait up to `timeoutSec` for
pending analysis before returning.

**Conda (temporary compatibility):** `pkg:conda` inputs are served from the
already-scanned PyPI package with the same normalized name and version when
one exists; the response row keeps the original conda PURL in `inputPurl`
but reports `type: pypi`. Conda `build`, `subdir`, `type`, and `channel`
qualifiers are ignored, and conda packages without a scanned PyPI
counterpart return the normal `notFound` result. This mapping will be
replaced by native conda support.

## Examples:

### Looking up an npm package:

```json
{
  "components": [
    {
      "purl": "pkg:npm/express@4.19.2"
    }
  ]
}
```

### Looking up an PyPi package:

```json
{
  "components": [
    {
      "purl": "pkg:pypi/django@5.0.6"
    }
  ]
}
```

### Looking up a Maven package:

```json
{
  "components": [
    {
      "purl": "pkg:maven/log4j/log4j@1.2.17"
    }
  ]
}
```

### Batch lookup

```json
{
  "components": [
    {
      "purl": "pkg:npm/express@4.19.2"
    },
    {
      "purl": "pkg:pypi/django@5.0.6"
    },
    {
      "purl": "pkg:maven/log4j/log4j@1.2.17"
    }
  ]
}
```

This endpoint consumes 100 units of your quota.

This endpoint requires the following org token scopes:
- packages:list

## License Attribution

License attribution information for a resource at a given PURL can be requested by setting the query parameter `licenseattrib=true`. License attribution information is returned as a JSON object in the following format:

```
attribText: string
attribData: Array<{
    purl: string,
    foundInFilepath?: string
    spdxExpr: string,
    foundAuthors: Array<string>
}>
```

* The `attribText` attribute contains the contents of the license that was found, or the model text of the license if the license information was found via package metadata. For example, if an npm package contains a LICENSE file with slight modifications inserting the actual author names and copyright dates, the precise contents of that LICENSE file will occupy the `attribText` field, but if the license information concerns the presence of an SPDX identifier `MIT` in the package.json file, `attribText` will contain the base text of the MIT license.
* The `attribData` attribute is an array with one element for each occurrence of the license text in question. Because an identical license text may be used an arbitrary number of times in a large code base, this helps keep the size of responses manageable. The `purl` attribute corresponds to the `purl` of the resource in which this license information was found, while `foundInFilepath` contains the relative path to the location of the license information within the resource (package or artifact). `foundInFilepath` may be null if the license information was gleaned from resource metadata. `spdxExpr` contains an SPDX expression describing the license content. `foundAuthors` is an array of additional author information found which is relevant to that particular appearance/instance of the license. For example, if a python package has a pyproject.toml file which identifies the MIT license and contains an array of author names and email addresses, the array entry for that particular `attribData` will have a purl pointing to that package/artifact, a relative path to the pyproject.toml file, an SPDX expression identifying the MIT license, and an array containing the author information present in the pyproject.toml file.

## License Details

More fine-grained details concerning license identification can be requested by setting the query parameter `licensedetails=true`. License details are returned as a JSON object in the following format:

```
spdxDisj: string  
provenance: string  
filepath?: string  
match_strength: float
```

* The `spdxDisj` attribute contains an SPDX expression identifying the license match
* The `provenance` attribute contains information concerning the provenance of the license data (in a more detailed sense than just resource path, where did we find this license info?)
* The `filepath` attribute contains a relative path to the resource used to identify this license information if it exists (for license information taken from something like package metadata, there may not be an appropriate filepath)
* The `match_strength` property contains a value between 0 and 1 describing the strength of the license match (0 for no similarity, 1 for identical contents). For license data found by examining SPDX expressions, this property will be `1`.

# OpenAPI definition

````json
{
  "openapi": "3.0.0",
  "info": {
    "description": "Specification of the Socket API endpoints",
    "title": "API Endpoints",
    "version": "0"
  },
  "servers": [
    {
      "url": "https://api.socket.dev/v0"
    }
  ],
  "tags": [
    {
      "name": "packages"
    }
  ],
  "components": {
    "responses": {
      "SocketBadRequest": {
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "additionalProperties": true,
              "description": "",
              "properties": {
                "error": {
                  "type": "object",
                  "additionalProperties": true,
                  "description": "",
                  "properties": {
                    "message": {
                      "type": "string",
                      "description": "",
                      "default": ""
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "",
                      "default": null,
                      "nullable": true
                    }
                  },
                  "required": [
                    "details",
                    "message"
                  ]
                }
              },
              "required": [
                "error"
              ]
            }
          }
        },
        "description": "Bad request"
      },
      "SocketUnauthorized": {
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "additionalProperties": true,
              "description": "",
              "properties": {
                "error": {
                  "type": "object",
                  "additionalProperties": true,
                  "description": "",
                  "properties": {
                    "message": {
                      "type": "string",
                      "description": "",
                      "default": ""
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "",
                      "default": null,
                      "nullable": true
                    }
                  },
                  "required": [
                    "details",
                    "message"
                  ]
                }
              },
              "required": [
                "error"
              ]
            }
          }
        },
        "description": "Unauthorized"
      },
      "SocketForbidden": {
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "additionalProperties": true,
              "description": "",
              "properties": {
                "error": {
                  "type": "object",
                  "additionalProperties": true,
                  "description": "",
                  "properties": {
                    "message": {
                      "type": "string",
                      "description": "",
                      "default": ""
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "",
                      "default": null,
                      "nullable": true
                    }
                  },
                  "required": [
                    "details",
                    "message"
                  ]
                }
              },
              "required": [
                "error"
              ]
            }
          }
        },
        "description": "Insufficient max_quota for API method"
      },
      "SocketTooManyRequestsResponse": {
        "description": "Insufficient quota for API route",
        "headers": {
          "Retry-After": {
            "description": "Retry contacting the endpoint *at least* after seconds.\nSee https://tools.ietf.org/html/rfc7231#section-7.1.3",
            "schema": {
              "format": "int32",
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "additionalProperties": true,
              "description": "",
              "properties": {
                "error": {
                  "type": "object",
                  "additionalProperties": true,
                  "description": "",
                  "properties": {
                    "message": {
                      "type": "string",
                      "description": "",
                      "default": ""
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "",
                      "default": null,
                      "nullable": true
                    }
                  },
                  "required": [
                    "details",
                    "message"
                  ]
                }
              },
              "required": [
                "error"
              ]
            }
          }
        }
      },
      "SocketNotFoundResponse": {
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "additionalProperties": true,
              "description": "",
              "properties": {
                "error": {
                  "type": "object",
                  "additionalProperties": true,
                  "description": "",
                  "properties": {
                    "message": {
                      "type": "string",
                      "description": "",
                      "default": ""
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "",
                      "default": null,
                      "nullable": true
                    }
                  },
                  "required": [
                    "details",
                    "message"
                  ]
                }
              },
              "required": [
                "error"
              ]
            }
          }
        },
        "description": "Resource not found"
      }
    },
    "schemas": {
      "SocketManifestReference": {
        "type": "object",
        "additionalProperties": true,
        "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"
        ]
      },
      "SocketScore": {
        "type": "object",
        "additionalProperties": true,
        "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"
        ]
      },
      "SocketId": {
        "type": "string",
        "description": "",
        "default": ""
      },
      "BatchPurlStreamSchema": {
        "anyOf": [
          {
            "$ref": "#/components/schemas/SocketArtifact"
          },
          {
            "type": "object",
            "additionalProperties": true,
            "properties": {
              "_type": {
                "type": "string",
                "enum": [
                  "purlError"
                ]
              },
              "value": {
                "$ref": "#/components/schemas/PurlErrorSchema"
              }
            },
            "required": [
              "_type",
              "value"
            ]
          },
          {
            "type": "object",
            "additionalProperties": true,
            "properties": {
              "_type": {
                "type": "string",
                "enum": [
                  "summary"
                ]
              },
              "value": {
                "$ref": "#/components/schemas/PurlSummarySchema"
              }
            },
            "required": [
              "_type",
              "value"
            ]
          }
        ]
      },
      "SocketOrgBatchPURLFetch": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "components": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SocketBatchPURLRequest"
            },
            "description": ""
          }
        },
        "required": [
          "components"
        ]
      },
      "SocketArtifact": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SocketPURL"
          },
          {
            "$ref": "#/components/schemas/SocketArtifactLink"
          },
          {
            "type": "object",
            "additionalProperties": true,
            "properties": {
              "id": {
                "$ref": "#/components/schemas/SocketId"
              },
              "fileName": {
                "type": "string",
                "description": "Exact PyPI filename verified against the retained artifact catalog for an artifact_filename selector. Absent for unresolved selectors.",
                "default": ""
              },
              "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 or artifact was published, when known. Currently populated for PURL types: actions, cargo, composer, go, maven, npm, nuget, openvsx, pypi, and rubygems. Maven and PyPI can use artifact-grain dates when artifact qualifiers identify a concrete artifact; other listed ecosystems use package-version dates.",
                "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
              },
              "verdictRevision": {
                "type": "integer",
                "description": "Revision of the organization configuration this record was evaluated against. Equals the `X-Socket-Verdict-Revision` response header and is present only on organization-scoped routes. A cached verdict whose revision is lower than the latest one reported for the organization must be rechecked; an unchanged revision never extends how long a verdict may be reused.",
                "default": 0,
                "minimum": 0
              },
              "license": {
                "type": "string",
                "description": "",
                "default": ""
              },
              "licenseDetails": {
                "$ref": "#/components/schemas/LicenseDetails"
              },
              "licenseAttrib": {
                "$ref": "#/components/schemas/SAttrib1_N"
              }
            }
          }
        ]
      },
      "PurlErrorSchema": {
        "type": "object",
        "additionalProperties": true,
        "description": "",
        "properties": {
          "error": {
            "type": "string",
            "description": "",
            "default": ""
          },
          "inputPurl": {
            "type": "string",
            "description": "",
            "default": ""
          },
          "retryable": {
            "type": "boolean",
            "description": "True when the error is transient (timeout or shed resolution) and a retry can succeed. Absent or false means the error is an authoritative verdict for this input."
          }
        },
        "required": [
          "error",
          "inputPurl",
          "retryable"
        ]
      },
      "PurlSummarySchema": {
        "type": "object",
        "additionalProperties": true,
        "description": "",
        "properties": {
          "purl_input": {
            "type": "integer",
            "description": "",
            "default": 0
          },
          "resolved": {
            "type": "integer",
            "description": "",
            "default": 0
          },
          "errors": {
            "type": "object",
            "additionalProperties": true,
            "description": "",
            "properties": {
              "purl_malformed": {
                "type": "integer",
                "description": "",
                "default": 0
              },
              "purl_ecosystem_not_enabled": {
                "type": "integer",
                "description": "",
                "default": 0
              },
              "package_not_found": {
                "type": "integer",
                "description": "",
                "default": 0
              }
            },
            "required": [
              "package_not_found",
              "purl_ecosystem_not_enabled",
              "purl_malformed"
            ]
          }
        },
        "required": [
          "errors",
          "purl_input",
          "resolved"
        ]
      },
      "SocketBatchPURLRequest": {
        "type": "object",
        "additionalProperties": false,
        "description": "",
        "properties": {
          "purl": {
            "type": "string",
            "description": "",
            "default": ""
          }
        },
        "required": [
          "purl"
        ]
      },
      "SocketPURL": {
        "type": "object",
        "additionalProperties": true,
        "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"
        ]
      },
      "SocketArtifactLink": {
        "type": "object",
        "additionalProperties": true,
        "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": true,
              "properties": {
                "result": {
                  "type": "integer",
                  "description": "Computed priority score for this alert",
                  "default": 0
                },
                "components": {
                  "type": "object",
                  "additionalProperties": true,
                  "description": "",
                  "properties": {
                    "isFixable": {
                      "type": "object",
                      "additionalProperties": true,
                      "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": true,
                      "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": true,
                      "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": true,
                "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": true,
                "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": ""
      },
      "LicenseDetails": {
        "type": "array",
        "items": {
          "type": "object",
          "additionalProperties": true,
          "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": ""
      },
      "SAttrib1_N": {
        "type": "array",
        "items": {
          "type": "object",
          "additionalProperties": true,
          "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": true,
                "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": true,
        "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",
            "additionalProperties": true,
            "description": "Additional alert-specific properties and metadata that vary by alert type. For vulnerability alerts this includes the `cveId` and `ghsaId` identifiers, either of which may be an empty string when GitHub has not assigned that identifier to the advisory.",
            "default": null
          },
          "action": {
            "type": "string",
            "description": "Action to take for this alert (e.g., error, warn, ignore)",
            "default": ""
          },
          "actionSource": {
            "type": "object",
            "additionalProperties": true,
            "description": "",
            "properties": {
              "type": {
                "type": "string",
                "description": "Type of action source (e.g., policy, override)",
                "default": ""
              },
              "candidates": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true,
                  "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": ""
                    },
                    "policyId": {
                      "type": "string",
                      "description": "ID of the alert policy whose rule matched. Absent when not applicable (alert-policy candidates only)",
                      "default": ""
                    },
                    "policyName": {
                      "type": "string",
                      "description": "Display name of the matched alert policy at evaluation time; null for the default policy. Absent when not applicable (alert-policy candidates only)",
                      "default": "",
                      "nullable": true
                    },
                    "ruleId": {
                      "type": "string",
                      "description": "ID of the matched alert policy rule: the rule uuid for custom rules, the issue name for baseline rules. Absent when not applicable (alert-policy candidates only)",
                      "default": ""
                    },
                    "ruleName": {
                      "type": "string",
                      "description": "Name of the matched alert policy rule at evaluation time. Absent when not applicable (alert-policy candidates only)",
                      "default": ""
                    },
                    "ruleIndex": {
                      "type": "integer",
                      "description": "0-based position of the matched rule in first-match-wins evaluation order. Absent when not applicable (alert-policy candidates only)",
                      "default": 0,
                      "minimum": 0
                    },
                    "isBaseline": {
                      "type": "boolean",
                      "default": false,
                      "description": "Whether the matched alert policy rule is a baseline rule. Absent when not applicable (alert-policy candidates only)"
                    }
                  },
                  "required": [
                    "action",
                    "actionPolicyIndex",
                    "repoLabelId",
                    "type"
                  ]
                },
                "description": ""
              }
            },
            "required": [
              "candidates",
              "type"
            ]
          },
          "alertPolicyRule": {
            "$ref": "#/components/schemas/SocketAlertPolicyRule"
          },
          "actionPolicyIndex": {
            "type": "integer",
            "description": "Index of the policy rule that triggered this action, for traceability to security policies",
            "default": 0
          },
          "fix": {
            "type": "object",
            "additionalProperties": true,
            "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": true,
                  "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": true,
            "properties": {
              "head": {
                "$ref": "#/components/schemas/ReachabilityResult"
              },
              "base": {
                "$ref": "#/components/schemas/ReachabilityResult"
              }
            },
            "description": ""
          },
          "subType": {
            "type": "string",
            "description": "Generic alert sub-type",
            "default": ""
          }
        },
        "required": [
          "key",
          "type"
        ]
      },
      "SocketArtifactPatch": {
        "type": "object",
        "additionalProperties": true,
        "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": ""
      },
      "SocketPURL_Type": {
        "type": "string",
        "enum": [
          "alpm",
          "apk",
          "bitbucket",
          "cocoapods",
          "cargo",
          "chrome",
          "clawhub",
          "composer",
          "conan",
          "conda",
          "cran",
          "deb",
          "docker",
          "firefox-extension",
          "edge-extension",
          "gem",
          "generic",
          "github",
          "golang",
          "hackage",
          "hex",
          "huggingface",
          "maven",
          "mlflow",
          "npm",
          "nuget",
          "qpkg",
          "oci",
          "pub",
          "pypi",
          "rpm",
          "socket",
          "swid",
          "swift",
          "vscode",
          "vscode-extension",
          "unknown"
        ],
        "description": "Package ecosystem type identifier based on the PURL specification",
        "default": "unknown"
      },
      "SocketIssueSeverity": {
        "type": "string",
        "enum": [
          "low",
          "middle",
          "high",
          "critical"
        ],
        "description": "",
        "default": "low"
      },
      "SocketCategory": {
        "type": "string",
        "enum": [
          "supplyChainRisk",
          "quality",
          "maintenance",
          "vulnerability",
          "license",
          "other"
        ],
        "description": "",
        "default": "other"
      },
      "SocketAlertPolicyRule": {
        "type": "object",
        "additionalProperties": true,
        "description": "The alert policy rule that decided `action`. Included in both normal and `compact=true` responses whenever an alert policy rule decided the action; absent when the action came from any other source. Unrelated to `actionPolicyIndex`, which indexes the legacy security policy",
        "properties": {
          "policyId": {
            "type": "string",
            "description": "ID of the alert policy whose rule decided this action: a UUID, or `default` for the default policy until it is first customized",
            "default": ""
          },
          "policyName": {
            "type": "string",
            "description": "Display name of that policy at evaluation time; null for the default policy",
            "default": "",
            "nullable": true
          },
          "ruleId": {
            "type": "string",
            "description": "ID of the rule that decided this action: the rule UUID for custom rules, the alert type name for baseline rules",
            "default": ""
          },
          "ruleName": {
            "type": "string",
            "description": "Name of that rule at evaluation time; baseline rules use the alert type name",
            "default": ""
          },
          "ruleIndex": {
            "type": "integer",
            "description": "0-based position of the rule in first-match-wins evaluation order (custom rules first, then baseline)",
            "default": 0,
            "minimum": 0
          },
          "isBaseline": {
            "type": "boolean",
            "default": false,
            "description": "Whether the rule is a baseline rule rather than a custom rule"
          }
        },
        "required": [
          "isBaseline",
          "policyId",
          "policyName",
          "ruleId",
          "ruleIndex",
          "ruleName"
        ]
      },
      "SocketPatch": {
        "type": "object",
        "additionalProperties": true,
        "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"
        ]
      },
      "ReachabilityResult": {
        "type": "object",
        "additionalProperties": true,
        "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"
        ]
      },
      "ReachabilityResultItem": {
        "type": "object",
        "additionalProperties": true,
        "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": true,
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "function-level"
                    ]
                  },
                  "value": {
                    "type": "array",
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CallStackItem"
                      },
                      "description": ""
                    },
                    "description": ""
                  }
                }
              },
              {
                "type": "object",
                "additionalProperties": true,
                "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": ""
          },
          "subprojectId": {
            "type": "string",
            "description": "Identifier of the analysed subproject. Differs from subprojectPath when several independent builds share a directory",
            "default": ""
          },
          "workspaceId": {
            "type": "string",
            "description": "Identifier of the analysed workspace within the subproject. Differs from workspacePath when several independent builds share a directory",
            "default": ""
          },
          "viaPrivateDependency": {
            "type": "boolean",
            "default": false,
            "description": "For direct_dependency results: the direct importer is a private/unresolvable package in the project rather than the application manifest"
          }
        },
        "required": [
          "type"
        ]
      },
      "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"
      },
      "CallStackItem": {
        "type": "object",
        "additionalProperties": true,
        "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": ""
      },
      "ClassStackItem": {
        "type": "object",
        "additionalProperties": true,
        "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": ""
      },
      "SourceLocation": {
        "type": "object",
        "additionalProperties": true,
        "description": "",
        "properties": {
          "start": {
            "type": "object",
            "additionalProperties": true,
            "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": true,
            "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"
        ]
      }
    },
    "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"
      }
    }
  },
  "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**Conda (temporary compatibility):** `pkg:conda` inputs are served from the\nalready-scanned PyPI package with the same normalized name and version when\none exists; the response row keeps the original conda PURL in `inputPurl`\nbut reports `type: pypi`. Conda `build`, `subdir`, `type`, and `channel`\nqualifiers are ignored, and conda packages without a scanned PyPI\ncounterpart return the normal `notFound` result. This mapping will be\nreplaced by native conda support.\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": {}
      }
    }
  }
}
````