API Overview
Base URL, authentication, scopes, and error format for the Headoni API.
The Headoni API is a small, per-desk REST API. You can create tickets and read them back. Every route is scoped to a single desk through the bearer token you send.
Authentication
Mint a token on the customer dashboard: open your desk, go to the API page, and
create a token. The secret is shown once on creation, so copy it then. Send it
as a bearer header on every request. Tokens start with hd_.
curl https://acme.headoni.app/api/v1/ticket-types \
-H "Authorization: Bearer hd_your_secret_here"Revoking a token takes effect immediately and cannot be undone.
Scopes
Each token carries one or more scopes. A route returns 403 insufficient_scope
when the token is missing the scope it needs.
Endpoints
Ids And Types
Every id in a response is a string, even though it looks like a number. Ids are
64-bit and would lose precision as JSON numbers, so the API sends them as
strings. A ticket also carries a short, per-desk number (an integer) that
matches the [#1247] token your customers see.
Timestamps are ISO 8601 strings in UTC.
Errors
Errors use a stable envelope: a machine-readable error code, plus an optional
detail string or a issues array for validation failures.
{ "error": "insufficient_scope", "detail": "requires \"tickets:read\"" }| Status | error | Meaning |
|---|---|---|
| 400 | invalid_body | Body failed validation. See issues. |
| 400 | invalid_query | Query failed validation. See issues. |
| 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. |
Machine-Readable Reference
Each desk publishes a per-desk llms.txt at
https://<your-desk>.headoni.app/llms.txt, pre-filled with that desk's
departments, ticket types, and defaults. Every page here also has an LLM doc,
linked from the button at the bottom.