Conventions
| What | Value |
|---|---|
| Base URL | https://app.kosuke.ai. Every path starts with /api. |
| Authentication | Authorization: Bearer $KOSUKE_API_KEY, where the variable holds your API key. The CLI reads the same variable. |
| Path parameters | Written in braces, such as {workspaceId}, {projectId} and {sessionId}. The CLI takes them as positional arguments, in the same order. |
| Workspace ids | The API calls a workspace organization. Workspace routes live under /api/organizations, and a body field named orgId takes a workspace id. |
| Request bodies | JSON, unless a section says the route also takes files as multipart. |
To create an API key, see Authentication. A few routes serve only the web app and refuse a key. They are listed in What only the web app can do.
A first call lists the workspaces you belong to:
curl -s https://app.kosuke.ai/api/organizations \
-H "Authorization: Bearer $KOSUKE_API_KEY"
Responses and errors
A successful call answers with the result in data. A list that pages also carries meta.pagination.
{
"data": [
{ "id": "YzH4k2P9sQ1mVx7bN3cR8tL5wD0fG6jA", "name": "Acme", "slug": "acme-4f1c9a2e", "logo": null }
]
}
Some routes that change something answer 204 with no body. The route's section says so.
A failed call answers with an HTTP status, a message in error and a stable code to branch on. Some errors add details.
{ "error": "Forbidden", "code": "FORBIDDEN" }
Each page ends with the codes its routes return. Responses and errors has the full table and what to do about each code.
Pages in this reference
| Page | What you do there |
|---|---|
| Workspaces | Find your workspace ids, check provider access, read credits and usage, stop sandboxes, list members, and manage plugins and skills. |
| Provider credentials | Store, switch and remove the workspace's AI provider Credentials, including Claude Code and Codex logins. |
| GitHub | Check your GitHub Connection and list the repositories you can import. |
| Account | Read your profile, connect a Subscription, set your Default Model, and manage Personal Skills and Personal Plugins. |
| Activity | Read what changed across your workspaces and what is new to you. |
| Models | List the model values a chat session, a Default Model or the deploy agent can take. |
| Projects | Import a repository as a project, then list, rename or delete projects and read their branches and skills. |
| Project settings | Change setup commands, branches, sandbox size, services and environment variables, or import a kosuke.config.json. |
| Deploys | Start a Deploy, answer the deploy agent, stop it, pick its model and read past Deploys. |
| Chat sessions | Create, find, change, start and delete chat sessions. |
| Messages and turns | Send a message into a session and follow or stop the turn it starts. |
| Pull requests and sync | Ask the agent to open the pull request or bring the branch up to date. |
| Previews | Read, wake, reset and share a preview. |
| Files and commits | Read and write files in a session's sandbox and read its git state. |
| Diff | Read a session's changes and leave review comments on them. |
| Session files | Read the documents, mockups, images and videos the agent wrote, and point a ticket at a file. |
| Crons | Schedule a prompt to run in one or more projects, fire it once and read its runs. |
| Sensei | Read your open needs and threads across your workspaces, and merge as you. |
| Personal tasks | File, list and edit the tasks that are yours alone, and move one into a workspace. |
| Your Mac | See whether your Mac is online and what it offers, and the tools Sensei uses on it. |
Endpoints that need no API key
GET /api/meta is a liveness check. It answers 200 with an empty data object, { "data": {} }, and ignores any key you send.
curl -s https://app.kosuke.ai/api/meta
The whole API is also published as an OpenAPI 3.1 document at https://app.kosuke.ai/api/openapi.json. It needs no API key and comes without the data envelope, so OpenAPI tools read it as it is. Point a client generator at it, or hand it to your agent.