API Reference --- All Endpoints with Examples

admin · Mar 7, 2026

This is the complete API reference for Panelica's External API. Every endpoint is documented with method, path, required scopes, parameters, and request/response examples.

Base URL & Authentication

Base URL:

Code:

https://your-server.com:3002/api/external/v1/

Authentication: All requests require HMAC-SHA256 headers:

Code:

X-API-Key: pk_live_your_key
X-Timestamp: 1709827200
X-Signature: hmac_sha256_hex

See API Keys & HMAC Authentication Guide for full authentication details.

Response Format: All responses are JSON. Successful responses return the data directly. Error responses include:

Code:

{
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": "Additional context"
}

---

Domains

List Domains

Code:

GET /v1/domains
Scope: domains:read

Response:

Code:

[
  {
    "id": "uuid",
    "domain": "example.com",
    "user_id": "uuid",
    "status": "active",
    "php_version": "8.4",
    "web_server": "nginx",
    "document_root": "/home/user1/example.com/public_html",
    "ssl_enabled": true,
    "disk_usage_mb": 245,
    "bandwidth_mb": 1024,
    "created_at": "2026-01-15T10:30:00Z"
  }
]

---

Get Domain

Code:

GET /v1/domains/{id}
Scope: domains:read

---

Create Domain

Code:

POST /v1/domains
Scope: domains:write

Request:

Code:

{
  "domain": "example.com",
  "user_id": "uuid",
  "php_version": "8.4",
  "web_server": "nginx",
  "ssl_type": "lets_encrypt"
}

Response:

Code:

{
  "id": "uuid",
  "domain": "example.com",
  "status": "active",
  "php_version": "8.4",
  "document_root": "/home/user1/example.com/public_html",
  "created_at": "2026-03-07T12:00:00Z"
}

---

Update Domain

Code:

PATCH /v1/domains/{id}
Scope: domains:write

Request:

Code:

{
  "php_version": "8.3",
  "web_server": "apache"
}

---

Delete Domain

Code:

DELETE /v1/domains/{id}
Scope: domains:delete

---

Suspend Domain

Code:

POST /v1/domains/{id}/suspend
Scope: domains:write

---

Unsuspend Domain

Code:

POST /v1/domains/{id}/unsuspend
Scope: domains:write

---

User Accounts

List Users

Code:

GET /v1/accounts
Scope: accounts:read

Response:

Code:

[
  {
    "id": "uuid",
    "username": "john",
    "email": "[email protected]",
    "role": "USER",
    "status": "active",
    "plan_id": "uuid",
    "plan_name": "Standard",
    "domain_count": 3,
    "disk_usage_mb": 512,
    "bandwidth_mb": 2048,
    "created_at": "2026-01-10T08:00:00Z"
  }
]

---

Get User

Code:

GET /v1/accounts/{id}
Scope: accounts:read

---

Create User

Code:

POST /v1/accounts
Scope: accounts:write

Request:

Code:

{
  "username": "john",
  "email": "[email protected]",
  "password": "SecurePassword123!",
  "role": "USER",
  "plan_id": "uuid"
}

---

Update User

Code:

PATCH /v1/accounts/{id}
Scope: accounts:write

---

Delete User

Code:

DELETE /v1/accounts/{id}
Scope: accounts:delete

---

Suspend User

Code:

POST /v1/accounts/{id}/suspend
Scope: accounts:write

---

Unsuspend User

Code:

POST /v1/accounts/{id}/unsuspend
Scope: accounts:write

---

DNS Records

List DNS Records

Code:

GET /v1/dns/zones/{zone_id}/records
Scope: dns:read

Response:

Code:

[
  {
    "id": "uuid",
    "zone_id": "uuid",
    "name": "www",
    "type": "A",
    "content": "192.168.1.100",
    "ttl": 3600,
    "priority": null
  },
  {
    "id": "uuid",
    "zone_id": "uuid",
    "name": "@",
    "type": "MX",
    "content": "mail.example.com",
    "ttl": 3600,
    "priority": 10
  }
]

---

Create DNS Record

Code:

POST /v1/dns/zones/{zone_id}/records
Scope: dns:write

Request:

Code:

{
  "name": "www",
  "type": "A",
  "content": "192.168.1.100",
  "ttl": 3600
}

Supported record types: A, AAAA, CNAME, MX, TXT, NS, SRV, CAA, PTR

---

Update DNS Record

Code:

PATCH /v1/dns/zones/{zone_id}/records/{record_id}
Scope: dns:write

---

Delete DNS Record

Code:

DELETE /v1/dns/zones/{zone_id}/records/{record_id}
Scope: dns:delete

---

SSL Certificates

List SSL Certificates

Code:

GET /v1/ssl/certificates
Scope: ssl:read

Response:

Code:

