REST API

The DeskAI REST API lets monitoring tools, RMM platforms and your own scripts create and work tickets, add replies and notes, and keep knowledge base articles and assets in sync. It’s included on the Enterprise plan. The full description, for tools that import OpenAPI, is at /api/v1/openapi.json on your DeskAI address.

Create a key

1. Go to Admin Portal → API & Keys (MSP admins) or API & webhooks (company admins).
2. Name the key after the tool that will use it, and choose only the permissions it needs.
3. Click Create key and copy it straight away. DeskAI keeps only a fingerprint of it, so it can’t be shown again.

A company admin’s key only sees that company’s records. An MSP admin’s key is a workspace key: it sees every company, and can create records for one with companyId. Revoke a key at any time from the same page.

Authenticate

Send the key as a bearer token. GET /me checks a key works and shows its permissions.

curl https://your-deskai-address/api/v1/me   -H "Authorization: Bearer dsk_your_key"

Permissions

Endpoints

Create a ticket

New tickets go through the same routing rules, automations, AI triage and smart routing as email and the portal. The ticket comes back straight away; triage fills in the priority, category and summary a few seconds later. A priority or category you send is kept.

curl https://your-deskai-address/api/v1/tickets   -H "Authorization: Bearer dsk_your_key"   -H "Content-Type: application/json"   -H "Idempotency-Key: alert-48213"   -d '{
    "subject": "Disk almost full on FS-02",
    "description": "C: is at 96% on the file server FS-02.",
    "requester": { "email": "monitoring@deskyon.example", "name": "Monitoring" },
    "priority": "High",
    "tags": ["monitoring"]
  }'

Update, reply and resolve

Resolving or closing a ticket needs a resolutionNote, as it does in DeskAI. Notifications, Slack and Teams alerts, the satisfaction survey, webhooks and automations follow a change from the API just as they follow a change an agent makes.

curl -X PATCH https://your-deskai-address/api/v1/tickets/1042   -H "Authorization: Bearer dsk_your_key"   -H "Content-Type: application/json"   -d '{ "status": "resolved", "resolutionNote": "Cleared old backups; C: at 61%." }'

A message’s type decides where it goes. A reply reaches the requester where the ticket came from: its Slack or Teams thread, otherwise email (which needs email set up). A requester message is added as if the requester wrote it, and reopens a resolved ticket. A note is internal.

Paging

Lists return { "data": [...], "nextCursor": "1017" }. Pass cursor to get the next page, until nextCursor is null. limit sets the page size, from 1 to 100 (25 by default).

Rate limits

Each key can make 120 requests a minute. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Past the limit, requests get a 429 with a Retry-After header in seconds.

Safe retries

Send an Idempotency-Key header when creating a ticket, message, article or asset. If the request is retried with the same key within 24 hours, DeskAI returns the first response instead of creating a duplicate.

Errors

Errors return { "error": { "code": "...", "message": "..." } }, with details listing each field when validation fails. Codes include unauthorized (401), insufficient_scope, plan_required and forbidden (403), not_found (404), invalid_request (422), rate_limited (429) and delivery_failed (502, a reply that couldn’t reach the requester).

Keys are for servers and scripts. Don’t put one in a web page or an app people download. To hear about changes as they happen instead of polling, use webhooks.