Developer Documentation

Deskwoot REST API

Build integrations, automate workflows, and manage your entire Deskwoot account programmatically. All endpoints use JSON and return standard HTTP status codes.

Base URL: https://deskwoot.com/api/v1

Authentication

The Deskwoot API uses bearer token authentication. API tokens can be created in your account settings under Settings > API Tokens. API access requires the Enterprise plan.

Include your API token in the Authorization header of every request:

curl https://deskwoot.com/api/v1/accounts/{account_id}/contacts \
  -H "Authorization: Bearer dw_your_api_token_here" \
  -H "Content-Type: application/json"

Token format

All API tokens start with the prefix dw_ followed by 64 hex characters. Tokens are shown only once at creation time. Store them securely.

Scopes

Each token has one or more scopes that control which resources it can access. The broad read and write scopes cover all resources. Use narrow scopes for least-privilege access.

Parameter	Type	Required	Description
`read`	scope	Optional	Read access to all resources
`write`	scope	Optional	Write access to all resources
`contacts:read`	scope	Optional	Read contacts only
`contacts:write`	scope	Optional	Create and update contacts
`conversations:read`	scope	Optional	Read conversations and messages
`conversations:write`	scope	Optional	Update conversations and send messages

Errors

The API returns standard HTTP status codes. Errors include a JSON body with an error field describing the problem.

Parameter	Type	Required	Description
`200`	OK	Optional	Request succeeded
`201`	Created	Optional	Resource created
`400`	Bad Request	Optional	Invalid parameters or missing required fields
`401`	Unauthorized	Optional	Missing or invalid API token
`403`	Forbidden	Optional	Token lacks required scope or feature not available on your plan
`404`	Not Found	Optional	Resource does not exist
`409`	Conflict	Optional	Resource already exists (e.g. duplicate email)
`500`	Server Error	Optional	Unexpected error on our side

Error response example

{
  "error": "Label with this title already exists"
}

Conversations

GET/v1/conversations/{conversationId}

Retrieve a single conversation with its contact, inbox, assignee, team, labels, and messages.

Auth: Bearer token (conversations:read) or session

Response

{
  "id": "clx1abc...",
  "status": "OPEN",
  "priority": "MEDIUM",
  "inboxId": "clx2def...",
  "contactId": "clx3ghi...",
  "assigneeId": "clx4jkl...",
  "teamId": null,
  "muted": false,
  "lastActivityAt": "2026-03-14T10:30:00Z",
  "createdAt": "2026-03-13T08:00:00Z",
  "contact": { "id": "...", "name": "Lisa", "email": "lisa@example.com" },
  "inbox": { "id": "...", "name": "Live Chat", "channelType": "WEB" },
  "assignee": { "id": "...", "name": "Jan", "email": "jan@deskwoot.com" },
  "labels": [{ "id": "...", "title": "VIP", "color": "#6366F1" }],
  "messages": [...]
}

PATCH/v1/conversations/{conversationId}

Update a conversation's status, priority, assignee, or team.

Auth: Bearer token (conversations:write) or session

Parameter	Type	Required	Description
`status`	string	Optional	OPEN, RESOLVED, PENDING, or SNOOZED
`priority`	string \| null	Optional	URGENT, HIGH, MEDIUM, LOW, or null to clear
`assigneeId`	string \| null	Optional	Agent ID to assign, or null to unassign
`teamId`	string \| null	Optional	Team ID to assign, or null to unassign
`muted`	boolean	Optional	Mute notifications for this conversation

Example

curl -X PATCH https://deskwoot.com/api/v1/conversations/{id} \
  -H "Authorization: Bearer dw_your_token" \
  -H "Content-Type: application/json" \
  -d '{"status": "RESOLVED", "priority": null}'

POST/v1/accounts/{accountId}/conversations/bulk

Update multiple conversations at once. Supports status changes, assignments, priority, labels, and muting.

Auth: Bearer token (conversations:write) or session