[
  {
    "id": "uuid",
    "domain_id": "uuid",
    "domain": "example.com",
    "type": "lets_encrypt",
    "status": "active",
    "issuer": "Let's Encrypt",
    "expires_at": "2026-06-07T00:00:00Z",
    "auto_renew": true,
    "created_at": "2026-03-07T12:00:00Z"
  }
]

---

Issue SSL Certificate

Code:

POST /v1/ssl/certificates
Scope: ssl:write

Request:

Code:

{
  "domain_id": "uuid",
  "type": "lets_encrypt",
  "auto_renew": true
}

Types: lets_encrypt, self_signed, custom

---

Renew SSL Certificate

Code:

POST /v1/ssl/certificates/{id}/renew
Scope: ssl:write

---

Databases

List Databases

Code:

GET /v1/databases
Scope: databases:read

Response:

Code:

[
  {
    "id": "uuid",
    "name": "wordpress_db",
    "type": "mysql",
    "size_mb": 45.2,
    "user_count": 1,
    "domain_id": "uuid",
    "created_at": "2026-02-15T14:00:00Z"
  }
]

---

Create Database

Code:

POST /v1/databases
Scope: databases:write

Request:

Code:

{
  "name": "myapp_db",
  "type": "mysql",
  "domain_id": "uuid"
}

Types: mysql, postgresql

---

Create Database User

Code:

POST /v1/databases/{db_id}/users
Scope: databases:write

Request:

Code:

{
  "username": "myapp_user",
  "password": "SecurePassword123!",
  "privileges": "ALL"
}

---

Delete Database

Code:

DELETE /v1/databases/{id}
Scope: databases:delete

---

Email Accounts

List Email Accounts

Code:

GET /v1/email/accounts
Scope: email:read

Response:

Code:

[
  {
    "id": "uuid",
    "email": "[email protected]",
    "domain_id": "uuid",
    "quota_mb": 1024,
    "used_mb": 128.5,
    "status": "active",
    "created_at": "2026-01-20T09:00:00Z"
  }
]

---

Create Email Account

Code:

POST /v1/email/accounts
Scope: email:write

Request:

Code:

{
  "local_part": "info",
  "domain_id": "uuid",
  "password": "SecurePassword123!",
  "quota_mb": 1024
}

---

Delete Email Account

Code:

DELETE /v1/email/accounts/{id}
Scope: email:delete

---

FTP Accounts

List FTP Accounts

Code:

GET /v1/ftp/accounts
Scope: ftp:read

---

Create FTP Account

Code:

POST /v1/ftp/accounts
Scope: ftp:write

Request:

Code:

{
  "username": "ftp_user",
  "password": "SecurePassword123!",
  "domain_id": "uuid",
  "home_directory": "/home/user1/example.com/public_html",
  "quota_mb": 500
}

---

Delete FTP Account

Code:

DELETE /v1/ftp/accounts/{id}
Scope: ftp:delete

---

Backups

List Backups

Code:

GET /v1/backups
Scope: backups:read

Response:

Code:

[
  {
    "id": "uuid",
    "name": "daily-backup-20260307",
    "type": "full",
    "status": "completed",
    "size_bytes": 1073741824,
    "domains_count": 5,
    "encrypted": true,
    "compression_level": 6,
    "created_at": "2026-03-07T02:00:00Z"
  }
]

---

Create Backup

Code:

POST /v1/backups
Scope: backups:write

Request:

Code:

{
  "name": "manual-backup",
  "type": "full",
  "encryption": "panel_key",
  "compression_level": 6,
  "include_web": true,
  "include_databases": true,
  "include_email": true,
  "include_dns": true,
  "include_ssl": true,
  "domain_ids": ["uuid1", "uuid2"]
}

---

Restore Backup

Code:

POST /v1/backups/{id}/restore
Scope: backups:restore

Request:

Code:

{
  "domain_ids": ["uuid1"],
  "include_web": true,
  "include_databases": true,
  "conflict_action": "overwrite",
  "create_pre_restore_backup": true
}

---

Delete Backup

Code:

DELETE /v1/backups/{id}
Scope: backups:write

---

Services

List Services

Code:

GET /v1/server/services
Scope: services:read

Response:

Code:

[
  {
    "name": "nginx",
    "display_name": "Nginx",
    "status": "running",
    "pid": 1234,
    "uptime_seconds": 864000,
    "cpu_percent": 0.5,
    "memory_mb": 128
  },
  {
    "name": "mysql",
    "display_name": "MySQL 8.0",
    "status": "running",
    "pid": 5678,
    "uptime_seconds": 864000,
    "cpu_percent": 2.1,
    "memory_mb": 512
  }
]

---

Start Service

Code:

POST /v1/server/services/{name}/start
Scope: services:start

---

Stop Service

Code:

