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.
POST
/
api
/
v1
/
repos
/
reset-commits
Reset Branch to Commit
curl --request POST \
--url https://api.{cluster}.code.storage/api/v1/repos/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\":\"docs@example.com\"}}}\n"
'import requests
url = "https://api.{cluster}.code.storage/api/v1/repos/reset-commits"
payload = "{\"metadata\":{\"target_branch\":\"main\",\"base_ref\":\"abc123def4567890abc123def4567890abc123de\",\"expected_target_sha\":\"0123456789abcdef0123456789abcdef01234567\",\"commit_message\":\"Reset branch\",\"author\":{\"name\":\"Docs Bot\",\"email\":\"docs@example.com\"}}}
"
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/x-ndjson"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/x-ndjson'},
body: JSON.stringify('{"metadata":{"target_branch":"main","base_ref":"abc123def4567890abc123def4567890abc123de","expected_target_sha":"0123456789abcdef0123456789abcdef01234567","commit_message":"Reset branch","author":{"name":"Docs Bot","email":"docs@example.com"}}}\n')
};
fetch('https://api.{cluster}.code.storage/api/v1/repos/reset-commits', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.{cluster}.code.storage/api/v1/repos/reset-commits",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode('{"metadata":{"target_branch":"main","base_ref":"abc123def4567890abc123def4567890abc123de","expected_target_sha":"0123456789abcdef0123456789abcdef01234567","commit_message":"Reset branch","author":{"name":"Docs Bot","email":"docs@example.com"}}}
'),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/x-ndjson"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.{cluster}.code.storage/api/v1/repos/reset-commits"
payload := strings.NewReader("\"{\\\"metadata\\\":{\\\"target_branch\\\":\\\"main\\\",\\\"base_ref\\\":\\\"abc123def4567890abc123def4567890abc123de\\\",\\\"expected_target_sha\\\":\\\"0123456789abcdef0123456789abcdef01234567\\\",\\\"commit_message\\\":\\\"Reset branch\\\",\\\"author\\\":{\\\"name\\\":\\\"Docs Bot\\\",\\\"email\\\":\\\"docs@example.com\\\"}}}\\n\"")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/x-ndjson")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.{cluster}.code.storage/api/v1/repos/reset-commits")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/x-ndjson")
.body("\"{\\\"metadata\\\":{\\\"target_branch\\\":\\\"main\\\",\\\"base_ref\\\":\\\"abc123def4567890abc123def4567890abc123de\\\",\\\"expected_target_sha\\\":\\\"0123456789abcdef0123456789abcdef01234567\\\",\\\"commit_message\\\":\\\"Reset branch\\\",\\\"author\\\":{\\\"name\\\":\\\"Docs Bot\\\",\\\"email\\\":\\\"docs@example.com\\\"}}}\\n\"")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.{cluster}.code.storage/api/v1/repos/reset-commits")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/x-ndjson'
request.body = "\"{\\\"metadata\\\":{\\\"target_branch\\\":\\\"main\\\",\\\"base_ref\\\":\\\"abc123def4567890abc123def4567890abc123de\\\",\\\"expected_target_sha\\\":\\\"0123456789abcdef0123456789abcdef01234567\\\",\\\"commit_message\\\":\\\"Reset branch\\\",\\\"author\\\":{\\\"name\\\":\\\"Docs Bot\\\",\\\"email\\\":\\\"docs@example.com\\\"}}}\\n\""
response = http.request(request)
puts response.read_body{
"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>"
}
}{
"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>"
}
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>",
"error": "<string>",
"instance": "<string>"
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>",
"error": "<string>",
"instance": "<string>"
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>",
"error": "<string>",
"instance": "<string>"
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>",
"error": "<string>",
"instance": "<string>"
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>",
"error": "<string>",
"instance": "<string>"
}{
"commit": null,
"result": {
"branch": "",
"message": "branch already matches target commit",
"new_sha": "",
"old_sha": "",
"status": "precondition_failed",
"success": false
}
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>",
"error": "<string>",
"instance": "<string>"
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>",
"error": "<string>",
"instance": "<string>"
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>",
"error": "<string>",
"instance": "<string>"
}Authorizations
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.
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
Documented for backwards compatibility with clients written against the original reset-commits contract. Successful resets return 201 Created; see the 201 response.
⌘I
Reset Branch to Commit
curl --request POST \
--url https://api.{cluster}.code.storage/api/v1/repos/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\":\"docs@example.com\"}}}\n"
'import requests
url = "https://api.{cluster}.code.storage/api/v1/repos/reset-commits"
payload = "{\"metadata\":{\"target_branch\":\"main\",\"base_ref\":\"abc123def4567890abc123def4567890abc123de\",\"expected_target_sha\":\"0123456789abcdef0123456789abcdef01234567\",\"commit_message\":\"Reset branch\",\"author\":{\"name\":\"Docs Bot\",\"email\":\"docs@example.com\"}}}
"
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/x-ndjson"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/x-ndjson'},
body: JSON.stringify('{"metadata":{"target_branch":"main","base_ref":"abc123def4567890abc123def4567890abc123de","expected_target_sha":"0123456789abcdef0123456789abcdef01234567","commit_message":"Reset branch","author":{"name":"Docs Bot","email":"docs@example.com"}}}\n')
};
fetch('https://api.{cluster}.code.storage/api/v1/repos/reset-commits', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.{cluster}.code.storage/api/v1/repos/reset-commits",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode('{"metadata":{"target_branch":"main","base_ref":"abc123def4567890abc123def4567890abc123de","expected_target_sha":"0123456789abcdef0123456789abcdef01234567","commit_message":"Reset branch","author":{"name":"Docs Bot","email":"docs@example.com"}}}
'),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/x-ndjson"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.{cluster}.code.storage/api/v1/repos/reset-commits"
payload := strings.NewReader("\"{\\\"metadata\\\":{\\\"target_branch\\\":\\\"main\\\",\\\"base_ref\\\":\\\"abc123def4567890abc123def4567890abc123de\\\",\\\"expected_target_sha\\\":\\\"0123456789abcdef0123456789abcdef01234567\\\",\\\"commit_message\\\":\\\"Reset branch\\\",\\\"author\\\":{\\\"name\\\":\\\"Docs Bot\\\",\\\"email\\\":\\\"docs@example.com\\\"}}}\\n\"")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/x-ndjson")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.{cluster}.code.storage/api/v1/repos/reset-commits")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/x-ndjson")
.body("\"{\\\"metadata\\\":{\\\"target_branch\\\":\\\"main\\\",\\\"base_ref\\\":\\\"abc123def4567890abc123def4567890abc123de\\\",\\\"expected_target_sha\\\":\\\"0123456789abcdef0123456789abcdef01234567\\\",\\\"commit_message\\\":\\\"Reset branch\\\",\\\"author\\\":{\\\"name\\\":\\\"Docs Bot\\\",\\\"email\\\":\\\"docs@example.com\\\"}}}\\n\"")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.{cluster}.code.storage/api/v1/repos/reset-commits")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/x-ndjson'
request.body = "\"{\\\"metadata\\\":{\\\"target_branch\\\":\\\"main\\\",\\\"base_ref\\\":\\\"abc123def4567890abc123def4567890abc123de\\\",\\\"expected_target_sha\\\":\\\"0123456789abcdef0123456789abcdef01234567\\\",\\\"commit_message\\\":\\\"Reset branch\\\",\\\"author\\\":{\\\"name\\\":\\\"Docs Bot\\\",\\\"email\\\":\\\"docs@example.com\\\"}}}\\n\""
response = http.request(request)
puts response.read_body{
"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>"
}
}{
"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>"
}
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>",
"error": "<string>",
"instance": "<string>"
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>",
"error": "<string>",
"instance": "<string>"
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>",
"error": "<string>",
"instance": "<string>"
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>",
"error": "<string>",
"instance": "<string>"
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>",
"error": "<string>",
"instance": "<string>"
}{
"commit": null,
"result": {
"branch": "",
"message": "branch already matches target commit",
"new_sha": "",
"old_sha": "",
"status": "precondition_failed",
"success": false
}
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>",
"error": "<string>",
"instance": "<string>"
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>",
"error": "<string>",
"instance": "<string>"
}{
"status": 123,
"title": "<string>",
"type": "<string>",
"detail": "<string>",
"error": "<string>",
"instance": "<string>"
}