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	List the repositories the Kosuke GitHub App can reach through your connection, all at once, with installUrl when there is no connection yet. 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.

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

{
  "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.

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

{
  "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.

kosuke github repositories list \
  | 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.

Next steps

• Import a repository from the list with Projects.
• Do the same in the web app with Import a repository.