diff --git a/docs/CyberPanel_Cloud_API_DOCS.md b/docs/CyberPanel_Cloud_API_DOCS.md new file mode 100644 index 000000000..57643264a --- /dev/null +++ b/docs/CyberPanel_Cloud_API_DOCS.md @@ -0,0 +1,1246 @@ +# CyberPanel Cloud Platform - VPS API Documentation + +**Version:** 1.0.0 +**Base URL:** `https://platform.cyberpersons.com/api/v1` +**Last Updated:** January 2026 + +--- + +## Table of Contents + +1. [Introduction](#introduction) +2. [Authentication](#authentication) +3. [Rate Limiting](#rate-limiting) +4. [Response Format](#response-format) +5. [Error Codes](#error-codes) +6. [Endpoints](#endpoints) + - [General](#general-endpoints) + - [Account & Billing](#account--billing-endpoints) + - [VPS Management](#vps-management-endpoints) + - [VPS Actions](#vps-action-endpoints) + - [VPS Creation](#vps-creation-endpoints) + +--- + +## Introduction + +The CyberPanel Cloud Platform API allows you to programmatically manage your VPS instances, view account information, and automate your infrastructure. This RESTful API uses JSON for request and response bodies. + +### Quick Start + +1. Create an API key at https://platform.cyberpersons.com/api-keys/ +2. Copy your key (shown only once) +3. Include it in the `Authorization` header: + ``` + Authorization: Bearer cyp_live_your_api_key_here + ``` + +--- + +## Authentication + +All API requests (except `/health` and `/scopes`) require authentication using an API key. + +### API Key Format + +API keys have the format: `cyp_live_<64_character_hex_string>` + +Example: `cyp_live_3ac1ca2feaADSRTSAFDbcdd86f2dc01c4a574e4a34EWRWEb9d995a28723caERERE` + +### Authorization Header + +Include your API key in the `Authorization` header using the Bearer scheme: + +``` +Authorization: Bearer cyp_live_your_api_key_here +``` + +### Permission Scopes + +API keys have granular permission scopes. When creating an API key, select only the scopes you need: + +| Scope | Description | +|-------|-------------| +| `vps:read` | List and view VPS instances, plans, locations, templates | +| `vps:write` | Create, start, stop, restart, and modify VPS instances | +| `vps:delete` | Delete VPS instances (destructive action) | +| `account:read` | View account information and API key metadata | +| `account:write` | Update account settings | +| `billing:read` | View balance, invoices, and billing information | +| `billing:write` | Add funds to account | +| `support:read` | View support tickets | +| `support:write` | Create and reply to support tickets | +| `email:read` | View email service information | +| `email:write` | Send emails via Email Delivery Service | +| `all` | Full access to all permissions | + +### Security Features + +- **Key Hashing:** Keys are SHA-256 hashed before storage - we never store plain keys +- **IP Whitelisting:** Optionally restrict key usage to specific IP addresses +- **Expiration Dates:** Set optional expiration dates for keys +- **Usage Tracking:** All requests are logged for security auditing + +--- + +## Rate Limiting + +API keys have configurable rate limits to prevent abuse: + +| Limit Type | Default | Description | +|------------|---------|-------------| +| Per Minute | 60 requests | Requests allowed per minute | +| Per Hour | 1000 requests | Requests allowed per hour | + +### Rate Limit Headers + +Responses include rate limit information in headers: + +``` +X-RateLimit-Limit: 60 +X-RateLimit-Remaining: 58 +X-RateLimit-Reset: 1704067200 +``` + +### Rate Limit Exceeded (HTTP 429) + +When you exceed the rate limit: + +```json +{ + "success": false, + "error": "Rate limit exceeded", + "error_code": "RATE_LIMIT_EXCEEDED", + "message": "You have exceeded the per minute rate limit. Please retry after 45 seconds." +} +``` + +The response includes a `Retry-After` header indicating seconds to wait. + +--- + +## Response Format + +### Success Response + +```json +{ + "success": true, + "data": { + // Response data here + }, + "message": "Optional success message" +} +``` + +### Error Response + +```json +{ + "success": false, + "error": "Error description", + "error_code": "ERROR_CODE", + "message": "Human-readable explanation" +} +``` + +--- + +## Error Codes + +### Authentication Errors (4xx) + +| Error Code | HTTP Status | Description | +|------------|-------------|-------------| +| `NO_API_KEY` | 401 | No API key provided | +| `INVALID_API_KEY` | 401 | API key is invalid or malformed | +| `EXPIRED_API_KEY` | 401 | API key has expired | +| `INACTIVE_API_KEY` | 401 | API key has been deactivated | +| `IP_NOT_ALLOWED` | 403 | Request IP not in key's whitelist | +| `INSUFFICIENT_SCOPE` | 403 | API key lacks required permissions | +| `RATE_LIMIT_EXCEEDED` | 429 | Too many requests | + +### Resource Errors (4xx) + +| Error Code | HTTP Status | Description | +|------------|-------------|-------------| +| `VPS_NOT_FOUND` | 404 | VPS instance doesn't exist or isn't owned by you | +| `VPS_DELETED` | 400 | VPS has already been deleted | +| `VPS_SUSPENDED` | 403 | VPS is suspended (check suspension reason) | +| `VPS_ALREADY_DELETED` | 400 | Attempted to delete already-deleted VPS | +| `PLAN_NOT_FOUND` | 400 | Invalid plan_id | +| `LOCATION_NOT_FOUND` | 400 | Invalid location_code | +| `INVALID_TEMPLATE` | 400 | Invalid template_id | +| `KEY_NOT_FOUND` | 404 | API key doesn't exist | + +### Validation Errors (4xx) + +| Error Code | HTTP Status | Description | +|------------|-------------|-------------| +| `MISSING_FIELDS` | 400 | Required fields not provided | +| `INVALID_HOSTNAME` | 400 | Hostname format invalid | +| `PASSWORD_TOO_SHORT` | 400 | Password must be at least 8 characters | +| `PASSWORD_TOO_LONG` | 400 | Password must not exceed 72 characters | +| `PASSWORD_WEAK` | 400 | Password must contain letters AND numbers | +| `INSUFFICIENT_BALANCE` | 400 | Account balance too low | + +### Server Errors (5xx) + +| Error Code | HTTP Status | Description | +|------------|-------------|-------------| +| `START_FAILED` | 500 | Failed to start VPS | +| `STOP_FAILED` | 500 | Failed to stop VPS | +| `RESTART_FAILED` | 500 | Failed to restart VPS | +| `DELETE_FAILED` | 500 | Failed to delete VPS | +| `STATUS_FAILED` | 500 | Failed to get VPS status | +| `CONSOLE_FAILED` | 500 | Failed to get console access | +| `DEPLOYMENT_FAILED` | 500 | VPS deployment failed | +| `NODE_NOT_FOUND` | 500 | Proxmox node not found | + +--- + +## Endpoints + +### General Endpoints + +#### Health Check + +Check if the API is operational. No authentication required. + +``` +GET /api/v1/health +``` + +**Response:** +```json +{ + "success": true, + "data": { + "status": "healthy", + "service": "CyberPanel Cloud API", + "version": "1.0.0" + } +} +``` + +--- + +#### Test Authentication + +Verify your API key is working. + +``` +GET /api/v1/test +``` + +**Required Scope:** Any valid API key + +**Response:** +```json +{ + "success": true, + "data": { + "message": "API authentication successful!", + "key_name": "My Production Key", + "key_prefix": "cyp_live_3ac", + "user_email": "user@example.com", + "scopes": ["vps:read", "vps:write"], + "ip_address": "203.0.113.50", + "request_count": 142 + }, + "message": "Your API key is working correctly" +} +``` + +--- + +#### List Available Scopes + +List all available permission scopes. No authentication required. + +``` +GET /api/v1/scopes +``` + +**Response:** +```json +{ + "success": true, + "data": { + "scopes": [ + {"scope": "vps:read", "description": "VPS - Read"}, + {"scope": "vps:write", "description": "VPS - Create/Modify"}, + {"scope": "vps:delete", "description": "VPS - Delete"}, + {"scope": "billing:read", "description": "Billing - Read"}, + {"scope": "billing:write", "description": "Billing - Add Funds"}, + {"scope": "account:read", "description": "Account - Read Info"}, + {"scope": "all", "description": "Full Access - All Permissions"} + ] + } +} +``` + +--- + +### Account & Billing Endpoints + +#### Get Account Info + +``` +GET /api/v1/account +``` + +**Required Scope:** `account:read` + +**Response:** +```json +{ + "success": true, + "data": { + "id": 123, + "email": "user@example.com", + "full_name": "John Doe", + "balance": "150.00", + "status": "active", + "two_factor_enabled": true, + "vps_ordering_enabled": true, + "registration_date": "2024-01-15T10:30:00Z" + } +} +``` + +--- + +#### Get Billing Info + +``` +GET /api/v1/billing +``` + +**Required Scope:** `billing:read` + +**Response:** +```json +{ + "success": true, + "data": { + "balance": "150.00", + "auto_funding": { + "enabled": true, + "threshold": "10.00", + "amount": "50.00" + }, + "recent_invoices": [ + { + "id": 456, + "description": "VPS Hourly Charge - my-server.example.com", + "amount": "-0.0082", + "type": "debit", + "date": "2026-01-05T12:00:00Z" + } + ] + } +} +``` + +--- + +#### List API Keys + +List all your API keys (metadata only, not the actual keys). + +``` +GET /api/v1/account/api-keys +``` + +**Required Scope:** `account:read` + +**Response:** +```json +{ + "success": true, + "data": { + "api_keys": [ + { + "id": 1, + "name": "Production Key", + "key_prefix": "cyp_live_3ac", + "scopes": ["vps:read", "vps:write"], + "is_active": true, + "ip_whitelist": [], + "expires_at": null, + "last_used_at": "2026-01-05T14:30:00Z", + "last_used_ip": "203.0.113.50", + "request_count": 142, + "rate_limit_per_minute": 60, + "rate_limit_per_hour": 1000, + "created_at": "2025-12-01T09:00:00Z" + } + ], + "total": 1 + } +} +``` + +--- + +#### Get API Key Usage Logs + +``` +GET /api/v1/account/api-keys/{key_id}/usage +``` + +**Required Scope:** `account:read` + +**Query Parameters:** + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `limit` | integer | 50 | Number of records (max 100) | +| `offset` | integer | 0 | Pagination offset | + +**Response:** +```json +{ + "success": true, + "data": { + "key_id": 1, + "key_name": "Production Key", + "usage_logs": [ + { + "endpoint": "/api/v1/vps", + "method": "GET", + "ip_address": "203.0.113.50", + "response_status": 200, + "response_time_ms": 45, + "created_at": "2026-01-05T14:30:00Z" + } + ], + "pagination": { + "limit": 50, + "offset": 0, + "total": 142, + "has_more": true + } + } +} +``` + +--- + +### VPS Management Endpoints + +#### List VPS Instances + +``` +GET /api/v1/vps +``` + +**Required Scope:** `vps:read` + +**Query Parameters:** + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `status` | string | - | Filter by status: `running`, `stopped`, `suspended` | +| `location` | string | - | Filter by location code: `la`, `de`, `eu` | +| `limit` | integer | 50 | Number of results (max 100) | +| `offset` | integer | 0 | Pagination offset | + +**Response:** +```json +{ + "success": true, + "data": { + "instances": [ + { + "id": 45, + "vmid": 281, + "name": "my-server.example.com", + "status": "running", + "ip_address": "74.81.40.145", + "is_suspended": false, + "created_at": "2026-01-05T10:00:00Z" + } + ], + "pagination": { + "total": 3, + "limit": 50, + "offset": 0, + "has_more": false + } + } +} +``` + +--- + +#### Get VPS Details + +``` +GET /api/v1/vps/{id} +``` + +**Required Scope:** `vps:read` + +**Response:** +```json +{ + "success": true, + "data": { + "id": 45, + "vmid": 281, + "name": "my-server.example.com", + "status": "running", + "ip_address": "74.81.40.145", + "is_suspended": false, + "created_at": "2026-01-05T10:00:00Z", + "updated_at": "2026-01-05T14:30:00Z", + "plan": { + "id": 1, + "name": "Starter", + "cpu_cores": 1, + "ram_mb": 1024, + "disk_gb": 25, + "bandwidth_gb": 1000, + "price": "6.00" + }, + "location": { + "code": "la", + "name": "Los Angeles, USA" + }, + "server": { + "hostname": "lax-power.cyberpersons.com" + }, + "billing": { + "hourly_rate": "0.0082", + "billing_start": "2026-01-05T10:00:00Z", + "last_billed": "2026-01-05T14:00:00Z" + } + } +} +``` + +--- + +#### Get VPS Dashboard Summary + +``` +GET /api/v1/vps/summary +``` + +**Required Scope:** `vps:read` + +**Response:** +```json +{ + "success": true, + "data": { + "total_instances": 3, + "running": 2, + "stopped": 1, + "suspended": 0, + "total_monthly_cost": "18.00", + "locations": { + "la": 2, + "de": 1 + } + } +} +``` + +--- + +#### Get VPS Live Status + +Get real-time metrics from Proxmox. + +``` +GET /api/v1/vps/{id}/status +``` + +**Required Scope:** `vps:read` + +**Response:** +```json +{ + "success": true, + "data": { + "vps_id": 45, + "vmid": 281, + "name": "my-server.example.com", + "status": "running", + "qmpstatus": "running", + "cpu": { + "usage_percent": 2.5, + "cores": 1 + }, + "memory": { + "used_bytes": 536870912, + "total_bytes": 1073741824, + "usage_percent": 50.0 + }, + "disk": { + "read_bytes": 1234567890, + "write_bytes": 987654321 + }, + "network": { + "in_bytes": 5678901234, + "out_bytes": 1234567890 + }, + "uptime_seconds": 86400, + "pid": 12345 + } +} +``` + +--- + +#### List VPS Plans + +``` +GET /api/v1/vps/plans +``` + +**Required Scope:** `vps:read` + +**Response:** +```json +{ + "success": true, + "data": { + "plans": [ + { + "id": 1, + "name": "Starter", + "cpu_cores": 1, + "ram_mb": 1024, + "disk_gb": 25, + "bandwidth_gb": 1000, + "monthly_price": "6.00", + "price_hourly": "0.0082" + }, + { + "id": 2, + "name": "Basic", + "cpu_cores": 2, + "ram_mb": 2048, + "disk_gb": 50, + "bandwidth_gb": 2000, + "monthly_price": "12.00", + "price_hourly": "0.0164" + } + ] + } +} +``` + +--- + +#### List Locations + +``` +GET /api/v1/vps/locations +``` + +**Required Scope:** `vps:read` + +**Response:** +```json +{ + "success": true, + "data": { + "locations": [ + { + "code": "la", + "name": "Los Angeles, USA", + "country": "US", + "available_ips": 15, + "is_available": true + }, + { + "code": "de", + "name": "Falkenstein, Germany", + "country": "DE", + "available_ips": 8, + "is_available": true + } + ] + } +} +``` + +--- + +#### List OS Templates + +``` +GET /api/v1/vps/templates +``` + +**Required Scope:** `vps:read` + +**Response:** +```json +{ + "success": true, + "data": { + "templates": [ + {"id": "101", "name": "CyberPanel", "os": "AlmaLinux 8", "description": "CyberPanel pre-installed with OpenLiteSpeed"}, + {"id": "9000", "name": "Ubuntu 22.04", "os": "Ubuntu 22.04 LTS", "description": "Clean Ubuntu 22.04 LTS installation"}, + {"id": "9022", "name": "Ubuntu 24.04", "os": "Ubuntu 24.04 LTS", "description": "Clean Ubuntu 24.04 LTS installation"}, + {"id": "9010", "name": "Debian 12", "os": "Debian 12", "description": "Clean Debian 12 installation"}, + {"id": "9001", "name": "AlmaLinux 8", "os": "AlmaLinux 8", "description": "Clean AlmaLinux 8 installation"}, + {"id": "9008", "name": "AlmaLinux 9", "os": "AlmaLinux 9", "description": "Clean AlmaLinux 9 installation"}, + {"id": "9125", "name": "Windows Server 2022", "os": "Windows Server 2022", "description": "Windows Server 2022 (requires $20 min balance)"} + ] + } +} +``` + +--- + +### VPS Action Endpoints + +#### Start VPS + +``` +POST /api/v1/vps/{id}/start +``` + +**Required Scope:** `vps:write` + +**Response:** +```json +{ + "success": true, + "data": { + "id": 45, + "vmid": 281, + "name": "my-server.example.com", + "status": "running", + "ip_address": "74.81.40.145" + }, + "message": "VPS started successfully" +} +``` + +--- + +#### Stop VPS + +``` +POST /api/v1/vps/{id}/stop +``` + +**Required Scope:** `vps:write` + +**Response:** +```json +{ + "success": true, + "data": { + "id": 45, + "vmid": 281, + "name": "my-server.example.com", + "status": "stopped", + "ip_address": "74.81.40.145" + }, + "message": "VPS stopped successfully" +} +``` + +--- + +#### Restart VPS + +``` +POST /api/v1/vps/{id}/restart +``` + +**Required Scope:** `vps:write` + +**Response:** +```json +{ + "success": true, + "data": { + "id": 45, + "vmid": 281, + "name": "my-server.example.com", + "status": "running", + "ip_address": "74.81.40.145" + }, + "message": "VPS restarted successfully" +} +``` + +--- + +#### Delete VPS + +**WARNING:** This permanently deletes the VPS and all data. This action cannot be undone. + +``` +POST /api/v1/vps/{id}/delete +``` + +**Required Scope:** `vps:write` + +**Response:** +```json +{ + "success": true, + "data": { + "deleted": true, + "vps_id": 45, + "name": "my-server.example.com", + "vmid": 281 + }, + "message": "VPS \"my-server.example.com\" deleted successfully" +} +``` + +--- + +#### Get Console Access + +Get noVNC console URL for browser-based access. + +``` +GET /api/v1/vps/{id}/console +``` + +**Required Scope:** `vps:read` + +**Response:** +```json +{ + "success": true, + "data": { + "vps_id": 45, + "console_url": "https://lax-power.cyberpersons.com:8006/?console=kvm&novnc=1&vmid=281&node=lax-power", + "type": "novnc", + "expires_in_seconds": 300 + }, + "message": "Console URL generated. Valid for 5 minutes." +} +``` + +--- + +### VPS Creation Endpoints + +#### Create VPS + +``` +POST /api/v1/vps/create +``` + +**Required Scope:** `vps:write` + +**Request Body:** + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `hostname` | string | Yes | FQDN hostname (e.g., `my-server.example.com`) | +| `plan_id` | integer | Yes | Plan ID from `/vps/plans` | +| `location_code` | string | Yes | Location code from `/vps/locations` | +| `template_id` | string | Yes | Template ID from `/vps/templates` | +| `root_password` | string | Yes | Root password (8-72 chars, must have letters AND numbers) | +| `ssh_key` | string | No | SSH public key for root access | +| `webhook_url` | string | No | URL to notify when deployment completes/fails | +| `webhook_secret` | string | No | Secret for webhook signature verification | + +**Example Request:** +```json +{ + "hostname": "my-server.example.com", + "plan_id": 1, + "location_code": "la", + "template_id": "9000", + "root_password": "SecurePass123", + "ssh_key": "ssh-rsa AAAAB3NzaC1yc2E...", + "webhook_url": "https://your-server.com/webhook" +} +``` + +**Response:** +```json +{ + "success": true, + "data": { + "vps_id": 46, + "name": "my-server.example.com", + "status": "deploying", + "ip_address": "74.81.40.146", + "plan": { + "id": 1, + "name": "Starter", + "price": "6.00" + }, + "location": "la", + "template": "9000", + "deployment_url": "/api/v1/vps/46/deployment", + "estimated_time_seconds": 180, + "webhook_configured": true + }, + "message": "VPS deployment started. Use the deployment endpoint to check progress." +} +``` + +--- + +#### Get Deployment Status + +Poll this endpoint to track VPS deployment progress. + +``` +GET /api/v1/vps/{id}/deployment +``` + +**Required Scope:** `vps:read` + +**Response (In Progress):** +```json +{ + "success": true, + "data": { + "vps_id": 46, + "deployment_status": "in_progress", + "vps_status": "deploying", + "current_task": "configure_network", + "progress_percent": 70, + "tasks": [ + {"name": "validate_resources", "status": "completed", "order": 1}, + {"name": "allocate_ip", "status": "completed", "order": 2}, + {"name": "create_vm", "status": "completed", "order": 3}, + {"name": "configure_hardware", "status": "completed", "order": 4}, + {"name": "apply_cloud_init", "status": "completed", "order": 5}, + {"name": "start_vm", "status": "completed", "order": 6}, + {"name": "configure_network", "status": "in_progress", "order": 7}, + {"name": "wait_for_guest_agent", "status": "pending", "order": 8}, + {"name": "verify_connectivity", "status": "pending", "order": 9}, + {"name": "finalize", "status": "pending", "order": 10} + ], + "tasks_completed": 6, + "tasks_total": 10, + "started_at": "2026-01-05T15:00:00Z", + "is_ready": false + } +} +``` + +**Response (Completed):** +```json +{ + "success": true, + "data": { + "vps_id": 46, + "deployment_status": "completed", + "vps_status": "running", + "current_task": null, + "progress_percent": 100, + "tasks_completed": 10, + "tasks_total": 10, + "started_at": "2026-01-05T15:00:00Z", + "completed_at": "2026-01-05T15:03:00Z", + "is_ready": true, + "access_info": { + "ip_address": "74.81.40.146", + "ssh_port": 22, + "ssh_user": "root" + } + }, + "message": "VPS deployment completed successfully" +} +``` + +--- + +### VPS Snapshots + +#### List Snapshots + +``` +GET /api/v1/vps/{id}/snapshots +``` + +**Required Scope:** `vps:read` + +**Response:** +```json +{ + "success": true, + "data": { + "vps_id": 45, + "snapshots": [ + { + "name": "pre-upgrade-snapshot", + "description": "Before system upgrade", + "created_at": "2026-01-04T10:00:00Z", + "vmstate": false + } + ] + } +} +``` + +--- + +#### Create Snapshot + +``` +POST /api/v1/vps/{id}/snapshots/create +``` + +**Required Scope:** `vps:write` + +**Request Body:** + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `name` | string | Yes | Snapshot name (alphanumeric, underscores) | +| `description` | string | No | Description of the snapshot | +| `include_ram` | boolean | No | Include RAM state (default: false) | + +**Example Request:** +```json +{ + "name": "pre_upgrade_snapshot", + "description": "Before upgrading to Ubuntu 24.04", + "include_ram": false +} +``` + +**Response:** +```json +{ + "success": true, + "data": { + "vps_id": 45, + "snapshot": { + "name": "pre_upgrade_snapshot", + "description": "Before upgrading to Ubuntu 24.04", + "created_at": "2026-01-05T16:00:00Z" + } + }, + "message": "Snapshot created successfully" +} +``` + +--- + +## Code Examples + +### Python + +```python +import requests + +API_KEY = "cyp_live_your_api_key_here" +BASE_URL = "https://platform.cyberpersons.com/api/v1" + +headers = { + "Authorization": f"Bearer {API_KEY}", + "Content-Type": "application/json" +} + +# List all VPS instances +response = requests.get(f"{BASE_URL}/vps", headers=headers) +instances = response.json()["data"]["instances"] +for vps in instances: + print(f"{vps['name']}: {vps['status']} ({vps['ip_address']})") + +# Create a new VPS +new_vps = requests.post(f"{BASE_URL}/vps/create", headers=headers, json={ + "hostname": "my-server.example.com", + "plan_id": 1, + "location_code": "la", + "template_id": "9000", + "root_password": "SecurePass123" +}) +vps_id = new_vps.json()["data"]["vps_id"] + +# Poll deployment status +import time +while True: + status = requests.get(f"{BASE_URL}/vps/{vps_id}/deployment", headers=headers) + data = status.json()["data"] + print(f"Progress: {data['progress_percent']}% - {data['current_task']}") + if data["is_ready"]: + print(f"VPS ready at {data['access_info']['ip_address']}") + break + time.sleep(10) +``` + +### JavaScript (Node.js) + +```javascript +const API_KEY = "cyp_live_your_api_key_here"; +const BASE_URL = "https://platform.cyberpersons.com/api/v1"; + +const headers = { + "Authorization": `Bearer ${API_KEY}`, + "Content-Type": "application/json" +}; + +// List all VPS instances +const response = await fetch(`${BASE_URL}/vps`, { headers }); +const { data } = await response.json(); +data.instances.forEach(vps => { + console.log(`${vps.name}: ${vps.status} (${vps.ip_address})`); +}); + +// Create a new VPS +const createResponse = await fetch(`${BASE_URL}/vps/create`, { + method: "POST", + headers, + body: JSON.stringify({ + hostname: "my-server.example.com", + plan_id: 1, + location_code: "la", + template_id: "9000", + root_password: "SecurePass123" + }) +}); +const { data: vpsData } = await createResponse.json(); +console.log(`VPS ${vpsData.vps_id} deployment started`); +``` + +### cURL + +```bash +# Test authentication +curl -X GET "https://platform.cyberpersons.com/api/v1/test" \ + -H "Authorization: Bearer cyp_live_your_api_key_here" + +# List VPS instances +curl -X GET "https://platform.cyberpersons.com/api/v1/vps" \ + -H "Authorization: Bearer cyp_live_your_api_key_here" + +# Create VPS +curl -X POST "https://platform.cyberpersons.com/api/v1/vps/create" \ + -H "Authorization: Bearer cyp_live_your_api_key_here" \ + -H "Content-Type: application/json" \ + -d '{ + "hostname": "my-server.example.com", + "plan_id": 1, + "location_code": "la", + "template_id": "9000", + "root_password": "SecurePass123" + }' + +# Stop VPS +curl -X POST "https://platform.cyberpersons.com/api/v1/vps/45/stop" \ + -H "Authorization: Bearer cyp_live_your_api_key_here" + +# Delete VPS (WARNING: Permanent!) +curl -X POST "https://platform.cyberpersons.com/api/v1/vps/45/delete" \ + -H "Authorization: Bearer cyp_live_your_api_key_here" +``` + +### PHP + +```php + "my-server.example.com", + "plan_id" => 1, + "location_code" => "la", + "template_id" => "9000", + "root_password" => "SecurePass123" +]); +echo "Created VPS ID: " . $new_vps["data"]["vps_id"]; +?> +``` + +--- + +## Webhook Notifications + +When creating a VPS, you can specify a `webhook_url` to receive notifications when deployment completes or fails. + +### Webhook Payload + +```json +{ + "event": "vps.deployment.completed", + "timestamp": "2026-01-05T15:03:00Z", + "data": { + "vps_id": 46, + "name": "my-server.example.com", + "status": "running", + "ip_address": "74.81.40.146", + "deployment_time_seconds": 180 + } +} +``` + +### Event Types + +| Event | Description | +|-------|-------------| +| `vps.deployment.completed` | VPS deployment finished successfully | +| `vps.deployment.failed` | VPS deployment failed | + +### Webhook Security + +If you provide a `webhook_secret`, the webhook request will include a signature header: + +``` +X-Webhook-Signature: sha256= +``` + +Verify the signature by computing HMAC-SHA256 of the request body using your secret. + +--- + +## Support + +- **Documentation:** https://platform.cyberpersons.com/api-keys/ +- **Support Tickets:** https://platform.cyberpersons.com/support/ +- **Email:** help@cyberpanel.net + +--- + +## Changelog + +### v1.0.0 (January 2026) +- Initial API release +- VPS management endpoints (list, create, start, stop, restart, delete) +- Account and billing endpoints +- Snapshot management +- Webhook notifications for deployments \ No newline at end of file