Base: /api/v1/ • Client session: HCSESSID cookie via /auth/login/ • Programmatic: Authorization: Bearer hc_… tokens
Mutating client calls require the session CSRF token in csrf_token body field or X-CSRF-Token header. Staff/internal endpoints are documented separately under /admin/api/v1/ (staff session required).
0. REST API v1 — Bearer Token Surface
The programmatic surface mirrors the console: what you can click, you can call. Create tokens under Dashboard → Profile → API Tokens — each carries scopes, an optional expiry and an IPv4 CIDR allow-list. Secrets are stored sha256-hashed and shown once.
| Scope | Grants |
|---|---|
read | All GET endpoints + POST /quote |
orders.write | POST /instances — deploy + pay from wallet |
instances.write | Power actions, reinstall, console/VNC tickets, DELETE /instances/{id} |
billing.read | GET /billing, GET /invoices |
* | Everything |
| Method | Endpoint | Scope | Purpose |
|---|---|---|---|
| GET | /me | read | Account, wallet, token scopes |
| GET | /locations | read | Zones + live availability + IPv4 stock + OS list |
| GET | /plans | read | All active plans (vps/game/web, specs, INR price) |
| GET | /os | read | OS template catalogue |
| POST | /quote | read | {"plan_id":N} or {"plan":"VPS-…"} → price + spec |
| GET | /instances | read | Your services + live power state |
| POST | /instances | orders.write | Deploy: {"plan":"MC-2048MB","server_name":"…","eula":true,"idempotency_key":"…"} → 201 + order + job |
| GET | /instances/{id} | read | Detail incl. credentials + last job — treat as secret |
| GET | /instances/{id}/stats | read | Live power, CPU, memory, uptime |
| POST | /instances/{id}/{action} | instances.write | start · stop · restart · kill · reinstall · vnc · console → 202 |
| DELETE | /instances/{id} | instances.write | Terminate — body must send {"confirm":"<label>"} |
| GET | /jobs/{id} | read | Provisioning job status/progress |
| GET | /billing | billing.read | Wallet, monthly run-rate, unpaid orders |
| GET | /invoices | billing.read | Order history (last 100) |
| GET | /status | read | Node fleet health + your instance states |
tickets / dns return 404 — those modules aren't built on this platform.
Limits: 600 req/min/token, 10 deploys/hour/account. Every call is logged to api_logs (method, path, status, IP, duration).
Money is INR; deploys charge the wallet and return 402-style errors when it can't cover the price.
1. Response Envelopes & Authentication
Three envelope shapes exist in the codebase — all are real:
| Auth level | How it is enforced |
|---|---|
PUBLIC | No session — e.g. health, register, login. |
CLIENT | require_client_auth() — HCSESSID cookie from /api/v1/client/auth/login/. Ownership is enforced server-side per row. |
TOKEN | REST v1 Bearer token (hc_…) with scopes — see section 0. |
CSRF | require_client_csrf() on every client mutation — send csrf_token (session token) or X-CSRF-Token. |
2. Health Telemetry
Database heartbeat + service readiness. Real response (live):
3. Client Authentication
| Field | Required | Notes |
|---|---|---|
name | yes | 2–128 chars |
email | yes | unique — 422 if taken |
username | yes | unique |
password | yes | 8+ chars, letter + number |
Creates account → verification email sent → must verify before login. Rate-limited (429).
| Field | Notes |
|---|---|
identifier or email | email OR username |
password | account password |
remember | bool — extends session |
csrf_token | required |
Sets the HCSESSID session cookie. Errors: unverified email, suspended account, invalid credentials, 429 lockout.
Passwordless login. Two-step: {"action":"request","identifier":"…"} emails a 6-digit code, then {"action":"verify","identifier":"…","code":"123456"} returns the session.
forgot/ — body {"identifier":"email-or-username"} → mails a reset linkreset/ — body {"token":"…","password":"…"} → sets new passwordverify/ — body {"token":"…"} → marks email verifiedlogout/ — destroys the session (client auth required)
4. Account
GET → profile ("Account loaded."). POST → update name or change password (current_password + password).
5. Catalog
| Param | Notes |
|---|---|
(none) | full catalog — plans with availability, regions, pricing |
?plan_id=N | resolve one plan → "Plan resolved." (404 Plan not found.) |
6. Wallet & Manual Deposits
Balance + transaction history → "Wallet loaded."
| Field | Notes |
|---|---|
amount | INR amount |
txn_ref | UPI/bank reference — unique, 422 on reuse |
screenshot | payment proof upload |
Submits a manual deposit for staff approval. Rate-limited (429). Duplicate txn_ref → 422.
7. Orders
?id=N → order detail; no param → list ("Orders loaded.").
| Field | Notes |
|---|---|
plan_id | catalog plan |
config | object — hostname, OS, server name, eula, region… |
domain | required for web plans |
idempotency_key | dedupe — same key + different payload → 409 idempotency_conflict |
Charges wallet atomically and queues the provisioning job. Errors: insufficient_funds (422), unavailable:<reason> (409), domain_required/bad_domain, bad_config_<field>.
8. Services & VPS
?id=&action=credentials|events|ssoPOST —
{"id":N,"action":"renew"} (wallet-charged renewal) · request_suspend · request_terminate (staff-reviewed)Errors:
not_owner, not_renewable, duplicate_request, insufficient_funds
Live power probe against the hypervisor/panel — "Live status retrieved."
Metrics time-series for charts. Invalid timeframe / Instance has no VM on bad input.
{"id":N,"action":"start|stop|restart|kill"} — power signals{"id":N,"action":"reinstall","os":"…","confirm":"…"} — OS reinstallErrors:
bad_signal, suspended, reinstall_running, confirmation_mismatch, hypervisor_not_configured
9. Game Server Management
Single multiplexed endpoint — ?service=N&action=…. Backed by Pterodactyl; ownership + install-state enforced per call.
| Group | Actions |
|---|---|
| Info | overview · resources · activity · events · network · provision_status |
| Console | console_ws (mints one-time ws ticket → ws://127.0.0.1:8755/?t=…) · command · power (start|stop|restart|kill) · eula_accept |
| Files | files · file_read · file_write · file_upload · file_upload_url · file_download · files_delete · files_rename · file_copy · files_compress · file_decompress · folder_create |
| Backups | backups · backup_create · backup_restore · backup_delete · backup_download |
| Databases | databases · db_create · db_delete · db_rotate |
| Schedules | schedules · schedule_create · schedule_update · schedule_delete · schedule_execute |
| Startup | startup · startup_var |
| Users | users · user_invite · user_update · user_remove |
| Lifecycle | settings_rename · reinstall |
Errors: not_game_service, no_server (still provisioning), server_installing, path_traversal, binary_file, file_too_large, ptero_forbidden.
10. Web Hosting (cPanel/WHM)
| Group | Actions |
|---|---|
| Info | overview · usage · events · nameservers · dns |
| Databases | databases · db_create · db_delete · db_assign · db_user_create · db_user_delete |
mailboxes · mailbox_create · mailbox_delete · mailbox_password · mailbox_quota | |
| Runtime | php · php_set · password_change |
| HTTPS | https_status · https_force · https_unforce |
Errors: not_web_service, no_panel_user, node_unreachable, weak_password, bad_db_name, bad_mailbox.
11. Notifications & Client Search
GET → list. POST {"action":"read","id":N} → "Marked as read."
Account-scoped global search — services, IPs, orders, wallet txns, deposits. Shape detection: IP/prefix/CIDR, MAC, email, pay_/order_ ids, #num, domain, text. Operators: type: status: loc: node: user:. Rate limit 30/10s → 429.