Parameter	Type	Required	Description
`conversationIds`	string[]	Required	Array of conversation IDs
`action`	string	Required	change_status, assign_agent, assign_team, change_priority, add_label, or mute
`value`	string \| null	Optional	The target value for the action

Example

curl -X POST https://deskwoot.com/api/v1/accounts/{accountId}/conversations/bulk \
  -H "Authorization: Bearer dw_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "conversationIds": ["conv_1", "conv_2", "conv_3"],
    "action": "change_status",
    "value": "RESOLVED"
  }'

Messages

GET/v1/conversations/{conversationId}/messages

List all messages in a conversation, including sender info and attachments.

Auth: Bearer token (conversations:read) or session

Response

[
  {
    "id": "clx5mno...",
    "content": "Hi, I need help with my order.",
    "messageType": "INCOMING",
    "private": false,
    "createdAt": "2026-03-14T10:00:00Z",
    "sender": { "id": "...", "name": "Lisa", "type": "contact" },
    "attachments": []
  },
  {
    "id": "clx6pqr...",
    "content": "Sure, let me look into that for you!",
    "messageType": "OUTGOING",
    "private": false,
    "createdAt": "2026-03-14T10:02:00Z",
    "sender": { "id": "...", "name": "Jan", "type": "user" },
    "attachments": []
  }
]

POST/v1/conversations/{conversationId}/messages

Send a new message in a conversation. The message is delivered to the customer through the original channel.

Auth: Bearer token (conversations:write) or session

Parameter	Type	Required	Description
`content`	string	Required	Message text
`private`	boolean	Optional	If true, the message is only visible to agents (internal note). Default: false
`messageType`	string	Optional	OUTGOING (default) or INCOMING

Example

curl -X POST https://deskwoot.com/api/v1/conversations/{id}/messages \
  -H "Authorization: Bearer dw_your_token" \
  -H "Content-Type: application/json" \
  -d '{"content": "Your order has been shipped!", "private": false}'

POST/v1/conversations/{conversationId}/attachments

Upload a file attachment to a conversation. Max file size: 10 MB.

Auth: Bearer token (conversations:write) or session

Example

curl -X POST https://deskwoot.com/api/v1/conversations/{id}/attachments \
  -H "Authorization: Bearer dw_your_token" \
  -F "file=@invoice.pdf" \
  -F "content=Here is your invoice."

POST/v1/conversations/{conversationId}/labels

Add a label to a conversation.

Auth: Bearer token (conversations:write) or session

Parameter	Type	Required	Description
`labelId`	string	Required	The label ID to add

DELETE/v1/conversations/{conversationId}/labels?labelId={labelId}

Remove a label from a conversation.

Auth: Bearer token (conversations:write) or session

Contacts

GET/v1/accounts/{accountId}/contacts

List contacts with optional search and segment filtering. Supports pagination.

Auth: Bearer token (contacts:read) or session

Parameter	Type	Required	Description
`search`	string	Optional	Search by name, email, or phone number
`segment`	string	Optional	Filter: active-7d, active-30d, no-email, has-email, has-phone, new
`page`	number	Optional	Page number (default: 1)
`pageSize`	number	Optional	Items per page (default: 25)

Response

{
  "contacts": [
    {
      "id": "clx7stu...",
      "name": "Lisa Schmidt",
      "email": "lisa@example.com",
      "phone": "+49 170 1234567",
      "avatarUrl": null,
      "company": "Acme GmbH",
      "lastActivityAt": "2026-03-14T09:00:00Z",
      "createdAt": "2026-01-15T12:00:00Z"
    }
  ],
  "total": 142,
  "page": 1,
  "pageSize": 25
}

POST/v1/accounts/{accountId}/contacts/merge

Merge two contact records into one. The primary contact keeps its data; the secondary contact's conversations are moved over.

Auth: Bearer token (contacts:write) or session

Parameter	Type	Required	Description
`primaryContactId`	string	Required	The contact to keep
`secondaryContactId`	string	Required	The contact to merge and delete

Inboxes

GET/v1/accounts/{accountId}/inboxes

List all inboxes in your account.

