A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Dixa API is how an app or AI agent works with a Dixa customer service workspace: reading and creating conversations, replying to a customer or adding an internal note, closing or transferring a conversation, and managing end users, agents, teams, queues, and tags. Access is granted through a single API token created by an administrator, and that token is organization-scoped with no per-endpoint permissions, so it reaches everything the API exposes across the organization. A conversation event, like a message added or a conversation closed, can be pushed to a subscribed webhook.
How an app or AI agent connects to Dixa determines what it can reach. There is a route for making calls and a route for receiving events, and each is governed by the API token behind it, which carries the access of the whole organization.
The v1 Dixa API answers at https://dev.dixa.io and uses JSON request and response bodies. A call authenticates with an API token sent as a Bearer token in the Authorization header. The token is created by an administrator in Dixa and carries the access of the whole organization. This API replaces the older Integrations API.
Dixa POSTs a JSON payload to a subscribed HTTPS URL when a conversation event fires, like ConversationCreated, ConversationMessageAdded, or ConversationClosed. Each delivery carries an X-DIXA-SIGNATURE header, a comma-separated timestamp and HMAC signature, so the receiver can verify the payload came from Dixa using the subscription's verification secret.
A Dixa API token is created by an administrator in Settings, under Integrations, on the API Tokens tab, choosing the 'Dixa API' version. It is sent as a Bearer token in the Authorization header. The token is organization-scoped, with no granular per-endpoint scopes, so it carries the access of the whole organization and any agent given it can read and write across all conversations, users, and settings the API exposes.
The Dixa API is split into areas an agent can act on, like conversations, end users, agents, teams, queues, and tags. Each area has its own methods, and writes can reply to a customer, close a ticket, or permanently anonymize personal data.
Create, read, close, reopen, and transfer conversations, and add messages to them.
Read a conversation's messages, add a message, and add or list internal notes.
Create tags, list them, and add or remove tags on a conversation.
Create, read, and update end users, and read the conversations they requested.
Create, list, read, and update agents, and read an agent's presence status.
Create teams, list them, and list or change a team's members.
Create queues, list them, and assign agents to a queue.
List custom attribute definitions, and set custom attributes on end users and conversations.
List available metrics and records, and fetch aggregated or unaggregated metric data.
Create, list, read, patch, and delete webhook subscriptions, and read their delivery status.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
ConversationsCreate, read, close, reopen, and transfer conversations, and add messages to them.7 | ||||||
| POST | /v1/conversations | Create a conversation on a channel, like email, chat, or phone. | write | — | Current | |
A token reaches every conversation in the organization; Dixa has no per-endpoint scopes. Acts onconversation Permission (capability)None required VersionAvailable since the API’s base version Webhook event ConversationCreatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/conversations/{conversationId} | Get a single conversation by its id. | read | — | Current | |
Read-only; the token can read any conversation in the organization. Acts onconversation Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v1/conversations/{conversationId}/close | Mark a conversation as closed. | write | — | Current | |
Closes a real customer conversation. Acts onconversation Permission (capability)None required VersionAvailable since the API’s base version Webhook event ConversationClosedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v1/conversations/{conversationId}/reopen | Reopen a closed conversation and re-offer it. | write | — | Current | |
Returns a closed conversation to an active state. Acts onconversation Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v1/conversations/{conversationId}/transfer/queue | Transfer a conversation to a target queue. | write | — | Current | |
Re-routes a live conversation to a different queue. Acts onconversation Permission (capability)None required VersionAvailable since the API’s base version Webhook event ConversationTransferredRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v1/conversations/{conversationId}/anonymize | Permanently anonymize a conversation and its personal data. | write | — | Current | |
Irreversibly removes personal data, used for data-subject erasure requests. Acts onconversation Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/search/conversations | Search conversations by text, by filter, or by both. | read | — | Current | |
Read-only; there is no plain list-all endpoint, so search is how conversations are found. Acts onconversation Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Messages & notesRead a conversation's messages, add a message, and add or list internal notes.4 | ||||||
| GET | /v1/conversations/{conversationId}/messages | Get all messages for a particular conversation. | read | — | Current | |
Read-only; returns the message history of a conversation. Acts onmessage Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/conversations/{conversationId}/messages | Add a message to a conversation, which can reply to the customer. | write | — | Current | |
Sends a real message; an outbound message is delivered to the customer. Acts onmessage Permission (capability)None required VersionAvailable since the API’s base version Webhook event ConversationMessageAddedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/conversations/{conversationId}/notes | Create an internal note on a conversation, visible only to the team. | write | — | Current | |
A note is internal and not sent to the customer. Acts onnote Permission (capability)None required VersionAvailable since the API’s base version Webhook event ConversationNoteAddedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/conversations/{conversationId}/notes | List the internal notes on a conversation. | read | — | Current | |
Read-only. Acts onnote Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TagsCreate tags, list them, and add or remove tags on a conversation.4 | ||||||
| POST | /v1/tags | Create a tag in the organization. | write | — | Current | |
Adds a reusable tag to the organization's tag list. Acts ontag Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/tags | List all tags in the organization. | read | — | Current | |
Read-only. Acts ontag Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v1/conversations/{conversationId}/tags/{tagId} | Add a tag to a conversation. | write | — | Current | |
Tags a real conversation. Acts ontag Permission (capability)None required VersionAvailable since the API’s base version Webhook event ConversationTagAddedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/conversations/{conversationId}/tags/{tagId} | Remove a tag from a conversation. | write | — | Current | |
Removes a tag from a real conversation. Acts ontag Permission (capability)None required VersionAvailable since the API’s base version Webhook event ConversationTagRemovedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
End users (contacts)Create, read, and update end users, and read the conversations they requested.4 | ||||||
| POST | /v1/endusers | Create an end user (a customer contact). | write | — | Current | |
Creates a real customer contact record. Acts onend user Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/endusers/{userId} | Get an end user by id. | read | — | Current | |
Read-only; returns a customer's contact details. Acts onend user Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v1/endusers/{userId} | Update an end user's details. | write | — | Current | |
Changes a real customer contact record. Acts onend user Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/endusers/{userId}/conversations | List the conversations an end user requested. | read | — | Current | |
Read-only. Acts onconversation Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AgentsCreate, list, read, and update agents, and read an agent's presence status.4 | ||||||
| POST | /v1/agents | Create an agent. | write | — | Current | |
Creates a real agent account in the organization. Acts onagent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/agents | List all agents and admins. | read | — | Current | |
Read-only. Acts onagent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/agents/{agentId} | Get an agent by id. | read | — | Current | |
Read-only. Acts onagent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/agents/{agentId}/presence | Get an agent's presence status. | read | — | Current | |
Read-only; reports whether an agent is online and available. Acts onagent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TeamsCreate teams, list them, and list or change a team's members.4 | ||||||
| POST | /v1/teams | Create a team. | write | — | Current | |
Creates a real team in the organization. Acts onteam Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/teams | List all teams. | read | — | Current | |
Read-only. Acts onteam Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/teams/{teamId}/agents | List all agents and admins in a team. | read | — | Current | |
Read-only. Acts onteam Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v1/teams/{teamId}/agents | Add one or more members to a team. | write | — | Current | |
Changes real team membership. Acts onteam Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
QueuesCreate queues, list them, and assign agents to a queue.3 | ||||||
| POST | /v1/queues | Create a queue. | write | — | Current | |
Creates a real routing queue. Acts onqueue Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/queues | List all queues. | read | — | Current | |
Read-only. Acts onqueue Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v1/queues/{queueId}/members | Assign one or more agents or admins to a queue. | write | — | Current | |
Changes who receives conversations from a queue. Acts onqueue Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Custom attributesList custom attribute definitions, and set custom attributes on end users and conversations.3 | ||||||
| GET | /v1/custom-attributes | List all custom attribute definitions. | read | — | Current | |
Read-only; returns the fields that can be set on users and conversations. Acts oncustom attribute Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v1/endusers/{userId}/custom-attributes | Set custom attributes on an end user. | write | — | Current | |
Changes custom field values on a real customer contact. Acts oncustom attribute Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v1/conversations/{conversationId}/custom-attributes | Set custom attributes on a conversation. | write | — | Current | |
Changes custom field values on a real conversation. Acts oncustom attribute Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Analytics & metricsList available metrics and records, and fetch aggregated or unaggregated metric data.3 | ||||||
| GET | /v1/analytics/metrics | List the available metric ids. | read | — | Current | |
Read-only. Acts onmetric Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/analytics/metrics | Get aggregated data for a specific metric. | read | — | Current | |
Read-only despite the POST verb; the body carries the query, not a change. Acts onmetric Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/analytics/records | Get unaggregated records for a specific metric. | read | — | Current | |
Read-only despite the POST verb; the body carries the query, not a change. Acts onrecord Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksCreate, list, read, patch, and delete webhook subscriptions, and read their delivery status.3 | ||||||
| POST | /v1/webhooks | Create a webhook subscription for conversation events. | write | — | Current | |
Sets a URL that will receive conversation events. Acts onwebhook subscription Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/webhooks | List all webhook subscriptions in the organization. | read | — | Current | |
Read-only. Acts onwebhook subscription Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/webhooks/{webhookSubscriptionId}/delivery-status | Get the latest delivery statuses for a webhook subscription. | read | — | Current | |
Read-only; shows whether recent events were delivered. Acts onwebhook subscription Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Dixa can notify an app when something happens to a conversation, like a conversation being created, a message added, or a conversation closed. It posts a JSON payload to a subscribed URL, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
ConversationCreated | A conversation was created in Dixa. | /v1/conversations |
ConversationMessageAdded | A message was added to a conversation. | /v1/conversations/{conversationId}/messages |
ConversationNoteAdded | An internal note was added to a conversation. | /v1/conversations/{conversationId}/notes |
ConversationClosed | A conversation was closed. | /v1/conversations/{conversationId}/close |
ConversationTransferred | A conversation was transferred to another queue or agent. | /v1/conversations/{conversationId}/transfer/queue |
ConversationTagAdded | A tag was added to a conversation. | /v1/conversations/{conversationId}/tags/{tagId} |
ConversationTagRemoved | A tag was removed from a conversation. | /v1/conversations/{conversationId}/tags/{tagId} |
ConversationRated | A conversation was rated by the end user, or a rating comment was left. One event fires per rating or comment. | In-app only |
ConversationEnqueued | A conversation entered a queue. | In-app only |
ConversationPending | A conversation moved to a pending state, awaiting a reply. | In-app only |
ConversationAssigned | A conversation was assigned to an agent. | In-app only |
ConversationUnassigned | A conversation was unassigned from an agent. | In-app only |
Dixa limits how fast an app can call by a per-token request rate, measured per second with a short burst allowance and a daily ceiling.
Dixa meters requests per API token. The limit is 10 requests per second with a short burst allowance of 4 requests, and a daily ceiling of 864,000 requests per token. Going over returns HTTP 429 Too Many Requests. Dixa does not send a Retry-After header, so a client backs off on its own, ideally with exponential backoff. Because the limit is per token rather than per account, splitting work across separate tokens raises the total throughput available.
List endpoints return results in pages and accept paging parameters on the query string. Search runs through POST /v1/search/conversations, which takes text and filter criteria in the body, since there is no plain list-all-conversations endpoint. Read the per-endpoint reference for the exact page-size and cursor parameters, which vary by endpoint.
Requests and responses are JSON. Dixa does not publish a single fixed payload size limit across the API; individual endpoints, such as bulk tagging or bulk notes, set their own batch ceilings, documented on those endpoints.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request was malformed or a parameter was missing or invalid. | Fix the request body or parameters and resend. The request is not retryable as-is. |
| 401 | Unauthorized | No valid API token was provided, or the token is wrong or expired. | Send a valid token in the Authorization header as 'Bearer |
| 403 | Forbidden | The token is valid but not permitted to perform the request. | Confirm the token was created as a 'Dixa API' token by an administrator. |
| 404 | Not Found | The requested resource, like a conversation or end user, does not exist. | Check the id in the path and confirm the resource exists. |
| 429 | Too Many Requests | The per-token rate limit was exceeded, at 10 requests per second with a burst of 4 and a daily ceiling of 864,000 requests. | Back off and retry with exponential backoff. Dixa does not send a Retry-After header, so the client sets its own delay. |
| 500 | Internal Server Error | An error on Dixa's side. It is rare. | Retry with backoff, and contact Dixa support if it persists. |
Dixa runs a single current v1 API, the Dixa API, which replaces the older Integrations API that is being sunset. The token chooses which API it targets, and v1 is the version to build on.
The v1 Dixa API at https://dev.dixa.io is the current API, covering conversations, messages, internal notes, end users, agents, teams, queues, tags, custom attributes, analytics, and webhooks. It is selected by the token version when an API token is created. It supersedes the older Integrations API, which Dixa is sunsetting, with a published migration guide that maps the old endpoints and fields to v1.
The earlier Integrations API, hosted at integrations.dixa.io, is deprecated and being sunset in favor of the v1 Dixa API. Dixa provides a migration guide that maps each Integrations API endpoint and field to its Dixa API equivalent, for example moving user creation from the old users endpoint to the new endusers endpoint.
Build on the v1 Dixa API; the older Integrations API is being retired.
Dixa API migration guide ↗Bollard AI sits between a team's AI agents and Dixa. Grant each agent exactly the access it needs, read or write, conversation by conversation, and every call is checked and logged.