SupportMesh Docs

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 tenant-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	Mutation route exists, but this phase returns HTTP 501 because ticket creation through the public API is not enabled yet. It returns HTTP 501 in the current phase.
GET	/api/v1/tickets/{ticketId}	tickets.read	Read a single ticket by ID.
PATCH	/api/v1/tickets/{ticketId}	tickets.write	Mutation route exists, but this phase returns HTTP 501 because ticket updates through the public API are not enabled yet. It returns HTTP 501 in the current phase.
POST	/api/v1/tickets/{ticketId}/comments	comments.write	Comment creation route exists, but this phase returns HTTP 501 because public API comment writes are not enabled yet. It returns HTTP 501 in the current phase.

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"

Example response fields are fictional, but the route shape and enum names match the current implementation.

{
  "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 tenants, and insufficient scopes. The request layer also supports request IDs. The API foundation includes idempotency storage helpers, but the documented `/api/v1/tickets` routes in this phase do not yet advertise route-level idempotent write behavior because those writes are not available.