# The Sensei API

Use the Sensei 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](https://kosuke.ai/docs/api/authentication.md), 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:

```bash
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](https://kosuke.ai/docs/api/errors.md) 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](https://kosuke.ai/docs/api/quickstart.md) |
| The CLI | You script from a shell. Each operation is one `kosuke` command that prints JSON, and `kosuke sessions jobs watch` streams a turn as it runs. | `npm install -g @kosuke-ai/kosuke`, then `kosuke auth login`. | [Sensei CLI](https://kosuke.ai/docs/interfaces/cli.md) |
| The MCP server | Your coding agent, such as Claude Code, Codex or Cursor, drives Sensei 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](https://kosuke.ai/docs/interfaces/mcp.md) |

## OpenAPI document

Sensei 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](https://kosuke.ai/docs/endpoint-reference.md) lists the same operations by resource, with examples.

## Next steps

- [Quickstart](https://kosuke.ai/docs/api/quickstart.md)
- [Authentication](https://kosuke.ai/docs/api/authentication.md)
- [Build an agent on Sensei](https://kosuke.ai/docs/api/build-an-agent.md)