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

# GitHub Connection Status

> Check whether your GitHub account is connected and verify that your stored token is valid.

This endpoint validates the stored GitHub token by calling the GitHub API and returns the connected account's profile information. Use this to confirm your GitHub integration is active before creating tasks that work with repositories.

<Note>
  This endpoint requires a **Pro subscription**. Ensure your BLACKBOX account is on the Pro plan before calling GitHub integration endpoints.
</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>

## Response Fields

### Connected

<ResponseField name="connected" type="boolean">
  `true` when a valid GitHub token is stored.
</ResponseField>

<ResponseField name="login" type="string">
  GitHub username of the connected account.
</ResponseField>

<ResponseField name="name" type="string | null">
  Display name of the GitHub user.
</ResponseField>

<ResponseField name="email" type="string | null">
  Primary email address of the GitHub user (if public).
</ResponseField>

<ResponseField name="avatarUrl" type="string">
  URL of the GitHub user's avatar image.
</ResponseField>

<ResponseField name="scopes" type="string">
  Comma-separated list of OAuth scopes granted by the token (e.g. `"repo,user"`).
</ResponseField>

<ResponseField name="publicRepos" type="number">
  Number of public repositories owned by the user.
</ResponseField>

<ResponseField name="privateRepos" type="number">
  Number of private repositories owned by the user.
</ResponseField>

<ResponseField name="tokenValid" type="boolean">
  Whether the stored token successfully authenticated with GitHub.
</ResponseField>

### Not Connected

<ResponseField name="connected" type="boolean">
  `false` when no token is stored or the token is invalid.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable explanation (e.g. `"No GitHub token found"`).
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl 'https://agent.blackbox.ai/api/v1/git/status' \
    -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/status",
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  );

  const data = await response.json();
  if (data.connected) {
    console.log(`Connected as: ${data.login}`);
    console.log(`Scopes: ${data.scopes}`);
  } else {
    console.log("GitHub not connected:", data.message);
  }
  ```

  ```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/status",
      headers={"Authorization": f"Bearer {API_KEY}"},
  )
  data = response.json()
  if data["connected"]:
      print(f"Connected as: {data['login']}")
      print(f"Scopes: {data['scopes']}")
  else:
      print(f"Not connected: {data['message']}")
  ```

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

      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)

      if result["connected"] == true {
          fmt.Printf("Connected as: %s\n", result["login"])
      } else {
          fmt.Printf("Not connected: %s\n", result["message"])
      }
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Connected theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "connected": true,
    "login": "octocat",
    "name": "The Octocat",
    "email": "octocat@github.com",
    "avatarUrl": "https://avatars.githubusercontent.com/u/583231",
    "scopes": "repo,user",
    "publicRepos": 8,
    "privateRepos": 3,
    "tokenValid": true
  }
  ```

  ```json Not Connected theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "connected": false,
    "message": "No GitHub token found"
  }
  ```
</ResponseExample>

## Error Codes

| Status Code | Error                 | Description                        |
| ----------- | --------------------- | ---------------------------------- |
| 200         | Success               | Status returned (connected or not) |
| 401         | Unauthorized          | Invalid or missing API key         |
| 403         | Forbidden             | Pro subscription required          |
| 500         | Internal Server Error | Failed to validate token           |