Skip to main content

Quickstart

Create an API key, start a chat session from your terminal, and read the agent's reply when its first turn ends. You need curl, jq, and a project already imported into Kosuke.

1. Create an API key​

  1. In the web app, open Settings > Your Account > API keys.
  2. Type a name for the key, such as laptop-cli.
  3. Press Create API key.
  4. Press Copy. Kosuke 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. Kosuke 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 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"

Next steps​