Developers / APIProduct guide

API Keys and REST API

Integrate with the current public API surface accurately, including the read-only routes that work now and the mutation routes that intentionally still return HTTP 501.

Authentication and API keys

SupportMesh uses bearer-token API keys. Send the key in the `Authorization` header as `Bearer <api-key>`.

Authorization: Bearer sm_example_key
X-Request-Id: docs-example-001

API keys are workspace-scoped, carry an explicit scope list, and can be active, revoked, or expired. Keep them server-side and rotate them like any other secret.

Current scope catalog

Current `/api/v1` routes

Method	Path	Scope	Current behavior
GET	/api/v1/tickets	tickets.read	List tickets with pagination and server-side filters.
POST	/api/v1/tickets	tickets.write	Ticket creation through the public API is not available; this route returns HTTP 501.
GET	/api/v1/tickets/{ticketId}	tickets.read	Read a single ticket by ID.
PATCH	/api/v1/tickets/{ticketId}	tickets.write	Ticket updates through the public API are not available; this route returns HTTP 501.
POST	/api/v1/tickets/{ticketId}/comments	comments.write	Comment creation through the public API is not available; this route returns HTTP 501.

Ticket list filters and response shape

The current ticket list endpoint accepts `page`, `per_page`, `client_id`, `priority`, `status`, `support_item_id`, `type`, `q`, and `updated_since`. Results are ordered by newest created ticket first.

curl https://supportmeshplatform.com/api/v1/tickets?page=1&per_page=25&status=in_progress \
  -H "Authorization: Bearer sm_example_key" \
  -H "Accept: application/json"

The example values are illustrative; the route shape and enum names match the live API contract.

{
  "page": 1,
  "per_page": 25,
  "total_count": 1,
  "tickets": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "ticket_number": "SUP-1042",
      "subject": "Checkout error after update",
      "status": "in_progress",
      "priority": "high"
    }
  ]
}

Errors, request IDs, and idempotency

SupportMesh returns JSON error responses for missing authentication, inactive workspaces, and insufficient scopes. Responses include request IDs. Ticket mutation routes are unavailable, so they do not advertise idempotent write behavior.