Docs

Server API

Everything the SDKs, the report widget and the generator send goes to https://api.hlpd.uk. These are its public endpoints and what they expect.

SDK API

Requests to /v1/* carry the app's SDK key and identify the bundle and device:

HTTP

Authorization: Bearer hk_…
X-Hlpd-Bundle: drink-ios
X-Hlpd-Bundle-Version: 2026.10.12-1
X-Hlpd-Device: 7fQ2kLp9Xc3mVb8N

Endpoint	Purpose
`POST /v1/chat/completions`	OpenAI-style chat completions for the on-device agent, within the app's daily, monthly and per-device limits
`POST /v1/events`	Analytics events as `{"events": [...]}`, at most 200 per request
`GET /v1/order`	Topic order and service-notice pins, optionally for one `screen`, with `ETag` support
`GET /v1/bundle`	The live published manifest for over-the-air updates, or `204` when none is live
`GET /v1/files/{sha256}/{name}`	One bundle file by content hash

Event types are topic_view, search, walkthrough_start, walkthrough_complete, chat_question, feedback, suggestion_shown, suggestion_opened and report_filed.

The chat agent runs on the device and the API only gates the language model. The agent uses plain tool calling with search_topics, get_topic, show_topic, show_walkthrough and escalate, with at most 6 tool rounds and 600 tokens per completion.

Reports and tickets

Reports and feature requests are sent as multipart/form-data to POST /api/reports:

Field	Notes
`project_id`	The public project id, `brp_…`
`title`	Required
`kind`	`bug` (default) or `feature`
`body`	The description
`client_id`	The device id. Required when attaching files
`classification_level`	`low`, `medium` (default) or `high`
`metadata`	A JSON object as a string, such as the screen, app version and topics viewed
`attachments`	Images, up to 4 files of 5 MB each

Shell

curl https://api.hlpd.uk/api/reports \
  -F project_id=brp_your_project \
  -F title="Reminders won't stop" \
  -F kind=bug \
  -F body="They keep buzzing after 10pm." \
  -F client_id=7fQ2kLp9Xc3mVb8N \
  -F 'metadata={"screen_name": "Settings"}'

The response identifies the ticket. reply_token is only returned when the app has public ticket status turned on; keep it to read and reply to the thread.

JSON

{
  "id": "…",
  "ticket_id": "…",
  "ticket_url": "https://api.hlpd.uk/tickets/…",
  "client_id": "7fQ2kLp9Xc3mVb8N",
  "kind": "bug",
  "status": "received",
  "classification_level": "medium",
  "status_visible": true,
  "can_reply": true,
  "reply_token": "…"
}

Endpoint	Purpose
`GET /api/tickets/{ticket_id}`	Ticket status and public messages
`POST /api/tickets/{ticket_id}/messages`	Reply as the reporter with `{"reply_token": "…", "body": "…"}`
`POST /api/tickets/{ticket_id}/push`	Register for reply pushes with `{"reply_token": "…", "platform": "apns", "token": "…"}`; `platform` is `apns` or `fcm`
`POST /api/tickets/{ticket_id}/push/unregister`	Stop reply pushes
`GET /report/{project_id}`	The hosted report form
`GET /tickets/{ticket_id}`	The hosted ticket status page

When an app has allowed origins, browser requests must come from one of them.

Owner API

The admin, the native admin app and the generator use owner endpoints under /admin/api. Native apps and command-line tools open a bearer session, valid for 30 days, with POST /admin/api/session and {"email": "…", "password": "…"}. Coding agents can create an account and first app with POST /api/signup; see For coding agents.

Endpoint	Purpose
`GET /admin/api/projects`	Your apps
`POST /admin/api/projects`	Create an app within your plan's app limit
`PATCH /admin/api/projects/{id}`	Bundle id, quotas and store text
`POST /admin/api/projects/{id}/keys`	Create an SDK key
`DELETE /admin/api/projects/{id}/keys/{key}`	Revoke an SDK key
`POST /admin/api/projects/{id}/bundles`	Upload a bundle as a gzipped tar
`GET /admin/api/projects/{id}/bundles`	List uploaded bundles
`PUT /admin/api/projects/{id}/bundle`	Choose the live bundle version
`GET /admin/api/projects/{id}/usage`	Chat usage against the app's limits
`GET /admin/api/projects/{id}/analytics`	Help analytics; `topics` and `gaps` sit alongside it
`GET /admin/api/projects/{id}/pins`	Service-notice pins; `PUT` replaces them, with `ETag`
`GET /admin/api/reports`	Reports across your apps

GET /health reports whether the server is up.

Accounts and email

Owners sign in with an email address and a password. When an account is created, hlpd sends a verification email. The account works straight away; upgrading to a paid plan needs a verified email address.

Endpoint	Purpose
`POST /api/signup`	Create an account and first app with `{"email": "…", "password": "…", "project": "…"}`; see For coding agents
`POST /api/verify`	Verify the email address with `{"token": "…"}` from the verification email
`POST /api/verify/resend`	Send the signed-in owner's verification email again
`POST /api/password/forgot`	Send a password reset email with `{"email": "…"}`
`POST /api/password/reset`	Set a new password with `{"token": "…", "password": "…"}` from the reset email

Run your own server

The server is a FastAPI app with one SQLite database. To deploy it to a Linux host running Caddy:

Copy deploy/env.example to /opt/hlpd/server/.env on the host and fill it in.
Point the API domain at the host. Caddy obtains the certificate.
Run deploy/server.sh user@host, and again after every change.

At startup the server creates two accounts if they are missing: a super-admin from HLPD_ADMIN_EMAIL and HLPD_ADMIN_PASSWORD, and an owner from HLPD_OWNER_EMAIL and HLPD_OWNER_PASSWORD.

Verification and password reset emails use these settings:

Variable	Purpose
`HLPD_MAIL_BACKEND`	`log` writes each email to the server log instead of sending it; `ses` sends it through Amazon SES
`HLPD_MAIL_FROM`	Sender address, which must be a verified SES identity when sending through SES
`HLPD_MAIL_REPLY_TO`	Reply-to address
`AWS_REGION`	The SES region

With ses, also provide AWS credentials allowed to send through SES, such as AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

Data lives in the service user's ~/.hlpd: the SQLite database, uploads and bundle objects.