Start a unit of work (fork a branch from main)

POST

/v1/projects/{project_id}/branches

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

• Production

Fork a new working branch from the project’s main branch. The branch is copied from main’s current state and owned by you; your changes stay isolated on it until merged. Requires an editor role, and there is a per-project limit on how many active branches you can hold at once.

Authorizations

• Bearer

Parameters

Path Parameters

project_id

required

Project Id

The project to fork a branch in.

string format: uuid

The project to fork a branch in.

Request Body^required

Media typeapplication/json

V1CreateBranchBody

Body for POST /v1/projects/{pid}/branches. name defaults to the next main-work[-N] for the caller, so a bodyless POST works.

object

name

Any of:

string

string

>= 1 characters <= 200 characters

null

null

Example^generated

{
  "name": "example"
}

Responses

201

Successful Response

Media typeapplication/json

BranchCreateResponse

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

string

null

null

name

required

Name

string

owner_id

required

Any of:

string

string format: uuid

null

null

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

Example^generated

{
  "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

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

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

Example^generated

{
  "detail": {
    "code": "example",
    "message": "example"
  }
}

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

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

Example^generated

{
  "detail": [
    {
      "ctx": {},
      "input": "example",
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ]
}

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

Retry-After

integer

X-RateLimit-Limit

integer

X-RateLimit-Remaining

integer

X-RateLimit-Reset

integer