Endpoint reference
Every endpoint in this reference answers JSON. Each needs an API key except the liveness check, the OpenAPI document and the two share-link reads. Pick the page for the resource you want to act on from the table below. Most pages list their routes, the body each one takes, an example request and response, and the matching kosuke command. Pull requests and sync has no routes of its own. It shows the skill message you send to the messages route.
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, then commit and push. |
| Diff | Read a session's changes and leave review comments on them. |
| Artifacts | Read the documents, mockups, images and videos the agent wrote. |
| Crons | Schedule a prompt to run in one or more projects, fire it once and read its runs. |
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.