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

# Quickstart

> Make your first request to the Clarky API in under 2 minutes

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.

<Info>
  **Plan availability:** Standard, Pro, or Enterprise. See [Plans & Billing](/features/settings/plans).
</Info>

## 1. Create an API key

<Steps>
  <Step title="Open Settings → API Keys">
    From the admin dashboard, click **Settings**, then choose **API Keys** under the Workspace section.
  </Step>

  <Step title="Click 'New API Key'">
    Give it a memorable name (e.g. "Local testing"). The full key is shown **only once** — copy it immediately.
  </Step>

  <Step title="Save the key">
    Store it somewhere safe. If you lose it, revoke it and create a new one.
  </Step>
</Steps>

## 2. Set the key as a shell variable

This keeps the key out of your shell history and makes the examples below copy-pasteable.

<CodeGroup>
  ```bash macOS / Linux theme={null}
  export CLARKY_KEY='ck_live_paste_your_key_here'
  ```

  ```powershell Windows (PowerShell) theme={null}
  $env:CLARKY_KEY='ck_live_paste_your_key_here'
  ```
</CodeGroup>

## 3. List your contacts

Your first read. The list is automatically scoped to the workspace the key belongs to.

```bash theme={null}
curl -H "Authorization: Bearer $CLARKY_KEY" \
  "https://clarky.ai/api/v1/contacts?page=1&page_size=5"
```

Expected response shape:

```json theme={null}
{
  "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 }
}
```

<Tip>
  Pipe the response through `jq` for readable output: `curl ... | jq`. Install with `brew install jq` on macOS.
</Tip>

## 4. Get a single contact

Grab any `id` from the previous response and use it in the path:

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

<Tip>
  For idempotent imports use [`POST /api/v1/contacts/upsert`](/api-reference/contacts) — it dedupes on primary email or phone so you can re-run the same payload safely.
</Tip>

## 7. Verify auth is enforced

Sanity-check that the API rejects requests without a valid key:

```bash theme={null}
curl -i "https://clarky.ai/api/v1/contacts"
```

You should get back `HTTP/1.1 401 Unauthorized` with:

```json theme={null}
{ "error": { "code": "unauthorized", "message": "Missing or invalid API key" } }
```

## Common pitfalls

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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](/api-reference/rate-limits) for details.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Scopes, key rotation, security best practices
  </Card>

  <Card title="Pagination" icon="list" href="/api-reference/pagination">
    Walking large result sets
  </Card>

  <Card title="Rate Limits" icon="gauge-high" href="/api-reference/rate-limits">
    Per-key limits and retry behavior
  </Card>

  <Card title="Contacts" icon="address-book" href="/api-reference/contacts">
    Full Contacts endpoint reference
  </Card>
</CardGroup>