POST /v1/server/services/{name}/stop
Scope: services:stop

---

Restart Service

Code:

POST /v1/server/services/{name}/restart
Scope: services:restart

Available services: nginx, apache, mysql, postgresql, redis, php-fpm, postfix, dovecot, bind, proftpd, fail2ban, clamav, and more.

---

Server Information

Get Server Status

Code:

GET /v1/server/status
Scope: server:read

Response:

Code:

{
  "hostname": "server1.example.com",
  "os": "Ubuntu 24.04.3 LTS",
  "kernel": "6.8.0-101-generic",
  "uptime_seconds": 8640000,
  "cpu": {
    "model": "Intel Xeon E-2288G",
    "cores": 8,
    "usage_percent": 12.5
  },
  "memory": {
    "total_mb": 32768,
    "used_mb": 8192,
    "usage_percent": 25.0
  },
  "disk": {
    "total_gb": 500,
    "used_gb": 125,
    "usage_percent": 25.0
  },
  "load_average": [0.45, 0.52, 0.48]
}

---

Bandwidth

Get Bandwidth Usage

Code:

GET /v1/bandwidth
Scope: bandwidth:read

Query parameters: ?period=monthly&month=2026-03

Response:

Code:

{
  "total_bytes_in": 10737418240,
  "total_bytes_out": 53687091200,
  "period": "2026-03",
  "domains": [
    {
      "domain": "example.com",
      "bytes_in": 5368709120,
      "bytes_out": 26843545600
    }
  ]
}

---

Plans

List Plans

Code:

GET /v1/plans
Scope: plans:read

Response:

Code:

[
  {
    "id": "uuid",
    "name": "Starter",
    "max_domains": 5,
    "max_databases": 10,
    "max_email_accounts": 25,
    "max_ftp_accounts": 10,
    "disk_space_mb": 10240,
    "bandwidth_mb": 102400,
    "php_versions": ["8.1", "8.2", "8.3", "8.4"],
    "user_count": 15
  }
]

---

Create Plan

Code:

POST /v1/plans
Scope: plans:write

---

Update Plan

Code:

PATCH /v1/plans/{id}
Scope: plans:write

---

Files

List Directory

Code:

GET /v1/files?path=/home/user1/example.com/public_html
Scope: files:read

Response:

Code:

[
  {
    "name": "index.php",
    "type": "file",
    "size": 4096,
    "permissions": "0644",
    "owner": "user1",
    "group": "user1",
    "modified_at": "2026-03-07T12:00:00Z"
  },
  {
    "name": "wp-content",
    "type": "directory",
    "size": 0,
    "permissions": "0755",
    "owner": "user1",
    "group": "user1",
    "modified_at": "2026-03-07T12:00:00Z"
  }
]

---

Read File

Code:

GET /v1/files/content?path=/home/user1/example.com/public_html/index.php
Scope: files:read

---

Write File

Code:

PUT /v1/files/content
Scope: files:write

Request:

Code:

{
  "path": "/home/user1/example.com/public_html/test.txt",
  "content": "Hello, World!"
}

---

Delete File

Code:

DELETE /v1/files?path=/home/user1/example.com/public_html/test.txt
Scope: files:delete

---

CloudFlare Integration

List CloudFlare Zones

Code:

GET /v1/cloudflare/zones
Scope: cloudflare:read

---

Sync DNS Records

Code:

POST /v1/cloudflare/zones/{zone_id}/sync
Scope: cloudflare:write

---

API Keys (Self-Management)

List API Keys

Code:

GET /v1/api-keys
Scope: *:*

---

Create API Key

Code:

POST /v1/api-keys
Scope: *:*

Request:

Code:

{
  "name": "New Key",
  "scopes": ["domains:read", "domains:write"],
  "rate_limit_tier": "professional",
  "ip_whitelist": ["203.0.113.50"],
  "expires_in": 90,
  "environment": "live"
}

Response (credentials shown once):

Code:

{
  "id": "uuid",
  "name": "New Key",
  "api_key": "pk_live_a1b2c3d4...",
  "api_secret": "sk_live_x9y8z7w6...",
  "key_prefix": "pk_live_a1b2c3d4",
  "scopes": ["domains:read", "domains:write"],
  "rate_limit_tier": "professional",
  "expires_at": "2026-06-05T12:00:00Z",
  "created_at": "2026-03-07T12:00:00Z"
}

---

Regenerate Secret

Code:

POST /v1/api-keys/{id}/regenerate
Scope: *:*

Response (new secret shown once):

Code:

{
  "api_secret": "sk_live_new_secret_here..."
}

---

Webhooks (Self-Management)

List Webhooks

Code:

GET /v1/webhooks
Scope: webhooks:read

---

Create Webhook

Code:

POST /v1/webhooks
Scope: webhooks:write

Request:

