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

{
  "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
}
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:
  1. Go to app.blackbox.ai/agent-api and click Get an API Key (requires a Pro subscription)
  2. Once provisioning completes, you will be redirected to your Dashboard
  3. 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

​
Authorization
string
required
API Key of the form Bearer <api_key>.Example: Bearer sk_b41b647ffbfed27f616560

​
Query Parameters

​
owner
string
required
Repository owner (GitHub username or organization name).Example: owner=octocat
​
repo
string
required
Repository name.Example: repo=my-app
​
protected_only
boolean
default:"false"
When true, returns only branches with branch protection rules enabled.Default: falseExample: protected_only=true

​
Response Fields

​
branches
array
Array of branch objects.
​
default_branch
string
The repository’s default branch name (e.g. "main").
​
total
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'

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

Status CodeErrorDescription
200SuccessBranch list returned
400Bad RequestMissing owner or repo query parameters
401UnauthorizedInvalid or missing API key
403ForbiddenPro subscription required or no GitHub token stored
500Internal Server ErrorFailed to fetch branches from GitHub