Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.clarky.ai/llms.txt

Use this file to discover all available pages before exploring further.

This walks you from zero to a working curl call against your live workspace data. By the end you’ll have listed contacts, fetched a single contact, and created one — using nothing but the terminal.
Plan availability: Standard, Pro, or Enterprise. See Plans & Billing.

​
1. Create an API key

1

Open Settings → API Keys

From the admin dashboard, click Settings, then choose API Keys under the Workspace section.
2

Click 'New API Key'

Give it a memorable name (e.g. “Local testing”). The full key is shown only once — copy it immediately.
3

Save the key

Store it somewhere safe. If you lose it, revoke it and create a new one.

​
2. Set the key as a shell variable

This keeps the key out of your shell history and makes the examples below copy-pasteable. 
export CLARKY_KEY='ck_live_paste_your_key_here'

​
3. List your contacts

Your first read. The list is automatically scoped to the workspace the key belongs to. 
curl -H "Authorization: Bearer $CLARKY_KEY" \
  "https://clarky.ai/api/v1/contacts?page=1&page_size=5"
Expected response shape: 
{
  "data": [
    {
      "id": "9f1c6a9e-8c3b-4ea2-bf8c-5b08f7a4d6c2",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "emails": ["ada@example.com"],
      "company": "Analytical Engines",
      "tags": ["beta-tester"],
      "created_at": "2026-01-12T14:30:00Z",
      "updated_at": "2026-01-12T14:30:00Z"
    }
  ],
  "pagination": { "page": 1, "page_size": 5, "total": 47, "total_pages": 10 }
}
Pipe the response through jq for readable output: curl ... | jq. Install with brew install jq on macOS.

​
4. Get a single contact

Grab any id from the previous response and use it in the path: 
curl -H "Authorization: Bearer $CLARKY_KEY" \
  "https://clarky.ai/api/v1/contacts/9f1c6a9e-8c3b-4ea2-bf8c-5b08f7a4d6c2"

​
5. Search by email

Useful for “do I already have this contact?” lookups. Returns 404 if no match. 
curl -H "Authorization: Bearer $CLARKY_KEY" \
  "https://clarky.ai/api/v1/contacts/by-email?email=ada@example.com"

​
6. Create a contact (your first write)

You’ll need a bot_id — find it in the URL when you’re inside an agent’s admin pages (/admin/<workspace>/<bot>/...), or call GET /api/v1/pipelines and use the bot_id from any returned pipeline. 
curl -X POST "https://clarky.ai/api/v1/contacts" \
  -H "Authorization: Bearer $CLARKY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": "your-bot-uuid",
    "first_name": "Test",
    "last_name": "User",
    "emails": ["test@example.com"],
    "tags": ["api-test"],
    "lead_source": "API Quickstart"
  }'
A 201 Created response means it worked. Open the CRM → People tab in your dashboard and you’ll see the new contact.
For idempotent imports use POST /api/v1/contacts/upsert — it dedupes on primary email or phone so you can re-run the same payload safely.

​
7. Verify auth is enforced

Sanity-check that the API rejects requests without a valid key: 
curl -i "https://clarky.ai/api/v1/contacts"
You should get back HTTP/1.1 401 Unauthorized with: 
{ "error": { "code": "unauthorized", "message": "Missing or invalid API key" } }

​
Common pitfalls

The Authorization header is missing, malformed, or the key has been revoked. The header must be exactly Authorization: Bearer <key> — note the literal word Bearer and a single space.
Your key was created without the write scope. Revoke it and create a new one with both read and write (the default).
The bot_id you sent doesn’t belong to your workspace. Use a bot ID from your own workspace — pulling one from GET /api/v1/pipelines is the easiest check.
You’ve exceeded the per-key rate limit (120 reads/min, 60 writes/min). Look at the Retry-After header and back off. See Rate Limits for details.
On Windows or older curl versions the JSON body may need different quoting. Use single quotes around the -d payload on macOS/Linux and escape inner double quotes on Windows, or use a --data @body.json file instead.

​
Next steps

Authentication

Scopes, key rotation, security best practices

Pagination

Walking large result sets

Rate Limits

Per-key limits and retry behavior

Contacts

Full Contacts endpoint reference