> ## Documentation Index > Fetch the complete documentation index at: https://code.storage/docs/llms.txt > Use this file to discover all available pages before exploring further. # Get Branch Diff > Compare a feature branch to its base branch and return every change that would be reviewed before a merge. Repeated `path` filters limit the diff to selected files and bypass the usual large-file filtering for those requested paths. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes Deprecated: Use `/api/repos/{repo_name}/branches/diff` instead. ## OpenAPI ````yaml https://api.pierre.code.storage/api/openapi.json get /api/v1/repos/branches/diff openapi: 3.1.0 info: description: >- The Code Storage HTTP API exposes repository management, Git reads, and write workflows over plain HTTPS. ## Authentication Send a signed JWT in the `Authorization: Bearer ` header on every request. - Organisation-scoped endpoints such as `GET /api/repos` require organisation scopes like `org:read` - Repository-scoped endpoints require a JWT whose `repo` claim names the target repository - Write operations require the relevant scope such as `git:write` or `repo:write` ## Pagination List endpoints use cursor-based pagination. - `cursor` is an opaque token returned by the previous response - `limit` defaults to `20` and is capped per endpoint - `has_more` tells you whether another request is available - `next_cursor` becomes the next `cursor` value ## Paths Preferred routes use the shorter `/api/...` form. Legacy `/api/v1/...` aliases remain documented where they are still supported and are marked as deprecated when a preferred route exists. ## Repository names in paths - Names containing `/` (or any other character that is not safe in a URL path segment) **must** be URL encoded so the value occupies a single path segment. For example, `pierre/example` becomes `pierre%2Fexample` and the request URL is `/api/repos/pierre%2Fexample/...`. - Plain names that contain only URL-safe characters can be sent as-is: `/api/repos/dotfiles/...`. - The server URL-decodes the value before resolving the repository, so double-encoding is not required. ## Errors Most endpoints return RFC 9457-compatible problem details under `application/problem+json`, with a legacy `error` field mirrored from `detail`. Streaming commit and note workflows may return operation-specific failure bodies so callers can inspect partial results, branch state, or workflow status without parsing generic error strings. title: code.storage version: 1.0.0 servers: - description: Code Storage tenant cluster url: https://api.{cluster}.code.storage variables: cluster: default: cluster description: >- Tenant cluster identifier (e.g. pierre-dev, pierre-staging, pierre-prod). security: [] tags: - description: >- Create, inspect, update, delete, and synchronise repositories, including upstream pull-sync and generic HTTPS Git credentials for non-GitHub upstreams. name: Repositories - description: Create, delete, list, and compare branches. name: Branches - description: >- Read commit metadata and diffs, or create commits without a local Git client. name: Commits - description: >- Read repository trees, file contents, archives, and server-side search results. name: Files - description: List, create, and delete Git tags. name: Tags - description: Attach and retrieve Git notes for commits or other Git objects. name: Notes paths: /api/v1/repos/branches/diff: get: tags: - Commits summary: Get Branch Diff description: >- Compare a feature branch to its base branch and return every change that would be reviewed before a merge. Repeated `path` filters limit the diff to selected files and bypass the usual large-file filtering for those requested paths. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes Deprecated: Use `/api/repos/{repo_name}/branches/diff` instead. operationId: get_branch_diff_legacy parameters: - description: Branch name to diff. example: feature/new-auth in: query name: branch required: true schema: type: string - description: Optional base branch or ref to diff against. example: main in: query name: base schema: type: string - description: Whether `branch` should be resolved from the ephemeral namespace. example: true in: query name: ephemeral schema: type: boolean - description: Whether `base` should be resolved from the ephemeral namespace. example: false in: query name: ephemeral_base schema: type: boolean - description: >- Optional repeated path filter. Provide multiple `path` query values to restrict the diff to specific files or directories. example: - src/main.go - README.md in: query name: path schema: items: type: string type: array responses: '200': content: application/json: example: base: main branch: feature/new-feature files: - bytes: 2048 is_eof: true path: src/main.go raw: |- diff --git a/src/main.go b/src/main.go ... state: M filtered_files: - bytes: 50000 is_eof: true path: package-lock.json state: M merge_base_sha: a2d127e6a4d54bb7390de828a99e36411f0c84df stats: additions: 50 changes: 60 deletions: 10 files: 3 schema: additionalProperties: false description: >- Diff between a branch and its base, including merge base, aggregate stats, and per-file changes. properties: base: description: The base branch or ref used for comparison. examples: - main type: string branch: description: The branch name being diffed. examples: - feature/new-feature type: string files: description: Files returned with inline diff content. items: additionalProperties: false description: Per-file diff entry including the raw unified diff text. properties: additions: description: Added lines in this file. format: int64 type: integer bytes: description: File size in bytes. examples: - 2048 format: int64 type: integer deletions: description: Deleted lines in this file. format: int64 type: integer is_eof: description: Whether the file ends with a newline. examples: - true type: boolean old_path: description: Previous file path for renamed files. type: string path: description: >- Repository-relative file path (new location for renames). examples: - src/main.go type: string raw: description: Raw unified diff content. examples: - |- diff --git a/src/main.go b/src/main.go ... type: string state: description: >- Git status code: A (added), M (modified), D (deleted), R (renamed), C (copied), or T (type changed). examples: - M type: string required: - path - state - raw - bytes - is_eof - additions - deletions type: object type: array filtered_files: description: >- Files filtered out of inline diff output because of size or file-type rules. items: additionalProperties: false description: >- Per-file diff entry that was excluded from inline diff output because of size or file-type rules. properties: bytes: description: File size in bytes. examples: - 50000 format: int64 type: integer is_eof: description: Whether the file ends with a newline. examples: - true type: boolean old_path: description: Previous file path for renamed files. type: string path: description: >- Repository-relative file path (new location for renames). Excluded from inline diff content because of size or file-type rules. examples: - package-lock.json type: string state: description: >- Git status code: A (added), M (modified), D (deleted), R (renamed), C (copied), or T (type changed). examples: - M type: string required: - path - state - bytes - is_eof type: object type: array merge_base_sha: description: Merge base SHA used for the three-dot branch diff. examples: - a2d127e6a4d54bb7390de828a99e36411f0c84df type: string stats: additionalProperties: false description: Aggregate diff statistics. properties: additions: description: Total added lines across the diff. examples: - 50 format: int64 type: integer changes: description: Total line changes (additions plus deletions). examples: - 60 format: int64 type: integer deletions: description: Total deleted lines across the diff. examples: - 10 format: int64 type: integer files: description: Number of files changed. examples: - 3 format: int64 type: integer required: - files - additions - deletions - changes type: object required: - branch - base - merge_base_sha - stats - files - filtered_files type: object description: >- Diff between a source branch and its base, including the merge base used for the three-dot comparison. '400': content: application/json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: >- Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status type: object application/problem+json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: >- Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status type: object description: Bad Request '401': content: application/json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: >- Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status type: object application/problem+json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: >- Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status type: object description: Unauthorized '403': content: application/json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: >- Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status type: object application/problem+json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: >- Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status type: object description: Forbidden '404': content: application/json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: >- Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status type: object application/problem+json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: >- Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status type: object description: Not Found '409': content: application/json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: >- Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status type: object application/problem+json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: >- Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status type: object description: Conflict '429': content: application/json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: >- Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status type: object application/problem+json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: >- Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status type: object description: Too Many Requests '500': content: application/json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: >- Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status type: object application/problem+json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: >- Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status type: object description: Internal Server Error '503': content: application/json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: >- Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status type: object application/problem+json: schema: additionalProperties: false description: >- RFC 9457-compatible problem details payload describing the error response. properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. type: string error: description: >- Legacy compatibility field mirroring `detail` for older clients. type: string instance: description: >- A URI reference that identifies the specific occurrence of the problem. type: string status: description: >- The HTTP status code generated by the origin server for this occurrence of the problem. format: int64 type: integer title: description: A short, human-readable summary of the problem type. type: string type: description: >- A URI reference that identifies the problem type. `about:blank` indicates the generic HTTP status semantics apply. type: string required: - type - title - status type: object description: Service Unavailable deprecated: true security: - bearerAuth: [] components: securitySchemes: bearerAuth: bearerFormat: JWT scheme: bearer type: http ````