Control Panel API

Complete reference for the Quazzar Control Panel REST API. All endpoints use the /api/ prefix and require JWT bearer token authentication. Every request is scoped to the authenticated user’s tenant. The base URL is your Control Panel instance (for example, https://panel.quazzar.cloud/api/).

See Authentication for details on obtaining and using tokens.

Authentication

Endpoints for user registration, login, profile management, and TOTP two-factor authentication.

Method	Path	Description
`POST`	`/api/auth/register`	Register a new user account
`POST`	`/api/auth/login`	Authenticate and receive JWT tokens
`GET`	`/api/auth/me`	Get the current authenticated user
`PUT`	`/api/auth/profile`	Update user profile
`POST`	`/api/auth/change-password`	Change password
`POST`	`/api/auth/totp/enable`	Enable TOTP two-factor authentication
`POST`	`/api/auth/totp/verify`	Verify a TOTP code

Fleet Management

Monitor and manage all Cloud OS instances connected to the Control Panel. The fleet API provides a centralized view of instance health, metrics, and remote command execution.

Method	Path	Description
`GET`	`/api/fleet/instances`	List all connected Cloud OS instances
`GET`	`/api/fleet/summary`	Get fleet summary (total instances, health overview)
`GET`	`/api/fleet/health`	Get health status for all instances
`GET`	`/api/fleet/metrics/{instanceId}`	Get metrics for a specific instance
`GET`	`/api/fleet/instances/{id}/metrics/history`	Get historical metric data for a specific instance
`POST`	`/api/fleet/instances/{id}/impersonate`	Mint an impersonate token to open an OS session
`GET`	`/api/fleet/alerts`	List active alerts across the fleet
`POST`	`/api/fleet/commands`	Send a command to one or more instances
`POST`	`/api/fleet/tokens`	Generate a fleet enrollment token

Historical Metrics


curl "https://panel.quazzar.cloud/api/fleet/instances/inst_abc123/metrics/history?range=24h" \
  -H "Authorization: Bearer <token>"

Query parameters:

Parameter	Values	Default	Description
`range`	`1h`, `6h`, `24h`, `7d`, `30d`, `3mo`	`24h`	Time range to query
`metric`	`cpu`, `mem`, `disk`, `net`	(all)	Filter to a single metric

The response returns time-bucketed arrays of [timestamp, value] pairs. Data source is selected automatically: raw heartbeat data for ranges ≤ 6 h, hourly rollup for ≤ 30 d, daily rollup for longer ranges.

Impersonate (Open in Node)


curl -X POST "https://panel.quazzar.cloud/api/fleet/instances/inst_abc123/impersonate" \
  -H "Authorization: Bearer <token>"


{
  "session_url": "https://my-node.example.com/api/cp/session?token=<signed-jwt>"
}

Redirect the browser to session_url. The OS validates the token and creates an authenticated session. Tokens are single-use and expire after 60 seconds.

Example: List Fleet Instances


curl https://panel.quazzar.cloud/api/fleet/instances \
  -H "Authorization: Bearer <token>"


[
  {
    "id": "inst_abc123",
    "name": "production-01",
    "hostname": "cloud.example.com",
    "version": "0.2.9",
    "status": "healthy",
    "apps_count": 12,
    "cpu_percent": 35.2,
    "memory_percent": 62.1,
    "last_seen": "2025-01-15T10:30:00Z"
  },
  {
    "id": "inst_def456",
    "name": "staging-01",
    "hostname": "staging.example.com",
    "version": "0.2.9",
    "status": "healthy",
    "apps_count": 5,
    "cpu_percent": 12.8,
    "memory_percent": 28.4,
    "last_seen": "2025-01-15T10:29:55Z"
  }
]

Example: Get Fleet Summary


curl https://panel.quazzar.cloud/api/fleet/summary \
  -H "Authorization: Bearer <token>"


{
  "total_instances": 8,
  "healthy": 7,
  "degraded": 1,
  "offline": 0,
  "total_apps": 45,
  "total_cpu_cores": 32,
  "total_memory_gb": 128
}

Example: Send a Fleet Command


curl -X POST https://panel.quazzar.cloud/api/fleet/commands \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_ids": ["inst_abc123", "inst_def456"],
    "command": "update",
    "params": {
      "version": "0.3.0"
    }
  }'

Example: Generate Enrollment Token


curl -X POST https://panel.quazzar.cloud/api/fleet/tokens \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "datacenter-west",
    "expires_in_hours": 24
  }'


{
  "token": "flt_abc123def456...",
  "name": "datacenter-west",
  "expires_at": "2025-01-16T10:30:00Z"
}

Use fleet enrollment tokens to connect new Cloud OS instances to the Control Panel. Pass the token during Cloud OS initial configuration to automatically register the instance.

Billing

