Quickstart

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

Open Settings → API Keys

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

Click 'New API Key'

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

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'

$env: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

401 Unauthorized

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.

403 Forbidden on a POST/PATCH/DELETE

Your key was created without the write scope. Revoke it and create a new one with both read and write (the default).

422 Validation error referencing bot_id

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.

429 Too Many Requests

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.

Curl seems to hang

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

Getting Started

Resources

1. Create an API key

2. Set the key as a shell variable

3. List your contacts

4. Get a single contact

5. Search by email

6. Create a contact (your first write)

7. Verify auth is enforced

Common pitfalls

Next steps

Authentication

Pagination

Rate Limits

Contacts

​1. Create an API key

​2. Set the key as a shell variable

​3. List your contacts

​4. Get a single contact

​5. Search by email

​6. Create a contact (your first write)

​7. Verify auth is enforced

​Common pitfalls

​Next steps

Authentication

Pagination

Rate Limits

Contacts

1. Create an API key

2. Set the key as a shell variable

3. List your contacts

4. Get a single contact

5. Search by email

6. Create a contact (your first write)

7. Verify auth is enforced

Common pitfalls

Next steps