Баталгаажуулалт
API түлхүүрийг bearer token хэлбэрээр илгөэнэ үү. Энэхүү төгсгөлийн цэг нь тодорхойлолтдоо тодорхой зөвшөөрлийг заагаагүй тул түлхүүрээрээ шаардагдах хамгийн бага эрхийг өгч, таамаглахаас илүүтэйгээр хариуг шалгана уу.
Таны байгууллагын дугаар орох газар
Энэ төгсгөлийн цэг нь JSON бие хэсэгт org_id-ийг талбар болгон авдаг.
Танай байгууллагын ID нь таны хяналтын самбар дээрх API түлхүүрийн дэлгэцэнд, түлхүүр өөрөө хажууд байрладаг. Энэ нь таны хийх дуудлага бүрт ижил ID байна.
Туршиж үзэх
Өнцөг хаалтанд байгаа бүх зүйлийг өөрийн утгаар солиж, түлхүүр санамж байрлуулагчийг хяналтын самбарынхаа түлхүүрээр сольж оруулна уу.
curl -X POST https://api.zinndigital.com/v1/sites \
-H "Authorization: Bearer zdk_live_…" \
-H "Content-Type: application/json" \
-d '{ "product_line": <string>, "primary_domain": <Hostname> }'Та нэвтэрсэн байна уу? Таны хяналтын самбар дахь API консол нь таны бодит байгууллагын ID болон өөрийн түлхүүрийг автоматаар бөглөж, шууд ажиллаж буй API рүү хүсэлт илгээх тул та бодит хариуг харах боломжтой болно. Энэ төгсгөлийн цэгийг API консол дээр нээх
Дэлгэрэнгүй
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).
Параметрүүд
| Нэр | Төрөл | Заавал шаардлагатай | Энэ юу вэ |
|---|---|---|---|
Idempotency-Key (header) | string | Үгүй | Client-generated key that makes an unsafe request replay-safe: the server stores the first response and returns it verbatim for repeats. |
Хүсэлтийн бие
| Нэр | Төрөл | Заавал шаардлагатай | Энэ юу вэ |
|---|---|---|---|
org_id | Uuid | null | Үгүй | The organization to create the site under. Defaults to the caller's org; the caller must hold `sites.create` in the target org. |
product_line | string | Тийм | — |
primary_domain | Hostname | Тийм | A fully-qualified DNS hostname, lowercase, no trailing dot. |
name | string | Үгүй | — |
source | SiteSource | Үгүй | Where a site's initial content came from (docs/04 §2). `blueprint` is a fresh site off one of our published stack recipes. `site_blueprint` is a copy of one of the **customer's… |
blueprint_id | Uuid | null | Үгүй | A published blueprint version to build from. When given, `stack_type` and `runtime` are taken from the blueprint and must not be sent; when omitted, `stack_type` is required. |
site_blueprint_id | Uuid | null | Үгүй | One of **your own** captured sites (`GET /v1/site-blueprints`) to build this one from. The new site is provisioned on that blueprint's stack and its archive is then restored ont… |
stack_type | StackType | Үгүй | The application stack a site runs (docs/04 §1). `nextcloud`, `owncloud` and `headless_cms` are **own-fleet only** (docs/139): we install them ourselves from each project's own d… |
runtime | Runtime | Үгүй | **Derived from `stack_type` — do not send it.** A stack decides its own runtime (WordPress is PHP, Static is static), so asking for both allowed WordPress-on-Node to be submitte… |
php_version | string | Үгүй | The PHP version the site starts on, as a minor-version family. Must be a version offered on this product line (`GET /v1/catalog/php-versions`); anything else is a `422` naming w… |
application | string | Үгүй | The application to build the site with. Accepted on the two stacks that ASK the customer what to install, and validated against a different catalogue for each: * `stack_type: on… |
subscription_id | Uuid | null | Үгүй | The subscription entitling this site. Must belong to the org that will own the site; anything else is a `422` (never a `404`, so it cannot be used to probe which subscription id… |
region | string | Үгүй | Pin placement to a data-residency region; any region when omitted. Validated on write against **one of two vocabularies**, chosen by the site's deploy target: a fleet site is ch… |
cdn_vendor | string | Үгүй | Which CDN vendor this site's edge runs on. Omit (or send `""`) to let the footprint balancer choose, which is the default and the **only** permitted value on a managed line — a… |
dns_vendor | string | Үгүй | Which DNS vendor this site's zone is created on. Omit to let the footprint balancer choose. Only consulted when the zone has no placement yet: a name inside a zone this organiza… |
use_own_dns | boolean | Үгүй | Serve this site's DNS from **your own connected DNS account** rather than Zinn®'s pool (W20-G). ⛔ This is a different question from `dns_vendor`, and the two must not be confuse… |
cdn_tier | string | Үгүй | The CDN tier this site starts on (W20-G — "deploy/select it at deployment time for the applicable lines"). ⭐ Omit for the product line's own default, which is **not** the same a… |
canonical_host | string<apex, www> | Үгүй | Which of the site's two hostnames serves; the other is published and permanently redirects to it, so the site is never reachable at two addresses at once. Chosen **at deploy** r… |
force_https | boolean | Үгүй | Redirect http to https at the edge. **Omitted means `true`** — the insecure choice has to be asked for and is never reached by leaving the field out. |
deploy_target | string | Үгүй | Deploy this site to **your own edge-host account** instead of to the platform your plan places it on. Omitted — the normal case — means the plan decides, and is what every site… |
Хариу үйлдэл
| Нэр | Төрөл | Заавал шаардлагатай | Энэ юу вэ |
|---|---|---|---|
id | Uuid | Тийм | UUIDv7 identifier — sortable by creation time (docs/02 §8). |
org_id | Uuid | Тийм | UUIDv7 identifier — sortable by creation time (docs/02 §8). |
product_line | string | Тийм | Product line code this site belongs to (CLAUDE.md §2.14). |
source | SiteSource | Тийм | Where a site's initial content came from (docs/04 §2). `blueprint` is a fresh site off one of our published stack recipes. `site_blueprint` is a copy of one of the **customer's… |
blueprint_id | Uuid | null | Үгүй | The exact blueprint version the site was built from; null for imports. |
subscription_id | Uuid | null | Үгүй | The subscription entitling this site; null while unassigned. |
plan_code | string | null | Үгүй | Stable code of the plan behind this site's subscription (e.g. `pbn_25`); null when the site has no subscription. Use this, not `plan_name`, for filters, saved views and support… |
plan_name | string | null | Үгүй | Display name of the plan behind this site's subscription; null when the site has no subscription (a real state — a trial, an internal site, or a site provisioned before its orde… |
seo | SiteSeoSummary | null | Үгүй | **This site's search-index status and authority metrics, on the list row.** The same readings `GET /v1/sites/{siteId}/index-check` and `/seo-metrics` return for one site, comput… |
primary_domain | Hostname | Тийм | A fully-qualified DNS hostname, lowercase, no trailing dot. |
name | string | Үгүй | Human label for the site; defaults to the primary domain. |
stack_type | StackType | Тийм | The application stack a site runs (docs/04 §1). `nextcloud`, `owncloud` and `headless_cms` are **own-fleet only** (docs/139): we install them ourselves from each project's own d… |
runtime | Runtime | Тийм | The runtime the web server serves the site with. |
php_version | string | Үгүй | The PHP version this site is pinned to, or `""` when it follows the product line's current default. Echoed so a caller can confirm the choice it just made on create — without it… |
status | SiteStatus | Тийм | A site's lifecycle state (docs/04 §3). A newly created site is `pending` until the provisioning workflow picks it up; `deleted` is terminal. `restricted` and `quarantined` are t… |
status_reason | SiteStatusReason | null | Үгүй | Why the site is in that status. **Null on any healthy site**, and cleared the moment the site leaves `failed` — a reason that outlives its failure reads to the customer as current. |
failed_step | string | Үгүй | WHERE provisioning failed — the saga step that was running when it did, as a `SiteFailedStep` code the client localises, or `""` when the site is not `failed` (cleared in the sa… |
failed_activity | string | Үгүй | The activity that refused, by the name the worker registered it under (`create_dns_zone`, `verify_site_serving`). An identifier of ours, never the vendor's message, so it is saf… |
region | string | Үгүй | Where the site is running. On our own fleet this is the region of the box the site is **placed on**, not the region asked for at create time — the two can disagree when placemen… |
cdn_vendor | string | Үгүй | The CDN vendor this site was pinned to, or `""` when the footprint balancer chooses (the default, and the only value on a managed line). This is the customer's own choice echoed… |
dns_vendor | string | Үгүй | The DNS vendor this site's zone was pinned to, or `""` when the footprint balancer chooses. |
deploy_target | string | Үгүй | Where the site actually runs (docs/62 §1) — `fleet`, `cf_pages`, `twentyi_shared`, and so on. Empty when it has not been decided. A machine identifier the client localises, neve… |
deletion_state | string<none, scheduled, running, stalled, deleted> | Үгүй | Whether this site is on its way out. The same five values as `SiteDeletion.state`, reused verbatim so a list chip and the danger zone cannot disagree inside one screen. ⛔ **An a… |
deletion_scheduled_for | string | Үгүй | When the teardown fires. Null unless a deletion is armed or running. Stored when the request is made rather than recomputed from the grace period, so a countdown already shown t… |
created_at | string | Тийм | — |
updated_at | string | Үгүй | — |
Энэ төгсгөл цэгээс буцааж болох алдаанууд
401 · 403 · 409 · 422 · 429