Manage subscriptions, usage, packages, and invoices for your tenant. All billing endpoints are Stripe-backed.

Method	Path	Description
`GET`	`/api/billing/subscription`	Get current subscription details
`PUT`	`/api/billing/subscription`	Update subscription plan
`GET`	`/api/billing/licenses`	List active licenses
`GET`	`/api/billing/usage`	Get current plan usage (nodes, users, storage)
`GET`	`/api/billing/packages`	List available plans and pricing
`GET`	`/api/billing/invoices`	List Stripe invoices (60 s cache)

Example: Get Subscription


curl https://panel.quazzar.cloud/api/billing/subscription \
  -H "Authorization: Bearer <token>"


{
  "plan": "pro",
  "status": "active",
  "instance_limit": 25,
  "instances_used": 8,
  "features": ["fleet-management", "ha-clustering", "governance", "priority-support"],
  "billing_cycle": "monthly",
  "next_invoice_date": "2025-02-01T00:00:00Z"
}

Example: Get Usage


curl https://panel.quazzar.cloud/api/billing/usage \
  -H "Authorization: Bearer <token>"


{
  "nodes": { "used": 8, "limit": 25 },
  "users": { "used": 12, "limit": 50 },
  "storage_gb": { "used": 42.3, "limit": 500 }
}

Example: List Invoices


curl https://panel.quazzar.cloud/api/billing/invoices \
  -H "Authorization: Bearer <token>"


[
  {
    "id": "in_1abc...",
    "date": "2026-05-01T00:00:00Z",
    "period_start": "2026-04-01T00:00:00Z",
    "period_end": "2026-04-30T23:59:59Z",
    "amount_due": 4900,
    "currency": "usd",
    "status": "paid",
    "pdf_url": "https://invoice.stripe.com/..."
  }
]

OAuth (CP as IdP)

The Control Panel acts as an OAuth 2.0 Authorization Code identity provider for connected Cloud OS nodes. These endpoints are used by the “Sign in with Quazzar Cloud” flow on the OS login page.

Method	Path	Description
`GET`	`/api/oauth/authorize/preflight`	Check whether the requesting node is authorized to start the flow
`POST`	`/api/oauth/authorize/consent`	User approves the authorization; returns a redirect with a code
`POST`	`/api/oauth/token`	Exchange an authorization code for a CP-signed identity assertion

Flow overview

The OS redirects the user to the CP authorization URL with client_id, redirect_uri, state, and code_challenge.
The CP calls GET /api/oauth/authorize/preflight to verify the node is registered and the redirect_uri matches.
The user approves on the CP consent screen (POST /api/oauth/authorize/consent).
The CP redirects to the OS redirect_uri with a single-use, time-limited code and the original state.
The OS calls POST /api/oauth/token to exchange the code for an identity token, then creates a local session.

Codes are stored in oauth_codes (migration 073), are single-use, and expire after 5 minutes.

Governance

Manage compliance policies, canary deployments, GitOps configurations, and governance scores across your fleet.

Method	Path	Description
`GET`	`/api/governance/policies`	List governance policies
`POST`	`/api/governance/policies`	Create a governance policy
`PUT`	`/api/governance/policies/{id}`	Update a governance policy
`DELETE`	`/api/governance/policies/{id}`	Delete a governance policy
`GET`	`/api/governance/canary`	List canary deployments
`POST`	`/api/governance/canary`	Create a canary deployment
`PUT`	`/api/governance/canary/{id}`	Update a canary deployment
`GET`	`/api/governance/gitops`	List GitOps configurations
`POST`	`/api/governance/gitops`	Create a GitOps configuration
`PUT`	`/api/governance/gitops/{id}`	Update a GitOps configuration
`GET`	`/api/governance/scores`	Get governance scores across the fleet

Example: Create a Governance Policy


curl -X POST https://panel.quazzar.cloud/api/governance/policies \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Require encrypted backups",
    "type": "backup",
    "rule": {
      "condition": "backup.encryption",
      "operator": "equals",
      "value": true
    },
    "enforcement": "mandatory",
    "applies_to": "all_instances"
  }'

Example: Get Governance Scores


curl https://panel.quazzar.cloud/api/governance/scores \
  -H "Authorization: Bearer <token>"


{
  "overall_score": 87,
  "by_instance": [
    {
      "instance_id": "inst_abc123",
      "name": "production-01",
      "score": 92,
      "violations": 1
    },
    {
      "instance_id": "inst_def456",
      "name": "staging-01",
      "score": 78,
      "violations": 4
    }
  ]
}

Kubernetes

Manage Kubernetes clusters and deployments through the Control Panel.

