Talk to the home bridge.

Getting started

1. Install pk-client from npm: npm install -g @planekey/client
2. Create a free account at planekey.dev
3. Run pk login to pair your install to the account
4. Run pk update-check to see what's available on your tier

Public endpoints

GET /health

Liveness probe. Returns 200 OK with a small JSON status payload. No authentication.

GET /api/plan-counts

Aggregate counts per subscription tier. No PII, no account identifiers — only counts. Cached 60 seconds in-process. Used by the pricing page counter.

GET /package/builds/public/{build_id}

Hash-only mirror for free clients. Exposes build_hash, total_size_bytes, chunk_count, and recipe identifiers. Use this to verify your npm-downloaded bytes match what the home bridge knows about.

Authenticated endpoints

Repo ingest

POST /repo/ingest — HMAC-signed payload from pk-repo-db-builder. Idempotent on (repo_id, branch_id, tree_hash). A duplicate replay returns idempotent: true with the same identifiers and zero rows inserted.

Package delivery

• GET /package/recipes — list recipes accessible to the account
• POST /package/download/start — open a download session
• GET /package/download/{sid}/chunk/{n} — fetch chunk metadata; idempotent on re-request of the current index
• POST /package/download/{sid}/chunk/{n}/ack — client posts its computed chunk hash for tamper detection
• GET /package/download/{sid}/status
• POST /package/download/{sid}/pause
• POST /package/download/{sid}/resume

Install pairing

• POST /account/claim-install — pair an anonymous install to an account
• POST /account/release-install — unpair (logout, plan-cancel, revoke)
• POST /install/{install_id_hash}/runtime — pk-client reports its current build hash
• GET /install/{install_id_hash}/update-check — returns stay, download, or unpair with available recipes
• GET /account/{account_id}/upgrades-list — dashboard query of all paired installs and pending upgrades

Reports

• POST /reports/update — proposed update with base + proposed runtime hashes
• POST /reports/runtime — confirms runtime fingerprint after deploy
• POST /reports/closure — confirms route verified and packet ready
• POST /reports/submit — universal report intake (signed)

Webhooks

• POST /webhooks/entitlements-changed — Auth DB pushes entitlement state changes here; signed with its own HMAC secret

Request shape

All POST endpoints accept JSON. Signed endpoints include a signature field with the HMAC-SHA256 hex over a deterministic concatenation of the other fields. The exact concatenation order is in the request example files.

Errors return JSON like {"error": "..."} with an appropriate HTTP status. 401 for signature failures. 403 for entitlement failures. 404 when a referenced resource doesn't exist. 409 when a chunk request is out of order — the response includes expected_next so the client can rewind.

Client tools

• pk-repo-db-builder.js — walks a working directory, computes path/content hashes, extracts components, plans deterministic chunks, emits an ingest packet
• pk-flight-report.js — turns patch artifacts into update/runtime/closure reports
• pk-canon-forensics-adapter.js — converts canon-analyzer output into signed canon/forensic payloads
• planekey_env_observer_mcp.py — MCP server for coding assistants; read-only environment observer, never patches

Going deeper

Full architectural docs live in the repo under docs/. Highlights:

• docs/REPO_DB_PACKAGE_BUILDER.md — the materials layer
• docs/REPO_DB_ROUTES_V0216.md — the delivery layer
• docs/PAIRED_INSTALLS_AND_UPDATE_CHECK.md — the lifecycle layer
• docs/CANONICAL_DOMAINS.md — DNS posture
• docs/CLOUDFLARE_ZERO_TRUST.md — edge posture