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

# Get GitHub Issues

> Retrieve issues from a specific GitHub repository.

This endpoint returns a list of issues from a specified GitHub repository, including issue details such as title, state, labels, and assignees.

## Authentication

To use this API, you need a BLACKBOX API Key. Follow these steps to get your API key:

1. **Click on your Profile Image** in the top right corner at [cloud.blackbox.ai](https://cloud.blackbox.ai)
2. **Click on "BLACKBOX API Token"** from the dropdown menu
3. **Copy the existing token** or **click "Generate"** if you don't have one yet

Your API key will be in the format: `bb_xxxxxxxxxxxxxxxxxxxxxx`

## Headers

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

  Example: `Bearer bb_b41b647ffbfed27f61656049d3eaeef3d903cc503345d9eb80080d98bc0`
</ParamField>

## Query Parameters

<ParamField query="owner" type="string" required>
  The GitHub username or organization name that owns the repository.

  Example: `example-user` or `example-org`
</ParamField>

<ParamField query="repo" type="string" required>
  The repository name from which to retrieve issues.

  Example: `example-repo`
</ParamField>

## Response

The endpoint returns an array of issue objects. If no issues exist, an empty array is returned.

<ResponseField name="number" type="number">
  The issue number.
</ResponseField>

<ResponseField name="title" type="string">
  The title of the issue.
</ResponseField>

<ResponseField name="state" type="string">
  The current state of the issue (`open` or `closed`).
</ResponseField>

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

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the issue was created.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp of when the issue was last updated.
</ResponseField>

<ResponseField name="labels" type="array">
  Array of label objects associated with the issue.
</ResponseField>

<ResponseField name="assignees" type="array">
  Array of user objects assigned to the issue.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl --location 'https://cloud.blackbox.ai/api/github/issues?owner=example-user&repo=example-repo' \
  --header '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 owner = "example-user";
  const repo = "example-repo";
  const API_URL = `https://cloud.blackbox.ai/api/github/issues?owner=${owner}&repo=${repo}`;

  const response = await fetch(API_URL, {
      method: "GET",
      headers: {
          Authorization: `Bearer ${API_KEY}`,
      },
  });

  const issues = await response.json();
  console.log(issues);
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import requests

  API_KEY = "YOUR_API_KEY"
  owner = "example-user"
  repo = "example-repo"
  API_URL = f"https://cloud.blackbox.ai/api/github/issues?owner={owner}&repo={repo}"

  headers = {
      "Authorization": f"Bearer {API_KEY}"
  }

  response = requests.get(API_URL, headers=headers)
  issues = response.json()
  print(issues)
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  [
      {
          "number": 42,
          "title": "Fix authentication bug",
          "state": "open",
          "html_url": "https://github.com/example-user/example-repo/issues/42",
          "created_at": "2025-11-10T09:15:30Z",
          "updated_at": "2025-11-18T14:22:45Z",
          "labels": [
              {
                  "name": "bug",
                  "color": "d73a4a"
              }
          ],
          "assignees": [
              {
                  "login": "developer1",
                  "avatar_url": "https://avatars.githubusercontent.com/u/12345?v=4"
              }
          ]
      }
  ]
  ```

  ```json Empty Response (No Issues) theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  []
  ```

  ```json Error Response theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "error": "Bad Request",
    "message": "Missing required parameters: owner and repo",
    "status": 400
  }
  ```
</ResponseExample>

## Error Codes

| Status Code | Error                 | Description                                              |
| ----------- | --------------------- | -------------------------------------------------------- |
| 200         | Success               | Issues retrieved successfully                            |
| 400         | Bad Request           | Missing required parameters: owner and repo              |
| 401         | Unauthorized          | Invalid or missing API key                               |
| 404         | Not Found             | GitHub token not found, expired, or repository not found |
| 502         | Bad Gateway           | GitHub API error occurred                                |
| 500         | Internal Server Error | Database or server error occurred                        |