Method	Path	Description
`GET`	`/api/k8s/clusters`	List Kubernetes clusters
`POST`	`/api/k8s/clusters`	Register a Kubernetes cluster
`GET`	`/api/k8s/clusters/{id}`	Get cluster details
`PUT`	`/api/k8s/clusters/{id}`	Update cluster configuration
`DELETE`	`/api/k8s/clusters/{id}`	Remove a cluster
`GET`	`/api/k8s/deployments`	List deployments across clusters
`POST`	`/api/k8s/deployments`	Create a deployment
`GET`	`/api/k8s/deployments/{id}`	Get deployment details
`PUT`	`/api/k8s/deployments/{id}`	Update a deployment
`DELETE`	`/api/k8s/deployments/{id}`	Delete a deployment

Example: List Clusters


curl https://panel.quazzar.cloud/api/k8s/clusters \
  -H "Authorization: Bearer <token>"


[
  {
    "id": "k8s_abc123",
    "name": "production-cluster",
    "provider": "hetzner",
    "version": "1.29",
    "nodes": 5,
    "status": "healthy",
    "region": "eu-central"
  }
]

High Availability

Manage high availability clustering and failover for the Control Panel itself.

Method	Path	Description
`GET`	`/api/cc/ha/status`	Get HA cluster status
`GET`	`/api/cc/ha/nodes`	List HA cluster nodes
`POST`	`/api/cc/ha/failover`	Trigger a manual failover
`POST`	`/api/cc/ha/upgrade`	Initiate a rolling upgrade

Example: Get HA Status


curl https://panel.quazzar.cloud/api/cc/ha/status \
  -H "Authorization: Bearer <token>"


{
  "mode": "active-passive",
  "status": "healthy",
  "leader": "node-1",
  "nodes": 3,
  "replication_lag_ms": 12,
  "last_failover": "2025-01-10T08:15:00Z"
}

Hosting

Manage hosting providers, servers, and infrastructure resources.

Method	Path	Description
`GET`	`/api/hosting/providers`	List configured hosting providers
`GET`	`/api/hosting/servers`	List provisioned servers
`POST`	`/api/hosting/servers`	Provision a new server
`GET`	`/api/hosting/servers/{id}`	Get server details
`DELETE`	`/api/hosting/servers/{id}`	Decommission a server
`GET`	`/api/hosting/regions`	List available regions
`GET`	`/api/hosting/sizes`	List available server sizes

Example: Provision a Server


curl -X POST https://panel.quazzar.cloud/api/hosting/servers \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "hetzner",
    "region": "eu-central",
    "size": "cx31",
    "name": "production-03",
    "install_cloud_os": true
  }'


{
  "id": "srv_abc123",
  "name": "production-03",
  "provider": "hetzner",
  "region": "eu-central",
  "size": "cx31",
  "status": "provisioning",
  "ip_address": null,
  "created_at": "2025-01-15T10:30:00Z"
}

MSP (Managed Service Provider)

Endpoints for managed service providers to manage client organizations and white-label branding.

Method	Path	Description
`GET`	`/api/msp/clients`	List MSP client organizations
`POST`	`/api/msp/clients`	Create a client organization
`GET`	`/api/msp/clients/{id}`	Get client details
`PUT`	`/api/msp/clients/{id}`	Update client configuration
`DELETE`	`/api/msp/clients/{id}`	Remove a client
`GET`	`/api/msp/branding`	Get current branding configuration
`PUT`	`/api/msp/branding`	Update white-label branding

Example: Create an MSP Client


curl -X POST https://panel.quazzar.cloud/api/msp/clients \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "contact_email": "[email protected]",
    "instance_limit": 10,
    "plan": "pro"
  }'

Example: Update White-Label Branding


curl -X PUT https://panel.quazzar.cloud/api/msp/branding \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "CloudHost Pro",
    "logo_url": "https://cdn.cloudhost.pro/logo.svg",
    "primary_color": "#2563EB",
    "support_email": "[email protected]"
  }'

MSP features require the Enterprise plan. Client organizations are fully isolated tenants with their own instances, users, and billing.

Partners

Manage partner relationships and partner tier configurations.

Method	Path	Description
`GET`	`/api/partners`	List partner organizations
`POST`	`/api/partners`	Register as a partner
`GET`	`/api/partners/{id}`	Get partner details
`PUT`	`/api/partners/{id}`	Update partner information
`GET`	`/api/partner-tiers`	List available partner tiers

Example: List Partner Tiers


curl https://panel.quazzar.cloud/api/partner-tiers \
  -H "Authorization: Bearer <token>"


[
  {
    "id": "tier_silver",
    "name": "Silver",
    "discount_percent": 10,
    "min_instances": 5,
    "features": ["priority-support", "co-branding"]
  },
  {
    "id": "tier_gold",
    "name": "Gold",
    "discount_percent": 20,
    "min_instances": 25,
    "features": ["priority-support", "co-branding", "dedicated-account-manager"]
  }
]