Developer API · Monesize Desk

Desk Public API

Support infrastructure, exposed as a REST API.

Create customers and tickets, run conversations, organize teams, publish knowledge base content, and move attachments. Every call operates on the same data your agents see in the Desk workspace.

Quickstart Endpoint index

Base URLhttps://api.desk.monesize.com/v1/api

Versionv1

FormatJSON

AuthenticationBearer API key

Documentation contents

Quickstart

Create an API key in Desk under Settings, then API keys. Use a test key while you build. All examples send the key in the Authorization header and read the key from DESK_API_KEY.

Create a test key. Test keys start with dsk_test_ and write to a hidden test environment.
Send a request. Create a ticket for a new customer. The customer is created automatically when the email is new.
Read the response. Use data.id for follow-up calls and data.ticketNumber for display.

cURL

export DESK_API_KEY="dsk_test_your_key"

curl -X POST "https://api.desk.monesize.com/v1/api/tickets" \
  -H "Authorization: Bearer $DESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerEmail": "ada@acme.example",
    "customerName": "Ada Lovelace",
    "subject": "Cannot sign in",
    "description": "I get a 500 error when I submit the login form.",
    "priority": "HIGH"
  }'

JavaScript

const res = await fetch("https://api.desk.monesize.com/v1/api/tickets", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DESK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    customerEmail: "ada@acme.example",
    customerName: "Ada Lovelace",
    subject: "Cannot sign in",
    description: "I get a 500 error when I submit the login form.",
    priority: "HIGH",
  }),
});

if (!res.ok) {
  const error = await res.json();
  throw new Error(`${error.code}: ${error.message}`);
}

const { data } = await res.json();
console.log(data.id, data.ticketNumber, data.status);

Keep keys server side.

A key grants full access to its environment. Never ship a key in browser code or a mobile binary. Call the Desk API from your backend and pass only the data your client needs.

Authentication

Every request must include an API key. Send it as a bearer token, or use the X-Desk-Api-Key header. If both are present, the bearer token wins.

Header

Authorization: Bearer dsk_live_0123456789abcdef0123456789abcdef

# Alternative
X-Desk-Api-Key: dsk_live_0123456789abcdef0123456789abcdef

Keys are tenant-wide. There are no per-endpoint scopes.
Keys do not expire automatically. Revoke a key in Settings to invalidate it immediately.
Revoked, unknown, or missing keys return HTTP 401 with code API_KEY_INVALID.
Only a key prefix is stored for display. The full key is shown once at creation time.

Environments

Each organization has separate test and production keys. Both environments use the same base URL. The key prefix decides which environment a request touches.

Environment	Prefix	Data store	Use it for
Test	`dsk_test_`	A hidden sibling tenant, created on first use.	Development, automated tests, and demos. Test data never appears in the agent workspace.
Production	`dsk_live_`	Your real organization.	Live traffic. Data appears in the agent workspace and can trigger customer email.

The test environment inherits the organization plan. Attachments still require an eligible plan.

Response format

Successful requests return a JSON object with message and data. List endpoints also include meta. All successful responses use HTTP 200, including creates and deletes.

Success

{
  "message": "Ticket fetched.",
  "data": {
    "id": "2f6a8c1d-7e9b-4a3c-8d5f-0a1b2c3d4e5f",
    "ticketNumber": 1042,
    "status": "OPEN"
  }
}

Error

{
  "message": "Invalid priority.",
  "code": "VALIDATION_ERROR"
}

data can be an object, an array, or true for deletes.
meta only appears on paginated list endpoints.
Timestamps are UTC strings in ISO 8601 format.
Ids are UUID strings.
Errors never include a data field. They may include details when structured validation data exists.

Pagination

List endpoints accept page and perPage. Page defaults to 1. perPage defaults to 20 and is capped at 100.

Parameter	Default	Behavior
`page`	1	Values below 1 or non-numeric values fall back to page 1.
`perPage`	20	Values above 100 are clamped to 100. Invalid values use the default.

Read meta.total to calculate pages. The response never returns a cursor. Use the same filters plus a higher page number to continue.

Errors

Errors use a stable machine-readable code and a human-readable message. Branch on the code, not the message.

API error codes

Status	Code	When
400	`VALIDATION_ERROR`	A required field is missing, malformed, or not recognized.
401	`API_KEY_INVALID`	The API key is missing, unknown, or revoked.
403	`ATTACHMENTS_NOT_ALLOWED_PLAN`	The environment plan does not include attachments.
403	`FORBIDDEN`	The request is not allowed for this resource.
404	`NOT_FOUND`	The requested resource does not exist in the environment.
404	`ORG_NOT_FOUND`	The environment could not be resolved.
409	`CUSTOMER_EMAIL_TAKEN`	A customer with this email already exists.
409	`TEAM_NAME_TAKEN`	A team with this name already exists.
409	`KB_SLUG_TAKEN`	A knowledge base article with this slug already exists.
429	`RATE_LIMITED`	The request rate for this client exceeded 300 requests per minute.
500	`INTERNAL_ERROR`	An unexpected server error occurred. Retry with backoff.

Validation messages describe the first problem found. Fix the request and retry. For 429 and 5xx responses, use exponential backoff.

Rate limits

Public API keys are limited to 300 requests per minute per client. The limiter returns standard rate limit headers and HTTP 429 when the limit is exceeded.

429 response

{
  "message": "Too many requests. Please try again later.",
  "code": "RATE_LIMITED"
}

Calculate one rate limit budget per client, not per endpoint.
Back off when you receive a 429. Do not retry in a tight loop.
JSON request bodies are limited to 2 MB. File uploads use S3 and allow up to 10 MB per file.

Endpoint index

All public endpoints. Every path is relative to https://api.desk.monesize.com/v1/api.

Method	Path	Description	Group
GET	`/customers`	List customers	Customers
POST	`/customers`	Create a customer	Customers
GET	`/customers/:customerId`	Get a customer	Customers
PATCH	`/customers/:customerId`	Update a customer	Customers
GET	`/tickets`	List tickets	Tickets
POST	`/tickets`	Create a ticket	Tickets
GET	`/tickets/:ticketId`	Get a ticket	Tickets
PATCH	`/tickets/:ticketId`	Update a ticket	Tickets
POST	`/tickets/:ticketId/assign`	Assign a ticket	Tickets
POST	`/tickets/:ticketId/reopen`	Reopen a ticket	Tickets
POST	`/tickets/:ticketId/escalate`	Escalate a ticket	Tickets
POST	`/tickets/:ticketId/messages`	Post a customer reply	Conversations
GET	`/teams`	List teams	Teams
POST	`/teams`	Create a team	Teams
GET	`/teams/:teamId`	Get a team	Teams
PATCH	`/teams/:teamId`	Rename a team	Teams
POST	`/teams/:teamId/members`	Add team members	Teams
DELETE	`/teams/:teamId/members`	Remove team members	Teams
DELETE	`/teams/:teamId`	Delete a team	Teams
GET	`/kb`	List articles	Knowledge base
POST	`/kb`	Create an article	Knowledge base
GET	`/kb/:articleSlug`	Get an article by slug	Knowledge base
PATCH	`/kb/:articleId`	Update an article	Knowledge base
DELETE	`/kb/:articleId`	Delete an article	Knowledge base
POST	`/attachments/tickets/:ticketId`	Start an upload	Attachments
GET	`/attachments/:attachmentId`	Get a download URL	Attachments

