On this page Overview Endpoints GET /me GET /conversations GET /conversations/{id} GET /conversations/{id}/messages POST /conversations/{id}/replies GET /customers Webhook events Schemas 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.
Item Value Base URL https://support.example.com/api/v1/public-api (example origin; replace with your installation’s origin) Authentication bearerAuth: HTTP bearer — API key beginning with kd_live_, created in Admin > Settings > Developer
Endpoints GET /meDescribe the calling API key.
Status Meaning Body 200Key details ApiKeyInfo401Missing, invalid, expired or revoked API key Error429Rate limit exceeded Error
GET /conversationsList conversations in the key’s workspaces. Requires the read scope.
Parameter In Type Notes limitquery integer default 25, min 1, max 100 cursorquery stringOpaque cursor from a previous page workspaceIdquery string (uuid)Narrow to one of the key’s workspaces. Other ids return an empty list. lifecyclequery "open" | "pending" | "resolved"referencequery stringExact conversation reference, case-insensitive and with an optional # prefix
Status Meaning Body 200A page of conversations, newest activity first object401Missing, invalid, expired or revoked API key Error403Key lacks the read scope Error429Rate limit exceeded Error
GET /conversations/{id}Get one conversation. Requires the read scope.
Parameter In Type Notes id required path string (uuid)
Status Meaning Body 200The conversation object401Missing, invalid, expired or revoked API key Error404Not found or outside the key’s workspaces Error429Rate limit exceeded Error
GET /conversations/{id}/messagesList public messages (internal notes are never included). Requires the read scope.
Parameter In Type Notes id required path string (uuid)limitquery integer default 200, min 1, max 500
Status Meaning Body 200Messages, oldest first object401Missing, invalid, expired or revoked API key Error404Not found or outside the key’s workspaces Error429Rate limit exceeded Error
POST /conversations/{id}/repliesSend 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.
Parameter In Type Notes id required path string (uuid)Idempotency-Keyheader stringAlternative to the body field min length 8, max length 100
Request body (application/json): ReplyInput
Status Meaning Body 200Duplicate idempotency key; original message returned ReplyResult201Reply accepted ReplyResult401Missing, invalid, expired or revoked API key Error403Key lacks the write scope Error404Not found or outside the key’s workspaces Error409Channel cannot send replies Error422Validation failed Error429Rate limit exceeded Error
GET /customersList customers in the key’s workspaces. Requires the read scope.
Parameter In Type Notes limitquery integer default 25, min 1, max 100 cursorquery stringOpaque cursor from a previous page workspaceIdquery string (uuid)Narrow to one of the key’s workspaces. Other ids return an empty list. emailquery stringExact, case-insensitive match
Status Meaning Body 200A page of customers object401Missing, invalid, expired or revoked API key Error403Key lacks the read scope Error429Rate limit exceeded Error
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.
Header Notes X-KasaDesk-Signature Example: v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bdX-KasaDesk-TimestampUnix seconds X-KasaDesk-Event-IdX-KasaDesk-Event-TypeX-KasaDesk-Delivery-Id
conversation.createdconversation.reopenedconversation.statusconversation.priorityconversation.assignedconversation.unassignedconversation.movedconversation.escalatedconversation.human_takeoverconversation.ai_resumedmessage.createdmessage.deliverywebhook.testSchemas ErrorField Type Notes error required object
ApiKeyInfoField Type Notes id required string (uuid)name required stringscopes required "read" | "write"[]workspaceIds required string (uuid)[]
ConversationField Type Notes id required string (uuid)referencestringStable short record reference subjectstring | nulllifecycle required "open" | "pending" | "resolved"handler required "ai" | "human" | "queued"priority required "low" | "normal" | "high" | "urgent"workspace required objectworkgroup required objectchannel required objectcustomer required objectassigneenull | objectlastMessagePreviewstring | nulllastMessageAtstring | nullcreatedAt required string (date-time)slaDueAtstring | null
MessageField Type Notes id required string (uuid)referencestringStable short record reference conversationId required string (uuid)conversationReferencestringStable short record reference authorType required "customer" | "agent" | "ai" | "system"authorNamestring | nullbody required stringdeliveryStatus required "none" | "queued" | "sending" | "accepted" | "delivered" | "read" | "failed"createdAt required string (date-time)attachments required object[]
CustomerField Type Notes id required string (uuid)referencestringStable short record reference workspaceId required string (uuid)workspaceReferencestringStable short record reference namestring | nullemailstring | nullphonestring | nullverification required "guest" | "unverified" | "verified"createdAt required string (date-time)
Field Type Notes body required string min length 1, max length 20000 idempotencyKeystring min length 8, max length 100
ReplyResultField Type Notes data required object
WebhookEventField Type Notes id required stringStable 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 required string (date-time)workspaceId required string (uuid)workspaceReferencestringStable short record reference data required object
WebhookTestEventField Type Notes id required stringtype required createdAt required string (date-time)workspaceId required string (uuid)data required object