Code:

{
  "name": "Domain Alerts",
  "destination_type": "http",
  "destination_config": {
    "url": "https://example.com/webhook",
    "method": "POST"
  },
  "events": ["domain.created", "domain.deleted"],
  "retry_count": 3,
  "retry_delay_seconds": 60,
  "timeout_seconds": 30
}

Telegram destination example:

Code:

{
  "name": "Telegram Alerts",
  "destination_type": "telegram",
  "destination_config": {
    "bot_token": "123456:ABC-DEF...",
    "chat_id": "-1001234567890",
    "parse_mode": "HTML"
  },
  "events": ["security.ip_blocked", "backup.failed"]
}

Slack destination example:

Code:

{
  "name": "Slack Notifications",
  "destination_type": "slack",
  "destination_config": {
    "webhook_url": "https://hooks.slack.com/services/T.../B.../xxx",
    "channel": "#server-alerts"
  },
  "events": ["system.service_failed", "system.disk_warning"]
}

Discord destination example:

Code:

{
  "name": "Discord Alerts",
  "destination_type": "discord",
  "destination_config": {
    "webhook_url": "https://discord.com/api/webhooks/123/abc...",
    "username": "Panelica Bot"
  },
  "events": ["domain.created", "ssl.expiring_soon"]
}

---

Get Available Events

Code:

GET /v1/webhooks/events
Scope: webhooks:read

Response:

Code:

{
  "categories": [
    {
      "name": "User Events",
      "events": [
        {"type": "user.created", "description": "Triggered when a new user is created"},
        {"type": "user.deleted", "description": "Triggered when a user is deleted"}
      ]
    },
    {
      "name": "Domain Events",
      "events": [
        {"type": "domain.created", "description": "Triggered when a domain is added"},
        {"type": "domain.deleted", "description": "Triggered when a domain is removed"}
      ]
    }
  ]
}

---

Get Webhook Statistics

Code:

GET /v1/webhooks/stats
Scope: webhooks:read

Response:

Code:

{
  "total_webhooks": 5,
  "active_webhooks": 4,
  "total_deliveries_24h": 127,
  "successful_deliveries_24h": 120,
  "failed_deliveries_24h": 7,
  "avg_response_time_ms": 245,
  "success_rate_24h": 94.5
}

---

Get Delivery Logs

Code:

GET /v1/webhooks/{id}/logs?page=1&limit=20
Scope: webhooks:read

Response:

Code:

{
  "data": [
    {
      "id": "uuid",
      "event_type": "domain.created",
      "event_id": "evt_uuid",
      "status": "success",
      "status_code": 200,
      "response_time_ms": 156,
      "retry_count": 0,
      "created_at": "2026-03-07T12:00:00Z"
    }
  ],
  "total": 127,
  "page": 1,
  "limit": 20
}

---

Test Webhook

Code:

POST /v1/webhooks/{id}/test
Scope: webhooks:write

Sends a test event with sample data to verify the webhook endpoint is working.

---

Rate Limiting

Get Rate Limit Status

Code:

GET /v1/rate-limit

Response:

Code:

{
  "tier": "professional",
  "requests_per_minute": 300,
  "requests_per_hour": 10000,
  "burst_size": 50,
  "current_minute_usage": 12,
  "current_hour_usage": 456,
  "reset_at": "2026-03-07T12:01:00Z"
}

---

Utility Endpoints

Health Check

Code:

GET /v1/health
(No authentication required)

Response:

Code:

{
  "status": "healthy",
  "version": "1.0.27",
  "uptime": "10d 5h 30m"
}

---

Get Current Key Info

Code:

GET /v1/me

Response:

Code:

{
  "key_id": "uuid",
  "key_prefix": "pk_live_a1b2c3d4",
  "name": "My API Key",
  "scopes": ["domains:read", "domains:write"],
  "rate_limit_tier": "professional",
  "user": {
    "id": "uuid",
    "username": "admin",
    "role": "ROOT"
  }
}

---

Download Postman Collection

Code:

GET /v1/postman-collection

Returns a Postman v2.1 collection JSON with all endpoints and a pre-request script for HMAC signing.

---

Common Patterns

Pagination:
Most list endpoints support pagination:

Code:

GET /v1/domains?page=1&limit=25&sort=created_at&order=desc

Filtering:
Some endpoints support query filters:

Code:

GET /v1/domains?status=active&user_id=uuid
GET /v1/email/accounts?domain_id=uuid
GET /v1/backups?type=full&status=completed

Error Handling:
Always check the HTTP status code and parse the error response:

Code:

# Success: 200, 201, 204
# Client Error: 400, 401, 403, 404, 409, 429
# Server Error: 500

---

Search

Search

API Reference --- All Endpoints with Examples

admin

Administrator

admin

Administrator

admin

Administrator