Quickstart

1. Create an API key

In the web app, open Settings > You > API keys.
In Key name, type a name for the key, such as laptop-cli.
Under Access, tick Tasks and sessions.
Pick an end date: 30 days, 90 days or 1 year.
Press Create API key.
Press Copy. Sensei shows the key only once.

2. Export the key

export KOSUKE_API_KEY=kosuke_...

The CLI reads the same variable.

3. List your workspaces and projects

curl -s https://app.kosuke.ai/api/organizations \
  -H "Authorization: Bearer $KOSUKE_API_KEY" | jq '.data[] | {id, name}'

{ "id": "k3Hq8vLr2", "name": "Acme" }

An API key reaches every workspace you belong to. List the projects in all of them:

curl -s https://app.kosuke.ai/api/projects \
  -H "Authorization: Bearer $KOSUKE_API_KEY" | jq '.data[] | {id, name, orgId}'

{ "id": "3f1c2a9e-5b7d-4c1e-9a0f-2d6b8e4c7a15", "name": "storefront", "orgId": "k3Hq8vLr2" }

orgId is the workspace the project belongs to. Copy the id of the project you want:

PROJECT_ID=3f1c2a9e-5b7d-4c1e-9a0f-2d6b8e4c7a15

4. Start a chat session

Send the first message as content. Sensei creates a branch, starts a sandbox and runs the first turn.

curl -s -X POST "https://app.kosuke.ai/api/projects/$PROJECT_ID/chat-sessions" \
  -H "Authorization: Bearer $KOSUKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Add a /healthz endpoint that returns 200 with {\"ok\": true}."}' \
  > session.json

SESSION_ID=$(jq -r '.data.session.id' session.json)
CHAT_JOB_ID=$(jq -r '.data.chatJobId' session.json)

The response, trimmed:

{
  "data": {
    "session": { "id": "9b2e4f60-…", "status": "active" },
    "chatJobId": "c47a1d3b-…",
    "jobNumber": 1
  }
}

The session runs on your Default Model. To pick another, add "model": "anthropic:sonnet-5-5__medium" to the body. kosuke models list prints every id.

5. Follow the turn

Poll the turn's job until it leaves pending and running:

while true; do
  STATUS=$(curl -s "https://app.kosuke.ai/api/projects/$PROJECT_ID/chat-sessions/$SESSION_ID/jobs/chat/$CHAT_JOB_ID" \
    -H "Authorization: Bearer $KOSUKE_API_KEY" | jq -r '.data.job.status')
  echo "$STATUS"
  case "$STATUS" in
    pending|running) sleep 3 ;;
    *) break ;;
  esac
done

The first turn waits for the sandbox to start, so it takes longer than later ones. It ends as completed, awaiting_response (the agent asked you a Clarification), failed or cancelled. Follow a turn says what to do after each.

With the CLI installed, one command streams the turn instead:

kosuke sessions jobs watch "$PROJECT_ID" "$SESSION_ID" "$CHAT_JOB_ID"

6. Read the reply

curl -s "https://app.kosuke.ai/api/projects/$PROJECT_ID/chat-sessions/$SESSION_ID/messages" \
  -H "Authorization: Bearer $KOSUKE_API_KEY" \
  | jq -r '[.data.messages[] | select(.role == "assistant")] | last | .blocks[] | select(.type == "text") | .content'

7. Open the session in the web app

Print the link, then open it to watch the session, try the preview and review the changes:

echo "https://app.kosuke.ai/projects/$PROJECT_ID/chat-sessions?session=$SESSION_ID"

Quickstart.