HCL Platform API

Version 1 — REST / JSON
Stable

Overview

The HCL Platform API is a RESTful API that accepts JSON request bodies and returns JSON responses. All timestamps are ISO 8601 in UTC. Amounts are in minor currency units (e.g., cents) unless stated otherwise.

Base URL: https://api.hclhosting.com/v1

Authentication

Pass your API key as a Bearer token in the Authorization header. API keys are scoped per tenant and carry permission scopes.

Authorization: Bearer hcl_live_xxxxxxxxxxxxxxxxxxxx
200 OK
201 Created
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
422 Unprocessable
500 Server Error

Authentication

Method Path Description Auth
POST /auth/login Obtain a short-lived JWT (email + password)
POST /auth/refresh Refresh an expired JWT
POST /auth/logout Invalidate the current JWT
POST /auth/2fa/verify Complete TOTP 2FA challenge
GET /auth/me Return the authenticated user profile

Tenants

Method Path Description Auth
GET /tenants List tenants (platform admin only)
POST /tenants Provision a new tenant
GET /tenants/{id} Get a single tenant
PUT /tenants/{id} Update tenant settings
DELETE /tenants/{id} Terminate a tenant (soft delete)
GET /tenants/{id}/usage Fetch usage summary for the tenant

Customers

Method Path Description Auth
GET /customers List customers for the authenticated tenant
POST /customers Create a new customer account
GET /customers/{id} Get a customer record
PUT /customers/{id} Update customer profile / contact details
DELETE /customers/{id} Deactivate a customer account
GET /customers/{id}/services List all services owned by the customer

Services

Method Path Description Auth
GET /services List service instances
GET /services/{id} Get a service instance
POST /services/{id}/suspend Suspend a service instance
POST /services/{id}/unsuspend Unsuspend a service instance
POST /services/{id}/terminate Terminate a service instance
POST /services/{id}/renew Trigger manual renewal

Orders

Method Path Description Auth
GET /orders List orders
POST /orders Place a new order
GET /orders/{id} Get order details
POST /orders/{id}/cancel Cancel a pending order

Billing

Method Path Description Auth
GET /invoices List invoices
GET /invoices/{id} Get a single invoice
GET /invoices/{id}/pdf Download invoice as PDF
GET /subscriptions List active subscriptions
GET /subscriptions/{id} Get subscription details
DELETE /subscriptions/{id} Cancel a subscription
GET /payments List payment transactions
POST /payments Record a manual payment
GET /wallet Get wallet / credit balance
POST /wallet/topup Add credits to the wallet

Domains

Method Path Description Auth
GET /domains List domain services
POST /domains/check Check availability of a domain name
POST /domains/register Register a new domain
POST /domains/transfer Initiate a domain transfer
GET /domains/{id} Get domain details
PUT /domains/{id}/nameservers Update nameservers
POST /domains/{id}/renew Renew a domain

Hosting

Method Path Description Auth
GET /hosting List hosting accounts
POST /hosting Create a hosting account
GET /hosting/{id} Get hosting account details
POST /hosting/{id}/reset-password Reset cPanel/DirectAdmin password
GET /hosting/{id}/stats Get disk / bandwidth usage stats

SSL Certificates

Method Path Description Auth
GET /ssl List SSL certificates
POST /ssl Order a new SSL certificate
GET /ssl/{id} Get certificate details
POST /ssl/{id}/renew Renew an SSL certificate
POST /ssl/{id}/reissue Reissue an SSL certificate
GET /ssl/{id}/download Download certificate bundle (zip)

DNS Zones

Method Path Description Auth
GET /dns/zones List DNS zones
POST /dns/zones Create a DNS zone
GET /dns/zones/{id} Get a DNS zone
DELETE /dns/zones/{id} Delete a DNS zone
GET /dns/zones/{id}/records List records in a zone
POST /dns/zones/{id}/records Add a DNS record
PUT /dns/zones/{id}/records/{rid} Update a DNS record
DELETE /dns/zones/{id}/records/{rid} Delete a DNS record

Email Hosting

Method Path Description Auth
GET /email List email hosting services
POST /email Create an email hosting account
GET /email/{id} Get email service details
POST /email/{id}/mailboxes Create a mailbox
DELETE /email/{id}/mailboxes/{mbx} Delete a mailbox

VPS / Cloud

Method Path Description Auth
GET /vps List VPS instances
POST /vps Provision a new VPS
GET /vps/{id} Get VPS details
POST /vps/{id}/start Start a VPS
POST /vps/{id}/stop Stop a VPS
POST /vps/{id}/reboot Reboot a VPS
POST /vps/{id}/resize Resize (upgrade/downgrade) a VPS
DELETE /vps/{id} Terminate a VPS

Support Tickets

Method Path Description Auth
GET /support/tickets List support tickets
POST /support/tickets Open a new support ticket
GET /support/tickets/{id} Get ticket details + replies
POST /support/tickets/{id}/replies Post a reply to a ticket
POST /support/tickets/{id}/close Close a ticket

Webhooks

Method Path Description Auth
GET /webhooks List webhook endpoints
POST /webhooks Register a new webhook endpoint
GET /webhooks/{id} Get webhook endpoint details
PUT /webhooks/{id} Update webhook endpoint
DELETE /webhooks/{id} Delete a webhook endpoint
GET /webhooks/{id}/deliveries List delivery attempts
POST /webhooks/{id}/test Send a test payload

API Keys

Method Path Description Auth
GET /api-keys List API keys for the tenant
POST /api-keys Create a new API key
GET /api-keys/{id} Get API key metadata
DELETE /api-keys/{id} Revoke an API key
GET /api-keys/{id}/usage Get usage stats for a key

Request / Response Examples

POST /v1/auth/login

Request

{
  "email": "admin@example.com",
  "password": "secret",
  "totp_code": "123456"
}

Response 200

{
  "token": "eyJhbGci...",
  "expires_at": "2025-03-14T12:00:00Z",
  "user": {
    "id": "uuid",
    "email": "admin@example.com",
    "tenant_id": "uuid"
  }
}

POST /v1/orders

Request

{
  "customer_id": "uuid",
  "items": [
    {
      "sku_id": "uuid",
      "quantity": 1,
      "billing_cycle": "1_year",
      "config": {
        "domain": "example.com",
        "plan": "starter"
      }
    }
  ],
  "payment_method": "wallet"
}

Response 201

{
  "id": "uuid",
  "status": "processing",
  "total_amount": 999,
  "currency": "USD",
  "invoice_id": "uuid",
  "services": ["uuid"],
  "created_at": "2025-03-13T10:00:00Z"
}

Error Response Format (422)

{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."],
    "billing_cycle": ["Must be one of: hourly, one_time, monthly, quarterly, semi_annual, 1_year ... 10_year."]
  }
}

Rate Limits

Tier Limit Window Header
Default 60 requests 1 minute X-RateLimit-Limit, X-RateLimit-Remaining
Reseller 300 requests 1 minute X-RateLimit-Limit, X-RateLimit-Remaining
Platform 1000 requests 1 minute X-RateLimit-Limit, X-RateLimit-Remaining
Auth 10 requests 1 minute 429 Too Many Requests on breach