Adds a subdomain to an existing hosting account. The Panel creates the Nginx server block, a PHP-FPM pool entry (if PHP version is specified), a DNS A record in PowerDNS, and the document root directory.
[!NOTE] Opterius uses a single-domain-per-account architecture. Each account has one primary domain. Subdomains extend that account. Addon domains (separate apex domains on the same account) are not supported. See Domain Architecture for background.
Endpoint:
POST /api/v1/accounts/{account_id}/domains
Authentication: Bearer token — see API Authentication Overview.
Request Body
{
"subdomain": "blog",
"document_root": "public_html/blog",
"php_version": "8.3"
}
| Field | Type | Required | Notes |
|---|---|---|---|
subdomain |
string | Yes | The subdomain prefix only — e.g. blog, not blog.example.com. Alphanumeric and hyphens, max 63 characters. |
document_root |
string | No | Path relative to the account's home directory. Defaults to public_html/{subdomain}. |
php_version |
string | No | PHP version to use: 8.1, 8.2, 8.3, or 8.4. Defaults to the account's current PHP version. |
The resulting subdomain FQDN will be {subdomain}.{account_primary_domain}.
Response
201 Created:
{
"data": {
"id": 7,
"account_id": 42,
"subdomain": "blog",
"fqdn": "blog.alice.example.com",
"document_root": "/home/alice/public_html/blog",
"php_version": "8.3",
"status": "active",
"created_at": "2026-04-08T15:00:00Z"
}
}
Error Codes
| Status | Error | Cause |
|---|---|---|
| 404 | not_found |
No account with account_id exists |
| 409 | conflict |
That subdomain already exists on this account |
| 422 | validation_failed |
Invalid subdomain format or unsupported PHP version |
| 403 | license_required |
License invalid — writes are blocked |
curl Example
curl -sk -X POST \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
"subdomain": "blog",
"document_root": "public_html/blog",
"php_version": "8.3"
}' \
https://SERVER_IP:8443/api/v1/accounts/42/domains
SSL for the New Subdomain
Creating a subdomain does not automatically issue a TLS certificate. After creating the subdomain, issue a certificate via the Panel UI or via the SSL API endpoint. DNS must be pointing to the server before certificate issuance. See Issuing Certificates.