---
name: hlpd
description: Add in-app help, support chat, walkthroughs or bug reporting to an iOS, Android or web app. Use when asked to set up hlpd.
---

# hlpd

hlpd builds an in-app help centre from source, with walkthroughs, support chat and bug reports for iOS, Android and web. One API call creates an owner account on the Free plan, the first app and its SDK key. No card or browser session is needed. hlpd sends a verification email to the address; the account works straight away, and only upgrading to a paid plan needs a verified email address.

## Sign up

Use the human's email address and a long random password, and send:

```sh
curl -X POST https://api.hlpd.uk/api/signup \
  -H 'Content-Type: application/json' \
  -d '{"email": "...",
       "password": "...",
       "project": "My app"}'
```

The `201` response contains `token`, `owner.email`, `owner.plan` (`free`), `owner.email_verified`, `verification` (`sent`), `project.id`, `project.name`, `project.sdk_key`, `project.report_url`, `project.api_url` and `docs`. Save the token in `HLPD_TOKEN` or a secret store. It is the same kind of owner bearer token as `POST /admin/api/session` returns. Never commit the token or password or put them in the app. Project ids and SDK keys are public and ship in apps.

Errors use `{"error": {"code": "...", "message": "..."}}`:

| Code | HTTP status | What to do |
|---|---|---|
| `email_taken` | 409 | The email address already has an account. Ask the human to [sign in](https://api.hlpd.uk/admin/login) or reset the password with `POST /api/password/forgot`. |
| `invalid_request` | 422 | Fix the body; `message` says what is wrong. |
| `rate_limited` | 429 | There are 5 signups per IP per hour. Wait or ask the human to [sign up](https://api.hlpd.uk/admin/signup). |
| `signup_disabled` | 403 | Ask the human to [sign up](https://api.hlpd.uk/admin/signup). |

## Install and configure

- iOS: add `sdk/ios/Hlpd` as a Swift package and ship the bundle as `HlpdBundle`. Set `HlpdConfiguration(apiKey:)` to `project.sdk_key` and `HlpdTickets(serverURL:projectID:)` to the API URL and `project.id`. Add `HelpCenterView(configuration:)`, or `BugReporter` and `.bugReportSupportSheet(isPresented:reporter:)`.
- Android: include `:hlpd-sdk`, depend on `implementation(project(":hlpd-sdk"))`, copy the bundle to `src/main/assets/hlpd_bundle/` and set `androidResources { noCompress += "bin" }` in the host module. Set `HlpdConfiguration(apiKey = ...)` to `project.sdk_key` and `HlpdTickets(serverUrl = ..., projectId = ...)` to the API URL and `project.id`. Show `HelpCenter(configuration)` or `BugReportSupportScreen` with `BugReporter`; let the IDE offer the SDK imports.
- Web: serve the SDK's `src/` and bundle as static files and allow the site's origin on the hlpd app. Set `Hlpd.load({ apiKey, bundleURL, tickets: { serverURL, projectID } })` to the SDK key, bundle URL, API URL and project id. Mount help with `mountHelpCenter`, support with `mountSupport`, or use `mountBugReportForm(form, { serverUrl, projectId })`.

## Generate and publish

Set up the [generator](https://hlpd.uk/docs/generator). Replace the paths, token and project id; choose `--platform ios`, `--platform android` or `--platform web`:

```sh
python -m hlpd_generator generate /path/to/app --platform ios --out /tmp/hlpd/my-app
HLPD_TOKEN=... python -m hlpd_generator publish /tmp/hlpd/my-app/bundle --project brp_…
```

Ship the bundle inside the app too. `HLPD_EMAIL` and `HLPD_PASSWORD` can authenticate instead of `HLPD_TOKEN`. The raw upload is a gzipped tar to `POST /admin/api/projects/{id}/bundles` with the owner bearer token.

## Test a bug report

Replace the project id, then send:

```sh
curl https://api.hlpd.uk/api/reports \
  -F project_id=brp_… \
  -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"}'
```

Confirm `201` and a `ticket_id` in the JSON. The signup response's `project.report_url` is the hosted report form.

## More apps and sign-in

`POST /admin/api/projects` with `Authorization: Bearer <token>` and `{"name": "Another app"}` returns `201` with `project.id` and `project.keys[0]`. Free allows 1 app; requests beyond the plan's app limit return `403`. `POST /admin/api/session` with `{"email": "...", "password": "..."}` returns an owner bearer `token`. `POST /api/password/forgot` with `{"email": "..."}` sends a password reset email.

## Agent checklist

1. Sign up with `POST https://api.hlpd.uk/api/signup` using the human's email address and a long random password.
2. Save the owner token, project id and SDK key in a secret store or environment variables. The project id and SDK key are public and can ship in the app; never commit the owner token or password or put them in the app.
3. Install the SDK for the app's platform.
4. Initialise it with the SDK key and the public project id for tickets.
5. Generate a help bundle from the app's source and ship the bundle inside the app.
6. Publish the bundle with `python -m hlpd_generator publish` and the owner token in `HLPD_TOKEN`.
7. Add the platform's help or support entry point so users can file bug reports.
8. Send a test bug report with curl and confirm the `201` JSON response has a `ticket_id`.
9. Tell the human the email address, password and where to sign in: https://api.hlpd.uk/admin/login. Ask them to open the verification email; a paid plan needs a verified email address.

Read [For coding agents](https://hlpd.uk/docs/agents) and the [Markdown quickstart](https://api.hlpd.uk/api/agent) for exact platform examples.