API Reference

All paths below are relative to the base URL:

https://api.<your-domain>/api/v1

Every endpoint requires an API key with the scope shown in its row (see API keys). List endpoints accept limit (1–100, default 25) and cursor and return { items, nextCursor } — see Pagination. Write endpoints (POST, PATCH) accept an optional Idempotency-Key header — see the overview.

The full machine-readable contract, including every request and response schema, is in the public OpenAPI document at GET /openapi.json (no key needed).

Conversations

Method	Path	Scope	Description
`GET`	`/conversations`	`conversations:read`	List conversations, newest first. Filters: `state`, `channel`, `contactId`.
`GET`	`/conversations/{id}`	`conversations:read`	Get one conversation.
`GET`	`/conversations/{id}/messages`	`conversations:read`	List the messages of a conversation, newest first. Drafts and unreleased assistant output are not included.
`POST`	`/conversations/{id}/messages`	`conversations:write`	Send a text message into the conversation.
`POST`	`/conversations/{id}/handoff`	`conversations:write`	Hand the conversation to a human agent (creates an escalation).
`POST`	`/conversations/{id}/resume-bot`	`conversations:write`	Give the conversation back to the assistant after a handoff.

Send a message — body:

{
  "text": "Your order has shipped.",
  "clientMsgId": "my-id-42"
}

text is required (1–4096 characters). clientMsgId is optional: your own identifier for the message — the same value never sends twice, which makes retries safe even without an Idempotency-Key. The response is { "messages": [...] } with the created message(s).

Handoff — body (all fields optional):

{
  "note": "Customer asked about a refund",
  "priority": "high",
  "notifyCustomer": true
}

notifyCustomer defaults to true and sends the configured handoff message to the customer. The response contains the updated conversation and an escalationId.

Resume bot — body:

{ "followUpNow": true }

followUpNow defaults to false. When true, the assistant answers the customer's last message right away instead of waiting for the next one.

Contacts

Method	Path	Scope	Description
`GET`	`/contacts`	`contacts:read`	List contacts, newest first. Filters: `q` (name or phone search), `channel`.

Products

Method	Path	Scope	Description
`GET`	`/products`	`products:read`	List products. Filters: `q` (text search), `status` (`active`, `draft`, `hidden_from_bot`, `archived`), `stock` (`in_stock`, `out_of_stock`).
`PUT`	`/products/{sku}`	`products:write`	Create the product with this SKU (`201`) or update the one that has it (`200`).
`PATCH`	`/products/{sku}/stock`	`products:write`	Update stock for the SKU.

Create or update a product — PUT /products/{sku} upserts by SKU, which makes it ideal for catalog sync from an ERP or a store platform. Body (send only the fields you want to write; at least one):

{
  "titleAr": "عباية صيفية",
  "titleEn": "Summer abaya",
  "descriptionAr": null,
  "descriptionEn": null,
  "category": "Abayas",
  "brand": "Dar Noor",
  "tags": ["summer", "new"],
  "url": "https://shop.example.com/p/abaya-123",
  "status": "active",
  "priceMinor": 24900,
  "currency": "SAR",
  "stock": 12
}

priceMinor is an integer in the currency's minor units and is required when the SKU is new. Nullable fields (titleAr, descriptionEn, url, stock, ...) accept null to clear the value; stock: null means stock is not tracked.

Update stock — body:

{ "stock": 7, "stockPolicy": "track" }

stock is required (an integer, or null for "not tracked"); stockPolicy is optional.

Orders

Method	Path	Scope	Description
`GET`	`/orders`	`orders:read`	List orders, newest first. Filters: `status`, `channel`, `contactId`, `conversationId`.

Order amounts (totalMinor) are integers in minor units with a currency code.

Usage

Method	Path	Scope	Description
`GET`	`/usage`	`usage:read`	The workspace's plan, the current billing period, resource limits and what is used so far.

Response shape:

{
  "plan": "growth",
  "periodStart": "2026-10-01T00:00:00.000Z",
  "periodEnd": "2026-11-01T00:00:00.000Z",
  "limits": { "products": 1000, "seats": 5 },
  "used": { "products": 412, "seats": 3 }
}