> ## Documentation Index > Fetch the complete documentation index at: https://docs.githits.com/llms.txt > Use this file to discover all available pages before exploring further. # Compare two exact source trees > 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](https://docs.githits.com/api/requests-and-responses#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; source messages and diagnostics are never returned. 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. ## OpenAPI ````yaml https://api.githits.dev/v1/openapi.json post /v1/code/diff openapi: 3.1.0 info: description: >- Explore package metadata, security advisories, dependencies, documentation and source code with the GitHits API. ## Choose an operation | Task | Operations | | --- | --- | | Inspect a package | Release metadata, vulnerabilities and dependencies | | Review releases or upgrades | Changelog and batch upgrade reviews | | Read documentation or source code | Browse with list, then follow an exact action through the unified read operation | | Browse known content | List source files, local documentation, or an explicit hosted site | | Find exact text | Grep across ordered packages, repositories and hosted sites, then follow exact read actions | | Compare source trees | Compare files, line statistics and patches between package versions or repository refs | | Discover relevant content | Search across packages, repositories and documentation sites; retrieve a search's status and retained results | | Resolve a target name | Find ranked package, repository and documentation-site targets | | Research a cited question | Generate an answer grounded in a package, repository or documentation site, or continue a conversation | | Generate an example | Generate and save a code example, then submit feedback | | Generate an SBOM | Upload manifests and lockfiles to receive a CycloneDX, SPDX or text inventory | | Find a language identifier | Search supported programming languages | ## Authenticate and send requests The production API origin is `https://api.githits.dev`; development uses `https://api-dev.githits.dev`. Examples target production. Replace `` with your GitHits token. Send the token in `Authorization: Bearer `. JSON request bodies use `Content-Type: application/json`; public JSON field names use `snake_case`. Standard SBOM documents retain their format's field names. Percent-encode path parameters such as package names as one path segment, including any embedded slash. The unified read target is a query value: encode a literal plus sign as `%2B` and a literal fragment marker as `%23`; ordinary form decoding interprets `+` as a space. Each operation documents its accepted parameters and encoding rules. ## Select the data you need Where supported, `fields` is a comma-separated **query parameter**, including on POST requests. Omit it to use the operation's defaults. Supplying it replaces those defaults; required identity and information needed to interpret the result remain present. A **selector** names a supported **group** of response fields. Groups are atomic: their members are selected together. A **wildcard bundle**, such as `vulnerabilities.*`, selects only the groups listed for that bundle. A bare group does not automatically include nested groups. Arbitrary subfields and undeclared wildcards are not supported. Each operation lists its selectors, defaults, dependencies and the data they return. Selection can reduce transferred data without reducing the work needed to produce it; consult its parameter and response field documentation. Small fixed responses do not offer `fields`. ## Interpret responses and errors An omitted optional field can mean unselected or unavailable data, according to the operation's contract. Null has an operation-specific meaning: it can mark unavailable or inapplicable data, or an unselected search result. Empty arrays, zero and false are values, not substitutes for unavailable data. Always retain the result's completeness and freshness information when displaying or processing it. **Requested** identity records caller intent; **resolved** identity records what that intent resolved to; **served** identity identifies the artifact that produced the response. These can differ while indexing or refresh work continues. Use served identity when an exact follow-up read is required, preserving package-relative or repository-relative path scope. Errors normally use `application/problem+json`. Branch on the stable `code`, not the human-readable `detail`. Include `X-Request-ID` when reporting a problem; error `instance` matches that ID. Respect `Retry-After` when present. If request identity cannot be created, the response is an empty HTTP 500 without a request ID. Responses use `Cache-Control: no-store`. Timeouts do not guarantee that work stopped. Read the documented timeout responses, especially for Research, generated examples and append-only feedback. Optional `X-GitHits-*` request headers attribute client, agent and session usage. The OpenAPI extension `x-githits-cost` is provisional operation metadata, not a price or a measure of computation. ## Contract status This API is pre-production. The external v1 contract is not yet frozen. license: name: Proprietary title: GitHits Public API version: 0.1.0 servers: - description: Production url: https://api.githits.dev security: [] tags: - description: >- Find exact text across ordered source and hosted-documentation scopes, check coverage, and follow exact reads. name: Grep - description: >- Browse package, repository or hosted-site paths and follow exact read and browse actions. name: List - description: >- Package metadata, release history, vulnerabilities, dependency graphs and upgrade comparisons. Each operation documents its registry, version and evidence scope. name: Packages - description: >- Read an exact documentation page or source file and retain the page, package-version or repository-commit details needed to cite it. name: Read - description: >- Discover evidence across package, repository and documentation-site targets, then retrieve retained search results and progress. name: Search - description: >- Find supported programming-language names and aliases for example requests. name: Languages - description: >- Generate code examples for programming tasks, with source references and license attribution. name: Examples - description: Rate generated examples or sessions and provide written feedback. name: Feedback - description: Stable exact-tree source comparison. name: Code Diff - description: >- Preview target resolution, cited questions and SBOM generation, plus the deprecated source comparison alias. Use /v1/code/diff for stable source comparison. name: Experimental paths: /v1/code/diff: post: tags: - Code Diff summary: Compare two exact source trees description: > 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](https://docs.githits.com/api/requests-and-responses#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; source messages and diagnostics are never returned. 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. operationId: compare_source_trees parameters: - description: >- 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. in: query name: fields required: false schema: default: files.patch maxLength: 2048 type: string - description: Optional trimmed printable ASCII client name, maximum 80 bytes. in: header name: X-GitHits-Client-Name required: false schema: type: string - description: Optional trimmed printable ASCII client version, maximum 80 bytes. in: header name: X-GitHits-Client-Version required: false schema: type: string - description: >- Optional trimmed printable ASCII agent attribution, maximum 160 bytes. in: header name: X-GitHits-Agent required: false schema: type: string - description: >- 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. in: header name: X-GitHits-Session-ID required: false schema: maxLength: 64 minLength: 1 pattern: ^[A-Za-z0-9_-]{1,64}$ type: string requestBody: content: application/json: examples: package: value: from_version: 4.21.2 max_files: 50 name: express path_glob: lib/** registry: npm to_version: 5.1.0 repository: value: from_ref: v1.0.0 repo_url: https://gitlab.com/group/project to_ref: main schema: $ref: '#/components/schemas/CodeDiffRequest' required: true responses: '200': content: application/json: examples: content_failed: value: 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 @@ -old +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 empty: value: content_coverage: complete content_failure: null files: [] 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: 0 inventory_complete: true mode_changed: 0 modified: 0 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 inventory_only: value: content_coverage: not_requested content_failure: null files: - content_safety: filtered: false modifications: [] content_status: not_requested mode_changed: false 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 metadata_only: value: content_coverage: complete content_failure: null files: - additions: null content_omission_reason: null content_safety: filtered: false modifications: [] content_status: metadata_only deletions: null mode_changed: true patch: null path: submodule path_encoding: utf8 status: modified type_changed: true 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 partial_content: value: content_coverage: partial content_failure: null files: - additions: null content_omission_reason: total_patch_bytes content_safety: filtered: false modifications: [] content_status: omitted deletions: null mode_changed: false patch: null path: lib/large.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 patch: value: content_coverage: complete content_failure: null files: - additions: 2 content_omission_reason: null content_safety: filtered: false modifications: [] content_status: patch deletions: 1 mode_changed: false patch: |- @@ -1 +1,2 @@ -old +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 stats: value: content_coverage: complete content_failure: null files: - additions: 2 content_safety: filtered: false modifications: [] content_status: stats deletions: 1 mode_changed: false 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 schema: $ref: '#/components/schemas/CodeDiffResponse' description: Exact-tree inventory and selected content evidence headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace identity, also problem.instance. schema: type: string '400': content: application/problem+json: examples: invalid_session_id: value: code: INVALID_SESSION_ID detail: >- X-GitHits-Session-ID must occur once and match [A-Za-z0-9_-]{1,64}. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 400 title: Invalid session ID type: about:blank validation: value: code: VALIDATION_ERROR detail: The request is invalid. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 400 title: Validation error type: about:blank schema: $ref: '#/components/schemas/CodeDiffProblem' description: >- VALIDATION_ERROR INVALID_SESSION_ID: a supplied session header is invalid or duplicated. headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace identity, also problem.instance. schema: type: string '401': content: application/problem+json: example: code: AUTHENTICATION_REQUIRED detail: A bearer credential is required. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 401 title: Authentication required type: about:blank schema: $ref: '#/components/schemas/CodeDiffProblem' description: AUTHENTICATION_REQUIRED headers: Cache-Control: schema: enum: - no-store type: string WWW-Authenticate: description: Bearer challenge. schema: type: string x-request-id: description: Active trace identity, also problem.instance. schema: type: string '403': content: application/problem+json: example: code: FORBIDDEN detail: The caller is not allowed to access this resource. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 403 title: Forbidden type: about:blank schema: $ref: '#/components/schemas/CodeDiffProblem' description: >- FORBIDDEN, ACCOUNT_INACTIVE, FEATURE_FLAG_REQUIRED, TERMS_ACCEPTANCE_REQUIRED headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace identity, also problem.instance. schema: type: string '404': content: application/problem+json: examples: missing_ref: value: available_refs: - ref: main version: null code: REF_NOT_FOUND detail: The requested repository ref was not found. git_ref: missing instance: 4bf92f3577b34da6a3ce929d0e0e4736 repo_url: https://github.com/example/project retryable: false side: to status: 404 suggested_refs: - ref: v1 version: 1.0.0 title: Ref not found type: about:blank missing_version: value: available_versions: - ref: v4.21.2 version: 4.21.2 code: VERSION_NOT_FOUND detail: The requested package version was not found. instance: 4bf92f3577b34da6a3ce929d0e0e4736 published_versions: - 4.21.2 published_versions_truncated: false retryable: false side: from status: 404 title: Version not found type: about:blank schema: $ref: '#/components/schemas/CodeDiffProblem' description: >- PACKAGE_NOT_FOUND, NO_RELEASED_VERSIONS, VERSION_NOT_FOUND, REPOSITORY_NOT_FOUND, REF_NOT_FOUND headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace identity, also problem.instance. schema: type: string '405': content: application/problem+json: example: code: METHOD_NOT_ALLOWED detail: The requested method is not supported for this route. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 405 title: Method not allowed type: about:blank schema: $ref: '#/components/schemas/ProblemResponse' description: 'METHOD_NOT_ALLOWED: the route does not support this HTTP method.' headers: Allow: description: 'Supported methods: POST.' schema: type: string Cache-Control: schema: enum: - no-store type: string X-Request-ID: description: >- Request trace ID for diagnostics; matches problem.instance on failures. schema: type: string '422': content: application/problem+json: examples: raw_limit: value: code: RAW_DIFF_LIMIT_EXCEEDED detail: The exact-tree comparison exceeded a bounded source limit. instance: 4bf92f3577b34da6a3ce929d0e0e4736 limit_kind: output_bytes retryable: false stage: output status: 422 title: Raw diff limit exceeded type: about:blank unsupported_source: value: code: UNSUPPORTED_REGISTRY detail: >- The package registry or its source repository is not supported. instance: 4bf92f3577b34da6a3ce929d0e0e4736 registry: npm retryable: false side: from status: 422 title: Unsupported source type: about:blank schema: $ref: '#/components/schemas/CodeDiffProblem' description: >- UNSUPPORTED_PACKAGE_VARIANTS, UNSUPPORTED_REGISTRY, AMBIGUOUS_REF, REF_UNRESOLVABLE, RAW_DIFF_LIMIT_EXCEEDED headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace identity, also problem.instance. schema: type: string '429': content: application/problem+json: examples: rate_limit: value: code: RATE_LIMITED detail: The request was rate limited. instance: 4bf92f3577b34da6a3ce929d0e0e4736 retry_after_ms: 1001 retryable: true status: 429 title: Rate limited type: about:blank schema: $ref: '#/components/schemas/CodeDiffProblem' description: RATE_LIMITED headers: Cache-Control: schema: enum: - no-store type: string Retry-After: description: Optional bounded delta seconds or HTTP date. schema: type: string x-request-id: description: Active trace identity, also problem.instance. schema: type: string '451': content: application/problem+json: examples: legally_blocked: value: code: REPOSITORY_LEGALLY_BLOCKED detail: The source repository is unavailable for legal reasons. instance: 4bf92f3577b34da6a3ce929d0e0e4736 retryable: false side: to status: 451 title: Repository legally blocked type: about:blank schema: $ref: '#/components/schemas/CodeDiffProblem' description: REPOSITORY_LEGALLY_BLOCKED headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace identity, also problem.instance. schema: type: string '500': description: >- Request identity could not be created. Empty body without X-Request-ID; no problem object is available. headers: Cache-Control: schema: enum: - no-store type: string x-githits-empty-identity-failure: true '502': content: application/problem+json: example: code: UPSTREAM_ERROR detail: The upstream service returned malformed evidence or failed. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 502 title: Upstream error type: about:blank schema: $ref: '#/components/schemas/CodeDiffProblem' description: UPSTREAM_ERROR headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace identity, also problem.instance. schema: type: string '503': content: application/problem+json: example: code: PACKAGE_INDEXING detail: >- Source indexing is still in progress or required raw inventory is unavailable. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 503 title: Comparison unavailable type: about:blank schema: $ref: '#/components/schemas/CodeDiffProblem' description: PACKAGE_INDEXING, RAW_DIFF_UNAVAILABLE headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace identity, also problem.instance. schema: type: string '504': content: application/problem+json: example: code: TIMEOUT detail: The comparison did not complete within the operation deadline. instance: 4bf92f3577b34da6a3ce929d0e0e4736 status: 504 title: Upstream timeout type: about:blank schema: $ref: '#/components/schemas/CodeDiffProblem' description: TIMEOUT headers: Cache-Control: schema: enum: - no-store type: string x-request-id: description: Active trace identity, also problem.instance. schema: type: string security: - bearer_auth: [] x-codeSamples: - label: Package patch lang: HTTP source: >- POST /v1/code/diff HTTP/1.1 Host: api.githits.dev Authorization: Bearer Content-Type: application/json {"registry":"npm","name":"express","from_version":"4.21.2","to_version":"5.1.0"} - label: Repository inventory lang: HTTP source: >- POST /v1/code/diff?fields=files HTTP/1.1 Host: api.githits.dev Authorization: Bearer Content-Type: application/json {"repo_url":"https://codeberg.org/example/project","from_ref":"v1.0.0","to_ref":"main"} components: schemas: CodeDiffRequest: additionalProperties: false description: Compare two package versions or two repository refs. properties: from_ref: description: Explicit base ref, at most 255 UTF-8 bytes. type: string from_version: description: Base package version or registry-compatible constraint. type: string max_files: default: 50 description: Maximum relevance-ranked files returned after filtering. format: int32 maximum: 300 minimum: 1 type: integer max_patch_bytes: default: 262144 description: Total patch-byte budget, used only when `files.patch` is selected. format: int32 maximum: 2097152 minimum: 1024 type: integer name: description: Package name; requires registry and both version endpoints. type: string path_glob: description: Repository-relative bounded glob intersected with `path_prefix`. type: string path_prefix: description: >- Repository-relative component prefix, normalized without edge slashes. type: string registry: description: Package registry; requires name and both version endpoints. enum: - npm - pypi - hex - crates - vcpkg - zig - nuget - maven - packagist - rubygems - go - swift type: string repo_url: description: Supported credential-free public GitHub, GitLab or Codeberg URL. type: string to_ref: description: Explicit head ref, at most 255 UTF-8 bytes. type: string to_version: description: Head package version or registry-compatible constraint. type: string type: object CodeDiffResponse: description: Resolved commits, complete inventory counts, and selected file details. properties: content_coverage: $ref: '#/components/schemas/CodeDiffContentCoverage' description: Coverage of optional content for returned files. content_failure: oneOf: - type: 'null' - $ref: '#/components/schemas/CodeDiffContentFailure' description: >- Bounded content-phase failure; null unless `content_coverage` is failed. files: description: >- Files in relevance order, limited by `max_files`; paths that cannot be represented are omitted. items: $ref: '#/components/schemas/CodeDiffFile' type: array from_resolution: $ref: '#/components/schemas/CodeDiffResolution' description: Immutable base-side resolution used by the diff. has_more_files: description: >- Whether additional matching files with representable paths were omitted by `max_files`. type: boolean package: oneOf: - type: 'null' - $ref: '#/components/schemas/CodeDiffPackage' description: Canonical package identity; null for repository addressing. scope: $ref: '#/components/schemas/CodeDiffScope' description: Effective repository inventory scope and caller filters. summary: $ref: '#/components/schemas/CodeDiffSummary' description: >- Complete counts of matching repository changes, before limiting returned files. to_resolution: $ref: '#/components/schemas/CodeDiffResolution' description: Immutable head-side resolution used by the diff. required: - package - from_resolution - to_resolution - summary - scope - content_coverage - content_failure - files - has_more_files type: object CodeDiffProblem: allOf: - $ref: '#/components/schemas/ProblemResponse' - properties: available_refs: description: Indexed source ref/version alternatives in source order. items: $ref: '#/components/schemas/CodeDiffAvailableVersion' maxItems: 5 type: array available_versions: description: >- Available source refs paired with published package versions when known. items: $ref: '#/components/schemas/CodeDiffAvailableVersion' maxItems: 10 type: array git_ref: description: Requested repository ref associated with the failure. maxLength: 255 type: string limit_kind: description: Bounded raw-diff limit identifier. maxLength: 64 type: string published_versions: description: >- Published package version suggestions in source order; not a complete inventory. items: type: string maxItems: 50 type: array published_versions_truncated: description: >- Whether more published version suggestions were omitted by the source. type: boolean ref_kinds: description: Source ref kinds that make the requested name ambiguous. items: $ref: '#/components/schemas/CodeDiffRefKind' maxItems: 4 type: array registry: description: Supported package registry associated with this failure. type: string repo_url: description: >- Credential-free supported repository URL associated with the failure. type: string retry_after_ms: description: >- Source retry delay in milliseconds; Retry-After header takes precedence. format: int32 maximum: 2147483647 minimum: 0 type: integer retryable: description: >- Whether repeating the request may succeed without changing its input. type: boolean side: $ref: '#/components/schemas/CodeDiffSide' description: Comparison endpoint whose resolution failed. stage: description: Comparison stage associated with the failure, when available. maxLength: 64 type: string suggested_refs: description: Nearby source ref/version suggestions in source order. items: $ref: '#/components/schemas/CodeDiffAvailableVersion' maxItems: 5 type: array type: object description: >- Problem response with optional hints for correcting or retrying the request. ProblemResponse: description: >- The stable problem document returned for an unsuccessful public API request. properties: acceptance_url: description: Link for accepting the required terms, when provided. type: string code: description: The stable uppercase API error code. type: string detail: description: A stable, client-safe explanation of the failure. type: string instance: description: The active request trace ID. type: string status: description: The HTTP status returned with this problem. format: int32 minimum: 0 type: integer terms_url: description: Link to the terms that require acceptance, when provided. type: string title: description: A short, stable title for the error. type: string type: description: The generic RFC 9457 problem type. type: string required: - type - title - status - detail - instance - code type: object CodeDiffContentCoverage: description: Coverage of optional content for the returned files. enum: - not_requested - complete - partial - failed type: string CodeDiffContentFailure: description: >- Failure details for stats or patch work; the file inventory remains complete. properties: code: $ref: '#/components/schemas/CodeDiffContentFailureCode' description: Stable source failure category. limit_kind: description: Bounded source limit identifier, when available. type: - string - 'null' retry_after_ms: description: Suggested minimum retry delay in milliseconds, when available. format: int32 minimum: 0 type: - integer - 'null' retryable: description: Whether unchanged input may succeed when retried. type: boolean stage: description: Bounded source stage, when available. type: - string - 'null' required: - code - retryable - retry_after_ms - stage - limit_kind type: object CodeDiffFile: description: One changed file with its status and selected stats or patch. properties: additions: description: Selected textual inserted-line count; null when unavailable. format: int32 minimum: 0 type: - integer - 'null' content_omission_reason: description: Selected bounded omission reason; null for non-omitted content. type: - string - 'null' content_safety: $ref: '#/components/schemas/CodeDiffContentSafety' description: Source normalization report for path, omission reason and patch. content_status: $ref: '#/components/schemas/CodeDiffContentStatus' description: Strongest content evidence produced for this row. deletions: description: Selected textual deleted-line count; null when unavailable. format: int32 minimum: 0 type: - integer - 'null' mode_changed: description: Whether the Git file mode changed. type: boolean patch: description: >- Selected bounded unified patch; null for non-text or omitted content. type: - string - 'null' path: description: Display path; `byte_escaped` paths are not exact read tokens. type: string path_encoding: $ref: '#/components/schemas/CodeDiffPathEncoding' description: Whether path preserves the original opaque path bytes. status: $ref: '#/components/schemas/CodeDiffFileStatus' description: Directional tree status from base to head. type_changed: description: Whether the Git object kind changed. type: boolean required: - path - path_encoding - status - mode_changed - type_changed - content_status - content_safety type: object CodeDiffResolution: description: >- Requested endpoint and immutable commit resolution for one comparison side. properties: commit_sha: description: Full immutable commit SHA used for the exact-tree comparison. type: string ref: description: Resolved checkout ref retained as provenance, not identity. type: string ref_kind: $ref: '#/components/schemas/CodeDiffRefKind' description: Source classification of the resolved ref. requested: description: Exact version constraint or ref spelling supplied by the caller. type: string resolved_version: description: >- Exact published version selected for package addressing; null for repositories. type: - string - 'null' version_source: oneOf: - type: 'null' - $ref: '#/components/schemas/CodeDiffVersionSource' description: Package version-to-ref evidence source; null for repositories. required: - requested - resolved_version - ref - commit_sha - ref_kind - version_source type: object CodeDiffPackage: description: Canonical package and source repository identity. properties: name: description: Canonical registry package name. type: string registry: description: Canonical package registry. type: string repo_url: description: Canonical supported public repository URL. type: string required: - registry - name - repo_url type: object CodeDiffScope: description: Source scope and caller filters for this repository-wide inventory. properties: from_subpath: description: Package subdirectory; null for repository-wide comparisons. type: - string - 'null' path_glob: description: Caller glob exactly as accepted; null when omitted. type: - string - 'null' path_prefix: description: Normalized caller prefix; null when omitted. type: - string - 'null' status: $ref: '#/components/schemas/CodeDiffScopeStatus' description: Source-reported scope; current successful execution is repository. to_subpath: description: Package subdirectory; null for repository-wide comparisons. type: - string - 'null' required: - status - from_subpath - to_subpath - path_prefix - path_glob type: object CodeDiffSummary: description: >- Full filtered inventory counts independent of file and content truncation. properties: added: description: Paths present only in the head tree. format: int32 minimum: 0 type: integer deleted: description: Paths present only in the base tree. format: int32 minimum: 0 type: integer files_changed: description: >- Changed paths, including paths omitted because they cannot be represented or exceed `max_files`. format: int32 minimum: 0 type: integer inventory_complete: description: >- Always true on success: inventory enumeration completed, even if file details are limited. type: boolean mode_changed: description: Modified paths whose Git mode changed. format: int32 minimum: 0 type: integer modified: description: Paths present in both trees and changed. format: int32 minimum: 0 type: integer type_changed: description: Modified paths whose Git object kind changed. format: int32 minimum: 0 type: integer unprojectable_files: description: >- Matching paths too long to represent; included in summary counts but omitted from files. format: int32 minimum: 0 type: integer required: - files_changed - added - deleted - modified - mode_changed - type_changed - inventory_complete - unprojectable_files type: object CodeDiffAvailableVersion: description: >- Ordered source alternative; version is null for an unpaired repository ref. properties: ref: description: Exact source ref spelling supplied as recovery guidance. maxLength: 255 minLength: 1 type: string version: description: Published package version, when known. maxLength: 100 type: - string - 'null' required: - ref - version type: object CodeDiffRefKind: description: How a repository ref was classified before exact-SHA resolution. enum: - sha - tag - branch - head - unknown type: string CodeDiffSide: description: The failed comparison endpoint. enum: - from - to type: string CodeDiffContentFailureCode: description: Stable content-phase failure codes produced by the owning source. enum: - RATE_LIMITED - RAW_DIFF_LIMIT_EXCEEDED - RAW_DIFF_UNAVAILABLE - TIMEOUT - UPSTREAM_ERROR - INTERNAL_ERROR type: string CodeDiffContentSafety: description: Normalization applied to returned paths, omission reasons, and patches. properties: filtered: description: >- Whether normalization changed any returned path, omission reason, or patch. type: boolean modifications: description: Deduplicated transformations applied by the source. items: $ref: '#/components/schemas/CodeDiffContentModification' type: array required: - filtered - modifications type: object CodeDiffContentStatus: description: Strongest content evidence produced for one inventory row. enum: - not_requested - stats - patch - binary - metadata_only - omitted - unavailable type: string CodeDiffPathEncoding: description: Whether the display path preserves the original opaque path bytes. enum: - utf8 - byte_escaped type: string CodeDiffFileStatus: description: Directional tree status from base to head. enum: - added - deleted - modified type: string CodeDiffVersionSource: description: Evidence used to map a package version to a source ref. enum: - registry - git_head - tag - release type: string CodeDiffScopeStatus: description: Scope of the compared file inventory. enum: - package - repository - unknown type: string CodeDiffContentModification: description: Finite transformations applied by the source content-safety pipeline. enum: - invisible_controls_stripped - html_comments_stripped - images_replaced - unsafe_links_neutralized type: string securitySchemes: bearer_auth: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.