Skip to main content
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.
New to the Klipy API? Start here. If you’re integrating against v1, see Migrating from v1 for what changed.

​
Envelope format

Every response is wrapped in a JSON envelope with an object field that tells you what shape to expect:
objectUsed forShape
successGet, create, update, upsert{ object, data, meta } — data is the resource
listList endpoints{ object, data, page_info, meta } — data is an array, page_info carries cursor pagination
batchBatch-create endpoints{ object, data: { items, summary }, meta } — see Batch operations below
errorAny 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. 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 for the full lifecycle (rotation, revocation, access levels).
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.

​
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. 
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: 
{
  "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:
ResourceOperations
Contacts, CompaniesFull CRUD, batch-create
Deals, Pipelines, Tasks, Notes, SegmentsFull CRUD, batch-create; Deals, Notes, and Segments also expose relationship sub-resources
InteractionsRead, create, batch-create (no update or delete)
MeetingsRead-only, plus deal/company association
Recordings, BookingsRead-only
Production base URL: https://api.klipy.ai/api/v2. Always use HTTPS.
Last modified on July 7, 2026