Branches

Copy MarkdownOpen

Create Branch

POST /v1/repos/:slug/branches
POST /v1/repos/:namespace/:slug/branches

{
  "name": "feature-x",
  "from": "main"
}

• name — Required. New branch name
• from — Branch name to copy from (optional)
• from_sha — Commit SHA to branch from (optional, use instead of from)

If neither from nor from_sha is provided, branches from the default branch.

List Branches

GET /v1/repos/:slug/branches
GET /v1/repos/:namespace/:slug/branches

• limit — Max results (default: 100, max: 500)
• cursor — Keyset pagination cursor

Response 200:

{
  "branches": [
    { "name": "main", "sha": "7f3b..." },
    { "name": "feature-x", "sha": "a1c2..." }
  ],
  "default_branch": "main",
  "total": 2,
  "next_cursor": null
}

Get Branch

GET /v1/repos/:slug/branches/:name
GET /v1/repos/:namespace/:slug/branches/:name

Returns the branch name and the SHA of its head commit.

Delete Branch

DELETE /v1/repos/:slug/branches/:name
DELETE /v1/repos/:namespace/:slug/branches/:name

You cannot delete the default branch.

Merge Branch

POST /v1/repos/:slug/branches/:name/merge
POST /v1/repos/:namespace/:slug/branches/:name/merge

The :name in the URL is the target branch (the branch being merged into). The request body specifies the source branch and strategy:

{
  "source": "feature-x",
  "strategy": "fast-forward"
}

• source — Source branch to merge from (required)
• strategy — Merge strategy (optional, default: "fast-forward"). One of: "fast-forward", "merge-commit", "squash"
• message — Custom commit message (optional, used with merge-commit and squash)
• author — { name, email } for the merge commit author (optional, used with merge-commit and squash)
• expected_sha — CAS check on the target branch (optional). Fails with 409 if the target has moved

For example, to merge feature-x into main:

POST /v1/repos/my-app/branches/main/merge

{
  "source": "feature-x",
  "strategy": "merge-commit",
  "message": "Merge feature-x into main"
}

Strategies

Already Up-to-Date

If source and target point to the same commit, all strategies return immediately:

{
  "merged": true,
  "sha": "7f3b...",
  "strategy": "already_up_to_date"
}

Fast-Forward Response

Response 200:

{
  "merged": true,
  "sha": "a1c2...",
  "strategy": "fast-forward"
}

Returns 409 if the branches have diverged and cannot be fast-forwarded.

Merge-Commit Response

Response 200:

{
  "merged": true,
  "sha": "f6a7...",
  "strategy": "merge-commit",
  "merge_sha": "f6a7..."
}

Returns 409 with conflicts array if files cannot be auto-merged:

{
  "merged": false,
  "strategy": "merge-commit",
  "conflicts": ["src/auth.ts", "config.json"]
}

Squash Response

Response 200:

{
  "merged": true,
  "sha": "b2c3...",
  "strategy": "squash"
}

Returns 409 with conflicts array if files conflict, same as merge-commit.