code.storage

Return the cloud provider, region, and public inbound IP addresses of the Code Storage cluster that serves the current organisation. Addresses are listed separately for Git over HTTPS and for the HTTP API; allow them in firewall rules that restrict outbound traffic to Code Storage. The lists change when the cluster's ingress changes, so poll this endpoint rather than copying them once. Scope: `org:read`.

List repositories for the current organisation with cursor-based pagination. Supply `q` to filter results by a case-insensitive substring match against `repo_name` (for example `pierre/sdk-documentation`). Scope: `org:read`.

Create a repository. A repository starts empty or from a source. `base_repo` is a one-time copy of a Code Storage repository; `upstream` is a lasting link to an external Git host. A copy takes the history of one commit (`base_repo.ref`, or the source HEAD) into one branch, and keeps no link to its source. A sync keeps its upstream, and the repository can sync from it again. Set at most one of the two. Create is idempotent on the repository name. A new repository returns `201`. When the name already exists, the request returns `200`, and a copy copies nothing. When the name exists with a different upstream, the request returns `409`. The deprecated form of `base_repo`, with `provider` and `operation`, still works. Scope: `repo:write` on the repository.

Fetch the metadata of a repository. Scope: `git:read` on the repository.

Change the default branch of a repository. The gateway reads the current `HEAD` symbolic ref, then repoints it at the requested branch through a transactional compare-and-swap against that value, and finally records the new default branch in the repository row. Branch names are fully qualified for you: `main` is written as the symref target `refs/heads/main`, and a value that already starts with `refs/` is used verbatim. The branch itself is not created by this call. Scope: `repo:write` on the repository.

Permanently retire a repository. The API performs a soft delete first and then triggers asynchronous hot and cold storage cleanup. Scope: `repo:write` on the repository.

Download a repository snapshot without cloning the repo. This is useful for packaging docs, examples, or release artefacts directly from a branch, tag, or commit. Scope: `git:read` on the repository.

Detach the repository from its configured upstream provider. The operation is idempotent: already-detached repositories return success. `DELETE /api/repos/{repo_name}/upstream` replaces this endpoint. It returns the same responses. Scope: `repo:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/upstream` instead.

Return per-line blame metadata for a file at a branch, tag, or commit. Supports `git blame -L`-style range filters and rename/copy detection for callers building IDE blame views or audit tooling. Scope: `git:read` on the repository.

Get one branch by its exact short name. The response omits list pagination fields. Scope: `git:read` on the repository.

List branches in the repository with cursor pagination. Use this to build branch selectors, review tools, or sync jobs without shelling out to Git. Scope: `git:read` on the repository.

Delete a branch from the repository. Name the branch with the `target_branch` and `ephemeral` query parameters. The server resolves the current branch tip before deleting, so the caller does not need the branch SHA. The default branch is protected and cannot be deleted through this endpoint. Scope: `git:write` on the repository.

