> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blackbox.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List 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.

<Note>
  This endpoint requires a **Pro subscription** and a connected GitHub account.
</Note>

## 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](https://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](https://app.blackbox.ai/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

<ParamField header="Authorization" type="string" required>
  API Key of the form `Bearer <api_key>`.

  Example: `Bearer sk_b41b647ffbfed27f616560`
</ParamField>

## Query Parameters

<ParamField query="owner" type="string" required>
  Repository owner (GitHub username or organization name).

  Example: `owner=octocat`
</ParamField>

<ParamField query="repo" type="string" required>
  Repository name.

  Example: `repo=my-app`
</ParamField>

<ParamField query="protected_only" type="boolean" default="false">
  When `true`, returns only branches with branch protection rules enabled.

  Default: `false`

  Example: `protected_only=true`
</ParamField>

## Response Fields

<ResponseField name="branches" type="array">
  Array of branch objects.

  <Expandable title="Branch Object">
    <ResponseField name="name" type="string">
      Branch name.
    </ResponseField>

    <ResponseField name="protected" type="boolean">
      Whether the branch has protection rules enabled.
    </ResponseField>

    <ResponseField name="commit" type="object">
      Latest commit on this branch.

      <Expandable title="Commit Object">
        <ResponseField name="sha" type="string">
          Full commit SHA.
        </ResponseField>

        <ResponseField name="url" type="string">
          GitHub API URL for the commit.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="default_branch" type="string">
  The repository's default branch name (e.g. `"main"`).
</ResponseField>

<ResponseField name="total" type="number">
  Total number of branches returned.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl 'https://agent.blackbox.ai/api/v1/git/branches?owner=octocat&repo=my-app' \
    -H 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```bash cURL - Protected Only theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl 'https://agent.blackbox.ai/api/v1/git/branches?owner=octocat&repo=my-app&protected_only=true' \
    -H 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  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"})`)
  );
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  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})")
  ```

  ```go Go theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  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"])
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "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
  }
  ```

  ```json Error - Missing Parameters theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "error": "owner and repo query parameters are required"
  }
  ```
</ResponseExample>

## 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                |