Developer docsQuickstart
Get started

Quickstart

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

Updated View as Markdown

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.

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

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:

{
  "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

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:

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