Create a new branch from an existing branch or ref. This is useful for agent workflows, ephemeral previews, or server-side automation where you do not want to clone the repo first. Scope: `git:write` on the repository.

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. `GET /api/repos/{repo_name}/diff` replaces this endpoint. Send `branch` as `ref`, `base` as `base_ref`, `ephemeral` as `ref_is_ephemeral`, and `ephemeral_base` as `base_is_ephemeral`. When you omit `base`, this endpoint diffs against the repository default branch. When you omit `base_ref`, `/diff` returns the diff of one commit. To get the same diff, read `default_branch` from the repository and send it as `base_ref`. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/diff` with `ref` and `base_ref` instead.

Resolve a branch name, short SHA, or full SHA to a commit and return the same metadata shape used in commit listings. Use this when you need commit details without computing a diff. Scope: `git:read` on the repository.

Create a commit by streaming file operations directly to the service. This is designed for automation, AI agents, and other workflows that need atomic Git writes without running a local Git process. Scope: `git:write` on the repository.

List commit history for the repository default branch or for an explicit branch. Results are cursor-paginated and ordered by commit date, newest first. Set `path` to restrict the history to commits that modified a specific file or subtree. Scope: `git:read` on the repository.

Get the diff for a commit, optionally relative to a specific base commit. Repeated `path` parameters narrow the diff to selected files or directories. Scope: `git:read` on the repository.

Create a commit by streaming a Git patch instead of individual file blobs. Use this when your workflow already produces unified diffs or generated patches. Scope: `git:write` on the repository.

Stream a file directly from the repository with byte ranges, ETag validators, and Last-Modified conditionals. Use `ref` to read from a branch, tag, or commit without cloning the repo locally. Scope: `git:read` on the repository.

List files or direct child entries at a branch, tag, or commit without cloning the repository. Each entry includes its path, Git mode, and derived type (`blob`, `tree`, `symlink`, or `submodule`). Trees no longer carry a trailing `/`; branch on `type` instead. Scope: `git:read` on the repository.

Return a recursive file tree together with per-file commit metadata in one request. Each file also includes a derived `type` field for symmetry with `/files`. Scope: `git:read` on the repository.

Create a stored HTTPS credential for a repository configured with a generic Git upstream. Scope: `repo:write` on the repository.

Update a stored HTTPS credential for a generic Git upstream. Scope: `repo:write` on the repository.

Delete a stored HTTPS credential for a generic Git upstream. Scope: `repo:write` on the repository.

Search a repository without cloning it. Results are paginated and can include surrounding context lines so downstream tools only fetch the relevant slices. Scope: `git:read` on the repository.

Merge changes between branches without cloning the repository or shelling out to Git. This endpoint also supports promoting work from ephemeral branches into long-lived branches such as `main`. Omit `expected_target_sha` to merge into the current target tip and allow the gateway to retry stale target/repository movement internally; set `expected_target_sha` to require a strict target-tip precondition. GitHub-backed public targets currently do not use automatic retry. Scope: `git:write` on the repository.

Preview merge conflicts without creating commits, updating refs, or touching a working tree. When requested, conflict content is rendered from Git objects produced in request-local scratch storage. Scope: `git:read` on the repository.

Read the Git note attached to a commit or other Git object SHA. Notes let you store review status, handoff details, or other context without changing repository contents. Scope: `git:read` on the repository.

Attach text to a Git object without changing the repository contents. Use notes for review markers, internal decisions, or other lightweight context. To add text to a note, use `POST /notes/append`. Scope: `git:write` on the repository.

Remove the Git note attached to a commit or other Git object. Name the note with the query parameters of `GET /notes`. The notes commit of the delete has the default author. Scope: `git:write` on the repository.

Add text to the note on a Git object, or create the note if the object has none. A retry after a success adds the text again. To make a retry safe, set `expected_notes_ref_sha` to the notes ref SHA that you read before the first request: a retry then fails with 409 and adds nothing. Scope: `git:write` on the repository.

List Git notes refs under a notes ref prefix with cursor pagination. Use this to discover custom notes namespaces before reading individual notes. Scope: `git:read` on the repository.

Trigger a sync from the configured upstream of the repository. This only works for repositories that have an `upstream`. `POST /api/repos/{repo_name}/upstream/pull` replaces this endpoint. It takes the same request body and returns the same response. Scope: `git:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/upstream/pull` instead.

Create a new commit that resets a branch back to a specific commit SHA while preserving normal Git history. This is an alias of `restore-commit` and is served by the same handler; prefer `restore-commit` for new integrations. A successful reset responds with `201 Created`. Ref-level outcomes are reported in `result.status` and `result.success`, not by the status code alone, and failures raised by the restore itself come back in that same restore-result body. The problem-details schemas below describe gateway-level rejections such as `401`, `403` and `429`. Scope: `git:write` on the repository.

Create a new commit that resets a branch back to a specific commit SHA while preserving normal Git history. Ref-level outcomes are reported in `result.status` and `result.success`, not by the status code alone, and failures raised by the restore itself come back in that same restore-result body. The problem-details schemas below describe gateway-level rejections such as `401`, `403` and `429`. Scope: `git:write` on the repository.

Get one tag by its exact short name. The response returns the dereferenced commit SHA and omits internal fields. Scope: `git:read` on the repository.

List tags in lexical order with cursor pagination. The returned `sha` is the dereferenced commit SHA, even for annotated tags. Scope: `git:read` on the repository.

Create a lightweight tag pointing to a specific commit. Annotated tags are not created through this endpoint. Scope: `git:write` on the repository.

Delete a tag from the repository. The server resolves the stored ref correctly for both lightweight and annotated tags. Scopes: `git:read` and `git:write` on the repository.

Detach the repository from its configured upstream provider. The operation is idempotent: already-detached repositories return success. Scope: `repo:write` on the repository.

Trigger a sync from the configured upstream of the repository. This only works for repositories that have an `upstream`. Scope: `git:write` on the repository.

Fetch the metadata of a repository. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}` instead.