Auth: Bearer token (read) or session

Response

[
  {
    "id": "clx8uvw...",
    "name": "Website Chat",
    "channelType": "WEB",
    "greeting": "Hi! How can we help?",
    "greetingEnabled": true,
    "enableAutoAssign": true,
    "csatEnabled": true,
    "createdAt": "2026-01-01T00:00:00Z"
  },
  {
    "id": "clx9xyz...",
    "name": "Support Email",
    "channelType": "EMAIL",
    "emailAddress": "support@acme.com",
    "createdAt": "2026-01-01T00:00:00Z"
  }
]

POST/v1/accounts/{accountId}/inboxes

Create a new inbox. Supported channel types: WEB, EMAIL, TELEGRAM, WHATSAPP, SMS, LINE, TWITTER.

Auth: Session (permission: settings.manage_inboxes)

Parameter	Type	Required	Description
`name`	string	Required	Display name for the inbox
`channelType`	string	Required	WEB, EMAIL, TELEGRAM, WHATSAPP, SMS, LINE, or TWITTER
`greeting`	string	Optional	Welcome message shown to visitors
`greetingEnabled`	boolean	Optional	Show greeting message (default: false)
`enableAutoAssign`	boolean	Optional	Auto-assign to available agents (default: true)
`botEnabled`	boolean	Optional	Enable AI bot for this inbox
`agentBotId`	string	Optional	Bot ID to use when botEnabled is true

Example: Create Telegram inbox

curl -X POST https://deskwoot.com/api/v1/accounts/{accountId}/inboxes \
  -H "Authorization: Bearer dw_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Telegram Support",
    "channelType": "TELEGRAM",
    "telegramBotToken": "123456:ABC-DEF..."
  }'

GET/v1/accounts/{accountId}/inboxes/{inboxId}

Get full details for a single inbox.

Auth: Bearer token (read) or session

PATCH/v1/accounts/{accountId}/inboxes/{inboxId}

Update inbox settings such as name, greeting, auto-assign mode, CSAT, business hours, widget color, and bot configuration.

Auth: Session (permission: settings.manage_inboxes)

DELETE/v1/accounts/{accountId}/inboxes/{inboxId}

Delete an inbox and all associated data. This action cannot be undone.

Auth: Session (permission: settings.manage_inboxes)

Agents

GET/v1/accounts/{accountId}/agents

List all agents (team members) in your account, including their role and custom role.

Auth: Bearer token (read) or session

Response

{
  "agents": [
    {
      "user": {
        "id": "clx_user1",
        "name": "Jan",
        "email": "jan@deskwoot.com",
        "avatarUrl": null
      },
      "role": "ADMINISTRATOR",
      "customRole": null
    }
  ],
  "maxAgents": 10,
  "plan": "ENTERPRISE"
}

POST/v1/accounts/{accountId}/agents

Invite a new agent to your account. An invitation email is sent automatically.

Auth: Session (admin only)

Parameter	Type	Required	Description
`name`	string	Required	Full name of the new agent
`email`	string	Required	Email address
`role`	string	Optional	AGENT (default) or ADMINISTRATOR
`customRoleId`	string	Optional	ID of a custom role to assign

PATCH/v1/accounts/{accountId}/agents/{agentId}

Update an agent's role.

Auth: Session (admin only)

Parameter	Type	Required	Description
`role`	string	Optional	AGENT or ADMINISTRATOR
`customRoleId`	string \| null	Optional	Custom role ID or null to remove

DELETE/v1/accounts/{accountId}/agents/{agentId}

Remove an agent from your account.

Auth: Session (admin only)

Teams

Teams require the Business plan or higher.

GET/v1/accounts/{accountId}/teams

List all teams with their member count.

Auth: Bearer token (read) or session

POST/v1/accounts/{accountId}/teams

Create a new team.

Auth: Session (permission: settings.manage_teams)

Parameter	Type	Required	Description
`name`	string	Required	Team name
`description`	string	Optional	Team description
`allowAutoAssign`	boolean	Optional	Allow auto-assignment to this team (default: true)

