توثيقِ شناخت
ایک API کلید بطور بیر ٹوکن (bearer token) ارسال کریں۔ یہ اینڈ پوائنٹ اسپیسیفیکیشن میں کسی مخصوص اجازت کا ذکر نہیں کرتا، اس لیے فرض کرنے کے بجائے اپنی کلید کو کم از کم درکار اجازت دیں اور رسپانس چیک کریں۔
جہاں آپ کی تنظیم کی آئی ڈی آتی ہے
یہ اینڈ پوائنٹ JSON باڈی میں ایک فیلڈ کے طور پر org_id لیتا ہے۔
آپ کی تنظیم کی آئی ڈی آپ کے ڈیش بورڈ پر API کیز کی سکرین پر، خود کلید کے ساتھ موجود ہوتی ہے۔ یہ آپ کی کی جانے والی ہر کال میں ایک ہی آئی ڈی ہوتی ہے۔
آزمائیں
کوئی بھی چیز جو زاویہ دار قوسین میں ہو اسے اپنی اقدار سے بدلیں، اور کلیدی پلیس ہولڈر کو اپنے ڈیش بورڈ کی کسی کلید سے بدلیں۔
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 کنسول آپ کی حقیقی تنظیم کی آئی ڈی اور آپ کی اپنی کلید خود بخود پُر کر دیتا ہے، اور لائیو 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… |
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 onto… |
stack_type | StackType | نہیں | The application stack a site runs (docs/04 §1). nextcloud, owncloud, headless_cms and php_app are own-fleet only (docs/139, docs/564): we install them ourselves from… |
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 submitted… |
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… |
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:… |
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 ids… |
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… |
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… |
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 confused:… |
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 as… |
cdn_account_id | string | نہیں | Which of your own CDN accounts the site is created on — the half cdn_tier cannot express. List them with listCdnTargetsForCreate. ⛔ Only meaningful with cdn_tier: byo,… |
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… |
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… |
panel_connection_id | Uuid | null | نہیں | Which of your connected control panels to build this site on — an id from GET /v1/panels/connections. Applies to a plesk site and to nothing else. ⛔… |
جواب
| نام | قسم | لازمی | یہ کیا ہے |
|---|---|---|---|
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… |
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 order… |
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, computed… |
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, headless_cms and php_app are own-fleet only (docs/139, docs/564): we install them ourselves from… |
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 the… |
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 same… |
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 safe… |
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 placement… |
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, never… |
panel_connection_id | Uuid | null | نہیں | Which control panel this site's subscription lives on — the PanelConnection from GET /v1/panels/connections. Set only when deploy_target is plesk;… |
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. ⛔… |
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 to… |
created_at | string | ہاں | — |
updated_at | string | نہیں | — |
وہ خرابیان جو یہ اینڈ پوائنٹ واپس کر سکتا ہے
400 · 401 · 403 · 404 · 409 · 422 · 429