Customers

4 endpoints

Create and maintain the people who contact your support team. Customers are unique by email within an environment.

GET/customers

List customers

Returns customers in the authenticated environment, newest first.

Query parameters

Name	Type	Required	Description
`q`	`string`	No	Case-insensitive search across name, email, and phone. Email searches skip the phone match.
`page`	`integer`	No	Page number. Defaults to 1.
`perPage`	`integer`	No	Items per page. Defaults to 20, maximum 100.

Request

curl -X GET "https://api.desk.monesize.com/v1/api/customers?q=ada&page=1&perPage=20" \
  -H "Authorization: Bearer $DESK_API_KEY"

Response

{
  "message": "Customers fetched.",
  "data": [
    {
      "id": "9b1b6d3e-6f8c-4d7f-9f1a-1f2a3b4c5d6e",
      "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
      "coreTenantRef": null,
      "coreOrgName": null,
      "coreUserRef": null,
      "branchRef": null,
      "branchName": null,
      "coreRole": null,
      "email": "ada@acme.example",
      "name": "Ada Lovelace",
      "phone": "+1 555 0100",
      "createdAt": "2026-10-14T09:20:11.000Z",
      "updatedAt": "2026-10-14T09:20:11.000Z",
      "_count": { "tickets": 2 }
    }
  ],
  "meta": { "total": 1, "page": 1, "perPage": 20 }
}

Notes

Sensitive internal fields are omitted from examples.

POST/customers

Create a customer

Creates a customer record in the current environment. The email address must be unique within the environment.

Body parameters

Name	Type	Required	Description
`email`	`string`	Yes	Valid email address. Stored lowercase and trimmed.
`name`	`string`	Yes	Customer display name.
`phone`	`string`	No	Optional phone number.

Request

curl -X POST "https://api.desk.monesize.com/v1/api/customers" \
  -H "Authorization: Bearer $DESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@acme.example",
    "name": "Ada Lovelace",
    "phone": "+1 555 0100"
  }'

Response

{
  "message": "Customer created.",
  "data": {
    "id": "9b1b6d3e-6f8c-4d7f-9f1a-1f2a3b4c5d6e",
    "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
    "coreTenantRef": null,
    "coreOrgName": null,
    "coreUserRef": null,
    "branchRef": null,
    "branchName": null,
    "coreRole": null,
    "email": "ada@acme.example",
    "name": "Ada Lovelace",
    "phone": "+1 555 0100",
    "createdAt": "2026-10-14T09:20:11.000Z",
    "updatedAt": "2026-10-14T09:20:11.000Z"
  }
}

Endpoint errors

Status	Code	When
400	`VALIDATION_ERROR`	The email is invalid or the name is missing.
409	`CUSTOMER_EMAIL_TAKEN`	A customer with this email already exists.

GET/customers/:customerId

Get a customer

Returns one customer plus a compact history of their tickets, newest first.

Request

curl -X GET "https://api.desk.monesize.com/v1/api/customers/9b1b6d3e-6f8c-4d7f-9f1a-1f2a3b4c5d6e" \
  -H "Authorization: Bearer $DESK_API_KEY"

Response

{
  "message": "Customer fetched.",
  "data": {
    "id": "9b1b6d3e-6f8c-4d7f-9f1a-1f2a3b4c5d6e",
    "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
    "coreTenantRef": null,
    "coreOrgName": null,
    "coreUserRef": null,
    "branchRef": null,
    "branchName": null,
    "coreRole": null,
    "email": "ada@acme.example",
    "name": "Ada Lovelace",
    "phone": "+1 555 0100",
    "createdAt": "2026-10-14T09:20:11.000Z",
    "updatedAt": "2026-10-14T09:20:11.000Z",
    "tickets": [
      {
        "id": "2f6a8c1d-7e9b-4a3c-8d5f-0a1b2c3d4e5f",
        "ticketNumber": 1042,
        "subject": "Cannot sign in",
        "status": "OPEN",
        "priority": "HIGH",
        "createdAt": "2026-10-15T11:04:38.000Z"
      }
    ]
  }
}

Endpoint errors

Status	Code	When
404	`NOT_FOUND`	No customer with this id exists in the environment.

PATCH/customers/:customerId

Update a customer

Updates the editable customer fields. Fields left out of the request are unchanged.

Body parameters

Name	Type	Required	Description
`name`	`string`	No	New display name. Cannot be empty.
`email`	`string`	No	New email address. Must be valid and unique in the environment.
`phone`	`string \| null`	No	New phone number. Send null to clear it.

Request

curl -X PATCH "https://api.desk.monesize.com/v1/api/customers/9b1b6d3e-6f8c-4d7f-9f1a-1f2a3b4c5d6e" \
  -H "Authorization: Bearer $DESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada King",
    "phone": "+1 555 0199"
  }'

Response

{
  "message": "Customer updated.",
  "data": {
    "id": "9b1b6d3e-6f8c-4d7f-9f1a-1f2a3b4c5d6e",
    "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
    "email": "ada@acme.example",
    "name": "Ada King",
    "phone": "+1 555 0199",
    "createdAt": "2026-10-14T09:20:11.000Z",
    "updatedAt": "2026-10-16T08:12:04.000Z",
    "tickets": []
  }
}

Notes

Only name, email, and phone are documented as editable fields.

Endpoint errors

Status	Code	When
400	`VALIDATION_ERROR`	The name is empty or the email is invalid.
404	`NOT_FOUND`	No customer with this id exists in the environment.
409	`CUSTOMER_EMAIL_TAKEN`	The new email belongs to another customer.

Tickets

7 endpoints

Create tickets, move them through your queue, assign them to agents or teams, and write status changes to the audit trail.

GET/tickets

List tickets

Returns tickets ordered by last activity, newest first. Use it to build queues and inboxes.

Query parameters

Name	Type	Required	Description
`status`	`string`	No	One status or a comma-separated list: OPEN, IN_PROGRESS, WAITING_CUSTOMER, WAITING_INTERNAL, RESOLVED, CLOSED.
`priority`	`string`	No	LOW, MEDIUM, HIGH, or URGENT.
`category`	`string`	No	Exact category match.
`teamId`	`string`	No	Filter by assigned team id.
`agentId`	`string`	No	Filter by assigned desk user id.
`unassigned`	`boolean`	No	Set to true to return only tickets without an assigned user.
`page`	`integer`	No	Page number. Defaults to 1.
`perPage`	`integer`	No	Items per page. Defaults to 20, maximum 100.

