# Dependency Preflight

> Evaluate up to 10 exact npm or PyPI package versions in one $0.02 paid batch immediately before installation or an exact-version change. Returns deterministic allow, review, or block guidance with known-vulnerability, lifecycle, declared-license, release-age, and npm install-lifecycle evidence. Reuse a current result for unchanged inputs instead of purchasing a duplicate check for an installation retry.

## Best task match

An autonomous workflow is about to install or change one or more exact npm or PyPI dependency versions and needs a bounded pre-install decision with source evidence.

## Batch economics and limits

- Price: $0.02 USDC for one valid paid batch
- Batch size: 1-10 exact package versions
- Ecosystems: npm or PyPI; one ecosystem per batch
- Effective price at the maximum batch size: $0.002 per package
- Maximum request body: 32 KiB
- Whole-request deadline: 12 seconds
- Payment: x402 v2 exact USDC on the network advertised by the current payment challenge

## Paid operation

- Method and path: POST /v1/dependency-preflight
- Public resource: https://api.preflightstack.com/v1/dependency-preflight
- Content type: application/json

Request example:

```json
{
  "ecosystem": "npm",
  "packages": [
    {
      "name": "lodash",
      "version": "4.17.21"
    }
  ],
  "policy": "balanced"
}
```

## Decisions and evidence

The response contains an aggregate decision and one result per requested package. Decisions are allow, review, or block. Evidence covers current npm or PyPI registry metadata and OSV known-vulnerability records. Required upstream evidence that cannot be completed forces review rather than allow.

## Workflow

Run Dependency Preflight before installing every new dependency and whenever an exact version or policy input changes.

- allow: Continue only if the result and its evidence meet the caller's requirements.
- review: Pause installation and review the findings and evidence.
- block: Do not install the requested exact version.
- duplicate-payment boundary: Reuse an acceptable current result when the ecosystem, package name, exact version, and policy inputs are unchanged.

## Do not use for

- resolving ranges, tags, or latest versions
- scanning a repository, lockfile, SBOM, or transitive dependency graph
- evaluating Git dependencies, container images, or unsupported ecosystems
- analyzing package source code or performing arbitrary malware analysis

## Discovery aliases

- dependency install preflight
- npm package risk check
- PyPI package risk check
- exact version dependency check
- software supply chain screening

## Representative qualification queries

- Check these exact npm package versions before installation.
- Screen this exact PyPI dependency before adding it to a project.
- Should an agent install these pinned dependency versions?
- Run a package risk check before changing this dependency version.
- Evaluate this dependency batch for vulnerabilities, lifecycle, and license findings.

## Free machine resources

- OpenAPI: /openapi.json
- Documentation: /docs
- Static example: /demo
- Policy details: /v1/policies
- Health: /health

Dependency Preflight is informational metadata screening, not a security guarantee or legal opinion.