Service Desk API

All service desk endpoints are under /api/v1/service-desk/ and require BearerAuth. The interactive Swagger UI is available at /swagger/index.html.

tip

Super admins must filter by organization when accessing read endpoints. The API returns 400 Bad Request with message "super admins must filter by organization" if no org scope is provided.

Permissions

Permission	Description
servicedesk:read	View requests, kanban, metrics, comments, approvals, transitions, attachments
servicedesk:write	Create requests, add comments/attachments, execute transitions, submit approvals
servicedesk:delete	Reserved for future use
servicedeskconfig:read	View all organization mappings (admin)
servicedeskconfig:write	Create/update organization mappings (admin)
servicedeskconfig:delete	Delete organization mappings (admin)

Read Endpoints (ClickHouse)

List Requests

GET /api/v1/service-desk/tickets

Returns a paginated list of requests scoped by the caller's project labels.

Parameter	Type	Default	Description
page	int	1	Page number
per_page	int	20	Items per page
sort_by	string	updated	Sort column: created, updated, priority, status, issue_key, summary, assignee
sort_dir	string	DESC	ASC or DESC
status	string	—	Filter by exact status
priority	string	—	Filter by priority
issue_type	string	—	Filter by issue type
assignee	string	—	Filter by assignee
search	string	—	Search by issue key or summary (ILIKE)
date_from	string	—	Filter created on or after (ISO 8601)
date_to	string	—	Filter created on or before (ISO 8601)
my_requests	bool	false	When true, returns only requests where reporter_email matches the authenticated user

Response: ListResponse with data: Request[] and pagination meta. Each item includes linked_issue_key and reporter_email fields.

Pending writes (optimistic) are merged into the response: recently created requests appear as PENDING entries, and recent transitions update the status field.

Get Request Detail

GET /api/v1/service-desk/tickets/{issueKey}

Returns a single request with status history, SLA data, and delivery metrics. The three supplementary queries (history, SLA, delivery) run in parallel for faster response times.

Response:

{
  "data": {
    "ticket": {
      "...",
      "linked_issue_key": "PXD-456",
      "reporter_email": "[email protected]"
    },
    "status_history": [ { "from_status": "Open", "to_status": "In Progress", "changed_at": "..." } ],
    "sla": { "first_response_sla_met": 1, "resolution_sla_status": "Met", ... },
    "delivery": { "cycle_time_days": 3.2, "is_on_time": 1, ... }
  }
}

Get Kanban Board

GET /api/v1/service-desk/kanban

Returns requests grouped by status category (To Do, In Progress, Done), with sub-groups by specific status. Accepts the same filter parameters as List Requests (except pagination), including my_requests=true. Hard limit: 500 requests.

Get SLA Metrics

GET /api/v1/service-desk/metrics/sla?date_from=...&date_to=...

Returns aggregated SLA compliance metrics: average first response hours, average resolution hours, SLA percentages, total requests, breach count.

Get Delivery Metrics

GET /api/v1/service-desk/metrics/delivery?date_from=...&date_to=...

Returns delivery performance: average/median/p90 cycle time (days), throughput, on-time percentage.

Get Metrics Summary

GET /api/v1/service-desk/metrics/summary

Returns a dashboard summary: open count, resolved count, MTTA, MTTR, SLA compliance %, throughput.

Export CSV

GET /api/v1/service-desk/reports/export

Returns a CSV file download of matching requests (up to 10,000 rows). Accepts the same filter parameters as List Requests. Fields are sanitized against CSV formula injection.

Response: Content-Type: text/csv with Content-Disposition: attachment.

List Client Organizations

GET /api/v1/service-desk/organizations

Returns the org mappings for the authenticated user's client scope. Used by the frontend org picker.

Get Request Actions

GET /api/v1/service-desk/tickets/{issueKey}/actions

Returns the audit log of write actions performed on a request (create, comment, transition) from the service_desk_actions table.

JSM Proxy Endpoints

These endpoints proxy to the Jira Service Management Cloud API after validating request ownership.

info

When the issueKey is a PXD-prefixed engineering key, the backend automatically resolves the corresponding SUP key before forwarding the request to the JSM API. Clients always interact using their SUP keys.

Comments

GET  /api/v1/service-desk/tickets/{issueKey}/comments?start=0&limit=25
POST /api/v1/service-desk/tickets/{issueKey}/comments

POST body: { "body": "Comment text", "public": true }

Transitions

GET  /api/v1/service-desk/tickets/{issueKey}/transitions
POST /api/v1/service-desk/tickets/{issueKey}/transition

POST body: { "id": "31", "comment": "Optional comment" }

Approvals

GET  /api/v1/service-desk/tickets/{issueKey}/approvals
POST /api/v1/service-desk/tickets/{issueKey}/approvals/{approvalId}

POST body: { "decision": "approve" } or { "decision": "decline" }

Attachments

GET  /api/v1/service-desk/tickets/{issueKey}/attachments
POST /api/v1/service-desk/tickets/{issueKey}/attachments

POST: Multipart form upload with file field. Maximum 10 MB.

Create Request

POST /api/v1/service-desk/tickets

Body:

{
  "service_desk_id": "1",
  "request_type_id": "10",
  "request_field_values": {
    "summary": "Server disk full on prod-web-01",
    "description": "Root partition at 98% usage",
    "priority": { "id": "2" }
  },
  "raiseOnBehalfOf": "[email protected]"
}

The service_desk_id must belong to one of the caller's org mappings. The organization is automatically set via customfield_10002. The optional raiseOnBehalfOf field sets the reporter to a specific user for attribution (e.g., stakeholder users raising requests on behalf of others).

Get Request Type Fields

GET /api/v1/service-desk/request-types/{requestTypeId}/fields?service_desk_id=1

Returns the form field definitions for a JSM request type. Results are cached for PROXIMA_JSM_FIELD_CACHE_TTL (default 24h).

Admin Endpoints

Require servicedeskconfig:* permissions. All operations are scoped to the caller's accessible clients (unless super admin).

GET    /api/v1/service-desk/admin/organizations?page=1&per_page=20&client_id=...
POST   /api/v1/service-desk/admin/organizations
PUT    /api/v1/service-desk/admin/organizations/{id}
DELETE /api/v1/service-desk/admin/organizations/{id}

Input Validation

Parameter	Format	Example
issueKey	[A-Z][A-Z0-9]+-\d+	PROJ-123
approvalId	Numeric string	42
serviceDeskId	Numeric string	1
requestTypeId	Numeric string	10

Invalid formats return 400 Bad Request.

Rate Limiting

The JSM API client enforces 50 requests/second with a burst of 10 using a token bucket rate limiter. If Jira returns HTTP 429, the backend returns 429 Too Many Requests to the caller.