The KaryaFlow API is a REST API over HTTPS. Every request must be authenticated with a workspace API key passed in the Authorization: Bearer <key> header. All responses are JSON. Timestamps are ISO 8601 in UTC.
Base URL
https://api.karyaflow.com/v1
Authentication
Create workspace API keys from Settings → Developers. Keys are scoped to a single workspace and inherit the role of the user who created them. Rotate keys from the same screen; revoke at any time.
Rate limits
- 600 requests per minute per workspace on the Starter tier.
- 2,000 requests per minute per workspace on Growth.
- Custom limits on Enterprise (typically 10,000+ req/min).
Rate-limited responses return HTTP 429 with a Retry-After header in seconds and the X-RateLimit-Remaining header on every response.
Endpoints
Contacts
GET /v1/contacts— list with cursor pagination.POST /v1/contacts— create a contact.GET /v1/contacts/{id}— fetch by id.PATCH /v1/contacts/{id}— partial update.DELETE /v1/contacts/{id}— soft-delete.
Deals
GET /v1/deals— list with stage, owner, andclose_datefilters.POST /v1/deals— create a deal on a pipeline.PATCH /v1/deals/{id}— update stage, amount, or close-date.
Agents
POST /v1/agents/{id}/run— invoke an agent with a JSON payload. Returns the run id.GET /v1/agents/{id}/runs/{run_id}— fetch run status, logs, and output.
Webhooks
Webhooks fire on record events (contact.created, deal.updated, ticket.resolved) and on agent lifecycle events (agent.run.started, agent.run.completed, agent.run.failed). The full event list is published with the Enterprise GA.
Every webhook payload is signed with HMAC-SHA256. Verify the KaryaFlow-Signature header against the signature field in the request body using the secret from your webhook endpoint settings. Reject any payload whose timestamp is more than 5 minutes off to prevent replay.
SDKs
First-party TypeScript and Python SDKs are published on npm (@karyaflow/sdk) and PyPI (karyaflow). Both wrap the REST API and expose typed resources for contacts, deals, tickets, and agent runs.