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 --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\",\"target_commit_sha\":\"abc123def4567890abc123def4567890abc123de\",\"expected_head_sha\":\"0123456789abcdef0123456789abcdef01234567\",\"commit_message\":\"Reset branch\",\"author\":{\"name\":\"Docs Bot\",\"email\":\"docs@example.com\"}}}\n"
'import requests
url = "https://api.{cluster}.code.storage/api/repos/{repo_name}/reset-commits"
payload = "{\"metadata\":{\"target_branch\":\"main\",\"target_commit_sha\":\"abc123def4567890abc123def4567890abc123de\",\"expected_head_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","target_commit_sha":"abc123def4567890abc123def4567890abc123de","expected_head_sha":"0123456789abcdef0123456789abcdef01234567","commit_message":"Reset branch","author":{"name":"Docs Bot","email":"docs@example.com"}}}\n')
};
fetch('https://api.{cluster}.code.storage/api/repos/{repo_name}/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/repos/{repo_name}/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","target_commit_sha":"abc123def4567890abc123def4567890abc123de","expected_head_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/repos/{repo_name}/reset-commits"
payload := strings.NewReader("\"{\\\"metadata\\\":{\\\"target_branch\\\":\\\"main\\\",\\\"target_commit_sha\\\":\\\"abc123def4567890abc123def4567890abc123de\\\",\\\"expected_head_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/repos/{repo_name}/reset-commits")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/x-ndjson")
.body("\"{\\\"metadata\\\":{\\\"target_branch\\\":\\\"main\\\",\\\"target_commit_sha\\\":\\\"abc123def4567890abc123def4567890abc123de\\\",\\\"expected_head_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/repos/{repo_name}/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\\\",\\\"target_commit_sha\\\":\\\"abc123def4567890abc123def4567890abc123de\\\",\\\"expected_head_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,
"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,
"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
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
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
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/repos/{repo_name}/reset-commits \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/x-ndjson' \
--data '
"{\"metadata\":{\"target_branch\":\"main\",\"target_commit_sha\":\"abc123def4567890abc123def4567890abc123de\",\"expected_head_sha\":\"0123456789abcdef0123456789abcdef01234567\",\"commit_message\":\"Reset branch\",\"author\":{\"name\":\"Docs Bot\",\"email\":\"docs@example.com\"}}}\n"
'import requests
url = "https://api.{cluster}.code.storage/api/repos/{repo_name}/reset-commits"
payload = "{\"metadata\":{\"target_branch\":\"main\",\"target_commit_sha\":\"abc123def4567890abc123def4567890abc123de\",\"expected_head_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","target_commit_sha":"abc123def4567890abc123def4567890abc123de","expected_head_sha":"0123456789abcdef0123456789abcdef01234567","commit_message":"Reset branch","author":{"name":"Docs Bot","email":"docs@example.com"}}}\n')
};
fetch('https://api.{cluster}.code.storage/api/repos/{repo_name}/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/repos/{repo_name}/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","target_commit_sha":"abc123def4567890abc123def4567890abc123de","expected_head_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/repos/{repo_name}/reset-commits"
payload := strings.NewReader("\"{\\\"metadata\\\":{\\\"target_branch\\\":\\\"main\\\",\\\"target_commit_sha\\\":\\\"abc123def4567890abc123def4567890abc123de\\\",\\\"expected_head_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/repos/{repo_name}/reset-commits")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/x-ndjson")
.body("\"{\\\"metadata\\\":{\\\"target_branch\\\":\\\"main\\\",\\\"target_commit_sha\\\":\\\"abc123def4567890abc123def4567890abc123de\\\",\\\"expected_head_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/repos/{repo_name}/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\\\",\\\"target_commit_sha\\\":\\\"abc123def4567890abc123def4567890abc123de\\\",\\\"expected_head_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,
"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,
"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>"
}