Skip to main content
Every change to the public API contract lands here — new endpoints and fields the day they ship, and the rare in-place correction before it has real usage. Subscribe your integration to tolerance, and this page to awareness.
​
Free-trial access, per-second limits, and 403s that say what to do
  • The API is open during the free trial. A trial organization gets every endpoint, on a smaller budget, so an integration can be built and tested before paying.
  • Rate limits are now per second: 20 requests/second on Scale, 5 requests/second during the trial, shared across the organization’s keys. The X-RateLimit-* headers are unchanged; Retry-After on a 429 is now always 1.
  • GET /v1/me gains trial (boolean) — true while the organization is on its free trial. plan now reports the real plan code rather than always "scale".
  • Clearer 403s. scale_plan_required now means only “a live plan below Scale — upgrade”. Two new details cover the rest: trial_expired (the trial ended without a payment method) and subscription_required (canceled, or suspended for non-payment). See Authentication.
​
WhatsApp templates, sends, and broadcasts
The API can now send.
  • WhatsApp templates — list, read, create, delete (/v1/templates). Creating a template also submits it to Meta for approval in the same call, so it comes back PENDING; poll it until Meta flips it to APPROVED or REJECTED.
  • GET /v1/templates/{id}/send-requirements — what a template needs filled before it can be sent: the variable tokens, which of them resolve from the contact on their own, catalog slots, dynamic URL buttons, media surfaces, and a reason when a template can never be sent at all. Read this before your first send rather than discovering it through 422s.
  • POST /v1/templates/{id}/send — up to 100 recipients in one call, each addressed by contact_id or phone and carrying its own variables, url_suffixes, coupon_code, lto_expiration and media. recipients takes a single object or an array — sending to one person needs no wrapping. Media headers take a public URL (header_media_url / card_media_urls), fetched server-side. Returns 202 and the broadcast it created.
    • A phone that matches no contact creates one, so a send can grow your CRM.
    • Send Idempotency-Key and a retry is safe: the same key returns the original broadcast for 24 hours instead of sending again.
    • The request is refused whole — nothing queued, nothing charged — if a variable is missing, a key is one the template does not use, a media URL cannot be fetched, or the batch exceeds what is left of WhatsApp’s rolling 24-hour messaging limit.
  • Broadcasts — GET /v1/broadcasts and GET /v1/broadcasts/{id} for progress (sent / failed / pending always sum to requested), GET /v1/broadcasts/{id}/recipients for per-recipient outcomes, and POST /v1/broadcasts/{id}/cancel to abandon the un-sent remainder. Messages already accepted by WhatsApp cannot be recalled.
  • GET /v1/channels/whatsapp/phones — the connected numbers a send can go out from, so channel_id is discoverable. Optional when your WhatsApp account has exactly one number; required when it has more.
​
v1 launch
The first public surface of the Ciarem API:
  • Contacts — full CRUD (/v1/contacts).
  • CRM metadata — properties and funnel stages, full CRUD (/v1/properties, /v1/funnel-stages).
  • Conversations — read-only history (/v1/conversations), each message carrying a sender of contact, agent, ai, or system.
  • /v1/me — organization identity, plan, timezone, and language.
  • Organization-bound oak_ API keys, 60 requests/minute per organization.