Request

curl -X GET "https://api.desk.monesize.com/v1/api/tickets?status=OPEN,IN_PROGRESS&priority=HIGH&unassigned=true" \
  -H "Authorization: Bearer $DESK_API_KEY"

Response

{
  "message": "Tickets fetched.",
  "data": [
    {
      "id": "2f6a8c1d-7e9b-4a3c-8d5f-0a1b2c3d4e5f",
      "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
      "ticketNumber": 1042,
      "customerId": "9b1b6d3e-6f8c-4d7f-9f1a-1f2a3b4c5d6e",
      "subject": "Cannot sign in",
      "description": "I get a 500 error when I submit the login form.",
      "category": "ACCOUNT",
      "priority": "HIGH",
      "status": "OPEN",
      "assignedTeamId": null,
      "assignedUserId": null,
      "firstResponseAt": null,
      "resolvedAt": null,
      "closedAt": null,
      "reopenedAt": null,
      "createdAt": "2026-10-15T11:04:38.000Z",
      "lastActivityAt": "2026-10-15T11:04:38.000Z",
      "updatedAt": "2026-10-15T11:04:38.000Z",
      "customer": {
        "id": "9b1b6d3e-6f8c-4d7f-9f1a-1f2a3b4c5d6e",
        "name": "Ada Lovelace",
        "email": "ada@acme.example"
      },
      "assignedTeam": null,
      "assignedUser": null
    }
  ],
  "meta": { "total": 1, "page": 1, "perPage": 20 }
}

POST/tickets

Create a ticket

Creates a ticket and links it to an existing customer, or creates a customer when the email is new. New tickets start OPEN.

Body parameters

Name	Type	Required	Description
`customerEmail`	`string`	Yes	Email of the customer. Used to find an existing customer.
`customerName`	`string`	No	Required only when no customer exists with customerEmail.
`subject`	`string`	Yes	Short ticket subject. Trimmed before saving.
`description`	`string`	Yes	Ticket description. Trimmed before saving.
`category`	`string`	No	Free-form category label.
`priority`	`string`	No	LOW, MEDIUM, HIGH, or URGENT. Defaults to MEDIUM when omitted or not recognized.

Request

curl -X POST "https://api.desk.monesize.com/v1/api/tickets" \
  -H "Authorization: Bearer $DESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerEmail": "ada@acme.example",
    "customerName": "Ada Lovelace",
    "subject": "Cannot sign in",
    "description": "I get a 500 error when I submit the login form.",
    "category": "ACCOUNT",
    "priority": "HIGH"
  }'

Response

{
  "message": "Ticket created.",
  "data": {
    "id": "2f6a8c1d-7e9b-4a3c-8d5f-0a1b2c3d4e5f",
    "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
    "ticketNumber": 1042,
    "customerId": "9b1b6d3e-6f8c-4d7f-9f1a-1f2a3b4c5d6e",
    "subject": "Cannot sign in",
    "description": "I get a 500 error when I submit the login form.",
    "category": "ACCOUNT",
    "priority": "HIGH",
    "status": "OPEN",
    "assignedTeamId": null,
    "assignedUserId": null,
    "firstResponseAt": null,
    "resolvedAt": null,
    "closedAt": null,
    "reopenedAt": null,
    "createdAt": "2026-10-15T11:04:38.000Z",
    "lastActivityAt": "2026-10-15T11:04:38.000Z",
    "updatedAt": "2026-10-15T11:04:38.000Z",
    "customer": {
      "id": "9b1b6d3e-6f8c-4d7f-9f1a-1f2a3b4c5d6e",
      "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
      "email": "ada@acme.example",
      "name": "Ada Lovelace",
      "phone": "+1 555 0100",
      "createdAt": "2026-10-14T09:20:11.000Z",
      "updatedAt": "2026-10-14T09:20:11.000Z"
    }
  }
}

Notes

A new customer is created when the email is not found. In that case customerName is required.
The public API does not accept an assignee when creating a ticket. Assign it in a follow-up request.

Endpoint errors

Status	Code	When
400	`VALIDATION_ERROR`	The customer email, ticket subject, or description is invalid.
409	`CUSTOMER_EMAIL_TAKEN`	A customer creation race occurred for the same email.

GET/tickets/:ticketId

Get a ticket

Returns the full ticket with customer details, assignment, conversation, attachments, escalations, and audit trail.

Request

curl -X GET "https://api.desk.monesize.com/v1/api/tickets/2f6a8c1d-7e9b-4a3c-8d5f-0a1b2c3d4e5f" \
  -H "Authorization: Bearer $DESK_API_KEY"

Response

{
  "message": "Ticket fetched.",
  "data": {
    "id": "2f6a8c1d-7e9b-4a3c-8d5f-0a1b2c3d4e5f",
    "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
    "ticketNumber": 1042,
    "customerId": "9b1b6d3e-6f8c-4d7f-9f1a-1f2a3b4c5d6e",
    "subject": "Cannot sign in",
    "description": "I get a 500 error when I submit the login form.",
    "category": "ACCOUNT",
    "priority": "HIGH",
    "status": "OPEN",
    "assignedTeamId": null,
    "assignedUserId": null,
    "firstResponseAt": null,
    "resolvedAt": null,
    "closedAt": null,
    "reopenedAt": null,
    "createdAt": "2026-10-15T11:04:38.000Z",
    "lastActivityAt": "2026-10-15T11:04:38.000Z",
    "updatedAt": "2026-10-15T11:04:38.000Z",
    "customer": {
      "id": "9b1b6d3e-6f8c-4d7f-9f1a-1f2a3b4c5d6e",
      "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
      "email": "ada@acme.example",
      "name": "Ada Lovelace",
      "phone": "+1 555 0100",
      "createdAt": "2026-10-14T09:20:11.000Z",
      "updatedAt": "2026-10-14T09:20:11.000Z"
    },
    "assignedTeam": null,
    "assignedUser": null,
    "messages": [
      {
        "id": "5c7e9a1b-3d5f-4e7a-9b1c-2d3e4f5a6b7c",
        "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
        "ticketId": "2f6a8c1d-7e9b-4a3c-8d5f-0a1b2c3d4e5f",
        "authorType": "CUSTOMER",
        "authorUserId": null,
        "authorCustomerId": "9b1b6d3e-6f8c-4d7f-9f1a-1f2a3b4c5d6e",
        "visibility": "PUBLIC",
        "body": "I get a 500 error when I submit the login form.",
        "createdAt": "2026-10-15T11:04:38.000Z",
        "attachments": [],
        "authorUser": null,
        "authorCustomer": {
          "id": "9b1b6d3e-6f8c-4d7f-9f1a-1f2a3b4c5d6e",
          "name": "Ada Lovelace"
        }
      }
    ],
    "attachments": [],
    "escalations": [],
    "auditEvents": [
      {
        "id": "7e9f1a3b-5c7d-4e6f-8a9b-0c1d2e3f4a5b",
        "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
        "ticketId": "2f6a8c1d-7e9b-4a3c-8d5f-0a1b2c3d4e5f",
        "entityType": "TICKET",
        "entityId": "2f6a8c1d-7e9b-4a3c-8d5f-0a1b2c3d4e5f",
        "actorUserId": null,
        "action": "TICKET_CREATED",
        "description": "Created ticket \"Cannot sign in\"",
        "before": null,
        "after": { "subject": "Cannot sign in" },
        "createdAt": "2026-10-15T11:04:38.000Z"
      }
    ]
  }
}

