Koapanel
IT Try it free
All manual sections

DocumentationAPI and webhooks

API and webhooks

Every Koapanel server has a public REST API for billing systems and integrations other than WHMCS: accounts, resellers, packages, sites, databases, mail, usage, one-click login and webhooks. The full documentation, with examples ready to copy, is in API keys › API documentation; the OpenAPI 3.1 document is at /api/v1/openapi.json on the panel.

How to use it

  • Create a key in API keys and send it with every request: Authorization: Bearer kpk_…. The key acts as your account (a reseller sees only its clients).
  • Errors always look like {"error":{"code","message","field","requestId"}}.
  • Lists come in pages: ?limit= and ?cursor=, with nextCursor in the answer while more pages follow (with API keys 100 items per page when you give no limit).
  • POST requests accept Idempotency-Key: repeating the same request with the same key within 24 hours returns the first answer, without duplicates.
  • Every key can make 300 requests per minute; answers tell how many are left (X-RateLimit-Remaining).

Webhooks

In API keys › Webhooks you register the address of your system: for every event (account created, changed, suspended, reactivated, deleted, over its disk space, site created or deleted, new reseller) the panel sends a POST request signed with the webhook secret, shown only once. Test sends a test event at once; Deliveries shows the last sends and their outcome. If the address does not answer, the panel retries up to 5 times over the next two hours.

  • Administrators receive every event, resellers only their clients' events and only to public https:// addresses.
  • Always verify the signature (X-Koapanel-Signature) before trusting a request: the API documentation page shows how.

Monitoring (Prometheus and Grafana)

The panel address /api/v1/metrics answers the state of the server in the Prometheus format, also read by Grafana, Zabbix, Netdata, Datadog and Uptime Kuma: CPU, memory, disks, running services, online and suspended sites, space of every site, certificate expiry, last successful backup of every site, users, licence plan and available updates.

  • Create a key in API keys with an administrator user (for example "prometheus") and save it in a file on the Prometheus server.
  • Add the panel to the Prometheus configuration:
scrape_configs:
  - job_name: koapanel
    scheme: https
    metrics_path: /api/v1/metrics
    scrape_interval: 60s
    authorization:
      credentials_file: /etc/prometheus/koapanel.key
    tls_config:
      insecure_skip_verify: true   # only if the panel uses the self-signed certificate
    static_configs:
      - targets: ["panel.example.com:8443"]

Useful alerts: koapanel_service_up == 0 (a service is down), koapanel_site_ssl_expiry_timestamp_seconds - time() < 7*86400 (certificate expiring), time() - koapanel_site_last_backup_timestamp_seconds > 2*86400 (no backup for two days), koapanel_disk_free_bytes / koapanel_disk_total_bytes < 0.1 (disk almost full).