API Conventions

Canonical version

The canonical public API prefix is:

• /api/v1/*

The backend still accepts legacy unversioned /api/* routes for compatibility, but new integrations should use the versioned path.

Authentication

Most endpoints use bearer-token authentication:

Authorization: Bearer <jwt>

Public exceptions are documented directly on the operation, such as login and invitation acceptance.

Response envelope

Most JSON responses use the same top-level envelope:

{
  "success": true,
  "message": "Request completed successfully",
  "data": {},
  "timestamp": "2026-03-21T12:00:00"
}

The data field contains the actual endpoint payload.

Pagination

List endpoints typically return a paged payload with:

• content
• pageNumber
• pageSize
• totalElements
• totalPages
• last

Use the schema examples in the OpenAPI reference for the exact shape of each paged response.

Ticket references

Ticket endpoints now expose both:

• internal numeric id
• public-facing ticketCode

For frontend routing and customer-facing URLs, prefer ticketCode. Ticket detail pages should use paths like /tickets/{ticketCode}.

Realtime events

Realtime updates are exposed as Server-Sent Events on:

• /api/v1/realtime/events

Because the endpoint uses bearer authentication, browser integrations should use a fetch-based SSE client instead of plain EventSource, which cannot attach a custom Authorization header.

Error handling

Validation, authorization, and business-rule failures return standard HTTP status codes. Common cases:

• 400 for invalid input
• 401 for missing or invalid authentication
• 403 for authenticated but out-of-scope access
• 404 when the resource does not exist in caller scope
• 409 for state conflicts or domain rule conflicts
• 429 when rate limits are exceeded

Business-rule details should be read from the response body message.