zxn.uk Chat API
REST, webhooks, MCP and A2A. Machine-readable: openapi.json · llms.txt
Authenticate with Authorization: Bearer zxc_live_… (create a key in the app, Settings, Developers).
MCP: https://chat.zxn.uk/mcp (Streamable HTTP) · A2A: https://chat.zxn.uk/a2a/{site_public_key}
Account
GET | /v1/me | The signed-in user and their workspaces |
GET | /v1/whoami | Who the credential is: a user, or an API key and its workspace and scopes |
PATCH | /v1/me | Update my profile |
POST | /v1/devices | Register a push device (upsert by token) |
DELETE | /v1/devices/{id} | Forget a push device |
Workspaces
POST | /v1/workspaces | Create a workspace (caller becomes owner) |
GET | /v1/workspaces/{ws} | Get a workspace |
PATCH | /v1/workspaces/{ws} | Rename a workspace |
DELETE | /v1/workspaces/{ws} | Delete a workspace (owner only) |
Team
GET | /v1/workspaces/{ws}/members | List members |
PATCH | /v1/workspaces/{ws}/members/me | My availability and notification settings |
PATCH | /v1/workspaces/{ws}/members/{user_id} | Change a member role |
DELETE | /v1/workspaces/{ws}/members/{user_id} | Remove a member (or leave) |
GET | /v1/workspaces/{ws}/invites | Pending invites |
POST | /v1/workspaces/{ws}/invites | Invite someone by email (sends a join link and code) |
POST | /v1/invites/accept | Accept an invite |
Sites
GET | /v1/workspaces/{ws}/sites | List sites sites:read |
POST | /v1/workspaces/{ws}/sites | Create a site (defaults filled) sites:write |
GET | /v1/workspaces/{ws}/sites/{site_id} | Get a site sites:read |
PATCH | /v1/workspaces/{ws}/sites/{site_id} | Update a site (any field except ids) sites:write |
DELETE | /v1/workspaces/{ws}/sites/{site_id} | Delete a site and its conversations sites:write |
GET | /v1/workspaces/{ws}/sites/{site_id}/install | Install snippet and links sites:read |
Conversations
GET | /v1/workspaces/{ws}/conversations | List conversations, newest activity first conversations:read |
GET | /v1/workspaces/{ws}/conversations/{cv} | Get a conversation conversations:read |
PATCH | /v1/workspaces/{ws}/conversations/{cv} | Change status, assignee or turn the AI off conversations:write |
POST | /v1/workspaces/{ws}/conversations/{cv}/read | Mark read up to a seq (for me) conversations:read |
POST | /v1/workspaces/{ws}/conversations/{cv}/typing | Tell the visitor you are typing conversations:write |
Messages
GET | /v1/workspaces/{ws}/conversations/{cv}/messages | Message history (newest last) or catch-up conversations:read |
POST | /v1/workspaces/{ws}/conversations/{cv}/messages | Send a reply or an internal note (idempotent on client_id). A reply turns the AI off. conversations:write |
AI
POST | /v1/workspaces/{ws}/conversations/{cv}/suggest | AI draft of the next reply conversations:read |
POST | /v1/workspaces/{ws}/conversations/{cv}/summary | AI two-line summary conversations:read |
Visitors
GET | /v1/workspaces/{ws}/visitors/{vis} | A visitor and their conversations conversations:read |
PATCH | /v1/workspaces/{ws}/visitors/{vis} | Edit a visitor name or email conversations:write |
Saved replies
GET | /v1/workspaces/{ws}/saved-replies | List saved replies conversations:read |
POST | /v1/workspaces/{ws}/saved-replies | Create a saved reply conversations:write |
PATCH | /v1/workspaces/{ws}/saved-replies/{id} | Edit a saved reply conversations:write |
DELETE | /v1/workspaces/{ws}/saved-replies/{id} | Delete a saved reply conversations:write |
Realtime
GET | /v1/workspaces/{ws}/events | Events since a seq (7-day window; 410 gone when older) conversations:read |
GET | /v1/workspaces/{ws}/socket | WebSocket upgrade (token and since in the query) |
Developers
GET | /v1/workspaces/{ws}/api-keys | List API keys |
POST | /v1/workspaces/{ws}/api-keys | Create an API key (secret shown once) |
DELETE | /v1/workspaces/{ws}/api-keys/{id} | Revoke an API key |
GET | /v1/workspaces/{ws}/webhooks | List webhooks |
POST | /v1/workspaces/{ws}/webhooks | Create a webhook (Standard Webhooks signing; secret shown once) |
PATCH | /v1/workspaces/{ws}/webhooks/{id} | Edit a webhook (re-activating resets the failure count) |
DELETE | /v1/workspaces/{ws}/webhooks/{id} | Delete a webhook |
POST | /v1/workspaces/{ws}/webhooks/{id}/test | Send a ping |
Widget
GET | /v1/widget/config | Public site appearance and availability |
POST | /v1/widget/session | Start or resume a visitor session |
POST | /v1/widget/messages | Send a visitor message (creates the conversation on the first one; idempotent on client_id) |
GET | /v1/widget/messages | Poll fallback: messages after a seq |
POST | /v1/widget/typing | Visitor typing indicator |
POST | /v1/widget/identify | Attach name, email and custom attributes to the visitor |
POST | /v1/widget/handoff | Ask for a person (AI stops, team is notified) |
POST | /v1/widget/rating | Rate the conversation 1-5 |
DELETE | /v1/widget/conversation | The visitor deletes their conversation |
GET | /v1/widget/socket | Visitor WebSocket (site and visitor_token in the query) |