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

POST /api/repos/{repo_name}/reset-commits

Reset Branch to Commit

cURL

curl --request POST \
  --url https://api.{cluster}.code.storage/api/repos/{repo_name}/reset-commits \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/x-ndjson' \
  --data '
"{\"metadata\":{\"target_branch\":\"main\",\"base_ref\":\"abc123def4567890abc123def4567890abc123de\",\"expected_target_sha\":\"0123456789abcdef0123456789abcdef01234567\",\"commit_message\":\"Reset branch\",\"author\":{\"name\":\"Docs Bot\",\"email\":\"[e-mail]\"}}}\n"
'

200

{
  "commit": {
    "commit_sha": "<string>",
    "pack_bytes": 1,
    "target_branch": "<string>",
    "tree_sha": "<string>"
  },
  "result": {
    "branch": "<string>",
    "new_sha": "<string>",
    "old_sha": "<string>",
    "status": "<string>",
    "success": true,
    "target_branch": "<string>",
    "message": "<string>"
  }
}

Authorizations

Authorization · string · header · required

JWT bearer token signed with your organization's registered signing key. There is no OAuth authorization server; you mint tokens yourself and the token's scopes claim carries the granted permission scopes. Public scopes: git:read (read repository contents), git:write (write branches, commits, tags, and notes), repo:write (create and manage repositories), org:read (list an organization's repositories). Each operation's security requirement names the scopes it requires. See https://code.storage/docs/getting-started/authentication for how to mint tokens.

Path Parameters

repo_name · string · required

Repository name. Names that contain / 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 is sent as pierre%2Fexample. Plain names such as example can be sent as-is. The server URL-decodes the value before resolving the repository.

Body

application/x-ndjson

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.

NDJSON stream containing one metadata object.

Response

200

application/json

Documented for backwards compatibility with clients written against the original reset-commits contract. Successful resets return 201 Created; see the 201 response.

Result of a restore commit operation, including the created commit and the branch update.

commit · object · required

Created restore commit metadata.

Show child attributes

result · object · required

Branch update result.

Show child attributes