API reference
Every public endpoint. The base URL is https://www.hostkingpro.com. Auth is either a session cookie (browsers) or Authorization: Bearer hk_live_… (CLI). Mint a token at /dashboard/api-keys.
OpenAPI 3.1 spec
Machine-readable. Use it for Postman, Insomnia, or to generate client SDKs.
| Method | Path | Auth | Summary |
|---|---|---|---|
| GET | /api/healthz | no auth | Liveness probe. Always 200 if the process is up. { status: 'ok', service, build_sha, node_env, timestamp } |
| GET | /api/readyz | no auth | Readiness probe. 200 if Supabase is reachable, /home exists, ≥1 Server registered. 503 otherwise. { status: 'ready'|'not_ready', checks: { supabase, home_dir, pods } } |
| GET | /api/metrics | no auth | Live control-plane metrics from /proc: CPU %, memory %, swap, loadavg (1/5/15 min). Useful for embedding in monitoring. { cpu: { pct_used, loadavg }, memory: { total_mb, used_mb, pct_used }, swap: { total_mb, free_mb } } |
| GET | /api/network | no auth | Network info: hostname, uptime, interfaces (IPv4/IPv6/MAC), and listening sockets (with protocol + process). Useful for ops debugging. { hostname, uptime, primary_ip, interfaces, listening } |
| GET | /api/badge | no auth | Embeddable SVG badge (shields.io-style). ?label=X&status=Y&color=Z. Status maps to a color automatically. image/svg+xml |
| GET | /api/version | no auth | Build metadata: service, version, build_sha, node_env, node_version, started_at, uptime_seconds. Used by the CLI and by anyone who wants to verify deployment. { service, version, build_sha, node_env, node_version, started_at, uptime_seconds } |
| GET | /api/templates/[slug]/download | no auth | Builds and serves a starter-template zip (Next.js, Express, Hono, FastAPI, OpenAI, static). application/zip |
| GET | /api/samples/[slug]/download | no auth | Builds and serves a sample-app zip (Express, Node, static, WordPress). application/zip |
| GET | /api/me/orgs | session cookie | List the orgs the current user is a member of. { orgs: [{ role, organizations: { id, name, slug, plan_tier, plan_weight_pcu, subscription_status } }] } |
| GET | /api/me/usage | session cookie | Current usage vs the plan's limits. { org, usage: { sites, seats, deploys_30d, storage_mb } } |
| GET | /api/me/api-keys | session cookie | List API keys (no hashes). |
| POST | /api/me/api-keys | session cookie | Mint a new API key. Returns the plaintext once. |
| POST | /api/me/api-keys/revoke | session cookie | Revoke a key by id. The key's hash stays in the DB so we can refuse it. |
| GET | /api/sites | session cookie | List sites across the user's orgs. |
| POST | /api/sites | session cookie | Create a new site. Body: { name, organization_id, site_type, port, memory_limit_mb, cpu_quota_percent, domain? }. |
| GET | /api/sites/[id] | session cookie | Get a single site as JSON. |
| POST | /api/sites/[id]/restart | session cookie | Restart the systemd unit. Owner or admin only. |
| POST | /api/sites/[id]/stop | session cookie | Stop the unit (no traffic). |
| POST | /api/sites/[id]/start | session cookie | Start the unit. |
| POST | /api/sites/[id]/redeploy | session cookie | Re-run the last build. Picks up env-var changes after a manual save. |
| POST | /api/sites/[id]/delete | session cookie | Stop the unit, remove it, delete /home/<tenant>, mark site row as 'deleted'. Owner or admin only. |
| POST | /api/sites/[id]/env | session cookie | Replace env vars. Form fields are key_0/val_0, key_1/val_1, etc. |
| POST | /api/sites/[id]/domain | session cookie | Set the custom domain. |
| POST | /api/sites/[id]/transfer | session cookie | Move the site to a different org. Owner of source + member of target. |
| GET | /api/sites/[id]/metrics | session cookie | Live cgroup memory + CPU. Returns { running, memory: { current_mb, max_mb, pct }, cpu: { usage_seconds } }. |
| GET | /api/sites/[id]/logs | session cookie | Tail the systemd journal. ?tail=N (default 200, max 2000), ?severity=info|warn|error, ?since=ISO, ?until=ISO, ?format=raw (plain-text attachment). JSON: { unit, lines: [{ ts, severity, msg }] }. |
| GET | /api/sites/[id]/health | session cookie | Real HTTP probe to the site's loopback. Returns { ok, status_code, latency_ms }. |
| GET | /api/sites/[id]/deploys | session cookie | Recent deploys for a site. |
| GET | /api/sites/[id]/preview | session cookie | Proxy a request to the running site. ?path=/foo (default '/'). 5s timeout. Streams the raw response with the original content-type. |
| POST | /api/sites/[id]/share | session cookie | Mint a time-limited public share token for the site status page. Body: {ttl_hours?: number}. Returns {token, share_url, expires_at, site_name}. Default TTL: 24h. Max: 720h. |
| DELETE | /api/sites/[id]/share | session cookie | Revoke all active share tokens for the current user/site. |
| POST | /api/sites/bulk | session cookie | Bulk action on multiple sites. Body: {site_ids: [...], action: 'start'|'stop'|'restart'|'redeploy'}. Max 100 sites. Returns {succeeded, failed, forbidden}. Owner/admin only. |
| GET | /api/me/orgs | session cookie | List the orgs the current user is a member of, with role. |
| GET | /api/me/usage | session cookie | Current usage vs the plan's limits. |
| GET | /api/me/activity | session cookie | Recent audit events for the user's orgs. ?limit=N (max 50, default 5). Used by the sidebar widget. |
| POST | /api/cron | session cookie | Create a cron job. Form: name, schedule (5-field cron), endpoint (URL), enabled. |
| POST | /api/cron/[id]/toggle | session cookie | Toggle the enabled flag on a cron job. |
| POST | /api/cron/[id]/delete | session cookie | Permanently delete a cron job. |
| POST | /api/webhooks/test | session cookie | Fire a test webhook delivery to a URL. Body: {url, event?, secret?}. Signs with HMAC-SHA256 if secret is given. 10s timeout. Records the attempt in webhook_deliveries. |
| POST | /api/sites/_backup | session cookie | Trigger a one-shot backup. Form: site_id. |
| GET | /api/notifications | session cookie | List the current user's notifications. ?limit=N (default 50, max 200). ?unread_only=true to filter. {notifications: [{id, type, title, body, link, severity, read_at, created_at}], unread_count: N} |
| POST | /api/notifications/read-all | session cookie | Mark all of the current user's notifications as read. |
| PATCH | /api/notifications/[id] | session cookie | Mark a single notification as read. |
| DELETE | /api/notifications/[id] | session cookie | Delete a single notification. |
| POST | /api/sites/github | session cookie | Connect a GitHub repo to a site. Form: site_id, repo (owner/name), branch. |
| POST | /api/webhooks | session cookie | Subscribe a URL to org events. Form: url (https://), events (multi). |
| POST | /api/webhooks/[id]/delete | session cookie | Remove a webhook subscription. |
| POST | /api/deploy | session cookie | Upload a zip and trigger a deploy. Form: file, site_id, source (zip|github|vercel|cli). |
| GET | /api/deploy/[id]/status | session cookie | Status + last N log lines for a deploy. |
| GET | /api/deploy/[id]/stream | session cookie | SSE stream of live deploy logs. |
| POST | /api/internal/github-webhook | internal only | GitHub push receiver. HMAC-SHA256 signed. Maps repo → site via site.github_repo match. |
| POST | /api/internal/scan-result | internal only | ClamAV scan result receiver (Phase 3B). |
| GET | /metrics | no auth | Prometheus text-format metrics. 7 metric families. |
| GET | /sitemap.xml | no auth | XML sitemap of public marketing + docs routes. |
Try the API in the CLI: hostking sites:list · hostking usage · hostking site:metrics <id>