GET/v1/accounts/{accountId}/teams/{teamId}

Get a team with its full member list.

Auth: Bearer token (read) or session

PATCH/v1/accounts/{accountId}/teams/{teamId}

Update team name, description, or auto-assign setting.

Auth: Session (permission: settings.manage_teams)

DELETE/v1/accounts/{accountId}/teams/{teamId}

Delete a team.

Auth: Session (permission: settings.manage_teams)

POST/v1/accounts/{accountId}/teams/{teamId}/members

Add an agent to a team.

Auth: Session (permission: settings.manage_teams)

Parameter	Type	Required	Description
`userId`	string	Required	The agent's user ID

DELETE/v1/accounts/{accountId}/teams/{teamId}/members

Remove an agent from a team.

Auth: Session (permission: settings.manage_teams)

Parameter	Type	Required	Description
`userId`	string	Required	The agent's user ID

Labels

GET/v1/accounts/{accountId}/labels

List all labels in your account.

Auth: Bearer token (read) or session

Response

[
  {
    "id": "clx_label1",
    "title": "VIP",
    "color": "#6366F1",
    "description": "High-value customers",
    "showOnSidebar": true
  }
]

POST/v1/accounts/{accountId}/labels

Create a new label.

Auth: Session (permission: settings.manage_labels)

Parameter	Type	Required	Description
`title`	string	Required	Label name
`color`	string	Optional	Hex color code (default: "#6366F1")
`description`	string	Optional	Label description
`showOnSidebar`	boolean	Optional	Show in sidebar filter (default: true)

PATCH/v1/accounts/{accountId}/labels/{labelId}

Update a label's title, color, description, or visibility.

Auth: Session (permission: settings.manage_labels)

DELETE/v1/accounts/{accountId}/labels/{labelId}

Delete a label. It will be removed from all conversations.

Auth: Session (permission: settings.manage_labels)

Canned Responses

GET/v1/accounts/{accountId}/canned-responses

List all canned responses.

Auth: Bearer token (read) or session

POST/v1/accounts/{accountId}/canned-responses

Create a canned response. Agents can use it by typing the short code in the message input.

Auth: Session (permission: settings.manage_canned_responses)

Parameter	Type	Required	Description
`shortCode`	string	Required	Trigger shortcode (e.g. 'greeting')
`content`	string	Required	Response text. Supports {{contact.name}} variables.

PATCH/v1/accounts/{accountId}/canned-responses/{cannedResponseId}

Update a canned response.

Auth: Session (permission: settings.manage_canned_responses)

DELETE/v1/accounts/{accountId}/canned-responses/{cannedResponseId}

Delete a canned response.

Auth: Session (permission: settings.manage_canned_responses)

Macros

GET/v1/accounts/{accountId}/macros

List all public macros and your personal macros.

Auth: Bearer token (read) or session

Response

{
  "data": [
    {
      "id": "clx_macro1",
      "name": "Close and resolve",
      "visibility": "PUBLIC",
      "actions": [
        { "type": "change_status", "value": "RESOLVED" },
        { "type": "send_message", "value": "Thanks for reaching out! Closing this now." }
      ]
    }
  ]
}

POST/v1/accounts/{accountId}/macros

Create a new macro with one or more actions.

Auth: Bearer token (write) or session

Parameter	Type	Required	Description
`name`	string	Required	Macro name
`actions`	array	Optional	Array of action objects with type and value
`visibility`	string	Optional	PERSONAL (default) or PUBLIC

PATCH/v1/accounts/{accountId}/macros/{macroId}

Update a macro.

Auth: Bearer token (write) or session

DELETE/v1/accounts/{accountId}/macros/{macroId}

Delete a macro.

Auth: Bearer token (write) or session

Automation Rules

Automation rules require the Business plan or higher.

GET/v1/accounts/{accountId}/automation-rules

List all automation rules.

Auth: Bearer token (read) or session

POST/v1/accounts/{accountId}/automation-rules

Create an automation rule with conditions and actions.