Endpoint errors

Status	Code	When
404	`NOT_FOUND`	No ticket with this id exists in the environment.

PATCH/tickets/:ticketId

Update a ticket

Updates ticket fields and writes an audit event. Fields left out of the request are unchanged.

Body parameters

Name	Type	Required	Description
`subject`	`string`	No	New subject.
`category`	`string`	No	New category label.
`priority`	`string`	No	LOW, MEDIUM, HIGH, or URGENT.
`status`	`string`	No	OPEN, IN_PROGRESS, WAITING_CUSTOMER, WAITING_INTERNAL, RESOLVED, or CLOSED.

Request

curl -X PATCH "https://api.desk.monesize.com/v1/api/tickets/2f6a8c1d-7e9b-4a3c-8d5f-0a1b2c3d4e5f" \
  -H "Authorization: Bearer $DESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "RESOLVED",
    "priority": "URGENT",
    "category": "BILLING"
  }'

Response

{
  "message": "Ticket updated.",
  "data": {
    "id": "2f6a8c1d-7e9b-4a3c-8d5f-0a1b2c3d4e5f",
    "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
    "ticketNumber": 1042,
    "customerId": "9b1b6d3e-6f8c-4d7f-9f1a-1f2a3b4c5d6e",
    "subject": "Cannot sign in",
    "description": "I get a 500 error when I submit the login form.",
    "category": "BILLING",
    "priority": "URGENT",
    "status": "RESOLVED",
    "assignedTeamId": null,
    "assignedUserId": null,
    "firstResponseAt": null,
    "resolvedAt": "2026-10-16T10:31:45.000Z",
    "closedAt": null,
    "reopenedAt": null,
    "createdAt": "2026-10-15T11:04:38.000Z",
    "lastActivityAt": "2026-10-16T10:31:45.000Z",
    "updatedAt": "2026-10-16T10:31:45.000Z",
    "customer": {
      "id": "9b1b6d3e-6f8c-4d7f-9f1a-1f2a3b4c5d6e",
      "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
      "email": "ada@acme.example",
      "name": "Ada Lovelace",
      "phone": "+1 555 0100",
      "createdAt": "2026-10-14T09:20:11.000Z",
      "updatedAt": "2026-10-14T09:20:11.000Z"
    },
    "assignedTeam": null,
    "assignedUser": null
  }
}

Notes

Setting status to RESOLVED or CLOSED records the matching timestamp.
Setting status to OPEN from RESOLVED or CLOSED records reopenedAt.

Endpoint errors

Status	Code	When
400	`VALIDATION_ERROR`	The priority or status is not recognized.
404	`NOT_FOUND`	No ticket with this id exists in the environment.

POST/tickets/:ticketId/assign

Assign a ticket

Assigns a ticket to a desk user, a team, both, or neither. The endpoint replaces the current assignment.

Body parameters

Name	Type	Required	Description
`userId`	`string \| null`	No	Desk user id with role ADMIN, MANAGER, or AGENT. Omit or send null to clear the user assignment.
`teamId`	`string \| null`	No	Team id in the environment. Omit or send null to clear the team assignment.

Request

curl -X POST "https://api.desk.monesize.com/v1/api/tickets/2f6a8c1d-7e9b-4a3c-8d5f-0a1b2c3d4e5f/assign" \
  -H "Authorization: Bearer $DESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "4a5b6c7d-8e9f-4a1b-9c2d-3e4f5a6b7c8d",
    "teamId": "6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e"
  }'

Response

{
  "message": "Ticket assigned.",
  "data": {
    "id": "2f6a8c1d-7e9b-4a3c-8d5f-0a1b2c3d4e5f",
    "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
    "ticketNumber": 1042,
    "customerId": "9b1b6d3e-6f8c-4d7f-9f1a-1f2a3b4c5d6e",
    "subject": "Cannot sign in",
    "description": "I get a 500 error when I submit the login form.",
    "category": "ACCOUNT",
    "priority": "HIGH",
    "status": "OPEN",
    "assignedTeamId": "6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e",
    "assignedUserId": "4a5b6c7d-8e9f-4a1b-9c2d-3e4f5a6b7c8d",
    "firstResponseAt": null,
    "resolvedAt": null,
    "closedAt": null,
    "reopenedAt": null,
    "createdAt": "2026-10-15T11:04:38.000Z",
    "lastActivityAt": "2026-10-16T11:02:09.000Z",
    "updatedAt": "2026-10-16T11:02:09.000Z",
    "customer": {
      "id": "9b1b6d3e-6f8c-4d7f-9f1a-1f2a3b4c5d6e",
      "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
      "email": "ada@acme.example",
      "name": "Ada Lovelace",
      "phone": "+1 555 0100",
      "createdAt": "2026-10-14T09:20:11.000Z",
      "updatedAt": "2026-10-14T09:20:11.000Z"
    },
    "assignedTeam": {
      "id": "6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e",
      "name": "Billing"
    },
    "assignedUser": {
      "id": "4a5b6c7d-8e9f-4a1b-9c2d-3e4f5a6b7c8d",
      "name": "Grace Hopper",
      "email": "grace@monesize.example"
    }
  }
}

Notes

Send {} or omit both fields to remove both assignments.
Assigning a user creates an in-app notification for that user.

Endpoint errors

Status	Code	When
404	`NOT_FOUND`	The ticket, user, or team does not exist in the environment.

POST/tickets/:ticketId/reopen

Reopen a ticket

Sets the ticket status to OPEN. Resolved and closed tickets also get a reopenedAt timestamp and an audit event.

Request

curl -X POST "https://api.desk.monesize.com/v1/api/tickets/2f6a8c1d-7e9b-4a3c-8d5f-0a1b2c3d4e5f/reopen" \
  -H "Authorization: Bearer $DESK_API_KEY"

Response

