The Kosuke API
Use the Kosuke API to run chat sessions from your own scripts and agents. You can start a session, send the agent messages, read the diff and open the pull request. Every endpoint lives under https://app.kosuke.ai/api. All of them take an API key, except the few public routes listed there, such as the public share-link reads and the OpenAPI document.
What you can automate
- Start chat sessions, or add them to the Backlog and start them later.
- Send messages, follow each turn to its end, and answer the agent's Clarifications.
- Read the diff, comment on lines, and send the comments back to the agent.
- Open the pull request and sync with the Target Branch, by sending skills as messages.
- Wake a session's sandbox and read its preview URLs.
- Schedule recurring prompts with crons.
- Manage projects, their settings and deploys, Workspace Skills and the workspace's AI providers.
Base URL
Send every request to https://app.kosuke.ai, with your API key in the Authorization header:
curl -s https://app.kosuke.ai/api/organizations \
-H "Authorization: Bearer $KOSUKE_API_KEY"
Responses are JSON, except the empty 204 that most deletes answer. A successful one wraps its payload in data, and a failed one carries an error message and a code. Responses and errors has the details.
API, CLI or MCP server
The API and the CLI reach the same operations, and the MCP server has a tool for all but two of them. The API and the CLI use an API key, and the CLI reads it from KOSUKE_API_KEY. The MCP server is hosted at https://app.kosuke.ai/api/mcp and signs you in through the browser, so there is nothing to run yourself.
| Client | Use it when | How to start | Guide |
|---|---|---|---|
| The API | You write your own integration, in any language. | Send requests with Authorization: Bearer $KOSUKE_API_KEY. | Quickstart |
| The CLI | You script from a shell. Each operation is one kosuke command that prints JSON, and kosuke sessions watch streams a turn as it runs. | npm install -g @kosuke-ai/cli, then kosuke auth login. | Kosuke CLI |
| The MCP server | Your coding agent, such as Claude Code, Codex or Cursor, drives Kosuke as tools. The ship, watch and submit tools cover a whole change. | Add https://app.kosuke.ai/api/mcp to the client, then sign in. | Connect your coding agent |
OpenAPI document
Kosuke describes the whole API as an OpenAPI 3.1 document at https://app.kosuke.ai/api/openapi.json. It needs no API key. Use it to generate a typed client, or hand it to your agent as the list of operations it can call. The document is served as it is, without the data wrapper.
The endpoint reference lists the same operations by resource, with examples.