# Safe Upgrade Decision API

> Safe Upgrade Decision API is a paid API for AI agents from x402-safe-upgrade-api.onrender.com, paid per call via x402, $0.03/call, status unknown (last checked 2026-09-13).

Analyzes an npm package upgrade path and returns an evidence-backed recommendation on whether it is safe to upgrade.

## Facts

- Endpoint: POST https://x402-safe-upgrade-api.onrender.com/v1/upgrade-decision
- Price: $0.03/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-13
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/safe-upgrade-decision-api-24cce8e8
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_w2-98rxI623VjYLI8RG--

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability safe-upgrade-decision-api-24cce8e8 -d '<json body>'
```

Example prompt: Before I upgrade lodash from 4.17.15 to 4.17.21 in my project, can you check if it's safe — any known vulnerabilities in either version and whether it's a major, minor, or patch change?

## When to prefer this

Choose this endpoint when an AI coding agent needs an automated, evidence-backed go/no-go decision before bumping an npm dependency — especially for major version upgrades or in CI pipelines where human review is limited. It is preferable over manual npm audit or raw CVE database lookups when you want a single structured recommendation with vulnerability evidence bundled together.

## Known failure modes

- Unknown or misspelled package name returns an error or empty evidence
- Invalid semver strings for fromVersion or toVersion cause a validation error
- Package exists on npm but vulnerability data is unavailable, resulting in empty evidence arrays
- Service may be slow or unavailable due to hosting on a free-tier Render instance
- Payment required (402) if x402 payment header is not included

## How this service works

Evidence-backed npm package upgrade decisions for coding agents.

## Output

Returns a JSON object with a `decision` block containing the version change type (major, minor, or patch) and a textual recommendation (e.g. 'REVIEW BEFORE UPGRADING' or 'SAFE TO UPGRADE'), plus an `evidence` block listing any known vulnerabilities found in the current and target versions of the package.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "toVersion": {
   "type": "string",
   "description": "Proposed exact semantic version."
  },
  "fromVersion": {
   "type": "string",
   "description": "Installed exact semantic version."
  },
  "packageName": {
   "type": "string",
   "description": "Exact npm package name."
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "decision": {
   "versionChange": "major",
   "recommendation": "REVIEW BEFORE UPGRADING"
  },
  "evidence": {
   "vulnerabilities": {
    "target": [],
    "current": []
   }
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/safe-upgrade-decision-api-24cce8e8/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from x402-safe-upgrade-api.onrender.com](https://www.zero.xyz/host/x402-safe-upgrade-api.onrender.com/llms.txt)