Skip to content
hydrate.sh droplet markhydrate.sh

Rename a working branch

PATCH
/v1/branches/{branch_id}
curl --request PATCH \
  --url https://api.hydrate.sh/v1/branches/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example" }'

Rename a working branch you own. There is no separate archive state for a branch (that shape is DELETE, which is already recoverable by id via the audit trail if needed) — this route is rename-only.

Requires graph:write, same as the delta-apply route: a rename round-trips (nothing is destroyed), so it carries no scope of its own.

The protected main branch cannot be renamed: 409 main_not_writable. A branch that exists but is no longer active (already discarded or merged) cannot be renamed either: 409 branch_not_active.

Only the branch’s owner may rename it; a caller who can see the branch but does not own it gets the same 404 a non-existent branch gets.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
branch_id
required
Branch Id

The branch to rename.

string format: uuid

The branch to rename.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
V1PatchBranchBody

Body for PATCH /v1/branches/{branch_id}. Rename only — a branch has no archive state the way a project does; discard (the DELETE route beside this one) is already the non-listed-but-recoverable-by-id shape a project gets from archiving. name is required (not optional-with-a- no-fields-guard, unlike the project patch body): there is only one field, so an absent body is already a 422 from Pydantic without extra code.

object
name
required
Name

New name for the branch.

string
>= 1 characters <= 200 characters
Examplegenerated
{
  "name": "example"
}

Responses

Section titled “Responses”

200

Section titled “200”

Successful Response

Media typeapplication/json
BranchPatchResponse

Rename returns the branch alone — the project is not affected.

object
branch
required
BranchMeta
object
base_main_version
required
Base Main Version
integer
created_at
required
Created At
string
id
required
Id
string format: uuid
is_main
required
Is Main
boolean
last_active_at
required
Last Active At
string
merged_at
required
Any of:
string
name
required
Name
string
owner_id
required
Any of:
string format: uuid
project_id
required
Project Id
string format: uuid
status
required
Status
string
version
required
Version
integer
project_id
required
Project Id
string format: uuid
version
required
Version
string
Examplegenerated
{
  "branch": {
    "base_main_version": 1,
    "created_at": "example",
    "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "is_main": true,
    "last_active_at": "example",
    "merged_at": "example",
    "name": "example",
    "owner_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "project_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "status": "example",
    "version": 1
  },
  "project_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "version": "example"
}

401

Section titled “401”

No credentials, malformed credentials, or revoked credentials. The envelope is leak-parity (same shape across all 401 paths) so an attacker cannot distinguish revoked vs. unknown via the body.

Media typeapplication/json
object
detail
required
string
Example
{
  "detail": "unauthenticated"
}

403

Section titled “403”

Credentials are valid but lack the scope required for this route, or the principal lacks membership in the target project.

Media typeapplication/json
object
detail
object
code
string
message
string
Examplegenerated
{
  "detail": {
    "code": "example",
    "message": "example"
  }
}

404

Section titled “404”

Resource not found OR not accessible to this principal. Leak parity: the response is identical in both cases so an attacker cannot enumerate resources via 404-vs-403 timing.

Media typeapplication/json
object
detail
object
code
string
message
string
Example
{
  "detail": {
    "code": "not_found"
  }
}

422

Section titled “422”

Validation Error

Media typeapplication/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
ctx
Context
object
input
Input
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
Examplegenerated
{
  "detail": [
    {
      "ctx": {},
      "input": "example",
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ]
}

429

Section titled “429”

Per-bucket rate limit exceeded. The response carries Retry-After and the standard X-RateLimit-* headers (Limit / Remaining / Reset).

Media typeapplication/json
object
detail
string
Example
{
  "detail": "rate_limited"
}

Headers

Section titled “Headers”
Retry-After
integer
X-RateLimit-Limit
integer
X-RateLimit-Remaining
integer
X-RateLimit-Reset
integer