Auth: Session (permission: settings.manage_automation)

Parameter	Type	Required	Description
`name`	string	Required	Rule name
`eventName`	string	Required	Trigger event: conversation_created, conversation_updated, or message_created
`conditions`	array	Optional	Array of condition objects (attribute, operator, value)
`actions`	array	Optional	Array of action objects (type, value)
`active`	boolean	Optional	Enable the rule (default: true)

Example

curl -X POST https://deskwoot.com/api/v1/accounts/{accountId}/automation-rules \
  -H "Authorization: Bearer dw_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Auto-assign VIP to senior team",
    "eventName": "conversation_created",
    "conditions": [
      { "attribute": "label", "operator": "contains", "value": "VIP" }
    ],
    "actions": [
      { "type": "assign_team", "value": "senior-support-team-id" }
    ]
  }'

PATCH/v1/accounts/{accountId}/automation-rules/{ruleId}

Update an automation rule.

Auth: Session (permission: settings.manage_automation)

DELETE/v1/accounts/{accountId}/automation-rules/{ruleId}

Delete an automation rule.

Auth: Session (permission: settings.manage_automation)

Campaigns

Campaigns require the Business plan or higher.

GET/v1/accounts/{accountId}/campaigns

List all campaigns (ongoing and one-off).

Auth: Bearer token (read) or session

POST/v1/accounts/{accountId}/campaigns

Create a new campaign.

Auth: Session (permission: settings.manage_campaigns)

Parameter	Type	Required	Description
`title`	string	Required	Campaign title
`message`	string	Required	Message content
`campaignType`	string	Optional	ONGOING or ONE_OFF (default: ONGOING)
`inboxId`	string	Optional	Inbox to send from
`scheduledAt`	string	Optional	ISO date for one-off campaigns
`audience`	object	Optional	Audience targeting rules

GET/v1/accounts/{accountId}/campaigns/{campaignId}

Get campaign details.

Auth: Bearer token (read) or session

PATCH/v1/accounts/{accountId}/campaigns/{campaignId}

Update a campaign.

Auth: Session (permission: settings.manage_campaigns)

POST/v1/accounts/{accountId}/campaigns/{campaignId}/send

Send a one-off campaign immediately.

Auth: Session (permission: settings.manage_campaigns)

DELETE/v1/accounts/{accountId}/campaigns/{campaignId}

Delete a campaign.

Auth: Session (permission: settings.manage_campaigns)

Webhooks

Webhooks let you receive real-time HTTP notifications when events happen in your Deskwoot account. Every webhook payload is signed with HMAC-SHA256 so you can verify authenticity.

Verifying webhook signatures

Each webhook request includes an X-Deskwoot-Signature header. Compute the HMAC-SHA256 of the raw request body using your webhook secret, and compare it to the header value.

Verification example (Node.js)

import crypto from "crypto";

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Event types

Parameter	Type	Required	Description
`message.created`	event	Optional	A new message was sent or received in a conversation
`conversation.updated`	event	Optional	A conversation's status, assignee, team, or priority changed
`conversation.created`	event	Optional	A new conversation was started
`contact.created`	event	Optional	A new contact was created
`contact.updated`	event	Optional	A contact's details were updated

GET/v1/accounts/{accountId}/webhooks

List all webhooks.

Auth: Session (admin only)

POST/v1/accounts/{accountId}/webhooks

Create a webhook. A signing secret is generated automatically and returned in the response.

Auth: Session (admin only)

Parameter	Type	Required	Description
`url`	string	Required	The HTTPS URL to receive webhook events
`subscriptions`	string[]	Optional	Event types to subscribe to (default: all events)

Example

curl -X POST https://deskwoot.com/api/v1/accounts/{accountId}/webhooks \
  -H "Authorization: Bearer dw_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/deskwoot",
    "subscriptions": ["message.created", "conversation.updated"]
  }'

Response

{
  "id": "clx_wh1",
  "url": "https://your-app.com/webhooks/deskwoot",
  "subscriptions": ["message.created", "conversation.updated"],
  "secret": "whsec_a1b2c3d4e5f6...",
  "createdAt": "2026-03-14T12:00:00Z"
}

