Introduction

Tickets API

Overview

Organisation-scoped tickets and collaboration. Tenancy from Directory JWT orgId. Staff notifications are emitted to Communications; org master data lives in Directory.

Integration guide: Tickets service docs

OpenAPI v0.1.0 · source openapi/tickets.json

OpenAPI 3.0.0 · v0.1.0 · 17 operations

Operations

System

Liveness and generated documentation.

get/health

Health check

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/tickets/health"

Unauthenticated liveness probe. Does not verify D1, R2, or queues.

Operation ID: getHealth

Responses

200
Service is running
application/json

get/v1/health

Health check (versioned)

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/tickets/v1/health"

Unauthenticated liveness probe. Does not verify D1, R2, or queues.

Operation ID: getHealthV1

Responses

200
Service is running
application/json

Audit

get/v1/audit

Tickets audit trail

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/tickets/v1/audit"

Lists audit events for the organisation in the JWT (`orgId`).

Operation ID: listTicketsAudit

Responses

200
Audit events
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: invalid request body or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Tickets

Issue records and lifecycle commands.

get/v1/tickets

List tickets

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/tickets/v1/tickets"

Cursor-paginated ticket list. Non-admins only see tickets they opened.

Operation ID: listTickets

Parameters

Name	In	Type	Description
limit	query	integer	—
cursor	query	string	—
status	query	string	—
priority	query	string	—
reporterId	query	string (uuid)	—
assigneeId	query	string (uuid)	—
teamId	query	string (uuid)	—
number	query	string	Human-readable ticket number (INC-n).
category	query	string	—
source	query	string	—
externalReference	query	string	—
tag	query	string	—
q	query	string	—
createdAfter	query	string	—
createdBefore	query	string	—
updatedAfter	query	string	—
updatedBefore	query	string	—
resolvedAfter	query	string	—
resolvedBefore	query	string	—

Responses

200
Ticket page
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: invalid request body or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/tickets

Create a ticket

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/tickets/v1/tickets"

Creates a ticket in OPEN. Status cannot be set here; use POST /v1/tickets/{id}/transitions. Supports Idempotency-Key.

Operation ID: createTicket

Request body(required)

application/jsonTicketCreate

Responses

201
Created ticket
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, VERSION_CONFLICT, INVALID_STATE_TRANSITION, or IDEMPOTENCY_CONFLICT.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: invalid request body or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/tickets/external

Create or update an externally sourced ticket

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/tickets/v1/tickets/external"

Idempotent upsert keyed by `externalReference`. Venue exceptions use `source=venue` and `externalReference=venue:{id}`. Status may be set directly for this integration.

Operation ID: upsertExternalTicket

Request body(required)

application/jsonExternalTicketUpsert

Responses

200
Upserted ticket
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, VERSION_CONFLICT, INVALID_STATE_TRANSITION, or IDEMPOTENCY_CONFLICT.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: invalid request body or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/tickets/{id}

Get a ticket

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/tickets/v1/tickets/example-id"

Fetch a ticket by UUID, including its activity history. Use `GET /v1/tickets?number=INC-n` to resolve by human-readable number. Staff alerts are delivered via Communications (`/v1/notifications`).

Operation ID: getTicket

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Ticket id within the caller's organisation.

Responses

200
Ticket
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: invalid request body or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

patch/v1/tickets/{id}

Update ticket metadata

Example request

curl -sS \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/tickets/v1/tickets/example-id"

Does not change status. `version` is required; stale versions return 409 VERSION_CONFLICT.

Operation ID: updateTicket

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Ticket id within the caller's organisation.

Request body(required)

application/jsonTicketPatch

Responses

200
Updated ticket
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, VERSION_CONFLICT, INVALID_STATE_TRANSITION, or IDEMPOTENCY_CONFLICT.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: invalid request body or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/tickets/{id}/transitions

Transition ticket status

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/tickets/v1/tickets/example-id/transitions"

