# Quickstart

Make a read-only API key, then list the conversations in your inbox. It takes about 2 minutes.

Rookery for developers · Updated October 11, 2026 · https://userookery.com/developers/quickstart/

In about 2 minutes you'll make an API key and list the open conversations in your inbox. You need to be an owner or admin of your Rookery workspace, and a terminal with `curl`.

## 1. Make a read-only key

1. In Rookery, go to **Settings → Integrations → API keys**.
2. Give the key a **Name**, like "My first script".
3. Under **It may**, leave only **Read** ticked. A read-only key can look at mail but can't change anything, so it's the safe way to try things.
4. Click **Create key**, then copy the key. It starts with `rk_` and it's shown only once.

## 2. Keep the key out of your code

Put the key in an environment variable. Every example in these docs reads it from `ROOKERY_KEY`.

```bash
export ROOKERY_KEY=rk_xxx
```

Paste your key in place of `rk_xxx`. Never commit a key to a repository or put it in a web page.

## 3. Check the key works

```bash
curl https://app.userookery.com/api/v1/me \
  -H "Authorization: Bearer $ROOKERY_KEY"
```

You get back the agent the key acts as, and what it may do:

```json
{
  "agent": { "id": "agt_3n7q2wv9k4hxm8tr", "name": "My first script" },
  "scopes": ["read"]
}
```

A `401` means the key is missing, mistyped or revoked. Check that `ROOKERY_KEY` is set in this terminal.

## 4. List your open conversations

```bash
curl "https://app.userookery.com/api/v1/conversations?view=open&limit=5" \
  -H "Authorization: Bearer $ROOKERY_KEY"
```

You get up to 5 conversations, newest first. Each has an `id` like `cnv_…`, the subject, the customer, who it's assigned to and its tags.

## 5. Read one

Copy an `id` from the list and read the whole conversation:

```bash
curl https://app.userookery.com/api/v1/conversations/cnv_xxx \
  -H "Authorization: Bearer $ROOKERY_KEY"
```

The `timeline` has every message (with quoted history removed), the team's internal notes and what happened along the way.

## Next

- Try any endpoint from your browser in the [API reference](https://userookery.com/developers/reference/). Paste your read-only key into **Try it**.
- Let an agent write replies that a person approves: [Draft, don't send](https://userookery.com/developers/draft-dont-send/).
- Connect Claude Code, Claude or Cursor: [Connect with MCP](https://userookery.com/developers/mcp/).