Overview
Desk exposes the same support infrastructure the Desk portal uses — customers, tickets, conversations, attachments, status, priority, teams, assignments, escalations, and knowledge base — as a public API. Your product owns the customer-facing experience; your agents keep using the normal Desk workspace at desk.monesize.com.
Base URL:
https://api.desk.monesize.com/v1/apiAuthentication
Every request must include a bearer API key. Keys are created in Desk under Settings → API keys by an organization administrator.
Authorization: Bearer dsk_live_0123456789…The X-Desk-Api-Key header is accepted as an alternative.
Environments
Each organization has separate test and production keys.
| Environment | Key prefix | Notes |
|---|---|---|
| Test | dsk_test_… | For development and integration testing. Writes to a hidden test tenant that never appears in the agent workspace. |
| Production | dsk_live_… | For your live application. Operates on your real tenant and appears in the agent workspace. |
Error handling
Errors use the standard Desk envelope:
{
"message": "Ticket subject is required.",
"code": "VALIDATION_ERROR",
"details": null
}| Status | Code | Condition |
|---|---|---|
| 400 | VALIDATION_ERROR | Missing or malformed fields |
| 401 | API_KEY_INVALID | Missing, unknown, or revoked key |
| 403 | FORBIDDEN | Plan restriction (e.g. attachments) |
| 404 | NOT_FOUND | Resource does not exist in your organization |
| 429 | RATE_LIMITED | Over 300 requests/minute |
Customers
| Method | Path | Description |
|---|---|---|
| GET | /customers?q=&page=&perPage= | List customers (search on name/email/phone) |
| POST | /customers | Create a customer — { email, name, phone? } |
| GET | /customers/:customerId | Customer with their ticket history |
| PATCH | /customers/:customerId | Update — { name?, phone?, email? } |
Tickets
| Method | Path | Description |
|---|---|---|
| GET | /tickets?status=&priority=&category=&teamId=&agentId=&unassigned= | Queue-style list |
| POST | /tickets | Create — { customerEmail, customerName?, subject, description, category?, priority? } |
| GET | /tickets/:ticketId | Full ticket with conversation, attachments, escalations, audit trail |
| PATCH | /tickets/:ticketId | Update status/priority/category/subject |
| POST | /tickets/:ticketId/assign | Assign — { userId?, teamId? } |
| POST | /tickets/:ticketId/escalate | Escalate — { toTeamId?, fromTeamId?, reason } |
| POST | /tickets/:ticketId/reopen | Reopen a resolved/closed ticket |
Create example:
curl -X POST https://api.desk.monesize.com/v1/api/tickets \
-H "Authorization: Bearer dsk_live_…" \
-H "Content-Type: application/json" \
-d '{"customerEmail":"ada@acme.example","customerName":"Ada","subject":"Cannot sign in","description":"Getting a 500 on login","priority":"HIGH"}'Conversations
| Method | Path | Description |
|---|---|---|
| POST | /tickets/:ticketId/messages | Post a public reply — { body, customerEmail? }. Authored by the ticket's customer (or the customer matched by email); reopens resolved/closed tickets and notifies the assigned agent. |
Attachments
Uploads use presigned S3 URLs, same as the Desk portal (10 MB max, whitelisted MIME types, requires an eligible plan).
| Method | Path | Description |
|---|---|---|
| POST | /attachments/tickets/:ticketId | Start upload — { fileName, mimeType, sizeBytes } → returns a presigned PUT URL |
| GET | /attachments/:attachmentId | Resolve a presigned GET URL |
Teams
| Method | Path | Description |
|---|---|---|
| GET | /teams | List teams with members |
| POST | /teams | Create — { name, memberIds? } |
| GET | /teams/:teamId | Fetch a team |
| PATCH | /teams/:teamId | Rename — { name } |
| POST | /teams/:teamId/members | Add members — { memberIds } |
| DELETE | /teams/:teamId/members | Remove members — { memberIds } |
| DELETE | /teams/:teamId | Delete a team |
Knowledge base
| Method | Path | Description |
|---|---|---|
| GET | /kb?q=&visibility=&page=&perPage= | List articles (visibility: published | draft | all) |
| POST | /kb | Create — { title, body, isPublished?, portalVisible?, slug? } |
| GET | /kb/:articleSlug | Fetch an article |
| PATCH | /kb/:articleId | Update article fields |
| DELETE | /kb/:articleId | Delete an article |