Skip to content

Tickets

Shared inbox, forms and automations for customer requests.

Open Tickets
Checked against the dashboard on November 18, 2026

The ticket API lets software outside Xuda work a desk: open a ticket, list and read tickets, reply, assign, move a ticket between stages and close it, and read the topics and the team. Forms, workflows, AI agents, internal notes and the settings stay in the dashboard.

Every call is a POST to https://xuda.ai/cpi/<method> with a JSON body that carries your account API key as api_key. A call works on the desk of the account that owns the key, under that desk's plan, and cannot name another desk. Create the key in the dashboard under Developers, and keep it out of pages and public code.

The answer is { "code": ..., "data": ... }. A positive code is success. A refusal is a negative code with a sentence in data.

curl -s https://xuda.ai/cpi/ticket_api_submit \
  -H 'content-type: application/json' \
  -d '{"api_key":"YOUR_API_KEY","name":"Jordan Lee","email":"[email protected]","subject":"Export fails","details":"The export button returns a 500."}'
const res = await fetch('https://xuda.ai/cpi/ticket_api_submit', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    api_key: 'YOUR_API_KEY',
    name: 'Jordan Lee',
    email: '[email protected]',
    subject: 'Export fails',
    details: 'The export button returns a 500.',
  }),
});
const { code, data } = await res.json();
import requests

res = requests.post(
    'https://xuda.ai/cpi/ticket_api_submit',
    json={
        'api_key': 'YOUR_API_KEY',
        'name': 'Jordan Lee',
        'email': '[email protected]',
        'subject': 'Export fails',
        'details': 'The export button returns a 500.',
    },
)

name and details are required. A contact is created or reused from email, the ticket is filed with the source api, and the answer is a narrow view: number, id, status, stage, subject, topic, requester, the assignee's id and the timestamps. Internal ids and automation state are never returned.

email is optional when an integration or an agent files the ticket for itself: send a name only, and no contact is made and nothing is mailed to the requester.

Optional fields give the ticket a subject, phone, company, a topic_id and subtopic_id from the desk's topics, your own reference_id, a priority from 1 (highest) to 4, a type (issue, bug, feature or task) and attachments.

To hand the new ticket to someone, name them with assignee_uid or assignee_email, one of the two. They must be on the desk's workspace team, which is its owner and the accepted members of the workspace. A refused assignee files no ticket.

Find and read tickets

ticket_api_list lists tickets with the filters the dashboard has: status (open or closed), source, topic_id, type, assignee_uid, reference_id, a free-text search over subject, details and ticket number, and a created_from and created_to range. Sort with sort (date_created_ts, last_activity_ts, status_ts or priority) and dir, and page with limit (up to 500) and the bookmark from the previous answer.

ticket_api_get reads one ticket by ticket_id, with its public interactions. Internal notes and AI drafts are never returned.

ticket_api_topics returns the desk's topics and sub topics, so your own form can show the same picker the hosted form does. ticket_api_team returns the people a ticket can be assigned to, each with a uid, a name and an email.

curl -s https://xuda.ai/cpi/ticket_api_reply \
  -H 'content-type: application/json' \
  -d '{"api_key":"YOUR_API_KEY","ticket_id":"TICKET_ID","body":"Thanks, we are looking into it."}'
curl -s https://xuda.ai/cpi/ticket_api_set_stage \
  -H 'content-type: application/json' \
  -d '{"api_key":"YOUR_API_KEY","ticket_id":"TICKET_ID","status_stage":"in_progress"}'
curl -s https://xuda.ai/cpi/ticket_api_close \
  -H 'content-type: application/json' \
  -d '{"api_key":"YOUR_API_KEY","ticket_id":"TICKET_ID","reason":"Fixed in the latest release."}'
  • ticket_api_reply always posts a public reply, never an internal note. It is the desk answering, unless you pass as_requester: true, which posts it as the requester's own message. In that case the assignee, or the desk owner, is notified, and it does not count as the desk's first response.
  • ticket_api_set_stage moves an open ticket to new, in_progress, waiting_customer or resolved. A closed ticket is refused unless you pass reopen: true, which opens it again at that stage. Naming the stage the ticket already has changes nothing.
  • ticket_api_assign gives a ticket to a person on the team by assignee_uid or assignee_email. Naming the current assignee changes nothing. If more than one team member has that email, the call is refused with -409 and you pass the uid instead.
  • ticket_api_close closes the ticket. The optional reason is shown to the customer. A customer reply inside the reopen window brings the ticket back.

Read the desk's own list

get_support_tickets reads tickets back to the signed-in account that owns the desk, and can be limited to one ticket with _id. It is a different shape from the ticket_api_* view, which is built for a caller outside Xuda.

Plans and limits

The plan decides what a key may do. Reading (ticket_api_list, ticket_api_get, ticket_api_topics, ticket_api_team) needs read access, and writing (ticket_api_submit, ticket_api_reply, ticket_api_set_stage, ticket_api_assign, ticket_api_close) needs full access. A plan without it answers -402. Each plan also has a number of calls a minute, and past it a call is answered -429 until the next minute. History follows the plan's retention window, so a ticket older than it cannot be read. The plans page has the figures.

A new ticket counts against the month's allowance, as it does from any other way in.

Methods

How is this guide?

Last updated on November 12, 2026