Lifecycle command. Owners may resolve, close, or reopen their own tickets. Administrators must self-assign before other transitions.

Operation ID: transitionTicket

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Ticket id within the caller's organisation.

Request body(required)

application/jsonTicketTransition

Responses

200
Ticket after transition
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, VERSION_CONFLICT, INVALID_STATE_TRANSITION, or IDEMPOTENCY_CONFLICT.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: invalid request body or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/tickets/{id}/escalations

Escalate a ticket

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/tickets/v1/tickets/example-id/escalations"

Records an escalation event. `admin` only.

Operation ID: escalateTicket

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Ticket id within the caller's organisation.

Request body(required)

application/jsonTicketEscalation

Responses

200
Ticket after escalation
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, VERSION_CONFLICT, INVALID_STATE_TRANSITION, or IDEMPOTENCY_CONFLICT.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: invalid request body or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Assignments

User and team assignment.

post/v1/tickets/{id}/assignments

Assign a ticket

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/tickets/v1/tickets/example-id/assignments"

Assign yourself to a ticket. `assigneeId` must be your own user id, or null to release an assignment you hold.

Operation ID: assignTicket

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Ticket id within the caller's organisation.

Request body(required)

application/jsonTicketAssignment

Responses

200
Ticket after assignment
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, VERSION_CONFLICT, INVALID_STATE_TRANSITION, or IDEMPOTENCY_CONFLICT.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: invalid request body or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Comments

Public and internal comments.

get/v1/tickets/{id}/comments

List comments

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/tickets/v1/tickets/example-id/comments"

Internal comments are omitted for non-admins.

Operation ID: listComments

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Ticket id within the caller's organisation.

Responses

200
Comments
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: invalid request body or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/tickets/{id}/comments

Add a comment

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/tickets/v1/tickets/example-id/comments"

visibility defaults to public. Internal comments require admin.

Operation ID: addComment

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Ticket id within the caller's organisation.

Request body(required)

application/jsonCommentCreate

Responses

201
Created comment
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, VERSION_CONFLICT, INVALID_STATE_TRANSITION, or IDEMPOTENCY_CONFLICT.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: invalid request body or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Attachments

Files stored in R2.

get/v1/tickets/{id}/attachments

List attachments

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/tickets/v1/tickets/example-id/attachments"

Operation ID: listAttachments

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Ticket id within the caller's organisation.

Responses

200
Attachments
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: invalid request body or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/tickets/{id}/attachments

Upload an attachment

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/tickets/v1/tickets/example-id/attachments"

Stores the file in R2. Max 10 MB. JPEG, PNG, WebP, GIF, PDF, ZIP, JSON, CSV, and plain text.

Operation ID: uploadAttachment

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Ticket id within the caller's organisation.

Request body(required)

multipart/form-dataAttachmentUpload

Responses

201
Uploaded attachment
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
409
Conflict. `error.code`: CONFLICT, VERSION_CONFLICT, INVALID_STATE_TRANSITION, or IDEMPOTENCY_CONFLICT.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: invalid request body or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/tickets/{id}/attachments/{attachmentId}

Get attachment metadata

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/tickets/v1/tickets/example-id/attachments/example-id"

Operation ID: getAttachment

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Ticket id within the caller's organisation.
attachmentId*	path	string (uuid)	Attachment id on the ticket.

Responses

200
Attachment
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: invalid request body or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/tickets/{id}/attachments/{attachmentId}/content

Download attachment content

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/tickets/v1/tickets/example-id/attachments/example-id/content"

Operation ID: downloadAttachmentContent

Parameters

Name	In	Type	Description
id*	path	string (uuid)	Ticket id within the caller's organisation.
attachmentId*	path	string (uuid)	Attachment id on the ticket.

Responses

200
Attachment bytes
*/*
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is NOT_FOUND or a resource-specific *_NOT_FOUND value.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: invalid request body or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json