Change the default branch of a repository. The gateway reads the current `HEAD` symbolic ref, then repoints it at the requested branch through a transactional compare-and-swap against that value, and finally records the new default branch in the repository row. Branch names are fully qualified for you: `main` is written as the symref target `refs/heads/main`, and a value that already starts with `refs/` is used verbatim. The branch itself is not created by this call. Scope: `repo:write` on the repository. Deprecated: Use `/api/repos/{repo_name}` instead.

List repositories for the current organisation with cursor-based pagination. Supply `q` to filter results by a case-insensitive substring match against `repo_name` (for example `pierre/sdk-documentation`). Scope: `org:read`. Deprecated: Use `/api/repos` instead.

Create a repository. A repository starts empty or from a source. `base_repo` is a one-time copy of a Code Storage repository; `upstream` is a lasting link to an external Git host. A copy takes the history of one commit (`base_repo.ref`, or the source HEAD) into one branch, and keeps no link to its source. A sync keeps its upstream, and the repository can sync from it again. Set at most one of the two. Create is idempotent on the repository name. A new repository returns `201`. When the name already exists, the request returns `200`, and a copy copies nothing. When the name exists with a different upstream, the request returns `409`. The deprecated form of `base_repo`, with `provider` and `operation`, still works. Scope: `repo:write` on the repository. Deprecated: Use `/api/repos` instead.

Download a repository snapshot without cloning the repo. This is useful for packaging docs, examples, or release artefacts directly from a branch, tag, or commit. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/archive` instead.

Detach the repository from its configured upstream provider. The operation is idempotent: already-detached repositories return success. `DELETE /api/repos/{repo_name}/upstream` replaces this endpoint. It returns the same responses. Scope: `repo:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/upstream` instead.

Return per-line blame metadata for a file at a branch, tag, or commit. Supports `git blame -L`-style range filters and rename/copy detection for callers building IDE blame views or audit tooling. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/blame` instead.

List branches in the repository with cursor pagination. Use this to build branch selectors, review tools, or sync jobs without shelling out to Git. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/branches` instead.

Delete a branch from the repository. Name the branch with the `target_branch` and `ephemeral` query parameters. The server resolves the current branch tip before deleting, so the caller does not need the branch SHA. The default branch is protected and cannot be deleted through this endpoint. Scope: `git:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/branches` instead.

Create a new branch from an existing branch or ref. This is useful for agent workflows, ephemeral previews, or server-side automation where you do not want to clone the repo first. Scope: `git:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/branches/create` instead.

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. `GET /api/repos/{repo_name}/diff` replaces this endpoint. Send `branch` as `ref`, `base` as `base_ref`, `ephemeral` as `ref_is_ephemeral`, and `ephemeral_base` as `base_is_ephemeral`. When you omit `base`, this endpoint diffs against the repository default branch. When you omit `base_ref`, `/diff` returns the diff of one commit. To get the same diff, read `default_branch` from the repository and send it as `base_ref`. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/diff` with `ref` and `base_ref` instead.

Resolve a branch name, short SHA, or full SHA to a commit and return the same metadata shape used in commit listings. Use this when you need commit details without computing a diff. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/commit` instead.

Create a commit by streaming file operations directly to the service. This is designed for automation, AI agents, and other workflows that need atomic Git writes without running a local Git process. Scope: `git:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/commit-pack` instead.

List commit history for the repository default branch or for an explicit branch. Results are cursor-paginated and ordered by commit date, newest first. Set `path` to restrict the history to commits that modified a specific file or subtree. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/commits` instead.

Permanently retire a repository. The API performs a soft delete first and then triggers asynchronous hot and cold storage cleanup. Scope: `repo:write` on the repository. Deprecated: Use `/api/repos/{repo_name}` instead.

