{"openapi":"3.1.0","info":{"title":"UpgradeLens","version":"0.1.0","description":"Evidence-backed dependency upgrade intelligence for AI coding agents. One call answers: should this dependency move from version A to version B, and what must be handled? Deterministic, source-cited, no hallucinated migration facts. Free evaluation quota. Remote MCP endpoint at /mcp.","contact":{"url":"https://github.com/mattpicone/upgradelens"}},"servers":[{"url":"https://upgradelens.mattpicone.workers.dev"}],"paths":{"/v1/upgrade/check":{"post":{"operationId":"checkDependencyUpgrade","summary":"Decide whether a dependency can move from current_version to target_version (security, compatibility, EOL, breaking-change evidence).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ecosystem","package","current_version","target_version"],"properties":{"ecosystem":{"type":"string","enum":["npm","pypi"]},"package":{"type":"string","maxLength":214},"current_version":{"type":"string","maxLength":64},"target_version":{"type":"string","maxLength":64},"runtime":{"type":"object","properties":{"node":{"type":"string","description":"Node.js version in use, e.g. 20.11.0"},"python":{"type":"string","description":"Python version in use, e.g. 3.12"}}}}}}}},"responses":{"200":{"description":"Upgrade decision","content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","enum":["proceed","review_required","block","unknown"]},"risk_score":{"type":"integer","minimum":0,"maximum":100},"ecosystem":{"type":"string"},"package":{"type":"string"},"current_version":{"type":"string"},"target_version":{"type":"string"},"latest_stable":{"type":["string","null"]},"repository_url":{"type":["string","null"]},"version_facts":{"type":"object"},"security_delta":{"type":"object"},"compatibility":{"type":"object"},"breaking_changes":{"type":"array","items":{"type":"object"}},"reasons":{"type":"array","items":{"type":"string"}},"evidence":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"source_type":{"type":"string"},"source_url":{"type":"string"},"fact":{"type":"string"},"confidence":{"type":"number"},"fetched_at":{"type":"string","format":"date-time"}}}},"confidence":{"type":"number"},"freshness":{"type":"string","format":"date-time"},"analysis_version":{"type":"string"},"cache_hit":{"type":"boolean"}}}}}},"400":{"description":"Invalid request"},"429":{"description":"Rate limited"}}}},"/v1/upgrade/plan":{"post":{"operationId":"planDependencyUpgrade","summary":"Check plus ordered, source-cited migration actions and changelog URLs.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ecosystem","package","current_version","target_version"],"properties":{"ecosystem":{"type":"string","enum":["npm","pypi"]},"package":{"type":"string","maxLength":214},"current_version":{"type":"string","maxLength":64},"target_version":{"type":"string","maxLength":64},"runtime":{"type":"object","properties":{"node":{"type":"string","description":"Node.js version in use, e.g. 20.11.0"},"python":{"type":"string","description":"Python version in use, e.g. 3.12"}}}}}}}},"responses":{"200":{"description":"Upgrade plan with migration_actions[] and changelog_urls[]"}}}},"/v1/upgrade/target":{"post":{"operationId":"findSafeUpgradeTarget","summary":"Rank candidate target versions when the target is not yet known.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ecosystem","package","current_version"],"properties":{"ecosystem":{"type":"string","enum":["npm","pypi"]},"package":{"type":"string"},"current_version":{"type":"string"},"max_major_jump":{"type":"integer","minimum":0},"allow_prerelease":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Ranked candidates with per-candidate rationale"}}}},"/v1/upgrade/batch":{"post":{"operationId":"batchCheckUpgrades","summary":"Check up to 8 version pairs in one request.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["pairs"],"properties":{"pairs":{"type":"array","maxItems":8,"items":{"type":"object","required":["ecosystem","package","current_version","target_version"],"properties":{"ecosystem":{"type":"string","enum":["npm","pypi"]},"package":{"type":"string","maxLength":214},"current_version":{"type":"string","maxLength":64},"target_version":{"type":"string","maxLength":64},"runtime":{"type":"object","properties":{"node":{"type":"string","description":"Node.js version in use, e.g. 20.11.0"},"python":{"type":"string","description":"Python version in use, e.g. 3.12"}}}}}}}}}}},"responses":{"200":{"description":"Summary plus per-pair results"}}}},"/v1/package/{ecosystem}/{name}":{"get":{"operationId":"getPackageSnapshot","summary":"Current package snapshot: latest stable, recent versions, advisories, EOL.","parameters":[{"name":"ecosystem","in":"path","required":true,"schema":{"type":"string","enum":["npm","pypi"]}},{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Package snapshot"},"404":{"description":"Unknown package"}}}},"/v1/evidence/{id}":{"get":{"operationId":"getEvidence","summary":"Resolve an evidence ID to its provenance record.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Evidence record"},"404":{"description":"Not found"}}}},"/v1/keys":{"post":{"operationId":"createApiKey","summary":"Instantly create a free API key (higher rate limits than anonymous).","responses":{"201":{"description":"New API key"}}}},"/healthz":{"get":{"operationId":"health","summary":"Service health, version and source freshness.","responses":{"200":{"description":"Health status"}}}}}}