repos.branches.delete

Delete a branch from the repository. Name the branch with the target_branch and ephemeral query parameters. The server resolves the current branch tip before deleting, so the caller does not need the branch SHA. The default branch is protected and cannot be deleted through this endpoint.

Scope: git:write on the repository.

DELETE /api/repos/{repo_name}/branches

TypeScript

TypeScript

import { Pierre } from '@pierre/sdk';

// The client reads PIERRE_ORG and PIERRE_PRIVATE_KEY.
const pierre = new Pierre();

const result = await pierre.repos.branches.delete({
  repo_name: 'my-demo-repository',
  target_branch: 'feature/old-onboarding',
});
console.log(result);

200

{
  "ephemeral": false,
  "message": "branch deleted",
  "target_branch": "feature/old-onboarding"
}

Authorizations

Authorization · string · header · required

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.

Path Parameters

repo_name · string · required

The repository name, for example acme/web.

Query Parameters

target_branch · string

Exact short name of the branch to delete. Must not start with refs/. Required unless the deprecated body names the branch.

ephemeral · boolean

When true, delete the branch from the ephemeral namespace instead of the default namespace.

Body

application/json

Deprecated: send the target_branch and ephemeral query parameters, and no body. A query parameter wins over its body field.

Deprecated branch deletion body. Use the target_branch and ephemeral query parameters.

ephemeral · boolean · deprecated

Deprecated: use the ephemeral query parameter. Delete the branch from the ephemeral namespace instead of the default namespace.

Example:

false

name · string · deprecated

Deprecated: use the target_branch query parameter. Branch name to delete.

Example:

"feature/old-onboarding"

target_branch · string · deprecated

Deprecated: use the target_branch query parameter. Branch name to delete. Must not start with refs/.

Example:

"feature/old-onboarding"

Response

200

application/json

Branch deletion result.

Result of deleting a branch.

ephemeral · boolean · required

Whether the deleted branch lived in the ephemeral namespace.

Example:

false

message · string · required

Human-readable result message.

Example:

"branch deleted"

name · string · required · deprecated

Deprecated: use target_branch. Deleted branch name.

Example:

"feature/old-onboarding"

target_branch · string · required

Deleted branch name.

Example:

"feature/old-onboarding"