Authentication
Send an API key as a bearer token. The key must carry the sites.view permission; a key without it is refused with 403, not 404.
This endpoint takes no organisation id. Your key already identifies the organisation it belongs to, and the response is scoped to it.
Try it
Replace anything in angle brackets with your own values, and the key placeholder with a key from your dashboard.
curl -X POST https://api.zinndigital.com/v1/sites/{siteId}/subdomains \
-H "Authorization: Bearer zdk_live_…" \
-H "Content-Type: application/json" \
-d '{ "name": <string> }'Signed in? The API console in your dashboard fills in your real organisation id and your own key, and runs the request against the live API so you can see the actual response. Open this endpoint in the API console
Details
Adds one subdomain to the package. The effective ceiling is applied **before** the vendor is called: a package type that does not permit subdomains, and a customer who has used the last of their allowance, are both `422` with a sentence they can act on. ⛔ The response is the row **the platform stored**, not the name that was requested — the vendor normalises and namespaces it, so the client shows what came back. ⚖️ **On our own fleet this spends one of the plan's site slots** (owner ruling 2026-09-01), so the refusal at the cap is the same event as it is on site create and carries the same `SITE_QUOTA_EXCEEDED` code and figures. The row comes back `pending`: the DNS record, the virtual host and the chosen stack are built by a durable workflow, and the row reaches `active` when the name is serving. A build that cannot be done — a hostname whose DNS we do not control, or one this server's certificate cannot cover — lands in `failed` with the reason in `status_detail`. `404` for a site with no managed hosting package and no own-fleet placement. Requires `sites.view` and `sites.panel_access`.
Parameters
| Name | Type | Required | What it is |
|---|---|---|---|
siteId (path) | Uuid | Yes | Site ID (UUIDv7). |
Request body
| Name | Type | Required | What it is |
|---|---|---|---|
name | string | Yes | The subdomain to add. What the vendor actually created comes back in `SiteSubdomain.name`, and that — never this — is what the client shows. |
stack_type | string<static, php, wordpress, woocommerce> | No | What the subdomain should run. ⚖️ Owner ruling 2026-09-01 — a new subdomain *"will start as whatever they select"*. `static` and `php` give an empty document root to upload or d… |
Response
| Name | Type | Required | What it is |
|---|---|---|---|
name | string | Yes | The subdomain as the platform stored it. ⛔ Not necessarily what was requested — a vendor normalises it, and the client shows this value. |
document_root | string | Yes | The folder it serves. Relative to the package root on a resold package; an absolute path on our own fleet, where it is read back from the server's own configuration rather than… |
stack_type | string | No | What this subdomain runs, as the customer chose at creation. ⛔ **Empty on a resold package**, where the folder is the vendor's and there is no stack we chose — deliberately blan… |
status | string<pending, active, failed, deleting, > | No | Where the build has got to. `pending` while the record, the virtual host and the stack are being put in place; `active` once the name serves; `deleting` after a delete, when the… |
status_detail | string | No | Why it failed, or a note about a build that partly succeeded — a sentence written for the customer. Empty on a healthy row. |
Errors this endpoint can return
401 · 403 · 404 · 409 · 422 · 429 · 503