{
  "message": "Ticket reopened.",
  "data": {
    "id": "2f6a8c1d-7e9b-4a3c-8d5f-0a1b2c3d4e5f",
    "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
    "ticketNumber": 1042,
    "customerId": "9b1b6d3e-6f8c-4d7f-9f1a-1f2a3b4c5d6e",
    "subject": "Cannot sign in",
    "description": "I get a 500 error when I submit the login form.",
    "category": "ACCOUNT",
    "priority": "HIGH",
    "status": "OPEN",
    "assignedTeamId": null,
    "assignedUserId": null,
    "firstResponseAt": null,
    "resolvedAt": "2026-10-16T10:31:45.000Z",
    "closedAt": null,
    "reopenedAt": "2026-10-16T12:14:20.000Z",
    "createdAt": "2026-10-15T11:04:38.000Z",
    "lastActivityAt": "2026-10-16T12:14:20.000Z",
    "updatedAt": "2026-10-16T12:14:20.000Z",
    "customer": {
      "id": "9b1b6d3e-6f8c-4d7f-9f1a-1f2a3b4c5d6e",
      "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
      "email": "ada@acme.example",
      "name": "Ada Lovelace",
      "phone": "+1 555 0100",
      "createdAt": "2026-10-14T09:20:11.000Z",
      "updatedAt": "2026-10-14T09:20:11.000Z"
    },
    "assignedTeam": null,
    "assignedUser": null
  }
}

Endpoint errors

Status	Code	When
404	`NOT_FOUND`	No ticket with this id exists in the environment.

POST/tickets/:ticketId/escalate

Escalate a ticket

Records an escalation with a required reason. Escalating does not change the ticket status or assignment.

Body parameters

Name	Type	Required	Description
`reason`	`string`	Yes	Why the ticket is being escalated.
`toTeamId`	`string`	No	Receiving team id. Must exist in the environment.
`fromTeamId`	`string`	No	Originating team id, recorded for context.

Request

curl -X POST "https://api.desk.monesize.com/v1/api/tickets/2f6a8c1d-7e9b-4a3c-8d5f-0a1b2c3d4e5f/escalate" \
  -H "Authorization: Bearer $DESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fromTeamId": "6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e",
    "toTeamId": "8d9e0f1a-2b3c-4d5e-8f6a-7b8c9d0e1f2a",
    "reason": "Needs a billing specialist."
  }'

Response

{
  "message": "Ticket escalated.",
  "data": {
    "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
    "ticketId": "2f6a8c1d-7e9b-4a3c-8d5f-0a1b2c3d4e5f",
    "fromTeamId": "6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e",
    "toTeamId": "8d9e0f1a-2b3c-4d5e-8f6a-7b8c9d0e1f2a",
    "reason": "Needs a billing specialist.",
    "status": "OPEN",
    "createdBy": null,
    "createdAt": "2026-10-16T12:40:02.000Z"
  }
}

Notes

The response is the escalation record, not the ticket.

Endpoint errors

Status	Code	When
400	`VALIDATION_ERROR`	The reason is missing.
404	`NOT_FOUND`	The ticket or target team does not exist in the environment.

Conversations

1 endpoints

Post customer-visible replies to a ticket. The public API does not create agent replies or internal notes.

POST/tickets/:ticketId/messages

Post a customer reply

Adds a public message authored by the ticket customer. This endpoint represents the customer, not an agent.

Body parameters

Name	Type	Required	Description
`body`	`string`	Yes	Message body. Trimmed before saving.
`customerEmail`	`string`	No	Optional customer email to author the reply as. It must match the ticket's customer. A different customer returns 403.

Request

curl -X POST "https://api.desk.monesize.com/v1/api/tickets/2f6a8c1d-7e9b-4a3c-8d5f-0a1b2c3d4e5f/messages" \
  -H "Authorization: Bearer $DESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "The error is still happening after clearing my cache.",
    "customerEmail": "ada@acme.example"
  }'

Response

{
  "message": "Reply posted.",
  "data": {
    "id": "3b4c5d6e-7f8a-4b9c-8d0e-1f2a3b4c5d6e",
    "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
    "ticketId": "2f6a8c1d-7e9b-4a3c-8d5f-0a1b2c3d4e5f",
    "authorType": "CUSTOMER",
    "authorUserId": null,
    "authorCustomerId": "9b1b6d3e-6f8c-4d7f-9f1a-1f2a3b4c5d6e",
    "visibility": "PUBLIC",
    "body": "The error is still happening after clearing my cache.",
    "createdAt": "2026-10-16T13:02:54.000Z"
  }
}

Notes

Customer replies reopen resolved or closed tickets by setting the status to OPEN.
The assigned agent receives an in-app notification when the ticket has an assignee.
There is no public endpoint for internal notes or agent-authored replies.

Endpoint errors

Status	Code	When
400	`VALIDATION_ERROR`	The message body is missing or the ticket has no customer.
403	`FORBIDDEN`	The customer email belongs to a different customer than the ticket owner.
404	`NOT_FOUND`	The ticket or customer email does not exist in the environment.

Teams

7 endpoints

Organize desk users into teams. Teams can receive ticket assignments and appear in escalations.

GET/teams

List teams

Returns every team in the environment, sorted by name, with members and assigned ticket counts.

Request

curl -X GET "https://api.desk.monesize.com/v1/api/teams" \
  -H "Authorization: Bearer $DESK_API_KEY"

Response

{
  "message": "Teams fetched.",
  "data": [
    {
      "id": "6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e",
      "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
      "name": "Billing",
      "createdAt": "2026-09-30T08:00:00.000Z",
      "updatedAt": "2026-09-30T08:00:00.000Z",
      "members": [
        {
          "id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
          "teamId": "6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e",
          "userId": "4a5b6c7d-8e9f-4a1b-9c2d-3e4f5a6b7c8d",
          "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
          "user": {
            "id": "4a5b6c7d-8e9f-4a1b-9c2d-3e4f5a6b7c8d",
            "name": "Grace Hopper",
            "email": "grace@monesize.example",
            "role": "AGENT"
          }
        }
      ],
      "_count": { "assignedTickets": 12 }
    }
  ]
}

POST/teams

Create a team

Creates a team with an optional initial member list. Team names must be unique within the environment.

Body parameters

Name	Type	Required	Description
`name`	`string`	Yes	Team name. Trimmed before saving.
`memberIds`	`string[]`	No	Optional desk user ids to add as initial members.

Request

curl -X POST "https://api.desk.monesize.com/v1/api/teams" \
  -H "Authorization: Bearer $DESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Billing",
    "memberIds": ["4a5b6c7d-8e9f-4a1b-9c2d-3e4f5a6b7c8d"]
  }'

Response

