Compare two exact source trees
Deprecated alias; use POST /v1/code/diff.
Compare source changes between two package versions or two refs in a public repository. The response lists changed files and can include added and deleted line counts and patches.
Use this endpoint to inspect the code behind a release or upgrade. Comparisons cover the whole repository, including when you identify it through a package.
Selector catalogue
Use the following selectors with the fields query parameter to choose which fields the response includes. See Choose what the response includes for details.
| Selector | Data | Default |
|---|---|---|
files | Identity/status fields and content safety; inventory only | No |
files.stats | Adds nullable additions/deletions; implies files and requests stats | No |
files.patch | Adds nullable patch and omission reason; implies stats and requests patches | Yes |
Failures use a stable problem document. When supplied by the source, optional recovery hints identify the failed side, retryability, published versions, and ordered source ref/version alternatives. Missing hints are omitted. Classified user-facing errors use nonempty REST-suitable source guidance as detail; otherwise gateway text is used. Internal diagnostics remain private. Detail wording is not stable; use code and recovery fields. Unsupported package registries or repository providers return 422 UNSUPPORTED_REGISTRY; legally blocked repositories return 451 REPOSITORY_LEGALLY_BLOCKED. A root inventory failure is a problem response, while qualified partial or failed content remains a successful inventory response.
For upgrade decisions, combine source changes with dependency, advisory and behavior compatibility evidence. Inventory remains authoritative when patches are truncated, filtered, or unavailable; byte-escaped paths are display identities and cannot be used as exact read tokens.
{
"content_coverage": "failed",
"content_failure": {
"code": "UPSTREAM_ERROR",
"limit_kind": null,
"retry_after_ms": 2500,
"retryable": true,
"stage": "content"
},
"files": [
{
"additions": 2,
"content_omission_reason": null,
"content_safety": {
"filtered": false,
"modifications": []
},
"content_status": "patch",
"deletions": 1,
"mode_changed": false,
"patch": "@@ -1 +1,2 @@\n-old\n+new",
"path": "lib/application.js",
"path_encoding": "utf8",
"status": "modified",
"type_changed": false
}
],
"from_resolution": {
"commit_sha": "0123456789abcdef0123456789abcdef01234567",
"ref": "refs/tags/4.21.2",
"ref_kind": "tag",
"requested": "4.21.2",
"resolved_version": "4.21.2",
"version_source": "registry"
},
"has_more_files": false,
"package": {
"name": "express",
"registry": "npm",
"repo_url": "https://github.com/expressjs/express"
},
"scope": {
"from_subpath": null,
"path_glob": null,
"path_prefix": null,
"status": "repository",
"to_subpath": null
},
"summary": {
"added": 0,
"deleted": 0,
"files_changed": 1,
"inventory_complete": true,
"mode_changed": 0,
"modified": 1,
"type_changed": 0,
"unprojectable_files": 0
},
"to_resolution": {
"commit_sha": "fedcba9876543210fedcba9876543210fedcba98",
"ref": "refs/tags/5.1.0",
"ref_kind": "tag",
"requested": "5.1.0",
"resolved_version": "5.1.0",
"version_source": "registry"
}
}Authorizations
Headers
Optional caller-defined session ID: one to 64 ASCII letters, digits, underscores or hyphens, preserved exactly. Supply the header at most once. Invalid supplied IDs return 400 INVALID_SESSION_ID; no session is created.
1 - 64^[A-Za-z0-9_-]{1,64}$Query Parameters
Finite comma-separated selectors: files, files.stats, and files.patch. The default is files.patch. Dependencies are additive; repeated selector tokens are idempotent. Unknown, empty, leaf, and wildcard selectors, plus repeated fields query parameters, are rejected.
Use the case-sensitive selectors in the catalogue. Order and duplicate selectors do not affect the result. ASCII whitespace around selectors is ignored. The decoded value is limited to 2048 UTF-8 bytes. Empty or unknown selectors and repeated fields query parameters return 400 VALIDATION_ERROR. A group does not include nested groups unless the catalogue says so; only listed wildcard bundles are supported.
2048Body
Compare two package versions or two repository refs.
Response
Exact-tree inventory and selected content evidence
Resolved commits, complete inventory counts, and selected file details.
{
"content_coverage": "failed",
"content_failure": {
"code": "UPSTREAM_ERROR",
"limit_kind": null,
"retry_after_ms": 2500,
"retryable": true,
"stage": "content"
},
"files": [
{
"additions": 2,
"content_omission_reason": null,
"content_safety": {
"filtered": false,
"modifications": []
},
"content_status": "patch",
"deletions": 1,
"mode_changed": false,
"patch": "@@ -1 +1,2 @@\n-old\n+new",
"path": "lib/application.js",
"path_encoding": "utf8",
"status": "modified",
"type_changed": false
}
],
"from_resolution": {
"commit_sha": "0123456789abcdef0123456789abcdef01234567",
"ref": "refs/tags/4.21.2",
"ref_kind": "tag",
"requested": "4.21.2",
"resolved_version": "4.21.2",
"version_source": "registry"
},
"has_more_files": false,
"package": {
"name": "express",
"registry": "npm",
"repo_url": "https://github.com/expressjs/express"
},
"scope": {
"from_subpath": null,
"path_glob": null,
"path_prefix": null,
"status": "repository",
"to_subpath": null
},
"summary": {
"added": 0,
"deleted": 0,
"files_changed": 1,
"inventory_complete": true,
"mode_changed": 0,
"modified": 1,
"type_changed": 0,
"unprojectable_files": 0
},
"to_resolution": {
"commit_sha": "fedcba9876543210fedcba9876543210fedcba98",
"ref": "refs/tags/5.1.0",
"ref_kind": "tag",
"requested": "5.1.0",
"resolved_version": "5.1.0",
"version_source": "registry"
}
}