List Branches

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"])
}

{
  "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"
}

GET

api

git

branches

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"])
}

{
  "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"
}

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

string

required

API Key of the form Bearer <api_key>.Example: Bearer sk_b41b647ffbfed27f616560

Query Parameters

string

required

Repository owner (GitHub username or organization name).Example: owner=octocat

string

required

Repository name.Example: repo=my-app

boolean

default:"false"

When true, returns only branches with branch protection rules enabled.Default: falseExample: protected_only=true

Response Fields

array

Array of branch objects.

Show Branch Object

string

Branch name.

boolean

Whether the branch has protection rules enabled.

object

Latest commit on this branch.

Show Commit Object

string

Full commit SHA.

string

GitHub API URL for the commit.

string

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

number

Total number of branches returned.

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"])
}

{
  "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

Getting Started

API Reference

Authentication

Headers

Query Parameters

Response Fields

Error Codes

​Authentication

​Headers

​Query Parameters

​Response Fields

​Error Codes

Authentication

Headers

Query Parameters

Response Fields

Error Codes