{
  "message": "Team created.",
  "data": {
    "id": "6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e",
    "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
    "name": "Billing",
    "createdAt": "2026-10-17T07:45:12.000Z",
    "updatedAt": "2026-10-17T07:45:12.000Z",
    "members": [
      {
        "id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
        "teamId": "6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e",
        "userId": "4a5b6c7d-8e9f-4a1b-9c2d-3e4f5a6b7c8d",
        "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
        "user": {
          "id": "4a5b6c7d-8e9f-4a1b-9c2d-3e4f5a6b7c8d",
          "name": "Grace Hopper",
          "email": "grace@monesize.example",
          "role": "AGENT"
        }
      }
    ]
  }
}

Notes

Initial member ids are not validated with a friendly error before insert. Confirm desk user ids with your Desk admin.

Endpoint errors

Status	Code	When
400	`VALIDATION_ERROR`	The team name is missing.
409	`TEAM_NAME_TAKEN`	A team with this name already exists.

GET/teams/:teamId

Get a team

Returns one team with its members and assigned ticket count.

Request

curl -X GET "https://api.desk.monesize.com/v1/api/teams/6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e" \
  -H "Authorization: Bearer $DESK_API_KEY"

Response

{
  "message": "Team fetched.",
  "data": {
    "id": "6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e",
    "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
    "name": "Billing",
    "createdAt": "2026-09-30T08:00:00.000Z",
    "updatedAt": "2026-09-30T08:00:00.000Z",
    "members": [
      {
        "id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
        "teamId": "6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e",
        "userId": "4a5b6c7d-8e9f-4a1b-9c2d-3e4f5a6b7c8d",
        "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
        "user": {
          "id": "4a5b6c7d-8e9f-4a1b-9c2d-3e4f5a6b7c8d",
          "name": "Grace Hopper",
          "email": "grace@monesize.example",
          "role": "AGENT"
        }
      }
    ],
    "_count": { "assignedTickets": 12 }
  }
}

Endpoint errors

Status	Code	When
404	`NOT_FOUND`	No team with this id exists in the environment.

PATCH/teams/:teamId

Rename a team

Changes the team name. The new name must not belong to another team.

Body parameters

Name	Type	Required	Description
`name`	`string`	Yes	New team name. Trimmed before saving.

Request

curl -X PATCH "https://api.desk.monesize.com/v1/api/teams/6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e" \
  -H "Authorization: Bearer $DESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Billing and payments" }'

Response

{
  "message": "Team renamed.",
  "data": {
    "id": "6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e",
    "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
    "name": "Billing and payments",
    "createdAt": "2026-09-30T08:00:00.000Z",
    "updatedAt": "2026-10-17T08:20:31.000Z",
    "members": [],
    "_count": { "assignedTickets": 12 }
  }
}

Endpoint errors

Status	Code	When
400	`VALIDATION_ERROR`	The team name is missing.
404	`NOT_FOUND`	No team with this id exists in the environment.
409	`TEAM_NAME_TAKEN`	Another team already uses this name.

POST/teams/:teamId/members

Add team members

Adds desk users to a team. Existing memberships are skipped.

Body parameters

Name	Type	Required	Description
`memberIds`	`string[]`	Yes	Desk user ids to add. Every id must exist in the environment.

Request

curl -X POST "https://api.desk.monesize.com/v1/api/teams/6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e/members" \
  -H "Authorization: Bearer $DESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "memberIds": ["4a5b6c7d-8e9f-4a1b-9c2d-3e4f5a6b7c8d"] }'

Response

{
  "message": "Team members added.",
  "data": {
    "id": "6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e",
    "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
    "name": "Billing",
    "createdAt": "2026-09-30T08:00:00.000Z",
    "updatedAt": "2026-09-30T08:00:00.000Z",
    "members": [
      {
        "id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
        "teamId": "6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e",
        "userId": "4a5b6c7d-8e9f-4a1b-9c2d-3e4f5a6b7c8d",
        "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
        "user": {
          "id": "4a5b6c7d-8e9f-4a1b-9c2d-3e4f5a6b7c8d",
          "name": "Grace Hopper",
          "email": "grace@monesize.example",
          "role": "AGENT"
        }
      }
    ],
    "_count": { "assignedTickets": 12 }
  }
}

Endpoint errors

Status	Code	When
404	`MEMBER_NOT_FOUND`	One or more user ids do not exist in the environment.
404	`NOT_FOUND`	No team with this id exists in the environment.

DELETE/teams/:teamId/members

Remove team members

Removes desk users from a team. Ids that are not members are ignored.

Body parameters

Name	Type	Required	Description
`memberIds`	`string[]`	Yes	Desk user ids to remove.

Request

curl -X DELETE "https://api.desk.monesize.com/v1/api/teams/6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e/members" \
  -H "Authorization: Bearer $DESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "memberIds": ["4a5b6c7d-8e9f-4a1b-9c2d-3e4f5a6b7c8d"] }'

Response

{
  "message": "Team members removed.",
  "data": {
    "id": "6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e",
    "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
    "name": "Billing",
    "createdAt": "2026-09-30T08:00:00.000Z",
    "updatedAt": "2026-09-30T08:00:00.000Z",
    "members": [],
    "_count": { "assignedTickets": 12 }
  }
}

Endpoint errors

Status	Code	When
404	`NOT_FOUND`	No team with this id exists in the environment.

DELETE/teams/:teamId

Delete a team

Deletes a team. Tickets assigned to the team stay in place and become unassigned. Escalation and invite references to the team are cleared.

Request

curl -X DELETE "https://api.desk.monesize.com/v1/api/teams/6b7c8d9e-0f1a-4b2c-8d3e-4f5a6b7c8d9e" \
  -H "Authorization: Bearer $DESK_API_KEY"

Response

{
  "message": "Team deleted.",
  "data": true
}

Notes

This operation is not reversible. The tickets themselves are not deleted.

Endpoint errors

Status	Code	When
404	`NOT_FOUND`	No team with this id exists in the environment.

Knowledge base

5 endpoints

Publish help content and keep drafts in sync with the Desk knowledge base.

GET/kb

List articles

Returns knowledge base articles ordered by last update. The public API can see drafts.

Query parameters

Name	Type	Required	Description
`q`	`string`	No	Case-insensitive search across title and body.
`visibility`	`string`	No	published, draft, or all. Defaults to all.
`page`	`integer`	No	Page number. Defaults to 1.
`perPage`	`integer`	No	Items per page. Defaults to 20, maximum 100.

Request

curl -X GET "https://api.desk.monesize.com/v1/api/kb?q=refund&visibility=published&page=1&perPage=20" \
  -H "Authorization: Bearer $DESK_API_KEY"

Response

{
  "message": "Articles fetched.",
  "data": [
    {
      "id": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f8a",
      "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
      "title": "How refunds work",
      "slug": "how-refunds-work",
      "body": "Refunds are reviewed within two business days.",
      "isPublished": true,
      "portalVisible": true,
      "authorId": null,
      "createdAt": "2026-10-01T10:00:00.000Z",
      "updatedAt": "2026-10-10T14:30:00.000Z"
    }
  ],
  "meta": { "total": 1, "page": 1, "perPage": 20 }
}

