API reference
The essentials to call the Caryon Lead API from a script or a tool: authentication, resources, pagination, errors and limits.
The Caryon Lead API lets you read and write your companies, contacts, deals and actions from your own tools. It is included in the Business and Enterprise plans, and during the trial.
- Base URL:
https://api.caryon.app/lead/v1 - Full description (OpenAPI format, for your tools): https://api.caryon.app/lead/v1/openapi.json
Authentication
Create an API key and send it with every call:
Authorization: Bearer cyk_…The key acts for one workspace, with the rights of the role chosen; a read-only key cannot write.
Resources
| Resource | Access |
|---|---|
companies | read, write |
contacts | read, write |
deals | read, write |
actions | read, write |
exchanges (past exchanges) | read, write |
pipelines | read only |
users (members) | read only |
For each resource:
GET /resource: the list;GET /resource/:id: the detail;POST /resource: create;PATCH /resource/:id: update;POST /resource/:id/archiveandPOST /resource/:id/restore: archive and restore. Archiving takes an optional reason,{ "reason": "Duplicate" }(500 characters at most), shown in the Journal.
No deletion
The API never deletes anything: DELETE answers 405. Archive, and restore if needed. Lists hide archived items; add ?include_archived=true to see them.
If the member of the key linked their Google or CalDAV calendar, their meetings created, moved, canceled or archived through the API are carried over there as from Caryon Lead, invitations included if they turned them on.
Pagination
Lists are paginated by cursor. A response looks like { "data": [...], "next_cursor": "..." }: for the next page, send ?cursor=<next_cursor> back. next_cursor is null on the last page. limit sets the size of a page, from 1 to 100 (50 by default).
curl "https://api.caryon.app/lead/v1/contacts?limit=100&cursor=eyJ0Ijo…" \
-H "Authorization: Bearer cyk_…"Errors
An error always looks like this:
{ "error": { "code": "forbidden", "message": "…" } }| Code | HTTP | Meaning |
|---|---|---|
unauthorized | 401 | Key missing, invalid, expired or revoked |
plan_required | 403 | The workspace's plan does not include the API |
feature_disabled | 403 | An admin turned API keys off |
seat_required | 403 | The member has no Caryon Lead seat |
forbidden | 403 | The key's role does not allow this action |
rate_limited | 429 | Too many calls |
Limits
30 calls per minute and 5,000 per day per key. Beyond that, the API answers 429 with a Retry-After header: the number of seconds to wait.
Example
curl https://api.caryon.app/lead/v1/companies \
-H "Authorization: Bearer cyk_…"Every write is recorded in the Change log, "via the API key" used. To drive Caryon Lead in plain language rather than code, see Connect an AI agent.
A question not answered here? Write to us at contact@caryon.app.