List Branches

GEThttps://agent.blackbox.ai/api/v1/git/branches

List branches for a GitHub repository. Optionally filter to protected branches only.

This endpoint returns all branches for a given GitHub repository, along with the repository's default branch. Use the protected_only parameter to filter to branches with branch protection rules enabled.

This endpoint requires a Pro subscription and a connected GitHub account.

Authentication

To use this API, you need a BLACKBOX API Key. Follow these steps to get your API key:

Go to app.blackbox.ai/agent-api and click Get an API Key (requires a Pro subscription)
Once provisioning completes, you will be redirected to your Dashboard
From the Dashboard, create an API key to use with all Agent API requests

Your API key will be in the format: sk-xxxxxxxxxxxxxxxxxxxxxx

Headers

Authorizationstringrequired

API Key of the form Bearer <api_key>.

Example: Bearer sk_b41b647ffbfed27f616560

Query Parameters

ownerstringrequired

Repository owner (GitHub username or organization name).

Example: owner=octocat

repostringrequired

Repository name.

Example: repo=my-app

protected_onlybooleandefault: false

When true, returns only branches with branch protection rules enabled.

Default: false

Example: protected_only=true

Response Fields

branchesarray

Array of branch objects.

Branch Object

namestring

Branch name.

protectedboolean

Whether the branch has protection rules enabled.

commitobject

Latest commit on this branch.

Commit Object

shastring

Full commit SHA.

urlstring

GitHub API URL for the commit.

default_branchstring

The repository's default branch name (e.g. "main").

totalnumber

Total number of branches returned.

Request Example

curl 'https://agent.blackbox.ai/api/v1/git/branches?owner=octocat&repo=my-app' \
  -H 'Authorization: Bearer YOUR_API_KEY'

curl 'https://agent.blackbox.ai/api/v1/git/branches?owner=octocat&repo=my-app&protected_only=true' \
  -H 'Authorization: Bearer YOUR_API_KEY'

const API_KEY = "YOUR_API_KEY";

const params = new URLSearchParams({ owner: "octocat", repo: "my-app" });
const response = await fetch(
  `https://agent.blackbox.ai/api/v1/git/branches?${params}`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);

const data = await response.json();
console.log(`Default branch: ${data.default_branch}`);
data.branches.forEach(b =>
  console.log(`${b.name} (${b.protected ? "protected" : "unprotected"})`)
);

import requests

API_KEY = "YOUR_API_KEY"

response = requests.get(
    "https://agent.blackbox.ai/api/v1/git/branches",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"owner": "octocat", "repo": "my-app"},
)
data = response.json()
print(f"Default branch: {data['default_branch']}")
for branch in data["branches"]:
    status = "protected" if branch["protected"] else "unprotected"
    print(f"{branch['name']} ({status})")

package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    apiKey := "YOUR_API_KEY"
    url := "https://agent.blackbox.ai/api/v1/git/branches?owner=octocat&repo=my-app"

    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Set("Authorization", "Bearer "+apiKey)

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    var result map[string]interface{}
    json.Unmarshal(body, &result)
    fmt.Printf("Default branch: %s\n", result["default_branch"])
    fmt.Printf("Total branches: %v\n", result["total"])
}

Response Example

{
  "branches": [
    {
      "name": "main",
      "protected": true,
      "commit": {
        "sha": "abc123def456abc123def456abc123def456abc1",
        "url": "https://api.github.com/repos/octocat/my-app/commits/abc123def456"
      }
    },
    {
      "name": "develop",
      "protected": false,
      "commit": {
        "sha": "def456abc123def456abc123def456abc123def4",
        "url": "https://api.github.com/repos/octocat/my-app/commits/def456abc123"
      }
    },
    {
      "name": "blackbox/add-readme-fr",
      "protected": false,
      "commit": {
        "sha": "789xyz123abc789xyz123abc789xyz123abc789x",
        "url": "https://api.github.com/repos/octocat/my-app/commits/789xyz123abc"
      }
    }
  ],
  "default_branch": "main",
  "total": 3
}

{
  "error": "owner and repo query parameters are required"
}

Error Codes

Status Code	Error	Description
200	Success	Branch list returned
400	Bad Request	Missing `owner` or `repo` query parameters
401	Unauthorized	Invalid or missing API key
403	Forbidden	Pro subscription required or no GitHub token stored
500	Internal Server Error	Failed to fetch branches from GitHub