Create a branch¶

POST /api/v5/repos/{owner}/{repo}/branches

Creates a new branch in the specified repository. You can specify the branch starting point, the new branch name, and a description. On success it returns the new branch's name, description, target commit, and attributes such as whether it is the default or a protected branch.

Supported access tokens¶

AtomGit user access tokens

Anonymous access allowed¶

This endpoint does not allow anonymous access.

Request parameters¶

Parameter	Location	Type	Required	Description
`owner`	path	string	Yes	Namespace address to which the repository belongs (address path of the enterprise, organization, or user)
`repo`	path	string	Yes	Repository path (path)
`access_token`	query	string	Yes	User authorization code

Request Body:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "refs": {
      "description": "Starting point name",
      "type": "string",
      "default": "master"
    },
    "branch_name": {
      "description": "Name of the new branch",
      "type": "string"
    },
    "description": {
      "description": "Branch description",
      "type": "string"
    }
  },
  "required": ["refs", "branch_name"]
}

Response parameters¶

Field	Type	Always returned	Nullable	Description
`name`	string	Yes	No	Name of the new branch
`description`	string	Yes	No	Branch description
`commit`	object	Yes	No	Commit information the branch points to
`default_branch`	boolean	Yes	No	Whether this is the default branch
`protected`	boolean	Yes	No	Whether this is a protected branch

commit object

Field	Type	Always returned	Nullable	Description
`commit.commit`	object	Yes	No	Commit content
`commit.sha`	string	Yes	No	SHA value of the commit
`commit.url`	string	Yes	No	Link to the commit details

`commit.commit` object¶

Field	Type	Always returned	Nullable	Description
`commit.commit.author`	object	Yes	No	Author information
`commit.commit.committer`	object	Yes	No	Committer information
`commit.commit.message`	string	Yes	No	Commit message

`commit.commit.author` object¶

Field	Type	Always returned	Nullable	Description
`commit.commit.author.name`	string	Yes	No	Author name
`commit.commit.author.date`	string	Yes	No	Author commit time
`commit.commit.author.email`	string	Yes	No	Author email

`commit.commit.committer` object¶

Field	Type	Always returned	Nullable	Description
`commit.commit.committer.name`	string	Yes	No	Committer name
`commit.commit.committer.date`	string	Yes	No	Commit time
`commit.commit.committer.email`	string	Yes	No	Committer email

Error response¶

400 Invalid parameters

{
  "error": "invalid_request",
  "message": "Parameter branch_name cannot be empty",
  "field": "branch_name"
}

401 Unauthenticated

{
  "error": "unauthorized",
  "message": "Missing or invalid access token"
}

Error field names follow what the backend actually returns.

HTTP status codes¶

Status code	Description
`200`	Success (OK)
`400`	Invalid parameters (Bad Request)
`401`	Authentication required (Requires authentication)
`403`	Access forbidden (Forbidden)
`404`	Resource does not exist (Not Found)
`500`	Internal system error (Internal Server Error)

Request example¶

Parameter notes¶

Replace <owner> with the namespace address to which the repository belongs (the address path of the enterprise, organization, or user); replace <repo> with the repository path (path); replace <token> with your AtomGit user access token.

cURL¶

curl -X POST 'https://api.atomgit.com/api/v5/repos/<owner>/<repo>/branches?access_token=<token>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
  "refs": "master",
  "branch_name": "feature/test-branch",
  "description": "Test branch"
}'

JavaScript¶

const response = await fetch(
  "https://api.atomgit.com/api/v5/repos/<owner>/<repo>/branches?access_token=<token>",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Accept": "application/json",
    },
    body: JSON.stringify({
      refs: "master",
      branch_name: "feature/test-branch",
      description: "Test branch",
    }),
  }
);

if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`);
}

const data = await response.json();
console.log(data);

Python¶

import requests

resp = requests.post(
    "https://api.atomgit.com/api/v5/repos/<owner>/<repo>/branches",
    params={"access_token": "<token>"},
    headers={
        "Content-Type": "application/json",
        "Accept": "application/json",
    },
    json={
        "refs": "master",
        "branch_name": "feature/test-branch",
        "description": "Test branch",
    },
    timeout=10,
)
resp.raise_for_status()

print(resp.json())

Response example¶

Status code: 200

{
  "name": "gitcode",
  "description": "Test branch",
  "commit": {
    "commit": {
      "author": {
        "name": "dengmengmian",
        "date": "2024-09-10T08:29:18Z",
        "email": "dengmengmian@noreply.atomgit.com"
      },
      "committer": {
        "name": "dengmengmian",
        "date": "2024-09-10T08:29:18Z",
        "email": "dengmengmian@noreply.atomgit.com"
      },
      "message": "test"
    },
    "sha": "1af35823b8bbcaf68776cd6cb0ecbf88cfdec905",
    "url": "https://api.atomgit.com/api/v5/repos/dengmengmian/test03/commits/1af35823b8bbcaf68776cd6cb0ecbf88cfdec905"
  },
  "default_branch": false,
  "protected": false
}

Error codes¶

Error code	Description
`400`	Invalid parameters or the request cannot be parsed
`401`	Unauthenticated or invalid credentials (missing or invalid access credentials)
`403`	No permission to perform this operation
`404`	Request path or resource does not exist
`500`	Internal system error

Markdown source: View on AtomGit·Content from the open-source project gitcode-dev/atomgit-api-doc