PATCH/v1/accounts/{accountId}/webhooks/{webhookId}

Update a webhook's URL or subscriptions.

Auth: Session (admin only)

DELETE/v1/accounts/{accountId}/webhooks/{webhookId}

Delete a webhook.

Auth: Session (admin only)

API Tokens

API tokens require the Enterprise plan.

GET/v1/accounts/{accountId}/api-tokens

List all API tokens. The actual token value is not included for security.

Auth: Session (admin only)

Response

[
  {
    "id": "clx_tk1",
    "name": "Production Integration",
    "scopes": ["read", "write"],
    "lastUsedAt": "2026-03-14T10:00:00Z",
    "expiresAt": null,
    "createdAt": "2026-02-01T00:00:00Z"
  }
]

POST/v1/accounts/{accountId}/api-tokens

Create a new API token. The token value is only shown once in the response.

Auth: Session (admin only)

Parameter	Type	Required	Description
`name`	string	Optional	A descriptive name for the token
`scopes`	string[]	Optional	Array of scopes (default: ["read", "write"])
`expiresAt`	string	Optional	ISO date when the token expires (optional, never expires if omitted)

DELETE/v1/accounts/{accountId}/api-tokens/{tokenId}

Revoke an API token. It will immediately stop working.

Auth: Session (admin only)

Bots

GET/v1/accounts/{accountId}/bots

List all AI bots. API keys are masked in the response.

Auth: Bearer token (read) or session

POST/v1/accounts/{accountId}/bots

Create a new AI bot.

Auth: Session (permission: bots.manage)

Parameter	Type	Required	Description
`name`	string	Required	Bot name
`aiProvider`	string	Optional	AI provider: openai, anthropic, google, groq, or custom
`aiApiKey`	string	Optional	Your AI provider API key
`aiModel`	string	Optional	Model name (e.g. gpt-4o, claude-sonnet-4-20250514)
`systemPrompt`	string	Optional	Custom instructions for the bot
`useHelpCenter`	boolean	Optional	Let the bot use your help center articles as context
`temperature`	number	Optional	Creativity level 0-1 (default: 0.3)
`maxTokens`	number	Optional	Max response length 100-2000 (default: 500)

PATCH/v1/accounts/{accountId}/bots/{botId}

Update a bot's settings.

Auth: Session (permission: bots.manage)

DELETE/v1/accounts/{accountId}/bots/{botId}

Delete a bot.

Auth: Session (permission: bots.manage)

POST/v1/accounts/{accountId}/bots/test

Test a bot's response with a sample message.

Auth: Session (permission: bots.manage)

Parameter	Type	Required	Description
`botId`	string	Required	Bot ID to test
`message`	string	Required	Test message

Custom Attributes

Custom attributes require the Business plan or higher.

GET/v1/accounts/{accountId}/custom-attributes

List custom attribute definitions. Use ?model=CONVERSATION or ?model=CONTACT to filter.

Auth: Bearer token (read) or session

POST/v1/accounts/{accountId}/custom-attributes

Create a custom attribute definition.

Auth: Session (admin only)

Parameter	Type	Required	Description
`attributeDisplayName`	string	Required	Display name shown in the UI
`attributeKey`	string	Required	Unique key used in API (snake_case)
`attributeDisplayType`	string	Optional	TEXT, NUMBER, LINK, DATE, LIST, or CHECKBOX (default: TEXT)
`attributeModel`	string	Optional	CONVERSATION or CONTACT (default: CONVERSATION)
`attributeValues`	string[]	Optional	Predefined values for LIST type

PATCH/v1/accounts/{accountId}/custom-attributes/{attributeId}

Update a custom attribute.

Auth: Session (admin only)

DELETE/v1/accounts/{accountId}/custom-attributes/{attributeId}

Delete a custom attribute.

Auth: Session (admin only)

Custom Roles

GET/v1/accounts/{accountId}/custom-roles

