REST API

Standard HTTP, JSON in and out, one Bearer token. This page covers the conventions that apply everywhere; the resource pages have request and response examples for each endpoint.

Base URL

https://helmdesk.dev/api/v1

Authentication

Every request carries a project API key as a Bearer token. Keys are created from Dashboard → Project → API Keys.

curl https://helmdesk.dev/api/v1/tickets \
  -H "Authorization: Bearer sk_live_abc123..."

The key identifies the project, so no endpoint takes a project id. A missing or invalid key returns 401. See Authentication for key management and IP allowlists.

Environments

The key prefix selects the data plane. There is no environment parameter — the credential is the environment, so a sandbox key cannot reach live data even by id.

Scopes

Each key carries a scope list; the tables below name the scope every endpoint needs. A key created with an empty scope list has full access, which keeps older keys working. Calling an endpoint without its scope returns 403 auth.forbidden naming the scope you are missing.

Pagination

List endpoints take page and limit query parameters and return the rows under a named key alongside the page state:

{
  "tickets": [ /* … */ ],
  "total": 137,
  "page": 1,
  "limit": 50
}

The array key matches the resource — tickets, customers, logs, issues, and so on. Article search is the one exception: it returns { results, query, count } and is not paginated.

Rate limits

100 requests per minute per API key. Over that returns 429 rate_limit.exceeded. Plan quotas (emails, log events, storage) are separate and surface as 403 with a message naming the limit.

Errors

{
  "error": {
    "code": "auth.forbidden",
    "message": "This API key lacks the required scope: \"emails:manage\"."
  }
}

Every failure uses this shape. See Error Handling for the full code list.

Endpoints

OpenAPI specification

The full OpenAPI 3.1 spec — every endpoint, schema, and sample response on this site — is at:

https://helmdesk.dev/openapi.json

Use it to generate a client in any language, import into Postman or Insomnia, or point an agent at it.