Skip to content

Get all project branches

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

Retrieves all branches in the specified project (repository). Supports sorting by name or update time and paginated queries, and returns each branch's name, description, target commit, default-branch status, creation time, creator, and protection status.

Supported access tokens

  • AtomGit user access tokens

Anonymous access allowed

This endpoint allows anonymous access.

Request parameters

Parameter Location Type Required Description
owner path string Yes Namespace address to which the repository belongs (address path of the organization or user)
repo path string Yes Repository path (path)
sort query string No Sort field; enum: name / updated
direction query string No Sort direction; enum: asc / desc
page query integer No Current page number
per_page query integer No Number of items per page, maximum 100, default 20

Response parameters

The response body is an array of branch objects (array<object>). Each branch object has the following fields:

branch object

Field Type Always returned Nullable Description
name string Yes No Branch name
description string Yes No Branch description
commit object Yes No Commit object the branch points to
default_branch boolean Yes No Whether this is the default branch
created_at string Yes No Branch creation time
creator object Yes No Creator object
protected boolean Yes No Whether the branch is protected

commit object

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

commit.commit object

Field Type Always returned Nullable Description
commit.commit.author object Yes No Commit author object
commit.commit.committer object Yes No Committer object
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 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

creator object

Field Type Always returned Nullable Description
creator.avatar_url string Yes No URL of the creator's avatar
creator.id string Yes No Creator ID
creator.login string Yes No Creator login name
creator.name string Yes No Creator name

Error response

Possible error responses for this endpoint:

400 Invalid parameters

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

401 Unauthenticated

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

Note: 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 Repository does not exist (Not found)

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);
  • This endpoint allows anonymous access, so credentials are optional. For higher privileges you can also pass an AtomGit user access token in the query string (access_token=<token>).

cURL

curl -X GET 'https://api.atomgit.com/api/v5/repos/<owner>/<repo>/branches?sort=updated&direction=desc&page=1&per_page=20' \
  -H 'Accept: application/json'

JavaScript

// Native fetch (Node.js 18+ / browsers)
const response = await fetch(
  "https://api.atomgit.com/api/v5/repos/<owner>/<repo>/branches",
  {
    method: "GET",
    headers: {
      "Accept": "application/json",
    },
  }
);

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

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

Python

import requests

resp = requests.get(
    "https://api.atomgit.com/api/v5/repos/<owner>/<repo>/branches",
    headers={
        "Accept": "application/json",
    },
    timeout=10,
)
resp.raise_for_status()

print(resp.json())

Response example

Status code: 200

[
  {
    "name": "main",
    "description": "Default branch",
    "commit": {
      "commit": {
        "author": {
          "name": "octocat",
          "date": "2024-04-16T08:41:20.000Z",
          "email": "octocat@noreply.atomgit.com"
        },
        "committer": {
          "name": "octocat",
          "date": "2024-04-16T08:41:20.000Z",
          "email": "octocat@noreply.atomgit.com"
        },
        "message": "Add test class"
      },
      "sha": "1d45587145552af003cd32cc6fde9ac9d9e5fd42",
      "url": "https://api.atomgit.com/api/v5/repos/octocat/hello-world/commits/1d45587145552af003cd32cc6fde9ac9d9e5fd42"
    },
    "default_branch": true,
    "created_at": "2024-04-16T08:41:20.000Z",
    "creator": {
      "avatar_url": "https://api.atomgit.com/avatars/octocat.png",
      "id": "10001",
      "login": "octocat",
      "name": "octocat"
    },
    "protected": true
  }
]

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 Access forbidden
404 Repository or path does not exist
429 Too many requests; rate limit triggered
500 Internal system error

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