OpenAPI reference

KasaDESK Public API · version 1.0.0 · OpenAPI 3.1.0.Download the OpenAPI JSON. For keys, rate limits, signature verification and examples, read Developer API, webhooks and customer records.

Overview

Bearer-token API for integrations. Each API key is scoped to one or more workspaces and to read and/or write. Resources outside the key’s workspaces return 404. Internal notes are never exposed. Staff session cookies are not accepted.

ItemValue
Base URLhttps://support.example.com/api/v1/public-api (example origin; replace with your installation’s origin)
AuthenticationbearerAuth: HTTP bearer — API key beginning with kd_live_, created in Admin > Settings > Developer

Endpoints

MethodPathSummary
GET/meDescribe the calling API key
GET/conversationsList conversations in the key’s workspaces
GET/conversations/{id}Get one conversation
GET/conversations/{id}/messagesList public messages (internal notes are never included)
POST/conversations/{id}/repliesSend a public reply through the conversation’s origin channel
GET/customersList customers in the key’s workspaces

GET /me

Describe the calling API key.

StatusMeaningBody
200Key detailsApiKeyInfo
401Missing, invalid, expired or revoked API keyError
429Rate limit exceededError

GET /conversations

List conversations in the key’s workspaces. Requires the read scope.

ParameterInTypeNotes
limitqueryinteger default 25, min 1, max 100
cursorquerystringOpaque cursor from a previous page
workspaceIdquerystring (uuid)Narrow to one of the key’s workspaces. Other ids return an empty list.
lifecyclequery"open" | "pending" | "resolved"
referencequerystringExact conversation reference, case-insensitive and with an optional # prefix
StatusMeaningBody
200A page of conversations, newest activity firstobject
401Missing, invalid, expired or revoked API keyError
403Key lacks the read scopeError
429Rate limit exceededError

GET /conversations/{id}

Get one conversation. Requires the read scope.

ParameterInTypeNotes
id requiredpathstring (uuid)
StatusMeaningBody
200The conversationobject
401Missing, invalid, expired or revoked API keyError
404Not found or outside the key’s workspacesError
429Rate limit exceededError

GET /conversations/{id}/messages

List public messages (internal notes are never included). Requires the read scope.

ParameterInTypeNotes
id requiredpathstring (uuid)
limitqueryinteger default 200, min 1, max 500
StatusMeaningBody
200Messages, oldest firstobject
401Missing, invalid, expired or revoked API keyError
404Not found or outside the key’s workspacesError
429Rate limit exceededError

POST /conversations/{id}/replies

Send a public reply through the conversation’s origin channel. Requires the write scope.

The reply is sent through the conversation’s own channel (for email, via the outbox with retries). Channels without an outbound adapter return 409 channel_outbound_unavailable. Repeating an idempotency key returns the original message.

ParameterInTypeNotes
id requiredpathstring (uuid)
Idempotency-KeyheaderstringAlternative to the body field min length 8, max length 100

Request body (application/json): ReplyInput

StatusMeaningBody
200Duplicate idempotency key; original message returnedReplyResult
201Reply acceptedReplyResult
401Missing, invalid, expired or revoked API keyError
403Key lacks the write scopeError
404Not found or outside the key’s workspacesError
409Channel cannot send repliesError
422Validation failedError
429Rate limit exceededError

GET /customers

List customers in the key’s workspaces. Requires the read scope.

ParameterInTypeNotes
limitqueryinteger default 25, min 1, max 100
cursorquerystringOpaque cursor from a previous page
workspaceIdquerystring (uuid)Narrow to one of the key’s workspaces. Other ids return an empty list.
emailquerystringExact, case-insensitive match
StatusMeaningBody
200A page of customersobject
401Missing, invalid, expired or revoked API keyError
403Key lacks the read scopeError
429Rate limit exceededError

Webhook events

Signed with HMAC-SHA256 over {X-KasaDesk-Timestamp}.{raw body} using the endpoint signing secret. X-KasaDesk-Signature holds v1=<hex> (two comma-separated values during a secret rotation grace period; accept either). Reject timestamps older than 5 minutes. Deduplicate on X-KasaDesk-Event-Id (stable across retries). Respond 2xx within 10 seconds; other responses are retried with backoff, and the endpoint is disabled after repeated consecutive failures. Redirects are not followed.

HeaderNotes
X-KasaDesk-Signature Example: v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
X-KasaDesk-TimestampUnix seconds
X-KasaDesk-Event-Id
X-KasaDesk-Event-Type
X-KasaDesk-Delivery-Id
  • conversation.created
  • conversation.reopened
  • conversation.status
  • conversation.priority
  • conversation.assigned
  • conversation.unassigned
  • conversation.moved
  • conversation.escalated
  • conversation.human_takeover
  • conversation.ai_resumed
  • message.created
  • message.delivery
  • webhook.test

Schemas

Error

FieldTypeNotes
error requiredobject

ApiKeyInfo

FieldTypeNotes
id requiredstring (uuid)
name requiredstring
scopes required"read" | "write"[]
workspaceIds requiredstring (uuid)[]

Conversation

FieldTypeNotes
id requiredstring (uuid)
referencestringStable short record reference
subjectstring | null
lifecycle required"open" | "pending" | "resolved"
handler required"ai" | "human" | "queued"
priority required"low" | "normal" | "high" | "urgent"
workspace requiredobject
workgroup requiredobject
channel requiredobject
customer requiredobject
assigneenull | object
lastMessagePreviewstring | null
lastMessageAtstring | null
createdAt requiredstring (date-time)
slaDueAtstring | null

Message

FieldTypeNotes
id requiredstring (uuid)
referencestringStable short record reference
conversationId requiredstring (uuid)
conversationReferencestringStable short record reference
authorType required"customer" | "agent" | "ai" | "system"
authorNamestring | null
body requiredstring
deliveryStatus required"none" | "queued" | "sending" | "accepted" | "delivered" | "read" | "failed"
createdAt requiredstring (date-time)
attachments requiredobject[]

Customer

FieldTypeNotes
id requiredstring (uuid)
referencestringStable short record reference
workspaceId requiredstring (uuid)
workspaceReferencestringStable short record reference
namestring | null
emailstring | null
phonestring | null
verification required"guest" | "unverified" | "verified"
createdAt requiredstring (date-time)

ReplyInput

FieldTypeNotes
body requiredstring min length 1, max length 20000
idempotencyKeystring min length 8, max length 100

ReplyResult

FieldTypeNotes
data requiredobject

WebhookEvent

FieldTypeNotes
id requiredstringStable event id (evt_…); identical on every retry
type required"conversation.created" | "conversation.reopened" | "conversation.status" | "conversation.priority" | "conversation.assigned" | "conversation.unassigned" | "conversation.moved" | "conversation.escalated" | "conversation.human_takeover" | "conversation.ai_resumed" | "message.created" | "message.delivery"
createdAt requiredstring (date-time)
workspaceId requiredstring (uuid)
workspaceReferencestringStable short record reference
data requiredobject

WebhookTestEvent

FieldTypeNotes
id requiredstring
type required
createdAt requiredstring (date-time)
workspaceId requiredstring (uuid)
data requiredobject