Create a branch

POST

/repos/{owner}/{repo}/branches

curl --request POST \
  --url https://gitea.example.com/api/v1/repos/example/example/branches \
  --header 'Authorization: Basic <credentials>' \
  --header 'Content-Type: application/json' \
  --data '{ "new_branch_name": "example", "old_branch_name": "example", "old_ref_name": "example" }'

Authorizations

• BasicAuth
• Token
• AccessToken
• AuthorizationHeaderToken
• SudoParam
• SudoHeader
• TOTPHeader

Parameters

Path Parameters

owner

required

string

Owner of the repo

repo

required

string

Name of the repo

Request Body

Media typeapplication/json

CreateBranchRepoOption options when creating a branch in a repository

object

new_branch_name

required

Name of the branch to create

string

unique items

old_branch_name

Deprecated: true Name of the old branch to create from

string

unique items

old_ref_name

Name of the old branch/tag/commit to create from

string

unique items

Example^generated

{
  "new_branch_name": "example",
  "old_branch_name": "example",
  "old_ref_name": "example"
}

Responses

201

Branch

Media typeapplication/json

Branch represents a repository branch

object

commit

PayloadCommit represents a commit

object

added

Array<string>

author

PayloadUser represents the author or committer of a commit

object

email

string format: email

name

Full name of the commit author

string

username

string

committer

PayloadUser represents the author or committer of a commit

object

email

string format: email

name

Full name of the commit author

string

username

string

id

Sha1 hash of the commit

string

message

string

modified

Array<string>

removed

Array<string>

timestamp

string format: date-time

url

string

verification

PayloadCommitVerification represents the GPG verification of a commit

object

payload

string

reason

string

signature

string

signer

PayloadUser represents the author or committer of a commit

object

email

string format: email

name

Full name of the commit author

string

username

string

verified

boolean

effective_branch_protection_name

string

enable_status_check

boolean

name

string

protected

boolean

required_approvals

integer format: int64

status_check_contexts

Array<string>

user_can_merge

boolean

user_can_push

boolean

Example^generated

{
  "commit": {
    "added": [
      "example"
    ],
    "author": {
      "email": "hello@example.com",
      "name": "example",
      "username": "example"
    },
    "committer": {
      "email": "hello@example.com",
      "name": "example",
      "username": "example"
    },
    "id": "example",
    "message": "example",
    "modified": [
      "example"
    ],
    "removed": [
      "example"
    ],
    "timestamp": "2026-04-15T12:00:00Z",
    "url": "example",
    "verification": {
      "payload": "example",
      "reason": "example",
      "signature": "example",
      "signer": {
        "email": "hello@example.com",
        "name": "example",
        "username": "example"
      },
      "verified": true
    }
  },
  "effective_branch_protection_name": "example",
  "enable_status_check": true,
  "name": "example",
  "protected": true,
  "required_approvals": 1,
  "status_check_contexts": [
    "example"
  ],
  "user_can_merge": true,
  "user_can_push": true
}

403

The branch is archived or a mirror.

Media typeapplication/json

404

The old branch does not exist.

Media typeapplication/json

409

The branch with the same name already exists.

Media typeapplication/json

423

APIRepoArchivedError is an error that is raised when an archived repo should be modified

Media typeapplication/json

Headers

message

string

url

string