List all custom roles with their permissions.

Auth: Session (admin only)

POST/v1/accounts/{accountId}/custom-roles

Create a custom role with granular permissions.

Auth: Session (admin only)

Parameter	Type	Required	Description
`name`	string	Required	Role name
`description`	string	Optional	Role description
`permissions`	object	Optional	Permission flags (e.g. conversations.manage, settings.manage_inboxes)

PATCH/v1/accounts/{accountId}/custom-roles/{roleId}

Update a custom role.

Auth: Session (admin only)

DELETE/v1/accounts/{accountId}/custom-roles/{roleId}

Delete a custom role.

Auth: Session (admin only)

SLA Policies

SLA policies require the Business plan or higher.

GET/v1/accounts/{accountId}/sla-policies

List all SLA policies with conversation counts.

Auth: Bearer token (read) or session

POST/v1/accounts/{accountId}/sla-policies

Create an SLA policy.

Auth: Session (admin only)

Parameter	Type	Required	Description
`name`	string	Required	Policy name
`description`	string	Optional	Policy description
`firstResponseTimeThreshold`	number	Optional	Max seconds for first response
`nextResponseTimeThreshold`	number	Optional	Max seconds between responses
`resolutionTimeThreshold`	number	Optional	Max seconds to resolve
`onlyDuringBusinessHours`	boolean	Optional	Only count time during business hours (default: false)

PATCH/v1/accounts/{accountId}/sla-policies/{policyId}

Update an SLA policy.

Auth: Session (admin only)

DELETE/v1/accounts/{accountId}/sla-policies/{policyId}

Delete an SLA policy.

Auth: Session (admin only)

Business Hours

GET/v1/accounts/{accountId}/business-hours

Get your account's business hours configuration.

Auth: Bearer token (read) or session

Response

{
  "enabled": true,
  "timezone": "Europe/Berlin",
  "schedule": [
    { "day": "monday", "enabled": true, "openHour": 9, "openMinute": 0, "closeHour": 17, "closeMinute": 0 },
    { "day": "tuesday", "enabled": true, "openHour": 9, "openMinute": 0, "closeHour": 17, "closeMinute": 0 },
    { "day": "saturday", "enabled": false, "openHour": 0, "openMinute": 0, "closeHour": 0, "closeMinute": 0 },
    { "day": "sunday", "enabled": false, "openHour": 0, "openMinute": 0, "closeHour": 0, "closeMinute": 0 }
  ]
}

PUT/v1/accounts/{accountId}/business-hours

Set business hours. Provide the full schedule.

Auth: Session (permission: settings.manage_account)

Help Center (Portals)

GET/v1/accounts/{accountId}/portals

List your help center portals with article and category counts.

Auth: Bearer token (read) or session

POST/v1/accounts/{accountId}/portals

Create a new help center portal.

Auth: Session only

Parameter	Type	Required	Description
`name`	string	Required	Portal name
`slug`	string	Required	URL slug (e.g. 'help')
`headerText`	string	Optional	Header text shown on the portal
`brandColor`	string	Optional	Brand color hex (default: "#2563EB")
`customDomain`	string	Optional	Custom domain for the portal

GET/v1/accounts/{accountId}/portals/{portalId}/articles

List articles in a portal.

Auth: Bearer token (read) or session

POST/v1/accounts/{accountId}/portals/{portalId}/articles

Create a new help center article.

Auth: Session only

Parameter	Type	Required	Description
`title`	string	Required	Article title
`content`	string	Required	Article body (HTML supported)
`slug`	string	Optional	URL slug (auto-generated from title if omitted)
`categoryId`	string	Optional	Category to place the article in
`status`	string	Optional	DRAFT or PUBLISHED (default: DRAFT)

PATCH/v1/accounts/{accountId}/portals/{portalId}/articles/{articleId}

Update an article.

Auth: Session only

DELETE/v1/accounts/{accountId}/portals/{portalId}/articles/{articleId}

Delete an article.

Auth: Session only

Public Portal API (no authentication required)