POST/kb

Create an article

Creates a knowledge base article. A slug is generated from the title when you do not provide one.

Body parameters

Name	Type	Required	Description
`title`	`string`	Yes	Article title. Trimmed before saving.
`body`	`string`	Yes	Article body. Plain text or HTML, stored as provided after trimming.
`isPublished`	`boolean`	No	Publish state. Defaults to false.
`portalVisible`	`boolean`	No	Whether the article can appear in the customer portal. Defaults to false.
`slug`	`string`	No	Custom URL slug. Lowercased and sanitized. Defaults to a slugified title.

Request

curl -X POST "https://api.desk.monesize.com/v1/api/kb" \
  -H "Authorization: Bearer $DESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "How refunds work",
    "body": "Refunds are reviewed within two business days.",
    "isPublished": true,
    "portalVisible": true
  }'

Response

{
  "message": "Article created.",
  "data": {
    "id": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f8a",
    "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
    "title": "How refunds work",
    "slug": "how-refunds-work",
    "body": "Refunds are reviewed within two business days.",
    "isPublished": true,
    "portalVisible": true,
    "authorId": null,
    "createdAt": "2026-10-01T10:00:00.000Z",
    "updatedAt": "2026-10-01T10:00:00.000Z"
  }
}

Endpoint errors

Status	Code	When
400	`VALIDATION_ERROR`	The title or body is missing.
409	`KB_SLUG_TAKEN`	An article with this slug already exists.

GET/kb/:articleSlug

Get an article by slug

Returns one article by its slug. Drafts are visible to API keys.

Request

curl -X GET "https://api.desk.monesize.com/v1/api/kb/how-refunds-work" \
  -H "Authorization: Bearer $DESK_API_KEY"

Response

{
  "message": "Article fetched.",
  "data": {
    "id": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f8a",
    "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
    "title": "How refunds work",
    "slug": "how-refunds-work",
    "body": "Refunds are reviewed within two business days.",
    "isPublished": true,
    "portalVisible": true,
    "authorId": null,
    "createdAt": "2026-10-01T10:00:00.000Z",
    "updatedAt": "2026-10-10T14:30:00.000Z"
  }
}

Notes

Use the slug for reads. Updates and deletes take the article id.

Endpoint errors

Status	Code	When
404	`NOT_FOUND`	No article with this slug exists in the environment.

PATCH/kb/:articleId

Update an article

Updates article fields by id. Fields left out of the request are unchanged.

Body parameters

Name	Type	Required	Description
`title`	`string`	No	New title. Cannot be empty.
`body`	`string`	No	New body. Cannot be empty.
`slug`	`string`	No	New URL slug. Lowercased and sanitized. Must be unique.
`isPublished`	`boolean`	No	Publish state.
`portalVisible`	`boolean`	No	Whether the article can appear in the customer portal.

Request

curl -X PATCH "https://api.desk.monesize.com/v1/api/kb/5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f8a" \
  -H "Authorization: Bearer $DESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "How refunds work",
    "slug": "refund-policy",
    "body": "Refunds are reviewed within two business days. You will receive an email when the refund is issued.",
    "isPublished": true
  }'

Response

{
  "message": "Article updated.",
  "data": {
    "id": "5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f8a",
    "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
    "title": "How refunds work",
    "slug": "refund-policy",
    "body": "Refunds are reviewed within two business days. You will receive an email when the refund is issued.",
    "isPublished": true,
    "portalVisible": true,
    "authorId": null,
    "createdAt": "2026-10-01T10:00:00.000Z",
    "updatedAt": "2026-10-17T09:12:44.000Z"
  }
}

Notes

Changing the slug changes the URL used by Get an article. The response reflects the new slug.

Endpoint errors

Status	Code	When
400	`VALIDATION_ERROR`	The title or body is empty.
404	`NOT_FOUND`	No article with this id exists in the environment.
409	`KB_SLUG_TAKEN`	The requested slug is already in use.

DELETE/kb/:articleId

Delete an article

Permanently deletes an article by id.

Request

curl -X DELETE "https://api.desk.monesize.com/v1/api/kb/5d6e7f8a-9b0c-4d1e-8f2a-3b4c5d6e7f8a" \
  -H "Authorization: Bearer $DESK_API_KEY"

Response

{
  "message": "Article deleted.",
  "data": true
}

Notes

This operation is not reversible.

Endpoint errors

Status	Code	When
404	`NOT_FOUND`	No article with this id exists in the environment.

Attachments

2 endpoints

Upload and download ticket attachments through short-lived presigned S3 URLs.

POST/attachments/tickets/:ticketId

Start an upload

Creates attachment metadata and returns a presigned S3 PUT URL. Upload the file bytes directly to that URL.

Body parameters

Name	Type	Required	Description
`fileName`	`string`	Yes	Original file name, at most 255 characters.
`mimeType`	`string`	Yes	One of the allowed MIME types listed below.
`sizeBytes`	`integer`	Yes	File size in bytes. Must be greater than 0 and at most 10 MB.

Request

curl -X POST "https://api.desk.monesize.com/v1/api/attachments/tickets/2f6a8c1d-7e9b-4a3c-8d5f-0a1b2c3d4e5f" \
  -H "Authorization: Bearer $DESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "screenshot.png",
    "mimeType": "image/png",
    "sizeBytes": 184320
  }'

Response

{
  "message": "Upload started.",
  "data": {
    "attachment": {
      "id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
      "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
      "ticketId": "2f6a8c1d-7e9b-4a3c-8d5f-0a1b2c3d4e5f",
      "messageId": null,
      "fileName": "screenshot.png",
      "mimeType": "image/png",
      "sizeBytes": 184320,
      "s3Key": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e/tickets/2f6a8c1d-7e9b-4a3c-8d5f-0a1b2c3d4e5f/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d_screenshot.png",
      "createdAt": "2026-10-17T10:04:00.000Z"
    },
    "uploadUrl": "https://desk-attachments.s3.amazonaws.com/...presigned-put-url..."
  }
}

Notes

Allowed MIME types: application/pdf, image/png, image/jpeg, text/plain, text/csv, application/msword, and application/vnd.openxmlformats-officedocument.wordprocessingml.document.
Presigned URLs expire after five minutes by default.
When you PUT the file, send the same Content-Type value you used here.
Attachments require the INTERNAL or CORE plan.

Endpoint errors

Status	Code	When
400	`VALIDATION_ERROR`	The file name, MIME type, or size is not accepted.
403	`ATTACHMENTS_NOT_ALLOWED_PLAN`	The environment plan does not include attachments.
404	`NOT_FOUND`	No ticket with this id exists in the environment.

GET/attachments/:attachmentId

Get a download URL

Returns attachment metadata and a short-lived presigned GET URL for downloading the file.

