# npm Breaking Changes & Migration

> npm Breaking Changes & Migration is a paid API for AI agents from upgrade-brief.shopttyass-85f.workers.dev, paid per call via x402, $0.005/call, status unknown (last checked 2026-10-28).

Returns documented breaking changes, manifest diffs, and migration guides for an npm package upgrade between two versions

## Facts

- Endpoint: GET https://upgrade-brief.shopttyass-85f.workers.dev/breaking?utm_source=zero.xyz
- Price: $0.005/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-28
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/npm-breaking-changes-migration-8ee176a3
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_85SO1QrFKKloqQ_xbTJL7

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 npm-breaking-changes-migration-8ee176a3
```

Example prompt: Before I upgrade express from 4.21.0 to 5.0.0, can you pull the breaking changes, any ESM or engine requirement shifts, and migration guide links so I know what to fix?

## When to prefer this

Use this endpoint when you need a structured, per-version breakdown of breaking changes with source attribution for a specific npm package upgrade. It is superior to manual changelog reading because it aggregates npm registry, deps.dev, jsDelivr, and GitHub sources in one call, and returns a machine-readable verdict. Prefer it over the batch 'Dependency Upgrade Plan' endpoint when you need full detail for a single dependency rather than a high-level plan across multiple packages.

## Known failure modes

- Package not found on npm registry — returns error or empty result
- Version range invalid or from > to — returns error
- No changelog or release notes available — verdict set to UNKNOWN_INCOMPLETE_NOTES with partial coverage
- Rate limiting or upstream source unavailability causes degraded mode with incomplete notes
- Prerelease versions excluded by default unless prereleases=true is set

## How this service works

npm breaking changes between two versions of a package, before a package upgrade: the documented breaking changes per version, read from the real CHANGELOG, GitHub release notes and alpha/beta/rc notes, plus major version bumps, Node.js engine, ESM/CJS, exports and peer dependency changes, migration guide links and a verdict. Exact versions or a major ('4'); a source URL for every item. One call per dependency upgrade.

## Output

A JSON object containing: a verdict enum (BREAKING_CHANGES_LIKELY, REVIEW_MANIFEST_CHANGES, NO_BREAKING_CHANGES_DOCUMENTED, UNKNOWN_INCOMPLETE_NOTES), a human-readable summary, an array of breaking change items per version (each with source URL, bump type, and publish date), manifest changes (engines, module type, added/removed dependencies, peer dependency changes), major version bumps, migration guide URLs, version coverage stats, and the latest stable version.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "required": [
      "package",
      "from"
     ],
     "properties": {
      "to": {
       "type": "string",
       "default": "latest",
       "description": "Target version: exact, or a major/minor prefix ('5', '5.1') resolved to the first stable release of that series (5.0.0). Default: the latest stable release ('latest')"
      },
      "from": {
       "type": "string",
       "description": "Version you are on now: exact ('4.21.0'), or a major/minor prefix ('4', '4.21') resolved to its newest stable release"
      },
      "package": {
       "type": "string",
       "description": "npm package name, e.g. 'express', 'next' or '@types/node'"
      },
      "prereleases": {
       "enum": [
        "true",
        "false"
       ],
       "type": "string",
       "default": "false",
       "description": "Include alpha/beta/rc/canary versions in the range"
      }
     },
     "additionalProperties": false
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object",
     "required": [
      "package",
      "from",
      "to",
      "verdict",
      "summary",
      "breaking"
     ],
     "properties": {
      "to": {
       "type": "string"
      },
      "asOf": {
       "type": "string"
      },
      "from": {
       "type": "string"
      },
      "notes": {
       "type": "array",
       "items": {
        "type": "string"
       }
      },
      "latest": {
       "type": [
        "string",
        "null"
       ],
       "description": "Latest stable version"
      },
      "package": {
       "type": "string"
      },
      "sources": {
       "type": "array",
       "items": {
        "type": "string"
       }
      },
      "summary": {
       "type": "string"
      },
      "verdict": {
       "enum": [
        "BREAKING_CHANGES_LIKELY",
        "REVIEW_MANIFEST_CHANGES",
        "NO_BREAKING_CHANGES_DOCUMENTED",
        "UNKNOWN_INCOMPLETE_NOTES"
       ],
       
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "to": "5.0.0",
  "asOf": "2026-10-22T12:00:00.000Z",
  "from": "4.21.0",
  "notes": [],
  "latest": "5.3.0",
  "package": "express",
  "sources": [
   "https://deps.dev (versions, dates)",
   "https://registry.npmjs.org/express (manifests)",
   "https://cdn.jsdelivr.net/npm/express@5.0.0/History.md"
  ],
  "summary": "express 4.21.0 -> 5.0.0: 7 versions, 1 major bump(s) (5.0.0), 7 documented breaking item(s) in 2 version(s); release notes found for 6/7 versions. Manifest: Node.js engine requirement changed: >= 0.10.0 -> >= 18.",
  "verdict": "BREAKING_CHANGES_LIKELY",
  "breaking": [
   {
    "bump": "major",
    "items": [
     "`res.status()` accepts only integers, and input must be greater than 99 and less than 1000",
     "`res.redirect('back')` and `res.location('back')` is no longer a supported magic string, explicitly use `req.get('Referrer') || '/'`."
    ],
    "source": "https://cdn.jsdelivr.net/npm/express@5.0.0/History.md",
    "version": "5.0.0",
    "publishedAt": "2024-09-10T03:37:48Z"
   }
  ],
  "coverage": {
   "versionsWithNotes": 6,
   "versionsWithoutNotes": [
    "4.22.1"
   ]
  },
  "degraded": false,
  "majorBumps": [
   "5.0.0"
  ],
  "repository": "https://github.com/expressjs/express",
  "attribution": "Compiled from public sources (npm registry, deps.dev, jsDelivr, GitHub).",
  "toPublishedAt": "2024-09-10T03:37:48Z",
  "fromPublishedAt": "2024-09-11T19:49:43Z",
  "manifestChanges": {
   "flags": [
    "Node.js engine requirement changed: >= 0.10.0 -> >= 18"
   ],
   "engines": {
    "node": {
     "to": ">= 18",
     "from": ">= 0.10.0"
    }
   },
   "moduleType": {
    "to": "commonjs",
    "from": "commonjs"
   },
   "dependencies": {
    "added": [
     "router",
     "once"
    ],
    "removed": [
     "array-flatten"
    ],
    "changedCount": 18
   },
   "peerDependencies": {
    "added": {},
    "changed": {},
    "removed": {}
   }
  },
  "migrationGuides": [
   "https://expressjs.com/en/guide/migrating-5.html"
  ],
  "versionsInRange": 7,
  "includesPrereleases": false
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/npm-breaking-changes-migration-8ee176a3/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from upgrade-brief.shopttyass-85f.workers.dev](https://www.zero.xyz/host/upgrade-brief.shopttyass-85f.workers.dev/llms.txt)