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

> List all GitHub repositories accessible to your connected account, including personal and organization repositories.

This endpoint returns all GitHub repositories accessible to the connected GitHub account. It fetches both personal repositories and, optionally, repositories from all organizations the user belongs to. Results are deduplicated by `full_name`.

<Note>
  This endpoint requires a **Pro subscription** and a connected GitHub account. Connect your GitHub account via `POST /api/v1/git/config` first.
</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="include_orgs" type="boolean" default="true">
  Whether to include repositories from organizations the user belongs to.

  Default: `true`

  Example: `include_orgs=false`
</ParamField>

## Response Fields

<ResponseField name="repos" type="array">
  Array of repository objects.

  <Expandable title="Repository Object">
    <ResponseField name="id" type="number">
      GitHub repository ID.
    </ResponseField>

    <ResponseField name="name" type="string">
      Repository name (without owner prefix).
    </ResponseField>

    <ResponseField name="full_name" type="string">
      Full repository name in `owner/repo` format.
    </ResponseField>

    <ResponseField name="private" type="boolean">
      Whether the repository is private.
    </ResponseField>

    <ResponseField name="html_url" type="string">
      URL to the repository on GitHub.
    </ResponseField>

    <ResponseField name="description" type="string | null">
      Repository description.
    </ResponseField>

    <ResponseField name="fork" type="boolean">
      Whether the repository is a fork.
    </ResponseField>

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

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of the last update.
    </ResponseField>
  </Expandable>
</ResponseField>

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

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl 'https://agent.blackbox.ai/api/v1/git/repos' \
    -H 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```bash cURL - Personal Only theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl 'https://agent.blackbox.ai/api/v1/git/repos?include_orgs=false' \
    -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 response = await fetch(
    "https://agent.blackbox.ai/api/v1/git/repos",
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  );

  const data = await response.json();
  console.log(`Total repos: ${data.total}`);
  data.repos.forEach(r => console.log(`${r.full_name} (${r.private ? "private" : "public"})`));
  ```

  ```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/repos",
      headers={"Authorization": f"Bearer {API_KEY}"},
  )
  data = response.json()
  print(f"Total repos: {data['total']}")
  for repo in data["repos"]:
      visibility = "private" if repo["private"] else "public"
      print(f"{repo['full_name']} ({visibility})")
  ```

  ```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/repos"

      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("Total repos: %v\n", result["total"])
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "repos": [
      {
        "id": 123456789,
        "name": "my-app",
        "full_name": "octocat/my-app",
        "private": false,
        "html_url": "https://github.com/octocat/my-app",
        "description": "My awesome application",
        "fork": false,
        "default_branch": "main",
        "updated_at": "2026-05-20T10:00:00Z"
      },
      {
        "id": 987654321,
        "name": "private-api",
        "full_name": "my-org/private-api",
        "private": true,
        "html_url": "https://github.com/my-org/private-api",
        "description": "Internal API service",
        "fork": false,
        "default_branch": "main",
        "updated_at": "2026-05-19T08:30:00Z"
      }
    ],
    "total": 2
  }
  ```

  ```json Error - No GitHub Token theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "error": "No GitHub token found. Connect your GitHub account first."
  }
  ```
</ResponseExample>

## Error Codes

| Status Code | Error                 | Description                                         |
| ----------- | --------------------- | --------------------------------------------------- |
| 200         | Success               | Repository list returned                            |
| 401         | Unauthorized          | Invalid or missing API key                          |
| 403         | Forbidden             | Pro subscription required or no GitHub token stored |
| 500         | Internal Server Error | Failed to fetch repositories from GitHub            |