> ## Documentation Index
> Fetch the complete documentation index at: https://klipy.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Use the Klipy v2 API to manage every core CRM object — contacts, companies, deals, pipelines, tasks, notes, segments, interactions, meetings, recordings, and bookings.

The Klipy v2 API is served at **`https://api.klipy.ai/api/v2`**. It covers the full CRM object model — contacts, companies, deals, pipelines, tasks, notes, segments, and interactions are fully readable and writable; meetings, recordings, and bookings are read-only, since they're sourced from calendar and call-recording integrations rather than created directly through the API.

<Note>
  New to the Klipy API? Start here. If you're integrating against v1, see [Migrating from v1](/api/v2/migrating-from-v1) for what changed.
</Note>

## Envelope format

Every response is wrapped in a JSON envelope with an `object` field that tells you what shape to expect:

| `object`  | Used for                    | Shape                                                                                           |
| --------- | --------------------------- | ----------------------------------------------------------------------------------------------- |
| `success` | Get, create, update, upsert | `{ object, data, meta }` — `data` is the resource                                               |
| `list`    | List endpoints              | `{ object, data, page_info, meta }` — `data` is an array, `page_info` carries cursor pagination |
| `batch`   | Batch-create endpoints      | `{ object, data: { items, summary }, meta }` — see [Batch operations](#batch-operations) below  |
| `error`   | Any 4xx/5xx response        | `{ object, error: { code, message, details }, meta }`                                           |

List endpoints paginate with a cursor: pass `?cursor=` from the previous response's `page_info.end_cursor`, and check `page_info.has_next_page` to know when to stop.

## Authentication

Create and manage API keys in the Klipy app under **[Settings → API](https://app.klipy.ai/settings/api)**.

Send the key on every request using **one** of:

* **Header:** `X-Klipy-Api-Key: <key>`
* **Bearer:** `Authorization: Bearer <key>`

v2 keys use the format `klipy_live_<random>`. The full key is shown **once**, at creation or rotation — Klipy stores only a hash, never the raw secret. See [Issuing API keys](/api/v2/issuing-api-keys) for the full lifecycle (rotation, revocation, access levels).

<Warning>
  v2 keys are a different format from v1's `klipy_pk_<id>` keys and are **not interchangeable**. A v1 key will not authenticate against `/api/v2/*`, and vice versa.
</Warning>

## Scopes

Every v2 key is issued with an explicit set of scopes chosen at creation — there is no `ALL` scope, and no implicit full access. Each endpoint documents its required scope as `x-required-scope` in the OpenAPI spec. Scopes follow a `resource:action` pattern, for example `contacts:read`, `deals:write`, `tasks:delete`.

Two access levels, chosen when the key is created:

* **Organization-wide** — the key can read and write any record in the organization.
* **User-bound** — the key is bound to one user and scoped to that user's own records (their notes, their owned deals, and so on). A user-bound key cannot see or modify another user's data, even within the same organization.

If a request is missing a required scope, the API returns `403`. A missing, invalid, revoked, or expired key returns `401`.

## Rate limits

Limits apply **per API key** and **per organization**:

* **200** requests per minute per key
* **1000** requests per minute per organization

Successful responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`. Exceeding a limit returns `429` with a `Retry-After` header.

## Idempotency

Every `POST` and `PATCH` request accepts an optional `Idempotency-Key` header. If you send the same key with the same request body twice, the second call returns the identical cached response — the request is not re-executed, and it does not count against your rate limit.

Sending the same key with a **different** body is treated as an error (`422`) — reusing a key for a different request usually indicates a client-side bug, such as an ID that changed between retries.

```bash theme={null}
curl https://api.klipy.ai/api/v2/contacts \
  -X POST \
  -H "X-Klipy-Api-Key: <key>" \
  -H "Idempotency-Key: 8f14e45f-ceea-4b0a-9127-1e2e3c3c1a1a" \
  -H "Content-Type: application/json" \
  -d '{"email": "person@example.com"}'
```

Retrying the request above with the same `Idempotency-Key` — even after a network timeout — is always safe.

## Batch operations

Resources that support creation also support batch-create: `POST /{resource}/batch` with a JSON array of up to 100 items.

Batch is **not atomic** — each item is created independently, so a validation failure on one item doesn't affect the others. The response is always `200`, with per-item results and a summary:

```json theme={null}
{
  "object": "batch",
  "data": {
    "items": [
      { "index": 0, "status": "created", "data": { "id": "...", "email": "a@example.com" } },
      { "index": 1, "status": "error", "error": { "code": "VALIDATION_FAILED", "message": "email is required." } }
    ],
    "summary": { "total": 2, "succeeded": 1, "failed": 1 }
  },
  "meta": { "request_id": "..." }
}
```

Check `summary.failed` — a `200` status does not mean every item succeeded. Batch honors `Idempotency-Key` the same way single-item writes do.

## Relationship sub-resources

Some resources expose relationships as sub-paths:

* **Collections** (`deals/{id}/contacts`, `deals/{id}/companies`, `notes/{id}/records`, `segments/{id}/members`) — `GET` to list, `POST` to link an existing record, `DELETE .../{child_id}` to unlink. A deal or note can be linked to many contacts, companies, or records.
* **Single associations** (`meetings/{id}/deal`, `meetings/{id}/company`) — `GET` to read (`data` is `null` if unset), `PUT` to set, `DELETE` to clear. A meeting has at most one associated deal and one associated company.

## Resources

See the sidebar for the full set of resources and operations. In brief:

| Resource                                 | Operations                                                                                 |
| ---------------------------------------- | ------------------------------------------------------------------------------------------ |
| Contacts, Companies                      | Full CRUD, batch-create                                                                    |
| Deals, Pipelines, Tasks, Notes, Segments | Full CRUD, batch-create; Deals, Notes, and Segments also expose relationship sub-resources |
| Interactions                             | Read, create, batch-create (no update or delete)                                           |
| Meetings                                 | Read-only, plus deal/company association                                                   |
| Recordings, Bookings                     | Read-only                                                                                  |

<Note>
  Production base URL: `https://api.klipy.ai/api/v2`. Always use HTTPS.
</Note>

## Related topics

* [Issuing API keys](/api/v2/issuing-api-keys) — create, rotate, and revoke v2 keys.
* [Migrating from v1](/api/v2/migrating-from-v1) — what changed, and how to move existing integrations over.