Docs

For coding agents

Create an account and first app with one API call, then add in-app help and support using the returned hk_… SDK key and brp_… project id.

What an agent gets in one call

One request creates an owner account on the Free plan and the first app. 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.

The signup token is the same kind of owner bearer token that POST /admin/api/session returns. Keep the owner token and password out of git and out of the app.

GET https://api.hlpd.uk/api/agent returns the agent quickstart as Markdown. The site also provides llms.txt, llms-full.txt and a downloadable skill file.

Sign up

Use the human's email address and generate a long random password, then send JSON to POST https://api.hlpd.uk/api/signup:

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

The response is 201:

{
  "token": "...",
  "owner": {"email": "...", "plan": "free", "email_verified": false},
  "verification": "sent",
  "project": {
    "id": "brp_…",
    "name": "My app",
    "sdk_key": "hk_…",
    "report_url": "https://api.hlpd.uk/report/brp_…",
    "api_url": "https://api.hlpd.uk"
  },
  "docs": "https://hlpd.uk/docs/agents"
}

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

Keep the token in an environment variable or secret store, never in git. Tell the human the email address and password at the end, and ask them to open the verification email. They can sign in to manage the app and tickets. A forgotten password is reset by email; see Accounts and email.

Put the key and project id in the app

Use project.sdk_key for hk_… and project.id for brp_…. SDK keys and project ids are public; owner tokens and passwords are secrets.

iOS

Add sdk/ios/Hlpd as a Swift package dependency and the generated bundle as a folder reference named HlpdBundle.

import Hlpd

let hlpd = HlpdConfiguration(
    apiKey: "hk_…",                                  // the project's SDK key
    tickets: HlpdTickets(serverURL: URL(string: "https://api.hlpd.uk")!,
                         projectID: "brp_…"),        // the project's public id
    context: { ["screen_name": "Settings"] }
)

See the iOS guide for help and support views.

Android

Include :hlpd-sdk as a library module, add implementation(project(":hlpd-sdk")), copy the bundle to src/main/assets/hlpd_bundle/ and set androidResources { noCompress += "bin" } in the host application module.

import uk.hlpd.sdk.*

val configuration = HlpdConfiguration(
    apiKey = "hk_…",
    bundle = HlpdBundleSource.Assets("hlpd_bundle"),
    tickets = HlpdTickets(
        serverUrl = "https://api.hlpd.uk",
        projectId = "brp_…",
    ),
    onEscalate = { ticketId, summary -> /* Observe a sent ticket or handle app-owned support. */ },
    context = { mapOf("screen_name" to "Settings") },
)

// Inside Compose:
HelpCenter(configuration)
HelpSupport(configuration)
HelpSuggestions(text = reportDescription, configuration = configuration, surface = "bug_report")

See the Android guide.

Web

Serve the SDK's src/ directory and the bundle as static files, and allow your site's origin on the hlpd app; there is no npm install or build step.

import { Hlpd } from "./hlpd/src/index.js";

const hlpd = await Hlpd.load({
  apiKey: "hk_…",
  bundleURL: "/hlpd-bundle/",
  // baseURL defaults to https://api.hlpd.uk
  tickets: { serverURL: "https://api.hlpd.uk", projectID: "brp_…" },
  context: () => ({ screen_name: "Settings" }),
  onEscalate: (ticketId, summary) => { /* Observe a sent ticket or handle app-owned support. */ },
});

const help = hlpd.mountHelpCenter(document.querySelector("#help"));
const support = hlpd.mountSupport(document.querySelector("#support"));
// help.unmount(); support.unmount(); hlpd.destroy();

See the web guide for mounting help, support and the report widget.

Generate and publish a help bundle

Set up the generator, then run these commands. Use --platform ios, --platform android or --platform web for your app, and replace the source path, output path, token and project id.

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_…

Authentication uses the owner bearer token in HLPD_TOKEN, or HLPD_EMAIL and HLPD_PASSWORD. Ship /tmp/hlpd/my-app/bundle inside the app too; publishing lets installed apps fetch updates. See the generator guide for setup and bundle layout.

The raw upload endpoint is POST /admin/api/projects/{id}/bundles with a gzipped tar and the owner bearer token.

File a bug report from the app

• iOS: create BugReporter with the API URL and project id, then add .bugReportSupportSheet(isPresented:reporter:) to your support button.
• Android: create BugReporter with the API URL, project id and application context, then show BugReportSupportScreen(reporter = ..., onClose = ...).
• Web: add the report widget or call POST /api/reports. See the web guide.

Use the returned project.report_url to open the hosted report form at https://api.hlpd.uk/report/brp_…. You can test report intake without a device:

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"}'

Replace brp_… with your project id. Confirm the response is 201 and its JSON has a ticket_id. See the server guide for report fields and ticket threads.

Add another app

Use the owner bearer token to create another project:

curl -X POST https://api.hlpd.uk/admin/api/projects \
  -H "Authorization: Bearer $HLPD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name": "Another app"}'

The 201 response contains {"project": {...}}. Save project.id and the first SDK key, project.keys[0]. The Free plan allows 1 app; creating an app beyond your plan's limit returns 403.

Sign in again to get an owner bearer token:

curl -X POST https://api.hlpd.uk/admin/api/session \
  -H 'Content-Type: application/json' \
  -d '{"email": "...", "password": "..."}'

Save the returned token in HLPD_TOKEN or a secret store.

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.

Downloads

Download the hlpd skill and put it at .claude/skills/hlpd/SKILL.md for Claude Code, or copy its instructions into your agent's instructions file. llms.txt links to the guides; llms-full.txt contains all docs as Markdown.