These endpoints are publicly accessible and designed for embedding your help center in external websites or apps.

GET/v1/public/portals/{portalSlug}

Get public portal info with categories and article count.

Auth: None

GET/v1/public/portals/{portalSlug}/articles

List published articles. Supports search and pagination.

Auth: None

Parameter	Type	Required	Description
`categoryId`	string	Optional	Filter by category
`search`	string	Optional	Search articles by title or content
`page`	number	Optional	Page number (default: 1)
`limit`	number	Optional	Items per page (default: 20, max: 50)

GET/v1/public/portals/{portalSlug}/articles/{articleSlug}

Get a single published article by slug.

Auth: None

Account Settings

GET/v1/accounts/{accountId}/settings

Get account settings including name, locale, timezone, plan, and feature flags.

Auth: Bearer token (read) or session

Response

{
  "id": "clx_acc1",
  "name": "Acme Support",
  "locale": "en",
  "timezone": "Europe/Berlin",
  "plan": "ENTERPRISE",
  "autoResolveEnabled": true,
  "autoResolveDuration": 48,
  "brandColor": "#2563EB",
  "liveTranslateEnabled": true,
  "liveTranslateTargetLang": "en",
  "createdAt": "2026-01-01T00:00:00Z"
}

PATCH/v1/accounts/{accountId}/settings

Update account settings.

Auth: Session (permission: settings.manage_account)

Parameter	Type	Required	Description
`name`	string	Optional	Account name
`locale`	string	Optional	Default locale (e.g. en, de)
`timezone`	string	Optional	IANA timezone (e.g. Europe/Berlin)
`autoResolveEnabled`	boolean	Optional	Auto-resolve inactive conversations
`autoResolveDuration`	number	Optional	Hours of inactivity before auto-resolve
`brandColor`	string	Optional	Brand color hex code
`liveTranslateEnabled`	boolean	Optional	Enable live translation
`liveTranslateTargetLang`	string	Optional	Target language for translation

Notifications

GET/v1/accounts/{accountId}/notifications

Get paginated notifications for the current user.

Auth: Session only

Response

{
  "data": [
    {
      "id": "clx_notif1",
      "type": "conversation_assigned",
      "read": false,
      "createdAt": "2026-03-14T10:00:00Z",
      "conversation": { "id": "...", "contactName": "Lisa" }
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 20,
    "total": 45,
    "unreadCount": 3
  }
}

PATCH/v1/accounts/{accountId}/notifications

Mark notifications as read.

Auth: Session only

Parameter	Type	Required	Description
`markAllRead`	boolean	Optional	Set to true to mark all as read
`notificationId`	string	Optional	Or mark a single notification as read

Audit Logs

Audit logs require the Enterprise plan.

GET/v1/accounts/{accountId}/audit-logs

Get paginated audit logs for your account. Admin only.

Auth: Session (admin only)

Parameter	Type	Required	Description
`page`	number	Optional	Page number (default: 1)

Response

{
  "data": [
    {
      "id": "clx_log1",
      "action": "inbox.created",
      "actor": { "name": "Jan", "email": "jan@deskwoot.com" },
      "details": { "inboxName": "WhatsApp" },
      "createdAt": "2026-03-14T08:00:00Z"
    }
  ],
  "meta": { "page": 1, "pageSize": 25, "total": 200, "totalPages": 8 }
}

Billing

GET/v1/accounts/{accountId}/billing

Get billing information for your account.

Auth: Session (permission: settings.manage_billing)

Response

{
  "plan": "ENTERPRISE",
  "status": "ACTIVE",
  "agentSeats": 10,
  "activeAgents": 4,
  "trialEndsAt": null,
  "currentPeriodEnd": "2026-04-01T00:00:00Z"
}

Rate limits

API requests are limited to 60 requests per minute per API token. If you exceed the limit, you will receive a 429 Too Many Requests response. Wait and retry after the window resets.

Need higher limits? Contact us to discuss your requirements.

Need help?

If you have questions about the API or need help with your integration, reach out to support@deskwoot.com or use the live chat on our website.