# 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 Sensei.

## 1. Create an API key

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

## 2. Export the key

```bash
export KOSUKE_API_KEY=kosuke_...
```

The CLI reads the same variable.

## 3. List your workspaces and projects

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

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

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

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

```json
{ "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:

```bash
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.

```bash
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:

```json
{
  "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`:

```bash
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](https://kosuke.ai/docs/api/turns.md) says what to do after each.

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

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

## 6. Read the reply

```bash
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:

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

## Next steps

- [Ship a change end to end](https://kosuke.ai/docs/recipes/ship-a-change-end-to-end.md)
- [Follow a turn](https://kosuke.ai/docs/api/turns.md)
- [Build an agent on Sensei](https://kosuke.ai/docs/api/build-an-agent.md)