# GitHub

Call these two routes before you create a project. `GET /api/auth/github/status` tells you whether your GitHub Connection works. `GET /api/auth/github/repositories` lists the repositories your GitHub Connection can reach through the Kosuke App, and marks the ones the Kosuke App is installed on. Pass one of those to `POST /api/projects` to import it.

| Method | Path                                                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------ | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| GET    | `/api/auth/github/repositories?limit=&cursor=&q=&importable=&installed=&refresh=` | List the repositories the Kosuke GitHub App can reach through your connection, installed first then by name, with installUrl when there is no connection yet. Every repository at once by default; with limit, pass nextCursor back as cursor until it is null. q filters by owner/name. Answers from a listing stored for up to 24 hours; refreshing true means a newer one is being read from GitHub, so read again in a few seconds. With an API key this is always your own listing, never the staff one. 401 GITHUB_RECONNECT_REQUIRED when GitHub no longer accepts your connection. |
| GET    | `/api/auth/github/status`                                                         | Whether your GitHub connection exists, the account and date behind it, and reconnectRequired when GitHub no longer accepts it.                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

Both routes read your own GitHub Connection, so they answer the same in every workspace.

## Check your GitHub Connection

Read whether you have a GitHub Connection and whether GitHub still accepts it.

```bash
curl -s https://app.kosuke.ai/api/auth/github/status \
  -H "Authorization: Bearer $KOSUKE_API_KEY"
```

```json
{
  "data": {
    "isConnected": true,
    "reconnectRequired": false,
    "username": "sam-acme",
    "avatarUrl": "https://avatars.githubusercontent.com/u/1234567",
    "connectedAt": "2026-08-14T09:12:44.000Z"
  }
}
```

| Field | Meaning |
| --- | --- |
| `isConnected` | You have a GitHub Connection. |
| `reconnectRequired` | GitHub stopped accepting the connection. Reconnect before you import. |
| `username`, `avatarUrl` | The GitHub account behind the connection, or `null`. |
| `connectedAt` | When you connected GitHub, or `null`. A reconnect keeps the date you first connected. |

To connect GitHub, open Settings > You > Integrations in the web app, open the GitHub row and press **Connect**. An API key cannot run that flow.

In the CLI, run `kosuke github connection get`.

## List repositories you can import

List every repository your GitHub Connection can reach through the Kosuke App, with the Kosuke App's install state on each.

```bash
curl -s https://app.kosuke.ai/api/auth/github/repositories \
  -H "Authorization: Bearer $KOSUKE_API_KEY"
```

```json
{
  "data": {
    "repositories": [
      {
        "id": 812405113,
        "name": "storefront",
        "full_name": "acme/storefront",
        "private": true,
        "owner": { "login": "acme" },
        "html_url": "https://github.com/acme/storefront",
        "clone_url": "https://github.com/acme/storefront.git",
        "default_branch": "main",
        "appInstalled": true,
        "installationId": 64207731
      }
    ],
    "needsGitHubConnection": false,
    "installUrl": "https://github.com/apps/kosuke-github-app"
  }
}
```

The list comes in one response, with no paging. Repositories with the Kosuke App installed come first, then the rest, each group sorted by `full_name`.

| Field | Meaning |
| --- | --- |
| `repositories[].appInstalled` | The Kosuke App is installed on this repository. Only these can become a project. |
| `repositories[].html_url` | Pass it as `repositoryUrl` to `POST /api/projects`. The `clone_url` works too. |
| `needsGitHubConnection` | `true` when you have no GitHub Connection. The list is then empty. |
| `installUrl` | The Kosuke App's page on GitHub. |

To import a repository whose `appInstalled` is `false`, open `installUrl` in a browser and install the Kosuke App on it. Then call this route again. The repository now shows `appInstalled: true`.

In the CLI, run `kosuke github repositories list`.

```bash
kosuke github repositories list --json \
  | jq -r '.data.repositories[] | select(.appInstalled) | .html_url'
```

## Reconnect when GitHub refuses

When GitHub refuses your connection, the repositories route answers `401` with code `GITHUB_RECONNECT_REQUIRED` and records the refusal. From then on the status route answers `reconnectRequired: true`. Your API key is fine. To fix it:

1. Open Settings > You > Integrations in the web app.
2. Press **Reconnect** in the GitHub row and approve on GitHub.
3. Call `GET /api/auth/github/status` again and check that `reconnectRequired` is `false`.

## Errors

| Status | Code | When |
| --- | --- | --- |
| 401 | `UNAUTHORIZED` | The API key is missing, revoked or expired. |
| 401 | `GITHUB_RECONNECT_REQUIRED` | GitHub no longer accepts your GitHub Connection. Reconnect it in the web app. |

The full list of codes is in [Responses and errors](https://kosuke.ai/docs/api/errors.md).

## Next steps

- Import a repository from the list with [Projects](https://kosuke.ai/docs/endpoint-reference/projects.md).
- Do the same in the web app with [Import a repository](https://kosuke.ai/docs/set-up/import-a-repository.md).