> ## 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. # Reset Branch to Commit > 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. ## OpenAPI ````yaml /openapi.json post /api/v1/repos/reset-commits 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/reset-commits: post: tags: - Commits summary: Reset Branch to Commit description: >- 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. operationId: reset_commits_legacy requestBody: content: application/x-ndjson: example: > {"metadata":{"target_branch":"main","target_commit_sha":"abc123def4567890abc123def4567890abc123de","expected_head_sha":"0123456789abcdef0123456789abcdef01234567","commit_message":"Reset branch","author":{"name":"Docs Bot","email":"docs@example.com"}}} schema: description: NDJSON stream containing one `metadata` object. type: string description: >- Send a single NDJSON metadata line describing the branch to restore and the commit SHA to restore it to. The handler requires this line and rejects an empty body with `400`, even though the published contract leaves it optional. responses: '200': content: application/json: schema: additionalProperties: false description: >- Result of a restore commit operation, including the created commit and the branch update. properties: commit: additionalProperties: false description: Created restore commit metadata. properties: commit_sha: description: SHA of the new restore commit. type: string pack_bytes: description: Size of the generated pack in bytes. format: int64 minimum: 0 type: integer target_branch: description: Branch that was reset. type: string tree_sha: description: Tree SHA of the restore commit. type: string required: - commit_sha - tree_sha - target_branch - pack_bytes type: object result: additionalProperties: false description: Branch update result. properties: branch: description: Branch that was updated. type: string message: description: Optional human-readable message. type: string new_sha: description: New tip SHA after restore. type: string old_sha: description: >- Previous tip SHA before restore (40-char hex; zeros when the ref did not previously exist). type: string status: description: Status code (ok, conflict, precondition_failed, etc.). type: string success: description: Whether the restore succeeded. type: boolean required: - branch - old_sha - new_sha - success - status type: object required: - commit - result type: object description: >- Documented for backwards compatibility with clients written against the original `reset-commits` contract. Successful resets return `201 Created`; see the `201` response. '201': content: application/json: schema: additionalProperties: false description: >- Result of a restore commit operation, including the created commit and the branch update. properties: commit: additionalProperties: false description: Created restore commit metadata. properties: commit_sha: description: SHA of the new restore commit. type: string pack_bytes: description: Size of the generated pack in bytes. format: int64 minimum: 0 type: integer target_branch: description: Branch that was reset. type: string tree_sha: description: Tree SHA of the restore commit. type: string required: - commit_sha - tree_sha - target_branch - pack_bytes type: object result: additionalProperties: false description: Branch update result. properties: branch: description: Branch that was updated. type: string message: description: Optional human-readable message. type: string new_sha: description: New tip SHA after restore. type: string old_sha: description: >- Previous tip SHA before restore (40-char hex; zeros when the ref did not previously exist). type: string status: description: Status code (ok, conflict, precondition_failed, etc.). type: string success: description: Whether the restore succeeded. type: boolean required: - branch - old_sha - new_sha - success - status type: object required: - commit - result type: object description: >- Restore commit created and the branch reset. This is the status a successful reset returns. '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 '412': content: application/json: example: commit: null result: branch: '' message: branch already matches target commit new_sha: '' old_sha: '' status: precondition_failed success: false schema: additionalProperties: false description: >- Result of a restore commit operation, including the created commit and the branch update. properties: commit: additionalProperties: false description: Created restore commit metadata. properties: commit_sha: description: SHA of the new restore commit. type: string pack_bytes: description: Size of the generated pack in bytes. format: int64 minimum: 0 type: integer target_branch: description: Branch that was reset. type: string tree_sha: description: Tree SHA of the restore commit. type: string required: - commit_sha - tree_sha - target_branch - pack_bytes type: object result: additionalProperties: false description: Branch update result. properties: branch: description: Branch that was updated. type: string message: description: Optional human-readable message. type: string new_sha: description: New tip SHA after restore. type: string old_sha: description: >- Previous tip SHA before restore (40-char hex; zeros when the ref did not previously exist). type: string status: description: Status code (ok, conflict, precondition_failed, etc.). type: string success: description: Whether the restore succeeded. type: boolean required: - branch - old_sha - new_sha - success - status type: object required: - commit - result type: object description: >- Storage rejected the restore because the branch cannot move as requested: the branch already points at `target_commit_sha`, the restore would produce no change, or `target_commit_sha` is not an ancestor of the current tip. The body carries the restore result with `result.status` set to `precondition_failed`. '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 ````