# API quick reference

Base path: `/api/v1`

- `POST /auth/bootstrap-owner` — one-time first Owner creation; requires `X-Bootstrap-Token`, only works on an empty DB.
- `POST /auth/login` — username/password; returns short-lived access token.
- `GET /auth/me` — current user and role.
- `GET /overview` — role-gated operational counts.
- `GET /tickets?limit=50&status_filter=OPEN` — list tickets; regular users see only their own tickets.
- `POST /tickets` — create ticket with subject/category/priority/first_message.
- `GET /tickets/{id}` — ticket detail and messages; internal notes hidden from regular users.
- `POST /tickets/{id}/messages` — add reply or staff-only internal note.
- `PATCH /tickets/{id}` — staff assign/update status/priority.
- `GET /admin/users` — role-gated user list.
- `POST /admin/users` — Owner-only staff creation.
- `POST /admin/users/{id}/suspend` — Owner-only suspension.
- `GET /admin/audit-logs` — role-gated recent audit events.
- `POST /admin/authorized-telegram-ids` — Owner-only pre-authorize Telegram IDs for Manager/Supervisor onboarding.
- `GET /admin/applications` — review staff applications.
- `POST /onboarding/applications` — internal-service endpoint; requires `X-Onboarding-Service-Token` and a pre-authorized Telegram ID.
- `POST /admin/applications/{id}/review` — Owner/Supervisor manual review; only Owner may approve Supervisor appointments.
- `POST /telegram/set-webhook` — intentionally returns 501; this build runs the bot in polling mode until a durable webhook worker is implemented.
- `GET /health/live`, `GET /health/ready` — liveness/readiness probes.

Authentication uses `Authorization: Bearer <access_token>`. Never put the bot token in the browser. The webhook receiver currently validates the Telegram secret token and acknowledges the update; the included bot container runs polling mode. For a production webhook deployment, connect the validated API receiver to a durable queue/worker before enabling webhook mode.