The public REST API
Read and write CRM data from your own scripts and services: API keys, scopes, pagination, rate limits, and a working curl example.
Ikigai CRM ships a workspace-scoped REST API under /api/v1. Everything the API returns belongs to your workspace only, and every request must carry an API key.
Create an API key
- Open Settings → API keys («API-ключи» / «API-ключі» in the localized interface). This page is available to workspace admins.
- Click Create key and give it a name (for example, "Reporting script").
- Pick an access mode:
- Acts as user — the key inherits the role permissions of a service user you select.
- Advanced: scopes — you pick exactly what the key may do, with Read-only and Read & write presets.
- Optionally set an expiry: 30 days, 90 days, no expiry, or pick an exact date with Pick a date.
The full key (it starts with sk_) is shown exactly once — copy it into your secret manager right away. Only a SHA-256 hash is stored on our side. You can later Rotate a key: a new value is issued and the old one keeps working for 24 hours, so deploys don't break mid-rotation.
Authenticate
Send the key as a bearer token on every request:
curl -s "https://api.example.com/api/v1/deals?status=open&limit=10" \
-H "Authorization: Bearer sk_your_key_here"
A missing, expired, or revoked key returns 401. A key that lacks the scope for an action (for example deal.read) returns 403.
What you can read
| Endpoint | Returns |
|---|---|
GET /api/v1/deals | Deals, filterable by pipelineId, stageId, ownerId, status (open / won / lost), tag, source, amountMin / amountMax, updatedWithinDays |
GET /api/v1/contacts | Contacts (list of basic fields). Emails and phones are returned by GET /contacts/{id} (the identifiers array) or GET /contacts/lookup |
GET /api/v1/companies | Companies |
GET /api/v1/pipelines | Pipelines; /pipelines/{id}/summary adds per-stage deal count and value |
GET /api/v1/tasks, /users, /teams, /workspace | Tasks, team members, teams, workspace info |
GET /api/v1/search?q=… | Cross-object search (deals, contacts, companies, tasks, notes) |
GET /api/v1/records/{type}/{id}/timeline | The timeline of one record |
Writes
The API is not read-only. Behind write scopes (deal.write, contact.write, …) you can create and update contacts, companies, and deals, move deal stages, add notes and tags, manage tasks, and run bulk deal operations. A deal created through the API fires the same automation events as one created in the UI.
Pagination and response shape
Single objects arrive as { "data": … }; collections as { "data": [...], "next": "cursor-or-null" }. Pass next back as the cursor query parameter to fetch the following page. limit accepts 1–100 (default 50).
Rate limits
Read endpoints allow 600 requests per minute; write endpoints allow 120 per minute. The bucket is per key per endpoint (the path is part of the counter), so hammering one endpoint does not starve the others.
Self-describing docs
The API publishes an OpenAPI 3.1 document at /api/v1/openapi.json and an interactive explorer at /api/v1/docs.
Never embed an API key in browser-side code — keys are server credentials. For website forms, use lead webhooks instead.
Was this article helpful?