Get the diff for a commit, optionally relative to a specific base commit. Repeated `path` parameters narrow the diff to selected files or directories. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/diff` instead.

Create a commit by streaming a Git patch instead of individual file blobs. Use this when your workflow already produces unified diffs or generated patches. Scope: `git:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/diff-commit` instead.

Stream a file directly from the repository with byte ranges, ETag validators, and Last-Modified conditionals. Use `ref` to read from a branch, tag, or commit without cloning the repo locally. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/file` instead.

List files or direct child entries at a branch, tag, or commit without cloning the repository. Each entry includes its path, Git mode, and derived type (`blob`, `tree`, `symlink`, or `submodule`). Trees no longer carry a trailing `/`; branch on `type` instead. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/files` instead.

Return a recursive file tree together with per-file commit metadata in one request. Each file also includes a derived `type` field for symmetry with `/files`. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/files/metadata` instead.

Create a stored HTTPS credential for a repository configured with a generic Git upstream. Scope: `repo:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/git-credentials` instead.

Update a stored HTTPS credential for a generic Git upstream. Scope: `repo:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/git-credentials/{git_credential_id}` instead.

Delete a stored HTTPS credential for a generic Git upstream. Scope: `repo:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/git-credentials/{git_credential_id}` instead.

Search a repository without cloning it. Results are paginated and can include surrounding context lines so downstream tools only fetch the relevant slices. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/grep` instead.

Merge changes between branches without cloning the repository or shelling out to Git. This endpoint also supports promoting work from ephemeral branches into long-lived branches such as `main`. Omit `expected_target_sha` to merge into the current target tip and allow the gateway to retry stale target/repository movement internally; set `expected_target_sha` to require a strict target-tip precondition. GitHub-backed public targets currently do not use automatic retry. Scope: `git:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/merge` instead.

Preview merge conflicts without creating commits, updating refs, or touching a working tree. When requested, conflict content is rendered from Git objects produced in request-local scratch storage. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/merge/preview` instead.

Read the Git note attached to a commit or other Git object SHA. Notes let you store review status, handoff details, or other context without changing repository contents. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/notes` instead.

Attach text to a Git object without changing the repository contents. Use notes for review markers, internal decisions, or other lightweight context. To add text to a note, use `POST /notes/append`. Scope: `git:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/notes` instead.

Remove the Git note attached to a commit or other Git object. Name the note with the query parameters of `GET /notes`. The notes commit of the delete has the default author. Scope: `git:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/notes` instead.

List Git notes refs under a notes ref prefix with cursor pagination. Use this to discover custom notes namespaces before reading individual notes. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/notes/refs` instead.

Trigger a sync from the configured upstream of the repository. This only works for repositories that have an `upstream`. `POST /api/repos/{repo_name}/upstream/pull` replaces this endpoint. It takes the same request body and returns the same response. Scope: `git:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/upstream/pull` instead.

Create a new commit that resets a branch back to a specific commit SHA while preserving normal Git history. This is an alias of `restore-commit` and is served by the same handler; prefer `restore-commit` for new integrations. A successful reset responds with `201 Created`. Ref-level outcomes are reported in `result.status` and `result.success`, not by the status code alone, and failures raised by the restore itself come back in that same restore-result body. The problem-details schemas below describe gateway-level rejections such as `401`, `403` and `429`. Scope: `git:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/reset-commits` instead.

Create a new commit that resets a branch back to a specific commit SHA while preserving normal Git history. Ref-level outcomes are reported in `result.status` and `result.success`, not by the status code alone, and failures raised by the restore itself come back in that same restore-result body. The problem-details schemas below describe gateway-level rejections such as `401`, `403` and `429`. Scope: `git:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/restore-commit` instead.

List tags in lexical order with cursor pagination. The returned `sha` is the dereferenced commit SHA, even for annotated tags. Scope: `git:read` on the repository. Deprecated: Use `/api/repos/{repo_name}/tags` instead.

Create a lightweight tag pointing to a specific commit. Annotated tags are not created through this endpoint. Scope: `git:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/tags` instead.

Delete a tag from the repository. The server resolves the stored ref correctly for both lightweight and annotated tags. Scopes: `git:read` and `git:write` on the repository. Deprecated: Use `/api/repos/{repo_name}/tags/{tag_name}` instead.