Overview
The public HTTP API is URL-versioned under `/api/v1`. Breaking changes ship in a new version. Responses for resources go through typed API Resources, never raw Eloquent models.
Errors use RFC 7807 `application/problem+json` with `type`, `title`, `status`, `detail`, and `traceId`. Correlate with the `X-Request-Id` response header.
Conventions
Base path `/api/v1`
Version in the URL
Cursor pagination
`?cursor=...&limit=50`
Idempotency-Key on writes
UUIDv4, 24h dedupe window
JSON request/response bodies
Accept application/json
Common patterns
List with cursor
Follow `meta.nextCursor` while `meta.hasMore` is true. Do not invent offset pagination clients.
GET /api/v1/<resource>?limit=50&cursor=<opaque>
Handle problem+json
On 4xx/5xx, parse the problem document. Surface `title`/`detail` to operators; keep `traceId` for support tickets.
{
"type": "https://...",
"title": "Validation failed",
"status": 422,
"detail": "...",
"traceId": "..."
}Idempotent create
Generate a new UUIDv4 per logical operation. Retry transport failures with the same key; start a new key for a new logical create.
Start a flow for a contact
Send a published flow to one contact from your store, a form or Zapier. It runs in the contact's latest conversation; `variables` reach the flow as `{{ trigger.variables.name }}`.
POST /api/v1/workspaces/<workspace>/automations/<id>/start
{ "contact_id": "<contact id>", "variables": { "coupon": "WELCOME10" } }Keep a token narrow
A token can be limited to contacts or to the inbox. Give an integration only what it needs; `GET /api/v1/auth/me` answers every token, for a connection test.
Scope notes
Note
What the API covers
Workspace-scoped product resources (contacts, automations, inbox-related reads/writes as exposed, billing reads where permitted, etc.). Exact resource matrices expand with the product: treat Help + this reference as the contract surface.
Tip
Playbooks vs API
Comment-to-DM and creator growth recipes are Help playbooks. Use the API when your store or middleware needs to upsert contacts or kick off automations programmatically.
Was this guide helpful?
Browse more in the library
Ready to put this
into practice?
Start building your first automation for free. No credit card required. Just connect your channel and launch in minutes.