Cliedesk REST API Reference (v1)

Basics

Every request goes to your own site:

https://your-site.com/wp-json/cliedesk-api/v1

Version 1 only ever grows: fields and endpoints are added, never removed or changed without notice. Deprecations are announced 12 months ahead. Current revision: 1.0.0 (rev 2026-10-19).

Authentication

Create an API key in Cliedesk under Settings → Developer → API keys and send it as a Bearer token, or in the X-Cliedesk-Key header. Apps that act for a person use OAuth 2 with PKCE. A key never has more rights than its owner, and it only reaches the products it is limited to.

curl https://your-site.com/wp-json/cliedesk-api/v1/conversations \
  -H "Authorization: Bearer cdk_live_…"

The API guide covers keys, OAuth, pagination, filters, errors, rate costs and idempotency.

Scopes

Scope	Allows
`conversations:read`	List and read conversations, views and their events.
`conversations:write`	Create and change conversations: status, priority, assignment, merge, split, snooze, spam, bulk changes.
`conversations:delete`	Move conversations to Trash and restore them.
`messages:read`	Read messages of conversations.
`messages:write`	Send replies and record messages.
`notes:write`	Add internal notes.
`contacts:read`	List and read contacts and their timeline.
`contacts:write`	Create, change and merge contacts.
`contacts:delete`	Move contacts to Trash.
`organizations:read`	List and read organizations.
`organizations:write`	Create, change and delete organizations and their members.
`workspace:read`	Read products, brands, teams, fields and statuses.
`tags:read`	List tags.
`tags:write`	Create, change and delete tags and tag conversations.
`saved_replies:read`	List, read and render saved replies.
`saved_replies:write`	Create, change and delete saved replies.
`articles:read`	Search and read help-center articles.
`approvals:read`	Read approval requests (never decide them).
`events:read`	Read the changed-since sync feed and timelines.
`reports:read`	Read report metrics.
`channels:write`	Post events of custom channels (messages, receipts, typing).
`webhooks:read`	Read webhook subscriptions and their deliveries.
`webhooks:write`	Create, change, test and delete webhook subscriptions and replay deliveries.
`mcp:read`	Use the MCP server with read-only tools.
`mcp:write`	Use the MCP server with tools that change things (within your rights; some need approval).
`customer:read`	Customers only: see your own orders and support requests.
`customer:write`	Customers only: open support requests and write messages in them.
`audit:read`	Read the audit log, check its hash chain and read the read-access log.
`surveys:read`	Read surveys and survey responses (CSAT, NPS, CES, microsurveys).
`surveys:write`	Create surveys and write survey responses from other survey tools.
`ai:read`	Read AI agent profiles and playbooks (metadata) and receive AI events.
`ai:read_traces`	Read redacted AI traces (sensitive: the key owner needs the right to view AI traces).
`ai_agent:read`	Read the AI agent's answers to messages this key sent.
`ai_agent:write`	Send customer messages to the AI agent, run playbooks and escalate to people.
`events:write`	Record custom customer events.
`records:read`	List and read custom records and their types.
`records:write`	Create, change and delete custom records.
`access:read`	Read customers' product access records and their history.
`access:write`	Grant, change and revoke product access and import access records.
`commerce:read`	Read orders, subscriptions and the other commerce records of customers.
`commerce:write`	Run commerce actions (refunds, cancellations, coupons, subscription changes) under the commerce guardrails; some need approval.

REST API reference

Basics

Authentication

Scopes