Request

curl -X GET "https://api.desk.monesize.com/v1/api/attachments/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d" \
  -H "Authorization: Bearer $DESK_API_KEY"

Response

{
  "message": "Attachment URL resolved.",
  "data": {
    "attachment": {
      "id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
      "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
      "ticketId": "2f6a8c1d-7e9b-4a3c-8d5f-0a1b2c3d4e5f",
      "messageId": null,
      "fileName": "screenshot.png",
      "mimeType": "image/png",
      "sizeBytes": 184320,
      "s3Key": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e/tickets/2f6a8c1d-7e9b-4a3c-8d5f-0a1b2c3d4e5f/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d_screenshot.png",
      "createdAt": "2026-10-17T10:04:00.000Z",
      "message": null,
      "ticket": {
        "id": "2f6a8c1d-7e9b-4a3c-8d5f-0a1b2c3d4e5f",
        "tenantId": "8b2d4c6e-1a3f-4b5d-8c7e-9f0a1b2c3d4e",
        "ticketNumber": 1042,
        "customerId": "9b1b6d3e-6f8c-4d7f-9f1a-1f2a3b4c5d6e",
        "subject": "Cannot sign in",
        "description": "I get a 500 error when I submit the login form.",
        "category": "ACCOUNT",
        "priority": "HIGH",
        "status": "OPEN",
        "assignedTeamId": null,
        "assignedUserId": null,
        "firstResponseAt": null,
        "resolvedAt": null,
        "closedAt": null,
        "reopenedAt": null,
        "createdAt": "2026-10-15T11:04:38.000Z",
        "lastActivityAt": "2026-10-16T13:02:54.000Z",
        "updatedAt": "2026-10-16T13:02:54.000Z"
      }
    },
    "url": "https://desk-attachments.s3.amazonaws.com/...presigned-get-url..."
  }
}

Notes

Presigned URLs expire after five minutes by default.

Endpoint errors

Status	Code	When
404	`NOT_FOUND`	No attachment with this id exists in the environment.

Enumerations

These are the only accepted values for enum fields. Values are case-sensitive.

TicketStatus

Ticket workflow state.

OPENIN_PROGRESSWAITING_CUSTOMERWAITING_INTERNALRESOLVEDCLOSED

Priority

Ticket priority. New tickets default to MEDIUM.

LOWMEDIUMHIGHURGENT

AuthorType

Author of a conversation message.

CUSTOMERAGENTSYSTEM

Visibility

Message visibility. Public API replies are always PUBLIC.

PUBLICINTERNAL

EscalationStatus

Escalation state. New escalations start OPEN.

OPENACCEPTEDRESOLVEDREJECTED

ApiKeyEnvironment

Environment selected when the key is created.

TESTPRODUCTION

Role

Desk user role returned on team members.

ADMINMANAGERAGENT

Object reference

Field names match the JSON responses. Examples in this reference omit internal credential fields that are not intended for client use.

Customer

Field	Type	Description
`id`	`string`	Customer id (UUID).
`tenantId`	`string`	Environment id (UUID).
`email`	`string`	Unique email within the environment.
`name`	`string`	Display name.
`phone`	`string \| null`	Optional phone number.
`createdAt`	`string`	ISO 8601 timestamp.
`updatedAt`	`string`	ISO 8601 timestamp.
`tickets`	`array`	Present on get. Compact ticket history.
`_count`	`object`	Present on list. Contains tickets count.

Ticket

Field	Type	Description
`id`	`string`	Ticket id (UUID).
`tenantId`	`string`	Environment id.
`ticketNumber`	`integer`	Sequential number within the environment.
`customerId`	`string \| null`	Owning customer id.
`subject`	`string`	Ticket subject.
`description`	`string`	Initial ticket description.
`category`	`string \| null`	Free-form category.
`priority`	`string`	Priority enum.
`status`	`string`	Ticket status enum.
`assignedTeamId`	`string \| null`	Assigned team id.
`assignedUserId`	`string \| null`	Assigned desk user id.
`firstResponseAt`	`string \| null`	First agent response time.
`resolvedAt`	`string \| null`	Last time the ticket was resolved.
`closedAt`	`string \| null`	Last time the ticket was closed.
`reopenedAt`	`string \| null`	Last time the ticket was reopened.
`createdAt`	`string`	ISO 8601 timestamp.
`lastActivityAt`	`string`	Updated by messages and assignments.
`updatedAt`	`string`	ISO 8601 timestamp.

Team

Field	Type	Description
`id`	`string`	Team id (UUID).
`tenantId`	`string`	Environment id.
`name`	`string`	Unique team name.
`createdAt`	`string`	ISO 8601 timestamp.
`updatedAt`	`string`	ISO 8601 timestamp.
`members`	`array`	Team memberships with user details.
`_count`	`object`	Present on get and list. Contains assignedTickets.

KBArticle

Field	Type	Description
`id`	`string`	Article id (UUID).
`tenantId`	`string`	Environment id.
`title`	`string`	Article title.
`slug`	`string`	Unique slug within the environment.
`body`	`string`	Article content.
`isPublished`	`boolean`	Publication state.
`portalVisible`	`boolean`	Whether the portal may show the article.
`authorId`	`string \| null`	Author desk user id. Public API articles have null.
`createdAt`	`string`	ISO 8601 timestamp.
`updatedAt`	`string`	ISO 8601 timestamp.

Attachment

Field	Type	Description
`id`	`string`	Attachment id (UUID).
`tenantId`	`string`	Environment id.
`ticketId`	`string \| null`	Owning ticket id.
`messageId`	`string \| null`	Owning message id, when attached to a message.
`fileName`	`string`	Original file name.
`mimeType`	`string`	Validated MIME type.
`sizeBytes`	`integer`	File size in bytes.
`s3Key`	`string`	Internal storage key.
`createdAt`	`string`	ISO 8601 timestamp.

ConversationMessage

Field	Type	Description
`id`	`string`	Message id (UUID).
`tenantId`	`string`	Environment id.
`ticketId`	`string`	Owning ticket id.
`authorType`	`string`	Author type enum.
`authorUserId`	`string \| null`	Agent author id.
`authorCustomerId`	`string \| null`	Customer author id.
`visibility`	`string`	Visibility enum.
`body`	`string`	Message body.
`createdAt`	`string`	ISO 8601 timestamp.

Escalation

Field	Type	Description
`id`	`string`	Escalation id (UUID).
`tenantId`	`string`	Environment id.
`ticketId`	`string`	Escalated ticket id.
`fromTeamId`	`string \| null`	Originating team id.
`toTeamId`	`string \| null`	Receiving team id.
`reason`	`string`	Escalation reason.
`status`	`string`	Escalation status enum.
`createdBy`	`string \| null`	Desk user id. Public API escalations have null.
`createdAt`	`string`	ISO 8601 timestamp.