POST /v1/sites

Authentication

Send an API key as a bearer token. The endpoint checks sites.blueprint.manage, sites.create; a key without it is refused with 403, not 404.

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 \
  -H "Authorization: Bearer zdk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "product_line": <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

Registers a new site and returns it immediately with status pending. Provisioning (placement, account, blueprint deploy, DNS, verification) runs asynchronously as a Temporal workflow — this call never blocks on it (CLAUDE.md §2.9). Send an Idempotency-Key so retries never create duplicates (docs/09 §2). Entitlement-gated (docs/05 §1). The site must be covered by a plan's max_sites allowance. The governing plan is resolved from the owning org and, failing that, from its parent_org chain — so a reseller's client orgs draw on the reseller's own allowance (docs/18 §3). Sites in every state except deleted consume a slot, including suspended and failed. A max_sites of -1 means unlimited, and a staff org is unlimited by type. Refusals are 422 with a specific error.code: PLAN_REQUIRED when nothing grants hosting, SITE_QUOTA_EXCEEDED when the plan is full. Both carry the plan's own max_sites, sites_in_use and entitling_org_id in error.details so a client can render an upsell without re-deriving a resolution only the server can perform — but ONLY when the entitling org is within the caller's own scope. Where an ancestor's plan governs and the caller has no authority over it, the figures are omitted entirely and the message says the plan is managed by the parent organisation: sites_in_use is counted across the entitling org's whole subtree, so disclosing it to a client-org member would be a cross-tenant aggregate over sibling tenants (#566). A trial's site waits for a verified email address (D41995): a person whose address is not yet confirmed, in an organization on a free trial, is refused with 403 and error.refusal.key = refusal.trial.confirmEmailFirst. Staff acting as the customer and API keys are not asked. Every site is created purpose: customer, and that decides how it is deleted (R48c). purpose is not a request field. A customer site's delete is scheduled with the seven-day grace period (the customer's undo) and holds its fleet slot until then. The only automatic exception is a hostname whose first label carries a lane prefix (w<digits><letters>-…, or w<NN>-<n>-… under a platform-owned domain), which is created internal. A test or proof site created under any other name stays customer: staff reclassify it with manage.py set_site_purpose, and an internal site is torn down at once, with no grace, by manage.py teardown_internal_sites (docs/740).

Parameters

Request body

Response

Errors this endpoint can return

400 · 401 · 403 · 404 · 409 · 422 · 429