​

Introduction

The Klipy REST API is version v1 and is served at https://api.klipy.ai/api/v1. Use it to integrate Klipy with your data warehouse, internal tools, or automation—create and query people, companies, and interactions with the same records you see in the Klipy app. All successful responses use a consistent JSON envelope (object, data, meta). List endpoints return pagination via page_info (cursor-based). Errors return a structured body with a machine-readable code, human-readable message, and optional details.

​

Endpoints

​

Authentication

• Authenticate — GET /authenticate — Validate your API key and return your organization name.

​

People

• Get person — GET /people/{personId}
• Query people — POST /people/query
• Create person — POST /people
• Upsert person — PUT /people
• Update person — PATCH /people/{personId}
• Delete person — DELETE /people/{personId}

​

Companies

• Get company — GET /companies/{companyId}
• Create company — POST /companies
• Update company — PATCH /companies/{companyId}
• Delete company — DELETE /companies/{companyId}

​

Interactions

• Get interaction — GET /interactions/{interactionId}
• Query interactions — POST /interactions/query
• Create interaction — POST /interactions

​

Common use cases

• Sync CRM data — Pull or push people and companies on a schedule using Query people, Query interactions, and the create/update endpoints.
• Enrich workflows — Log meetings, emails, and touchpoints with Create interaction so your team sees a full timeline in Klipy.
• Health checks — Use Authenticate to verify keys and org context before batch jobs run.

​

Authentication

Create and revoke 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>

Keys use the format klipy_api_<id>. Treat them as secrets for server-side use only—do not embed them in public clients or front-end code.

​

Scopes

Each key is issued with a set of scopes. Every endpoint requires a matching scope (see x-required-scope on each operation in the OpenAPI spec). Supported scopes: If the key is missing, invalid, or lacks scope, the API returns 401 or 403 with a stable error code in the response body.

​

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. When you exceed a limit, the API returns 429 with a Retry-After header.

​

Related topics

• Getting started — Overview of the Klipy product (web app).

Maintainers: internal standards for updating openapi.json and navigation live in docs/api/CONTRIBUTING.md in the klipy-app repository.