---
title: API Overview (LLM)
description: Headoni API base URL, auth, scopes, ids, and error format.
---

# Headoni API: Overview

Per-desk REST API for creating and reading support tickets.

## Base URL

```
https://<your-desk>.headoni.app/api/v1
```

- `<your-desk>` is the desk slug. Desk slug `acme` => `https://acme.headoni.app/api/v1`.
- The API host is always the `.headoni.app` tenant host. Custom portal domains do not host the API.

## Authentication

- Header on every request: `Authorization: Bearer hd_<secret>`.
- Tokens are minted per desk in the customer dashboard (desk > API page). The secret is shown once at creation.
- The `hd_` prefix is optional in the header; both `hd_<secret>` and `<secret>` work.
- Revocation is immediate and permanent.

## Scopes

- `tickets:create` — required for `POST /tickets`.
- `tickets:read` — required for every `GET` route (`GET /tickets`, `GET /tickets/:idOrNumber`, `GET /departments`, `GET /ticket-types`).
- A token may hold any subset. Missing scope => `403 insufficient_scope`.

## Endpoints

- `POST /tickets` — create a ticket. Scope: `tickets:create`.
- `GET /tickets` — list tickets. Scope: `tickets:read`.
- `GET /tickets/:idOrNumber` — one ticket + public messages. Scope: `tickets:read`.
- `GET /departments` — list departments. Scope: `tickets:read`.
- `GET /ticket-types` — list ticket types. Scope: `tickets:read`.

## Value Types

- All ids are strings (64-bit snowflakes, sent as strings to avoid JSON number precision loss).
- `number` (on a ticket) is an integer, the per-desk sequential ticket number shown to customers as `[#1247]`.
- Timestamps are ISO 8601 UTC strings.
- `priority` is one of: `low`, `normal`, `high`, `urgent`.
- `status.internalType` is one of: `open`, `awaiting_reply`, `resolved`, `closed`.
- `authorKind` (on a message) is one of: `agent`, `end_user`, `system`, `automation`.

## Error Format

All errors: `{ "error": "<code>", "detail"?: "<string>", "issues"?: [...] }`.

| status | error | cause |
| --- | --- | --- |
| 400 | invalid_body | request body failed validation; see `issues` |
| 400 | invalid_query | query params failed validation; see `issues` |
| 400 | invalid_id | path id/number was not all digits |
| 400 | invalid_status | `status` filter was neither a keyword nor a numeric id |
| 401 | unauthenticated | missing, unknown, revoked, or expired token |
| 403 | insufficient_scope | token lacks the required scope |
| 403 | token_desk_mismatch | token belongs to a different desk than the host |
| 404 | ticket_not_found | no such ticket on this desk |

## Notes

- Reads return PUBLIC messages only. Internal notes are never returned.
- Per-desk machine-readable reference: `https://<your-desk>.headoni.app/llms.txt`.