code.storage

Resolve the repository URL path for an internal repository ID in the current organisation. The returned `url` is the value clients use in the JWT `repo` claim. #### JWT claims Required scopes: `org:read` Requires per repo scope: No

List repositories for the current organisation with cursor-based pagination. Supply `q` to filter results by a case-insensitive substring match against the repository `url` (for example `pierre/sdk-documentation`). #### JWT claims Required scopes: `org:read` Requires per repo scope: No

Create a repository using the repo name embedded in the JWT. You can start empty, mirror an upstream repository, or fork another Code Storage repository into a new independent repo. #### JWT claims Required scopes: `repo:write` Requires per repo scope: Yes

Fetch repository metadata for the repository identified by the JWT `repo` claim. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes

Change the default branch of the repository identified by the JWT `repo` claim. 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. #### JWT claims Required scopes: `repo:write` Requires per repo scope: Yes

Permanently retire a repository. The API performs a soft delete first and then triggers asynchronous hot and cold storage cleanup. #### JWT claims Required scopes: `repo:write` Requires per repo scope: Yes

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. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes

Detach the repository from its configured upstream provider. The operation is idempotent: already-detached repositories return success. #### JWT claims Required scopes: `repo:write` Requires per repo scope: Yes

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. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes

Get one branch by its exact short name. The response omits list pagination fields. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes

List branches in the repository with cursor pagination. Use this to build branch selectors, review tools, or sync jobs without shelling out to Git. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes

Delete a branch from the repository. The default branch is protected and cannot be deleted through this endpoint. #### JWT claims Required scopes: `git:write` Requires per repo scope: Yes

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. #### JWT claims Required scopes: `git:write` Requires per repo scope: Yes

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

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. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes

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. #### JWT claims Required scopes: `git:write` Requires per repo scope: Yes

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. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes

Get the diff for a commit, optionally relative to a specific base commit. Repeated `path` parameters narrow the diff to selected files or directories. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes

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. #### JWT claims Required scopes: `git:write` Requires per repo scope: Yes

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. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes

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. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes

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`. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes

Create a stored HTTPS credential for a repository configured with a generic Git upstream. #### JWT claims Required scopes: `repo:write` Requires per repo scope: Yes

Update a stored HTTPS credential for a generic Git upstream. #### JWT claims Required scopes: `repo:write` Requires per repo scope: Yes

Delete a stored HTTPS credential for a generic Git upstream. #### JWT claims Required scopes: `repo:write` Requires per repo scope: Yes

Search a repository without cloning it. Results are paginated and can include surrounding context lines so downstream tools only fetch the relevant slices. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes

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. #### JWT claims Required scopes: `git:write` Requires per repo scope: Yes

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. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes

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. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes

Attach text to a Git object without changing the repository contents. Use notes for review markers, internal decisions, or other lightweight context. #### JWT claims Required scopes: `git:write` Requires per repo scope: Yes

Remove the Git note attached to a commit or other Git object SHA. #### JWT claims Required scopes: `git:write` Requires per repo scope: Yes

List Git notes refs under a notes ref prefix with cursor pagination. Use this to discover custom notes namespaces before reading individual notes. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes

Trigger a sync from the configured upstream for the repository in the JWT `repo` claim. This only works for repositories that were created with an upstream `base_repo`. #### JWT claims Required scopes: `git:write` Requires per repo scope: Yes

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`. #### JWT claims Required scopes: `git:write` Requires per repo scope: Yes

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`. #### JWT claims Required scopes: `git:write` Requires per repo scope: Yes

Get one tag by its exact short name. The response returns the dereferenced commit SHA and omits internal fields. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes

List tags in lexical order with cursor pagination. The returned `sha` is the dereferenced commit SHA, even for annotated tags. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes

Create a lightweight tag pointing to a specific commit. Annotated tags are not created through this endpoint. #### JWT claims Required scopes: `git:write` Requires per repo scope: Yes

Delete a tag from the repository. The server resolves the stored ref correctly for both lightweight and annotated tags. #### JWT claims Required scopes: `git:read`, `git:write` Requires per repo scope: Yes

Fetch repository metadata for the repository identified by the JWT `repo` claim. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes Deprecated: Use `/api/repos/{repo_name}` instead.

Change the default branch of the repository identified by the JWT `repo` claim. 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. #### JWT claims Required scopes: `repo:write` Requires per repo scope: Yes 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 the repository `url` (for example `pierre/sdk-documentation`). #### JWT claims Required scopes: `org:read` Requires per repo scope: No Deprecated: Use `/api/repos` instead.

Create a repository using the repo name embedded in the JWT. You can start empty, mirror an upstream repository, or fork another Code Storage repository into a new independent repo. #### JWT claims Required scopes: `repo:write` Requires per repo scope: Yes 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. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes 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. #### JWT claims Required scopes: `repo:write` Requires per repo scope: Yes Deprecated: Use `/api/repos/{repo_name}/base` 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. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes 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. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes Deprecated: Use `/api/repos/{repo_name}/branches` instead.

Delete a branch from the repository. The default branch is protected and cannot be deleted through this endpoint. #### JWT claims Required scopes: `git:write` Requires per repo scope: Yes 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. #### JWT claims Required scopes: `git:write` Requires per repo scope: Yes 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. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes Deprecated: Use `/api/repos/{repo_name}/branches/diff` 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. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes 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. #### JWT claims Required scopes: `git:write` Requires per repo scope: Yes 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. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes 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. #### JWT claims Required scopes: `repo:write` Requires per repo scope: Yes 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. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes 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. #### JWT claims Required scopes: `git:write` Requires per repo scope: Yes 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. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes 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. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes 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`. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes Deprecated: Use `/api/repos/{repo_name}/files/metadata` instead.

Create a stored HTTPS credential for a repository configured with a generic Git upstream. #### JWT claims Required scopes: `repo:write` Requires per repo scope: Yes Deprecated: Use `/api/repos/{repo_name}/git-credentials` instead.

Update a stored HTTPS credential for a generic Git upstream. #### JWT claims Required scopes: `repo:write` Requires per repo scope: Yes Deprecated: Use `/api/repos/{repo_name}/git-credentials/{git_credential_id}` instead.

Delete a stored HTTPS credential for a generic Git upstream. #### JWT claims Required scopes: `repo:write` Requires per repo scope: Yes 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. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes 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. #### JWT claims Required scopes: `git:write` Requires per repo scope: Yes 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. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes 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. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes 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. #### JWT claims Required scopes: `git:write` Requires per repo scope: Yes Deprecated: Use `/api/repos/{repo_name}/notes` instead.

Remove the Git note attached to a commit or other Git object SHA. #### JWT claims Required scopes: `git:write` Requires per repo scope: Yes 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. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes Deprecated: Use `/api/repos/{repo_name}/notes/refs` instead.

Trigger a sync from the configured upstream for the repository in the JWT `repo` claim. This only works for repositories that were created with an upstream `base_repo`. #### JWT claims Required scopes: `git:write` Requires per repo scope: Yes Deprecated: Use `/api/repos/{repo_name}/pull-upstream` 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`. #### JWT claims Required scopes: `git:write` Requires per repo scope: Yes 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`. #### JWT claims Required scopes: `git:write` Requires per repo scope: Yes 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. #### JWT claims Required scopes: `git:read` Requires per repo scope: Yes 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. #### JWT claims Required scopes: `git:write` Requires per repo scope: Yes 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. #### JWT claims Required scopes: `git:read`, `git:write` Requires per repo scope: Yes Deprecated: Use `/api/repos/{repo_name}/tags/{tag_name}` instead.