{"openapi":"3.1.0","info":{"title":"Zinn Digital® Platform API","version":"0.1.0","summary":"API-first control plane for the Zinn Digital® hosting & SEO platform.","description":"The public API is a product, and it is the **same engine API** the dashboard, AI assistant, CLI, Terraform provider and MCP server all use — published and hardened (docs/09). It is spec-first, so it is 100% documented at build time. All resources are tenant-scoped and enforced by Postgres Row-Level Security (CLAUDE.md §2.3); money is always integer minor units + ISO currency code (CLAUDE.md §2.8).","termsOfService":"https://zinndigital.com/legal/api-terms","contact":{"name":"Zinn Digital® Ltd","url":"https://zinndigital.com","email":"office@zinndigital.com"},"license":{"name":"Proprietary","url":"https://zinndigital.com/legal/license"}},"servers":[{"url":"https://api.zinndigital.com","description":"Production"}],"tags":[{"name":"surveys","description":"In-app surveys, rendered by US and stored by the behavioural backend (owner ruling 2026-08-26 — removing the vendor's branding costs $250/month, so we draw the card). Every decision ABOUT the customer is applied server-side before a survey crosses the wire; the client is left with the route, the quiet period and the sampling die. Feature flags live here too, because the survey kill switch is one."},{"name":"system","description":"Health and service metadata. Unauthenticated."},{"name":"identity","description":"The authenticated principal (user, memberships, active org)."},{"name":"tenancy","description":"Organizations — the tenant. Tenancy is hierarchical (reseller → client → sites) and every access is scoped to the tree (CLAUDE.md §2.3, docs/02 §1)."},{"name":"partner","description":"Partner connections (docs/808). Another product of OURS — the first is V1, `app.pbn.ltd` — selling our domains to ITS OWN customers, who have no Zinn Digital® account. ⛔ Not reselling: a partner sets no prices, is not invoiced wholesale, and Zinn Digital® LTD invoices the end customer directly. A partner places orders UNPAID and the customer pays on a hosted page, so a partner key never holds `billing.payment.manage` and never touches a payment method."},{"name":"reseller","description":"Wholesale reselling (docs/99). The client pays the RESELLER and Zinn® bills the reseller monthly at wholesale rates; the reseller charges their clients through their OWN payment gateway. ⛔ Not the marketplace's commission model — different direction, different counterparty, opposite VAT answer."},{"name":"footprint","description":"The PBN footprint checker — what publicly ties an organisation's sites to each other, and a fix for each finding. Every site hosted with us is included; sites hosted elsewhere are added within the plan's allowance."},{"name":"visibility","description":"The visibility add-ons (docs/11 §4) — whether the answer engines cite a site and whether it is fit to be cited, what the review platforms say about a business, and what a whole-site technical crawl finds. A watched domain need not be hosted with us: auditing a competitor or a prospect is a deliberate feature, metered against a per-plan allowance. ⛔ A `null` score means \"we could not measure\", never \"zero\"."},{"name":"ads","description":"Zinn® Ads (docs/1006) — a customer connects their OWN Google Ads accounts (many per organisation, each separate) and every change to them is approve-first: it waits in a queue for a person unless that action class is switched to automatic. Applied changes can be undone for 30 days; a kill switch per account, per organisation and globally stops every write. ⛔ No token is ever returned; it lives in Vault."},{"name":"syndication","description":"Social syndication (docs/201) — once an article is live at a real URL, a short post goes out to the channels a plan names, carrying that URL and the image. A connection is scoped to the ORGANISATION, not to a site: a LinkedIn company page belongs to the business. ⛔ A lapsed credential reads `needs_reconnect`, never \"posting failed\" — they are different facts and only one is the customer's to fix."},{"name":"connections","description":"Connected third-party accounts (Cloudflare, GitHub, GitLab) the customer brings so we can deploy, manage a BYO CDN, and drive their edge on their behalf. Tokens are validated before they are stored and live only in Vault — a connection row holds a pointer, never the credential (CLAUDE.md §2.4)."},{"name":"security","description":"Controls over who may reach a shell, and from where. Today that is the IP allow-lists (#1493): a customer's own list for their sites, and — on the admin surface — the two staff lists covering platform infrastructure and customer site access. An empty list means UNRESTRICTED, never deny-all."},{"name":"hosting","description":"Sites — the hosted workloads. A site is created `pending` and provisioned asynchronously by a durable Temporal workflow (CLAUDE.md §2.9, docs/04 §3); poll `status` or subscribe to the `site.*` events for completion."},{"name":"zinn-agents","description":"**Zinn® Agents** — one-click AI agent apps (OpenClaw, Hermes Agent, Paperclip, the Activepieces automation builder) running for the customer on our sandboxed agent pool (`docs/1047`). Each agent is bound to one paid Zinn® Agents plan or the 7-day trial, and every model call it makes goes through the metered agent gateway on the customer's one Zinn® AI credit balance (or their own provider key)."},{"name":"zinn-campaigns","description":"**Zinn® Campaigns** — a customer's own email marketing (`docs/1052`). Contacts are imported with a consent record for every person, and campaigns leave through Zinn®'s marketing pool or the customer's own SMTP server, behind the same abuse gate. The product ships switched off; `open` on the overview says whether it is available to the organisation."},{"name":"databases","description":"**Standalone managed databases** — a database with no website attached (`docs/258`). Distinct from `/v1/sites/{siteId}/databases`, which manages the MySQL database that belongs to a hosting account: these are their own product, bought by size, with their own endpoint, their own backup chain and their own engine version. Provisioning is asynchronous — the row is written, a durable Temporal workflow builds the cluster, and the instance reports `provisioning` until it has a primary. ⛔ The credential is **never** a field on any response here. `POST /v1/databases/{databaseId}/credentials` is the only way to obtain it, it demands its own permission, and every call is audit-logged."},{"name":"compute","description":"Whole machines — Zinn® Cloud and the VPS range (docs/62 §3.2/§3.3). A **server**, not a site: it has a power state and a term, and it is configured *before it exists*. Ordering is asynchronous — the row is written, a durable Temporal workflow buys the machine, and the client polls until `status` leaves `provisioning` (CLAUDE.md §2.9). Every read resolves from **our** rows and never from the provider's own listing, which is the whole reseller account; a machine that is not the caller's and a machine that does not exist give the same `404` on purpose. ⛔ The provider's control panel is deliberately not brokered here — no customer ever reaches it (docs/62 §3.7)."},{"name":"fleet","description":"**Machine-to-machine.** How a worker box joins the fleet and stays in it (docs/60). The caller is an agent on a hosting box holding one `zwrk_` enrolment credential — no user, no org, no RBAC scopes — and these are the only paths that credential opens. A box reports what it can honestly observe about itself; everything that affects placement (region, pool, driver, capacity, drain) is the operator's and is set through `manage.py register_worker_host`. Not a customer surface and not a staff one: the staff view of the same fleet lives under `/v1/admin/fleet/*`."},{"name":"live-chat","description":"**Zinn® Chat.** The live-chat product a customer switches on for their OWN visitors — the widget script, its session and message paths, and the staff side that answers them. ⛔ Not the platform's own support inbox (`support`) and not the AI assistant (`ai`): those answer for Zinn®, this answers for the customer's business, so every path here is scoped to the customer's org and a transcript never leaves it."},{"name":"localization","description":"Translatable content — the engine-side surface of the auto-translation pipeline (CLAUDE.md §2.19, docs/28). External content systems (Payload CMS, the KB, the public site build) **register** source fields here; translation itself runs asynchronously in the background, never in the request path (§2.16). The read side serves whichever locale a build or a page render needs, together with the per-locale `status` so the caller can decide how much staleness it tolerates."},{"name":"billing","description":"Stored payment mandates and gateway webhooks. Zinn® stores a **mandate** and the engine drives every recurring charge — there is never a gateway subscription object as the source of truth (ADR 0011, docs/05 §3a). Adding a method is an on-session flow: the browser confirms a SetupIntent with the gateway directly and the mandate is persisted **on the confirming webhook**, never from a client-side claim. Card data never reaches Zinn®."},{"name":"catalog","description":"The sellable plan + pricing catalogue, rendered straight from the billing engine (docs/05, docs/34 §4). Deliberately **public** (unauthenticated): prices are public marketing data, and serving them from the same source the engine charges from is what makes \"what you see is what you are billed\" true rather than a copy that can drift (docs/35 #19). Non-tenant, so no RLS and no org scope. Read-only, cacheable, and — like the localization bundle — returned whole rather than cursor-paginated: the catalogue is our own bounded content, read as a unit by a pricing page or a checkout flow."},{"name":"commerce","description":"Carts, checkout and orders (docs/31 §4, ADR 0011). A cart accrues priced lines; checkout converts it to an immutable `Order`, charges wallet-first, and starts asynchronous fulfilment (a Temporal workflow — this call never blocks on provisioning, §2.9). Every resource is tenant-scoped and enforced by RLS."},{"name":"mail","description":"Email hosting — mailboxes on a customer's own domain (#573, docs/48 §4). Setting up email **rewrites the domain's MX**, so provisioning runs as a durable Temporal workflow that refuses to overwrite mail already delivering elsewhere, and a zone it cannot read counts as \"already delivering\" rather than as safe. Mailbox passwords are returned once, at creation or reset, and are never stored or readable afterwards. The mail backend is swappable and its name never appears in a response (CLAUDE.md §2.6)."},{"name":"notifications","description":"What we tell a customer, and what they have asked us not to (#627, docs/15 §2). Preferences are per topic, and set per organisation **and** per user — a person's own answer outranks their organisation's, in both directions, so an org-wide switch is a default rather than a lock. A topic whose every message is one we are obliged to send (a failed payment, an expiring domain, an invoice, a security notice) is shown and explained rather than hidden: a settings screen that omits what you cannot change is one that lies by omission."},{"name":"offers","description":"The contextual upsells on the customer dashboard Overview (owner 2026-08-28) — what this customer is **missing that we sell**, chosen from a catalogue staff switch on and off in admin. Distinct from `notices`, which is what we are *telling* a customer: a notice is authored, scheduled and withdrawn and is true whether or not they act on it, while an offer is evergreen, gated on a computed signal, and removes itself the moment they buy the thing."},{"name":"notices","description":"The block at the top of the customer's dashboard (docs/87, owner 2026-08-05) — operator-authored announcements and promotions, and warnings the platform raises about this customer specifically. Distinct from `notifications`, which is about **delivering** a message to a person over a channel: this is about what a signed-in customer's own screen says while they are looking at it.\n\n⛔ The audience is always explicit. A notice reaches an organization only if it is deliberately marked `everyone` or that org is named in its audience — an untargeted notice reaches nobody, never everybody. The owner's requirement was that a notice is *\"only shown to the users it actually affects\"*, and a default that broadcasts is how that gets violated by accident rather than by decision."},{"name":"code-care","description":"Code Care (monthly included developer time) and pay-as-you-go fix requests: request, AI-drafted or staff quote, approve, logged real time, billed once (docs/1327)."},{"name":"extras","description":"First-party purchasable services (docs/26) — DB maintenance, SSL setup, managed migration, malware cleanup, and more. An admin-managed catalog; a purchase is charged then handed to durable fulfilment (an automated workflow or a staff task)."},{"name":"platform-transfers","description":"Replatforming sold as a service (docs/213) — moving a store off Shopify, Wix, Squarespace, Magento or any of 60+ platforms onto WooCommerce or WordPress hosted with us, with the old URLs redirected, canonicals and structured data preserved and the sitemap resubmitted. A specialist performs the work; the SEO checklist gates completion, so \"no data lost, no SEO loss\" is a control rather than a claim.\n\nA transfer is charged through the extras rails (one money path), so it carries the same tax treatment, wallet-first payment and invoice as every other purchase."},{"name":"domains","description":"Domain search, registration, transfer and DNS (docs/31). Availability search is public; everything that costs money or mutates a registered domain is tenant-scoped and RBAC-gated. Registration and transfer are **asynchronous** — they run as durable Temporal sagas behind an order, so the endpoints return a resource to poll rather than blocking on the registrar (§2.9)."},{"name":"seo","description":"Authority research and metrics (docs/11). The **research tool** runs any domain — including ones this account does not own — through the authority provider and is metered per lookup against a daily plan allowance, with packs of extra lookups bought from the account credit balance. Metrics for domains and sites the account already holds are kept fresh by a platform sweep and are free to read."},{"name":"api-keys","description":"Per-org API keys (docs/09 §1). Create, list, inspect and revoke keys, each scoped to a subset of RBAC permissions the creator holds. The secret is shown **once**, at creation, and only its hash is stored (CLAUDE.md §2.4); every mutation is audit-logged."},{"name":"audit","description":"The organization's append-only audit log (docs/06 §4) — a read view of the privileged actions taken in the tenant, including staff access. Every entry is immutable once written."},{"name":"links","description":"**The Link Tracker** (docs/96 §1) — a report over the outbound links that already exist in the customer's own WordPress sites: which domains they link to, how many times, in how many posts, and **from which of their sites**. It is a report, not a publisher.\n\nThe sites report themselves. A signed webhook carries a **full per-site snapshot** (batched, reconciled on completion), so nothing here reads a host and the same code works on our own fleet, the PBN line and managed hosting alike.\n\n⭐ A target that is one of the customer's **own** sites is marked as such. That distinction — *my own network* versus *a client's money site* — is the reason a PBN operator opens the screen."},{"name":"agency-board","description":"**The agency project board** (docs/320) — a Kanban an agency runs client work on, part of which the client themselves can see, answer questions on, and raise requests in.\n\nTwo surfaces at two prefixes. `/v1/agency/boards/**` is the agency's own, read in their own tenancy like any other customer endpoint. `/v1/agency/client/boards/**` is the client's restricted view of somebody else's board — the one place on this API that deliberately reads across a tenant boundary, authorised on the board's own `client_org_id`, narrowed to that single agency org, and returned through a hand-written projection whose field list is pinned by a test."},{"name":"agency-time","description":"**Agency time tracking, and the draft invoice it becomes** (docs/590) — staff log minutes against a client's work, a rate resolves, and unbilled time turns into a draft invoice in the agency's own invoicing suite on one of four triggers.\n\n⛔ Two things are integers everywhere on this surface and neither is negotiable. Money is minor units (§2.8), and **time is minutes** — there is no `hours` field anywhere, because an hours-as-float duration re-enters the money through the rate and no rounding point can recover it.\n\n⛔⛔ An hourly line carries the **rate**, never a price per minute. £50.00/h ÷ 60 is 83.33p and 83p × 90 minutes is £74.70 against a true £75.00 — a silent, deterministic under-bill on every rate that does not divide by 60, invisible to any test comparing one integer to another. The division happens once, in the invoicing suite, from `minutes` and `rate_minor_per_hour`.\n\nThere is no client-facing surface here: a timesheet is the agency's internal commercial record. The client sees the invoice."},{"name":"board-github","description":"**GitHub Projects v2, two-way** (docs/456) — a customer connects their GitHub, picks a Project, and gets a board in this app that is nicer to use than GitHub's own: a roll-up across every connected project, a roadmap built from real dates, WIP limits GitHub does not have, and notices for work that has gone quiet or run late.\n\nProjects v2 is **GraphQL only** — the REST `/projects` API is the deprecated *classic* Projects and cannot see a Project v2 at all. It fails in the reassuring direction: the REST call answers 200 with an empty list, which reads as *\"this customer has no projects\"* rather than *\"you asked the wrong API\"*.\n\nConflicts resolve **last-writer-wins with no banner** (owner ruling, 2026-09-03). \"Silently\" binds the screen and not the record: every overwrite is kept on `/v1/board-github/links/{linkId}/conflicts` with both values and both timestamps."},{"name":"members","description":"Organization membership (docs/06 §2). Invite people to an org with a role, accept an invitation, and remove members. Tenancy is hierarchical, so a membership grant is always within one org of the tree."},{"name":"affiliate","description":"The affiliate and referral programme (docs/22, docs/247). An affiliate shares a `?ref=CODE` link; the first touch is captured server-side and never overwritten, so the referrer who introduced a customer cannot be displaced by a later paid click.\n\nAn affiliate chooses one of two commission lines — 20% for twelve months, or 10% for the customer's lifetime. The choice can be changed at any time and **applies to new signups only**: the terms are frozen onto each referral when it converts, so changing your line never reprices customers you referred earlier."},{"name":"marketplace","description":"The marketplace a Zinner® sells on and a buyer browses (docs/83). Authoring is org-scoped; the listing page is anonymous and SINGLE-VARIANT — the masking rule is \"not signed in\" and a crawler is never signed in, so there is no user-agent branch anywhere and the revealed value lives behind a separate authenticated endpoint."},{"name":"proposals","description":"Priced offers an organisation sends to anyone by e-mail. Accepting one raises a real invoice; paying it opens a project board with a client room for messages and files (`docs/720`)."},{"name":"access","description":"Access & impersonation — the identity-side capabilities above tenancy/RBAC (docs/06, docs/35): the current impersonation status (banner) and exiting an impersonation session. The staff **mint** lives under `admin`; these are for the impersonated session itself."},{"name":"mcp","description":"The hosted **MCP server** (docs/27, register #36) — the AI connector. Customers mint a **per-tool, scoped, revocable** connection (\"Connect AI tool\") whose token lets an AI agent (Claude Code, Cursor, ChatGPT, …) drive their hosting over the Model Context Protocol. Every tool the agent invokes is gated by the connection's RBAC scopes and the same line-aware IP-protection the dashboard enforces (register #93), destructive actions require confirmation, paid actions are spend-capped, and every action is audit-logged (docs/27 §7). The protocol endpoint speaks JSON-RPC 2.0 and is authenticated only by the `zmcp_…` connection token; OAuth 2.1 discovery (RFC 9728) advertises Keycloak as the authorization server."},{"name":"assistant","description":"The customer AI assistant (docs/08 §4) — \"Ask Zinn®\". A conversation is a signed-in person's own thread, scoped to them and not merely to their organization: RLS scopes rows to a tenant and has no opinion about which colleague wrote them, so a colleague's thread is a `404`. Answers are grounded in **published knowledge-base articles** and, when the caller names one of their own sites, that site's health as read from our monitoring database moments earlier. It **cannot act** — no operation under this tag changes anything about a site, an order or an account, because a customer chatting is not a customer authorizing; acting lives under `mcp`, where a connection carries explicit scopes and every call is audited. When it cannot answer it says so (`needs_human`) and the thread can be escalated into a support ticket carrying the whole transcript."},{"name":"ai","description":"The acting AI agent and the AI we sell (docs/148, docs/133 §3–§5). Two audiences in one tag because they are two halves of one mechanism: a customer sees what the agent proposes for their sites and decides it; staff see **what the agent is allowed to do unattended**, and move it.\n\n⛔ **Authority is staged and earned per ACTION** — propose, then canary on one named target with the result watched, then fleet, and only after a rehearsed rollback. It is never granted to the agent as a whole: \"cache purge is at rung 3 and plugin rollback is at rung 1\" is a state that exists; \"the agent is trusted\" is not.\n\n⛔ **The agent holds no identity of its own.** Every application runs under the permissions of the person who approved it, so an approval can never reach further than the approver could reach by hand — and the staff agent is offered only the actions the calling operator already holds.\n\nMetering is **one meter with a funding field** (D4): a customer's own provider key, Zinn® AI credit, or the included daily allowance all write the same record, because two meters is how a customer on their own key gets billed by us."},{"name":"support","description":"Customer support tickets (docs/41) — the subsystem the control plane always owned on paper (CLAUDE.md §1) and finally implements. A ticket is a tenant-scoped conversation with a status/priority lifecycle, optionally about one site or one invoice, with a staff assignee. Both the ticket and every message on it carry `org_id` and are enforced by RLS (§2.3), so a thread is confined to the owning org's subtree. Staff notes are `internal` and are **never returned** on this surface — the customer query does not fetch them. The staff-side mirror of these endpoints lives under `admin`."},{"name":"plugin-support","description":"Support intake for the Zinn® WordPress plugins (Tranzly, Page Builder Sandwich) and a site's connection to it (X1/X7, ADR 0035). Anonymous or connection-token authenticated. A person who gives only an e-mail address becomes a support CONTACT — never an organization — and every ticket lands in the one Zinn-owned \"Zinn® plugin support\" org."},{"name":"seo-connect","description":"A Zinn® SEO WordPress site connected to a paying customer organization (stage E1, ADR 0038): a device-code flow approved by a signed-in member, or an account created from inside the plugin. The `zsc_` token is what the plugin's credit tools spend the organization's Zinn® credits with. Not the plugin-SUPPORT connection (`plugin-support`, ADR 0035)."},{"name":"seo-data","description":"Zinn® SEO stage C2: a connected site owner's OWN SEO data accounts (Ahrefs, Majestic, Moz, Semrush, SE Ranking, Open PageRank — keys held in Vault, never in WordPress) and Zinn® Authority on Zinn® credits; the metrics to show and track, competitors, history and up/down alerts."},{"name":"pbs-library","description":"The Page Builder Sandwich website-kit catalogue and cloud library (plan milestone X2, `docs/plugins-overhaul/pbs-cloud-library.md`). Kits are public to list; a free kit's content is public, a Pro kit's needs a Pro session. The cloud library (saved sections, pages and styles, and Agency team libraries) needs a session proven with the site's licensing install key. Metadata in Postgres, bytes in object storage, per-plan quotas."},{"name":"public","description":"The **guest funnel** (docs/43 §3.4) — search a domain, build a basket and buy it **without an account**; the account is created at checkout. Every operation here is **unauthenticated**, which makes this the only write surface on the API with no principal behind it. Two consequences worth knowing before you build against it. First, authorization is the cart's opaque **bearer token**: whoever holds it holds the cart, so treat it as a credential, and expect a uniform `404` for a token that is unknown, malformed, expired or already checked out. Second, every call spends an **abuse budget** — per client and globally — so a `429` here is normal traffic shaping, not an outage; honour `Retry-After`. Carts expire 24 hours after they are opened. Prices are always server-computed: a price sent by a client is ignored."},{"name":"campaigns","description":"Customer messaging — the AUDIENCE half (docs/25, docs/235). Who a campaign reaches, and who it must not. Both platform staff and resellers build segments here; the scope is derived from the caller and a reseller can only ever describe their OWN clients. ⛔ A platform campaign can never reach a reseller's client — they are white-labelled and have never heard of Zinn Digital® (owner ruling 2026-08-26). Delivery, templates and the in-app stream are the other half."},{"name":"Campaigns","description":"Customer messaging (docs/236) — templates with magic tags, multi-channel delivery, newsletters and the send report. ⚖️ Owner ruling 2026-08-26: staff AND resellers both compose here, and a reseller sends through their OWN provider account. ⛔ Marketing sends honour the suppression list and carry a one-click unsubscribe; transactional sends do neither, because a customer cannot opt out of \"your payment failed\"."},{"name":"client-reports","description":"White-label SEO reports an agency sends ITS clients (docs/858) — built from the SEO data the account already collects (rankings, AI visibility, the Google index, site health, backlinks, brand mentions), under the agency's own logo and colours, in the client's language, scheduled weekly, monthly or quarterly, e-mailed as a PDF and readable online behind a share link that expires. ⛔ A report never calls a supplier, and it names the agency, never the platform."},{"name":"agency-invoicing","description":"An AGENCY invoicing ITS OWN clients (docs/589) — a branded invoice builder, saved clients and their history, tax rates, PDF, email delivery and a public payment page that collects into the agency's OWN Stripe / PayPal / crypto account. ⛔⛔ Not the `invoices` tag, which is Zinn® invoicing its customer: a different company, a different tax registration, a different number series, and money that never touches our balance."},{"name":"Inbox","description":"The customer's in-app message stream (docs/236) — campaign messages, support-ticket replies and account notifications in one threaded list. ⛔ Deliberately DISJOINT from the alerts bell: an alert is transient and dismissable, a message is durable and re-readable, and no row is ever in both."}],"paths":{"/v1/agency-invoicing/profile":{"get":{"operationId":"getAgencyInvoicingProfile","tags":["agency-invoicing"],"summary":"Your agency's invoicing identity — what an invoice says it is FROM.","description":"Your registered name, address, tax number, logo, brand colour, defaults and your OWN invoice number series. ⛔ Separate from your panel branding: an invoice needs a legal entity, and you may bill under a different one from the one on your dashboard. Requires `agency.invoicing.view`.","parameters":[{"$ref":"#/components/parameters/AgencyInvoicingOrgId"}],"responses":{"200":{"description":"The profile.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyInvoicingProfile"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateAgencyInvoicingProfile","tags":["agency-invoicing"],"summary":"Change your invoicing identity or defaults.","description":"⛔ `next_number` is deliberately NOT settable. Rewinding a sequence would mint a duplicate number for a document already in a client's hands; advancing it leaves a gap a tax authority will ask about. Requires `agency.invoicing.manage`.","parameters":[{"$ref":"#/components/parameters/AgencyInvoicingOrgId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyInvoicingProfileUpdate"}}}},"responses":{"200":{"description":"The updated profile.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyInvoicingProfile"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/agency-invoicing/logo":{"post":{"operationId":"uploadAgencyInvoiceLogo","tags":["agency-invoicing"],"summary":"Upload the logo your invoices carry.","description":"⛔ Its own door, and `POST /v1/branding/logo` cannot serve it: that one stores the mark for a white-labelled **panel**, demands `reseller.manage`, and refuses unless white-label is on the plan — with the message *\"a logo here would appear nowhere\"*. On a panel that is right. On an invoice it is false: the document is your own paper and carries your mark whatever your plan says. ⭐ The image is vetted and stored content-addressed; the digest returned is what the PDF inlines as a `data:` URI, which is what keeps the render offline. Requires `agency.invoicing.manage`.","parameters":[{"$ref":"#/components/parameters/AgencyInvoicingOrgId"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["logo"],"properties":{"logo":{"type":"string","format":"binary","description":"The image. 256 KB maximum."}}}}}},"responses":{"201":{"description":"Stored, and set on your invoicing profile.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyInvoiceLogo"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"clearAgencyInvoiceLogo","tags":["agency-invoicing"],"summary":"Take the logo off future invoices.","description":"⛔ The stored image is **kept**. An invoice you have already issued names it in its frozen snapshot and inlines it when rendered — deleting the bytes would silently strip your mark off every document you have already sent. Requires `agency.invoicing.manage`.","parameters":[{"$ref":"#/components/parameters/AgencyInvoicingOrgId"}],"responses":{"204":{"description":"Cleared."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/agency-invoicing/gateway":{"get":{"operationId":"getAgencyInvoicingGateway","tags":["agency-invoicing"],"summary":"Can you collect online, and through which of your own accounts?","description":"⭐ The answer to a silent failure. An agency with no connected gateway gets a payment portal that refuses every payment — correctly, because the money would otherwise settle somewhere it does not belong — and nothing else on the platform says so. ⛔ `established: false` means we could not look, which is NOT the same as \"you have none\": the second is actionable and the first is ours to fix. Requires `agency.invoicing.view`.","parameters":[{"$ref":"#/components/parameters/AgencyInvoicingOrgId"}],"responses":{"200":{"description":"The agency's own connected gateways.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyInvoicingGatewayStatus"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/agency-invoicing/clients":{"get":{"operationId":"listAgencyClients","tags":["agency-invoicing"],"summary":"The clients you invoice.","description":"⛔ These are contact records you typed, NOT platform organizations — your client may have no account here at all. Requires `agency.invoicing.view`.","parameters":[{"$ref":"#/components/parameters/AgencyInvoicingOrgId"},{"name":"include_archived","in":"query","required":false,"description":"Include clients you have archived.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Your clients.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyClientList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createAgencyClient","tags":["agency-invoicing"],"summary":"Save a client.","parameters":[{"$ref":"#/components/parameters/AgencyInvoicingOrgId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyClientWrite"}}}},"responses":{"201":{"description":"The saved client.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyClient"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/agency-invoicing/clients/{clientId}":{"parameters":[{"name":"clientId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"get":{"operationId":"getAgencyClient","tags":["agency-invoicing"],"summary":"One client, with their whole invoice history.","description":"⭐ Every invoice you have raised against them, what they still owe and what they have been billed in total — the \"all client history\" screen in one request rather than a filtered list. Requires `agency.invoicing.view`.","parameters":[{"$ref":"#/components/parameters/AgencyInvoicingOrgId"}],"responses":{"200":{"description":"The client and their history.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyClientHistory"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateAgencyClient","tags":["agency-invoicing"],"summary":"Change a client's details.","parameters":[{"$ref":"#/components/parameters/AgencyInvoicingOrgId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyClientWrite"}}}},"responses":{"200":{"description":"The updated client.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyClient"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"archiveAgencyClient","tags":["agency-invoicing"],"summary":"Archive a client.","description":"⛔ Archived, never deleted. Deleting would take the counterparty off invoices you have already sent. Requires `agency.invoicing.manage`.","parameters":[{"$ref":"#/components/parameters/AgencyInvoicingOrgId"}],"responses":{"204":{"description":"Archived."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/agency-invoicing/tax-rates":{"get":{"operationId":"listAgencyTaxRates","tags":["agency-invoicing"],"summary":"The tax rates you charge — VAT, GST, a sales tax, or zero-rated.","description":"Rates are integer **basis points**: 20% VAT is `2000`. Nothing on this path is a float. Requires `agency.invoicing.view`.","parameters":[{"$ref":"#/components/parameters/AgencyInvoicingOrgId"}],"responses":{"200":{"description":"Your tax rates.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyTaxRateList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createAgencyTaxRate","tags":["agency-invoicing"],"summary":"Add a tax rate.","parameters":[{"$ref":"#/components/parameters/AgencyInvoicingOrgId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyTaxRateWrite"}}}},"responses":{"201":{"description":"The new rate.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyTaxRate"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/agency-invoicing/tax-rates/{rateId}":{"parameters":[{"name":"rateId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"patch":{"operationId":"updateAgencyTaxRate","tags":["agency-invoicing"],"summary":"Change a tax rate.","description":"⭐ Changing a rate does NOT restate any invoice that already carries it — the percentage and the name are copied onto each line when it is saved. That is what lets you move VAT from 20% to 17.5% next April without rewriting last month. Requires `agency.invoicing.manage`.","parameters":[{"$ref":"#/components/parameters/AgencyInvoicingOrgId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyTaxRateWrite"}}}},"responses":{"200":{"description":"The updated rate.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyTaxRate"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"archiveAgencyTaxRate","tags":["agency-invoicing"],"summary":"Archive a tax rate.","parameters":[{"$ref":"#/components/parameters/AgencyInvoicingOrgId"}],"responses":{"204":{"description":"Archived."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/agency-invoicing/blocks":{"get":{"operationId":"listAgencyInvoiceBlocks","tags":["agency-invoicing"],"summary":"Saved reusable text — footers, notes and payment terms.","description":"The \"repeating things\" you set up once and drop onto invoices. Requires `agency.invoicing.view`.","parameters":[{"$ref":"#/components/parameters/AgencyInvoicingOrgId"}],"responses":{"200":{"description":"Your saved blocks.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyInvoiceBlockList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createAgencyInvoiceBlock","tags":["agency-invoicing"],"summary":"Save a reusable text block.","parameters":[{"$ref":"#/components/parameters/AgencyInvoicingOrgId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyInvoiceBlockWrite"}}}},"responses":{"201":{"description":"The saved block.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyInvoiceBlock"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/agency-invoicing/blocks/{blockId}":{"parameters":[{"name":"blockId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"patch":{"operationId":"updateAgencyInvoiceBlock","tags":["agency-invoicing"],"summary":"Change a saved text block.","parameters":[{"$ref":"#/components/parameters/AgencyInvoicingOrgId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyInvoiceBlockWrite"}}}},"responses":{"200":{"description":"The updated block.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyInvoiceBlock"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"deleteAgencyInvoiceBlock","tags":["agency-invoicing"],"summary":"Delete a saved text block.","parameters":[{"$ref":"#/components/parameters/AgencyInvoicingOrgId"}],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/agency-invoicing/preview":{"post":{"operationId":"previewAgencyInvoiceTotals","tags":["agency-invoicing"],"summary":"Total a set of lines without saving anything.","description":"Backs the live preview in the invoice builder. ⭐ It calls the SAME arithmetic the save path uses — a preview computed by a second implementation is one that can disagree with the invoice, and you would find out after you had sent it. Requires `agency.invoicing.view`.","parameters":[{"$ref":"#/components/parameters/AgencyInvoicingOrgId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["lines"],"properties":{"lines":{"type":"array","items":{"$ref":"#/components/schemas/AgencyInvoiceLineWrite"}}}}}}},"responses":{"200":{"description":"The totals these lines would produce.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyInvoiceTotals"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/agency-invoicing/invoices":{"get":{"operationId":"listAgencyInvoices","tags":["agency-invoicing"],"summary":"Your invoices.","description":"⭐ `status=overdue` is a real filter even though there is no overdue column: overdue is derived from the due date and the status, so there is no sweep to maintain a flag and nothing to go stale. Requires `agency.invoicing.view`.","parameters":[{"$ref":"#/components/parameters/AgencyInvoicingOrgId"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","sent","partially_paid","paid","void","overdue"]}},{"name":"client_id","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"Your invoices, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyInvoiceList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createAgencyInvoice","tags":["agency-invoicing"],"summary":"Start a draft invoice.","description":"Give a `client_id`, or a `client` object to create one inline — a client typed during invoicing is SAVED, so next time you can just select them. ⛔ Totals are never accepted from the caller; they are computed from the lines. Requires `agency.invoicing.manage`.","parameters":[{"$ref":"#/components/parameters/AgencyInvoicingOrgId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyInvoiceCreate"}}}},"responses":{"201":{"description":"The draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyInvoice"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/agency-invoicing/invoices/{invoiceId}":{"parameters":[{"name":"invoiceId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"get":{"operationId":"getAgencyInvoice","tags":["agency-invoicing"],"summary":"One invoice, with its lines, payments and payment link.","parameters":[{"$ref":"#/components/parameters/AgencyInvoicingOrgId"}],"responses":{"200":{"description":"The invoice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyInvoice"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateAgencyInvoice","tags":["agency-invoicing"],"summary":"Edit a draft invoice.","description":"⛔ A `409` means the invoice has been issued and its figures are frozen. A sent invoice is a document your client is holding — void it and issue a replacement rather than restating it. Requires `agency.invoicing.manage`.","parameters":[{"$ref":"#/components/parameters/AgencyInvoicingOrgId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyInvoiceUpdate"}}}},"responses":{"200":{"description":"The updated draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyInvoice"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"deleteAgencyInvoiceDraft","tags":["agency-invoicing"],"summary":"Delete a draft.","description":"⛔ Drafts only. An issued invoice is voided, which keeps its number and leaves an audit trail. Requires `agency.invoicing.manage`.","parameters":[{"$ref":"#/components/parameters/AgencyInvoicingOrgId"}],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/agency-invoicing/invoices/{invoiceId}/issue":{"parameters":[{"name":"invoiceId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"issueAgencyInvoice","tags":["agency-invoicing"],"summary":"Give the invoice its number and freeze it.","description":"Allocates the next number in YOUR series, freezes both parties onto the document and makes the payment link live. ⛔ An invoice with no lines, or one totalling zero, is refused — a numbered document for nothing is a gap in a sequence a tax authority expects to be unbroken. Requires `agency.invoicing.manage`.","parameters":[{"$ref":"#/components/parameters/AgencyInvoicingOrgId"}],"responses":{"200":{"description":"The issued invoice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyInvoice"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/agency-invoicing/invoices/{invoiceId}/send":{"parameters":[{"name":"invoiceId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"sendAgencyInvoice","tags":["agency-invoicing"],"summary":"Email the invoice to your client, with the PDF attached.","description":"Issues it first if it is still a draft. Leaves on YOUR mail account when you have connected one, otherwise on ours with your address as Reply-To and a line saying who issued it. The PDF is attached as bytes rather than linked — a link would expire, and it would put our storage hostname in front of your client. Requires `agency.invoicing.manage`.","parameters":[{"$ref":"#/components/parameters/AgencyInvoicingOrgId"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","description":"Where to send it. Defaults to the client's stored email."},"locale":{"type":"string","description":"Which language to render in. Defaults to the client's locale — an agency in Berlin invoicing a French client sends a French invoice."},"note":{"type":"string","description":"A covering line to put above the amount."}}}}}},"responses":{"200":{"description":"Sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyInvoiceSendResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/agency-invoicing/invoices/{invoiceId}/pdf":{"parameters":[{"name":"invoiceId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"get":{"operationId":"getAgencyInvoicePdf","tags":["agency-invoicing"],"summary":"A short-lived download URL for the invoice PDF.","description":"Rendered from the frozen snapshot, so the same invoice re-rendered years from now is the same document. ⛔ The renderer follows no external reference of any kind: your logo is inlined from bytes we hold. Requires `agency.invoicing.view`.","parameters":[{"$ref":"#/components/parameters/AgencyInvoicingOrgId"},{"name":"locale","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"A presigned URL.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyInvoicePdfLink"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/agency-invoicing/invoices/{invoiceId}/payments":{"parameters":[{"name":"invoiceId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"recordAgencyInvoicePayment","tags":["agency-invoicing"],"summary":"Record money received — mark it paid or part-paid.","description":"Defaults to the outstanding balance. The invoice's status is re-derived from the SUM of its payment rows, never incremented, so the two can never disagree. Requires `agency.invoicing.manage`.","parameters":[{"$ref":"#/components/parameters/AgencyInvoicingOrgId"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyInvoicePaymentWrite"}}}},"responses":{"200":{"description":"Already recorded — this payment reference had been seen before.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyInvoice"}}}},"201":{"description":"Recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyInvoice"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/agency-invoicing/invoices/{invoiceId}/void":{"parameters":[{"name":"invoiceId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"voidAgencyInvoice","tags":["agency-invoicing"],"summary":"Void an invoice.","description":"⛔ The number is KEPT — a voided invoice is a document that says VOID on it, not an absence, and deleting the number would leave the gap the sequence exists to prevent. ⛔ Refused when payments have been recorded: that is a refund, which is a different act. Requires `agency.invoicing.manage`.","parameters":[{"$ref":"#/components/parameters/AgencyInvoicingOrgId"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"Voided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyInvoice"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/agency-invoicing/portal-labels":{"get":{"operationId":"getAgencyInvoicePortalLabels","tags":["agency-invoicing"],"summary":"The payment pages' labels in one language, with no invoice. Unauthenticated.","description":"For the \"this payment link is no longer valid\" page on both public payment pages, which has no invoice to read labels from. Keyed on the URL's locale, never on a token, so it confirms nothing about any link.","security":[],"parameters":[{"name":"locale","in":"query","required":false,"schema":{"type":"string","default":"en"}}],"responses":{"200":{"description":"The labels.","content":{"application/json":{"schema":{"type":"object","required":["locale","direction","labels"],"properties":{"locale":{"type":"string"},"direction":{"type":"string","enum":["ltr","rtl"]},"labels":{"type":"object","additionalProperties":{"type":"string"}}}}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/agency-invoicing/portal/{token}":{"parameters":[{"name":"token","in":"path","required":true,"description":"The capability token from the payment link on the invoice.","schema":{"type":"string"}}],"get":{"operationId":"getAgencyInvoicePortal","tags":["agency-invoicing"],"summary":"The invoice, for the person paying it. Unauthenticated.","description":"⛔ **No authentication.** The payer is the agency's client and has no account here; the token in the URL is the whole authorisation and reaches exactly one invoice. A revoked, void or draft link answers `404`, the same as a wrong token — telling them apart would confirm to a stranger that a token is real.","security":[],"responses":{"200":{"description":"The invoice as the payer sees it, already localized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyInvoicePortal"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/agency-invoicing/portal/{token}/checkout":{"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"post":{"operationId":"checkoutAgencyInvoicePortal","tags":["agency-invoicing"],"summary":"Start a payment on the AGENCY's own gateway. Unauthenticated.","description":"⛔⛔ The money settles into the **agency's** merchant account and never touches Zinn®'s balance. An agency with no connected gateway gets a `409` — there is no fallback, because there is no relationship under which we could take money for a document our name is nowhere near. Returns a `client_token` for a browser SDK, a `redirect_url` for an approval or hosted-invoice rail, or a completed capture.","security":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","description":"Which of the agency's connected gateways to use. Their default when omitted."}}}}}},"responses":{"200":{"description":"The payment has been started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyInvoiceCheckout"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/agency/board-automation-catalogue":{"get":{"operationId":"getBoardAutomationCatalogue","summary":"What a rule can be built out of.","description":"Every trigger, condition operator, action and platform event this engine understands, with the context fields each trigger publishes.\n\n⛔ The rule builder reads THIS rather than carrying its own copy of the list. A hardcoded copy in the console is a second source of truth that goes stale the first time a lane adds a trigger — and it goes stale silently, because the builder still renders and simply does not offer the new one.\n\nNot board-scoped: the catalogue is the same for every board.","tags":["agency-board"],"responses":{"200":{"description":"The catalogue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardAutomationCatalogue"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/agency/boards/{boardId}/automations":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"}],"get":{"operationId":"listBoardAutomations","summary":"The board's automation rules.","tags":["agency-board"],"responses":{"200":{"description":"Every rule on this board, in the customer's own order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardAutomationRuleList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"createBoardAutomation","summary":"Create a rule — when this happens, only if that, then do these.","description":"Validated against the catalogue at save time, not at run time. A rule pairing a card action with a trigger that carries no card, naming a context field its trigger does not publish, or using an operator the field's type cannot take is refused here with the offending clause named — because the alternative is a rule that sits in the list looking enabled and does nothing for ever, whose only evidence is an absence.","tags":["agency-board"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardAutomationRuleWrite"}}}},"responses":{"201":{"description":"The new rule.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardAutomationRule"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/boards/{boardId}/automations/{ruleId}":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"},{"$ref":"#/components/parameters/BoardAutomationRuleId"}],"get":{"operationId":"getBoardAutomation","summary":"One rule.","tags":["agency-board"],"responses":{"200":{"description":"The rule.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardAutomationRule"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"operationId":"updateBoardAutomation","summary":"Change a rule, or pause and resume it.","description":"The WHOLE rule is re-validated, not just the changed fields — a change to the trigger alone can invalidate an action that was fine before it.\n\n⛔ `suspended` is not settable. That status means *we* paused the rule after repeated failure and carries a reason the customer has not read; letting it be written would make our decision indistinguishable from theirs. Re-enabling a suspended rule clears its failure count.","tags":["agency-board"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardAutomationRuleWrite"}}}},"responses":{"200":{"description":"The updated rule.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardAutomationRule"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"deleteBoardAutomation","summary":"Delete a rule and its history.","tags":["agency-board"],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/agency/boards/{boardId}/automations/{ruleId}/runs":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"},{"$ref":"#/components/parameters/BoardAutomationRuleId"}],"get":{"operationId":"listBoardAutomationRuns","summary":"Every time this rule was considered — and why it did or did not fire.","description":"A row is written whenever the rule was **considered**, not only when it fired, and each carries the result of every condition with the value it actually saw.\n\n⛔ That is the whole point of the endpoint. A rule that does not fire otherwise leaves the customer with an absence, which is indistinguishable from \"the trigger never happened\", from \"it is disabled\" and from \"the platform is down\".","tags":["agency-board"],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"A page of runs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardAutomationRunPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/agency/boards/{boardId}/automation-runs":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"}],"get":{"operationId":"listBoardAutomationRunsForBoard","summary":"Every rule's history on this board, together.","tags":["agency-board"],"parameters":[{"name":"outcome","in":"query","required":false,"description":"Only runs with this outcome.","schema":{"$ref":"#/components/schemas/BoardAutomationOutcome"}},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"A page of runs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardAutomationRunPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/agency/boards/{boardId}/webhooks":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"}],"get":{"operationId":"listBoardWebhooks","summary":"Where this board POSTs when something happens.","tags":["agency-board"],"responses":{"200":{"description":"The board's outbound webhook subscriptions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardWebhookList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"createBoardWebhook","summary":"Add an outbound webhook.","description":"HTTPS only. We mint the signing secret and return it **once, in this response**. There is no endpoint that can read it back, so keep it — rotate to get a new one.\n\nDeliveries are signed `X-Zinn-Signature: sha256=<hmac over \"<timestamp>.<body>\">` with `X-Zinn-Timestamp`, `X-Zinn-Delivery` and `X-Zinn-Event` beside them. The timestamp is bound INTO the signature so a captured request cannot be replayed for ever, and so a receiver cannot be tricked about which timestamp it was.","tags":["agency-board"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardWebhookWrite"}}}},"responses":{"201":{"description":"The new subscription, with its signing secret — shown only here.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardWebhookWithSecret"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/boards/{boardId}/webhooks/{webhookId}":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"},{"$ref":"#/components/parameters/BoardWebhookId"}],"get":{"operationId":"getBoardWebhook","summary":"One webhook subscription.","tags":["agency-board"],"responses":{"200":{"description":"The subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardWebhook"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"operationId":"updateBoardWebhook","summary":"Change a webhook, or pause and resume it.","tags":["agency-board"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardWebhookWrite"}}}},"responses":{"200":{"description":"The updated subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardWebhook"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"deleteBoardWebhook","summary":"Delete a webhook and forget its secret.","tags":["agency-board"],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/agency/boards/{boardId}/webhooks/{webhookId}/rotate":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"},{"$ref":"#/components/parameters/BoardWebhookId"}],"post":{"operationId":"rotateBoardWebhookSecret","summary":"Mint a new signing secret.","description":"The URL does not change; only the secret does. Deliveries signed with the old secret stop verifying immediately, so update the receiver in the same sitting.","tags":["agency-board"],"responses":{"200":{"description":"The subscription, with its new secret — shown only here.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardWebhookWithSecret"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/boards/{boardId}/webhooks/{webhookId}/test":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"},{"$ref":"#/components/parameters/BoardWebhookId"}],"post":{"operationId":"testBoardWebhook","summary":"Send a signed test delivery now.","description":"The most useful button on the screen: an integrator wiring up n8n wants to see a request arrive before they build the rest of the workflow. Returns the delivery row, which carries the response status and the first 500 bytes the receiver answered with.","tags":["agency-board"],"responses":{"202":{"description":"The delivery that was attempted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardWebhookDelivery"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/agency/boards/{boardId}/webhook-deliveries":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"}],"get":{"operationId":"listBoardWebhookDeliveries","summary":"What we sent, when, and what came back.","description":"The body is stored exactly as it was signed and sent, because \"did it work\" and \"what did you send me\" are different questions and only the second one is ever actually asked.","tags":["agency-board"],"parameters":[{"name":"subscriptionId","in":"query","required":false,"description":"Only deliveries for this subscription.","schema":{"$ref":"#/components/schemas/Uuid"}},{"name":"status","in":"query","required":false,"schema":{"$ref":"#/components/schemas/BoardWebhookDeliveryStatus"}},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"A page of deliveries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardWebhookDeliveryPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/agency/boards/{boardId}/webhook-deliveries/{deliveryId}/replay":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"},{"$ref":"#/components/parameters/BoardWebhookDeliveryId"}],"post":{"operationId":"replayBoardWebhookDelivery","summary":"Send the same payload again.","description":"Re-sends the STORED bytes with a fresh timestamp and a fresh signature over those same bytes. Nothing is re-serialised — a different byte string would produce a signature the receiver cannot verify, which fails as *\"your signatures are wrong\"* on their side and is unfalsifiable from ours.","tags":["agency-board"],"responses":{"202":{"description":"The replay delivery.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardWebhookDelivery"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/agency/boards/{boardId}/inbound-endpoints":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"}],"get":{"operationId":"listBoardInboundEndpoints","summary":"The URLs n8n, Zapier and Make POST to.","tags":["agency-board"],"responses":{"200":{"description":"The board's inbound endpoints.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardInboundEndpointList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"createBoardInboundEndpoint","summary":"Create an inbound endpoint.","description":"Returns the full URL to paste into the sending system, and the secret **once**.\n\nThe URL carries one opaque key, not the board id — so it leaks no internal identifier into somebody else's logs, and rotating the secret does not change the URL. Tenancy comes off the endpoint row and never out of the POSTed body, which is what makes it unforgeable across tenants.","tags":["agency-board"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardInboundEndpointWrite"}}}},"responses":{"201":{"description":"The new endpoint, with its secret — shown only here.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardInboundEndpointWithSecret"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/boards/{boardId}/inbound-endpoints/{endpointId}":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"},{"$ref":"#/components/parameters/BoardInboundEndpointId"}],"get":{"operationId":"getBoardInboundEndpoint","summary":"One inbound endpoint.","tags":["agency-board"],"responses":{"200":{"description":"The endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardInboundEndpoint"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"operationId":"updateBoardInboundEndpoint","summary":"Rename an endpoint, or pause and resume it.","tags":["agency-board"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardInboundEndpointWrite"}}}},"responses":{"200":{"description":"The updated endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardInboundEndpoint"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"deleteBoardInboundEndpoint","summary":"Delete an endpoint and forget its secret.","tags":["agency-board"],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/agency/boards/{boardId}/inbound-endpoints/{endpointId}/rotate":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"},{"$ref":"#/components/parameters/BoardInboundEndpointId"}],"post":{"operationId":"rotateBoardInboundEndpointSecret","summary":"Mint a new secret for an inbound endpoint.","description":"The URL is unchanged — only the secret the sender signs with. That separation is why a rotation is a one-field edit in the sending system rather than a reconfigure.","tags":["agency-board"],"responses":{"200":{"description":"The endpoint, with its new secret — shown only here.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardInboundEndpointWithSecret"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/boards/{boardId}/inbound-requests":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"}],"get":{"operationId":"listBoardInboundRequests","summary":"What arrived on this board's endpoints — accepted and refused.","description":"Refusals are kept as well as acceptances. An integrator whose signature is wrong reads *why* here; a log of successes only is a log that is empty exactly when somebody needs it.","tags":["agency-board"],"parameters":[{"name":"endpointId","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Uuid"}},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"A page of inbound requests.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardInboundRequestPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/agency/boards/{boardId}/event-subscriptions":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"}],"get":{"operationId":"listBoardEventSubscriptions","summary":"Which Zinn® platform events create cards on this board.","tags":["agency-board"],"responses":{"200":{"description":"The board's platform-event subscriptions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardEventSubscriptionList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"setBoardEventSubscription","summary":"Turn a platform event on for this board.","description":"Opt-in, per board, off by default — nothing appears on a board nobody chose. One subscription per event type per board; posting the same event type again updates it.\n\nCards land `internal` unless you say otherwise: a platform event names our own infrastructure and sometimes our own failures, and putting one in front of the agency's client should be a choice rather than a default.","tags":["agency-board"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardEventSubscriptionWrite"}}}},"responses":{"200":{"description":"The updated subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardEventSubscription"}}}},"201":{"description":"The new subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardEventSubscription"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/boards/{boardId}/event-subscriptions/{subscriptionId}":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"},{"$ref":"#/components/parameters/BoardEventSubscriptionId"}],"delete":{"operationId":"deleteBoardEventSubscription","summary":"Stop this event creating cards on this board.","tags":["agency-board"],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/board-hooks/{endpointKey}":{"parameters":[{"$ref":"#/components/parameters/BoardInboundEndpointKey"}],"post":{"operationId":"receiveBoardInboundWebhook","summary":"The public inbound door — n8n, Zapier, Make, GitHub.","description":"**Unauthenticated by design: the HMAC signature IS the authentication**, exactly as `/v1/webhooks/stripe` is. Send `X-Zinn-Signature: sha256=<hmac-sha256 over \"<timestamp>.<raw body>\">` and `X-Zinn-Timestamp` (unix seconds, within five minutes of now), signed with the endpoint's secret.\n\nThe body must be a JSON object. Five top-level values — `event`, `status`, `title`, `body`, `ref` — are projected into the rule's condition surface as `payload_*`, so a rule can branch on them. Anything else in the body is stored in the request log and is not conditionable.\n\n⛔ An unknown endpoint key and a bad signature both answer **404 with the same body**, deliberately: distinguishing them would turn this into an oracle for whether a key exists. The endpoint's OWNER sees the real reason on their own screen.","tags":["agency-board"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardInboundPayload"}}}},"responses":{"202":{"description":"Accepted; rules were evaluated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardInboundAccepted"}}}},"200":{"description":"Accepted and ignored — a ping, or an event this endpoint does not act on. A 2xx on purpose: a sender that gets a 4xx for a healthy no-op retries it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardInboundAccepted"}}}},"404":{"description":"No such endpoint, or the signature did not verify.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"This endpoint is paused by its owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The payload is larger than 64 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 120 requests in a minute on this endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/affiliate":{"get":{"operationId":"getAffiliateAccount","summary":"Your affiliate account, your earnings, and the lines you can choose from.","description":"Gated on `affiliate.view`. Answers `200` with `account: null` when this organisation has not joined — \"you are not an affiliate yet\" is a normal state of a screen every customer can open, not an error.\n\n`totals.by_currency` is grouped by currency and deliberately **not** summed across them: adding 100 GBP to 100 EUR produces a number that is wrong in both. `plans` is served from the engine rather than hardcoded in a console, so a rate the owner changes cannot disagree with the rate a customer read before signing up.","tags":["affiliate"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The affiliate account, or `null` with the catalogue of lines.","content":{"application/json":{"schema":{"type":"object","required":["account","totals","plans"],"properties":{"account":{"allOf":[{"$ref":"#/components/schemas/AffiliateAccount"}],"nullable":true},"totals":{"$ref":"#/components/schemas/AffiliateTotals"},"plans":{"type":"array","items":{"$ref":"#/components/schemas/AffiliateCommissionPlan"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"joinAffiliateProgramme","summary":"Join the affiliate programme.","description":"Gated on `affiliate.manage`. The account lands `pending` and accrues nothing until staff approve it — otherwise the programme is an open invitation to self-refer at scale. Choosing cash payouts sets `kyc_state` to `required`; wallet credit needs no verification because the money never leaves the platform.","tags":["affiliate"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AffiliateJoin"}}}},"responses":{"201":{"description":"The newly created affiliate account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AffiliateAccount"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"patch":{"operationId":"updateAffiliateAccount","summary":"Change your commission line or how you are paid.","description":"Gated on `affiliate.manage`. **A change applies to new signups only.** Customers you have already referred keep the terms that were live when they converted — those terms are stored on the referral itself, so nothing here can reprice them.","tags":["affiliate"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AffiliateUpdate"}}}},"responses":{"200":{"description":"The updated affiliate account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AffiliateAccount"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/affiliate/referrals":{"get":{"operationId":"listAffiliateReferrals","summary":"The customers who signed up through your links.","description":"Gated on `affiliate.view`. Each row carries the commission terms **as they were when that customer converted** — `plan`, `rate_bps` and `duration_months` are a snapshot, not a copy of your current line, so the screen shows what each referral actually earns.","tags":["affiliate"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"The affiliate's referrals, newest first.","content":{"application/json":{"schema":{"type":"object","required":["items","total","limit","offset"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AffiliateReferral"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/affiliate/commissions":{"get":{"operationId":"listAffiliateCommissions","summary":"Your earnings ledger.","description":"Gated on `affiliate.view`. One row per payment a referred customer made. `basis` is the payment the commission was computed from and `rate_bps` the rate applied, so every line can show its own working years later without reconstructing anything.","tags":["affiliate"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"state","in":"query","required":false,"schema":{"type":"string","enum":["pending","approved","paid","reversed"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"The affiliate's commission entries, newest first.","content":{"application/json":{"schema":{"type":"object","required":["items","total","limit","offset"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AffiliateCommission"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/surveys/active":{"get":{"operationId":"getActiveSurveys","summary":"The surveys this organisation may currently be shown.","description":"Every decision ABOUT the customer is applied here, server-side, before a survey crosses the wire — good standing, the per-organisation kill switch, and archived or stopped surveys. The client is left with exactly the three things only it can know: which route it is on, whether this person has seen a survey recently, and the sampling die roll.\n\n⛔ `available` is a first-class part of the answer. A survey store that is unconfigured, rate-limited or unreachable is NOT the same fact as \"you have no surveys\", and `surveys: []` on its own would tell the app every survey had been archived. On `available: false` the client keeps its previous answer. Requires `org.read`.","tags":["surveys"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"distinct_id","in":"query","required":false,"description":"The browser's analytics distinct id, so the join resolves.","schema":{"type":"string","maxLength":200}},{"name":"locale","in":"query","required":false,"description":"The language the app is rendering in (a BCP 47 tag such as `ar` or `pt-PT`). A supported value is the language the surveys are served in; an absent or unsupported one falls back to the caller's stored language preference.","schema":{"type":"string","maxLength":35}}],"responses":{"200":{"description":"The eligible surveys, or the reason none could be read.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActiveSurveys"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/surveys/{survey_id}/responses":{"post":{"operationId":"createSurveyResponse","summary":"Record one person's answers to one survey.","description":"Stored in our own organisation-scoped table FIRST and unconditionally, then mirrored to the behavioural backend so the analytics join resolves. The two copies have opposite error policies deliberately: losing the customer's answer is unacceptable, losing the vendor's copy of an answer we already hold costs a join.\n\n⛔ The survey is re-fetched and re-checked against the store — a client sends an id, and a client is a thing a person can edit. Answering an archived or stopped survey is refused. A SECOND answer from the same person returns `200` with `duplicate: true` rather than a conflict: the unique constraint exists to stop a doubled count, and the commonest way it fires is a retry after a dropped connection. Requires `org.read`.","tags":["surveys"],"parameters":[{"name":"survey_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SurveyResponseCreate"}}}},"responses":{"200":{"description":"The answer was recorded (or was already recorded).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SurveyResponseAck"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/feature-flags":{"get":{"operationId":"getFeatureFlags","summary":"Every feature flag that is ON for this person in this organisation.","description":"Evaluated by the engine rather than in the browser, so an ad-blocker cannot switch off whatever every flag gates, and so the product and the API cannot disagree about what a customer is entitled to see. A boolean flag answers `true`; an experiment answers its variant name.\n\n⛔ `available: false` is NOT `flags: {}`. An empty map and \"every flag is off\" are the same value, and every consumer reads a missing key as off — so a rate-limited vendor would quietly switch off whatever every flag gates. The client keeps its last answer on `available: false`. Requires `org.read`.","tags":["surveys"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"distinct_id","in":"query","required":false,"schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"The flags that are on, or the reason they could not be evaluated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureFlagsResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/healthz":{"get":{"operationId":"getHealthz","summary":"Liveness/health probe.","description":"Returns service health. Unauthenticated; used by load balancers and uptime checks.","tags":["system"],"security":[],"responses":{"200":{"description":"Service is healthy.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}},"/readyz":{"get":{"operationId":"getReadyz","summary":"Readiness probe — are this instance's workers warm and can it reach its database.","description":"Unauthenticated. 200 when every worker of this instance has finished its boot work (after the instance's first full warm-up, one warm worker is enough, so a worker being replaced does not take the instance out of service) and the instance can run a query; 503 otherwise (`reason` says which), so the orchestrator sends no request to an instance that is still starting or could only fail. A database that stops answering an instance that WAS serving is tolerated for a 45 s grace (`database: degraded`), because a blip shared by every instance must not take them all out of service at once; one that never answered it is not. Liveness stays on /healthz.","tags":["system"],"security":[],"responses":{"200":{"description":"Ready.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Readiness"}}}},"503":{"description":"Not ready (`warming` — workers still starting; `database` — it did not answer).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Readiness"}}}}}}},"/version.txt":{"get":{"operationId":"getVersionTxt","summary":"The commit this API build was made from.","description":"Plain text: the 40-character git sha baked into the running engine image at build time, or `unknown` for an image built without one. Unauthenticated and never cached, so a deploy can be proven live by reading it (Q133).","tags":["system"],"security":[],"responses":{"200":{"description":"The commit sha followed by a newline.","headers":{"Cache-Control":{"description":"Always `no-store`.","schema":{"type":"string"}}},"content":{"text/plain":{"schema":{"type":"string","example":"3ea4d392a63126fbc6433b53bf6aa46899476fd4"}}}}}}},"/v1/me":{"get":{"operationId":"getCurrentPrincipal","summary":"Get the authenticated principal.","description":"Returns the current user (from the Keycloak-issued token or the API key's owner) together with their org memberships. Clients use this to bootstrap the session and resolve which organizations are in scope.","tags":["identity"],"responses":{"200":{"description":"The authenticated principal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Principal"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The credential is valid but is not a user session (e.g. a per-org API key, which has no user principal). Use org-scoped endpoints.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateCurrentPrincipal","summary":"Set this person's language and display currency.","description":"The write path that did not exist — twice, for the same reason, one product surface apart.\n\n`User.locale` has been read by the notification renderer since notifications were built, and until 2026-07-30 exactly one code path in the whole platform ever wrote it — the public guest checkout. Anyone who signed up any other way received every email, notice and notification in English for the lifetime of their account, with no endpoint, no screen and no way to change it, while a fully built 58-locale pipeline sat one field-read away.\n\n`User.currency` had the same shape until 2026-08-04 (#460). The dashboard's currency switcher wrote a cookie plus `localStorage` and made **no server call at all**, so a customer who chose GBP on their laptop saw USD on their phone, and USD again after clearing cookies. `Organization.default_currency` is not that field: it is the tenant's **billing** currency — what a converting trial is charged in — and it belongs to the org because an invoice is issued to an org, while what a person browses in belongs to the person.\n\nRequires only an authenticated user session: this is a person changing a fact about themselves, not an act on an organization, so it carries no permission key.\n\nBoth fields are optional and independent — send the one that changed. Setting either marks it **chosen**, which is not cosmetic in either case. For language, an explicit choice outranks the `locale` claim the identity provider puts on every token. For currency, it outranks the geo/locale inference that runs on every request (docs/29 §3.1). Without that distinction the inference silently re-decides the value on the next request and the bug looks like \"it does not save\".\n\n`name` and `email` are deliberately NOT writable here. Both belong to Keycloak, and a second writable copy in the engine would drift from the identity the tokens are minted against.","tags":["identity"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"locale":{"allOf":[{"$ref":"#/components/schemas/LocaleCode"}],"description":"A code from the language registry, or one of the app-tier languages the dashboard and sign-in speak (`sv`, `is`, `pt-PT` — docs/28 \"App-tier locales\"; e-mail for an app-tier choice is sent in English until the comms catalogues carry it). Case- and region-tolerant on the way in (`PT-BR` and `pt-BR` are the same choice), stored exactly as the catalogues are keyed. A code this platform does not ship is REFUSED rather than accepted and quietly ignored: storing a locale nothing can render means every future message arrives in English and the person has no way to find out why."},"currency":{"allOf":[{"$ref":"#/components/schemas/CurrencyCode"}],"description":"An ISO-4217 code this platform can actually charge in — enabled in the currency registry, presentable by at least one payment gateway, and not policy-blocked. Anything else is REFUSED rather than stored, and the consequence is sharper than the language one: a currency no gateway can capture quotes a price the customer agrees to and then cannot pay, against a cart that has already locked that currency on its first line. `RUB` is the worked example — Stripe lists it, and a GB-settled account cannot settle it."},"analytics_opted_out":{"type":"boolean","description":"Ask not to have your use of the app measured, or ask to be measured again. ⚖️ Owner ruling 2026-08-24 — product analytics in the signed-in app runs on legitimate interest with this switch, not behind a cookie banner.\n\n⛔ Stored on the PERSON, never in a cookie: an opt-out held per browser silently turns itself back on the next time they open the app on another device or clear their cookies, which is a dark pattern with a settings screen in front of it. Both values are accepted without confirmation — a switch that argues back is not a working opt-out."},"marketing_opt_out":{"type":"boolean","description":"\"Don't email me offers and tips\" — the marketing opt-out offered at collection (soft opt-in, PECR reg. 22(3)). `true` opts this person out of marketing from every organisation they belong to, writing the same suppression a one-click unsubscribe writes, so every campaign and lifecycle sequence honours it; `false` opts back in. The app sends it straight after a self-registration and from account settings."}}}}}},"responses":{"200":{"description":"The updated principal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Principal"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"An API key was used; this endpoint needs a user session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The language is not one this platform supports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/me/acquisition-touch":{"post":{"operationId":"recordAcquisitionTouch","summary":"Record where the signed-in customer came from (the app's landing capture).","description":"The dashboard captures `utm_*`, `ref`, `zd_vid` (the product sites' visit id), the referring host and the landing page BEFORE the sign-in hop, and sends them here on the first signed-in page load. This is the only way an app sign-up can be attributed: self-registration provisions the organization inside authentication, which never sees the landing URL (docs/750). Unknown keys are dropped, values are capped, and the landing page is host and path only.\n\nRecorded only against an organization the caller OWNS — a member of someone else's account did not bring it to us — and never under impersonation. A MEMBER who is not the owner (staff, an invited team member) gets `200` with `recorded: false, reason: not_owner` and nothing is written; `403` only for an organization the caller does not belong to at all. The first touch is written once and never overwritten; the last touch is overwritten each time. A capture with nothing attributable (no campaign, affiliate code, visit id or foreign referrer) records nothing and answers `recorded: false, reason: empty` — except the app's DIRECT first visit (`entry: direct`), which is recorded as a first touch only, when the org has none, so the owner's alert reads \"Direct\" instead of \"Unknown\"; it never overwrites a source. The app sends that marker once per organization when it has nothing pending (a browser that already reported another account's landing). On an organization more than a day old it records nothing and answers `reason: late`, so an old \"Unknown\" sign-up is never relabelled \"Direct\". Before recording a direct marker on an org with no first touch, the engine asks Keycloak for the caller's REGISTER event: the app's register redirect URI carries the campaign (`zd_acq`), so a sign-up finished in another browser (the verify-email link) keeps its source, which is then recorded instead of \"Direct\".","tags":["tenancy"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcquisitionTouchRequest"}}}},"responses":{"200":{"description":"Whether a touch was recorded, and why not when it was not.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcquisitionTouchResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/me/overview-shortcuts":{"get":{"operationId":"getOverviewShortcuts","summary":"Get this person's Overview shortcut cards.","description":"The shortcut cards this person pinned to their dashboard Overview, in the order they appear. ⚖️ Owner, 2026-09-11: *\"on the overview screen we should have shortcuts to most-used sections, and the user should be able to select from all the sections and menu items to add their own shortcuts\"*.\n\n⛔ The ids are the dashboard's own navigation ids and are stored OPAQUELY. The section list is built per render from the caller's entitlements, permissions, brand and product lines — roughly 200 entries — so an allow-list in the engine would be correct on the day it was typed and would then start refusing nav entries shipped after it. The client resolves each id against the live tree it is already holding and drops what no longer exists.\n\n⛔ Read `chosen` before rendering. An empty list with `chosen: false` means nobody has ever chosen and the client shows its presets; the identical list with `chosen: true` means this person deliberately removed every card, and the presets must NOT grow back.","tags":["identity"],"responses":{"200":{"description":"The shortcut cards.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OverviewShortcuts"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"An API key was used; this endpoint needs a user session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setOverviewShortcuts","summary":"Replace this person's Overview shortcut cards.","description":"Replaces the whole list. ⛔ `PUT` rather than `PATCH`, and the verb is load-bearing: the ORDER is the preference, so a merge semantic could not express \"move the third card above the first\". Idempotent by construction, so it takes no `Idempotency-Key`.\n\nAn empty list is accepted and is a real choice — it clears the strip and stops the presets coming back. Duplicate ids are REFUSED rather than de-duplicated: two cards for one section is a client bug, and repairing it quietly would leave the customer with one fewer card than they dragged in and nothing to read about why.","tags":["identity"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["shortcuts"],"properties":{"shortcuts":{"$ref":"#/components/schemas/OverviewShortcutIds"}}}}}},"responses":{"200":{"description":"The saved shortcut cards.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OverviewShortcuts"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"An API key was used; this endpoint needs a user session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"An id is not a navigation id, the same section appears twice, or there are more cards than the limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/branding":{"get":{"operationId":"getBranding","summary":"The brand this customer's panel renders under.","description":"The name, logo, colour and links the signed-in customer's dashboard paints itself with — their agency's or reseller's if they are white-labelled, otherwise Zinn®'s.\n\n**Always answers, for every authenticated caller.** An organisation with no brand of its own is not a `404`: it receives the platform identity with `is_white_label: false`. A nullable answer would make every client invent its own fallback, and the second such client is the leak this feature exists to close.\n\nResolved by walking **up** the organisation tree to the org that owns the brand, and gated on the `white_label` entitlement held by that owner — never by the client reading it, who holds no such entitlement and never will.\n\n⛔ Not gated on a permission key. This answers *\"what does your screen look like?\"*, not *\"may you see this data?\"* — the payload is the brand the caller is already looking at. It is still authenticated and org-scoped, so one tenant cannot ask what another tenant's panel looks like.\n\n**`Cache-Control: private, no-store`** — this response is never stored, by any cache, and that is a tenancy requirement rather than a tuning choice. The URL is `/v1/branding` for every tenant and the organisation travels in `X-Zinn-Org`, so a stored copy is keyed on nothing that separates one tenant from the next. It was `private, max-age=60` until 2026-08-26; `private` bounds a stored copy to one browser profile and **does not** bound it to one tenant, and one browser profile is exactly where an organisation switch happens. Measured before the change: four organisations, one token, one second apart, all four answering with the first one's brand.\n\n`Vary: X-Zinn-Org, Authorization` is sent as well, so an intermediary that stores despite `no-store` still cannot serve one tenant's brand to another.","tags":["identity"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Which of the caller's organisations to resolve for. Optional, and only needed by a person who belongs to several. `X-Zinn-Org` stands in for it when it is absent.\n\nAccepts **any organisation in the caller's scope** — their memberships *and every descendant* — which is the same set `GET /v1/orgs` returns and the same set row level security enforces on the request, so it can only ever name an organisation the caller could already read. Until 2026-08-26 it accepted direct memberships only, so naming a client organisation silently resolved the caller's *first* membership instead: a different tenant's brand.\n\nAn id outside that scope is ignored rather than refused — the caller's own brand is returned, so this is never an existence oracle."}],"responses":{"200":{"description":"The resolved brand.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Brand"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/brand":{"get":{"operationId":"getResellerBrand","tags":["reseller"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"summary":"The identity your clients see.","description":"Your brand as your clients see it — the name on their panel, the logo, the accent colour and the help links. Requires `reseller.view`.\n\n⛔ A brand you have not set up yet is a **200 with `configured: false`**, never a 404: the screen renders an empty form either way, and a 404 would make the app decide what \"no brand\" means. `entitled` reports whether white-label is on your plan at all.","responses":{"200":{"description":"Your brand, and whether it is configured and entitled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerBrand"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setResellerBrand","tags":["reseller"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"summary":"Set the identity your clients see.","description":"Creates or updates your brand. Requires `reseller.manage` — reading your brand is a view permission; changing what every one of your clients sees is not.\n\n⛔ **This endpoint is why white-label was unreachable until 2026-08-16.** The resolver, the entitlement gate, the org-tree walk, the e-mail path and the panel painting were all built and correct, and nothing anywhere could create the row they all read — `Brand` held zero rows across the estate.\n\n⛔ `panel_hostname`, `sending_domain` and `sending_domain_verified` are **refused here, with a sentence saying why**, rather than ignored. All three are facts about the outside world this endpoint cannot establish: a hostname nobody serves is a link to nowhere, an unverified sending domain does not deliver, and a verified flag a customer can set is a wish rather than a verification.\n\nRefused with 422 when white-label is not on your plan — storing a brand the resolver would decline to serve is configuration that silently does nothing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerBrandWrite"}}}},"responses":{"200":{"description":"The saved brand.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerBrand"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/boards/brand":{"get":{"operationId":"getBoardsBrand","tags":["agency-board"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"summary":"The branding your shared boards carry.","description":"The name, mark and colour that people opening one of your board share links see — instead of ours. Requires `agency.board.view`.\n\n⛔ A brand you have not set up yet is a **200 with `configured: false`**, never a 404: the screen renders an empty form either way.\n\n⛔ `entitled` is computed on the **shared-board** surface specifically. Boards Business sells branding for shared boards and not platform-wide white-label, so this answers a narrower question than `GET /v1/reseller/brand`'s field of the same name — and answering the wider one here would tell a paying customer their branding does nothing.","responses":{"200":{"description":"Your boards branding, and whether your plan includes it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardsBrand"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setBoardsBrand","tags":["agency-board"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"summary":"Set the branding your shared boards carry.","description":"Creates or updates the identity on your board share links. Requires `agency.board.manage` — reading it is a view permission; changing what everyone you have shared a board with sees is not.\n\n⛔ **This endpoint is why Boards branding bought nothing until 2026-09-15.** The resolver, the entitlement and the shared-board payload were all built and correct, and the only surface that could create the brand row required `reseller.manage` — which a Boards customer has no reason to hold.\n\n⛔ Deliberately narrower than `PUT /v1/reseller/brand`. `panel_hostname` and `sending_domain` are **refused here by name**, as they are there: both are agency capabilities a Boards plan does not include, and both cost real money to provision.\n\nRefused with 422 when branding is not on your plan — storing a brand the resolver would decline to serve is configuration that silently does nothing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardsBrandWrite"}}}},"responses":{"200":{"description":"The saved branding.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardsBrand"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/boards/brand/logo":{"post":{"operationId":"uploadBoardsBrandLogo","tags":["agency-board"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"summary":"Upload the mark your shared boards show.","description":"The image shown beside your name on a board share link. Requires `agency.board.manage`.\n\n⛔ **Save a NAME first.** The brand row carries a not-blank constraint on its name, so an upload before one exists is refused with 422 rather than inventing a placeholder — a placeholder here would be shown to your own clients.\n\n⛔ Its own door rather than `POST /v1/branding/logo`, which demands `reseller.manage` and platform white-label — both correct for a reseller panel mark and both wrong here.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["logo"],"properties":{"logo":{"type":"string","format":"binary","description":"The image. Vetted for type, dimensions and byte size."}}}}}},"responses":{"201":{"description":"The stored mark.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardsBrandLogo"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"removeBoardsBrandLogo","tags":["agency-board"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"summary":"Take the mark off future shared boards.","description":"Clears the mark. Requires `agency.board.manage`.\n\n⛔ The stored bytes are left alone — clearing the digest is what removes it from what visitors see, and deleting bytes to tidy a settings screen changes artefacts that have already been sent.\n\n⭐ Answers 204 even when no brand exists: *\"there is no mark now\"* is true either way, and a 404 would make the screen render an error over a successful outcome.","responses":{"204":{"description":"The mark is off future shared boards."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/branding/logo":{"post":{"operationId":"uploadBrandLogo","tags":["reseller"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"summary":"Upload your logo.","description":"Your logo, as an image file. Requires `reseller.manage`.\n\n⚖️ **Uploaded, never linked** — owner ruling 2026-09-01. We store the image ourselves and serve it from `GET /v1/branding/logo/{sha256}`, and that is what makes it possible to print it on your invoices: an invoice is rendered offline from a frozen copy of the document and cannot fetch anything, so a link to your own web server could never appear on one. It would also mean a document that changes if your site goes down.\n\nSend the file as the `logo` part of a `multipart/form-data` request. PNG, JPEG, WebP and GIF, up to 256 KB and 4000 px on a side. ⛔ SVG is refused: it can carry scripts and remote references.\n\n⛔ Changing your logo does **not** change invoices already issued. Each document keeps the logo it was issued with, because it is referenced by a digest of the exact image.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["logo"],"properties":{"logo":{"type":"string","format":"binary"},"purpose":{"type":"string","enum":["panel","favicon","email"],"default":"panel","description":"Which mark this is. ⚖️ The owner named \"logo\" and \"icon\" separately on 2026-09-03, and mail needs a third: a panel wordmark is unreadable at 32px in a browser tab, and a light-on-dark panel mark disappears against a mail client's white background, which no reader can change.\n\n⭐ One upload door with three destinations rather than three endpoints, so the vetting rules and the byte store cannot diverge between them."}}}}}},"responses":{"200":{"description":"The stored logo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandLogo"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"deleteBrandLogo","tags":["reseller"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"purpose","in":"query","required":false,"schema":{"type":"string","enum":["panel","favicon","email"],"default":"panel"},"description":"Which mark to stop showing. ⛔ Without it \"remove my favicon\" clears the **panel** logo — a destructive off-by-one that a fixture setting only one of the two cannot see, because both end up empty either way."}],"summary":"Stop showing your logo.","description":"Removes the logo from your panel, your sign-in page and future invoices. Requires `reseller.manage`.\n\n⛔ Documents already issued keep theirs, and that is deliberate: a superseded logo is still the logo that was printed on last year's invoice.","responses":{"200":{"description":"The logo is no longer shown.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandLogo"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/branding/logo/{sha256}":{"get":{"operationId":"getBrandLogoFile","tags":["identity"],"summary":"One brand logo, as an image.","description":"The image bytes for a logo digest.\n\n⛔ **Unauthenticated, deliberately.** Its readers are a browser painting a panel, a browser painting a reseller's *sign-in* page — which by definition has nobody signed in — and a client's own panel. Requiring a token would break the login page, which is the surface where a reseller's mark matters most.\n\n⭐ What stands in for authentication is the digest: this is a content-addressed store, so asking for an object means already knowing the sha256 of its exact bytes. There is nothing to enumerate, and the image is one the brand publishes on its own public login page anyway.\n\n⭐ Immutable: the bytes behind a digest can never change, so the response is cacheable for a year and a new logo is simply a new URL.","parameters":[{"name":"sha256","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{64}$"}}],"responses":{"200":{"description":"The image.","content":{"image/png":{"schema":{"type":"string","format":"binary"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/webp":{"schema":{"type":"string","format":"binary"}},"image/gif":{"schema":{"type":"string","format":"binary"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/branding/font/{family}.css":{"get":{"operationId":"getBrandFontCss","tags":["identity"],"summary":"The `@font-face` rules for a self-hosted family.","description":"The stylesheet that installs a brand's chosen Google family — from **our** origin, not Google's.\n\n⛔ **Unauthenticated, deliberately**, and for the same reason as the logo above: a stylesheet is fetched by a `<link>` in a page nobody has signed in to yet, and the branded sign-in screen is the first place it is needed. It discloses nothing — the bytes are a public, OFL-licensed font and the family name is on screen for any visitor.\n\n⭐ Why we serve it at all rather than linking to `fonts.googleapis.com`: that link would send every one of a reseller's clients to a third party on every page load, with their IP address and a `Referer` naming the reseller's hostname, and would need a permanent CSP widening for every panel including those that picked a catalogue font. The family is fetched once, server-side, at install time.\n\n⛔ A family that is not installed is a **404, never an empty 200**. An empty stylesheet renders in the fallback font with nothing red anywhere, and the reseller is told their typeface \"did not work\" with no way to find out why.","parameters":[{"name":"family","in":"path","required":true,"schema":{"type":"string"},"description":"The family name, spaces written as `+`."}],"responses":{"200":{"description":"The `@font-face` rules.","content":{"text/css":{"schema":{"type":"string"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/branding/font-file/{sha256}":{"get":{"operationId":"getBrandFontFile","tags":["identity"],"summary":"One stored webfont file.","description":"The woff2 bytes for a digest. The twin of `GET /v1/branding/logo/{sha256}`, content-addressed for the same reason: the digest is the identity, so the response is cacheable for a year and a different file is a different URL.","parameters":[{"name":"sha256","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{64}$"}}],"responses":{"200":{"description":"The font file.","content":{"font/woff2":{"schema":{"type":"string","format":"binary"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/reseller/brand/font":{"post":{"operationId":"installBrandFont","tags":["reseller"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"summary":"Install a Google font into our own origin.","description":"Send a Google family **name**; we fetch it once, store the woff2 files and serve them from our own hostname. Requires `reseller.manage` and the `white_label` entitlement.\n\n⛔ A separate door from `PUT /v1/reseller/brand`, deliberately: this is the only part of a brand save that makes a network call to a third party, and folding it in would make a typo in a font name refuse a change to your company name.\n\n⭐ Idempotent and shared across the platform. The bytes of *Inter Regular* are the same for everybody and the rows are content-addressed, so the second reseller to install a family costs one query and no egress.\n\n⭐ Four weights are installed — the ones the design system uses. A family can ship eighteen across two axes, and storing all of them would be half a megabyte of rows for weights no component references.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["family"],"properties":{"family":{"type":"string","maxLength":64}}}}}},"responses":{"200":{"description":"The family is installed and ready to select.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandFontInstall"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/brand/menu":{"get":{"operationId":"listBrandMenu","tags":["reseller"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"summary":"Your custom navigation links.","description":"The links you have added to your clients' panel, plus the icons and limits the form needs. Requires `reseller.view`.\n\n⭐ Returns **every** item including staff-only ones, unlike `GET /v1/branding` which filters. That is not an inconsistency: this is your own editing surface and you are the author of every row, so hiding your own configuration from you would make the list disagree with what saving it does.","responses":{"200":{"description":"Your links.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandMenu"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"addBrandMenuItem","tags":["reseller"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"summary":"Add a link to your clients' panel.","description":"Adds one navigation link. Requires `reseller.manage` and the `white_label` entitlement.\n\n⛔ `url` accepts `https://`, `http://` or a same-origin path beginning `/`, and nothing else. Your clients click these from inside an authenticated panel on your hostname, so a `javascript:` link would run in the origin holding their session — the allow-list is what makes that unrepresentable rather than merely filtered.\n\n⛔ Over the limit is a **422 naming the limit**, never a silent truncation at read time: a ninth link that simply never appears is a defect nobody can report.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandMenuItemInput"}}}},"responses":{"201":{"description":"The link was added.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandMenuItem"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/reseller/brand/menu/{item_id}":{"put":{"operationId":"updateBrandMenuItem","tags":["reseller"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"item_id","in":"path","required":true,"schema":{"type":"string"}}],"summary":"Change one link.","description":"Replaces one navigation link. Requires `reseller.manage`.\n\n⛔ Scoped to your own organisation as well as to the id. A `get(pk=…)` would let any reseller edit any other reseller's link by guessing a uuid — and uuid7 is time-ordered, so guessing is less of a barrier than it sounds.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandMenuItemInput"}}}},"responses":{"200":{"description":"The updated link.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandMenuItem"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"deleteBrandMenuItem","tags":["reseller"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"item_id","in":"path","required":true,"schema":{"type":"string"}}],"summary":"Remove one link.","description":"Removes one navigation link from your clients' panel. Requires `reseller.manage`.","responses":{"204":{"description":"The link is gone."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/reseller/brand/invoice":{"get":{"operationId":"getResellerInvoiceBranding","tags":["reseller"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"summary":"How your invoices read.","description":"The footer, payment terms, remittance details and support contact printed on invoices you issue to your clients. Requires `reseller.view`.\n\n⛔ `configured: false` means your clients are still invoiced under Zinn Digital®, so there is nothing to personalise yet.","responses":{"200":{"description":"Your invoice personalisation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerInvoiceBranding"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setResellerInvoiceBranding","tags":["reseller"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"summary":"Set how your invoices read.","description":"Requires `reseller.manage`.\n\n⭐ These are printed on **your** invoices, under your company, your VAT number and your number series — so the payment details are yours. Your clients are charged on your own payment gateway and you are the merchant of record for them.\n\n⛔ **Changing these does not change invoices already issued**, and must not: every value is frozen onto each document when it is raised. Restating where last month's invoice was payable would be a different demand for money under the same number.\n\nRefused with 422 when your clients are still invoiced under Zinn Digital®.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerInvoiceBrandingWrite"}}}},"responses":{"200":{"description":"The saved settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerInvoiceBranding"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/branding/by-panel-hostname":{"get":{"operationId":"getBrandingByPanelHostname","tags":["identity"],"summary":"The brand served on one panel hostname.","description":"The brand behind a reseller's own panel address.\n\n⛔ **Unauthenticated, deliberately, and this is the only endpoint on the API where that is the right answer.** Its caller is the edge Worker rendering a *maintenance page* — which by definition runs when the panel behind it is unreachable, quite possibly because the engine is having a bad time. A credential to fetch would be one more thing to go wrong on the error path, and the Worker has nobody to authenticate as.\n\n⭐ It discloses nothing new: it answers **only for a hostname that is already actively serving that brand's panel**, so everything in the payload is on the screen of anyone who types that address. An unknown or inactive hostname is a `404` with no detail, so it is not an oracle for \"which of these domains is a Zinn® customer\".","parameters":[{"name":"hostname","in":"query","required":true,"schema":{"type":"string","maxLength":253}}],"responses":{"200":{"description":"The brand served on that hostname.","content":{"application/json":{"schema":{"type":"object","required":["name","logo_url","primary_colour","support_url","oidc_client_id","oidc_authority","locales","default_locale","locales_restricted","language_switcher","currency_switcher"],"properties":{"name":{"type":"string"},"logo_url":{"type":"string"},"primary_colour":{"type":"string"},"support_url":{"type":"string"},"locales":{"type":"array","items":{"type":"string"},"description":"The languages this panel offers, so the **sign-in page** can be in one of them. A reseller selling into one market should not have their customers meet an English login form and only get their own language once they are already through it."},"default_locale":{"type":"string","description":"The language the sign-in page opens in."},"locales_restricted":{"type":"boolean","description":"True when the reseller narrowed the list."},"language_switcher":{"type":"boolean","description":"Whether the sign-in page should render a language picker at all."},"currency_switcher":{"type":"boolean","description":"Whether a currency picker should render. No `currencies` list rides on this response: a maintenance or sign-in page prices nothing, so the list would be dead weight on a response served when the estate is already unwell."},"palette":{"type":"object","additionalProperties":{"type":"string"},"description":"The brand's colour tokens, so the **logged-out** sign-in card can paint itself.\n\n⚖️ The owner asked directly on 2026-09-03 whether a visitor sent to a login from a members-only page reaches *\"their branded login and not ours\"*. They did not: the panel's own anonymous card renders above the session, where no authenticated brand lookup can run, so it showed our mark and our product name on a reseller's hostname.\n\n⭐ Served here rather than on a new endpoint because this route is already unauthenticated, already keyed by hostname alone and already fetched before sign-in to resolve the OIDC client. One fetch, one answer — two endpoints could paint one brand's colours under another brand's name."},"font_stack":{"type":"string","description":"A complete CSS `font-family` value, fallbacks included."},"font_css_url":{"type":"string","description":"The self-hosted webfont stylesheet, from our own origin. Empty for a catalogue font."},"nav_position":{"type":"string"},"density":{"type":"string"},"corner_radius":{"type":"string"},"colour_scheme":{"type":"string"},"favicon_url":{"type":"string","description":"The brand's icon, already falling back to its logo."},"oidc_client_id":{"type":"string","description":"The Keycloak client this panel signs in through.\n\n⛔ The panel cannot sign anybody in without it. One build of the dashboard is served on `app.zinndigital.com` and on every reseller's own address, and each panel has its own client — so a `clientId` compiled into the bundle sends the browser to a client that does not name the hostname it is standing on, and Keycloak answers `Invalid parameter: redirect_uri`.\n\n⭐ Disclosing it is safe and is not the tenancy control: a public OIDC client id travels in the query string of every authorisation request the browser makes. What confines a token minted by a reseller's panel to that reseller's own org subtree is the `azp` binding in the engine (`docs/99` §7.7a, D11085).\n\nEmpty when the panel is serving but its client has not been created yet; the caller then falls back to the platform client, which refuses the redirect URI with a message about sign-in."},"oidc_authority":{"type":"string","format":"uri","description":"Where this panel's browser fetches OIDC metadata from — the reseller's **own** hostname, not ours.\n\n⛔ **This is what keeps our name out of the address bar during sign-in** (#2990). The edge Worker serves Keycloak's `/realms/` and `/resources/` paths under the panel hostname and rewrites the absolute URLs Keycloak emits; but the SPA decides where to send the browser, and its compiled-in authority is `auth.zinndigital.com`. Without this field a reseller's customer still watches the address bar turn into ours for the whole of the one page they cannot avoid.\n\n⭐ The tokens themselves are unchanged and still carry `iss: https://auth.zinndigital.com/realms/<realm>` — `KC_HOSTNAME` stays pinned, which is what makes the change safe. The discovery document's `issuer` is deliberately **not** rewritten so that it agrees with them.\n\nEmpty when the panel is not actively serving; the caller then uses the platform authority, which works — only the address bar is worse."}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/brand/sending-domain":{"post":{"operationId":"attachResellerSendingDomain","tags":["reseller"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"summary":"Send your clients' e-mail from your own domain.","description":"Registers a sending domain and returns the DNS records to publish. Requires `reseller.manage`.\n\n⛔ **This is the largest single white-label leak and no template change could close it.** Everything inside a notification was already resolved to your brand — the name, the call-to-action link — while the envelope still read `Zinn Digital® Billing <billing@zinndigital.com>`, which is the line your client actually looks at.\n\n⛔ Attaching does **not** switch the sender. Publish the records, then call `/verify`; only a successful verification moves your mail onto your domain, because mail from an unverified domain does not arrive.\n\nA domain is already attached ⇒ `409`. Remove it first — replacing it silently would orphan the previous one at the provider.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandSendingDomainWrite"}}}},"responses":{"201":{"description":"Registered. Publish the records it returns.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandSendingDomain"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"delete":{"operationId":"removeResellerSendingDomain","tags":["reseller"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"summary":"Stop sending from your own domain.","description":"Releases the domain at the mail provider and reverts your clients' e-mail to the platform sender. Requires `reseller.manage`.\n\n⛔ If the provider will not release it this is a `503` and **nothing is changed** — clearing our side anyway would leave the domain registered there with nothing here pointing at it, so you could neither re-add it (it is taken) nor remove it (we forgot the id).","responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/reseller/brand/sending-domain/verify":{"post":{"operationId":"verifyResellerSendingDomain","tags":["reseller"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"summary":"Check your sending domain's DNS now.","description":"Asks the mail provider to re-check your DNS and returns what it found. Requires `reseller.manage`.\n\n⛔ The answer is the provider's, read back **after** the check rather than assumed from the trigger — \"verifying\" reads as progress and \"still pending\" reads as wait, and only one of them is true while your DNS is still propagating.","responses":{"200":{"description":"The provider's current view.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandSendingDomain"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/reseller/brand/panel-hostname":{"post":{"operationId":"attachResellerPanelHostname","tags":["reseller"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"summary":"Claim your own address for your clients' panel.","description":"Records a CLAIM on the hostname and returns the TXT record that proves you control it. Nothing reaches the edge and no certificate is requested yet (za-24). Requires `reseller.manage`.\n\nYour clients sign in at your address instead of ours — the address bar is what they look at on every single login, and it is the largest remaining piece of white-label.\n\n⛔⛔ Publish the `TXT` record in `claim.records`, then call `/verify`: only a proven claim is registered at the edge, which then hands back the `CNAME` to publish. This is what stops another account taking over a hostname whose old CNAME still points at us. Claiming the same hostname again keeps its token; a claim never proven is forgotten after 30 days, and a proven one is attached by the hourly sweep even if you never press verify.\n\nA hostname inside a domain Zinn® operates is refused with `422`, and a hostname is already attached ⇒ `409`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandPanelHostnameWrite"}}}},"responses":{"202":{"description":"Claimed. Publish the TXT record in `claim.records`, then verify.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandPanelHostname"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"delete":{"operationId":"removeResellerPanelHostname","tags":["reseller"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"summary":"Stop serving your clients' panel on your own address.","description":"Removes the edge route and the custom hostname, and reverts your clients to the platform panel address — or, when only a claim is pending, withdraws the claim. Requires `reseller.manage`.","responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/reseller/brand/panel-hostname/verify":{"post":{"operationId":"verifyResellerPanelHostname","tags":["reseller"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"summary":"Prove your claim, or check whether your panel address is serving.","description":"With a claim pending: reads the claim's TXT record from a public resolver and, when it carries the token, registers the hostname at the edge (`201`, with the `CNAME` to publish). The record missing ⇒ `422` naming it; the resolver not answering ⇒ `503` and nothing changes. An account not in good standing ⇒ `422 NOT_IN_GOOD_STANDING`. A hostname another panel already holds ⇒ `409`, refused before the edge is asked. If the hourly check attached the proven claim a moment earlier, `200` with the attached hostname — it is never registered twice.\n\nWith a hostname attached: asks the edge for its status **and fetches the URL**, and only says yes when both agree. Requires `reseller.manage`.\n\n⛔ The edge's own `active` is not the answer. Measured 2026-08-17: a custom hostname reached `active` with a valid certificate for the customer's name and returned **HTTP 522** to every visitor, because a certificate is not a route. Trusting the status word would have put a dead link in every one of that reseller's clients' e-mail.\n\n`errors` carries the edge's own words when it is not progressing.","responses":{"200":{"description":"What we measured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandPanelHostname"}}}},"201":{"description":"Ownership proven; registered at the edge. Publish the `CNAME` it returns.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandPanelHostname"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/reseller/nameservers":{"get":{"operationId":"getResellerNameservers","tags":["reseller"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"summary":"Your own nameserver brand.","description":"The nameserver brand your clients' domains are delegated to, and the glue records you must register for it. Requires `reseller.view`.\n\nA reseller who has never set one up gets an empty payload rather than a `404` — the screen has to render on the first visit.","responses":{"200":{"description":"What you have.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerNameservers"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setResellerNameservers","tags":["reseller"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"summary":"Claim a domain for your own nameservers.","description":"From `acme-hosting.com` we build `ns1.acme-hosting.com` and `ns2.acme-hosting.com`, served from Zinn Digital®'s own anycast DNS estate. Requires `reseller.manage` and white-label on your plan.\n\n⛔ Claiming serves **nothing** yet. The glue records live in *your* domain, at *your* registrar, so only you can create them — publish the `A` records this returns, then call `/verify`. Until that measurement passes, your clients' zones keep the platform nameservers, because delegating a live domain to a nameserver that does not answer takes that domain off the internet.\n\nA domain Zinn® already operates is refused with `422`; a domain another reseller already holds ⇒ `409`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerNameserversWrite"}}}},"responses":{"201":{"description":"Claimed. Register the glue records it returns.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerNameservers"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"removeResellerNameservers","tags":["reseller"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"summary":"Give back your nameserver brand.","description":"New zones revert to the platform nameservers. Requires `reseller.manage`.\n\n⚠️ Zones already delegated to your hostnames are **not** re-delegated by this call — their delegation lives at each client's registrar. Remove the glue at your own registrar only once those have moved.","responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/nameservers/verify":{"post":{"operationId":"verifyResellerNameservers","tags":["reseller"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"summary":"Check whether your nameservers answer.","description":"Looks your hostnames up on the public internet and confirms they resolve to our anycast addresses. Requires `reseller.manage`.\n\n⛔ This is the only thing that turns `serving` on, and `serving` is what lets a real client zone be delegated to you.\n\n⛔ `checked` is `false` when our resolver could not answer. That is **not** \"your glue is missing\" — nothing is changed, and the two send you to opposite actions.","responses":{"200":{"description":"What we measured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerNameservers"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/customers":{"post":{"operationId":"linkPartnerCustomer","tags":["partner"],"summary":"Link (or create) the organization for one of your own customers.","description":"Idempotent on `external_id` — your own id for that customer. An email we do not know gets a new organization under yours, with a billing profile and no members; an email that already has a Zinn Digital® account is **never** taken on your say-so and answers `409`, recording a consent request the customer answers in their own account. Requires `partner.domains`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCustomerCreate"}}}},"responses":{"201":{"description":"The link.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCustomer"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/customers/{externalId}":{"parameters":[{"$ref":"#/components/parameters/PartnerExternalId"}],"get":{"operationId":"getPartnerCustomer","tags":["partner"],"summary":"Read one of your customers' links.","description":"The organization you may act on, the state of the link, and whether a registrant contact is on file yet. A customer of another partner is a `404`, never a `403`. Requires `partner.domains`.","responses":{"200":{"description":"The link.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCustomer"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/customers/{externalId}/registrant":{"parameters":[{"$ref":"#/components/parameters/PartnerExternalId"}],"put":{"operationId":"setPartnerCustomerRegistrant","tags":["partner"],"summary":"Set the ICANN registrant this customer's domains are registered with.","description":"Stored once per customer and carried onto every registration you place for them. A registration cannot be made without it — the registrar refuses a domain with no registrant — so an order is refused until it is set. Requires `partner.domains`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerRegistrant"}}}},"responses":{"200":{"description":"The link, now carrying a registrant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCustomer"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/customers/{externalId}/registrant-email-reminders":{"parameters":[{"$ref":"#/components/parameters/PartnerExternalId"}],"post":{"operationId":"reportPartnerRegistrantEmailReminder","tags":["partner"],"summary":"Report a reminder you sent your customer about an unconfirmed registrant e-mail.","description":"When a customer's registrant e-mail is unconfirmed at the registrar you receive a `domain.registrant_email_flagged` event on `/v1/partner/events` carrying `registrant_email`, `deadline_at` (when the registry suspends the names), `suspended`, `domain_count` and `domains`. Remind your customer, then report each reminder here so our staff can see that it went, and when — rather than assume it. Recorded, never sent on to the customer. When every listed name reads verified at the registrar you receive `domain.registrant_email_confirmed` (same fields) once: stop reminding. Requires `partner.domains`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerRegistrantReminder"}}}},"responses":{"201":{"description":"Recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerRegistrantReminderRecorded"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/customers/{externalId}/holder-verifications":{"parameters":[{"$ref":"#/components/parameters/PartnerExternalId"}],"get":{"operationId":"listPartnerHolderVerifications","tags":["partner"],"summary":"Your customer's nic.at holder verifications.","description":"The same cases the customer sees in their dashboard (see `listHolderVerifications`). You also receive every step as `domain.holder_verification.*` events on your webhook and `/v1/partner/events`. Requires `partner.domains`.","parameters":[{"name":"state","in":"query","required":false,"schema":{"type":"string","enum":["open","all"],"default":"open"}}],"responses":{"200":{"description":"The verifications.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HolderVerificationList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/customers/{externalId}/holder-verifications/{caseId}":{"parameters":[{"$ref":"#/components/parameters/PartnerExternalId"},{"$ref":"#/components/parameters/HolderVerificationCaseId"}],"get":{"operationId":"getPartnerHolderVerification","tags":["partner"],"summary":"One of your customer's holder verifications.","description":"Requires `partner.domains`.","responses":{"200":{"description":"The verification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HolderVerification"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/customers/{externalId}/holder-verifications/{caseId}/documents":{"parameters":[{"$ref":"#/components/parameters/PartnerExternalId"},{"$ref":"#/components/parameters/HolderVerificationCaseId"}],"post":{"operationId":"uploadPartnerHolderDocument","tags":["partner"],"summary":"Upload one holder document for your customer (PDF, JPEG or PNG, 10 MB at most).","description":"Identical checks and storage to `uploadHolderVerificationDocument`. Requires `partner.domains`.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["kind","file"],"properties":{"kind":{"$ref":"#/components/schemas/HolderDocumentKind"},"file":{"type":"string","format":"binary"}}}}}},"responses":{"201":{"description":"Stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HolderVerification"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/partner/customers/{externalId}/holder-verifications/{caseId}/submit":{"parameters":[{"$ref":"#/components/parameters/PartnerExternalId"},{"$ref":"#/components/parameters/HolderVerificationCaseId"}],"post":{"operationId":"submitPartnerHolderVerification","tags":["partner"],"summary":"Hand your customer's documents to our verification team.","description":"Refused with `422` until every required kind is uploaded. Requires `partner.domains`.","responses":{"200":{"description":"Submitted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HolderVerification"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/customers/{externalId}/domain-orders":{"parameters":[{"$ref":"#/components/parameters/PartnerExternalId"}],"post":{"operationId":"createPartnerDomainOrder","tags":["partner"],"summary":"Place a domain order for one of your customers, unpaid.","description":"Prices every line from our catalogue, re-verifies every availability token and places the order `pending_payment`. A line may be a registration or, with `kind: domain_transfer` and the `auth_code`, a transfer-in of a name held at another registrar — checked and priced exactly as `POST /v1/domains/transfer/preflight` quotes it, and refused with that check's reason when it is not eligible. ⛔ Nothing is charged here and no payment method is touched: the customer pays on the hosted page named by `pay_url`, and their browser is sent back to `return_url` (or `cancel_url`) with only `?order=<human_ref>&status=paid` (or `cancelled`) appended. Both URLs must be `https` on a host allowlisted for your programme, matched exactly — anything else is a `422` and no order is placed. `pay_url` carries a secret that is stored nowhere and shown only in this response; it lives 24 hours. `Idempotency-Key` is **required** — a retry returns the same order with a fresh `pay_url` rather than buying the name twice. Requires `partner.domains`.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerDomainOrderCreate"}}}},"responses":{"201":{"description":"The placed, unpaid order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerOrder"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"description":"The body failed validation, a business rule refused the order (`error.details[].code`), or (`error.code` `REGISTRY_DATA_REQUIRED`, Q10) a domain's registry demands fields the item's `registry_data` did not carry — one `details[]` entry per `domain` + `field` + `code`; read `getTldRequirements` for what each extension needs, fill them in, retry. Nothing is placed and the customer is never sent to pay.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/customers/{externalId}/domain-orders/{orderId}":{"parameters":[{"$ref":"#/components/parameters/PartnerExternalId"},{"name":"orderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getPartnerDomainOrder","tags":["partner"],"summary":"Read one of your customer's domain orders, and each domain it became.","description":"The authoritative state of an order you placed — its status, and for every line the domain's own status, nameservers and expiry once provisioning has created it (`domain` is `null` until then). An order of another customer, of another partner, or one the customer placed themselves is a `404`. There is no `pay_url` here: the link is shown once, when the order is placed. Requires `partner.domains`.","responses":{"200":{"description":"The order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerOrder"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/customers/{externalId}/hosting-orders":{"parameters":[{"$ref":"#/components/parameters/PartnerExternalId"}],"post":{"operationId":"createPartnerHostingOrder","tags":["partner"],"summary":"Place a hosting order for one of your customers, unpaid.","description":"The hosting twin of `createPartnerDomainOrder`, with the same safety properties: the order is priced from our catalogue and placed `pending_payment`, nothing is charged and no payment method is touched, and the customer pays on the hosted page named by `pay_url` (a secret shown only in this response, alive 24 hours). `return_url` and `cancel_url` follow the same allowlist rules. `Idempotency-Key` is **required** — a retry returns the same order with a fresh `pay_url`.\n\n**Plan and term.** Name the plan by `plan_code` (or `plan_version_id`) from `listInAppCatalogPlans`. `term_months` is 1, 3, 6 or 12 on every plan, and what it costs is one rule: a **published interval that covers the term wins** (12 months on a plan with an `annual` price is that price), otherwise the term is **N months of the monthly price, with no discount** — the same arithmetic a prepayment on an existing subscription uses. A plan we hold no price for in `currency` is a `422` with `details[0].code = term_not_priced`; we never convert. Prices are per currency: the order is priced in `currency`, never in the first entry of a plan's `prices` array.\n\nA prepaid term (3, 6, or 12 where no annual price exists) is charged in full here and delivered as the subscription's first period plus a prepayment covering the rest, so the customer's RENEWAL price stays the monthly one. Every line carries its own `term_months` and `currency` so a partner can reconcile the charge against the quote it showed.\n\n**Site.** `site` names the site to create once the order is PAID: order fulfilment creates it in the customer's organization on the subscription this order buys, with the chosen application, and `getPartnerHostingOrder` then returns its id. The hostname, application, stack and region are all checked before anything is placed. **`site` may be omitted entirely** (sell the plan now, add the site later) and **`site.domain` may be omitted** — we mint a temporary address on our own preview domain, return it as `site.domain` with `temporary_domain: true`, and build the site on it, so a customer can start before their own domain points at us. Your key never gains `sites.manage` or `billing.payment.manage` in the customer's organization.\n\n**Add-ons.** `addons` carries codes from `listCatalogAddons`; each must be sold on the plan's product line and priced in `currency`. Refusals carry a stable `details[0].code` (`plan_unknown`, `plan_not_hosting`, `plan_not_fulfillable`, `term_not_priced`, `term_unknown`, `app_required`, `app_unknown`, `region_unknown`, `region_unavailable`, `site_domain_taken`, `addon_unknown`, `addon_not_offered`, `addon_currency`, `return_url_not_allowed`, `not_linked`).\n\n**`plan_not_fulfillable`**: the plan's deploy target has no usable provisioning connection right now, so a paid order could not be built — refused before any order exists. It clears itself when the plan can be provisioned again.\n\n**Card-free trial (`trial: true`, `hosting_orders.version` 5).** Starts the SAME card-free, never-billed trial a direct sign-up gets, on a plan whose `hosting_orders.trial.plans[].trial_days` is above 0 (open your trial choice on `hosting_orders.trial.served`). The order is priced at **0**, settles at once with no payment step (the response carries **no** `pay_url`), and fulfilment starts the trial and builds the `site`, if one was named. The trial is never converted and never charged automatically: at `trial.ends_at` the customer is told it ended, at `trial.cutoff_at` the trial ends and its site is suspended, and nothing is ever billed. To keep the site, the customer subscribes — you place an ordinary paid order for `trial.subscribe.plan_code` with **no** `site` and send them its `pay_url`; once paid, the trial converts and its site is moved onto the paid plan (and resumed if it had been suspended). That works before `ends_at`, during the grace window and after `cutoff_at`. Eligibility is the direct rule — **one trial per customer, ever** — plus: no add-ons on a trial order, and no trial on a product line the customer already pays for. Refusals: `trial_not_offered`, `trial_already_used`, `trial_already_subscribed`, `trial_addons`, `trial_limit` (a per-partner daily ceiling on new trials; retry tomorrow), `trial_domain_used` (the `site.domain` — or its www/apex twin, in any case — has already had a trial on any account). A paid order may name the trial it converts in `trial_id`; see that field for `trial_subscribe_other_line` and `trial_not_convertible`.\n\n**Checkout refusals always carry a code and checkout's own sentence** (2026-10-20). A refusal raised while placing is answered 422 with `details[0].code` and its customer-readable `message`: `billing_country_required` (with `field: billing_country`: send the country the customer is billed in), `registrant_required`, `availability_stale`, otherwise `order_not_placed` with checkout's own reason - never a generic sentence without a code.\n\n**Several plans (`hosting_orders.version` 7, ADR 0036).** A customer may hold ANY number of plan subscriptions, on any product line and several on the same one; a paid order ADDS a plan and never cancels or supersedes another. To change a plan instead, name the one it replaces in `replaces_subscription_id` (see that field); nothing else replaces anything. **`region_unknown` / `region_unavailable`**: `region` (top level or on `site`) is not a data centre we run, or is one with no box able to take this plan's site today. A region is never accepted and ignored; omit it for our default location, and read `getPartnerCapabilities` for the ones an order is accepted for.\n\n`lines` are in a fixed order: the plan line first, then the add-ons. Requires `partner.domains`.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerHostingOrderCreate"}}}},"responses":{"201":{"description":"The placed, unpaid order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerHostingOrder"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/customers/{externalId}/hosting-orders/{orderId}":{"parameters":[{"$ref":"#/components/parameters/PartnerExternalId"},{"name":"orderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getPartnerHostingOrder","tags":["partner"],"summary":"Read one of your customer's hosting orders, and the site it became.","description":"The authoritative state of a hosting order you placed: its status, the subscription the paid plan became (`subscription_id`, `null` until fulfilment), and — when the order carried a `site` — the site's id and status once fulfilment has created it, or `error` with the reason it could not be. A trial order also carries `trial`: its status, its `ends_at` and `cutoff_at`, and the plan to subscribe to. A domain order, another customer's or another partner's order is a `404`. There is no `pay_url` here. Requires `partner.domains`.","responses":{"200":{"description":"The order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerHostingOrder"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/customers/{externalId}/addon-orders":{"parameters":[{"$ref":"#/components/parameters/PartnerExternalId"}],"post":{"operationId":"createPartnerAddonOrder","tags":["partner"],"summary":"Place an add-on order for one of your customer's existing sites, unpaid.","description":"The hosting order with the plan taken away, and the same safety properties: priced from our catalogue in `currency`, placed `pending_payment`, nothing charged and no payment method touched; the customer pays on the hosted page named by `pay_url` (a secret shown only in this response). `return_url` and `cancel_url` follow the same allowlist rules. `Idempotency-Key` is **required** — a retry returns the same order with a fresh `pay_url`.\n\n**Site.** `site_id` is one of the customer's sites. Its **product line** decides what may be sold — the same rule a hosting order applies to its plan's line, from the same resolver, and the one `listCatalogAddons` publishes (`product_lines`, `excluded_product_lines`). Once paid, each add-on is created for THAT site and delivered by the same fulfilment a purchase in the customer's dashboard uses; `getPartnerAddonOrder` then returns each line's `purchase_id` and `purchase_status`.\n\n**Refusals** carry a stable `details[0].code`: `site_unknown` (no such site, or not one you can reach), `site_not_yours` (it belongs to another customer of yours — a crossed reference on your side), `site_unavailable` (being deleted, deleted, or never built), `not_in_good_standing` (the customer holds no active hosting to add to), `addons_required`, `too_many_addons`, `addon_unknown`, `addon_not_offered` (not sold on this site's product line, or a website slot for a line the customer has no plan on), `addon_currency`, `return_url_not_allowed`, `not_linked`. The set is published in `getPartnerCapabilities` as `hosting_orders.addon_order_refusal_codes`. There is no per-add-on quantity: a repeated code is bought once. Requires `partner.domains`.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerAddonOrderCreate"}}}},"responses":{"201":{"description":"The placed, unpaid order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerAddonOrder"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/customers/{externalId}/addon-orders/{orderId}":{"parameters":[{"$ref":"#/components/parameters/PartnerExternalId"},{"name":"orderId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getPartnerAddonOrder","tags":["partner"],"summary":"Read one of your customer's add-on orders, and what each add-on became.","description":"The authoritative state of an add-on order you placed: its status and, per line, the purchase fulfilment created once it was paid (`purchase_id`, `purchase_status`; `null` until then). A hosting or domain order, another customer's or another partner's order is a `404`. There is no `pay_url` here. Requires `partner.domains`.","responses":{"200":{"description":"The order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerAddonOrder"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/orders/{orderId}/cancel":{"parameters":[{"name":"orderId","in":"path","required":true,"description":"**Our** order id, as returned in `order_id` when the order was placed — not your own reference. Keyed this way deliberately: it works for every order that already exists, including ones placed before you began sending a reference of your own.","schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"cancelPartnerOrder","tags":["partner"],"summary":"Cancel an order of yours that has not been fulfilled.","description":"Stops an order you placed that has **not** been paid for and **not** been fulfilled — the stale rows left behind by verification and abandoned checkouts. Requires `partner.domains`.\n\n**It never moves money.** An order that has been paid is refused, not refunded: a refund is a separate, deliberate conversation. This is enforced by the order lifecycle itself, which has no transition from a paid state to a cancelled one, and not merely by this endpoint.\n\n**It is not a subscription control.** It cannot end a subscription, stop a renewal or tear down anything already provisioned. A verb that did both is how somebody eventually ends a paying customer's hosting while meaning to tidy a test order.\n\n**It is idempotent.** Cancelling an order that is already cancelled is a `200` carrying the current state, not a refusal, so a retry after a timeout is safe.\n\n**Refusals are machine-readable** under `error.details[].code` — `error.code` is the HTTP class and is not what you branch on:\n- `not_yours` — the order exists in a customer's org you can reach, but you did not\n  place it (it is the customer's own, or another partner's). Alert your staff; it means\n  a reference has been crossed somewhere on your side.\n- `already_paid` — money has moved. This is a refund conversation, not a cancellation.\n  An order that is mid-fulfilment reports this too: the money is the harder half to\n  undo.\n- `already_fulfilled` — at least one line has been delivered. A registered domain\n  cannot be un-registered, so the whole call is refused rather than half-applied — an\n  order whose state did not describe reality would fail your reconciliation for ever.\n  When a *line* is the cause, that detail entry carries `field: \"lines\"` and names the\n  domain in its own **`domain`** key. Branch on `domain`, never on the text of\n  `message`: the sentence is translated and its wording is not part of this contract.\n\n\nAn order id that does not exist, or one you have no reach into at all, is a `404` carrying `details[].code = unknown_reference`. The two cases are deliberately indistinguishable: telling you that an id exists but is out of your reach would report on other tenants' data.","responses":{"200":{"description":"The order, as it now stands. Returned both when this call cancelled it and when it was already cancelled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerOrder"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/customers/{externalId}/sites/{siteId}/resources":{"parameters":[{"$ref":"#/components/parameters/PartnerExternalId"},{"name":"siteId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getPartnerSiteResources","tags":["partner"],"summary":"Read a customer's site's resource tier, boost level, usage and the boosts it can buy.","description":"What one of your customer's sites runs on (`docs/866`): the rung its plan gives (`plan_tier`), the boost level it holds, its current limits, what it USED in the last 24 hours (`usage_24h`, `null` when metrics are unavailable — never a zero), the boost that sets the level (`held`), and every boost level that would lift it higher (`offers`; empty at the top tier). Order an offer's `code` on `createPartnerAddonOrder`. Another customer's site is a `404`. Requires `partner.domains`.","responses":{"200":{"description":"The site's resources.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerSiteResources"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/customers/{externalId}/boosts/{purchaseId}/cancel":{"parameters":[{"$ref":"#/components/parameters/PartnerExternalId"},{"name":"purchaseId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"cancelPartnerBoost","tags":["partner"],"summary":"Remove a customer's performance boost at the end of its paid month.","description":"The partner twin of `cancelBoostPurchase`: the boost keeps working until `ends_at` (the end of its paid month), then the site drops back to its plan's limits; nothing is refunded. `purchaseId` is the boost's id — `getPartnerSiteResources.held.id`, or the `purchase_id` on the order line that bought it. **It cannot touch a plan**: only a performance-boost purchase is accepted (`422 not_a_boost` otherwise), and a subscription is not a purchase. Refusals (`details[0].code`): `not_a_boost`, `not_owned` (another of your customers), `already_cancelled` (removal already scheduled), `already_ended`; an id you cannot reach is a `404`. Requires `partner.domains`.","responses":{"200":{"description":"The boost will stop renewing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoostCancelResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/customers/{externalId}/trials/{trialId}/cancel":{"parameters":[{"$ref":"#/components/parameters/PartnerExternalId"},{"name":"trialId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"cancelPartnerTrial","tags":["partner"],"summary":"End a card-free trial you started, now.","description":"Ends a trial you started with `createPartnerHostingOrder` `trial: true` (the id is `trial.trial_id` on `getPartnerHostingOrder`). The trial goes `canceled` at once, its site stops serving and its deletion is scheduled, and nothing is billed before or after. The response is the trial ORDER: its `trial.status` reads `canceled`; the order's own `status` stays `completed`, because a settled $0 order is a historical fact. Repeating the call is safe and returns the same body. Refusals, `details[0].code`: `not_owned` (a `404` — not a trial you started for this customer), `already_converted` (it became a paid plan: cancel the subscription instead), `already_ended` (past its cut-off; its site is already stopped). Open this on `hosting_orders.trial.cancel`. Requires `partner.domains`.","responses":{"200":{"description":"The trial order, with `trial.status` `canceled`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerHostingOrder"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/customers/{externalId}/subscriptions/{subscriptionId}/cancel":{"parameters":[{"name":"externalId","in":"path","required":true,"description":"Your own id for the customer, as linked with `createPartnerCustomer`.","schema":{"type":"string"}},{"name":"subscriptionId","in":"path","required":true,"description":"**Our** subscription id — the `subscription_id` a fulfilled hosting order reports on `getPartnerHostingOrder`.","schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"cancelPartnerSubscription","tags":["partner"],"summary":"Cancel a linked customer's subscription at the end of its paid period.","description":"Turns renewal **off** for a subscription you sold the customer. It is exactly the customer's own renewal switch in our dashboard (`setSubscriptionAutoRenew` with `auto_renew: false`): the plan **stays active until `current_period_end`**, keeps every entitlement until then, and then ends on its own. Nothing is torn down by this call. Requires `partner.domains`.\n\n**It never moves money.** No refund is issued. A body carrying `refund: true` is refused with `refund_not_offered` and **nothing is changed** — ask us about a refund separately.\n\n**It is idempotent.** Cancelling a subscription whose renewal is already off is a `200` carrying the current state, not a refusal, so a retry after a timeout is safe.\n\n**Refusals are machine-readable** under `error.details[].code` — `error.code` is the HTTP class and is not what you branch on. The set is published live as `subscriptions.cancel_refusal_codes` on `getPartnerCapabilities`:\n- `not_yours` — the subscription is in your linked customer's org, but it was not bought\n  through you (the customer bought it themselves, or through another partner). The\n  customer can stop it from their own dashboard.\n- `already_ended` — the subscription is `canceled` or `expired`; there is nothing to\n  cancel.\n- `renews_on_paypal` — the customer moved this subscription onto a PayPal agreement, and\n  PayPal, not us, takes the next payment. Turning our flag off would not stop PayPal\n  charging, so we refuse rather than answer `200`. The customer cancels the agreement in\n  PayPal; the subscription then ends at the end of its period.\n- `refund_not_offered` — you asked for a refund. Nothing was changed. - `not_applied` — the cancellation could not be recorded and nothing was changed. Safe\n  to retry.\n\n\nA customer, subscription or link that does not exist, is not active, or is out of your reach is a `404` carrying `details[].code = unknown_reference`. The cases are deliberately indistinguishable: telling them apart would report on other tenants' data.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerSubscriptionCancel"}}}},"responses":{"200":{"description":"The subscription as it now stands — `auto_renew: false` and `ends_at` set to the end of the paid period. Returned both when this call turned renewal off and when it was already off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerSubscription"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/customers/{externalId}/hosting-slots":{"parameters":[{"$ref":"#/components/parameters/PartnerExternalId"}],"get":{"operationId":"listPartnerHostingSlots","tags":["partner"],"summary":"How many sites each of your customer's hosting plans can still take.","description":"One row per product line the customer holds a site-hosting plan on. `max_sites`, `used_sites` and `free_sites` come from the SAME function that refuses a site create when a plan is full, so a row with `free_sites > 0` is one `createPartnerSiteMove` will accept. Every site that is not yet deleted counts as used — including one that failed to build and one being deleted. A customer on a free TRIAL has a row too (`kind: trial`): its `subscription_id` is the trial's id, which `createPartnerSiteMove` accepts as `subscription_id`. `replaceable_sites` lists the sites a move may import into instead of taking a free slot, each with `replaceable_reason`: `temporary_host` (still on a temporary address of ours) or `empty_starter` (the site the plan or trial was delivered with, on the customer's own domain, never imported into — the move re-checks that it is still empty and refuses with `replace_site_not_empty` if it is not). `available_sites` is `free_sites` plus the replaceable ones: the number to decide on whether a move can be offered. A plan that cannot take an imported site is listed with `importable: false` so you can say why. Requires `partner.domains`.","responses":{"200":{"description":"The customer's hosting slots.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerHostingSlots"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/customers/{externalId}/site-moves":{"parameters":[{"$ref":"#/components/parameters/PartnerExternalId"}],"get":{"operationId":"listPartnerSiteMoves","tags":["partner"],"summary":"Your customer's site moves, newest first.","description":"Every move you started for this customer, newest first, in the same shape as `getPartnerSiteMove`. Requires `partner.domains`.","responses":{"200":{"description":"The moves.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerSiteMoveList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createPartnerSiteMove","tags":["partner"],"summary":"Move one of your customer's sites onto their money-site hosting, from an archive.","description":"Starts an asynchronous move of ONE site into the customer's hosting plan (docs/808 §12). Nothing is charged: the move spends a site slot the customer already pays for. The call is validated and answered at once (`202`); the work runs as a durable workflow and is read back with `getPartnerSiteMove`.\n\n**The archive.** `archive_url` is an `https` link our hosting box downloads directly (never through this API): a `.tar.gz` (or `.zip`) holding the document root under `www/` and, for a site with a database, a MySQL dump named `dump.sql` at the top level — the V1 backup layout. The link must answer without cookies and must survive a `HEAD` plus up to three `GET`s (a retried download fetches again). `archive_sha256` is checked on the box before anything is applied; a mismatch fails the move with `archive_checksum_mismatch` without touching the site.\n\n**The site.** It is created in the customer's organization on the plan named by `subscription_id`, on `domain`, with `app` (a key from `getPartnerCapabilities` `site_moves.plans[].apps`). Or pass `replace_site_id` — one of `listPartnerHostingSlots` `replaceable_sites` — to import into that empty site and move it onto `domain` instead of taking a new slot. `domain` may be the replaced site's own name (an `empty_starter` is built on the customer's real domain); that is not `domain_in_use`. A replaced `empty_starter` that has content on it when the move starts fails with `replace_site_not_empty`, and nothing on it is touched. The domain's DNS is never touched: it keeps pointing where it points until you repoint it, and it may stay in your (or your customer's) Cloudflare for good. A subdomain whose apex is somebody else's live site is fine.\n\n**Refusals** (`422`, `details[0].code`): `no_free_slot`, `subscription_not_found`, `app_not_supported_by_plan`, `plan_cannot_import`, `domain_invalid`, `domain_in_use`, `archive_url_invalid`, `archive_checksum_invalid`, `replace_site_not_replaceable`, `move_already_running`, `idempotency_key_required`, `moves_not_open`, `no_capacity`, `dns_invalid`, `not_linked`. There is **no size limit** (D28455): room is made for a large archive, and the move is slower, never refused. ⚖️ **A full plan does not refuse a move** (row 1107#13, owner 2026-11-07): the site lands past the plan's site limit and is **frozen** (served, but read-only, no cron, no mail) until the customer upgrades or frees a slot, when it unfreezes by itself within about ten minutes (the quota sweep). `no_free_slot` is returned only past the hard cap of `max(10 × the plan's sites, sites + 9)`.\n\n**DNS (contract v2).** `dns` says where the zone is held and who changes it: with `auto_switch: true` YOU repoint the record when the move reaches `step: ready_to_switch` (then call go-live); otherwise the customer is shown and e-mailed the exact records, the change is detected automatically, and the move goes live on its own. A retry with the same `Idempotency-Key` returns the same move. Requires `partner.domains`.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerSiteMoveCreate"}}}},"responses":{"202":{"description":"The move, accepted and queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerSiteMove"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/customers/{externalId}/site-moves/{moveId}":{"parameters":[{"$ref":"#/components/parameters/PartnerExternalId"},{"$ref":"#/components/parameters/PartnerSiteMoveId"}],"get":{"operationId":"getPartnerSiteMove","tags":["partner"],"summary":"Read one site move — its status, preview address and origin target.","description":"The authoritative state of a move. `status` is `queued`, `importing`, `imported`, `going_live`, `live`, `failed` or `cancelled`. At `imported` the site is built on our hosting and `preview_url` serves it without any DNS change (compare it against the original before you switch); `origin` names what the domain's web record must point at. At `live` the domain is served from our hosting over HTTPS — **only then** delete the original. `error_code` and `error` explain a `failed` move; a go-live attempt that could not yet see the switch leaves the move `imported` with `error_code: dns_not_pointed`. Requires `partner.domains`.","responses":{"200":{"description":"The move.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerSiteMove"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/customers/{externalId}/site-moves/{moveId}/go-live":{"parameters":[{"$ref":"#/components/parameters/PartnerExternalId"},{"$ref":"#/components/parameters/PartnerSiteMoveId"}],"post":{"operationId":"goLivePartnerSiteMove","tags":["partner"],"summary":"Tell us the domain now points at our origin; we confirm it and secure it.","description":"Call after you have repointed the domain's web record at `origin` (proxied through Cloudflare with SSL \"Full\" is fine). Accepted only from `imported` (`422` `move_not_ready` otherwise). The move goes to `going_live` while we prove, from the public internet, that requests for the domain reach our box, and obtain its certificate; then `live`. If the switch is not visible within the attempt, the move returns to `imported` with `error_code: dns_not_pointed` and you may call this again. Idempotent: calling it while `going_live` or `live` returns the move unchanged. Requires `partner.domains`.","responses":{"202":{"description":"The move, now going live.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerSiteMove"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/customers/{externalId}/site-moves/{moveId}/cancel":{"parameters":[{"$ref":"#/components/parameters/PartnerExternalId"},{"$ref":"#/components/parameters/PartnerSiteMoveId"}],"post":{"operationId":"cancelPartnerSiteMove","tags":["partner"],"summary":"Abandon a move that has not gone live, and give the slot back.","description":"Stops the move and removes the site it built on our hosting at once — it never served the customer's domain, so there is nothing to keep — which frees the slot. A move that replaced an empty site leaves that site where it is. A `live` move cannot be cancelled (`422` `move_is_live`); a `failed` or `cancelled` one is returned unchanged, except that a failed move's half-built site is removed the same way. Requires `partner.domains`.","responses":{"200":{"description":"The move, cancelled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerSiteMove"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/customers/{externalId}/site-moves/{moveId}/retry":{"parameters":[{"$ref":"#/components/parameters/PartnerExternalId"},{"$ref":"#/components/parameters/PartnerSiteMoveId"}],"post":{"operationId":"retryPartnerSiteMove","tags":["partner"],"summary":"Re-run a failed move from where it failed.","description":"Accepted only when the move says `retryable: true` — it failed after its site was built (`archive_unreachable`, `archive_checksum_mismatch`, `import_failed`, `preview_not_serving`, `health_check_failed`), so the slot is already spent. Send a new `archive_url` + `archive_sha256` when the old link may have expired. Anything else is `422 move_not_retryable`: start a new move. Same move id, a new attempt. Requires `partner.domains`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerSiteMoveRetry"}}}},"responses":{"202":{"description":"The move, queued again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerSiteMove"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/customers/{externalId}/panel-invite":{"parameters":[{"$ref":"#/components/parameters/PartnerExternalId"}],"post":{"operationId":"invitePartnerCustomerToPanel","tags":["partner"],"summary":"Give your customer a way into their own control panel.","description":"Invites the e-mail address the customer is linked with to their organization as its owner, and returns `accept_url` — send it in your own message. They sign in or sign up with that address and land in their panel; the verified e-mail is the authorisation, so the link is not a secret. A customer who already belongs to the organization gets `status: already_member` and the panel address. Repeating the call returns the same pending invitation. Requires `partner.domains`.","responses":{"200":{"description":"The invitation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerPanelInvite"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/customers/{externalId}/panel-access":{"parameters":[{"$ref":"#/components/parameters/PartnerExternalId"}],"get":{"operationId":"getPartnerCustomerPanelAccess","tags":["partner"],"summary":"Whether your customer can sign in to their control panel yet.","description":"Read-only. `member` is true once a user with the e-mail the customer is linked with belongs to the customer's organization. `invitation` is the newest control-panel invitation for that e-mail (`expired` when a pending one has passed its `expires_at`), or null when none was ever sent — send `panel-invite`. `panel_url` is the address the customer bookmarks. Requires `partner.domains`; an unknown or inactive customer is 404. Not audited (it changes nothing).","responses":{"200":{"description":"The customer's panel access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerPanelAccess"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/customers/{externalId}/panel-sessions":{"parameters":[{"$ref":"#/components/parameters/PartnerExternalId"}],"post":{"operationId":"createPartnerCustomerPanelSession","tags":["partner"],"summary":"One-click sign-in to your customer's own control panel.","description":"Returns a URL that signs the customer straight into their own control panel — send their browser there at once. The single-use ticket rides in the URL fragment (never in a server log) and must be redeemed within 300 seconds; the session lasts one hour, is confined to the customer's organization, and can be ended at any time. With `site_id` the session opens on that site. The dashboard presents it as the customer's own sign-in (\"Signed in from\" the partner's name), never as a staff session. Audited as `partner.panel_session.issued` (the URL is never audited). Only for a customer whose organization YOU created (`created_org`): one who linked an account they already had is `422` `not_delegable`. `409` `no_account_holder` until the customer has accepted their invitation (see `panel-access`, `panel-invite`). An unknown customer, or a `site_id` outside their organization, is `404`. `503` when sign-in grants are not configured. Requires `partner.domains`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerPanelSessionRequest"}}}},"responses":{"201":{"description":"The sign-in link.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerPanelSession"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/partner/customers/{externalId}/sites/{siteId}/wp-login":{"parameters":[{"$ref":"#/components/parameters/PartnerExternalId"},{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"createPartnerCustomerSiteWpLogin","tags":["partner"],"summary":"One-click WordPress admin for your customer's site.","description":"Mints the same short-lived, single-use, site-bound WordPress sign-in as the customer's own \"WordPress admin\" button (`wpLogin`) — same preflight, same token, same audit row (`site.wp_login.issued`, recording the partner and `external_id`; the token and URL are never audited). Send the customer's browser to `url` at once: the token expires in about two minutes and works once. Only for a customer whose organization YOU created (`created_org`); one who linked an account they already had is refused `422` `not_delegable`. A site outside the customer's organization, or an unknown customer, is `404`. `422` for a site that is not WordPress/WooCommerce, `409` for one that is not serving or not reachable, and `409` with `details[].code` `move_in_progress` (a move into the site is not `live` yet, so its domain still opens the original copy) or `import_in_progress` (an import into it has not finished); `503` when one-click login is not configured. Requires `partner.domains`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WpLoginRequest"}}}},"responses":{"201":{"description":"The grant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WpLoginGrant"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/partner/customers/{externalId}/sites/{siteId}/upgrade-to-php":{"parameters":[{"$ref":"#/components/parameters/PartnerExternalId"},{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"upgradePartnerCustomerSiteToPhp","tags":["partner"],"summary":"Upgrade your customer's static HTML site to PHP hosting, in place.","description":"The partner door to `upgradeSiteToPhp`. A static HTML site becomes a PHP site IN PLACE, with no downtime (owner brief, queue Q111). On our servers every site's web server already runs PHP, so nothing is copied, re-placed or re-pointed: the site's stack becomes `php`, its PHP version the plan's default (or `php_version`, when the plan offers it) and the PHP tuning follows in the next maintenance pass. `422` with `details[].code` `SITE_NOT_STATIC` (already PHP, WordPress or another stack), `SITE_NOT_ACTIVE` (still setting up), `STATIC_ON_EDGE_HOST` (published to an edge host that cannot run PHP: move it onto our servers first) or `PHP_VERSION_NOT_OFFERED`. Audited as `hosting.site.upgrade_to_php`. A site outside the customer's organization, or an unknown customer, is `404`. Requires `partner.domains`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteStackUpgradeRequest"}}}},"responses":{"200":{"description":"The site, now PHP.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteStackUpgrade"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/partner/capabilities":{"get":{"operationId":"getPartnerCapabilities","tags":["partner"],"summary":"What the partner surface supports right now — probe this to open or close a checkout.","description":"Every value is DERIVED from the code that enforces it, never typed: `terms` and `term_discount_bps` are the pricing table the cart charges from; `refusal_codes` is the set a hosting order can be refused with (the raise path refuses any other), and `refuses_unfulfillable` / `region` say whether `plan_not_fulfillable` / the region refusals are among them; `plans` lists every site-hosting plan with `orderable` and `regions` from the SAME functions `createPartnerHostingOrder` refuses on — so a plan or region published here is accepted there, and one that is not is refused. `version` changes when the hosting-order contract does. Requires `partner.domains`.","responses":{"200":{"description":"The capabilities.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCapabilities"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/customers/{externalId}/consent-request":{"parameters":[{"$ref":"#/components/parameters/PartnerExternalId"}],"post":{"operationId":"requestPartnerCustomerConsent","tags":["partner"],"summary":"Ask a customer who already has an account again for their consent.","description":"E-mails the owners of the organization that address owns a single-use link to accept or decline your access; the first request is sent automatically when linking answers `409`. Asking again retires the previous link. At most one request every 15 minutes and five a day per customer (`429` with `Retry-After`). A customer who declined cannot be asked again (`422`). `503` means the e-mail could not be sent and no link is live. Requires `partner.domains`.","responses":{"202":{"description":"The request was e-mailed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerConsentSent"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/partner/events":{"get":{"operationId":"listPartnerEvents","tags":["partner"],"summary":"Poll what happened to your customers' orders and domains.","description":"Oldest first by the time each event was written, strictly after `after` (the `next_cursor` of your previous page; omit it to start from the beginning). Event ids are NOT time-ordered, so never compare them yourself: the cursor is the only position. An `after` that is not an event this feed served you is a `422`. Only customers whose link is `active` are included; order events cover only orders you placed; domain events cover every domain in a linked organization. Events are released 30 seconds after they are written so a slow transaction cannot land behind your cursor — delivery is at least once, so de-duplicate on `id`. A page can be shorter than `limit` and still have `has_more: true`. Webhooks ARE offered — see `/v1/partner/webhooks` — and this feed remains the authoritative catch-up behind them. Requires `partner.domains`.","parameters":[{"name":"after","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"One page of events.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerEventPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/marketplace/withdrawals":{"post":{"operationId":"createPartnerMarketplaceWithdrawal","tags":["partner"],"summary":"Take V1-imported marketplace listings off sale now.","description":"For the V1 platform only (a partner on the engine's V1 partner list; any other partner gets `403`). Send the V1 slugs of listings V1 has stopped publishing — a removed listing, or every listing of a banned seller. Each matching `source=v1` listing is archived in the request (it leaves search, the storefront and the API at once); its cached storefront pages are then purged and submitted to IndexNow. Signed: send `X-Zinn-Timestamp` (unix seconds, within 300 s) and `X-Zinn-Signature` (`sha256=` + hex HMAC-SHA256, keyed with your webhook subscription's signing secret, over `v1-marketplace-withdrawal.` + timestamp + `.` + the raw body). Idempotent: a listing already off sale is reported in `already_gone`. A push that is lost is caught by a sweep every 10 minutes. Requires `partner.domains`.","parameters":[{"name":"X-Zinn-Timestamp","in":"header","required":true,"schema":{"type":"string","pattern":"^[0-9]+$"}},{"name":"X-Zinn-Signature","in":"header","required":true,"schema":{"type":"string","pattern":"^sha256=[0-9a-f]{64}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerMarketplaceWithdrawalRequest"}}}},"responses":{"200":{"description":"What was taken off sale.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerMarketplaceWithdrawalResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/webhooks":{"get":{"operationId":"listPartnerWebhooks","tags":["partner"],"summary":"Your webhook subscriptions, and every event type you may ask for.","description":"The push half of `/v1/partner/events`. The poll feed remains the authoritative catch-up — a webhook is a convenience, and delivery is at least once, so de-duplicate on the event `id` (also sent as `X-Zinn-Delivery`). Never returns a signing secret. Requires `partner.domains`.","responses":{"200":{"description":"Your subscriptions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerWebhookList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createPartnerWebhook","tags":["partner"],"summary":"Subscribe an endpoint to your customers' events.","description":"Returns the signing secret ONCE — store it before you close the response. The subscription starts `unverified` and receives only a signed verification POST; answer it 2xx and it becomes `active`. Every POST carries `X-Zinn-Signature` (`sha256=` HMAC over `\"<X-Zinn-Timestamp>.<raw body>\"`), `X-Zinn-Delivery` and `X-Zinn-Event`. Re-subscribing an endpoint you already have re-keys and re-verifies it. Requires `partner.domains`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerWebhookCreate"}}}},"responses":{"201":{"description":"Subscribed. The signing secret is in this body and nowhere else.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerWebhook"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/webhooks/{subscriptionId}":{"parameters":[{"name":"subscriptionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"delete":{"operationId":"deletePartnerWebhook","tags":["partner"],"summary":"Stop delivering to an endpoint and forget its signing secret.","description":"A subscription belonging to another partner and one that never existed are the same 404. Requires `partner.domains`.","responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner-consents/{token}":{"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","maxLength":64}}],"get":{"operationId":"getPartnerConsent","tags":["partner"],"summary":"Read a partner's request to act for your organization.","description":"For the signed-in person who followed the link in the consent e-mail. The token names the request and authorises nothing by itself: only a direct member of the organization it asks about, who already holds `org.update` and every permission the partner would receive there, may read or answer it — anyone else, including a member of a parent organization or an impersonated session, is a `403`. An unknown, expired, superseded or answered link is a `404`.","responses":{"200":{"description":"The request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerConsent"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"answerPartnerConsent","tags":["partner"],"summary":"Accept or decline a partner's request to act for your organization.","description":"`accept` lets the partner register domains in this organization (each order paid by you on our payment page), manage their DNS and nameservers and see its sites, domains and invoices; `decline` is final for that partner. The link works once. The same membership rule as reading it applies.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["decision"],"properties":{"decision":{"type":"string","enum":["accept","decline"]}}}}}},"responses":{"200":{"description":"The answer was recorded.","content":{"application/json":{"schema":{"type":"object","required":["state","partner"],"properties":{"state":{"type":"string","enum":["active","declined"]},"partner":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/orgs":{"get":{"operationId":"listOrganizations","summary":"List organizations in scope.","description":"Lists the organizations the principal can access, walking the tenancy tree. Cursor-paginated. RLS guarantees no organization outside the principal's subtree is ever returned (CLAUDE.md §2.3). A signed-in person who can read no organization — an invitee who has not accepted yet — receives an empty list, never a 403.","tags":["tenancy"],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"type","in":"query","required":false,"description":"Filter by organization type.","schema":{"$ref":"#/components/schemas/OrgType"}}],"responses":{"200":{"description":"A page of organizations.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createOrganization","summary":"Create an organization.","description":"Creates a child organization under the caller's org (reseller creating a client, etc.). Send an `Idempotency-Key` so retries never create duplicates (docs/09 §2).","tags":["tenancy"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationCreate"}}}},"responses":{"201":{"description":"The created organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/orgs/{orgId}":{"parameters":[{"$ref":"#/components/parameters/OrgId"}],"get":{"operationId":"getOrganization","summary":"Get an organization.","description":"Returns a single organization the principal can access. RLS-scoped.","tags":["tenancy"],"responses":{"200":{"description":"The organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"renameOrganization","summary":"Rename an organization.","description":"⛔ Deliberately narrow: only `name`. `type`, `parent_org_id` and `default_currency` are **not** editable here — re-parenting moves a whole billing relationship and is `tenancy.offboarding`'s job. ⭐ The currency is not un-changeable, it simply is not a patchable field: it has its own route, `POST /v1/orgs/{orgId}/billing-currency` (`changeOrganizationBillingCurrency`), because re-denominating converts the wallet and re-prices live subscriptions rather than writing one column. This description read \"a currency change would leave stored prices and issued invoices denominated in something the org no longer claims (#501)\" until 2026-08-31, which was true of a patch and was read as *\"it cannot be done\"*. Requires `org.update` **on that org**; an org you cannot reach answers 404 rather than 403, the same as the GET, so this is never an existence oracle.","tags":["tenancy"],"parameters":[{"name":"orgId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationRename"}}}},"responses":{"200":{"description":"The renamed organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"closeOrganization","summary":"Close an organization.","description":"Closes the account: re-parents its client orgs to Zinn® (D-W15-11), tears every one of its own sites down through the ordinary `SiteTeardownWorkflow` (so they land in `DeletedSite` and stay restorable for the whole retention window), and **keeps its domains renewing** (D-W15-12). It also **switches renewal off on every one of the org's own subscriptions** and cancels any PayPal agreement, so a closed organization is never charged again: each paid period runs out and the subscription expires, with no refund or proration. Its still-active trials are **cancelled** (`trials_canceled`), so a closed organization is never counted as trialling. Its DNS zone records are deleted (`dns_zones_deleted`). Requires `org.delete` **on that org** — held by the customer `owner` and by `super_admin`, so this is a customer's own decision as well as a staff one.\n\n⛔ **An org that owes money is suspended, never torn down** (D-W15-13): the balance check runs first, performs the suspension itself, and answers **409**. Closing is not a route out of an unpaid invoice.\n\n⛔ Answers **200 with the result**, not 204: `failures` is what says a run was partial and left the org OPEN for a retry, and the counts are what an operator reconciles a vendor invoice against.","tags":["tenancy"],"responses":{"200":{"description":"What the closure did. A non-empty `failures` means the org is still open.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClosureResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/orgs/{orgId}/privacy/exports":{"parameters":[{"$ref":"#/components/parameters/OrgId"}],"get":{"operationId":"listPrivacyExports","summary":"List this organization's personal-data exports.","description":"GDPR Art. 15/20 (`docs/1100`). The newest 20 exports, newest first. Requires `org.delete` on that org — the customer `owner` — because an export is the whole account.","tags":["tenancy"],"responses":{"200":{"description":"The exports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrivacyRequestList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"requestPrivacyExport","summary":"Ask for a machine-readable copy of all of this organization's data.","description":"Starts a durable workflow that writes a zip of JSON Lines — one file per kind of record, every org-scoped table, plus the org's members — read under the org's own RLS scope. Credentials and key material are written as `[redacted]`. The archive can be downloaded for 7 days and is then deleted. Needs a sign-in from the last five minutes (`403 STEP_UP_REQUIRED` otherwise). An export already building or ready from the last 24 hours is returned with **200** instead of starting another; a new one answers **202**. If the workflow cannot be started the request is refused with **503**, never left pending.","tags":["tenancy"],"responses":{"200":{"description":"An export from the last 24 hours, returned instead of a new one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrivacyRequest"}}}},"202":{"description":"The export was started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrivacyRequest"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/orgs/{orgId}/privacy/exports/{requestId}/download":{"parameters":[{"$ref":"#/components/parameters/OrgId"},{"name":"requestId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"createPrivacyExportDownloadLink","summary":"A signed, 15-minute download link for a ready export.","description":"Mints a presigned URL straight to object storage (never proxied). The URL is a credential: it is returned once, never logged or stored, and expires after 15 minutes — ask again for a fresh one while the export is within its 7 days. Audit-logged as `privacy.export.downloaded`. Needs a recent sign-in. **409** when the export is not ready or has expired.","tags":["tenancy"],"responses":{"200":{"description":"The link.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrivacyDownloadLink"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/orgs/{orgId}/privacy/erasure":{"parameters":[{"$ref":"#/components/parameters/OrgId"}],"get":{"operationId":"getPrivacyErasure","summary":"This organization's most recent erasure request, if any.","tags":["tenancy"],"responses":{"200":{"description":"The latest erasure request (or `null`) and the cooling-off period.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrivacyErasureState"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"requestPrivacyErasure","summary":"Ask for this organization's account to be erased (GDPR Art. 17).","description":"Double confirmation — `confirm_name` must equal the organization's name exactly AND `acknowledge` must be `true` (**422** otherwise) — plus a sign-in from the last five minutes (`403 STEP_UP_REQUIRED`). Every renewal stops **now**, so nothing is billed after the request. The erasure runs after the cooling-off period (14 days) unless it is cancelled: the account is closed through the ordinary closure (sites torn down, client orgs re-parented), members who belong to no other org are pseudonymised and deleted from the identity provider, and contact details and free text in every other org-scoped record are overwritten. Invoices, credit notes, payments, orders and subscriptions are tax records and are kept unaltered until `retain_until` (10 years after the year of the last invoice), as the law requires. An org with an unpaid balance is refused (**409**). A request already scheduled is returned with **200**.","tags":["tenancy"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrivacyErasureCreate"}}}},"responses":{"200":{"description":"The erasure already scheduled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrivacyRequest"}}}},"202":{"description":"The erasure was scheduled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrivacyRequest"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/orgs/{orgId}/privacy/erasure/{requestId}/cancel":{"parameters":[{"$ref":"#/components/parameters/OrgId"},{"name":"requestId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"cancelPrivacyErasure","summary":"Cancel a scheduled erasure during its cooling-off period.","description":"No step-up: cancelling only undoes. Renewals stopped at the request stay stopped — turn automatic renewal back on in Billing. **409** once the erasure has started or finished.","tags":["tenancy"],"responses":{"200":{"description":"The cancelled request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrivacyRequest"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/orgs/{orgId}/billing-currency":{"parameters":[{"$ref":"#/components/parameters/OrgId"}],"post":{"operationId":"changeOrganizationBillingCurrency","summary":"Change what this organization is invoiced in.","description":"⚖️ Owner ruling 2026-08-31 (W37-V). A customer may re-denominate their own organization. Three things happen and they are deliberately different:\n\n1. **Invoices already issued are frozen.** An invoice is a legal document with a number; its currency, FX stamps and tax treatment stay as issued, for ever. ⚠️ An invoice that is still DUE keeps its old currency and will be collected in it — `invoices_left_in_old_currency` reports how many, so the screen can say so rather than let the customer discover it on a bill.\n\n2. **Live subscriptions re-price from the CATALOGUE**, not by FX-converting the locked price. The catalogue's per-currency price is the number a page displayed and the business chose; a converted one would be invented and would drift on every rate move. A subscription whose plan has no price in the target currency is left in its original currency and counted in `subscriptions_unpriced` — never zeroed.\n\n3. **Wallet credit is converted** at the day's rate, per purse, as a draw-down in the old currency plus a grant in the new sharing one reference. Credit is held per `(org, currency)` and currencies are never mixed, so leaving it would strand real money the customer could no longer spend.\n\n⛔ A dedicated route rather than a field on `PATCH /v1/orgs/{orgId}`: a rename writes one column, this moves money. It requires `billing.payment.manage` — the person who may correct a typo in the account name is not necessarily the person who may re-denominate the balance. An org you cannot reach answers 404, not 403.\n\n⭐ Send `dry_run: true` to get exactly these numbers **without** applying anything. The preview runs the real conversion inside a transaction it then rolls back, so it cannot disagree with the commit.","tags":["tenancy"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingCurrencyChange"}}}},"responses":{"200":{"description":"What the change did, or would do when `dry_run` was set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingCurrencyChangeResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/orgs/{orgId}/closure-plan":{"parameters":[{"$ref":"#/components/parameters/OrgId"}],"get":{"operationId":"getOrganizationClosurePlan","summary":"What closing this organization would do.","description":"A **pure read** — opens no transport, arms no workflow, writes nothing — computed by the same function `DELETE /v1/orgs/{orgId}` runs, so the summary a customer confirms is the plan that then executes.\n\n⛔ Gated on `org.delete`, not `org.read`: the plan is a complete inventory of the account (every site, every client org, every retained domain) plus what it owes.","tags":["tenancy"],"responses":{"200":{"description":"The closure plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClosurePlan"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites":{"get":{"operationId":"listSites","summary":"List sites in scope.","description":"Lists the sites the principal can view across its tenancy subtree. Cursor-paginated. RLS guarantees no site outside the principal's subtree is ever returned (CLAUDE.md §2.3).\n\nSites with status `deleted` are **not** listed by default — they are a terminal state with their own endpoint, `GET /v1/sites/deleted`, which also reports how long each one stays recoverable. Pass `status=deleted` explicitly to list them here. Every other status, including `deleting`, is listed as normal.","tags":["hosting"],"parameters":[{"$ref":"#/components/parameters/ActiveOrg"},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"org_id","in":"query","required":false,"description":"Restrict to one organization in scope (default — the whole subtree).","schema":{"$ref":"#/components/schemas/Uuid"}},{"name":"status","in":"query","required":false,"description":"Filter by site lifecycle status. Omitted, every status except `deleted` is returned; pass `deleted` to list deleted sites here rather than at `GET /v1/sites/deleted`.","schema":{"$ref":"#/components/schemas/SiteStatus"}},{"name":"product_line","in":"query","required":false,"description":"Filter by product line code (e.g. `footprint_free`, `mainstream`).","schema":{"type":"string","maxLength":64}},{"name":"group","in":"query","required":false,"description":"Restrict to the sites in one site group (#2729). A group id belonging to another tenant matches nothing and returns an empty page rather than a 404 — the queryset is already narrowed to the caller's organisations, so answering \"not found\" would confirm the id exists somewhere.","schema":{"type":"string","format":"uuid"}},{"name":"server","in":"query","required":false,"description":"Restrict to the sites on one server — a `key` from `listSiteServers` (and from each row's `server.key`): `own:<uuid>`, `panel:<uuid>`, `fleet:<region>-<n>`, or one of `edge`, `external`, `unplaced`, `managed`. Returns exactly the rows whose `server.key` is that key (D43). A value that is not a key is refused with 422 rather than ignored; a well-formed fleet name that names no box returns nothing.","schema":{"type":"string","maxLength":80}},{"name":"search","in":"query","required":false,"description":"Case-insensitive substring match on the site's primary domain or its name. Applied in the database across the whole collection in scope — not to the page already fetched — so a match on the 200th site is found from the first page.","schema":{"type":"string","maxLength":253}},{"name":"ordering","in":"query","required":false,"description":"Sort key, optionally `-`-prefixed for descending. Defaults to `-created` (newest first). Sorting is applied across the whole collection and the cursor carries the sort position, so paging a sorted list is exact. An unrecognised key is a 422, never a silent fall back to the default.","schema":{"type":"string","default":"-created","enum":["domain","-domain","name","-name","status","-status","line","-line","stack","-stack","region","-region","plan","-plan","created","-created","authority","-authority","indexed","-indexed","da","-da","pa","-pa","spam","-spam"]}},{"name":"min_da","in":"query","required":false,"description":"Only sites whose newest Moz Domain Authority is at least this. s1014 MOZ-V2. A site Moz has not measured is excluded by any bound on that metric (not measured is never 0). Applied across the whole collection.","schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"max_da","in":"query","required":false,"description":"Only sites whose newest Moz Domain Authority is at most this. s1014 MOZ-V2. A site Moz has not measured is excluded by any bound on that metric (not measured is never 0). Applied across the whole collection.","schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"min_pa","in":"query","required":false,"description":"Only sites whose newest Moz homepage Page Authority is at least this. s1014 MOZ-V2. A site Moz has not measured is excluded by any bound on that metric (not measured is never 0). Applied across the whole collection.","schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"max_pa","in":"query","required":false,"description":"Only sites whose newest Moz homepage Page Authority is at most this. s1014 MOZ-V2. A site Moz has not measured is excluded by any bound on that metric (not measured is never 0). Applied across the whole collection.","schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"min_spam","in":"query","required":false,"description":"Only sites whose newest Moz Spam Score (percent) is at least this. s1014 MOZ-V2. A site Moz has not measured is excluded by any bound on that metric (not measured is never 0). Applied across the whole collection.","schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"max_spam","in":"query","required":false,"description":"Only sites whose newest Moz Spam Score (percent) is at most this. s1014 MOZ-V2. A site Moz has not measured is excluded by any bound on that metric (not measured is never 0). Applied across the whole collection.","schema":{"type":"integer","minimum":0,"maximum":100}}],"responses":{"200":{"description":"A page of sites.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createSite","summary":"Create a site.","description":"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).\n\n**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).\n**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.\n\n**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`).","tags":["hosting"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCreate"}}}},"responses":{"201":{"description":"The created site, awaiting provisioning.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Site"}}}},"400":{"description":"`panel_connection_id` does not agree with where this site is going to run.\n\n`PANEL_CONNECTION_REQUIRED` — the site resolved to a control-panel target (`plesk`) and named no panel. There is no default: the connection is the only thing that says *which* box the site lives on, so a panel site created without one would be unreachable rather than merely incomplete.\n\n`PANEL_CONNECTION_NOT_APPLICABLE` — a panel was named for a target that has none. Refused rather than ignored, because a `201` here would tell a caller who believes they are building on their own panel that they succeeded and hand them a site somewhere else.\n\n⭐ Both refer to the **resolved** target, which is usually decided by the plan rather than by the `deploy_target` field — so a request that names no target at all can legitimately receive either. Both cite `panel_connection_id` in `error.details`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"The `panel_connection_id` names no panel in the organization the site is being created in.\n\n⛔ A `404` and deliberately not a `403`, with wording identical to a panel id that does not exist anywhere: confirming that a panel exists is itself a cross-tenant disclosure, so \"not yours\" and \"no such thing\" are indistinguishable from outside. It is also returned for a panel elsewhere in your own account tree — one panel connection is administrator over every site on the same box, so a site may only be placed on a panel belonging to its **own** organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The `primary_domain` is not available (another site uses it, or another organisation holds that domain or a domain it sits under; the answer does not say which), an `Idempotency-Key` was reused with a different body, or a request with that `Idempotency-Key` is still in flight (retry once it settles).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation (`UNPROCESSABLE_ENTITY`), or the site is not covered by a plan. `PLAN_REQUIRED` — nothing grants hosting in the owning org or its `parent_org` chain, so the customer must choose a plan. `SITE_QUOTA_EXCEEDED` — a plan is in force and its `max_sites` allowance is fully used, so the customer must move tier or delete a site. Both quota codes carry `max_sites`, `sites_in_use` and (when a plan was found) `entitling_org_id` in `error.details` — omitted in full when the governing plan belongs to an org outside the caller's scope (#566), so `error.details` may legitimately be absent on a `SITE_QUOTA_EXCEEDED`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; retry after the indicated delay. In addition to the standard limits, **rejected duplicate-domain attempts are separately budgeted**: a `409` reveals that a hostname is hosted on the platform (in some tenant), so repeatedly asking is treated as enumeration and is cut off well before it becomes useful. Successful creates are NOT charged against this budget, so bulk provisioning is unaffected.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sites/provider-options":{"get":{"operationId":"getSiteProviderOptions","summary":"List the options available for a new site.","description":"What a customer may choose on `POST /v1/sites`: `cdn_vendor` / `dns_vendor`, `stack_type` and `source`. The vendors are answered from the provider-account pool serving this organization — its own (BYO) accounts when it has any, otherwise the platform pool — so the picker can never offer a vendor the site would then fail to provision on. The CDN answer is `managed: false` on every line today, Footprint-Free included (owner ruling, 2026-09-09): the customer picks the **vendor** and the platform picks the **account**, spreading their sites across the pool without disclosing which account any of them landed on. `separates_sites` says whether a given vendor can deliver that spread at all, and `dns.allowed_by_cdn` carries the whole CDN→DNS pairing rule so the picker can re-filter without another request.\n\n`stacks` and `sources` answer the same question for the other two pickers — only what this deployment can actually build. Note there is deliberately **no** `runtime`: it is derived from the stack, not chosen.\n\nOn our own fleet a Node-runtime stack (`node`, `headless_cms`) is listed only when the product line has a published blueprint for it — provisioning reads the Node version from that blueprint — and `POST /v1/sites` refuses the same stack with a `422` on `stack_type` (D26530).","tags":["hosting"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"The organization to answer for. Defaults to the caller's first org in scope; an org outside scope is a `404` rather than a `403`, so this cannot be used to probe which organizations exist.","schema":{"$ref":"#/components/schemas/Uuid"}},{"name":"product_line","in":"query","required":false,"description":"The product line the site will be created on. Decides whether the CDN choice is platform-managed; omit for the unmanaged answer.","schema":{"type":"string","maxLength":64}},{"name":"cdn_vendor","in":"query","required":false,"description":"The CDN the customer has chosen, which **narrows the DNS answer**. Choosing Cloudflare restricts DNS to Cloudflare: its edge proxies a record in place inside its own authoritative zone, so a site fronted by Cloudflare whose DNS lives elsewhere has no mechanism by which the edge could see a request.\n\nA value this organization has no CDN account for is **ignored**, not an error — this endpoint populates a picker, and narrowing the DNS list on the strength of a typo would hide vendors the customer really has. The refusal for a genuinely unavailable choice belongs to `POST /v1/sites`, which names the field. Ignored entirely on a managed line, where the platform's own default applies instead.","schema":{"type":"string","maxLength":64}},{"name":"subscription_id","in":"query","required":false,"description":"The subscription the site will be created under, exactly as `createSite` takes it. Its plan decides the deploy target, and the target decides which `stacks` can run (#6071). Omitted, the organization's governing subscription for `product_line` is used, as the create does. A subscription the create would refuse falls back to our own fleet here; the refusal is the create's to report.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The vendors available to this organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteProviderOptions"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/sites/own-dns-preflight":{"post":{"operationId":"preflightOwnDns","tags":["hosting"],"summary":"Check, read-only, whether a domain's DNS can be published on your own DNS account.","description":"The create wizard's check for *publish DNS on my own Cloudflare/DNS account*, run before anything is provisioned. Three reads, nothing written to the account: the organization has an active DNS connection; its key lists the zone the domain lives in and its last permission report shows record edit passing; and the domain's public nameservers are the ones that account assigned. `ok` is the only passing verdict; every other `code` names the fix in `message`. The organization is the body `org_id` or the `X-Zinn-Org` header. Requires `sites.create`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","maxLength":253,"example":"example.com"},"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"The pre-flight verdict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OwnDnsPreflight"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/export":{"get":{"operationId":"exportSites","summary":"Download the sites in scope as a CSV.","description":"The same sites `listSites` would return for the same query, as a streamed `text/csv` attachment — V1 parity (`deploy.views.SiteExport`, \"Choose sites → Export to CSV\"), recorded as unported in `docs/35` §0.3c until W29-U.\n\n⛔⛔ **Server-side over the WHOLE matching set, and that is the point of it existing as an endpoint at all.** `listSites` is cursor-paginated, so a CSV assembled in the browser would contain one page and would look exactly like a complete file — no error, no truncation marker, and nothing a customer could use to tell the difference. There is deliberately **no `limit`**: a bound here would silently exclude rows and nothing downstream would ever pick up the remainder.\n\n⛔ It shares the list's filter chain rather than reproducing it, so \"export\" means \"export what I am looking at\" by construction. Every filter below behaves exactly as it does on `listSites`, including narrowing to nothing — rather than 403-ing — for an `org_id` outside the caller's scope.\n\n⛔⛔ **It requires `Authorization`, so it cannot be fetched with a plain `<a href>`.** A browser anchor navigation sends no bearer token and the engine has no cookie authentication to fall back on, so an anchor answers **401** and the customer sees nothing happen. Download it with an authenticated `fetch` and hand the result to the browser as a blob. This is not hypothetical: the estate shipped three staff download buttons built as anchors and every one of them was dead (`docs/72` D14200).\n\nThe header row is English and is **not** localized: the consumer is a spreadsheet or a script, and a header that changed with the viewer's locale would make one customer's file unreadable by another's tooling. Column order is part of the contract — new columns are appended, never inserted.","tags":["hosting"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"Restrict to one organization in the caller's scope.","schema":{"$ref":"#/components/schemas/Uuid"}},{"name":"status","in":"query","required":false,"description":"Filter by site lifecycle status.","schema":{"$ref":"#/components/schemas/SiteStatus"}},{"name":"product_line","in":"query","required":false,"description":"Filter by product line code.","schema":{"type":"string","maxLength":64}},{"name":"group","in":"query","required":false,"description":"Restrict to the sites in one site group.","schema":{"type":"string","format":"uuid"}},{"name":"server","in":"query","required":false,"description":"Restrict to the sites on one server — a `key` from `listSiteServers` (and from each row's `server.key`): `own:<uuid>`, `panel:<uuid>`, `fleet:<region>-<n>`, or one of `edge`, `external`, `unplaced`, `managed`. Returns exactly the rows whose `server.key` is that key (D43). A value that is not a key is refused with 422 rather than ignored; a well-formed fleet name that names no box returns nothing.","schema":{"type":"string","maxLength":80}},{"name":"search","in":"query","required":false,"description":"Case-insensitive substring match on the primary domain or the name, applied in the database across the whole collection in scope.","schema":{"type":"string","maxLength":253}},{"name":"min_da","in":"query","required":false,"description":"Only sites whose newest Moz Domain Authority is at least this, exactly as `listSites` applies it (s1014 MOZ-V2); an unmeasured site is excluded by any bound.","schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"max_da","in":"query","required":false,"description":"Only sites whose newest Moz Domain Authority is at most this, exactly as `listSites` applies it (s1014 MOZ-V2); an unmeasured site is excluded by any bound.","schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"min_pa","in":"query","required":false,"description":"Only sites whose newest Moz homepage Page Authority is at least this, exactly as `listSites` applies it (s1014 MOZ-V2); an unmeasured site is excluded by any bound.","schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"max_pa","in":"query","required":false,"description":"Only sites whose newest Moz homepage Page Authority is at most this, exactly as `listSites` applies it (s1014 MOZ-V2); an unmeasured site is excluded by any bound.","schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"min_spam","in":"query","required":false,"description":"Only sites whose newest Moz Spam Score (percent) is at least this, exactly as `listSites` applies it (s1014 MOZ-V2); an unmeasured site is excluded by any bound.","schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"max_spam","in":"query","required":false,"description":"Only sites whose newest Moz Spam Score (percent) is at most this, exactly as `listSites` applies it (s1014 MOZ-V2); an unmeasured site is excluded by any bound.","schema":{"type":"integer","minimum":0,"maximum":100}}],"responses":{"200":{"description":"The CSV, streamed. `Content-Disposition` names the file `zinn-sites-<timestamp>.csv`. No `Content-Length` is sent — the row count is unknown until the last chunk and a guess would truncate the download.","content":{"text/csv":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/sites/servers":{"get":{"operationId":"listSiteServers","summary":"The servers the caller's sites run on, with how many sites each.","description":"⚖️ Owner decision D43 (s1006): the site list shows *\"sites on servers with clear labels\"*, and a customer with thousands of sites needs the inverse question — which of my sites are on this server? This is the option list for `listSites`'s `server` filter.\n\nIt applies the same scope and filters as `listSites` (`org_id`, `status`, `product_line`, `group`, `search`), so each `sites` count is exactly the number of rows `listSites?server=<key>` returns. One grouped read over the placement columns: a handful of entries however many sites the organization has.\n\nA server on our own fleet is named by **region and number** (`fleet:hel1-1`, rendered \"Helsinki server 1\"); its hostname and id are platform infrastructure and are never returned. A customer's own server and connected panel carry the name the customer gave them.","tags":["hosting"],"parameters":[{"$ref":"#/components/parameters/ActiveOrg"},{"name":"org_id","in":"query","required":false,"description":"Restrict to one organization in the caller's scope.","schema":{"$ref":"#/components/schemas/Uuid"}},{"name":"status","in":"query","required":false,"schema":{"$ref":"#/components/schemas/SiteStatus"}},{"name":"product_line","in":"query","required":false,"schema":{"type":"string","maxLength":64}},{"name":"group","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"search","in":"query","required":false,"schema":{"type":"string","maxLength":253}}],"responses":{"200":{"description":"Every server the matching sites are on.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SiteServerFacet"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/capacity":{"get":{"operationId":"getSiteCapacity","summary":"Whether this organization may create another site, and how much room is left.","description":"The site cap **as `POST /v1/sites` would apply it**, answered before the customer fills the form in rather than after. Until this existed the cap was reachable only by failing: the create refused with `SITE_QUOTA_EXCEEDED` or `PLAN_REQUIRED` at the end of a three-step wizard, which is the worst moment to learn a plan is full.\n\nIt resolves through the same function the refusal does, so the screen and the refusal cannot disagree. It is **advisory and takes no lock**: another member of the organization may take the last slot between this answer and the create, in which case the create still refuses. The engine is the control; this endpoint is what lets a client disable a button *with a reason* instead of letting it fail.\n\n`has_room` is always answered — it discloses nothing a caller cannot obtain by POSTing — but every **figure** is gated twice: on the `billing.view` permission (plan size is what that permission means) and on whether the governing plan belongs to an organization already inside the caller's scope. Under hierarchical tenancy the plan may be an ancestor's and `used` is counted across that ancestor's whole subtree, so a client-org member is told their plan is managed elsewhere rather than handed an aggregate over sibling tenants.","tags":["hosting"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"The organization to answer for. Required when the caller can create sites in more than one; otherwise defaults to theirs.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The organization's site capacity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCapacity"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/sites/deployable-plans":{"get":{"operationId":"listDeployablePlans","summary":"The plans this organization can deploy a site into right now.","description":"Answers *\"what plan do I already have to add sites to\"* — one entry per plan the organization (or an ancestor, under hierarchical tenancy) already holds, with its free slots and the product lines it can actually take a site on.\n\nIt exists because the create wizard opened on a flat list of every active product line with no indication which of them the customer owned or could use, so the common case — I have capacity, I want another site — was buried in a catalogue. Deploying into capacity you already own and buying more capacity are two different jobs, and this endpoint is the first of them.\n\n⛔ Every entry resolves through the same function `POST /v1/sites` enforces, so a card reading \"193 free\" and a create answering `SITE_QUOTA_EXCEEDED` cannot disagree. It is advisory in exactly the way `/v1/sites/capacity` is: no lock is taken, so a concurrent create may still win the last slot.\n\n⛔ Lines that no purchasable plan grants a site slot on are **never** returned — a managed database has no document root and a Boards plan is not hosting, so offering either as somewhere to create a website is a dead end. The set is derived from the catalogue, so a line an operator seeds tomorrow is classified correctly without a deploy.\n\nAn empty `data` means the organization can deploy nowhere and must buy capacity first. The figures are gated exactly as `/v1/sites/capacity` gates them.","tags":["hosting"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"The organization to answer for. Required when the caller can create sites in more than one; otherwise defaults to theirs.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The plans a site can be deployed into.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DeployablePlan"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/sites/{siteId}":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSite","summary":"Get a site.","description":"Returns a single site the principal can view. RLS-scoped.","tags":["hosting"],"responses":{"200":{"description":"The site.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Site"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateSite","summary":"Rename a site.","description":"Changes the site's display name, the label the dashboard lists it as. Requires `sites.create` on the site's organization, the same authority that created it; a site the caller cannot reach is a `404`. The name is trimmed and must be 1 to 200 characters. Nothing else is writable here: the primary domain is a separate, multi-step operation (`renameSiteDomain`) because it re-points DNS, the CDN and TLS. Every rename writes a `site.name_changed` audit row with the old and new name.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteRename"}}}},"responses":{"200":{"description":"The renamed site.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Site"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"deleteSite","summary":"Schedule a site's permanent deletion.","description":"Starts the grace period after which the site, its vendor hosting package and everything on them are destroyed. Until this operation existed the driver could delete a package and the teardown workflow was in place, and a customer who wanted their own site gone had to open a ticket. The site is **not** suspended while the countdown runs — it serves normally, so waiting costs nothing.\n\n**Scheduled backups pause while the deletion is scheduled**: the daily and hourly backups skip the site, and its existing backups are kept. Cancelling the deletion (`cancelSiteDeletion`) resumes them with an immediate backup, so the gap closes the moment the customer keeps the site.\n\n⛔ **This operation carries a request body on `DELETE`.** RFC 9110 permits it and it is deliberate: the typed confirmation must travel with the request that acts on it, because a \"confirm\" call followed by an unconfirmed delete is two requests and the second one is the whole vulnerability. `confirm_domain` is compared against `SiteDeletion.primary_domain` — case-insensitively, ignoring surrounding whitespace and a trailing root dot, and never against an alias.\n\n`202` and not `200`: nothing has been destroyed yet. The body is the same `SiteDeletion` resource `getSiteDeletion` returns, so the client renders the countdown from the server's answer rather than from what it asked for. A deletion already scheduled is `409`. A confirmation that does not match, an absent `confirm_domain`, or a site whose state does not allow deletion is `422`. `503` means the teardown could not be armed and **nothing was scheduled** — the request is safe to repeat.\n\nA site is deletable when something real stands behind it: a vendor hosting package, a placement on a fleet worker, an **edge-hosted project** (GitHub Pages, Cloudflare Pages and the other edge hosts — the teardown detaches the custom domain, deletes the project at the provider and withdraws the DNS records the platform published for it), or a site whose provisioning failed before anything was placed. Anything else — a Zinn® VPS, or an edge site with no project recorded — has no such operation and returns `404`, exactly as an out-of-scope or unknown id does. Requires `sites.view` **and** `sites.delete`; the site lookup is scoped on `sites.delete`, so holding it in one organisation does not reach a site in another.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["confirm_domain"],"additionalProperties":false,"properties":{"confirm_domain":{"type":"string","maxLength":253,"description":"The site's primary domain, as the customer typed it. Read the value to prompt for from `SiteDeletion.primary_domain` rather than from a `Site` object already on screen: one value on both sides is what stops the instruction and the check drifting apart.","example":"example.com"}}}}}},"responses":{"202":{"description":"The deletion is scheduled. Nothing has been destroyed yet.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteDeletion"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/certificate":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteCertificate","summary":"The TLS certificate serving this site.","description":"Whether this site is served over HTTPS **on its own name**, and if not, why not.\n\nSites on our own fleet are served a per-vhost certificate the platform obtains itself by ACME (owner ruling 2026-09-07, `docs/537`), because not every site sits behind a CDN and a site with DNS pointed straight at our fleet needs a publicly-trusted certificate of its own.\n\n⛔ `state` is never simply \"no\". `issued` / `pending` / `failed` with a reason are three different facts, and the failure directions are asymmetric: behind Cloudflare Full (strict) an uncovered host answers HTTP 526 — a hard outage — while behind plain Full it is a silent downgrade. A payload that could only say \"no\" would leave a customer looking at a broken site with no explanation.\n\n⛔ `covered` and `serving` are DIFFERENT and both are returned. `covered` means a CA signed it; `serving` means the box actually presents it. A certificate that exists and is not installed serves nobody, and a screen built from `covered` alone would report a healthy site to a customer whose visitors see a name-mismatch warning.\n\n`scope` is `shared` when the site is covered by one platform certificate for a registrable domain we own — the ordinary case for a preview hostname, where a single wildcard covers every site on that domain rather than one certificate each.\n","tags":["hosting"],"responses":{"200":{"description":"The certificate state for this site.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCertificateStatus"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/sites/{siteId}/metrics":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteMetrics","summary":"Get a site's current usage metrics.","description":"Point-in-time usage for the Overview panel — disk, bandwidth, visits, the PHP version, the TLS state, and a short daily bandwidth series for the usage chart. RLS-scoped to a site the caller can view (`sites.view`); an out-of-scope or unknown id is a `404`, exactly like `getSite`.\n\n**Collection is asynchronous.** Metrics are gathered off the request path (a scheduled pull from the site's fleet worker into a cached store — never a live per-request driver call, CLAUDE.md §2.16) and read back here. Until a sample has been collected — a freshly-provisioned or suspended site, or a site on a worker not yet reporting — `available` is `false`, `collected_at` is `null` and the usage counters are `null`; the shape is stable so the client renders \"usage not yet available\" without a contract change once the collector populates it.","tags":["hosting"],"responses":{"200":{"description":"The site's current metrics (or an unavailable envelope).","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMetrics"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/usage":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteVisitUsage","summary":"Get one site's metered visits for the current billing period.","description":"This site's billable page views so far this billing period, alongside the organisation-wide allowance they count against. RLS-scoped to a site the caller can view (`sites.view`); an out-of-scope or unknown id is a `404`, exactly like `getSite`.\n\n**A visit is a human page view with bots excluded** (owner ruling 2026-08-11). Crawlers, automated agents, assets, redirects and error responses are all excluded, and `excludedPageViews` reports how many were — the rule is published so a customer can check it rather than take it on trust.\n\n**The organisation's totals are returned with the site's own** because a site figure cannot be read without its denominator: 40,000 views is unremarkable on Agency Growth and a chargeable overage on Starter. The allowance is granted to the plan, not to the site, and is shared across every site that plan pays for.","tags":["hosting"],"responses":{"200":{"description":"The site's metered visits for the current period.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteVisitUsage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/uptime/monitors/{monitor_id}":{"parameters":[{"name":"monitor_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getUptimeMonitor","summary":"One monitored address, with its history.","description":"The monitor, its hourly uptime and response-time history, its incidents, its Core Web Vitals readings, and — when its measured health warrants one — a migration offer. ⛔ Unknown ids answer **404, never 403**: a 403 would confirm the id exists and belongs to somebody else. Gated on `sites.view`.","tags":["hosting"],"parameters":[{"name":"hours","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":720,"default":168},"description":"How many hourly history points to return."}],"responses":{"200":{"description":"The monitor and its history.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UptimeMonitorDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"operationId":"updateUptimeMonitor","summary":"Pause, resume, rename or set where a monitored address is checked from.","description":"Gated on `uptime.manage`. ⛔ The **URL cannot be changed**: a monitor's Core Web Vitals readings are joined back to it by that canonical string, so a mutable URL would silently re-point a monitor at another address's history. Change an address by deleting the monitor and adding another. Pausing closes any open incident, so a paused monitor cannot accrue an outage out of us not looking.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UptimeMonitorUpdate"}}}},"responses":{"200":{"description":"The updated monitor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UptimeMonitorDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"deleteUptimeMonitor","summary":"Stop watching a web address.","description":"Gated on `uptime.manage`. Removes the monitor and everything measured for it, and frees its allowance slot.","tags":["hosting"],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/uptime/status-pages":{"get":{"operationId":"listStatusPages","summary":"The organisation's public status pages (Zinn® SEO zs-608).","description":"Each page's settings — title, logo, favicon, colours, theme, timezone, language, which monitors show — its fallback address (`https://status.zinndigital.com/s/<slug>`) and its own address with the edge's state. Gated on `sites.view`.","tags":["hosting"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Narrow to one organisation in the caller's subtree (intersected, never widened)."}],"responses":{"200":{"description":"The pages.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusPageList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createStatusPage","summary":"Create a public status page for the organisation's uptime monitors.","description":"`slug` is optional (one is made from the title). Colours are refused, not adjusted, when text would be hard to read (contrast under 4.5:1, brand under 3:1 on the background). Needs `uptime.manage`.","tags":["hosting"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusPageInput"}}}},"responses":{"201":{"description":"The new page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/uptime/status-pages/{page_id}":{"parameters":[{"name":"page_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getStatusPage","summary":"One status page's settings.","tags":["hosting"],"responses":{"200":{"description":"The page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"operationId":"updateStatusPage","summary":"Change a status page's settings (any subset).","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusPageInput"}}}},"responses":{"200":{"description":"The page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"deleteStatusPage","summary":"Delete a status page (its own address is detached first).","tags":["hosting"],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/uptime/status-pages/{page_id}/hostname":{"parameters":[{"name":"page_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"checkStatusPageHostname","summary":"Ask the edge whether the own address is serving yet.","tags":["hosting"],"responses":{"200":{"description":"The page, with `hostname_status` refreshed from the edge.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"post":{"operationId":"attachStatusPageHostname","summary":"Claim the customer's own address for the page (e.g. status.theirsite.com).","description":"Records a CLAIM on the address and returns the TXT record that proves you control it, in `hostname_claim.records`. ⛔⛔ Nothing reaches the edge and no certificate is requested yet (STATUSHOST): publish the TXT record in the address's own DNS zone, then call `/verify`. Only a proven claim is registered at the edge, which then hands back the CNAME to publish in `hostname_records`. This is what stops another account taking over an address whose old CNAME still points at us. Claiming the same address again keeps its token; a claim never proven is forgotten after 30 days, and a proven one is attached by the hourly sweep even if you never press verify. An own address is a monthly edge charge, so it needs an account in good standing (`403` for a suspended one); the page stays at its fallback address either way.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["hostname"],"properties":{"hostname":{"type":"string","maxLength":253}}}}}},"responses":{"202":{"description":"Claimed. Publish the TXT record in `hostname_claim.records`, then verify.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"delete":{"operationId":"detachStatusPageHostname","summary":"Stop serving the page at its own address (never refused — it stops a charge).","description":"Detaches the attached address — or, when only a claim is pending, withdraws the claim (nothing is at the edge to release).","tags":["hosting"],"responses":{"200":{"description":"Detached, or the claim withdrawn.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/uptime/status-pages/{page_id}/hostname/verify":{"parameters":[{"name":"page_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"verifyStatusPageHostname","summary":"Prove the claimed own address, then register it at the edge.","description":"Reads the claim's TXT record (`_domain-verify.<address>`) from a public resolver and, when it carries the claim's token, registers the address at the edge (`201`, with the CNAME to publish in `hostname_records`). The record missing ⇒ `422` naming it; the resolver not answering ⇒ `503` and nothing changes; an account not in good standing ⇒ `403`. An address any status page or agency panel already holds ⇒ `409`, refused before the edge is asked and without saying whose. If the hourly sweep attached it a moment earlier, `200` with the attached address — it is never registered twice.","tags":["hosting"],"responses":{"200":{"description":"Already attached (by the sweep, or earlier); nothing changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusPage"}}}},"201":{"description":"Ownership proven; registered at the edge. Publish `hostname_records`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/uptime/status-pages/{page_id}/{kind}":{"parameters":[{"name":"page_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"kind","in":"path","required":true,"schema":{"type":"string","enum":["logo","favicon"]}}],"put":{"operationId":"setStatusPageImage","summary":"Upload the page's logo or favicon (PNG, JPEG, WebP or GIF, up to 256 KB).","description":"Vetted and stored by us and served from the page's own address, so the page never loads an image from anywhere else. SVG is refused (it can carry scripts).","tags":["hosting"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"}}}}}},"responses":{"200":{"description":"The page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"removeStatusPageImage","summary":"Remove the page's logo or favicon.","tags":["hosting"],"responses":{"200":{"description":"The page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/public/status-pages/{slug}":{"get":{"operationId":"getPublicStatusPage","summary":"A published status page's public snapshot, by its fallback slug.","description":"What the status-page edge renders: per chosen monitor its state, 90 daily uptime figures (null for a day with no checks — never 100) and its incidents. ⛔ No monitor URL is ever included. Anonymous; cached a minute.","tags":["hosting"],"security":[],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The snapshot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusPageSnapshot"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/status-pages/hosts/{hostname}":{"get":{"operationId":"getPublicStatusPageByHost","summary":"A published status page's public snapshot, by its active own address.","tags":["hosting"],"security":[],"parameters":[{"name":"hostname","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The snapshot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusPageSnapshot"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/uptime/monitors":{"get":{"operationId":"listUptimeMonitors","summary":"The web addresses this organisation has asked us to watch.","description":"Every monitored URL in scope with its current state and its 30-day headline numbers, plus the organisation's allowance. ⛔ `summary.uptime_percent` is **null** until there is anything to divide, and `summary.checks` travels beside it so a client can render \"not enough data yet\" rather than a confident 100% — a monitor added a minute ago has proved nothing. Gated on `sites.view`.","tags":["hosting"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Narrow to one organisation in the caller's subtree — what the dashboard's org switcher sends. ⛔ **Narrow only:** intersected with what the caller may already read, so an org outside their subtree filters to nothing rather than 403-ing."}],"responses":{"200":{"description":"The monitors and the allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UptimeMonitorList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createUptimeMonitor","summary":"Start watching a web address.","parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Which organisation in the caller's subtree the monitor belongs to — what the dashboard's org switcher sends. ⛔ **Narrow only:** intersected with what the caller may already write to, so an org outside their subtree is a 404 rather than a create in somebody else's account."}],"description":"Gated on `uptime.manage`. The address may be **any public http(s) URL** — we do not need to host it, and it need not belong to the customer at all. Refused with 422 when the address is not a public web address (an internal or non-HTTP address is refused in wording that does not confirm our network shape), when this organisation already watches it, or when its allowance is used up. Every account includes three monitored URLs; further capacity is the `uptime_urls_10` extra.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UptimeMonitorCreate"}}}},"responses":{"201":{"description":"The monitor. It is checked on the next sweep, within a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UptimeMonitorDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/usage/visits":{"get":{"operationId":"getVisitUsage","summary":"Get the organisation's metered visits and any overage charge.","description":"Billable page views for the current billing period against the plan's `monthly_visits` allowance, plus the overage that has accrued. Requires `billing.view` rather than `sites.view`: this endpoint's distinguishing content is a **charge**, and a teammate granted site access to publish content should not thereby learn what the account is about to be invoiced.\n\n**Over the allowance, the site keeps serving** (owner ruling 2026-08-11). Nothing is throttled, suspended or refused for being popular; the excess is billed per block of 10,000 page views and shown here before the invoice is raised.\n\n**The first partial period is pro-rated.** Metering began on 2026-08-11 and nothing before it can be measured, so a period that started earlier has its allowance scaled to the part actually observed and `prorated` is `true` — otherwise a customer would be billed for a gap in our own instrumentation. `fullAllowance` carries the unscaled monthly figure so the UI can show both.\n\n`overageAmountMinor` and `overageCurrency` are `null` **together** when no overage rate is in force. That is a real state and it is not zero: \"not yet priced\" and \"costs nothing\" are different facts, and only one of them is safe to show a customer as a bill.","tags":["billing"],"responses":{"200":{"description":"The organisation's metered visits for the current period.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisitUsage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/database":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteDatabase","summary":"Get a site's database size and panel links.","description":"The per-site Tools tab's Database card — the site's MySQL size and table count, plus single-use SSO links into the phpMyAdmin and File Manager panels. Requires **both** `sites.view` and `sites.panel_access` — the panels are full database and filesystem access, which is strictly more than listing a site — and is RLS-scoped to a site the caller holds `sites.panel_access` over, so holding the key in one org never reaches another org's site. An out-of-scope or unknown id is a `404`, exactly like `getSite`; a caller who can see the site but lacks `sites.panel_access` gets a `403`.\n\n**The data source is provisioned, not synchronous.** The size/table figures come from the site's fleet worker and the panels are stood up per host behind Cloudflare Access. Until a host is serving them, `available` is `false` and every figure and panel URL is `null` — never a fabricated `0` or a link to a panel that is not there. The shape is stable, so populating it later is not a contract change. Panel URLs, when present, are always HTTPS single-use links minted on read (a non-HTTPS panel URL is never returned).\n\n**`links=false` — the page read (no box contact).** The full read reaches the site's server three times (seconds). With `links=false` the answer comes from the engine's rows and the last stored live reading instead: every URL is `null`, `tools` names the doors the site has (open one with `createSitePanelSession`), and `checked_at` is when the server was last asked — `null` when it has never been asked on the site's current host, in which case `available` is the expectation from the site's placement and the figures are `null`. A reading older than 15 minutes, or none, starts one background refresh; every full read and every panel session stores a fresh reading too, and a site that moves host has none until it is measured there.","tags":["hosting"],"parameters":[{"name":"links","in":"query","required":false,"description":"`false` answers from stored state with no panel links and no contact with the server (the dashboard's page read). Any other value, or none, is the full read that mints the links.","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"The site's database + panel links (or an unavailable envelope).","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteDatabase"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/panel-sessions":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"createSitePanelSession","summary":"Mint one single-use panel link, at the moment the customer clicks.","description":"Returns a freshly minted single-use SSO link into **one** of the site's per-site tools — phpMyAdmin or the File Manager — for the caller to open immediately.\n\n**Why this exists rather than reusing `getSiteDatabase`.** The links that endpoint returns are single-use and expire in **180 seconds**, deliberately: a panel link that still works tomorrow is a credential. Rendering one into an `<a href>` on page load therefore hands the customer something that is dead before they have read the card — they click four minutes later and are told the token expired, which reads to them as being asked to log in. This endpoint moves the mint to the click, so the token's whole life is one redirect.\n\nSame authority as `getSiteDatabase`: **both** `sites.view` and `sites.panel_access`, RLS-scoped on the narrower key, so holding `sites.panel_access` in one org can never mint a link for another org's site. An out-of-scope or unknown id is a `404`, never a `403`, so this cannot be used to discover that a site exists.\n\n`POST` because it is **not idempotent**: every call writes a new single-use token to the hosting box. A `GET` would be re-issued by a prefetch, a proxy or the back button, burning a token each time.\n\nA site with no panel to open is a `409` carrying the same sentence the Tools card shows — never a `200` with a null URL.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePanelSessionCreate"}}}},"responses":{"200":{"description":"A single-use HTTPS link into that panel, valid for 180 seconds.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePanelSession"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/ide-assist":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"askSiteIdeAssistant","summary":"Ask the AI assistant about one file in the site's web editor.","description":"Answers one request about one file, from inside the site's browser editor, and bills the model call to that site's organisation on the same AI meter as every other surface (their own provider key if they have added one, their Zinn® credit if not).\n\n**This is the one site endpoint family with no user session behind it, and that is deliberate.** Its caller is a VS Code extension running inside the customer's own CageFS jail on a hosting box, which cannot hold a Keycloak session. It authenticates with a **signed, site-bound, expiring grant** minted when the editor is opened and presented as `Authorization: Bearer <grant>`. The grant names the site, the organisation and the person who opened the editor; the site in it must match the site in the path, and the organisation is read from the grant and never from the request body, so a grant for one site can neither ask about another nor bill another tenant.\n\nThe grant never reaches the customer's browser: it is held in a root-owned file on the hosting box and attached by the editor gate, which runs outside every jail. A missing or unreadable grant is a `404`, never a `401`, so this cannot be used to discover that a site exists.\n\nAn **editing** action (`fix`, `refactor`, `complete`, `generate`) returns a `proposal`: the complete replacement for the region that was sent. It is a suggestion and nothing on this side applies it — the editor shows it as a diff and writes it only after the customer approves. A **read-only** action (`ask`, `explain`) never returns one, however code-shaped its answer.\n\nA refusal the customer should read — an exhausted allowance, a revoked provider key, a question that is too long, a file too large to rewrite safely — is a `422` carrying the sentence to show them and a code in `details[].code`, because \"you are out of credit\" and \"we could not reach the model\" are different facts and only one of them is theirs to fix.","tags":["hosting"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdeAssistAsk"}}}},"responses":{"200":{"description":"The assistant's answer, and a proposed change when one was asked for.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdeAssistAnswer"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/ide-assist/models":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"listSiteIdeAssistantModels","summary":"The AI models the site's web editor may use.","description":"What the editor's model picker offers this organisation, **cheapest first**. The first entry is also the one marked `default`: the editor's automatic choice is computed from our published price list rather than typed into the code, so a cheaper model becomes the default when it appears and nobody has to remember to change it.\n\n⛔ **Every model listed carries a real price**, and one we cannot price is not listed. Owner ruling 2026-09-09, reading this dropdown: *\"it says model price unknown - how can they be unknown they are public … it can never say unknown!\"* The rule this replaced listed unpriced models marked `priced: false`, on the reasoning that a BYO-key customer may run anything their account can — a fair argument that lost to the measurement, because **33 of 45 verified models were unpriced** and the \"marked exception\" was three quarters of the list. A **stale** price is still offered, with its age: a freshness problem must not become an availability problem.\n\nAuthenticated by the same grant as the assistant itself. When the organisation cannot spend at all, `models` is empty **and `refusal` says why**: an empty list on its own cannot be told apart from \"we could not look\".","tags":["hosting"],"security":[],"responses":{"200":{"description":"The picker's contents, and the reason it is empty when it is.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdeAssistModels"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/sites/{siteId}/ide-assist/credit":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteIdeAssistantCredit","summary":"What the site's web editor shows beside its assistant.","description":"The AI balance for the organisation that owns this site, and where its owner tops it up. The editor paints this when the assistant panel opens; every chat turn carries the same object back afterwards, so the number the customer sees is the one after their own question rather than one call behind it.\n\n**`spendable_micros` is the figure to render, not `balance_micros`.** They differ by whatever is left of today's included allowance, and an organisation with a zero balance and an unspent allowance can still ask the assistant anything it likes.\n\nThis never refuses for lack of credit: the customer who has run out is precisely the one who needs this screen and its `top_up_url`.","tags":["hosting"],"security":[],"responses":{"200":{"description":"The balance, and whether to offer a top-up.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdeAssistCredit"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/sites/{siteId}/ide-events":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"recordSiteIdeEvent","summary":"Record something the customer did in the site's web editor.","description":"Appends one row to the site's activity log for an action taken in the editor — a file saved, an AI suggestion applied, an earlier version restored, a terminal opened. Editing the files of a live website is a privileged action and is logged as one.\n\nThe acting person is taken from the **grant**, which the engine signed when the editor was opened, and never from the request: the caller runs inside the cage being audited, so anything it claimed about identity would be a claim by its own subject. The event name is mapped to a closed set of audit actions for the same reason.\n\n**This records what the editor did.** A customer with a terminal can change their own files without it, so it is an accountability trail for actions taken through our tool rather than a filesystem-level record. The filesystem-level answer is the site backup.","tags":["hosting"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdeEditorEventCreate"}}}},"responses":{"200":{"description":"The event was recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdeEditorEvent"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/sites/{siteId}/ide-chat":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"askSiteIdeChat","summary":"One turn of the web editor's AI chat.","description":"The conversation panel inside the site's web editor. Unlike `askSiteIdeAssistant` — which answers one question about one file — this carries a transcript and a catalogue of **tools** the editor is willing to run, so the assistant can answer questions about the customer's own hosting rather than only about their code.\n\nAuthenticated by the same signed, site-bound grant as the rest of the editor's endpoints, and metered to the same organisation on the same `web_ide` surface. The model is the organisation's own choice, or the cheapest priced one when they have expressed none — Claude, ChatGPT, Gemini or Grok, funded from Zinn® credit or the customer's own provider key.\n\n**The engine never runs a tool.** When the model asks for one, the response carries `tool_calls` and an empty `answer`, and the conversation is unfinished: the editor invokes them through its own MCP client — where the customer's confirmation happens for anything destructive, and where the MCP server's write gate and spend caps apply — and posts the results back on the next turn. A response with an empty `answer` and no `tool_calls` is never returned; that is a `422` carrying its own sentence, because the call was paid for either way and a blank panel is indistinguishable from a broken one.\n\nThe transcript is authored inside the customer's own jail, so it is treated as data: roles are mapped from a closed set, the tool list is bounded and coerced, and a malformed tool is dropped rather than offered.","tags":["hosting"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdeChatAsk"}}}},"responses":{"200":{"description":"The assistant's answer, or the tools it wants the editor to run.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdeChatTurn"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/ide-mcp":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"callSiteIdeMcp","summary":"The platform MCP server, reached from inside the site's web editor.","description":"A JSON-RPC 2.0 MCP endpoint — the **same** server, registry, write gate, confirmation guard, audit trail and spend caps as `/v1/mcp`, reached through a different door. What differs is only the credential: this one accepts the editor's own signed grant, so the editor can be shipped with our MCP server already connected without a customer's hosting jail ever holding an `McpConnection` token.\n\nThe editor's own MCP client is seeded to point at the session gate on the hosting box; the gate attaches the grant and relays here. One request, one response — a notification (no `id`) answers `202` with no body, and a JSON array is accepted as a batch.\n\n**Deliberately narrower than a connection a customer mints themselves.** An MCP token can never out-scope the human who created it, and an editor grant carries that person's name rather than their permissions — so this connection is scoped to what the editor already is: the customer's sites, their control panels and their cache. Opening an editor is not a privilege escalation.","tags":["hosting"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/JsonRpcRequest"},{"type":"array","items":{"$ref":"#/components/schemas/JsonRpcRequest"}}]}}}},"responses":{"200":{"description":"The JSON-RPC response, or an array of them for a batch.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/JsonRpcResponse"},{"type":"array","items":{"$ref":"#/components/schemas/JsonRpcResponse"}}]}}}},"202":{"description":"A notification was accepted. No body."},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/sites/{siteId}/cache-health":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteCacheHealth","summary":"Get a site's latest Zinn® Cache Pro cache-health report.","description":"The newest hourly report Zinn® Cache Pro sent about the site's object cache — hit ratio, Redis memory, evicted keys, whether it is connected — and the `problems` the engine found in it, which are exactly the problems the customer is e-mailed about (edge-triggered, one message when a problem appears and one when it clears). RLS-scoped to a site the caller can view (`sites.view`); an out-of-scope or unknown id is a `404`. Until the site has reported, `reported` is `false`.","tags":["hosting"],"responses":{"200":{"description":"The latest report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCacheHealth"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/sites/{siteId}/origin-load":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteOriginLoad","summary":"Is this site's server slow to answer, and what kind of request is slow.","description":"s1014 ORIGINGUARD (docs/1110). Every 5 minutes the engine counts each hosted site's requests that took 2 seconds or more at its server over the last 10 minutes, by kind (`own_jobs` — the site's own scheduled tasks and our checks; `visitor_ajax`; `admin`; `translated_paths`; `pages`), plus PHP entry-process denials (the 508 a full PHP pool answers). `state` is `slow` only when the site was over the line on EVERY check for 30 minutes (`watching` before that; `quiet` otherwise), so one busy minute never shows. `page_cache_ratio` is the share of guest page views answered from the page cache; `edge_hit_ratio` the site's own Cloudflare zone's cache hit rate over a day (null = not measured). `checked_at` null means no check has been published; `blind` means the last check could not read the logs — neither is \"fine\". Reads stored state only, never a vendor. RLS-scoped (`sites.view`); out-of-scope or unknown is a `404`.","tags":["hosting"],"responses":{"200":{"description":"The site's origin-load state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteOriginLoad"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/sites/{siteId}/vitals":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteVitals","summary":"Get a site's homepage Core Web Vitals.","description":"The site's newest Core Web Vitals reading — LCP, CLS and INP for its **homepage**, with the \"good / needs improvement / poor\" band for each and for the reading as a whole. Backs the Performance tab's vitals card and the free SEO Basics tile, both of which are sold as included on every plan and every site. RLS-scoped to a site the caller can view (`sites.view`); an out-of-scope or unknown id is a `404`, exactly like `getSite`.\n\n**Homepage only, by design.** Every surface that sells this sells *homepage* Core Web Vitals. Measuring every URL of every site is a different product.\n\n**Collection is asynchronous.** Readings are taken off the request path by a scheduled collector and read back here — a live Lighthouse run would be a 20-second uncached external call on a tab that mounts for every site (CLAUDE.md §2.16). Until a site has been measured, `available` is `false`, every metric is `null` and every band is `unknown`.\n\n**`source` must be rendered.** A `lab` reading is a synthetic Lighthouse run; a `field` reading is what real Chrome users experienced (Chrome UX Report) and is what Google ranks on. Field data does not exist for sites below CrUX's traffic threshold — which is most low-traffic sites — so `lab` is the coverage tier. Presenting a lab score as though real users produced it is a false claim about what visitors experienced, so clients must label which one they are showing.","tags":["hosting"],"responses":{"200":{"description":"The site's newest vitals reading (or an unavailable envelope).","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteVitals"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/vitals/history":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteVitalsHistory","summary":"Get a site's speed history and change timeline.","description":"How the site's speed has moved over time, **and what changed on the site**, on one axis — so a customer can see that activating a plugin cost them 0.4 s rather than having to remember it.\n\n**This is the consumer that was missing.** Vitals rows have been kept since #626 with a comment saying they exist \"so the Performance tab can show a trend\"; nothing ever read them, there was no time-series endpoint, and there was no charting library in the repo. The trend was being stored correctly, for weeks, for nobody.\n\n**Two producers, one axis.** `points` are Lighthouse measurements taken off the request path by a scheduled sweep. `events` are what the site reported about itself over a signed webhook (plugin activated, core updated, theme switched, PHP version changed), merged with its successful deploys. Events carry the time they happened **on the site**, so a webhook delivered late still lands beside the score it explains.\n\n**`score_delta` is computed here.** Two clients subtracting two nullable columns is two chances to render `-87` for \"we did not measure the earlier one\".\n\n⚠️ **Cadence.** The sweep measures a fixed number of sites per hour, so on a large estate a site's points can be days apart. A site that reports a change is moved to the front of the next sweep, which is why the timeline — not the sweep — is the primary signal for attributing a regression (docs/85 §4.2).\n\nRLS-scoped to a site the caller can view (`sites.view`); an out-of-scope or unknown id is a `404` alike, exactly like `getSite`.","tags":["hosting"],"parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":365,"default":90},"description":"How far back to look. Clamped rather than rejected — this is a cheap read of the caller's own data, so a `422` on `days=0` would be a worse experience than a sensible window, and only an unbounded one is a real risk."}],"responses":{"200":{"description":"The site's speed history, change timeline and tier recommendation.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteVitalsHistory"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/site-events/ingest":{"post":{"operationId":"ingestSiteEvents","summary":"Receive a site's report about its own changes (signed webhook).","description":"What a site's Zinn® plugin POSTs when something changed on it — a plugin activated or deactivated, core or a theme updated, a theme switched — plus the PHP version it is running.\n\n**Machine-to-machine; there is no principal.** WordPress is talking, not a person, so there is no session, no API key and no organisation header. Authentication is an **HMAC-SHA256** over `\"<timestamp>\\n<body>\"` in `X-Zinn-Cache-Signature` (`sha256=<hex>`), with `X-Zinn-Cache-Timestamp` carrying the unix seconds — the same scheme the plugin already uses for its cache-purge mirror.\n\n**The secret is derived, never stored.** The engine resolves `site` to a hosted site by primary domain, derives that site's webhook secret from the platform master key, and compares in constant time. The organisation comes from the **resolved site**: a valid signature proves the sender holds that site's secret and proves nothing whatsoever about any other tenant.\n\n**Every refusal is uninformative on purpose.** An unknown hostname is a bare `404` and a bad signature a bare `401`, because a chattier answer would tell anyone who can guess a hostname which domains this platform hosts.\n\n**Idempotent.** WordPress fires some of these hooks more than once per change and the POST is fire-and-forget, so a duplicate delivery is accepted with `stored: 0` rather than refused — replay safety lives in the database.","tags":["hosting"],"security":[],"parameters":[{"name":"X-Zinn-Cache-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds. Signed as part of the material, which is what makes the replay window meaningful — a signature over the body alone could be replayed for ever with a fresh header."},{"name":"X-Zinn-Cache-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"`sha256=<hex>`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteEventReportRequest"}}}},"responses":{"202":{"description":"Accepted. `stored` is how many rows were new.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteEventReport"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"description":"Ingest is not configured — the platform master key the per-site secret is derived from is absent. ⛔ A missing signing key refuses; it never degrades into an unauthenticated write path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/site-cache-health/ingest":{"post":{"operationId":"ingestSiteCacheHealth","summary":"Receive a site's hourly Zinn® Cache Pro cache-health report (signed webhook).","description":"What Zinn® Cache Pro POSTs once an hour on a site we host: numbers and state only (no keys, no query text, no visitor data). Authenticated exactly like `ingestSiteEvents`; the organisation is the resolved site's. The latest report per site is kept, and a problem that appears (or clears) since the previous report notifies the customer once.","tags":["hosting"],"security":[],"parameters":[{"name":"X-Zinn-Cache-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds, inside the signed material."},{"name":"X-Zinn-Cache-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"`sha256=<hex>`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCacheHealthReportRequest"}}}},"responses":{"202":{"description":"Stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCacheHealthAccepted"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"description":"Ingest is not configured (the site-secret master key is absent).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sla/policy":{"get":{"operationId":"getSlaPolicy","summary":"The published uptime commitment and its service-credit ladder.","description":"The figure we stand behind, the credit owed at each tier, the exclusions and the claim window — **rendered from `engine/engine/sla/policy.py` and never retyped**. ⛔ Clients must interpolate these values into their own copy rather than writing \"99.9%\" into a locale catalogue: a figure translated into 58 languages cannot be grepped for and cannot be changed (`CLAUDE.md` §2.45). `min_coverage_percent` is the share of a month we must have measured before a reading adjudicates; below it the month is `unadjudicable` and the customer's claimed tier stands.","tags":["billing"],"responses":{"200":{"description":"The published policy.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SlaPolicy"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/sla/periods":{"get":{"operationId":"listSlaPeriods","summary":"Recent months for every monitored site, and what may be claimed.","description":"One row per monitored site per calendar month, over the last six months. Only monitors attached to a site we **host** appear: we do not promise uptime for a URL we do not serve, and watching URLs we do not serve is the uptime product's whole purpose. ⛔⛔ `verdict` has **three** values and they must not be folded into a boolean — `met`, `missed`, and `unadjudicable` when our own coverage was too thin to decide. Reading `unadjudicable` as `met` is the convenient fold and it is the one that saves us money, so it is refused here (§2.44). `uptime_percent` is **null** when no check was made: zero checks is not zero uptime. Gated on `billing.view`.","tags":["billing"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Narrow to one organisation in the caller's subtree — what the dashboard's org switcher sends. ⛔ **Narrow only:** intersected with what the caller may already read, so an org outside their subtree filters to nothing rather than 403-ing."}],"responses":{"200":{"description":"The policy and the periods.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SlaPeriodList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/sla/claims":{"get":{"operationId":"listSlaCredits","summary":"The service credits already issued to this organisation.","description":"Newest first, capped at 100. Gated on `billing.view`.","tags":["billing"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Narrow to one organisation in the caller's subtree. Narrow only."}],"responses":{"200":{"description":"The credits issued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SlaCreditList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"claimSlaCredit","summary":"Claim the service credit for one monitored site's month.","description":"Issues account credit — not cash — as a share of that site's monthly fee, and records it. **Idempotent by construction:** one month and one monitor may be credited exactly once, enforced by a unique constraint, so a retry, a race and a double click all lose the same way. `credit_percent` is read **only** when the month is `unadjudicable`; a measured month is credited at the tier its own figure reaches and a better one cannot be claimed. Gated on `sla.claim`.","tags":["billing"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Narrow to one organisation in the caller's subtree — what the dashboard's org switcher sends. ⛔ **Narrow only:** intersected with what the caller may already write to, so an org outside their subtree resolves to nothing and 404s rather than crediting somebody else's ledger."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SlaClaimRequest"}}}},"responses":{"201":{"description":"The credit issued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SlaCredit"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"A conflict rather than a 422 because it is about the world, not the request: re-sending with different input cannot help. `SLA_ALREADY_CREDITED` — that month is already credited for this site. `SLA_SITE_NOT_IN_THIS_ORG` — the site has changed hands, so its uptime and its fee belong to another account (`hosting`'s transfer registry keeps the monitor with the seller and moves the site).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The claim was refused. `error.code` names which rule, so a client can show its own sentence per cause rather than one apology: `SLA_PERIOD_NOT_FINISHED`, `SLA_PERIOD_NOT_ELIGIBLE`, `SLA_CLAIM_WINDOW_CLOSED`, `SLA_NO_BILLABLE_SUBSCRIPTION`, `SLA_TIER_NOT_CLAIMABLE`, `SLA_SITE_NOT_SERVING` (the site is suspended or quarantined, so that downtime is our enforcement action rather than a failure of the service — `legal/sla` §5).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/site-links/ingest":{"post":{"operationId":"ingestSiteLinks","summary":"Receive one batch of a site's outbound-link scan (signed webhook).","description":"What a site's Zinn® plugin POSTs when its scheduled link scan runs: the posts it looked at, and for each one every outbound `<a>` tag it found, with how many times that tag appears in that post.\n\n**Machine-to-machine; there is no principal.** Authentication is the **same HMAC scheme** `ingestSiteEvents` uses — SHA-256 over `\"<timestamp>\\n<body>\"` in `X-Zinn-Cache-Signature`, with `X-Zinn-Cache-Timestamp` carrying the unix seconds, against a secret **derived** per site from the platform master key. ⛔ Deliberately not a second scheme: one secret, one derivation, one place for the two ends to agree. The organisation comes from the **resolved site** and never from the body.\n\n**A scan is a SNAPSHOT, delivered in batches.** One pass over a site carries one `scan_id` across as many requests as it takes; the request carrying `complete: true` triggers reconciliation, which deletes every post and placement for that site not stamped with that pass. ⛔ That is what makes a link the customer **removed** disappear from the report — an append-only index rots into a permanent overcount and looks authoritative while it does.\n\n⛔ **An abandoned pass deletes nothing.** No completing batch, no sweep: the report goes stale rather than wrong-by-deletion.\n\n⛔ **A batch from a superseded pass is ignored whole** and answers `ignored: true`. The plugin's POST is fire-and-forget with a two-second timeout, so a batch landing after the next cron tick has begun is expected; mixing it in would let a finished pass sweep away the live one's rows.\n\n**Every refusal is uninformative on purpose** — an unknown hostname is a bare `404` and a bad signature a bare `401`, because a chattier answer would tell anyone who can guess a hostname which domains this platform hosts.","tags":["links"],"security":[],"parameters":[{"name":"X-Zinn-Cache-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds. Signed as part of the material, which is what bounds a replay."},{"name":"X-Zinn-Cache-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"`sha256=<hex>`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteLinkReportRequest"}}}},"responses":{"202":{"description":"Accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteLinkReceipt"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"description":"Ingest is not configured — the platform master key the per-site secret derives from is absent. ⛔ A missing signing key refuses; it never degrades into an unauthenticated write path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/link-targets":{"get":{"operationId":"listLinkTargets","summary":"The Link Tracker report — domains this org's sites link out to.","description":"V1's columns, rebuilt: **Domain | Site | Reflinks | Ref posts | Ref sites**. Ranked by reflinks by default, because the question is *\"who am I linking to most\"*.\n\n**Search rolls variants up.** `www.`, letter case and punycode/Unicode are folded on the **write** path, so they are already one row by the time you search — that is the fix for the production defect where `cu-tv.com` showed 185 reflinks and `www.cu-tv.com` showed 1 (docs/96 §1.4, D1328). **Subdomains** stay separate rows, because an operator cares which host they hit, but a search for `skokka.com` finds `blog.skokka.com` too and `rollup` gives the combined totals across the whole match.\n\n⛔ **Paged by `offset`, not by cursor.** The shared cursor paginator is keyset over the sortable id, which is chronological; this list is ranked, and a keyset cursor cannot express that ordering. `total` is the full match so the screen can page all of it — there is no hidden cap.\n\n`coverage` says how much of the estate the report is based on. ⛔ Without it a customer cannot tell *\"no outbound links\"* from *\"nobody has scanned this yet\"*, and those two readings lead to opposite actions.","tags":["links"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Narrow to one organisation in the caller's subtree — what the dashboard's org switcher sends. ⛔ **Narrow only:** it is intersected with what the caller may already read, so an org outside their subtree filters to nothing rather than 403-ing, and sending it can never widen scope. Omitted returns the caller's whole readable subtree, which for a reseller is every client at once."},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"A domain, or any text. A value that parses as a hostname matches that host **and every subdomain of it**; anything else is a substring match, because someone typing `casino` means \"find the ones with casino in them\"."},{"name":"owned","in":"query","required":false,"schema":{"type":"string","enum":["own","external"]},"description":"`own` shows only targets that are the customer's **own** sites; `external` only those that are not. Omitted shows both."},{"name":"site_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Only targets linked to **from** this site."},{"name":"include_ips","in":"query","required":false,"schema":{"type":"boolean","default":true},"description":"Bare-IP targets are real links and are tracked, but they never group sensibly. Set `false` to hide them."},{"name":"min_links","in":"query","required":false,"schema":{"type":"integer","minimum":0},"description":"The noise filter. Padding links (`google.com`, `youtube.com`) sit beside the money links deliberately. ⛔ They are **filterable, never auto-deleted** — removing a link a customer placed on purpose because a heuristic called it noise is not a decision this tool makes."},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["links","posts","sites","host","recent"],"default":"links"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"The report page.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkTargetPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/link-targets/{targetId}":{"parameters":[{"$ref":"#/components/parameters/LinkTargetId"}],"get":{"operationId":"getLinkTarget","summary":"One target, and which of the customer's sites link to it.","description":"The middle drill-down: *\"you link to this domain 643 times — here are the 201 sites it comes from\"*. Each row carries that site's own link and post counts and when it was last scanned.","tags":["links"],"responses":{"200":{"description":"The target and its per-site breakdown.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkTargetDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/link-targets/{targetId}/placements":{"parameters":[{"$ref":"#/components/parameters/LinkTargetId"}],"get":{"operationId":"listLinkPlacements","summary":"Every link to this target, in every post, with its occurrence count.","description":"The deepest drill-down, and the input the bulk editor will act on.\n\n⭐ Each row carries the **whole `<a>` tag**, not just the href and the text. That is deliberate and it is what makes *\"edit the links in full\"* safe: an edit rewrites the href and the text **inside the existing tag**, so `rel`, `target` and the theme's classes survive instead of being flattened.","tags":["links"],"parameters":[{"name":"site_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Only the links on this one site."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"The placements page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkPlacementPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/link-targets/{targetId}/edit-preview":{"parameters":[{"$ref":"#/components/parameters/LinkTargetId"}],"get":{"operationId":"previewLinkEdit","summary":"How many links, posts and sites a bulk edit would change.","description":"The confirmation's own numbers, following whatever site selection the operator has made. Gated on `links.view`: counting what would change is reading, not writing.","tags":["links"],"parameters":[{"name":"site_id","in":"query","required":false,"explode":true,"schema":{"type":"array","items":{"type":"string","format":"uuid"}},"description":"Repeat once per site to narrow the count."}],"responses":{"200":{"description":"What the edit would change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkEditPreview"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/vector/indexes":{"get":{"operationId":"listVectorIndexes","summary":"The organisation's vector indexes.","description":"Every managed vector index this organisation holds, with the two meters the product is sold on: storage and queries this month. Requires `vector.view`.","tags":["hosting"],"responses":{"200":{"description":"The organisation's vector indexes.","content":{"application/json":{"schema":{"type":"object","required":["items","usage"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/VectorIndex"}},"usage":{"$ref":"#/components/schemas/VectorUsage"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createVectorIndex","summary":"Create a vector index.","description":"Creates an index of a fixed width and distance function. `dimension` is whatever your embedding model emits, from 1 to 3072 — it does not have to be a round number, and a width we do not store natively is held exactly rather than approximately.\n\nAbove 2000 dimensions the index is stored at half precision, because pgvector's HNSW index does not accept a full-precision column wider than that. Requires `vector.manage`, and is refused if the plan's `vector_indexes` allowance is full.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VectorIndexWrite"}}}},"responses":{"201":{"description":"The index.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VectorIndex"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/vector/indexes/{indexId}":{"parameters":[{"name":"indexId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The index's id."}],"get":{"operationId":"getVectorIndex","summary":"One vector index.","description":"One index belonging to this organisation. Requires `vector.view`.","tags":["hosting"],"responses":{"200":{"description":"The index.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VectorIndex"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"deleteVectorIndex","summary":"Delete a vector index and every vector in it.","description":"Deletes the index and its vectors in one transaction. **There is no recovery path** short of a database restore. Requires `vector.manage`.","tags":["hosting"],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/vector/indexes/{indexId}/vectors":{"parameters":[{"name":"indexId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The index's id."}],"post":{"operationId":"upsertVectors","summary":"Insert or replace vectors.","description":"Writes vectors by your own id: an id already in the index is replaced, not duplicated. Every vector must carry exactly `dimension` values. Refused when the write would take the organisation past its `vector_index_gb` allowance. Requires `vector.manage`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VectorUpsertRequest"}}}},"responses":{"200":{"description":"How many vectors were written, and the index's new total.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VectorUpsertResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/vector/indexes/{indexId}/vectors/delete":{"parameters":[{"name":"indexId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The index's id."}],"post":{"operationId":"deleteVectors","summary":"Delete vectors by id.","description":"Removes vectors by your own ids. A POST rather than a DELETE with a body: a body on DELETE is permitted by the RFC and dropped by enough proxies that it is not a safe contract to sell. Requires `vector.manage`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VectorDeleteRequest"}}}},"responses":{"200":{"description":"How many vectors were removed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VectorDeleteResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/vector/indexes/{indexId}/vectors/fetch":{"parameters":[{"name":"indexId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The index's id."}],"post":{"operationId":"fetchVectors","summary":"Read vectors back by id.","description":"Returns the vectors you stored, by your own ids, with their metadata. Values come back at the index's own `dimension` — never at the wider width they may physically be stored in, which is an implementation detail you should never have to know about.\n\nA POST rather than a GET because the ids are yours and there may be a thousand of them. This does **not** count against `vector_queries_monthly`: fetching by id runs no nearest-neighbour search. Requires `vector.manage`, like `query`, because it returns your stored data rather than your usage.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VectorDeleteRequest"}}}},"responses":{"200":{"description":"The vectors that exist, in no guaranteed order.","content":{"application/json":{"schema":{"type":"object","required":["vectors"],"properties":{"vectors":{"type":"array","items":{"$ref":"#/components/schemas/Vector"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/vector/indexes/{indexId}/query":{"parameters":[{"name":"indexId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The index's id."}],"post":{"operationId":"queryVectorIndex","summary":"Find the nearest vectors.","description":"Returns the `top_k` nearest vectors, nearest first, optionally restricted to those whose metadata contains `filter`. `distance` is in the index's own metric, so smaller is always nearer whichever metric you chose.\n\n⛔ A query **spends the plan's monthly query allowance**, which is why it requires `vector.manage` rather than `vector.view` — a read that costs money is not a read.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VectorQueryRequest"}}}},"responses":{"200":{"description":"The nearest vectors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VectorQueryResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/vector/usage":{"get":{"operationId":"getVectorUsage","summary":"Vector storage and query usage against the plan.","description":"Both meters against both caps: indexes held, bytes stored, and queries served this calendar month. A `null` limit means the plan states no cap for that meter. Requires `vector.view` — usage is a billing question, so it is readable without the key that can spend the allowance.","tags":["hosting"],"responses":{"200":{"description":"Usage against the plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VectorUsage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/storage/buckets":{"get":{"operationId":"listStorageBuckets","summary":"The organisation's object storage buckets.","description":"Every bucket this organisation has, ours and its own. A `zinn`-owned bucket is storage we operate and bill for; a `customer`-owned one is the organisation's own S3-compatible bucket, which costs us nothing and is therefore **not** metered against the plan's `object_storage_gb` allowance.\n\n`has_credential` reports whether a stored key exists. The credential itself and the Vault path it lives at are deliberately absent from this payload: a path is not a secret, but it is a map of where our secrets live, and this response reaches a browser. Requires `storage.view`.","tags":["hosting"],"responses":{"200":{"description":"The organisation's buckets.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"type":"object","required":["items","usage"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/StorageBucket"}},"usage":{"$ref":"#/components/schemas/StorageUsage"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createStorageBucket","summary":"Provision Zinn® storage, or attach a bucket of your own.","description":"With `ownership: zinn` this provisions storage on our own backend and needs nothing else. With `ownership: customer` it attaches an existing S3-compatible bucket and requires `bucket_name`, `endpoint`, `access_key_id` and `secret_access_key`.\n\nThe key pair is written to Vault and never to a column; the bucket is created `pending` and only becomes `active` once the write has returned, so a failure part way leaves a visibly unfinished bucket rather than one that reads as configured and cannot sign. Requires `storage.manage`.\n\nWith `ownership: zinn` the organisation must hold a plan that includes object storage (`object_storage_gb` granted — `0` counts). Without one this answers `422` with `code: FEATURE_NOT_INCLUDED` and `details[].message: object_storage_gb`, and creates nothing (D26223). `ownership: customer` is never refused for this.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageBucketWrite"}}}},"responses":{"201":{"description":"The bucket.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageBucket"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/storage/buckets/{bucketId}":{"parameters":[{"name":"bucketId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The bucket's id."}],"get":{"operationId":"getStorageBucket","summary":"One bucket.","description":"One bucket belonging to this organisation. Requires `storage.view`.","tags":["hosting"],"responses":{"200":{"description":"The bucket.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageBucket"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"deleteStorageBucket","summary":"Forget a bucket.","description":"Removes the bucket record and, for a bucket of your own, deletes its stored credential.\n\nA bucket still serving media for one or more sites answers `422` and names them: deleting it would leave every rewritten image URL in those sites' published posts pointing at a bucket the platform no longer knows about, and the person pressing delete on a storage screen has no way to know that. Turn media offload off on those sites first. Requires `storage.manage`.","tags":["hosting"],"responses":{"204":{"description":"Forgotten."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/media-offload":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteMediaOffload","summary":"Whether this site's media is offloaded to object storage, and how.","description":"A site with no offload configured answers `200` with `configured: false`, **not** `404`. \"This site does not offload its media\" is an answer; a `404` would be indistinguishable from \"no such site\", which is what the screen would then have to show the customer.\n\n`plan` is returned in **both** states and carries the organisation's included storage, what it is using and what more costs. Media offload is an allowance in the plan plus metered overage, not a separate add-on, and the off state is where a customer needs that said. Requires `storage.view`.","tags":["hosting"],"responses":{"200":{"description":"The site's offload configuration.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMediaOffload"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setSiteMediaOffload","summary":"Turn media offload on for a site, or change how it behaves.","description":"Creates the offload configuration if it does not exist, provisioning storage for the organisation on first use — \"turn on media offload\" is what the customer wants, and a bucket is our word for part of how we do it.\n\nMoving an offload that is already live to a **different** bucket answers `422`. The objects already written stay where they are, so the switch would leave the site serving half its media from a bucket the configuration no longer names, and nothing would report it because new uploads would keep succeeding. Requires `storage.manage`.\n\nProvisioning storage on first use needs a plan that includes object storage; without one this answers `422 FEATURE_NOT_INCLUDED` and creates neither a bucket nor an offload (D26223).","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMediaOffloadWrite"}}}},"responses":{"200":{"description":"The site's offload configuration.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMediaOffload"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"revokeSiteMediaOffload","summary":"Revoke the plugin's token and stop new uploads.","description":"Revokes the WordPress plugin's token so the site can no longer upload.\n\nThe configuration itself is **kept**, and that is deliberate: media already offloaded is addressed by URL inside the site's published posts, so discarding the bucket and prefix would break every one of those images. The customer asked to stop uploading, not to blank their archive. Requires `storage.manage`.","tags":["hosting"],"responses":{"200":{"description":"The site's offload configuration, now revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMediaOffload"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/media-offload/pairing":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"createSiteMediaOffloadPairing","summary":"Mint a short-lived code that pairs the WordPress plugin to this site.","description":"Returns a code the customer types into the Zinn® Media Offload plugin in their WordPress admin. The plugin exchanges it for a token scoped to this one site.\n\nThe code is single-use and expires in thirty minutes: it is read off one screen and typed into another within a minute or two, and a code that lived for a day would be a credential sitting in a browser tab. Requires `storage.manage`.","tags":["hosting"],"responses":{"201":{"description":"A pairing code and when it stops working.","content":{"application/json":{"schema":{"type":"object","required":["code","expires_at"],"properties":{"code":{"type":"string","description":"The code to type into the plugin.","example":"K7MPQ3RTVX"},"expires_at":{"type":"string","format":"date-time"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/media-offload/claim":{"post":{"operationId":"claimMediaOffloadPairing","summary":"The WordPress plugin, redeeming a pairing code for a scoped token.","description":"Called by the Zinn® Media Offload plugin on a customer's WordPress server. **This endpoint is unauthenticated**: the caller has no session with us and can name no organisation — the pairing code is what names it.\n\nEvery failure — an expired code, an already-claimed code and a code that never existed — returns the same `422`. Distinguishing them would confirm to a caller that a guessed code exists, which is the only thing between them and another organisation's storage.","tags":["hosting"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","maxLength":32},"plugin_version":{"type":"string","maxLength":32},"site_url":{"type":"string","maxLength":255}}}}}},"responses":{"201":{"description":"The token and the settings the plugin should apply.","content":{"application/json":{"schema":{"type":"object","required":["token","site_id","prefix","rewrite_urls","delete_local"],"properties":{"token":{"type":"string","description":"Shown once and never again. Stored by us only as a SHA-256 hash."},"site_id":{"type":"string","format":"uuid"},"prefix":{"type":"string","description":"The key prefix this site's objects live under."},"public_base_url":{"type":"string","description":"Where a rewritten media URL points. Empty when the bucket is private, in which case the plugin must not rewrite anything."},"rewrite_urls":{"type":"boolean"},"delete_local":{"type":"boolean"}}}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/media-offload/uploads":{"post":{"operationId":"createMediaOffloadUploads","summary":"Presigned upload URLs for a batch of media files.","description":"Called by the Zinn® Media Offload plugin with a bearer plugin token. Returns one presigned `PUT` URL per key; the plugin then sends the bytes **straight to storage**, so no file ever transits this API and no storage credential ever reaches WordPress.\n\nUp to 100 keys per request. Presigning is local cryptography with no vendor round trip, so a batch costs no more than a single key — which is what makes offloading an existing 20,000-file media library 200 requests rather than 20,000.\n\nEvery key is joined onto the site's own prefix and validated. A key that tries to climb out of that prefix is refused with `422`, never normalised into something plausible.\n\nAn offload writing to **our** storage answers `422` with `code: FEATURE_NOT_INCLUDED` and no URLs once the organisation no longer holds a plan that includes object storage — checked on every request, because a plugin token outlives the plan that paid for it (D26223). An offload writing to the customer's own bucket is unaffected.","tags":["hosting"],"security":[{"mediaOffloadToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["keys"],"properties":{"keys":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","maxLength":512}},"plugin_version":{"type":"string","maxLength":32}}}}}},"responses":{"200":{"description":"One signed upload per key.","content":{"application/json":{"schema":{"type":"object","required":["uploads"],"properties":{"uploads":{"type":"array","items":{"type":"object","required":["key","url","expires_at","public_url"],"properties":{"key":{"type":"string"},"url":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"public_url":{"type":"string","description":"Where the object will be readable, or empty for a private bucket."}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/media-offload/report":{"post":{"operationId":"reportMediaOffloadProgress","summary":"What the WordPress plugin says it has offloaded so far.","description":"Called by the Zinn® Media Offload plugin with a bearer plugin token, to report its progress and receive the settings it should currently apply.\n\n**These numbers are a diagnostic and never a bill.** They come from a plugin on the customer's own server, so a customer wanting a smaller invoice could simply send smaller ones. Storage is metered by measuring the bucket. What this endpoint feeds is the dashboard's \"your plugin last checked in nine minutes ago and has moved 4,102 files\".","tags":["hosting"],"security":[{"mediaOffloadToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["objects_offloaded","bytes_offloaded"],"properties":{"objects_offloaded":{"type":"integer","minimum":0},"bytes_offloaded":{"type":"integer","minimum":0},"plugin_version":{"type":"string","maxLength":32}}}}}},"responses":{"200":{"description":"The settings the plugin should apply.","content":{"application/json":{"schema":{"type":"object","required":["status","rewrite_urls","delete_local","prefix"],"properties":{"status":{"type":"string"},"rewrite_urls":{"type":"boolean"},"delete_local":{"type":"boolean"},"prefix":{"type":"string"},"public_base_url":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/private-network":{"get":{"operationId":"getPrivateNetwork","summary":"The organisation's private access network.","description":"The org's dedicated egress address, the region it lives in, and every device enrolled on it. Gated on `sites.view`.\n\n⛔ **This is not a browsing VPN.** A device reaches the customer's own estate and nothing else — the issued configuration carries no default route — so no third-party traffic ever leaves a Zinn® address. The product exists so a team can add ONE stable address to their SSH/SFTP allow-lists (`/v1/ip-allow`) instead of chasing changing home and mobile addresses.\n\n200 with `network: null` when the organisation has not bought the product, or when `org_id` names an organisation outside the caller's subtree (the two read the same, never a 403). Deliberately null rather than an empty network: a shell would make the screen look like something they own that does nothing. (It was a 404 until NIGHTFIX1114 PNEMPTY; a normal \"not bought\" answer logged a console error on every load.)","tags":["hosting"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Narrow to one organisation in the caller's subtree — what the dashboard's org switcher sends, and what `X-Zinn-Org` stands in for. ⛔ **Narrow only:** intersected with what the caller may already read, so an org outside their subtree filters to nothing rather than 403-ing. Omitted, a reseller reading their whole subtree gets whichever client network sorts first, which is why the switcher sends it."}],"responses":{"200":{"description":"The network and its devices, or `network` null when there is none.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrivateNetworkRead"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/private-network/devices":{"post":{"operationId":"enrolPrivateNetworkDevice","summary":"Enrol a device and return its configuration once.","description":"Gated on `network.private.manage` in addition to `sites.view`.\n\n⛔⛔ **The `config` in the response is shown ONCE and can never be retrieved again.** The private key is generated in memory and is never stored — not in the database and not in Vault — so there is no endpoint that could return it a second time. A customer who loses it rotates the device, which is the correct handling of a lost secret.\n\n422 when the device allowance is spent, when the label is blank, or when the organisation's dedicated address has not finished being assigned.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrivateNetworkDeviceCreate"}}}},"responses":{"201":{"description":"The device, and its configuration — shown once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrivateNetworkIssuedDevice"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/private-network/devices/{seatId}/rotate":{"parameters":[{"name":"seatId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"rotatePrivateNetworkDevice","summary":"Issue a fresh configuration for a device, invalidating the old one.","description":"Gated on `network.private.manage`. This is the answer to \"I lost my configuration file\": the previous keypair stops working the moment the gateway next syncs. The new `config` is likewise shown only once.","tags":["hosting"],"responses":{"200":{"description":"The device, and its new configuration — shown once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrivateNetworkIssuedDevice"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/private-network/devices/{seatId}":{"parameters":[{"name":"seatId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"delete":{"operationId":"revokePrivateNetworkDevice","summary":"Revoke a device.","description":"Gated on `network.private.manage`. The row is kept, marked revoked, so the revocation can be evidenced later — a revocation nobody can point at is not much of a control.\n\n⚠️ Access stops when the gateway next syncs its peer set, not at the instant this returns. The dashboard says so rather than implying otherwise.\n\n404 rather than 403 for a device in another tenant — a 403 would confirm it exists.","tags":["hosting"],"responses":{"200":{"description":"The revoked device.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrivateNetworkDevice"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/site-groups":{"get":{"operationId":"listSiteGroups","summary":"The organisation's site groups.","description":"Every group in scope with its member count, plus whether this caller's plan lets them create one and the colours a group may be drawn in. Gated on `sites.view` — a group is a view of sites the caller can already see.","tags":["hosting"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Narrow to one organisation in the caller's subtree — what the dashboard's org switcher sends. ⛔ **Narrow only:** intersected with what the caller may already read, so an org outside their subtree filters to nothing rather than 403-ing. Omitted returns the caller's whole readable subtree, which for a reseller is every client's group names at once — and a footprint-free operator's group names are their commercial strategy."}],"responses":{"200":{"description":"The groups.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteGroupList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createSiteGroup","summary":"Create a site group.","description":"Gated on `sites.groups.manage` in addition to `sites.view`. Refused with 422 when the organisation's plan does not sell `site_groups`, when the name is blank or already taken (case-insensitively, per organisation), or when the organisation already holds the maximum number of groups.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteGroupCreate"}}}},"responses":{"201":{"description":"The created group.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteGroup"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/site-groups/{groupId}":{"parameters":[{"name":"groupId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getSiteGroup","summary":"One site group.","description":"Gated on `sites.view`. 404 rather than 403 for a group in another tenant — a 403 would confirm the row exists.","tags":["hosting"],"responses":{"200":{"description":"The group.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteGroup"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"operationId":"updateSiteGroup","summary":"Rename or recolour a site group.","description":"Fields omitted from the body are left alone. Gated on `sites.groups.manage`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteGroupUpdate"}}}},"responses":{"200":{"description":"The updated group.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteGroup"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"deleteSiteGroup","summary":"Delete a site group.","description":"Removes the group and its memberships and **nothing else** — the sites themselves are untouched. Gated on `sites.groups.manage`.","tags":["hosting"],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/site-groups/{groupId}/sites":{"parameters":[{"name":"groupId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listSiteGroupSites","summary":"The sites in a group.","description":"Gated on `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The member sites.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteGroupMembers"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"addSiteGroupSites","summary":"Add sites to a group.","description":"Adds without disturbing what is already there — the site list's \"add selected to group\" action, which must not race another tab into replacing a membership it never read. Gated on `sites.groups.manage`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteGroupMembership"}}}},"responses":{"200":{"description":"What changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteGroupMembershipChange"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"put":{"operationId":"setSiteGroupSites","summary":"Replace a group's membership.","description":"Makes the membership exactly the sites given. Sites outside the group's own organisation are ignored rather than refused — naming them in an error would turn this into an existence oracle for another tenant's ids. Gated on `sites.groups.manage`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteGroupMembership"}}}},"responses":{"200":{"description":"What changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteGroupMembershipChange"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"removeSiteGroupSites","summary":"Remove sites from a group.","description":"Takes the named sites out of the group. The sites themselves are untouched. Gated on `sites.groups.manage`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteGroupMembership"}}}},"responses":{"200":{"description":"What changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteGroupMembershipChange"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/syndication/channels":{"get":{"operationId":"listSyndicationChannels","summary":"Every social channel the platform can post to.","description":"The catalogue the connect form, the plan editor and the price list all render from: what each channel needs to connect, what it can carry, its character limit and what one link-bearing post costs us. ⛔ `cost_per_link_post_micros` is the LINK-bearing price in USD micros — every post this platform makes carries a link, so the headline per-post price would understate X by ~13x. Gated on `syndication.view`.","tags":["syndication"],"responses":{"200":{"description":"The channel catalogue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyndicationChannelList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/syndication/connections":{"get":{"operationId":"listSyndicationConnections","summary":"The organisation's connected social accounts.","description":"Gated on `syndication.view`. ⛔ No credential is ever returned — the row holds a Vault pointer and this shape has no field one could live in.","tags":["syndication"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"Narrow to one organisation in the caller's subtree. Never widens scope.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The connected channels.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyndicationConnectionPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createSyndicationConnection","summary":"Connect a social account.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which organisation to connect it for, within the caller's subtree. ⛔ Scoped by `syndication.manage`, never by the reading key — a member holding only view on a client org must not be able to connect a channel that posts as that client.","schema":{"type":"string","format":"uuid"}}],"description":"Stores the credential in Vault and the pointer on the row, then probes it immediately so the customer learns now whether it works rather than when their next article publishes. Gated on `syndication.manage`, which is a separate key from `links.edit` because this posts publicly on the customer's own brand accounts.","tags":["syndication"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyndicationConnectionCreate"}}}},"responses":{"201":{"description":"The connection, with the result of its first probe.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyndicationConnection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/syndication/connections/{connectionId}":{"parameters":[{"name":"connectionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"put":{"operationId":"updateSyndicationConnection","summary":"Rename a connection or replace its credential.","description":"⛔ Omitting `credentials` KEEPS the stored credential rather than clearing it — a customer renaming a connection must not silently delete their token. Gated on `syndication.manage`.","tags":["syndication"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyndicationConnectionUpdate"}}}},"responses":{"200":{"description":"The updated connection, re-probed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyndicationConnection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"operationId":"deleteSyndicationConnection","summary":"Disconnect an account.","description":"Removes the row and the Vault secret. ⛔ Posts already made stay on the record — they are still live on the channel, and deleting our copy would make them unfindable. Gated on `syndication.manage`.","tags":["syndication"],"responses":{"204":{"description":"Disconnected."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/syndication/connections/{connectionId}/verify":{"parameters":[{"name":"connectionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"verifySyndicationConnection","summary":"Check a connection against the live channel.","description":"⛔ A failure is a **200 carrying a non-ready `status`**, not an error response — \"we could not reach it\" is the answer to the question that was asked. Three outcomes: `ready`, `needs_reconnect` (the customer must act) and `error` (we reached the vendor and it said no for another reason). Gated on `syndication.manage`.","tags":["syndication"],"responses":{"200":{"description":"The connection with its probed status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyndicationConnection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/syndication/plans":{"get":{"operationId":"listSyndicationPlans","summary":"Which channels articles go to, and how.","description":"Gated on `syndication.view`.","tags":["syndication"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The organisation's plans.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyndicationPlanPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createSyndicationPlan","summary":"Save a syndication plan.","parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"description":"A plan for one article (`post`), for a recipe (`recipe`) or for everything (`org_default`); the most specific one wins and a disabled plan stops the search rather than falling through. `approval_mode` defaults to `hold` — owner ruling, 2026-08-20. Gated on `syndication.manage`.","tags":["syndication"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyndicationPlanWrite"}}}},"responses":{"201":{"description":"The saved plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyndicationPlan"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/syndication/plans/{planId}":{"parameters":[{"name":"planId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"put":{"operationId":"updateSyndicationPlan","summary":"Change a plan's channels or behaviour.","description":"Replaces the plan's channel set with `connection_ids`. ⛔ Each id is re-checked against the CALLER's scope, not merely the plan's org — a connection id is a UUID somebody could paste, and a plan naming another tenant's connection would post this article to that tenant's account. Gated on `syndication.manage`.","tags":["syndication"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyndicationPlanWrite"}}}},"responses":{"200":{"description":"The saved plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyndicationPlan"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"operationId":"deleteSyndicationPlan","summary":"Remove a plan.","description":"Deletes the plan and its channel list. Runs already made keep their record of what went out. Gated on `syndication.manage`.","tags":["syndication"],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/syndication/runs":{"get":{"operationId":"listSyndicationRuns","summary":"What has been announced, and what is waiting for approval.","description":"One run per published article, with one post per channel. ⛔ `status: complete` means every channel SETTLED, not that every channel succeeded — a channel that failed does not fail the article or its siblings. Gated on `syndication.view`.","tags":["syndication"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"A page of runs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyndicationRunPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/syndication/runs/{runId}":{"parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getSyndicationRun","summary":"One article's fan-out.","description":"The run and one post per channel, each with its own status, what it dropped and why, and what it cost. Gated on `syndication.view`.","tags":["syndication"],"responses":{"200":{"description":"The run and its per-channel posts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyndicationRun"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/syndication/posts/{postId}":{"parameters":[{"name":"postId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"put":{"operationId":"editSyndicationPost","summary":"Change a held post's copy before it goes out.","description":"⛔ Refused once the post has gone out — there is nothing to edit. The channel's character limit is enforced here, so a customer typing 400 characters into a Bluesky box is told while they are typing. Gated on `syndication.manage`.","tags":["syndication"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyndicationPostEdit"}}}},"responses":{"200":{"description":"The updated post.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyndicationPost"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/syndication/posts/{postId}/{action}":{"parameters":[{"name":"postId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"action","in":"path","required":true,"description":"`approve` clears a held post for sending, `reject` marks it `skipped` (nothing went wrong — the customer said no), `retry` re-queues a failed one.","schema":{"type":"string","enum":["approve","reject","retry"]}}],"post":{"operationId":"actOnSyndicationPost","summary":"Approve, reject or retry one channel's post.","description":"Approving queues the post for the next sweep; rejecting settles it `skipped` because nothing went wrong; retrying re-queues a `failed` or `needs_reconnect` post — reconnect the account first, or it will settle the same way again. Gated on `syndication.manage`.","tags":["syndication"],"responses":{"200":{"description":"The updated post.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyndicationPost"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/content/posts":{"get":{"operationId":"listContentPosts","summary":"The organisation's content library.","description":"Posts this organisation has written, newest first, each with a count of how many sites it is scheduled or live on. Gated on `links.view` — reading the library is reading.","tags":["links"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"A page of content posts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentPostPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createContentPost","summary":"Write a new post.","description":"Creates a content item. It publishes nowhere until it is given a placement — see `createPostPlacement`. Gated on `links.edit`, the same key the bulk editor uses, because this content is destined for the customer's published pages.","tags":["links"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentPostCreate"}}}},"responses":{"201":{"description":"The created post.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentPost"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/content/posts/generate":{"post":{"operationId":"generateContentPosts","summary":"Write article drafts with the model.","description":"Turns a brief into DRAFT posts in the organisation's own content library, with the customer's anchors placed inside them. ⛔ It never schedules and never publishes — the drafts sit in the library until somebody reads them and creates a placement, which is the same line the hand-written path already draws.\n\nGated on `links.edit`, the same key as writing a post by hand, because that is what this is. Every call is metered on the caller's own organisation — BYO key, then credits, then the included allowance — and is refused with a sentence naming what would clear it if none of the three can pay.\n\n⛔ Anchors are placed VERBATIM and verified after generation. Any the model altered or dropped are named in the draft's `notes`, which the customer reads before scheduling — the platform never silently re-prompts (it would spend their money again) and never silently accepts (it would place a campaign they did not ask for).","tags":["links"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentPostGenerate"}}}},"responses":{"201":{"description":"The drafts that were written.","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ContentPost"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/content/campaigns/plan":{"post":{"operationId":"planContentCampaign","summary":"Price and preview a campaign without creating it.","description":"Resolves the target sites — named ones, or a **site group** expanded at this moment rather than remembered — lays the articles out across the drip window, and returns the whole schedule with the number of articles and publications it will produce. Creates nothing. Gated on `links.edit`.\n\n⚖️ The customer sees this before every campaign, not only above a spending threshold (owner ruling, 2026-09-08). `total_placements` is the honest size: twelve articles across twenty sites is two hundred and forty publications, and quoting `total_articles` alone understates the work and the spend by the number of sites.\n\n`targets.skipped_not_publishable` is always present, including at zero — *\"12 sites\"* and *\"12 of your 40 sites\"* need different actions from the customer.","tags":["links"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"Narrow to one organisation. A reseller managing several client organisations reads the wrong one without it — and on a footprint-free network, another operator's posting schedule *is* their strategy.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentCampaignWrite"}}}},"responses":{"200":{"description":"The plan. Nothing was created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentCampaignPlan"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/content/campaigns":{"get":{"operationId":"listContentCampaigns","summary":"Every campaign, with how far along it is.","description":"The schedule screen's index. Each row carries the counts a customer reads at a glance — queued, done, failed, paused — and when the next article lands. Gated on `links.view`.","tags":["links"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"Narrow to one organisation. A reseller managing several client organisations reads the wrong one without it — and on a footprint-free network, another operator's posting schedule *is* their strategy.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The campaigns.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentCampaignPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createContentCampaign","summary":"Schedule a run of articles across a window.","description":"Creates one queued article per topic, each targeting every site the campaign resolved to, each with its own moment inside the drip window. Gated on `links.edit`.\n\n**Nothing is started by this call.** The articles are queued as `pending` runs and a Temporal sweep starts each when its moment arrives — so the request path carries no long work, generation cost is spread across the window rather than paid upfront, and a campaign created during a Temporal outage is visible and simply starts late.\n\nRefused with 422 when the account is not in good standing: we do not spend money on an account that is not being paid for.","tags":["links"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"Narrow to one organisation. A reseller managing several client organisations reads the wrong one without it — and on a footprint-free network, another operator's posting schedule *is* their strategy.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentCampaignWrite"}}}},"responses":{"201":{"description":"The campaign, with its whole schedule.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentCampaignPlan"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/content/campaigns/{campaignId}":{"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getContentCampaign","summary":"One campaign's queue — what is scheduled, and when each lands.","description":"Every article in the campaign, in the order it will go out, with its topic, its moment and whether it can still be moved. Gated on `links.view`.","tags":["links"],"responses":{"200":{"description":"The campaign.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentCampaign"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/content/campaigns/{campaignId}/pause":{"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"pauseContentCampaign","summary":"Hold every article that has not started.","description":"Holds every queued article. Acts only on articles that have **not started** — one already being written has been paid for, and one already published is on a customer's site, so pausing cannot mean un-publishing and must not appear to. `affected` is how many were actually held, so a screen can say *\"paused 8 of 12\"* rather than reporting a silent success the customer's own queue contradicts. Gated on `links.edit`.","tags":["links"],"responses":{"200":{"description":"How many articles were affected, and the campaign afterwards.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentCampaignActionResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/content/campaigns/{campaignId}/resume":{"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"resumeContentCampaign","summary":"Put the held articles back on the calendar.","description":"Re-spreads any moment that passed while the campaign was held rather than firing the backlog at once — on a network a burst is the footprint the drip exists to avoid. Gated on `links.edit`.","tags":["links"],"responses":{"200":{"description":"How many articles were affected, and the campaign afterwards.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentCampaignActionResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/content/campaigns/{campaignId}/cancel":{"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"cancelContentCampaign","summary":"Drop every article that has not started.","description":"Terminal. Anything already published stays on the customer's sites; cancelling a schedule does not take a live page down. Gated on `links.edit`.","tags":["links"],"responses":{"200":{"description":"How many articles were affected, and the campaign afterwards.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentCampaignActionResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/content/campaigns/{campaignId}/runs/{runId}":{"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"runId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"operationId":"rescheduleContentCampaignRun","summary":"Move one queued article to a different moment.","description":"Refused with 422 once the article has started: its copy already exists and its placements already carry their own times, so \"reschedule\" would quietly mean something else. Gated on `links.edit`.","tags":["links"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["starts_at"],"properties":{"starts_at":{"type":"string","format":"date-time","description":"When this article should be written and placed."}}}}}},"responses":{"200":{"description":"The campaign, with the article moved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentCampaign"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/content/runs":{"get":{"operationId":"listContentRuns","summary":"Multi-site AI posting runs.","description":"Every run this organisation has started, newest first, each with its per-site outcomes. Gated on `links.view`.\n\nA **run** is one *\"write this brief and put it on these sites\"*. It executes as a durable Temporal workflow rather than on a request thread, so a provider outage, a rate limit or a worker restart pauses or retries it instead of losing it. The `state` says where it got to; `totals` says how many sites worked; `items` says what happened to each one and why.","tags":["links"],"parameters":[{"name":"state","in":"query","required":false,"description":"Only runs in this state.","schema":{"$ref":"#/components/schemas/ContentRunState"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"A page of runs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentRunPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createContentRun","summary":"Start a multi-site posting run.","description":"Writes one article from the brief and places it on every site named, eight at a time. Answers **201 immediately** with the run row — the work itself happens on the durable queue, and the run screen shows it progressing. Gated on `links.edit`, the same key as scheduling a post by hand, because that is what this creates.\n\n⛔ `publish_policy` defaults to `draft_only`, so a request that omits it produces scheduled drafts and puts nothing live. `unattended` is the only value that publishes without a human, and it is the mode the durability guarantees are written for.\n\n⛔ Every site id must belong to this organisation. A run naming a site that does not is refused whole with 422 rather than quietly posting to the rest — *\"it only posted to some of them\"* is not a state a customer can act on.\n\nSites that cannot receive a post (suspended, a non-WordPress stack, transferred away) are recorded as `skipped` with a reason and do not stop the run.","tags":["links"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentRunCreate"}}}},"responses":{"201":{"description":"The run, with one item per site, all pending.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentRun"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"description":"The durable queue is unreachable, so nothing was started and no run row was created. Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/content/runs/{runId}":{"parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getContentRun","summary":"One run, with every site's outcome.","description":"The whole run screen in one call. Gated on `links.view`. 404 rather than 403 for a run in another tenant — a 403 would confirm the row exists.","tags":["links"],"responses":{"200":{"description":"The run.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentRun"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/content/runs/{runId}/resume":{"parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"resumeContentRun","summary":"Retry the sites that failed — never the ones that worked.","description":"Puts a paused or partly-done run back to work on **its failures only**. The posts that already published stay published and are never touched again; a site that succeeded cannot be attempted a second time, because duplicate content on a private network is a footprint rather than an inconvenience. Gated on `links.edit`.\n\n⛔ `skipped` items are not revived: a skip means the site is suspended, has no CMS, or has moved to another account, and retrying it would fail identically — or, after a transfer, would publish the previous owner's content onto somebody else's domain.\n\nRefused with 422 if the run is still going, or if nothing failed. Read `resumable` on the run before offering the button.\n\n⛔ Pressing this is usually unnecessary. A paused run re-probes what stopped it and restarts itself the moment the cause is gone — including after a replaced key or a topped-up balance.","tags":["links"],"responses":{"200":{"description":"The run, restarted, with the failed items back to pending.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentRun"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"description":"The durable queue is unreachable; nothing was restarted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/content/run-schedules":{"get":{"operationId":"listContentRunSchedules","summary":"Repeating posting runs.","description":"Every cadence this organisation has set. Gated on `links.view`.","tags":["links"],"responses":{"200":{"description":"The schedules.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentRunSchedulePage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createContentRunSchedule","summary":"Post to these sites every N hours.","description":"Creates a cadence. The first run happens one interval from now, not immediately — a customer setting up a daily schedule at 4pm expects one tomorrow, not one before they have finished reading the form. Gated on `links.edit`.\n\nThe cadence is served by a durable workflow on the worker, not by a job that calls this API back, so a scheduled run behaves identically to one started by hand. Minimum interval is one hour: anything finer on a private network is a footprint.","tags":["links"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentRunScheduleWrite"}}}},"responses":{"201":{"description":"The schedule.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentRunSchedule"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/content/run-schedules/{scheduleId}":{"parameters":[{"name":"scheduleId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"operationId":"updateContentRunSchedule","summary":"Change or pause a cadence.","description":"Any subset of the fields. Setting `enabled` to false stops future runs and leaves every run it has already made alone. Gated on `links.edit`.","tags":["links"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentRunScheduleWrite"}}}},"responses":{"200":{"description":"The updated schedule.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentRunSchedule"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"deleteContentRunSchedule","summary":"Delete a cadence.","description":"Stops future runs. Runs it has already made keep their history and their published posts. Gated on `links.edit`.","tags":["links"],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/content/posts/{postId}":{"parameters":[{"name":"postId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getContentPost","summary":"One post.","description":"The post with its live placement counts. Gated on `links.view`. 404 rather than 403 for a post in another tenant — a 403 would confirm the row exists.","tags":["links"],"responses":{"200":{"description":"The post.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentPost"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"operationId":"deleteContentPost","summary":"Delete a post that is not live anywhere.","description":"Refused with 422 while any placement is `published`: deleting the row here would not remove those pages, only the customer's record of what they published and where. Gated on `links.edit`.","tags":["links"],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/content/posts/{postId}/placements":{"parameters":[{"name":"postId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listPostPlacements","summary":"Where this post is scheduled or live.","description":"Every placement of this post, newest first — which sites it is going to, when, and what happened. Gated on `links.view`.","tags":["links"],"responses":{"200":{"description":"The post's placements.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostPlacementPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"createPostPlacement","summary":"Schedule this post onto one of your sites.","description":"Publishes the post to that site, in that WordPress category, at that time — V1's `PostTask`. The category is a **name**, not a term id, because a term id is per-site and one post goes to many sites. Refused with 409 if the post is already scheduled or live on that site: publishing the same content twice to one site is a duplicate-content footprint on the line whose premise is not leaving one. Gated on `links.edit`.","tags":["links"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostPlacementCreate"}}}},"responses":{"201":{"description":"The scheduled placement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostPlacement"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/content/placements/{placementId}":{"parameters":[{"name":"placementId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"delete":{"operationId":"cancelPostPlacement","summary":"Cancel a scheduled publication.","description":"Refused with 422 once the post is `published` — cancelling a schedule does not take a live page down, and answering 200 would leave the customer believing it had. Gated on `links.edit`.","tags":["links"],"responses":{"200":{"description":"The cancelled placement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostPlacement"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/content/targets":{"get":{"operationId":"listContentTargets","summary":"Which of your sites can receive a post, and why the rest cannot.","description":"Every live site in scope with its **suitability**: can it take an article, and — when it cannot — whose fact that is. Gated on `links.view`.\n\n⛔⛔ `suitability` has five values and the difference between two of them is the whole point of this endpoint. `unsuitable` is **measured**: every adapter was asked which sites it claims and each one declined, so this kind of site genuinely has nowhere to put an article. `unknown` means **we could not determine it** — the box was unreachable, the credential has never been tested, or nothing has checked this site yet. A client MUST NOT render `unknown` as a refusal, MUST NOT silently exclude it from a selection, and SHOULD count it separately in any confirmation (\"9 ready, 3 unchecked\"). Treating \"we could not look\" as \"no\" is the defect this endpoint exists to prevent.\n\n⛔ This endpoint makes **no outbound calls**. Suitability is served from the last stored probe with `checkedAt` beside it, because probing every row of a 500-site page would be an uncached external call in an interactive path. `checkedAt: null` means never checked and MUST be shown as such, not as a fresh result. Use `probeContentTargets` to refresh.\n\n⭐ `requires` takes capability ids a recipe needs; each row then carries `missingCapabilities`, so an editor can grey a site out and say what it cannot do. A site whose capabilities are not established reports **nothing** missing rather than everything missing — for the same reason `unknown` is not `unsuitable`.","tags":["links"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"Narrow to one organisation in a reseller subtree. Can never widen scope.","schema":{"type":"string","format":"uuid"}},{"name":"q","in":"query","required":false,"description":"Match on domain or site name.","schema":{"type":"string"}},{"name":"suitability","in":"query","required":false,"schema":{"type":"string","enum":["ready","needs_setup","unknown","unsuitable","blocked"]}},{"name":"product_line","in":"query","required":false,"schema":{"type":"string"}},{"name":"stack_type","in":"query","required":false,"schema":{"type":"string"}},{"name":"group_id","in":"query","required":false,"description":"Only sites in this site group.","schema":{"type":"string","format":"uuid"}},{"name":"cms","in":"query","required":false,"description":"Only sites whose target is this kind.","schema":{"type":"string","enum":["wordpress","headless_rest","git_static"]}},{"name":"requires","in":"query","required":false,"description":"Comma-separated capability ids a recipe requires, e.g. `cms_target:featured_image,cms_target:category`.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"A page of sites with their suitability.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteTargetPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/content/targets/facets":{"get":{"operationId":"contentTargetFacets","summary":"Filter counts over the whole matching set, not the current page.","description":"Counts per suitability, product line, CMS and site group, computed over **every** site matching the current filters. Gated on `links.view`.\n\n⭐ This is what makes \"select all 214 matching\" a number a customer can trust rather than an extrapolation from the 50 rows on screen. It accepts the same filter parameters as `listContentTargets`.\n\n⛔ The `unknown` count **includes every site that has never been probed**. A facet that counted only stored rows would report `unknown: 0` on an estate where nothing had been checked — a blind instrument reporting that everything is fine.","tags":["links"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"q","in":"query","required":false,"schema":{"type":"string"}},{"name":"suitability","in":"query","required":false,"schema":{"type":"string","enum":["ready","needs_setup","unknown","unsuitable","blocked"]}},{"name":"product_line","in":"query","required":false,"schema":{"type":"string"}},{"name":"stack_type","in":"query","required":false,"schema":{"type":"string"}},{"name":"group_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"cms","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The filter facets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentTargetFacets"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/content/targets/probe":{"post":{"operationId":"probeContentTargets","summary":"Re-check, for real, whether these sites can receive a post.","description":"Contacts each named site's CMS and stores what came back. Gated on `links.edit`, because it makes outbound calls to the customer's own infrastructure.\n\n⛔ Bounded at 100 sites per call and run 10 at a time. A refresh over a whole estate would be a self-inflicted outage; the picker refreshes what is on screen.\n\n⛔ A site that could not be reached comes back `unknown`, never `unsuitable`, and a credential the CMS refused comes back with reason `no_credential` — the site is perfectly capable and we are the ones who cannot get in.","tags":["links"],"parameters":[{"name":"requires","in":"query","required":false,"description":"The same comma-separated capability ids `listContentTargets` takes, so a client re-rendering rows from this response gets the same `missingCapabilities` it would get from a refetch. Omitted, every row reports nothing missing **because nothing was asked** — not because nothing is.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["site_ids"],"properties":{"site_ids":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","format":"uuid"}}}}}}},"responses":{"200":{"description":"What each probe found.","content":{"application/json":{"schema":{"type":"object","required":["items","checked"],"properties":{"checked":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/SiteTarget"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/content/link-sets":{"get":{"operationId":"listLinkSets","summary":"Your reusable link sets — the URLs you build links to, and the words for each.","description":"A link set is a named list of destinations and, for each one, every anchor text you want used for it. Recipes point at a set rather than carrying their own copy, so a URL that changes changes in one place. Gated on `links.view`.\n\nEach row carries a `distribution`: the resolved share of every (URL, wording) pair, summing to 100. That is computed by the **same** function a recipe run uses, so the preview on screen and the links actually placed cannot disagree. When the shares cannot be resolved, `distribution` is empty and `distribution_error` says why — the two are separate fields because an empty list also means \"this set has no links\", and one value for two facts is not an answer.","tags":["links"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"include_archived","in":"query","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"The customer's link sets.","content":{"application/json":{"schema":{"type":"object","required":["items","total"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/LinkSet"}},"total":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createLinkSet","summary":"Create a link set.","description":"Gated on `links.edit`. Shares are optional: leave every one blank and the links rotate evenly; set some and the rest share what is left. A set whose shares cannot be resolved is refused with a sentence naming the total, not a code.","tags":["links"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkSetWrite"}}}},"responses":{"201":{"description":"The created link set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkSet"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/content/link-sets/{linkSetId}":{"parameters":[{"name":"linkSetId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getLinkSet","summary":"One link set, with its resolved distribution.","description":"Gated on `links.view`. Carries the same `distribution` the list does — the resolved share of every (URL, wording) pair, computed by the function a recipe run actually uses, so the preview and the placements cannot disagree.","tags":["links"],"responses":{"200":{"description":"The link set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkSet"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"operationId":"updateLinkSet","summary":"Rename a link set, archive it, or replace its links.","description":"Gated on `links.edit`. Sending `entries` replaces the whole list. That is safe for a link's placement history because the history is keyed on the URL and wording, not on a row id — so editing the list does not reset how often a link has been used.","tags":["links"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkSetWrite"}}}},"responses":{"200":{"description":"The updated link set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkSet"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"deleteLinkSet","summary":"Delete a link set no recipe is using.","description":"Gated on `links.edit`. Refused with `422` while any recipe still points at this set, and the refusal names those recipes. Deleting one out from under a recipe would leave it running, costing credits, and publishing articles with no links in them — so archiving is offered instead.","tags":["links"],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/content/external-sites":{"get":{"operationId":"listExternalSites","summary":"WordPress sites you connected that we do not host.","description":"Sites on somebody else's hosting that you have connected so we can publish to them. They appear in your Sites list badged **External** and they consume no hosting allowance. Gated on `links.view`.\n\nEach row carries its `backup` state, so a screen listing a customer's external estate does not have to ask `GET /v1/sites/{siteId}/external-backup` once per row.\n\n⛔ This description said an external site has *\"no server, backup or SSH controls\"* until 2026-09-09. That was true when it was written on 2026-08-22 and the owner ruled the opposite into existence six days later: backups for sites we do not host are a shipped, priced product (three tiers, `external_backups`). A UI deciding what to render from this sentence would have hidden a feature the customer is paying for.","tags":["links"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The connected external sites.","content":{"application/json":{"schema":{"type":"object","required":["items","total"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ExternalSite"}},"total":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"connectExternalSite","summary":"Connect a WordPress site we do not host, with an application password.","description":"Gated on `links.edit`. The credential is **verified against the site before anything is stored**: if WordPress refuses it, nothing is created and the error says what to fix. The password goes to Vault; no secret is stored on the row.\n\nGenerate the application password in that site's WordPress admin under Users → your user → Application Passwords. The user needs to be able to publish posts.","tags":["links"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","username","application_password"],"properties":{"url":{"type":"string","description":"The site's address, e.g. `https://example.com` or `https://example.com/blog`."},"username":{"type":"string"},"application_password":{"type":"string","description":"The application password WordPress generated. Spaces are ignored, so it may be pasted exactly as displayed."},"name":{"type":"string"}}}}}},"responses":{"201":{"description":"Connected and verified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalSite"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/content/external-sites/pairing":{"post":{"operationId":"createConnectorPairing","summary":"A one-time code for the Zinn® connector plugin.","description":"Gated on `links.edit`. Install the Zinn® connector plugin on the WordPress site and paste this code into it; the plugin creates its own application password and connects the site, so nothing is copied by hand. The code is single-use and expires in thirty minutes.","tags":["links"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"201":{"description":"A live pairing code.","content":{"application/json":{"schema":{"type":"object","required":["code","expires_at","plugin_slug"],"properties":{"code":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"plugin_slug":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/content/external-sites/{siteId}":{"parameters":[{"name":"siteId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"delete":{"operationId":"removeExternalSite","summary":"Remove a connected site we do not host.","description":"Forgets the site: its publishing credential and any backup credential are deleted from our secret store, the site leaves every list, and no lost-connection notice is sent for it again — including by a check already in flight. Monthly add-ons bought for the site stop billing. Backups of it we already hold stay downloadable until 30 days after they were taken and are then deleted; copies in the customer's own offsite storage are left there. Nothing on the site itself is changed. Gated on `links.edit`.","tags":["links"],"responses":{"200":{"description":"What removal did.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalSiteRemoval"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/content/external-sites/{siteId}/verify":{"parameters":[{"name":"siteId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"verifyExternalSite","summary":"Re-check the credential on one connected external site, now.","description":"Gated on `links.edit`. The same check runs daily on its own; this is the button for a customer who has just fixed something and does not want to wait.\n\n`422` (`VERIFY_INCONCLUSIVE`) means we could not check the site just now — the probe has no healthy outbound route and never falls back to a direct call (docs/765 §9). The stored verdict stands and no e-mail is sent; try again later.","tags":["links"],"responses":{"200":{"description":"What the site said.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalSite"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/connector/claim":{"post":{"operationId":"claimConnectorPairing","summary":"Redeem a pairing code — called by the Zinn® WordPress connector plugin.","description":"**Unauthenticated by necessity**: the caller is a WordPress plugin on the customer's own server, which has no session with us. The pairing code identifies the organisation, is single-use, and expires in thirty minutes. The credential it carries is verified against the site before anything is stored.\n\nEvery invalid-code failure returns the same sentence, so a caller cannot use this endpoint to discover whether a code exists.","tags":["links"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code","site_url","username","application_password"],"properties":{"code":{"type":"string"},"site_url":{"type":"string"},"username":{"type":"string"},"application_password":{"type":"string"},"site_name":{"type":"string"}}}}}},"responses":{"201":{"description":"The site is connected.","content":{"application/json":{"schema":{"type":"object","required":["site_id","primary_domain","detail"],"properties":{"site_id":{"type":"string","format":"uuid"},"primary_domain":{"type":"string"},"detail":{"type":"string"}}}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/connector/backup/claim":{"post":{"operationId":"claimConnectorBackupJob","tags":["hosting"],"summary":"Ask whether a backup is due — called by the Zinn® WordPress connector plugin.","description":"**Unauthenticated by session, authorised by a per-site bearer token** minted when the customer connected the site. The caller is PHP on a server we have never seen and has no session with us.\n\nReturns either a job (`job_id` plus a short-lived presigned upload URL) or an empty object meaning *nothing due*. The plugin polls hourly and streams the archive straight to object storage, so it never passes through our servers.\n\n⛔ **A wrong or unknown token returns `200` with an empty body, exactly like \"nothing due\".** That is deliberate and is the opposite of what an API normally does: a `401` would confirm to an unauthenticated caller that a given site is enrolled for backups, and this route is reachable by anyone. The plugin cannot tell the two apart either, and does not need to.","security":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"site_url":{"type":"string","description":"The plugin's own view of the site address, for diagnostics only."}}}}}},"responses":{"200":{"description":"A job to run, or an empty object when nothing is due.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBackupJob"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/connector/backup/complete":{"post":{"operationId":"completeConnectorBackupJob","tags":["hosting"],"summary":"Report a finished backup — called by the Zinn® WordPress connector plugin.","description":"Settles the job the plugin claimed. Same bearer token, same silent treatment of an unknown one.\n\n⛔ **The reported `size_bytes` is a cross-check, not the record.** We HEAD the stored object ourselves, because a truncated upload that reports success is indistinguishable from a good one until somebody tries to restore it — and because a site could otherwise report `uploaded` having written nothing, leaving a restore button over an object that does not exist.\n\nA `failed` report settles the row so it is not left running for ever. The detail is kept for staff and never shown to the customer: it is untranslated English and can carry a filesystem path from their server.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorBackupCompletion"}}}},"responses":{"200":{"description":"Accepted. The body is empty in every case.","content":{"application/json":{"schema":{"type":"object"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/connector/status":{"get":{"operationId":"getConnectorStatus","tags":["hosting"],"summary":"Is this site's connector credential still live? — called by the Zinn® WordPress plugin.","description":"**Unauthenticated by session, authorised by the per-site bearer token** minted when the customer connected. The caller is PHP on a server we have never seen.\n\n⛔ Unlike `/v1/connector/backup/claim`, this endpoint DOES distinguish a good token from a bad one, and that is not a regression of that decision — it is a different question. It says nothing about a site: it says whether **the token the caller already holds** is live, which is exactly what the legitimate holder needs and is worth nothing to anybody else. Learning one bit about somebody else's site would require possessing their token first.\n\n⛔ A refused account and an outage are different answers with different remedies, so a refusal carries `refused: true` and a `reason` written for the site owner (CLAUDE.md §2.57). The plugin shows the reason and links to billing; it never reports a suspension as an outage or an outage as a suspension.","security":[],"responses":{"200":{"description":"What we know about this token.","content":{"application/json":{"schema":{"type":"object","required":["connected"],"properties":{"connected":{"type":"boolean","description":"Whether the presented token is live. False for an unknown one."},"org":{"type":"string","description":"The organisation this site belongs to. Empty when unreadable."},"refused":{"type":"boolean","description":"Present and true when the account may not currently publish."},"reason":{"type":"string","description":"Why, written for the site owner. Only set alongside `refused`."}}}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/connector/diagnostics":{"post":{"operationId":"sendConnectorDiagnostics","tags":["hosting"],"summary":"A support report a site owner chose to send — called by any Zinn® WordPress plugin.","description":"⚖️ Owner ruling 2026-09-08, asked directly: the plugin shows the customer **exactly what will be sent, redacted, before they press send**. Declared secrets are omitted from the payload entirely rather than blanked, and the preview is the same bytes as the request body.\n\n⛔ **Unauthenticated by design.** The customer most in need of sending a report is the one whose credential has just been revoked, so requiring the token would refuse exactly the population the feature exists for. A token, when present, ATTRIBUTES the report to an org and opens a real support ticket on that org's queue; without one the report is logged against the returned reference for an agent to find.\n\nThe report is stored and never executed, never rendered as markup and never used to look anything up — it is written by PHP on a server we do not control.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["plugin","report"],"properties":{"plugin":{"type":"string","maxLength":64,"description":"The plugin slug that built the report."},"report":{"type":"object","additionalProperties":true,"description":"The report body, as previewed to the customer."}}}}}},"responses":{"200":{"description":"Accepted.","content":{"application/json":{"schema":{"type":"object","required":["received","reference"],"properties":{"received":{"type":"boolean"},"reference":{"type":"string","description":"The support reference to quote. Returned even if the ticket could not be opened."}}}}}},"413":{"description":"The report is larger than we accept.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/content/target-presets":{"get":{"operationId":"listCmsPresets","summary":"The headless CMS products we can publish to, and what each can carry.","description":"The catalogue the set-up screen offers — Payload, Strapi, Directus, Ghost, Shopify, Webflow and a custom endpoint — each with the capabilities that product actually supports and a hint telling the customer where to find their key. Gated on `links.view`.\n\n⛔ The capability sets genuinely differ and are not decoration. Ghost is the only one with a first-class canonical-url field; Webflow claims almost nothing because a Webflow collection's fields are whatever the designer made them, and sending a field that does not exist is a validation error the customer cannot act on.","tags":["links"],"responses":{"200":{"description":"The CMS catalogue.","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CmsPreset"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/sites/{siteId}/cms-target":{"parameters":[{"name":"siteId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getSiteCmsTarget","summary":"Where this site's posts go.","description":"The site's content target. Gated on `links.view`.\n\n⛔ A site with no configured target is **200, not 404**. Most WordPress sites on our own fleet need no configuration at all — we hold a managed shell on the box, so the target is derived from the site — and the response then describes that derived target and its capabilities with `hasCredential: false`. Treating \"no row\" as \"no target\" would report most of the estate as unconfigured.\n\n⛔ No secret is ever returned, in any form — not masked, not last-four. `hasCredential` is a boolean and the only consumer of the value is the adapter making the call.","tags":["hosting"],"responses":{"200":{"description":"The site's target.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCmsTarget"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"operationId":"setSiteCmsTarget","summary":"Tell us where this site's posts should go.","description":"Creates or replaces the site's content target. Gated on `links.edit`.\n\n⛔ `secret` is write-only, and **omitting it keeps the credential you already have** rather than clearing it — a customer editing a collection name must not silently delete their key. The secret is written to Vault **before** the row is saved, and the row is only written if that succeeded: the other order leaves a row that reads as configured on every screen and fails at the first publish.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCmsTargetWrite"}}}},"responses":{"200":{"description":"The saved target.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCmsTarget"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"deleteSiteCmsTarget","summary":"Stop publishing to this site's CMS.","description":"Removes the target and deletes its credential from Vault. Gated on `links.edit`. Posts already published are not touched.","tags":["hosting"],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/sites/{siteId}/cms-target/test":{"parameters":[{"name":"siteId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"testSiteCmsTarget","summary":"Check the credential actually works, against the real CMS.","description":"Contacts the site's CMS with the stored credential and records what happened. Gated on `links.edit`.\n\n⭐ **This is what promotes a target from \"configured\" to \"ready\".** A preset we shipped from a vendor's documentation is a claim; a probe against the customer's own instance is a measurement, and nothing in the picker reads green until this has answered.\n\n⛔ A failure here is a 200 carrying `reachable: false` and a reason, not an error status. \"We could not reach it\" is the answer to the question that was asked.","tags":["hosting"],"responses":{"200":{"description":"What the probe found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CmsTargetProbeResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/link-edits":{"get":{"operationId":"listLinkEdits","summary":"Bulk edits this organisation has run.","description":"The history, newest first — what was changed, when, by how much, and whether it has been undone. Gated on `links.view`, because reading what was done is reading.","tags":["links"],"parameters":[{"name":"target_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Only edits against this target."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"The edit history page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkEditPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createLinkEdit","summary":"Change or remove a target's links across the network.","description":"**The one write in this feature, and the most consequential single action in the customer surface**: it rewrites published content on every site that links to the target. It is therefore gated on its own permission, `links.edit`, which `links.view` does not imply and which the `read_only` role does not hold.\n\n**Returns `202`, never the result.** Two hundred sites is minutes of work on the boxes; holding the request open is the uncached hot-path work CLAUDE.md 2.16 forbids. Poll `getLinkEdit` and read each site's outcome from `items`.\n\n**How the change is made.** Each item is one exact `<a>` tag on one site, replaced by a whole-site string replacement. That is what makes the edit *idempotent* (the second run finds nothing), *reversible* (`undoLinkEdit` swaps the two strings) and cheap on a large site (no post content is ever read back). Only the `href` — and the text, if you supply one — changes: `rel=\"nofollow\"`, `target` and the theme's classes are carried through byte for byte, because for a PBN operator dropping a `rel` across two hundred sites is a change to what the link *does*.\n\n**`unlink` keeps the words.** The tag is replaced by its inner HTML, so an image link leaves the image and a bold anchor leaves the bold.\n\n**A host with no managed command is `unsupported`, not failed.** this platform exposes no shell, so those sites report that per item and the rest of the network still changes.","tags":["links"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkEditRequest"}}}},"responses":{"202":{"description":"The edit was planned and started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkEdit"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/link-edits/{editId}":{"parameters":[{"$ref":"#/components/parameters/LinkEditId"}],"get":{"operationId":"getLinkEdit","summary":"One bulk edit, and what happened on every site.","description":"Poll this while `status` is `pending` or `running`. Each entry in `items` is one site, and it carries the exact strings that were replaced — an edit screen that reports \"197 links changed\" and cannot show you one of them is asking to be trusted rather than checked.\n\nGated on `links.view`: reading what was done is reading.","tags":["links"],"responses":{"200":{"description":"The edit and its per-site items.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkEdit"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/link-edits/{editId}/undo":{"parameters":[{"$ref":"#/components/parameters/LinkEditId"}],"post":{"operationId":"undoLinkEdit","summary":"Put back exactly what a bulk edit replaced.","description":"Reverses the items that actually **applied** — a `stale` item is not reversed, because re-inserting a link the customer had already removed themselves would be a change nobody asked for, and a failed item never wrote anything to put back.\n\nOnce. A second undo would reverse the first and put the original change back, which is the opposite of what the button says, so it is a `409`.","tags":["links"],"responses":{"202":{"description":"The undo was planned and started. It is itself an edit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkEdit"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/vitals/checks":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"startSiteVitalsCheck","summary":"Measure one page of this site on demand.","description":"`getSiteVitals` measures the **homepage** on a schedule, which makes the product descriptive. This makes it diagnostic: *\"the homepage is fine, it is `/shop/category/boots` that is slow\"*. Gated on `sites.view` — asking how fast your own page is changes nothing about it.\n\n**Returns `202`, never the measurement.** A Lighthouse run takes 10-30 seconds; holding the request open is the uncached hot-path work CLAUDE.md 2.16 forbids and it times out behind Cloudflare. Poll `getSiteVitalsCheck` with the returned `id` until `status` is `done` or `failed`.\n\n**A URL outside this site is a `404`, not a `403`.** A 403 would confirm that some other organisation owns that hostname, turning this endpoint into an ownership oracle over the estate. The submitted address may be a path (`/shop/boots`), a bare hostname, or an absolute URL; it is normalised — lowercased, port and trailing dot stripped, leading `www.` folded — before being compared against the site's `primary_domain` and its aliases. The URL that comes back is rebuilt on whichever of the site's own hostnames matched, **not** on the folded form and not on what was typed: a site that lives on `www.` is measured on `www.`, because the apex may 301 or not resolve at all. Clients should display the returned `url`.\n\n**A recent identical check is returned instead of starting a new one.** Within the cache window the stored measurement comes back with `cached: true` and `status` already `done`, and it costs no quota. Clients should render `measured_at` rather than implying the page was just re-measured.\n\n**A check of the same URL that is still running is returned too** — same `202`, `cached: false`, `status` `queued` or `running`. A double-click is therefore one measurement and one quota unit, not two. Clients get an `id` to poll either way, so no branch on this is needed; it is documented because the `id` may be one the caller has already seen.\n\n**A check that has not finished within the staleness window is reported `failed`** with `error_code: timed_out`, by the read path rather than by a writer. Nothing writes a terminal status when a workflow is cancelled or its task queue has no worker, so a client that waits for one would poll a `running` check for ever.\n\n**`429` when the organisation's daily allowance is spent**, with `Retry-After` and a body naming the limit. The allowance exists because one customer in a refresh loop would otherwise burn the whole estate's shared PageSpeed quota and take a free feature down for everyone. Cached results never count against it.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VitalsCheckRequest"}}}},"responses":{"202":{"description":"The check was accepted and is running — or, when `cached` is `true`, a recent measurement of the same URL is returned already complete.\n\nThe remaining allowance is in the **body** as `remaining_today`, not in a `RateLimit-Remaining` header: neither of these operations emits one, and §2.5 makes this document the contract rather than a wish.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VitalsCheck"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/vitals/checks/{checkId}":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"checkId","in":"path","required":true,"description":"The check id returned by `startSiteVitalsCheck`.","schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getSiteVitalsCheck","summary":"Poll one on-demand page check.","description":"Returns the check's current `status` and, once it is `done`, the measurement inline as `result` — the same shape `getSiteVitals` returns, so a client renders one component for both.\n\nScoped to the organisation **and** the site, so a check id belonging to another of the caller's own sites does not resolve here either: the poll URL must not become a way to enumerate what else has been measured.\n\n`failed` carries an `error` sentence written for a customer to act on — a page that is unreachable, blocked to crawlers, or redirecting. It is never a stack trace.","tags":["hosting"],"responses":{"200":{"description":"The check's current state. The remaining allowance is in the body as `remaining_today`; this operation emits no `RateLimit-Remaining` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VitalsCheck"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/i18n/sources":{"post":{"operationId":"registerTranslationSources","summary":"Register translatable source fields (batch).","description":"Registers (or updates) source fields for auto-translation into every enabled locale (CLAUDE.md §2.19, docs/28). Each item is keyed by `(surface, object_ref, field)` within the calling organization; the org is taken from the credential and can never be set from the body.\n\n**Batched by design.** One CMS page save touches on the order of 150 translatable fields (body blocks, meta title/description, OpenGraph, JSON-LD text, alt text, breadcrumb labels, the slug). A per-field request would turn a single editorial save into 150 round-trips, so the endpoint takes up to 200 items per call; more than that is a `422` asking the caller to split the batch.\n\n**Intrinsically idempotent — an `Idempotency-Key` is accepted but not needed.** Registration is keyed on a SHA-256 of the source text: when the content hash is unchanged the call is a complete no-op (nothing is marked stale, no re-translation event is emitted, `changed` comes back `false`). Replaying the same batch therefore costs nothing and changes nothing, so unlike every other unsafe endpoint here this one needs no replay protection to be safe. The header is still accepted so that clients and generated SDKs can send it uniformly across all writes.\n\nTranslation runs asynchronously afterwards — a successful response means the source is recorded and (if it changed) queued, never that any locale is translated yet. Poll `GET /v1/i18n/bundles/{locale}` or watch the `translation.completed` events.","tags":["localization"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslationSourceBatch"}}}},"responses":{"200":{"description":"Every item was registered. Items whose content was unchanged report `changed: false` and did nothing.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslationSourceBatchResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/i18n/repo-translations":{"post":{"operationId":"recordRepoTranslations","summary":"Record translations the repository committed (batch).","description":"i18n fix A (2026-10-16): when a lane commits a translation into the repository after the engine translated the SAME English, the repository's copy wins, and the export (`scripts/i18n-sync.mjs export`) hands it back here so the engine and the repo hold one truth. Each item is accepted only while `source_hash` still equals the string's current English hash; an item whose English moved on (`stale`) or whose string is unknown (`missing`) is reported and left alone, so a changed source keeps re-translating through the ordinary batched pipeline (CLAUDE.md §2.19). An accepted row is `up_to_date`, its `translated_at` is now, and it is attributed `repo` — indistinguishable from any other translation to every consumer. Idempotent: the same text again changes nothing. An item whose text drops a required term rendering for its locale (`engine/engine/i18n/term_renderings.py`, e.g. de \"Zinn® Managed WordPress\") is `refused` and left alone: a pin outranks the repository, exactly as it outranks a new machine answer.","tags":["localization"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":200,"items":{"type":"object","required":["surface","object_ref","field","locale","text","source_hash"],"properties":{"surface":{"type":"string","maxLength":32},"object_ref":{"type":"string","maxLength":255},"field":{"type":"string","maxLength":64},"locale":{"$ref":"#/components/schemas/LocaleCode"},"text":{"type":"string","minLength":1},"source_hash":{"type":"string","minLength":64,"maxLength":64}}}}}}}}},"responses":{"200":{"description":"How many items were recorded, already equal, stale, unknown or refused.","content":{"application/json":{"schema":{"type":"object","required":["recorded","unchanged","stale","missing","refused"],"properties":{"recorded":{"type":"integer"},"unchanged":{"type":"integer"},"stale":{"type":"integer"},"missing":{"type":"integer"},"refused":{"type":"integer","description":"Items whose text breaks a term rendering pinned for its locale; the engine's row is kept unchanged."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/i18n/bundles/{locale}":{"parameters":[{"name":"locale","in":"path","required":true,"description":"The target locale to build a bundle for (docs/28 registry code), or an app-tier locale (`sv`, `is`, `pt-PT`; docs/28 \"App-tier locales\") for the strings kept in the app tier, such as the customer dashboard catalogue.","schema":{"$ref":"#/components/schemas/LocaleCode"}}],"get":{"operationId":"getTranslationBundle","summary":"Get every translated string for one locale.","description":"Returns the calling organization's translated strings for `locale`, grouped by `object_ref` then `field` — the read a site build or an SSR render performs to populate a locale.\n\n**Last-good-while-stale.** An entry's `text` is returned whenever it is non-empty, *regardless of its `status`*: the store retains the previous translation while a re-translation is in flight, and serving that is better than serving an English string (or nothing) on a localized page. The per-entry `status` is exposed so the caller decides — a production build may accept `stale`, a release gate may refuse anything that is not `up_to_date`. Entries with no text yet are omitted entirely rather than returned blank.\n\n**Deliberately NOT cursor-paginated — a documented deviation from the rest of this API.** Every other collection here is cursor-paginated, and that is the right default for tenant data that grows without bound. This corpus is different: it is our own bounded, self-owned content, read as a single unit at build time. Paginating it would turn one build into hundreds of sequential round-trips *per locale* (58 locales × pages), for no isolation or performance benefit. Instead the response is bounded by a hard server-side cap; a bundle that would exceed it is a `422` naming the cap and telling the caller to narrow with `surface` or `object_ref_prefix` rather than silently truncating.\n\nCacheable: responses carry a strong `ETag` over the bundle contents plus `Cache-Control: public, max-age=60`. Send `If-None-Match` to get a `304` and skip the transfer entirely.\n\nRate limits: the per-principal `user` rate and the per-tenant `org` rate, except that an API key of the platform org itself (the public-site build) reads under its own `i18n_read_internal` bucket instead of `user`.","tags":["localization"],"parameters":[{"name":"surface","in":"query","required":false,"description":"Comma-separated list of surfaces to include (e.g. `page,meta_title`). All surfaces when omitted. An unknown surface is a `422`.","schema":{"type":"string","maxLength":512},"example":"page,meta_title,meta_description"},{"name":"object_ref_prefix","in":"query","required":false,"description":"Only include entries whose `object_ref` starts with this prefix (e.g. `kb_article:` or `page:pricing`). Narrows a bundle that would otherwise exceed the entry cap.","schema":{"type":"string","maxLength":255},"example":"kb_article:"},{"name":"object_ref","in":"query","required":false,"description":"Comma-separated list of exact `object_ref` values (at most 100). Fetches a **group** of documents in one request.\n\nThis exists because a prefix cannot express a group and one request per document cannot be afforded. One locale's `page` surface is ~7,900 entries against the 5,000-entry cap, so `?surface=page&object_ref_prefix=page:` is always a `422`; the marketing-page fetcher (`scripts/i18n-pages.mjs`) asks for 20 documents at a time instead of issuing 3,591 round-trips per site build.","schema":{"type":"string","maxLength":8192},"example":"page:pricing,page:hosting"},{"name":"limit","in":"query","required":false,"description":"Page size. **Sending this (or `cursor`) opts into paging**; send neither and the response is the whole bundle, with the `422` above when it exceeds the cap. Clamped to the 5,000-entry cap; a non-integer or a value below 1 is a `422` rather than a silent default, because `?limit=all` quietly meaning 5,000 is how a client comes to believe it read a collection it truncated.","schema":{"type":"integer","minimum":1,"maximum":5000},"example":5000},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page, passed back verbatim. Opaque — a cursor this endpoint did not issue is a `422`, never a silent restart, which would loop a caller forever on plausible-looking first pages.\n\nKeyset over `(surface, object_ref, field)`, **not** over `id` like every other collection in this API. That key is the uniqueness the model already declares, it is the order the response is grouped in, and it makes a page boundary predictable from the key names — so \"did page 2 arrive?\" is a question a human can check on a screen instead of having to trust.\n\n**Why paging exists on an endpoint documented as unpaginated.** The cap was sized for the `page` surface and inherited by the dashboard console's `ui` surface, which passed 5,000 keys on 2026-08-17 and from that moment could not be read at all — by the freshness gate or, on the same call site, by the nightly export that is the only path a finished translation takes into the repo. Raising the number moves the wall; this removes it. The original objection (\"hundreds of round-trips per locale ×58\") holds at a small page size and not at one equal to the cap, where 5,031 entries is two requests.","schema":{"type":"string","maxLength":512}},{"name":"If-None-Match","in":"header","required":false,"description":"A previously returned `ETag`; a match responds `304`.","schema":{"type":"string","maxLength":256}}],"responses":{"200":{"description":"The bundle for this locale.","headers":{"ETag":{"description":"Strong validator over the bundle contents.","schema":{"type":"string"}},"Cache-Control":{"description":"Always `public, max-age=60`.","schema":{"type":"string"}},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslationBundle"}}}},"304":{"description":"The bundle is unchanged since the supplied `If-None-Match`.","headers":{"ETag":{"description":"The unchanged validator.","schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"description":"An unknown `locale`/`surface`, or the bundle exceeds the server's entry cap — narrow it with `surface` or `object_ref_prefix`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/i18n/slugs":{"get":{"operationId":"listTranslatedSlugs","summary":"Get translated URL slugs for every locale.","description":"Returns the calling organization's translated public URL slugs, keyed by the canonical (source-locale) identifier then by locale — what the public frontend needs to build locale-routed URLs and `hreflang` alternates (CLAUDE.md §2.19, docs/28, docs/30).\n\nReads the `slug` surface only.\n\n**Every emitted value is a valid URL path.** The stored translation is normalised on the way out — case-folded to lower case, inner whitespace and underscores collapsed to single hyphens, NFC — and a value that is still not a usable path after that (most often a model answer that lost one of the source's `/` separators, so it names a different route) is **omitted rather than emitted broken**. The caller then falls back to the canonical URL, which is a live, indexable page; publishing the broken form would advertise a URL the router cannot resolve.\n\nThis was added by W24-B on 2026-08-20 (`docs/72` D12010) after measuring that **694 of 4,043** settled page slugs were values the public site's own validator refused — `\"Über uns\"`, `\"Относно\"` — every one `up_to_date`, every one counted complete on the admin Translation Status dashboard, and not one of them reachable by any reader in any language.\n\n**A locale's slug is emitted ONLY when its status is `up_to_date`.** This is stricter than `GET /v1/i18n/bundles/{locale}`, and deliberately so: a URL is not a string on a page, it is an identity. Publishing a slug that is still `stale`/`translating` means publishing a URL that will change again within minutes — every link, share and crawl against the interim URL then 404s or bounces through a redirect, which costs real link equity and manufactures redirect churn on exactly the pages SEO cares about. A locale whose slug is not yet settled is simply absent from the response, and the caller falls back to the canonical URL until it is.","tags":["localization"],"parameters":[{"name":"object_ref_prefix","in":"query","required":false,"description":"Only include slugs whose canonical id starts with this prefix.","schema":{"type":"string","maxLength":255},"example":"page:"},{"name":"limit","in":"query","required":false,"description":"Page size, in slug ROWS (one per `object_ref` × locale). **Sending this (or `cursor`) opts into paging**; send neither and the response is the whole map, with a `422` when it would exceed the 5,000-row cap. Paging exists because a site's slug population grows with its pages (a reviews site passed the cap on 2026-09-26 and the export of EVERY site's slugs failed on it) — the cap is a per-request bound, never a bound on what a caller can read. Clamped to 5,000; a non-integer or a value below 1 is a `422`.","schema":{"type":"integer","minimum":1,"maximum":5000}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page, passed back verbatim. Opaque; a cursor this endpoint did not issue is a `422`. Keyset over `(object_ref, locale)`, so rows written while a caller walks the pages are neither skipped nor repeated. An `object_ref`'s locales may span two pages — merge them per `object_ref`.","schema":{"type":"string","maxLength":1024}}],"responses":{"200":{"description":"The translated slug map.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslatedSlugs"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/i18n/catalogues/{locale}":{"parameters":[{"name":"locale","in":"path","required":true,"description":"The target locale (docs/28 registry code).","schema":{"$ref":"#/components/schemas/LocaleCode"}}],"get":{"operationId":"getPublicMessageCatalogue","summary":"Get the public site's UI message catalogue for one locale.","description":"Returns the Zinn® marketing site's own UI strings for `locale`, **nested** in the shape `next-intl` consumes directly — the read `marketplace-web` performs on the server at render time.\n\n**Public, and non-tenant.** Unlike `getTranslationBundle` this needs no credential and has no organization scope: it returns the platform's own strings, which are already present in the public HTML of every page in that language. That is also what makes it cacheable by URL at the edge — an `Authorization` header suppresses shared caching, which would put a network round trip on every page render.\n\n**Why it exists next to `getTranslationBundle`.** The bundle is the *build-time* read: authenticated, tenant-scoped, and shaped as `object_ref → field → {text, status}` for a script that re-nests it and commits `messages/<locale>.json`. That made a finished translation wait for a commit, a rebuild and a deploy. This is the *render-time* read, so a finished translation goes live on its own.\n\n**`up_to_date` only** — deliberately stricter than the bundle's last-good-while-stale rule. The site layers this response *over* its committed catalogue, so an omitted key falls back to the committed translation rather than to English; serving stale text here could only replace a good translation with an older one.\n\n**An unknown-to-the-pipeline locale is a `200` with an empty `messages` object, never a `404`.** The caller treats any failure as \"use the committed catalogue\", so a `404` would be indistinguishable from an outage and would report a locale that simply has not been translated yet as the engine being broken.\n\nCacheable: strong `ETag` plus `Cache-Control: public, max-age=300, stale-while-revalidate=86400`. Send `If-None-Match` for a `304`.","tags":["localization"],"security":[],"parameters":[{"name":"If-None-Match","in":"header","required":false,"description":"A previously returned `ETag`; a match responds `304`.","schema":{"type":"string","maxLength":256}}],"responses":{"200":{"description":"The locale's UI catalogue.","headers":{"ETag":{"description":"Strong validator over the catalogue contents.","schema":{"type":"string"}},"Cache-Control":{"description":"Edge caching directives for the render path.","schema":{"type":"string"}},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicMessageCatalogue"}}}},"304":{"description":"The caller's `If-None-Match` matched; no body."},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/i18n/documents/{locale}":{"parameters":[{"name":"locale","in":"path","required":true,"description":"The target locale (docs/28 registry code).","schema":{"$ref":"#/components/schemas/LocaleCode"}}],"get":{"operationId":"getPublicDocumentTranslations","summary":"Get one marketing document's finished translations.","description":"Returns the finished translations for a **single** document, as `field -> text` across the surfaces a rendered page is built from (`page`, `meta_title`, `meta_description`, `alt_text`) — the read the public site performs on the server, per page, at render time.\n\n**Why a second public endpoint next to `getPublicMessageCatalogue`.** They are cached on different keys and answer different questions. The catalogue is one response per locale covering the shell (nav, footer, meta) and is read on every page; this is one response per document per locale, read only by the page it belongs to. Folding them together would churn the shell's cache entry whenever any of 60 marketing pages was retranslated.\n\n**⛔ `object_ref` is required.** One locale's whole `page` surface is ~7,879 entries — the read `scripts/i18n-pages.mjs` batches at build time, and the one that OOM-killed the engine on 2026-08-05. Making the parameter optional would re-create that on a public, unauthenticated URL. A single document is ~131 leaves, which is what makes this safe on a render path behind an edge cache.\n\n**Public and non-tenant**, for the same reasons as the catalogue: the text is already in the page's HTML, and an `Authorization` header suppresses shared caching. **`up_to_date` only** — the site applies this *over* the document the current deploy already serves, so stale text could only replace a good translation with an older one.\n\n**An untranslated document is a `200` with an empty `fields` object, never a `404`** — the caller treats any failure as \"use the build-time document\", so a `404` would be indistinguishable from an outage.\n\nCacheable: strong `ETag` plus `Cache-Control: public, max-age=300, stale-while-revalidate=86400`.","tags":["localization"],"security":[],"parameters":[{"name":"object_ref","in":"query","required":true,"description":"The document, e.g. `page:hosting`. Required — see the description.","schema":{"type":"string","maxLength":256}},{"name":"If-None-Match","in":"header","required":false,"description":"A previously returned `ETag`; a match responds `304`.","schema":{"type":"string","maxLength":256}}],"responses":{"200":{"description":"The document's finished translations.","headers":{"ETag":{"description":"Strong validator over the document's contents.","schema":{"type":"string"}},"Cache-Control":{"description":"Edge caching directives for the render path.","schema":{"type":"string"}},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicDocumentTranslations"}}}},"304":{"description":"The caller's `If-None-Match` matched; no body."},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/i18n/document-sets/{locale}":{"parameters":[{"name":"locale","in":"path","required":true,"description":"The target locale (docs/28 registry code).","schema":{"$ref":"#/components/schemas/LocaleCode"}}],"get":{"operationId":"getPublicDocumentTranslationSets","summary":"Get several marketing documents' finished translations in one call.","description":"The **batched** form of `getPublicDocumentTranslations`: name up to 50 documents with a repeated `object_ref`, get all of their finished translations in one round trip.\n\n**Why it exists (D13732).** `marketplace-web` prerenders every (locale × page) route, and asking for one document at a time cost 100 documents × 58 locales = **5,800** requests per prerender pass — about 23,200 per build once `next build`'s worker processes are counted, against a 600/min budget. Measured in one 20-minute build window on the live engine: **38,322 × `429` against 20,142 served — 65% of the build's document fetches refused**, each one silently degrading a freshly deployed page to the copy committed in `content/site/`. Batched, a locale costs `ceil(100/50)` = **2** calls, so a whole build is ~464 requests.\n\n**⛔ The remedy is a bulk read, never a bigger limit** (CLAUDE.md §2.10). The call count is `ceil(documents/50)`, so it does not move when marketing pages are added — a raised limit would have to be re-derived on the next content push.\n\n**⛔ `object_ref` is required and bounded at 50.** One locale's whole `page` surface is ~7,879 entries; an unbounded read of it on a public URL is the thing this parameter exists to prevent, and a batch is not an exemption from that.\n\n**A document with no finished translations is present and empty, never omitted** — a caller cannot otherwise distinguish \"nothing translated yet\" from \"I forgot to ask for it\", and the second silently serves English.\n\n**Public and non-tenant**, **`up_to_date` only**, and cacheable with a strong `ETag` plus `Cache-Control: public, max-age=300, stale-while-revalidate=86400` — all for the same reasons as the single-document read.","tags":["localization"],"security":[],"parameters":[{"name":"object_ref","in":"query","required":true,"description":"A document, e.g. `page:hosting`. **Repeat it** to ask for several; at most 50 per call. Duplicates are charged once.","explode":true,"style":"form","schema":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","maxLength":256}}},{"name":"If-None-Match","in":"header","required":false,"description":"A previously returned `ETag`; a match responds `304`.","schema":{"type":"string","maxLength":256}}],"responses":{"200":{"description":"The named documents' finished translations.","headers":{"ETag":{"description":"Strong validator over the whole batch's contents.","schema":{"type":"string"}},"Cache-Control":{"description":"Edge caching directives for the build/render path.","schema":{"type":"string"}},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicDocumentTranslationSet"}}}},"304":{"description":"The caller's `If-None-Match` matched; no body."},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/members/invitations":{"get":{"operationId":"listInvitations","summary":"List pending member invitations in scope.","description":"Returns the organization's **pending** invitations. Accepted/revoked invites are omitted. There is no secret in the payload — accept is authorized by the invitee's verified email (register #31). Requires `members.read`.","tags":["members"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"Restrict to one organization in scope (default — the whole subtree).","schema":{"$ref":"#/components/schemas/Uuid"}},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"A page of pending invitations.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitationPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createInvitation","summary":"Invite an email to join an organization with a role.","description":"Invites an **email** (the person need not exist yet — users are Keycloak subjects) to join with a role. The role is validated to be one the inviter is themselves permitted to grant: a role holding any permission the inviter lacks in that organization is refused (422), so `members.invite` is not a ladder to owner. A re-invite of the same email refreshes the pending invite. Emits `member.invited` so the invitation email is sent. Requires `members.invite` in the target org. An address on a domain that never receives mail — the RFC 2606 / RFC 6761 reserved `example.com`, `example.net`, `example.org` (and their subdomains), any `.test`, `.invalid`, `.localhost` or `.example` name, or a single-label domain — is refused with `400` `INVITE_EMAIL_UNDELIVERABLE` before anything is written: no invitation, no invitation email and no sign-in identity are created for it.","tags":["members"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitationCreate"}}}},"responses":{"201":{"description":"The created invitation.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invitation"}}}},"400":{"description":"`INVITE_EMAIL_UNDELIVERABLE` — the address is on a reserved or undeliverable domain (RFC 2606 / RFC 6761), so the invitation email could never arrive. Nothing was written; enter the person's real address. The sentence is keyed (`refusal.invitation.emailUndeliverable`) and rendered in the reader's language.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/members/invitations/mine":{"get":{"operationId":"listMyInvitations","summary":"List the caller's own pending invitations.","description":"The pending invitations addressed to the **caller's verified email**, across every organization. Any authenticated user may read their own invitations — no per-org permission is required (you are not yet a member of the inviting org). An API-key principal has no inbox and receives an empty list.","tags":["members"],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"A page of the caller's pending invitations.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitationPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/members/invitations/{invitationId}":{"delete":{"operationId":"revokeInvitation","summary":"Revoke a pending invitation.","description":"Revokes a pending invitation so it can no longer be accepted. Only a pending invite can be revoked (revoking an accepted one would not un-join the member). 404 (not 403) on an out-of-scope id. Requires `members.invite`.","tags":["members"],"parameters":[{"$ref":"#/components/parameters/InvitationId"}],"responses":{"204":{"description":"Revoked."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Refused — this is the account's last operational way to pay and something is still going to charge it (a live subscription, a scheduled ad-hoc charge, or an active reseller programme). ⚖️ Owner ruling 2026-08-22. A `409` rather than a `422` because the request is well-formed and would be accepted once the customer adds another method, elects to pay by crypto, or cancels what is billing them.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/members/invitations/{invitationId}/accept":{"post":{"operationId":"acceptInvitation","summary":"Accept an invitation addressed to your email.","description":"Accepts an invitation whose email matches the **caller's verified email**, joining the organization with the invited role. The email match is the authorization — there is no secret token. Refuses an expired, revoked, already-accepted, or wrong-email invitation (422). Idempotent on the resulting membership.","tags":["members"],"parameters":[{"$ref":"#/components/parameters/InvitationId"}],"responses":{"200":{"description":"The accepted invitation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invitation"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/pricing/tax-quote":{"post":{"operationId":"quoteTaxDisplay","summary":"What these net prices look like to this customer, after VAT.","description":"⚖️ **Net-constant pricing** (owner ruling 2026-08-04, `docs/34` §2.1a ruling 3, #1482). The advertised figure is **net** and VAT is added on top at the destination rate, so our revenue per sale is identical everywhere: a €10 plan nets €10 whether the buyer is in Germany or Hungary, and their total differs (€11.90, €12.70) because their own rate does.\n\n**A consumer is shown the VAT-inclusive figure; a business with a VIES-validated VAT number is shown net.** `display_mode` says which — read it, never derive it. The discriminator is **validation state**, not \"has typed a VAT number\": an unvalidated number is charged VAT (§2.3), so treating it as a business would understate what the customer pays.\n\n⛔ **This endpoint rates; it never prices.** The caller passes amounts it already holds from the catalogue, so this cannot become a second source of prices that drifts from the first.\n\n⭐ **Both figures always come back**, whichever one leads, so a frontend picks a field rather than multiplying by a rate. A rate applied in TypeScript is a float applied to money (§2.8) *and* a second implementation of the tax rules — one rounding rule away from the invoice, for ever.\n\n⛔ **`indeterminate: true` means the supply could not be rated** (usually a member state with no `TaxRate` row) and the net figure is being returned with `notice: vat_at_checkout`. It is not an error to surface: the charge path refuses in that situation, correctly, but a pricing page that refused would go **blank for a whole country**. In the fallback `gross_total_minor` equals net and is never `0`, so a caller rendering the gross field unconditionally shows the price rather than a free product.","tags":["billing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxQuoteRequest"}}}},"responses":{"200":{"description":"The figures, in both forms, plus which one to lead with.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxQuote"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"description":"A malformed item list, a repeated `ref`, or an unknown currency.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/accounting/xero":{"get":{"operationId":"getMyXeroConnection","summary":"This organization's connection to its own Xero.","description":"Whether this organization has connected its own Xero, which Xero organization it is pointed at, and how many of its invoices are waiting, synced or failed.\n\n⛔ `status` distinguishes three states and they are **not** interchangeable. `not_connected` means they have never connected (or disconnected on purpose); `needs_reconnect` means the link existed and **died** — Xero ends a refresh token after 60 days of inactivity, and it also ends when someone removes our access in Xero. Rendering the second as the first tells a paying customer their connection never existed, and hides the fact that invoices are queuing behind it.\n\n`entitled` is reported whether or not it is true, so the screen can draw an honest upgrade prompt rather than an empty panel. Requires `billing.view`.","tags":["billing"],"parameters":[{"$ref":"#/components/parameters/ActiveOrg"}],"responses":{"200":{"description":"The connection, or `not_connected`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XeroConnection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateXeroConnection","summary":"Change what a connection syncs.","description":"Today the one option is `includeSubclientInvoices`, which is meaningful only for a reseller: with it on, the invoices the reseller raised **to its own clients** are pushed into the reseller's Xero as well as the invoices Zinn® raised to them.\n\n⛔ It never widens the scope to invoices Zinn® raised **directly** to those clients. Those are Zinn®'s own sales, on Zinn®'s legal entity, and are none of the reseller's business — the engine discriminates on the invoice's legal entity owner, not on the organization tree alone. Requires `billing.invoice.manage`.","tags":["billing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/XeroConnectionUpdate"}}}},"parameters":[{"$ref":"#/components/parameters/ActiveOrg"}],"responses":{"200":{"description":"The updated connection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XeroConnection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"disconnectMyXero","summary":"Disconnect this organization's Xero.","description":"Deletes the stored Xero credential and stops syncing. The record of what was already pushed is kept, so the customer can still see which invoices reached their books.\n\n⛔ Invoices waiting to be sent are marked *not sent* rather than held: a deliberate disconnect must not accumulate a hidden backlog that floods their ledger the day they reconnect. This is the opposite of an expired connection, where the queue IS kept. Requires `billing.invoice.manage`.","tags":["billing"],"parameters":[{"$ref":"#/components/parameters/ActiveOrg"}],"responses":{"200":{"description":"Disconnected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XeroConnection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/accounting/xero/connect":{"post":{"operationId":"startXeroConnect","summary":"Begin connecting this organization's Xero.","description":"Returns the Xero authorization URL to send the customer to. The URL carries a signed, short-lived `state` that names the organization and the actor — the callback has no other authority, because Xero redirects a browser to it with no credential of ours.\n\n`409 ACCOUNTING_CONNECTION_REFUSED` means **our** Xero application has no free organization slot, not that the caller did anything wrong. `422 FEATURE_NOT_INCLUDED` means the plan does not include accounting sync and it has not been bought as an add-on. Requires `billing.invoice.manage`.","tags":["billing"],"parameters":[{"$ref":"#/components/parameters/ActiveOrg"}],"responses":{"200":{"description":"Where to send the customer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XeroAuthorizeUrl"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/accounting/xero/oauth/callback":{"get":{"operationId":"completeXeroConnect","summary":"Where Xero returns the customer after they authorize us.","description":"⛔ **Not called by a client** — Xero redirects the customer's browser here, so it is unauthenticated by necessity and all of its authority comes from the signed `state` minted by `startXeroConnect`. A missing, tampered or expired state is refused identically, and told apart only in our logs.\n\nAlways answers with a 302 back to the dashboard rather than JSON, because the caller is a person in a browser. The outcome is carried in the query string.","tags":["billing"],"security":[],"parameters":[{"name":"code","in":"query","required":false,"description":"Xero's authorization code.","schema":{"type":"string"}},{"name":"state","in":"query","required":false,"description":"The signed state minted by `startXeroConnect`.","schema":{"type":"string"}},{"name":"error","in":"query","required":false,"description":"Present when the customer declined on Xero's consent screen.","schema":{"type":"string"}}],"responses":{"302":{"description":"Redirect back to the dashboard with the outcome.","headers":{"Location":{"description":"The dashboard URL, carrying the outcome.","schema":{"type":"string"}}}}}}},"/v1/accounting/xero/sync":{"post":{"operationId":"syncXeroNow","summary":"Push outstanding invoices to Xero now.","description":"Runs a batch immediately instead of waiting for the hourly sweep. Idempotent: every invoice carries a deterministic reference and the engine searches Xero for it before creating anything, so pressing this twice cannot produce two invoices in the customer's books.\n\n`409` means the connection needs reconnecting. Nothing is lost in that state — outstanding invoices stay queued and are sent on reconnect. Requires `billing.invoice.manage`.","tags":["billing"],"parameters":[{"$ref":"#/components/parameters/ActiveOrg"}],"responses":{"200":{"description":"What the run did.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MyXeroSyncRun"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/accounting/xero/invoices":{"get":{"operationId":"listXeroInvoiceLinks","summary":"Which of this organization's invoices are in its Xero.","description":"Every invoice the connection knows about, newest first, with its state and — where it failed or was not sent — the reason.\n\n⭐ States other than `synced` are listed deliberately. An invoice that is simply absent from a list is indistinguishable from one the sync never saw, so a customer could not tell a deliberate skip from a bug. `total` is the true count, which may exceed the number of items returned. Requires `billing.view`.","tags":["billing"],"parameters":[{"$ref":"#/components/parameters/ActiveOrg"}],"responses":{"200":{"description":"The invoice links.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XeroInvoiceLinkList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/entitlements":{"get":{"operationId":"getEntitlementUsage","summary":"What this organization's plan grants, and how much of it is used.","description":"The customer-facing half of entitlement enforcement (#2726). Returns every **counted allowance** the engine refuses on — with `used`, `limit` and `remaining` — and every **boolean feature** it gates on, marked included or not.\n\nA cap the engine refuses on and the customer cannot see is a cap nobody can plan around: the first they learn of it is the moment it stops them. So the numbers here are the same numbers the refusal quotes.\n\n`limit` distinguishes three states (docs/144 §1) and they are **not** interchangeable: `-1` means the plan sold \"unlimited\" and says so; a non-negative integer is a real cap; **`null` means the plan states no cap at all**, which is neither a promise nor a limit and is the normal case — only 8 of 134 live plans state `team_seats`. `enforced` is the single field a client should branch on to decide whether to draw a usage bar.\n\nResolution walks the organization tree: a reseller's client org holds no subscription of its own, so the answer comes from the nearest ancestor that grants one, and `entitling_org_id` names it. Requires `billing.view`.","tags":["billing"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"The organization to report on; defaults to the caller's own.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The organization's allowances, usage and included features.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntitlementUsage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/billing/payment-preferences":{"get":{"operationId":"getPaymentPreferences","summary":"How this account intends to pay.","description":"The crypto election, the nominated primary/backup, and the two derived answers a billing screen must not compute for itself: whether the account can be charged unattended at all, and whether its backup could actually catch the primary's decline.\n\n⛔ Deliberately **not** part of `GET/PUT /v1/billing/profile`, even though it reads and writes the same row. That endpoint is a documented **full replace**, so folding the crypto election into it would mean a customer correcting a typo in their billing address silently switched their account off crypto — surfacing a month later as an unpaid invoice, with nothing in between to notice it.","tags":["billing"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"The organization to read. Omitted or empty means the caller's own.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The account's payment posture.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentPreferences"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"put":{"operationId":"setPaymentPreferences","summary":"Elect (or stop) paying by crypto.","description":"Requires `billing.payment.manage` — the same key that gates adding and removing a payment method, because this **is** a payment-method decision. ⛔ Not `billing.invoice.manage`: it changes what we can charge, not what prints on an invoice.\n\nTurning crypto **off** answers `409` when it is currently the only way the account can be charged and something is still going to charge it. The floor is on the resulting **state**, not on one of the two actions that can breach it — otherwise a customer could satisfy it with crypto, delete their last card, then switch crypto off.","tags":["billing"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"The organization to update. Omitted or empty means the caller's own.","schema":{"$ref":"#/components/schemas/Uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentPreferencesUpdate"}}}},"responses":{"200":{"description":"The updated payment posture.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentPreferences"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"Refused — this would leave the account with no operational way to pay while something is still going to charge it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/billing/profile":{"get":{"operationId":"getBillingProfile","summary":"Get the organization's billing profile.","description":"Returns the customer's one \"Bill to\" block — what renders on the next invoice (docs/34 §2.5). An organization that has never saved one gets a **200 with an empty profile** (every field blank, `updated_at` null), not a 404, so the form always has a shape to render. Requires `billing.view`.","tags":["billing"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"The organization whose profile to read; defaults to the caller's own.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The billing profile (empty if never saved).","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingProfile"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"updateBillingProfile","summary":"Replace the organization's billing profile.","description":"A full replace (PUT) of the editable \"Bill to\" fields; an omitted field resets to blank. `billing_address` (with its required `country`, needed for tax) is the one mandatory member. Editing changes only invoices issued **afterwards** — a past invoice snapshotted the buyer block at issue time and is never rewritten (docs/34 §1.1). `vat_status` is engine-owned (the validate-not-trust flow, §2.3) and is not accepted here; changing `vat_number` resets it to `unvalidated`. Requires `billing.invoice.manage` in the target organization.","tags":["billing"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"The organization whose profile to replace; defaults to the caller's own.","schema":{"$ref":"#/components/schemas/Uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingProfileUpdate"}}}},"responses":{"200":{"description":"The saved billing profile.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingProfile"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/payment-methods":{"get":{"operationId":"listPaymentMethods","summary":"List the stored payment methods in scope.","description":"Returns the caller's stored mandates. Revoked methods are omitted. The gateway-side `customer_ref`/`method_token` are **never** returned — they are the references a charge is made against (CLAUDE.md §2.4).","tags":["billing"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"Narrow the list to one organization. Without it the response is every organization the caller can read, and `PaymentMethod` carries no `org_id`, so a reseller or agency cannot tell whose card is whose — including which one is `is_default`.","schema":{"$ref":"#/components/schemas/Uuid"}},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"A page of payment methods.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentMethodPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"beginPaymentMethodSetup","summary":"Begin adding a payment method (on-session).","description":"Opens a gateway SetupIntent and returns its short-lived `client_secret` for the browser SDK to confirm, completing 3-D Secure there. **No payment method is created by this call** — a mandate is consent, and the row is written only when the gateway confirms it on its webhook (ADR 0011 §3). Requires `billing.payment.manage` in the target organization.","tags":["billing"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentMethodSetupRequest"}}}},"responses":{"201":{"description":"A setup intent the browser can confirm.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentMethodSetup"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/payment-options":{"get":{"operationId":"getPaymentOptions","summary":"The payment rails a purchase in this currency may be settled on.","description":"What the **checkout** screen offers before anything is bought, so a customer picks how to pay instead of discovering after the fact that only a card was tried.\n\nFiltered exactly as `getOrderPaymentOptions` is, by the same function: a rail the operator has switched off is absent; a rail that cannot present `currency` is absent (PayPal presents 24 currencies and Indonesian rupiah is not among them); and a reseller's client receives exactly one entry — their reseller's connected gateway — because that is the only merchant account their money may land in.\n\nA customer who is suspended or overdue is deliberately **not** filtered: paying us is how an account stops being suspended.\n\n`checkoutCart` refuses any `gateway` that is not in this list, so the picker and the charge path read one source.","tags":["commerce"],"parameters":[{"name":"currency","in":"query","required":true,"description":"ISO 4217 code the purchase is priced in.","schema":{"$ref":"#/components/schemas/CurrencyCode"}},{"name":"org_id","in":"query","required":false,"description":"The organization buying. Omit it and the engine uses the one organization where you hold `billing.payment.manage`, and refuses when you hold it in more than one — guessing which reseller's client is buying would be guessing whose merchant account settles it.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The rails available for a purchase in this currency, most-preferred first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentOptions"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/payment-methods/paypal":{"post":{"operationId":"beginPayPalMandateSetup","summary":"Begin saving a PayPal account as a payment method.","description":"Opens a PayPal vault setup token and returns the `approval_url` the buyer must visit to consent. **No payment method is created by this call** — a mandate is consent, and the row is written only once PayPal confirms it, either through `POST /v1/payment-methods/paypal/confirm` when the buyer returns or through PayPal's own `VAULT.PAYMENT-TOKEN.CREATED` webhook (ADR 0011 §3). Requires `billing.payment.manage` in the target organization.\n\nA saved PayPal mandate is chargeable off-session, so it may be nominated as the account's `primary` **or** its `backup` — including as the backup behind a card primary, which the platform charges on PayPal's rail when the card declines.","tags":["billing"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentMethodSetupRequest"}}}},"responses":{"201":{"description":"An opened PayPal vault setup the buyer can approve.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayPalMandateSetup"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/payment-methods/paypal/confirm":{"post":{"operationId":"confirmPayPalMandateSetup","summary":"Finish saving a PayPal account after the buyer approved it.","description":"Exchanges an approved setup token for the permanent vault token and stores the mandate. The organization is read from **PayPal's** answer and must match the caller's, so a setup token belonging to another account cannot be attached here.\n\nIdempotent, and it deliberately races PayPal's `VAULT.PAYMENT-TOKEN.CREATED` webhook: whichever arrives first writes the mandate and the other converges on it, so a buyer whose browser never returns still ends up with a saved method.","tags":["billing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayPalMandateConfirmRequest"}}}},"responses":{"201":{"description":"The stored payment method.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentMethod"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/payment-methods/form-failures":{"post":{"operationId":"reportPaymentFormFailure","summary":"Report that the add-a-payment-method form failed in the browser.","description":"The browser half of the payment form failed — the vendor's script did not load, the form did not mount, or saving broke for a reason that is not the customer's — so nothing reached the gateway and the engine would otherwise never know. The customer is already shown a translated error with a retry; this records the failure (log + `zinn_payment_form_failures_total`) and, when a card-required trial funnel is open for the organization, tells it, so the operator alert names the cause instead of reporting a silent \"card stuck\". Requires `billing.payment.manage` in the target organization. Nothing is charged or stored.","tags":["billing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentFormFailure"}}}},"responses":{"202":{"description":"The failure was recorded.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentFormFailureRecorded"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/payment-methods/form-closures":{"post":{"operationId":"reportPaymentFormClosed","summary":"Report that the customer closed the add-a-payment-method form.","description":"The customer closed the payment form, and whether they ever pressed Save. A form closed with nothing submitted leaves the gateway's setup in the same state as a form that silently broke, so only the browser can tell the two apart. When a card-required trial funnel is open for the organization it is told, and a close with nothing submitted is recorded as the outcome `closed_card_form` instead of alerting the operator with \"card stuck\". A form that broke in the browser is reported separately (`reportPaymentFormFailure`). Requires `billing.payment.manage` in the target organization. Nothing is charged or stored.","tags":["billing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentFormClosed"}}}},"responses":{"202":{"description":"The close was recorded.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentFormClosedRecorded"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/payment-methods/{paymentMethodId}":{"patch":{"operationId":"updatePaymentMethod","summary":"Nominate a stored payment method as primary or backup.","description":"Sets the mandate's account-wide `role`, demoting whichever method held that slot. A method that is not usable (unconfirmed, revoked, or past its printed expiry) is rejected with 422 rather than silently accepted — the customer must not believe their renewals are covered when they are not.\n\nNominating the current primary as backup (or the reverse) **swaps** them atomically, so the account is never left holding two of one slot and none of the other.\n\nPromoting a method that currently has **no role** demotes the outgoing primary to `backup` when — and only when — the backup slot is empty (owner ruling 2026-08-24, #3798). A backup the customer nominated deliberately is never overwritten; the outgoing primary simply loses its role, as before. Without this the account could end up with a primary and no fallback without being told, and the automatic backup-on-decline charge could not fire.\n\n⛔ This operation described a field named `is_default` until 2026-08-25. No such field has existed since roles replaced it — the request schema has required `role` throughout — so the published description named a parameter no client could send (D13613).","tags":["billing"],"parameters":[{"$ref":"#/components/parameters/PaymentMethodId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentMethodUpdate"}}}},"responses":{"200":{"description":"The updated payment method.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentMethod"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"deletePaymentMethod","summary":"Revoke a stored payment method.","description":"Revokes the mandate and clears its default flag. Emits `payment_method.removed` carrying whether this was the organization's **last** mandate, so the customer can be warned rather than discovering it at the next renewal (ADR 0011 §2).","tags":["billing"],"parameters":[{"$ref":"#/components/parameters/PaymentMethodId"}],"responses":{"204":{"description":"Revoked."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Refused — this is the account's last operational way to pay and something is still going to charge it (a live subscription, a scheduled ad-hoc charge, or an active reseller programme). ⚖️ Owner ruling 2026-08-22. A `409` rather than a `422` because the request is well-formed and would be accepted once the customer adds another method, elects to pay by crypto, or cancels what is billing them.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/inbound-email":{"post":{"operationId":"receiveInboundEmail","summary":"Ingest a customer's support reply from the mail edge.","description":"**Unauthenticated by design** — the caller is a Cloudflare Email Routing Worker with no Zinn® credential, so an HMAC over `\"<timestamp>\\n<body>\"` in `X-Zinn-Signature` *is* the authentication. The timestamp is inside the signed material and its skew is bounded, so a captured request cannot be replayed later.\n\nThis is the inbound half of support email. Before it existed the platform sent notifications from an address that accepted mail and discarded it: a customer replied, nothing happened, and neither they nor the waiting staff member was told. The ticket is resolved from a **signed token inside the `Message-ID`** we set on the outbound notification — nothing in the body, the `From` address or any other header selects a tenant, because all of those are chosen by whoever sent the mail.\n\nRedelivery is the normal case, not the exception: email is at-least-once and a lost response guarantees a retry, so a message already filed answers `200` with `duplicate: true` rather than appending a second copy.\n\n⛔ Unlike the gateway webhooks, a message that **cannot be routed is answered `422`**, not `200`. A 2xx tells the Worker to accept the mail, and an accepted message that reaches no ticket is the exact defect this endpoint exists to remove; `422` makes the Worker reject it so the sender's own mail server bounces it back to the customer.","tags":["support"],"security":[],"parameters":[{"name":"X-Zinn-Timestamp","in":"header","required":true,"description":"Unix seconds. Inside the signed material; skew-bounded to five minutes.","schema":{"type":"string"}},{"name":"X-Zinn-Signature","in":"header","required":true,"description":"`sha256=<hex>` HMAC over `\"<timestamp>\\n<body>\"`.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"The parsed message. The signature covers these exact bytes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboundEmail"}}}},"responses":{"200":{"description":"Filed on the ticket (or already filed, on a redelivery) — or HELD by the support spam guard (s1014 TICKETSPAM): a blocked sender, an exact repeat of mail already filed, a flood from one address or an auto-responder loop. A held message is not filed and is logged for staff (`getSupportSpamGuard`); it is still a `200`, because a bounce sent to an auto-responder is what feeds a mail loop.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/InboundEmailResult"},{"$ref":"#/components/schemas/InboundEmailHeld"}]}}}},"400":{"description":"Missing, stale or invalid signature, or an unparseable body."},"422":{"description":"Well-formed and correctly signed, and not routable to an open ticket — no valid token, or the thread is closed. The Worker turns this into an SMTP rejection."},"503":{"description":"Inbound email is not configured on this deployment."}}}},"/v1/webhooks/demo-budget":{"post":{"operationId":"reportDemoBudgetExhausted","summary":"A hands-on demo site reports that one of its AI budgets ran out.","description":"**Unauthenticated by design** — the caller is one of our own hands-on demo WordPress sites (demo.tranzly.io, demo.zinnchat.com, demo.pagebuildersandwich.com, demo.zinnseo.com), which holds no Zinn® credential, so an HMAC over `\"<timestamp>\\n<body>\"` in `X-Zinn-Signature` (its own secret) *is* the authentication; the timestamp is inside the signed material and skew-bounded to five minutes.\n\nFiles ONE `demo.budget_exhausted` event per `(demo, limit, period)` — the event id is derived from those three — which e-mails the owner which demo, which limit, the spend, and step by step how to raise it. A repeat report answers `200` with `duplicate: true` and sends nothing. ⛔ The demo sends enumerated keys and numbers only; every word of the e-mail is the platform's own.","tags":["notifications"],"security":[],"parameters":[{"name":"X-Zinn-Timestamp","in":"header","required":true,"description":"Unix seconds. Inside the signed material; skew-bounded to five minutes.","schema":{"type":"string"}},{"name":"X-Zinn-Signature","in":"header","required":true,"description":"`sha256=<hex>` HMAC over `\"<timestamp>\\n<body>\"`.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DemoBudgetReport"}}}},"responses":{"200":{"description":"Filed (or already filed for this demo, limit and period).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DemoBudgetReportResult"}}}},"400":{"description":"Missing, stale or invalid signature, or not a JSON object."},"422":{"description":"Correctly signed, and not one of the known demo budgets in its own shape."},"503":{"description":"Demo budget reports are not configured on this deployment."}}}},"/v1/webhooks/mail-relay-events":{"post":{"operationId":"receiveMailRelayEvents","summary":"Ingest signed delivery events from our own mail relay.","description":"**Unauthenticated by design**: the relay holds no Zinn® credential, so `x-signature: base64(HMAC-SHA256(secret, raw body))` *is* the authentication. Counts remote deliveries and permanent refusals per mailbox, and suspends sending on a mailbox whose last 24 hours are at least 50 refusals and at least 20% of its outcomes. With no configured secret it answers `503` and counts nothing. Events older than two hours are ignored, so a captured request replayed later changes nothing.","tags":["mail"],"security":[],"parameters":[{"name":"x-signature","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailRelayEventBatch"}}}},"responses":{"200":{"description":"The batch was counted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailRelayEventResult"}}}},"400":{"description":"Missing or invalid signature, or a body that is not an event batch."},"503":{"description":"The relay webhook is not configured on this deployment."}}}},"/v1/webhooks/campaign-events":{"post":{"operationId":"receiveCampaignDeliveryWebhook","summary":"Ingest a signed delivery event from the e-mail provider.","description":"**Unauthenticated by design** — the provider holds no Zinn® credential, so the HMAC over the raw request body *is* the authentication, exactly as for the Stripe path above. This is what moves a campaign delivery from *sent* to *delivered*, *bounced* or *complained*, and what feeds the suppression list. Redelivery is the normal case and every transition is monotonic, so a replay is a no-op rather than a row moved backwards. An event type Zinn® does not handle is acknowledged with 200, because a 4xx would only buy a retry storm for an event nobody was going to act on.\n\n⛔ With **no configured secret this endpoint answers 503 and processes nothing.** Accepting unsigned events \"until it is configured\" would be an unauthenticated write path into the delivery table and the suppression list — i.e. anybody on the internet could suppress a competitor's entire customer base.","tags":["campaigns"],"security":[],"requestBody":{"required":true,"description":"The raw provider event. Opaque to this API; the signature covers these exact bytes.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Event accepted (handled, ignored, or a duplicate).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookAck"}}}},"400":{"description":"Signature verification failed, or the payload was unreadable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"No signing secret is configured, so no event can be trusted or accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/git/{provider}/{repoId}":{"post":{"operationId":"receiveGitPushWebhook","summary":"Ingest a push from a customer's git provider and deploy it.","description":"**Unauthenticated by design** — the git provider holds no Zinn® credential, so the signature over the raw body *is* the authentication. A verified push on the branch a repository is wired to triggers a deploy of that site.\n\n⛔ The `repoId` in the path identifies which connection's secret verifies the signature; it is not a permission. A request whose signature does not verify is refused before anything is read from it.","tags":["hosting"],"security":[],"parameters":[{"name":"provider","in":"path","required":true,"description":"The git host that sent the push.","schema":{"type":"string","enum":["github","gitlab","bitbucket"]}},{"name":"repoId","in":"path","required":true,"description":"The connected repository this push belongs to.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"description":"The raw provider push event. Opaque to this API; the signature covers these exact bytes.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Push accepted (a deploy was queued, or the event was ignored).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookAck"}}}},"400":{"description":"Signature verification failed, or the payload was unreadable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such connected repository.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/stripe":{"post":{"operationId":"receiveStripeWebhook","summary":"Ingest a signed Stripe webhook event.","description":"**Unauthenticated by design** — Stripe holds no Zinn® credential, so the `Stripe-Signature` HMAC over the raw request body *is* the authentication. This is the only path that turns a confirmed SetupIntent into a chargeable mandate, and the only path that captures an async or SCA payment; neither may be asserted by a browser. Replays are expected and converge. An event type Zinn® does not handle is acknowledged with 200 (a non-2xx would make Stripe retry it for days). A Stripe TEST-mode event (signed with the test endpoint's secret, `livemode: false`) arriving at a live engine is acknowledged with `{\"status\": \"ignored\", \"mode\": \"test\"}` and changes nothing: no dedupe row, no handler, no live record.","tags":["billing"],"security":[],"requestBody":{"required":true,"description":"The raw Stripe event. Opaque to this API; the signature covers these exact bytes.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Event accepted (handled, ignored, or a duplicate).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookAck"}}}},"400":{"description":"Signature verification failed, or the event carried no id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/nowpayments":{"post":{"operationId":"receiveNowPaymentsWebhook","summary":"Ingest a signed NOWPayments IPN.","description":"**Unauthenticated by design** — NOWPayments holds no Zinn® credential, so the `x-nowpayments-sig` HMAC-SHA512 over the raw request body *is* the authentication. Crypto holds no mandate, so this path only ever **confirms an async (invoice-ahead) payment** (ADR 0011 §6) — it never creates a chargeable mandate. The tenant is recovered from the `order_id` Zinn® packed on the outbound invoice, since the IPN carries no principal. Replays are expected and converge; a status Zinn® does not act on (still pending, or terminally failed) is acknowledged with 200 (a non-2xx would make NOWPayments retry it for days). An `expired` invoice on a checkout order arms the customer's one-hour payment-help e-mail (`order.payment_help`, sent only if nothing is paid by then); the order's state is not changed.","tags":["billing"],"security":[],"requestBody":{"required":true,"description":"The raw NOWPayments IPN. Opaque to this API; the signature covers these exact bytes.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"IPN accepted (handled, ignored, or a duplicate).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookAck"}}}},"400":{"description":"Signature verification failed, or the IPN carried no payment id or status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/nowpayments/renewals/{autoRenewId}":{"parameters":[{"name":"autoRenewId","in":"path","required":true,"description":"The crypto auto-renew choice whose NOWPayments plan this IPN was sent from.","schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"receiveNowPaymentsRenewalWebhook","summary":"Ingest a signed NOWPayments IPN for a crypto auto-renew payment.","description":"**Unauthenticated by design**, exactly like `/v1/webhooks/nowpayments`: the `x-nowpayments-sig` HMAC-SHA512 over the raw body *is* the authentication, verified before the path is used. Each crypto auto-renew choice has its own NOWPayments plan whose IPN URL names it — a recurring payment's IPN carries no order or subscription id, so the URL is the attribution. A `finished` payment credits the fiat amount the plan asked for, once per `payment_id`, and settles an open renewal invoice from that credit; anything else (pending, partially paid, another currency, an unknown id) is acknowledged with 200 and credits nothing.","tags":["billing"],"security":[],"requestBody":{"required":true,"description":"The raw NOWPayments IPN. Opaque to this API; the signature covers these exact bytes.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"IPN accepted (handled, ignored, or a duplicate).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookAck"}}}},"400":{"description":"Signature verification failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"NOWPayments is not configured on this platform (NOWPayments retries).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/paypal":{"post":{"operationId":"receivePayPalWebhook","summary":"Ingest a signed PayPal webhook event.","description":"**Unauthenticated by design** — PayPal holds no Zinn® credential, so its asymmetric transmission signature *is* the authentication, verified server-side against the configured webhook id via PayPal's `verify-webhook-signature` API over the raw body + `PAYPAL-*` transmission headers. This is the only path that turns a confirmed vaulted payment token into a chargeable mandate (`VAULT.PAYMENT-TOKEN.CREATED`) and the only path that settles an async capture (`PAYMENT.CAPTURE.COMPLETED`); neither may be asserted by a browser. Replays are expected and converge. An event type Zinn® does not handle is acknowledged with 200 (a non-2xx would make PayPal retry it).","tags":["billing"],"security":[],"requestBody":{"required":true,"description":"The raw PayPal event. Opaque to this API; the signature covers these exact bytes.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Event accepted (handled, ignored, or a duplicate).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookAck"}}}},"400":{"description":"Signature verification failed, or the event carried no id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/reseller/webhooks/{code}/{orgId}":{"parameters":[{"name":"code","in":"path","required":true,"description":"The gateway code — `stripe`, `paypal` or `nowpayments`.","schema":{"type":"string"}},{"name":"orgId","in":"path","required":true,"description":"The RESELLER organization whose own gateway account is calling back. It is in the path because the signing secret is per organization: the engine must resolve *their* credential **before** it can verify anything. It is an identifier, not a capability — knowing it lets you attempt a delivery, and the signature decides whether that attempt does anything.","schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"receiveResellerWebhook","summary":"Ingest a signed callback from a reseller's OWN payment gateway.","description":"**Unauthenticated by design**, exactly like the platform callbacks above — the provider's signature over the raw body *is* the authentication. What differs is whose secret it is verified against: this endpoint resolves the reseller's own credential from Vault first, because `/v1/webhooks/{code}` verifies against **Zinn®'s** secret and answers `400 INVALID_SIGNATURE` to anything a reseller's account sends it. Without this endpoint a BYO gateway can charge but never settle asynchronously — no SCA completion, no mandate confirmation, no crypto IPN.\n\n⛔ A valid signature is **not** an authorization to touch a tenant. It proves only that the delivery came from the account we hold keys for; the event may act only on organizations that bill back to this reseller, and anything else is acknowledged with 200 and changes nothing. Replays are expected and converge on a dedupe key namespaced per reseller, so two accounts delivering the same provider event id cannot silently cancel each other out.","tags":["reseller"],"security":[],"requestBody":{"required":true,"description":"The raw provider event. Opaque to this API; the signature covers these exact bytes, so it is never re-serialized before verification.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Event accepted (handled, ignored, or a duplicate).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookAck"}}}},"400":{"description":"Signature verification failed, or the event carried no id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No callback here. Uniform for an unknown gateway code, an organization that is not an active reseller, and a reseller who has not connected this gateway — they are different facts and an unauthenticated caller may learn none of them.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The connection exists but its credential could not be read right now. Retryable on purpose: a permanent answer here would discard a real settlement over an outage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/catalog/product-lines":{"get":{"operationId":"listProductLines","summary":"List the active product lines.","description":"Returns every active product line (Footprint-Free, Mainstream, …) with its marketing feature list and the entitlement grants shared by every plan in the line. **Public** — prices and product definitions are public marketing data (docs/35 #19). Cacheable: the response carries a strong `ETag` and `Cache-Control: public, max-age=60`; send `If-None-Match` for a `304`.","tags":["catalog"],"security":[],"parameters":[{"name":"If-None-Match","in":"header","required":false,"description":"A previously returned `ETag`; a match responds `304`.","schema":{"type":"string","maxLength":256}}],"responses":{"200":{"description":"The active product lines.","headers":{"ETag":{"description":"Strong validator over the catalogue contents.","schema":{"type":"string"}},"Cache-Control":{"description":"Always `public, max-age=60`.","schema":{"type":"string"}},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductLineList"}}}},"304":{"description":"The catalogue is unchanged since the supplied `If-None-Match`.","headers":{"ETag":{"description":"The unchanged validator.","schema":{"type":"string"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/catalog/reseller-terms":{"get":{"operationId":"getResellerTerms","summary":"The platform-wide reseller wholesale discount, per product line.","description":"The discount off list price that every reseller gets, per product line a reseller can sell, plus the discount on AI credit packs. **Public**: the reseller marketing pages state the discount model from this rather than from a typed percentage, because the discount is a dated wholesale-rate row that changes without a deploy. Only the platform-wide rates are returned; a reseller's own negotiated rate is never public. `discount_bps` is basis points (2500 = 25%). `scope` is `platform_product_line` when the line has its own rate, `platform` when it inherits the standard one, and empty when no rate is in force (the reseller then pays full list). Cacheable: strong `ETag` and `Cache-Control: public, max-age=60`.","tags":["catalog"],"security":[],"parameters":[{"name":"If-None-Match","in":"header","required":false,"description":"A previously returned `ETag`; a match responds `304`.","schema":{"type":"string","maxLength":256}}],"responses":{"200":{"description":"The platform-wide reseller discounts in force today.","headers":{"ETag":{"description":"Strong validator over the response contents.","schema":{"type":"string"}},"Cache-Control":{"description":"Always `public, max-age=60`.","schema":{"type":"string"}},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerTermsResponse"}}}},"304":{"description":"Unchanged since the supplied `If-None-Match`.","headers":{"ETag":{"description":"The unchanged validator.","schema":{"type":"string"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/catalog/product-lines/owned":{"get":{"operationId":"listOwnedProductLines","summary":"List the product lines this organization actually has.","description":"The product lines the caller's organization has, or has ever had, something on — for narrowing a list of what they already own, never for choosing what to buy.\n\n⚖️ **Owner, 2026-09-08:** *\"in the filters it shows all product lines, even when they do not have any products in that line or never brought it, it should only show the hosting types they actually own or used so to speak.\"* Measured that morning on a real account with seven sites across **two** lines, the sites filter offered **sixteen**; fourteen of them could only narrow the list to nothing.\n\nA line is returned when the organization has a **site** on it — including `deleted` sites, so the deleted-sites screen stays filterable — **or** a **subscription** to a plan in it, in **any** status, cancelled included. A line paid for does not stop being theirs. An abandoned cart is not ownership and is excluded: it minted neither a site nor a subscription.\n\n⛔ **Not the list to offer when somebody is BUYING.** Restricting a purchase flow to lines already owned means a customer can never buy their first line. Use `listProductLines` (or `listInAppProductLines`) for that.\n\n⛔ **Authenticated and tenant-scoped**, unlike the other `/v1/catalog` reads: it is a fact about one organization's estate, computed over exactly the scope `listSites` reads (`sites.view`), so the filter and the rows it filters cannot disagree. Served `Cache-Control: no-store` — a shared cache in front of it would serve one organization's lines to the next caller.\n\n⛔ Retired, internal and in-app-only lines are **not** filtered out here, unlike the public catalogue. Every code in the response is present because a row of theirs names it, so there is nothing to leak — and a retired line whose sites still exist must stay filterable, or those sites become unreachable by filter with nothing to tell the customer why.","tags":["catalog"],"responses":{"200":{"description":"The lines this organization has, name-ordered. Empty when they have no sites and no subscriptions — which is a real answer, not a failure: a client renders its \"you have no sites yet\" state, and must not fall back to the full catalogue.","headers":{"Cache-Control":{"description":"Always `no-store` — this body is one tenant's.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OwnedProductLineList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/catalog/plan-moves":{"get":{"operationId":"listPlanMoves","summary":"For a product line I am already on, which plans can I move to?","description":"The ladder from the plan the organization currently holds on one product line — every purchasable tier on that line, marked `upgrade`, `downgrade` or `current`, priced in the organization's own currency and term.\n\nIt exists because a customer already on a plan is not shopping: offering them the whole catalogue as fresh purchases, the tier they are on included, is what the buy screen must not do. A tier above theirs is an upgrade and a tier below is a downgrade, and only one of those can be refused by what the account already uses.\n\n`blocked_by` is empty when a move is offerable. It is populated only on a `downgrade`, and only with limits the account is **already over** — a smaller plan cannot be moved to while seven sites will not fit five slots. Limits that could not be measured are deliberately **not** reported as blockers: \"no evidence\" and \"over the limit\" are different facts, and rendering the first as the second refuses a legitimate downgrade because a stored sample went stale.\n\nDirection comes from the catalogue's own ordering, not from price — a promotional price or an annual term can invert the ladder, and a plan with no price in the caller's currency has no direction at all. Price is the tiebreak within one rung. From a plan that is no longer on sale, or onto another line, there is no shared ladder, so price decides.\n\nA RETIRED line with a successor still answers (`product_line=wordpress` or `fleet_enterprise`), and asking for the successor (`mainstream`) when the organization only holds a plan on a line it replaced returns that plan as `current`: its customers move onto the one WordPress line as a prorated change of the same subscription, not as a second purchase.\n\n`current: null` with an empty `moves` means the organization holds no plan on that line, so there is nothing to move from and the ordinary catalogue applies.","tags":["billing"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"The organization to answer for. Required when the caller can see billing for more than one; otherwise defaults to theirs.","schema":{"$ref":"#/components/schemas/Uuid"}},{"name":"product_line","in":"query","required":true,"description":"The product line to build the ladder for.","schema":{"type":"string","example":"footprint_free"}}],"responses":{"200":{"description":"The plan the organization is on, and where it can move.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanMoves"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/catalog/plans":{"get":{"operationId":"listCatalogPlans","summary":"List the sellable plans with their prices.","description":"Returns every active plan with its current version's **resolved entitlements** (product-line defaults overlaid with the plan's own) and its list prices, in the stored currency and interval. Prices are integer minor units + an ISO currency code (CLAUDE.md §2.8); USD is the base, and a derived, charm-rounded row is served for every enabled currency once the FX refresh has run (docs/29 §2). **Public** (docs/35 #19).\n\n**`prices` is a multi-row array, one entry per (interval, currency)** — never a single pre-converted row. A client selects the entry matching the customer's chosen currency AND interval, and must render **nothing** rather than fall back to an amount in a different currency: a number in the wrong currency, or the right number under the wrong symbol, is worse than an absent price (#471).\n\n**Each plan carries `plan_version_id`, the identifier that makes it purchasable.** A `hosting_plan` cart line pins a plan *version*, not a plan, so before this field existed a customer could browse the catalogue and had no way to buy anything in it (#463). The full self-serve path is `POST /v1/carts` → `POST /v1/carts/{cartId}/lines` with `{kind: hosting_plan, plan_version_id, metadata: {interval}}` → `POST /v1/carts/{cartId}/checkout`. An **internal** plan is never listed here and the cart refuses it, so the unlimited staff plan cannot be self-served.\n\nReturned **whole, not cursor-paginated** — a deliberate, documented deviation matching `getTranslationBundle`: the catalogue is our own bounded content, and a pricing page or the pricing slider needs every tier at once, not 50 at a time. The response is bounded by a hard server-side cap; a catalogue that would exceed it is a `422` (it never silently truncates), which cannot happen with today's catalogue and exists only so unbounded future growth fails loudly.\n\nCacheable exactly like `listProductLines` (strong `ETag` + `max-age=60`).\n**Cross-origin callers.** Besides zinndigital.com, this route answers the browsers of the hosting sites' on-page free trial — zinnhosting.com, zinnhosting.co.uk and the zinndigital country sites (`engine.api.trial_cors`, list generated from the product-sites registry into `engine/engine/api/trial_origins.json`). Exact origins only, never credentials; the route's own budgets, Turnstile and trial guard apply unchanged (docs/749 §16).","tags":["catalog"],"security":[],"parameters":[{"name":"product_line","in":"query","required":false,"description":"Restrict to one product line by its code (e.g. `footprint_free`). Unknown code → empty list.","schema":{"type":"string","maxLength":64}},{"name":"currency","in":"query","required":false,"description":"Narrow each plan's `prices` array to a single ISO 4217 currency. **Optional and additive**: omitting it returns every currency exactly as before, so no existing client changes behaviour.\n\n**Why it exists.** Measured on production 2026-09-02: the unfiltered response is **902,291 bytes across 144 plans, of which 91.8% is `prices`** — 56 (interval, currency) rows per plan, when a client renders one. With `?currency=GBP` the same catalogue is **114 KB, an 8x reduction**. The dashboard requests this on every boot, and a multi-second megabyte on the boot path is what exhausts the API's worker slots.\n\nAn unknown or malformed code yields an **empty** `prices` array per plan rather than a `404` or a silent fall back to every currency — empty is the honest answer to \"what does this cost in XYZ\", and falling back would return the 900 KB the caller asked to avoid.","schema":{"type":"string","minLength":3,"maxLength":3,"pattern":"^[A-Za-z]{3}$"}},{"name":"If-None-Match","in":"header","required":false,"description":"A previously returned `ETag`; a match responds `304`.","schema":{"type":"string","maxLength":256}}],"responses":{"200":{"description":"The active plans.","headers":{"ETag":{"description":"Strong validator over the catalogue contents.","schema":{"type":"string"}},"Cache-Control":{"description":"Always `public, max-age=60`.","schema":{"type":"string"}},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogPlanList"}}}},"304":{"description":"The catalogue is unchanged since the supplied `If-None-Match`.","headers":{"ETag":{"description":"The unchanged validator.","schema":{"type":"string"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/catalog/app/product-lines":{"get":{"operationId":"listInAppProductLines","summary":"List the product lines a signed-in customer may buy, including unadvertised ones.","description":"Identical to `listProductLines`, plus every line marked **in-app-only** — sold, but never promoted on the public site.\n\n⚖️ **Owner ruling, 2026-08-16:** email is not a product we sell. It is free with every domain registered with us or transferred in. Email for a domain registered *somewhere else* stays purchasable *\"only form inside the app\"* and is not promoted on the frontend, so the `mail` line is served here and **not** by `listProductLines`.\n\nRequires authentication and nothing else — every signed-in customer sees the same catalogue, so there is no org to scope to and no permission to require. Responses are `Cache-Control: private, no-store`: the body varies by whether the caller is signed in, and a shared cache in front of it would hand the in-app catalogue to the next anonymous visitor.","tags":["catalog"],"responses":{"200":{"description":"The active product lines, including in-app-only ones.","headers":{"Cache-Control":{"description":"Always `private, no-store`.","schema":{"type":"string"}},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductLineList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/catalog/app/site-hosting-lines":{"get":{"operationId":"listSiteHostingLines","summary":"List the product lines a SITE can be created on.","description":"The subset of `listInAppProductLines` a website can actually live on, and the catalogue half of what a deploy or migrate picker needs.\n\n⚖️ **Owner, 2026-09-09, on the migration flow:** *\"When it allows them to select a hosting type to migrate to, does it only show them the hosting types they actually own and say for other hosting plans they need to buy it first type of thing?\"*. Measured live the same day, the migration screen offered **eighteen** lines — of which **four sell something that is not a website**: Zinn® Boards, Zinn® Managed Databases, Zinn® Vector Databases and email for an external domain. A managed database has no document root; Boards is a project board.\n\n⛔ **The predicate is derived, never enumerated.** A line appears here iff some purchasable plan on it grants a positive or unlimited `max_sites` — which is exactly the entitlement a site create spends, so this cannot drift from what `POST /v1/sites` accepts. A hand-written deny list would be right on the day it was typed and would silently offer the fifth non-hosting line an operator seeds tomorrow.\n\n⛔ **It says nothing about whether the caller can afford one.** *\"Do I already have room\"* is `getDeployablePlans`, and the two stay apart: a screen composes them — the owned half to offer, the difference to upsell. Reseller clients see only the lines their provider still sells, exactly as `listInAppProductLines` does, so nothing here can be bought and then refused by the cart.\n\n`internal` lines (the staff tariff) are excluded: they grant unlimited sites and are assigned by staff, so offering one advertises a plan the customer cannot buy.\n\nRequires authentication and nothing else. `Cache-Control: private, no-store` — the list carries in-app-only lines, so a shared cache would hand them to the next anonymous visitor.","tags":["catalog"],"responses":{"200":{"description":"Every active, non-internal product line a site can be created on.","headers":{"Cache-Control":{"description":"Always `private, no-store`.","schema":{"type":"string"}},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteHostingLineList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/catalog/app/plans":{"get":{"operationId":"listInAppCatalogPlans","summary":"List the plans a signed-in customer may buy, including unadvertised ones.","description":"Identical to `listCatalogPlans` — same shape, same multi-currency `prices` array, same `plan_version_id` purchase path — plus the plans on **in-app-only** lines.\n\nThis is the endpoint the dashboard reads to offer email on an external domain. The purchase path is unchanged: `POST /v1/carts` → `POST /v1/carts/{cartId}/lines` with `{kind: hosting_plan, plan_version_id, metadata: {interval}}` → checkout.\n\n⛔ The in-app-only exclusion on the public endpoint is applied **even when `product_line` names the hidden line** — naming a thing is not authorisation to see it, and that parameter arrives from an untrusted query string.\n\n**A reseller's client is quoted the reseller's prices** — the reseller's own price for the plan where they set one, otherwise list plus their default markup — which is exactly what the cart charges. The public `listCatalogPlans` never does this: it is anonymous and shared-cached. The dashboard's checkout reads this endpoint for that reason.","tags":["catalog"],"parameters":[{"name":"product_line","in":"query","required":false,"description":"Restrict to one product line by its code (e.g. `mail`). Unknown code → empty list.","schema":{"type":"string","maxLength":64}},{"name":"currency","in":"query","required":false,"description":"Narrow each plan's `prices` array to a single ISO 4217 currency, exactly as on `listCatalogPlans`, and publish each plan's per-term prices in `terms`. Omitted, every currency is returned and `terms` is absent.","schema":{"type":"string","minLength":3,"maxLength":3,"pattern":"^[A-Za-z]{3}$"}}],"responses":{"200":{"description":"The active plans, including those on in-app-only lines.","headers":{"Cache-Control":{"description":"Always `private, no-store`.","schema":{"type":"string"}},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogPlanList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/catalog/app/addons":{"get":{"operationId":"listCatalogAddons","summary":"List the add-ons a hosting order can carry, priced in every currency we can.","description":"Every add-on we sell (the same rows the cart and `createPartnerHostingOrder` accept): its `code`, name, summary, `interval` (`one_off` or `monthly`), how it is fulfilled, the product lines it is sold on (`all_lines` is true when it is sold on every line), and its price per currency in integer minor units. A currency we hold no exchange rate for is omitted from `prices` rather than listed at the USD figure. Pass `currency` to narrow `prices` to the one you sell in — take that entry, never the first. Signed-in, non-tenant data: every caller sees the same list.","tags":["catalog"],"parameters":[{"name":"product_line","in":"query","required":false,"description":"Only add-ons sold on this product line.","schema":{"type":"string","maxLength":64}},{"name":"currency","in":"query","required":false,"description":"Narrow each add-on's `prices` to one ISO 4217 currency.","schema":{"type":"string","minLength":3,"maxLength":3,"pattern":"^[A-Za-z]{3}$"}}],"responses":{"200":{"description":"The add-on catalogue.","headers":{"Cache-Control":{"description":"Always `private, no-store`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogAddon"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/catalog/app/regions":{"get":{"operationId":"listHostingRegions","summary":"List the hosting regions a new site can be placed in right now.","description":"The regions of our own fleet that have a box able to take a new site **right now** — derived from the servers registered in each region, never from a typed list. A region with no capacity is simply absent: there is no \"coming soon\" entry to render. When a server is registered in a new region it appears here on the next read, with no client change.\n\n`code` is the value `createSite`, the checkout (`addCartLine`) and `createPartnerHostingOrder` accept as `region`. Sending a region that is not in this list is refused **before** anything is created: a region we run that has no capacity today is a `422` with error code `REGION_UNAVAILABLE` (`region_unavailable` on the partner order), naming the regions that are available.\n\nRender `name_key` from your catalogue where you have one (our own consoles carry it in every language); `city` is the English fallback and `country` is ISO-3166 alpha-2 for a decorative flag — never the accessible name. With exactly one region a client may state it as a fact rather than render a one-option picker.\n\nSigned-in, non-tenant data (a partner API key reaches it exactly as it reaches `listInAppCatalogPlans`). `product_line` narrows the answer to boxes that serve that line in the pool its sites are placed in; a line placed on no box of ours (cloud, compute, mail, agents…) or an unknown code answers an empty list. `include=unavailable` adds every region we run with `available: false` — for staff tooling only; a picker must never pass it.","tags":["catalog"],"parameters":[{"name":"product_line","in":"query","required":false,"description":"Only regions with a box that can take a site on this product line.","schema":{"type":"string","maxLength":64}},{"name":"include","in":"query","required":false,"description":"`unavailable` also lists regions we run that cannot take a site today.","schema":{"type":"string","enum":["unavailable"]}}],"responses":{"200":{"description":"The regions, available first.","headers":{"Cache-Control":{"description":"Always `private, no-store`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/HostingRegion"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/catalog/regions":{"get":{"operationId":"listPublicHostingRegions","summary":"List the cities we can host a new site in, for public pages.","description":"The anonymous twin of `listHostingRegions`, for marketing pages: the cities with capacity for a new site right now, by our own public `slug` (`nuremberg`). It carries **no** placement code — a supplier's zone token on a public page leaks our vendor inventory — so it cannot be used to order; use `listHostingRegions` for that. Cached publicly for 60 seconds with a strong ETag.","tags":["catalog"],"security":[],"parameters":[{"name":"product_line","in":"query","required":false,"description":"The per-line placement truth (s1014 R37): for a fleet line, only cities with a box that can take a site on that line (pool and affinity); for `cloud` (VPS) and `zinn_compute`, the cities an orderable size of that line is priced in; for footprint-free (`pbn`), none (it is placed for the customer); for any other line or an unknown code, an empty list. Omitted, every fleet city with room.","schema":{"type":"string","maxLength":64}}],"responses":{"200":{"description":"The cities with capacity.","headers":{"ETag":{"schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicHostingRegion"}}}}}}},"304":{"description":"Not modified — the `If-None-Match` ETag is current."},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/catalog/compute":{"get":{"operationId":"listCatalogCompute","summary":"List the sellable cloud machine sizes.","description":"Every Zinn® Cloud size a customer may buy, with **every cadence it is priced at**, read straight from the catalogue rows an operator edits in admin. **Public** — no authentication, no tenant, no principal — and cacheable exactly like `listCatalogPlans` (strong `ETag` + `max-age=60`).\n\n**This is not `getComputeCatalogue` made public, and it deliberately cannot become it.** That endpoint (`GET /v1/compute/catalogue`, `sites.view`) reads the provider matrix, which is an org-scoped live call to the vendor with the org's own credentials. This one is a pure read of our own plan and price rows, which is why it can be served to a logged-out visitor at all. The corollary is part of the contract: **this endpoint returns no providers and no data centres.** Both are defaulted server-side at checkout, once an org exists to read them with.\n\nOnly sizes that can actually be **bought** are listed. A size with no vendor spec token, or with no price at any sellable cadence, is one the cart refuses — listing it would be a configurator that offers a size and then answers `422`.\n\nReturned **whole, not cursor-paginated**, matching `listCatalogPlans`: a configurator needs every size at once to render a comparison, not 50 at a time.","tags":["catalog"],"security":[],"parameters":[{"name":"If-None-Match","in":"header","required":false,"description":"A previously returned `ETag`; a match responds `304`.","schema":{"type":"string"}}],"responses":{"200":{"description":"The sellable machine sizes.","headers":{"ETag":{"description":"Strong entity tag over the response body.","schema":{"type":"string"}},"Cache-Control":{"description":"`public, max-age=60`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicComputeTier"}}}}}}},"304":{"description":"Not modified — the caller's `ETag` still matches."},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/catalog/compute/own-cloud":{"get":{"operationId":"listCatalogOwnCloudCompute","summary":"List the Zinn® Private Cloud sizes, with a \"from\" price and the cities they run in.","description":"The **Zinn® Private Cloud** range — the machines we source ourselves rather than resell — for the public product page. **Public**, cacheable exactly like `listCatalogCompute` (strong `ETag` + `max-age=60`).\n\n⛔ **A sibling of `listCatalogCompute`, not a widening of it, and the reason is the price.** Every size on this range is priced **per data centre** — the same machine is $33.99 in one city and $44.99 in another — so `listCatalogCompute`, which by contract returns no data centres, has no honest figure to publish for one. This endpoint returns the cities, and every `amount_minor` here is the **cheapest** figure across them: a **\"from\" price**, which is the only kind that exists on a zoned range, and which the page must render with the word *from*.\n\n⛔ **Nothing here is an offer.** An organisation passes a one-off verification before its first machine on this range (owner ruling 2026-08-14), so this read describes a product rather than opening a purchase — unlike `listCatalogCompute`, whose whole purpose is feeding an anonymous basket. A price is not an offer on this range in a second sense too: a city can be out of stock, and buildability is settled live at order time against the provider, never from this list.\n\n⛔ `locations` are **our** city slugs (`falkenstein`, `singapore`), never a supplier zone token. The words a visitor reads are a translated catalogue entry per locale (§2.19); a zone whose city we have no public words for is **omitted**, because a vendor inventory key on an indexed page in 58 languages is a footprint disclosure nobody asked for (#1956).","tags":["catalog"],"security":[],"parameters":[{"name":"include_sold_out","in":"query","required":false,"description":"`true` also returns the sizes the stock watch holds **sold out** (no data centre can build them now), each with `sold_out: true` and its real \"from\" prices, so a full price list can show them as sold out instead of silently omitting them. Off by default: a product page that sells sizes must never list one nobody can build.","schema":{"type":"boolean","default":false}},{"name":"If-None-Match","in":"header","required":false,"description":"A previously returned `ETag`; a match responds `304`.","schema":{"type":"string"}}],"responses":{"200":{"description":"The Zinn® Private Cloud sizes, each with its \"from\" prices and cities.","headers":{"ETag":{"description":"Strong entity tag over the response body.","schema":{"type":"string"}},"Cache-Control":{"description":"`public, max-age=60`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicOwnCloudComputeTier"}}}}}}},"304":{"description":"Not modified — the caller's `ETag` still matches."},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/catalog/compute/add-ons":{"get":{"operationId":"listCatalogComputeAddOns","summary":"List the add-ons a Zinn® Private Cloud machine can carry, with every stored price.","description":"The machine add-on catalogue (control panels, CloudLinux, LiteSpeed, KernelCare and **managed server care**) for the public product pages. **Public**, cacheable exactly like `listCatalogCompute` (strong `ETag` + `max-age=60`).\n\n⛔ **Every currency the row is STORED in, never a conversion.** The public site prints a stored EUR or GBP figure where one exists, because that is what checkout charges. A paid add-on with no price row at all is omitted.\n\n⛔ **Sell prices only.** No vendor cost, no vendor, no licence stock: those are the admin ledger's and checkout's. `listComputeAddOns` (signed in) remains the picker, which also answers whether a seat is free right now.","tags":["catalog"],"security":[],"parameters":[{"name":"If-None-Match","in":"header","required":false,"description":"A previously returned `ETag`; a match responds `304`.","schema":{"type":"string"}}],"responses":{"200":{"description":"The enabled add-ons, each with its stored prices.","headers":{"ETag":{"description":"Strong entity tag over the response body.","schema":{"type":"string"}},"Cache-Control":{"description":"`public, max-age=60`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicComputeAddOn"}}}}}}},"304":{"description":"Not modified — the caller's `ETag` still matches."},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/catalog/fx-rates":{"get":{"operationId":"listFxRates","summary":"List the current FX rates vs the USD base.","description":"The current stored exchange rates (each currency vs the USD base) the platform uses to derive per-currency prices, refreshed on a schedule (docs/29 §1-2). The frontend `CurrencySwitcher` and the admin helper lines (docs/29 §5) read these. **Public** reference data — no auth, no tenant scope. `rate_vs_usd` is a **string** decimal, never a JSON float, so no floating-point value ever represents the rate a price was derived from (§2.8). Empty until the first refresh runs (prices fall back to USD, never an error). Cacheable exactly like `listCatalogPlans`.","tags":["catalog"],"security":[],"parameters":[{"name":"If-None-Match","in":"header","required":false,"description":"A previously returned `ETag`; a match responds `304`.","schema":{"type":"string","maxLength":256}}],"responses":{"200":{"description":"The current FX rates.","headers":{"ETag":{"description":"Strong validator over the rate set.","schema":{"type":"string"}},"Cache-Control":{"description":"Always `public, max-age=60`.","schema":{"type":"string"}},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FxRateList"}}}},"304":{"description":"The rate set is unchanged since the supplied `If-None-Match`.","headers":{"ETag":{"description":"The unchanged validator.","schema":{"type":"string"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/catalog/php-versions":{"get":{"operationId":"listPhpVersions","summary":"List the PHP versions offered to new sites.","description":"The PHP versions a new site can be created with, each with its support `status` (`active` current line, `hardened_legacy` CloudLinux-patched alt-php, `eol`), whether it is the default, and the product lines it is offered on. **Public** catalog reference data — no auth, no tenant scope. Only versions offered to new sites appear; a version retired for new sites (grandfathered on existing sites) is omitted. `?product_line=` narrows to one line (an unknown code yields an empty list, never an error). Cacheable exactly like `listCatalogPlans` (strong `ETag` + `max-age=60`).","tags":["catalog"],"security":[],"parameters":[{"name":"product_line","in":"query","required":false,"description":"Restrict to one product line by its code (e.g. `footprint_free`). Unknown code → empty list.","schema":{"type":"string","maxLength":64}},{"name":"If-None-Match","in":"header","required":false,"description":"A previously returned `ETag`; a match responds `304`.","schema":{"type":"string","maxLength":256}}],"responses":{"200":{"description":"The PHP versions offered to new sites.","headers":{"ETag":{"description":"Strong validator over the catalogue contents.","schema":{"type":"string"}},"Cache-Control":{"description":"Always `public, max-age=60`.","schema":{"type":"string"}},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhpVersionCatalogList"}}}},"304":{"description":"The catalogue is unchanged since the supplied `If-None-Match`.","headers":{"ETag":{"description":"The unchanged validator.","schema":{"type":"string"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/catalog/applications":{"get":{"operationId":"listCatalogApplications","summary":"List the applications the platform installs on its own fleet.","description":"Every application our own installer can put down for a customer — the source of truth for any \"one-click applications\" count or list on the public site (docs/681). Read from the installer registry at this release, so an application appears here only when the platform can actually install it. **Public** catalog reference data — no auth, no tenant scope — and cacheable exactly like `listCatalogPlans` (strong `ETag` + `max-age=60`). Bring-your-own code is not an installed application and is not listed.","tags":["catalog"],"security":[],"parameters":[{"name":"If-None-Match","in":"header","required":false,"description":"A previously returned `ETag`; a match responds `304`.","schema":{"type":"string","maxLength":256}}],"responses":{"200":{"description":"The applications the platform installs, ordered by name.","headers":{"ETag":{"description":"Strong validator over the catalogue contents.","schema":{"type":"string"}},"Cache-Control":{"description":"Always `public, max-age=60`.","schema":{"type":"string"}},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FleetApplication"}}}}}}},"304":{"description":"The catalogue is unchanged since the supplied `If-None-Match`.","headers":{"ETag":{"description":"The unchanged validator.","schema":{"type":"string"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/api-keys":{"get":{"operationId":"listApiKeys","summary":"List the organization's API keys.","description":"Lists the non-revoked API keys the caller can manage. Only key **metadata** is returned — never the secret or its hash (CLAUDE.md §2.4). Requires `apikeys.manage`.","tags":["api-keys"],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"org_id","in":"query","required":false,"description":"Restrict to one organization in scope (default — every org you manage keys in).","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"A page of API keys.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createApiKey","summary":"Create an API key.","description":"Mints a new per-org API key and returns the full `zdk_…` token **once** — only its hash is stored, so a lost token is replaced, never recovered. The requested `scopes` must be permissions the caller already holds in the target org; asking for one you do not hold is a `403` (a key can never out-scope its creator). Send an `Idempotency-Key` so a retry after a lost response returns the same token rather than orphaning a key. Requires `apikeys.manage`.","tags":["api-keys"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreate"}}}},"responses":{"201":{"description":"The created key, including its one-time secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreated"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/api-keys/{apiKeyId}":{"parameters":[{"$ref":"#/components/parameters/ApiKeyId"}],"get":{"operationId":"getApiKey","summary":"Get an API key.","description":"Returns one non-revoked key's metadata (never the secret). RBAC + RLS scoped.","tags":["api-keys"],"responses":{"200":{"description":"The API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKey"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"revokeApiKey","summary":"Revoke an API key.","description":"Revokes the key — it stops authenticating immediately and drops out of the list. The revocation is recorded in the audit log. Requires `apikeys.manage`.","tags":["api-keys"],"responses":{"204":{"description":"Revoked."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Refused — this is the account's last operational way to pay and something is still going to charge it (a live subscription, a scheduled ad-hoc charge, or an active reseller programme). ⚖️ Owner ruling 2026-08-22. A `409` rather than a `422` because the request is well-formed and would be accepted once the customer adds another method, elects to pay by crypto, or cancels what is billing them.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/audit":{"get":{"operationId":"listAuditLog","summary":"Read the organization's audit log.","description":"Returns the append-only record of privileged actions taken in the tenant — including staff access — **newest first**, ordered by the sortable id, with older entries reachable by paging the cursor. (It described itself as `oldest → newest` until #462 made every collection newest-first: for an audit feed the answer to \"what just happened here?\" was on the last page.) The actor's IP is not exposed here (it is admin-console only). Requires `audit.read`.\n\n**An undeclared query parameter is refused with `422`, never ignored.** A filter this endpoint does not read used to answer `200` with the whole log, which is indistinguishable from a real answer and reads as \"there is a lot of history here\" rather than \"the filter was dropped\" (D26500). Every parameter below is read.","tags":["audit"],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"org_id","in":"query","required":false,"description":"Restrict to one organization in scope (default — the whole subtree).","schema":{"$ref":"#/components/schemas/Uuid"}},{"name":"action","in":"query","required":false,"description":"Filter to one action code (e.g. `apikey.created`).","schema":{"type":"string","maxLength":100}},{"name":"actor","in":"query","required":false,"description":"Filter to one actor (e.g. `user:0190…` or `apikey:0190…`).","schema":{"type":"string","maxLength":200}},{"name":"target","in":"query","required":false,"description":"Filter to one acted-on object — the exact `target` a row carries (a hostname, a site id, a deploy sha). **Exact match, never a prefix**: a substring match would make `site-1` return `site-11`'s rows, from the endpoint whose purpose is attribution. Until 2026-09-16 this parameter was undeclared and unread, so sending it returned *every* row as though it had been applied (D26500).","schema":{"type":"string","maxLength":255}},{"name":"since","in":"query","required":false,"description":"Only entries at or after this ISO 8601 instant (inclusive).","schema":{"type":"string","format":"date-time"}},{"name":"until","in":"query","required":false,"description":"Only entries at or before this ISO 8601 instant (inclusive), so `since` and `until` together bound an incident window. `since == until` selects that instant rather than nothing.","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"A page of audit entries.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditLogPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/carts":{"get":{"operationId":"listCarts","summary":"List the open baskets in scope.","description":"The organization's OPEN carts that hold at least one line, newest first by paging, so the dashboard's basket screen can open the customer's basket when it is reached without a cart id (a reload, a bookmark, the nav). An empty cart and a converted or abandoned one are not listed. Lines are not re-priced here; read one with `getCart`. Requires `billing.payment.manage`, the permission every other cart operation needs.","tags":["commerce"],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"org_id","in":"query","required":false,"description":"Restrict to one organization in scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"A page of open baskets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CartSummaryPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createCart","summary":"Open a shopping cart.","description":"Creates an empty open cart for the organization. Prices on its lines are server-authoritative and re-computed on every read (the client price is never trusted). Requires `billing.payment.manage`.","tags":["commerce"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CartCreate"}}}},"responses":{"201":{"description":"The new, empty cart.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cart"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/carts/adopt":{"post":{"operationId":"adoptGuestCart","summary":"Carry a guest basket into the signed-in account.","description":"Moves the items of an anonymous guest cart into the caller's organization cart, so a visitor who built a basket on the public site and then signed in continues instead of starting again (`docs/87` §575, #2599).\n\n⛔ **Two credentials, both required.** The raw cart `token` proves the caller built the basket; the authenticated principal decides which organization it lands in. Neither alone is sufficient — a token cannot name a destination and a session cannot claim a basket it never held.\n\nOne-way and idempotent: the guest cart is closed under a conditional update, so a double-submit or a refresh adopts once. Requires `billing.payment.manage`.\n\n⛔ Declared before `/v1/carts/{cartId}` so the literal `adopt` is not read as a cart id.","tags":["commerce"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CartAdopt"}}}},"responses":{"200":{"description":"What was adopted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CartAdoptResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"description":"The basket could not be adopted. `error.refusal.key` distinguishes `refusal.cart.adoptNotFound` (expired or never existed), `refusal.cart.adoptAlreadyOrdered` (already turned into an order), `refusal.cart.adoptAlreadyAdded` (another tab adopted it first) and `refusal.cart.adoptGuestCheckout` (the basket is already part of a guest checkout for another account) — kept apart because each leads the customer to do something different. A guest basket in a different currency from the account's other basket is NOT refused: it is adopted into its own basket in the currency it was quoted in (CARTADOPT1115).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/carts/{cartId}":{"parameters":[{"$ref":"#/components/parameters/CartId"}],"get":{"operationId":"getCart","summary":"Get a cart.","description":"Returns the cart with its lines re-priced from the live catalog and its pre-tax totals.","tags":["commerce"],"responses":{"200":{"description":"The cart.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cart"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/carts/{cartId}/lines":{"parameters":[{"$ref":"#/components/parameters/CartId"}],"post":{"operationId":"addCartLine","summary":"Add a line to a cart.","description":"Adds a priced line. A `hosting_plan` line needs a `plan_version_id`; a `domain_register`/`domain_transfer`/`domain_renew` line needs a `domain_name`, `tld` and `period_years`. The line shape and price are validated + stamped by the server; a bad shape (or a plan version with no price) is a `422`.","tags":["commerce"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CartLineCreate"}}}},"responses":{"201":{"description":"The updated cart, including the new line.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cart"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/carts/{cartId}/lines/{lineId}":{"parameters":[{"$ref":"#/components/parameters/CartId"},{"$ref":"#/components/parameters/LineId"}],"delete":{"operationId":"removeCartLine","summary":"Remove a line from a cart.","description":"Deletes one line. A line id from another cart or tenant is a `404`.","tags":["commerce"],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/carts/{cartId}/promo-code":{"parameters":[{"$ref":"#/components/parameters/CartId"}],"put":{"operationId":"setCartPromoCode","summary":"Type a discount code into a cart.","description":"Applies a hosting/SEO-tool coupon (docs/1311) to the basket. The saving is taken off the FIRST billing period of each eligible line only; renewals are never discounted, and VAT is computed on the discounted net at checkout. A code that cannot apply to this customer at all is a `422` whose `details[0].code` is one of `not_found`, `inactive`, `not_started`, `expired`, `exhausted`, `already_used`. A code that applies to nothing in the basket YET is accepted and reported on `Cart.coupon.reason` (`not_eligible`, `currency_mismatch`), because a customer may type it before choosing the plan. A domain promotion code is accepted here too and priced by the domain path.","tags":["commerce"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromoCodeSet"}}}},"responses":{"200":{"description":"The re-priced cart, with `promo_code` and `coupon`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cart"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"clearCartPromoCode","summary":"Remove the discount code from a cart.","tags":["commerce"],"responses":{"200":{"description":"The re-priced cart, with no code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cart"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/promo-codes/quote":{"post":{"operationId":"quotePromoCode","summary":"Preview what a discount code takes off these items.","description":"A DISPLAY for the checkout form (docs/1311): the same rules and arithmetic as the cart, on the catalogue amounts given. Checkout re-prices the basket and charges from the cart, never from this answer. `once_per_customer` is judged against the caller's org (`org_id`, required only when the caller manages billing for several).","tags":["commerce"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CouponQuoteRequest"}}}},"responses":{"200":{"description":"The preview.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CouponQuote"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/carts/{cartId}/checkout":{"parameters":[{"$ref":"#/components/parameters/CartId"}],"post":{"operationId":"checkoutCart","summary":"Check out a cart — place and charge an order.","description":"Converts the cart to an **immutable order**: re-prices every line, re-verifies each domain availability token (a stale/taken one is a `409`, with no charge), computes tax, places the order and charges it **wallet-first**. Fulfilment (provisioning/registration) then runs asynchronously as a Temporal workflow — this call never blocks on it (§2.9); poll the order `status` or the resource it produces. An **`Idempotency-Key` header is required**: a retried checkout returns the same order and never charges twice. Requires `billing.payment.manage`.\n\n**Pay first.** A cart carrying a new plan (`hosting_plan`, `compute_server`, `managed_database` or `boards_plan`) is refused with a `422` and the refusal `refusal.billing.renewalUnpaidNewPlan` while any subscription of the organisation owes an unpaid renewal, before tax is computed and before any order row or charge. Pay the renewal on the billing page, then check out.","tags":["commerce"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutRequest"}}}},"responses":{"201":{"description":"The placed order (its `status` reflects whether the charge settled).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"A domain's availability token was stale, taken or expired — or an aged domain could not be HELD (s1014): no fresh live supplier check (ask `checkAgedDomain`, then retry), another customer's open order holds it, it has just sold, or the shop is paused. Or (`error.code` `DOMAIN_ALREADY_ORDERED`, s1014 DOMAINWALK) a `domain_register` line names a domain this organisation already holds or is already buying — a second press of Register is refused here, serialised per name, so one name is never ordered and paid for twice. Or (`error.details[0].code` `COUPON_WITHDRAWN`, docs/1311) a replayed checkout resumed an unpaid order whose coupon claim had lapsed and could not be re-taken: the code was removed and the order repriced to the full total, which the keyed message (`refusal.commerce.couponWithdrawn`) states. Nothing was placed and nothing was charged; the message is a keyed refusal (`refusal.agedDomains.*`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The cart is not open, or `gateway` names a rail this purchase cannot be settled on, or (`error.code` `REGISTRY_DATA_REQUIRED`, Q10) a domain's registry demands fields `registry_data` did not carry (one `details[]` entry per `domain` + `field` + `code`), or (`error.code` `REGISTRANT_REQUIRED`) a domain in the basket has no owner — send `registrant` or set the default registrant, then retry with the same `Idempotency-Key`. `error.details` names each domain. Or (`error.code` `REFUND_TERMS_REQUIRED`) the organisation has not agreed that refunds are issued as Zinn® credit — ask the customer, then retry with `accept_refund_terms: true`. Nothing was placed and nothing was charged. Or the card's share of the order is under the payment gateway's smallest charge and account credit cannot cover the whole order (docs/31 §4.4; no credit drawn), or the gateway answered and refused the charge (any credit drawn for it was given back).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/orders":{"get":{"operationId":"listOrders","summary":"List orders in scope.","description":"The organization's orders, newest reachable by paging. Requires `billing.view`.","tags":["commerce"],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"status","in":"query","required":false,"description":"Filter by order status.","schema":{"$ref":"#/components/schemas/OrderStatus"}},{"name":"org_id","in":"query","required":false,"description":"Restrict to one organization in scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"A page of orders.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/orders/{orderId}":{"parameters":[{"$ref":"#/components/parameters/OrderId"}],"get":{"operationId":"getOrder","summary":"Get an order.","description":"Returns one order with its lines and payment summaries. RBAC + RLS scoped.","tags":["commerce"],"responses":{"200":{"description":"The order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/orders/{orderId}/payment-options":{"parameters":[{"$ref":"#/components/parameters/OrderId"}],"get":{"operationId":"getOrderPaymentOptions","summary":"The payment gateways this order may be settled on.","description":"What the pay screen offers the customer, so an overdue bill can be settled through whichever enabled gateway they pick rather than only the one the subscription was created with.\n\nThe answer is **per order, not per platform**. A reseller's client always receives exactly one entry — their reseller's connected gateway — whatever the platform has enabled, because that is the only merchant account their money may land in. `payOrder` refuses any `gateway` that is not in this list.\n\nAnswers for a settled order too, with the same list: the question \"what could pay this?\" is meaningful for a receipt, and refusing would make the screen depend on a race with the webhook that settled it.","tags":["commerce"],"responses":{"200":{"description":"The gateways available for this order, most-preferred first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentOptions"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/orders/{orderId}/pay":{"parameters":[{"$ref":"#/components/parameters/OrderId"}],"post":{"operationId":"payOrder","summary":"Pay an order that was placed but not charged.","description":"Charges an order left `pending_payment` (or retries one that is `payment_failed`), wallet credit first and the remainder on the org's default mandate. This is where the guest funnel's `next: \"payment\"` step lands: checkout converts the cart when it places the order, so the cart endpoint cannot settle it afterwards and this is the only surface that can.\n\n**Idempotent without an `Idempotency-Key`**, unlike checkout. The order already exists and is itself the dedup scope, so a double-submit records the same capture rather than taking a second one. A pay attempt against an already-paid order returns that order unchanged rather than an error.\n\nA **declined card answers 200**, not 402: the attempt was processed exactly as asked and the order comes back `payment_failed` for the caller to read. Only the platform being unable to charge at all — no gateway configured, or one an operator has deliberately disabled — is a 503. A decline on the customer's side (their bank said no, 3-D Secure not completed, card details wrong) arms ONE short help e-mail (`order.payment_help`) an hour later, tailored to the cause and the card's country, and sent only if nothing has been paid by then; a failure on our side never does.\n\n**Choosing a gateway.** Send `gateway` to settle this order on a specific rail rather than the org's default mandate — the owner's *\"settle overdue bills with any gateway they like\"*. It must be one of `getOrderPaymentOptions`'s entries, which is why a reseller's client (who has exactly one) cannot be re-routed. Rails that finish in the browser — PayPal approval, a crypto invoice — answer `200` with the order still `pending_payment` and a `customer_action` carrying the URL to send the customer to; the order settles when the gateway's webhook confirms it.","tags":["commerce"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"gateway":{"type":"string","description":"The rail to settle on (`stripe`, `paypal`, `nowpayments`). Omit to use the org's nominated payment method. `422` if it is not one of this order's `getOrderPaymentOptions`.","example":"paypal"},"payment_method_id":{"type":"string","format":"uuid","description":"Which of the organisation's own saved cards to charge (s1014 row 1108#28). After a decline (\"insufficient funds\") the fix is another card, and without a pick a retry charges the primary mandate, which is the card that was just declined. Must be one of this organisation's chargeable mandates (`listPaymentMethods`, `status: active`) on the rail being charged; anything else is `422` with `details[0].field = payment_method_id` before anything is charged, never a fall back to the primary. A pick pins this charge only and never changes which card is primary. Omit to charge the primary, then backup.","example":"3f6c1a52-8e0b-4d1e-9b7a-2c5d4e6f7a81"}}}}}},"responses":{"200":{"description":"The order after the attempt. Read `status`: `paid` on success, `payment_failed` on a decline, still `pending_payment` if the gateway answered asynchronously and its webhook has yet to confirm.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Order"},{"type":"object","properties":{"customer_action":{"type":"object","description":"Present only when the attempt needs the customer to finish it in a browser (PayPal approval, a crypto invoice, a 3-D Secure step). Short-lived and never stored — request it again rather than keeping it.","required":["kind","url"],"properties":{"kind":{"type":"string","example":"approve"},"url":{"type":"string","format":"uri"}}}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"The order is in a state that cannot be paid (canceled, refunding, draft), or `gateway` names a rail this order may not be settled on, or the card's share is under the gateway's smallest charge and account credit cannot cover the whole order (docs/31 §4.4), or the gateway answered and refused the charge. Nothing was charged and any account credit drawn was given back.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`error.details[0].code` `COUPON_WITHDRAWN` (docs/1311): the order's coupon claim had lapsed while it sat unpaid and the code can no longer be used (its cap was reached, or this customer has used it since), so the code was removed and the order repriced to the full total, tax re-rated. Nothing was charged; the keyed message (`refusal.commerce.couponWithdrawn`) states the new total, and paying again pays it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"description":"No payment gateway can charge this order — unconfigured, or disabled by an operator; or the chosen rail stopped being usable mid-request. Nothing was charged and the order stays payable, on this rail or another.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/orders/{orderId}/payment-step-abandoned":{"parameters":[{"$ref":"#/components/parameters/OrderId"}],"post":{"operationId":"reportOrderPaymentStepAbandoned","summary":"Tell staff the customer left an in-place payment step without paying.","description":"Q225. Called when a customer closes the on-session payment step of a one-click purchase (`PaymentStep`) without paying. It moves no money and changes no status — the order stays payable from Billing and nothing was declined — and raises the staff alert *\"Checkout abandoned at payment\"* **once per order**, never for one of our own internal or test organisations.\n\nAlways `204`: an order that is paid, not a one-click purchase, or already reported is simply nothing to tell anyone.","tags":["commerce"],"responses":{"204":{"description":"Recorded (or nothing to record)."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/orders/{orderId}/customer-action":{"parameters":[{"$ref":"#/components/parameters/OrderId"}],"post":{"operationId":"openOrderCustomerAction","summary":"Reopen the checkout for a payment that is waiting on the customer.","description":"Returns where the customer finishes paying an order that is already part-way through a payment — the NOWPayments hosted crypto invoice, a PayPal approval page, or a fresh Stripe SCA credential. This is what makes a crypto order payable: the gateway supplies that link once, at the instant the invoice is opened, and until this endpoint existed nothing gave it to the customer.\n\n**It never charges.** `POST /v1/orders/{orderId}/pay` is the guarded surface that opens a payment; this one only reopens the checkout for a payment already in progress, so it sits behind none of the card-testing defences and needs none. Call `/pay` first; come back here to send the customer to the checkout, and again whenever they return to it later.\n\n**A crypto action always returns the SAME invoice.** The confirming IPN is matched on the invoice id recorded against the payment, so a second invoice for one order would take the customer's money against a record that does not exist. NOWPayments has no read-invoice endpoint either, so the link captured when the invoice was opened is the only one there is.","tags":["commerce"],"responses":{"200":{"description":"Where to send the customer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderCustomerAction"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"There is nothing for the customer to do — the order is already paid, is in a state that cannot be paid, has no payment in progress yet, or its checkout can no longer be reopened. The message says which, and is safe to show.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/orders/{orderId}/paypal":{"parameters":[{"$ref":"#/components/parameters/OrderId"}],"post":{"operationId":"openPayPalOrder","summary":"Open a PayPal order for the browser to complete.","description":"Returns the PayPal order id the JS SDK attaches to. The order carries no `payment_source`, so it is open to **either** rail — the PayPal wallet via Buttons, or a card entered into PayPal's hosted Advanced card fields — and the buyer's choice in the browser decides which. Idempotent per Zinn® order: reloading the checkout page returns the same PayPal order rather than opening a second one.\n\nWhen the order lets account credit pay first (`use_credit`, row 1106#49) the PayPal order is opened for the total **less** that credit; the credit is debited just before capture and given back if the capture is declined or the approval abandoned.","tags":["commerce"],"responses":{"200":{"description":"The PayPal order to complete in the browser.","content":{"application/json":{"schema":{"type":"object","required":["paypal_order_id"],"properties":{"paypal_order_id":{"type":"string","description":"PayPal's order id, for `createOrder` in the JS SDK."},"amount_minor":{"type":"integer","format":"int64","description":"What the PayPal order was opened for, in minor units (the total less any credit)."},"credit_minor":{"type":"integer","format":"int64","description":"The account credit that pays the rest, in minor units; 0 when none."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"The order is already paid, or in a state that cannot be paid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"description":"PayPal is not configured, or an operator has disabled it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/orders/{orderId}/paypal/capture":{"parameters":[{"$ref":"#/components/parameters/OrderId"}],"post":{"operationId":"capturePayPalOrder","summary":"Capture a PayPal order the buyer completed.","description":"Settles the order against a PayPal order the buyer has approved (wallet) or paid by card (including any 3-D Secure step).\n\n⛔ **The browser is not believed.** It reports that the buyer finished; only PayPal's capture response says money moved, and only the engine writes a payment. Posting an invented `paypal_order_id` produces a gateway error, never a paid order.\n\nA **declined card answers 200** with the order `payment_failed`, for the same reason `payOrder` does — the attempt was processed exactly as asked. A decline on the customer's side (e.g. `INSTRUMENT_DECLINED`) also arms a one-hour help e-mail (`order.payment_help`), sent only if nothing is paid by then.","tags":["commerce"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["paypal_order_id"],"properties":{"paypal_order_id":{"type":"string","description":"The id returned by `openPayPalOrder` and completed in the browser."}}}}}},"responses":{"200":{"description":"The order after the attempt. Read `status`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"No `paypal_order_id`, an id that was not opened for this order at its total, or the order cannot be paid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Nothing was captured: the account credit the PayPal order was priced against is no longer there (open PayPal again), or a dedicated server sold since approval.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"description":"PayPal is not configured, or an operator has disabled it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/orders/{orderId}/refund-eligibility":{"parameters":[{"$ref":"#/components/parameters/OrderId"}],"get":{"operationId":"getRefundEligibility","summary":"Preview an order's refund eligibility.","description":"The refund policy's decision for this order without opening a request — whether it is eligible, the amount that would be refunded, and whether it needs staff approval (docs/05 §4.13). Requires `billing.view`.","tags":["commerce"],"responses":{"200":{"description":"The policy decision.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundEligibility"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/orders/{orderId}/refund-request":{"parameters":[{"$ref":"#/components/parameters/OrderId"}],"post":{"operationId":"requestRefund","summary":"Request a refund for an order.","description":"Opens a refund request per the policy: within the 30-day money-back window the refund is issued immediately (status `auto_approved`); otherwise a pro-rata request is recorded `pending` for staff approval (docs/05 §4.13). The amount and approval path come from the server, never the client. Requires `billing.payment.manage`.","tags":["commerce"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundRequestCreate"}}}},"responses":{"201":{"description":"The refund request (issued or pending).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundRequest"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/refund-requests":{"get":{"operationId":"listRefundRequests","summary":"List the organization's refund requests.","description":"The refund requests in scope, newest first. Cursor-paginated, RLS-scoped; requires `billing.view`.","tags":["commerce"],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"status","in":"query","required":false,"description":"Filter by refund-request status.","schema":{"$ref":"#/components/schemas/RefundRequestStatus"}}],"responses":{"200":{"description":"A page of refund requests.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundRequestPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/refund-requests/{refundRequestId}":{"parameters":[{"$ref":"#/components/parameters/RefundRequestId"}],"get":{"operationId":"getRefundRequest","summary":"Get a refund request.","description":"Returns one refund request in scope, with its policy class, amount and outcome. Requires `billing.view`.","tags":["commerce"],"responses":{"200":{"description":"The refund request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundRequest"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/refund-requests/{refundRequestId}/approve":{"parameters":[{"$ref":"#/components/parameters/RefundRequestId"}],"post":{"operationId":"approveRefundRequest","summary":"Approve a pending refund request (staff).","description":"Approves a pending (pro-rata / goodwill) refund request and issues the refund as Zinn® credit (owner ruling 2026-10-26: refunds are never sent back to the original payment source). Staff-only — requires the `billing.refund` permission held by a staff role, not by any customer role. `to_original_source: true` is the owner's override only: anyone else gets 403, a blank `override_reason` gets 403, and a granted override is audit-logged as `refund.original_source_override`.","tags":["commerce"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundApproveInput"}}}},"responses":{"200":{"description":"The approved refund request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundRequest"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/refund-requests/{refundRequestId}/reject":{"parameters":[{"$ref":"#/components/parameters/RefundRequestId"}],"post":{"operationId":"rejectRefundRequest","summary":"Reject a pending refund request (staff).","description":"Declines a pending refund request; no money moves. Staff-only — requires `billing.refund`.","tags":["commerce"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundDecisionInput"}}}},"responses":{"200":{"description":"The rejected refund request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundRequest"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/extras":{"get":{"operationId":"listExtras","summary":"List purchasable services.","description":"The extras (services) catalog — DB maintenance, SSL setup, managed migration, malware cleanup, and more (docs/26). Optionally filtered to those offered on a product line. Requires `billing.view`.\n\n**`price` is in the caller's currency.** `Extra` rows are stored in the base currency only (there is no per-currency price table as plans have), so each price is converted per request from the cached FX rates and `price.currency` reports the code actually used — which falls back to the base currency when the requested one has no stored rate, rather than labelling an unconverted amount with the requested symbol. Send `X-Zinn-Currency` to choose. `purchaseExtra` applies the **same** conversion and captures it, so the amount shown here is the amount billed (#471).","tags":["extras"],"parameters":[{"name":"product_line","in":"query","required":false,"description":"Only extras offered on this product line.","schema":{"type":"string"}},{"name":"locale","in":"query","required":false,"description":"The language the app is rendering in (a BCP 47 tag such as `ar` or `pt-PT`). A supported value is the language each extra's `name` and `description` are served in; an absent or unsupported one falls back to the caller's stored language preference. Never read from `Accept-Language`.","schema":{"type":"string","maxLength":35}}],"responses":{"200":{"description":"The extras catalog.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtraList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/extra-purchases/{purchaseId}/cancel":{"parameters":[{"name":"purchaseId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"cancelBoostPurchase","tags":["extras"],"summary":"Remove a performance boost at the end of its paid month.","description":"Stops a performance boost renewing (`docs/866` §3). It keeps working until `ends_at` (the date the customer paid to), then the site returns to its plan's rung at the next converge. Nothing is refunded. Refusals: `not_a_boost`, `already_cancelled`, `already_ended`. Requires `billing.payment.manage` in the purchase's organization.","responses":{"200":{"description":"The boost will stop renewing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoostCancelResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/pbn-boost":{"get":{"operationId":"getPbnBoost","tags":["extras"],"summary":"The account's PBN Performance Boost — level, price, and which sites have it.","description":"One boost level for a whole Footprint-Free (PBN) account (`docs/897`): 1.5x, 2x or 3x every PBN site's CPU and memory, including sites added later. Priced per site per month on the account's total PBN site count with a monthly minimum, in the caller's currency, and re-priced only at renewal. `sites` says how many active PBN sites have it now and how many wait for room on their server (waiting sites are counted in the price). The organization is `org_id` or `X-Zinn-Org`. Requires `billing.view`.","parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The account's boost state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PbnBoostState"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"post":{"operationId":"choosePbnBoost","tags":["extras"],"summary":"Choose or change the account's PBN Performance Boost level.","description":"Buys the level through the ordinary add-on purchase (charge, tax, invoice), priced `max(minimum, per site x sites)` on today's PBN site count. Choosing another level replaces the current one and credits its unused days to the account. Staff organizations are not charged. Refusals (`details[].code`): `pbn_boost_unknown_level`, `pbn_boost_no_pbn_line`, `pbn_boost_same_level`. `PAYMENT_METHOD_REQUIRED` means no payment method is on file and nothing was charged. **Paying in place (Q225).** When nothing on file can settle it, the purchase is **placed** (order `pending_payment`, purchase `awaiting_payment`) and NOT charged: the `422 PAYMENT_METHOD_REQUIRED` envelope carries `error.payment` — the order to settle on-session with `payOrder` / `openPayPalOrder` / `openOrderCustomerAction`, exactly as the basket checkout does. Paying it completes the purchase and starts fulfilment as a stored-card buy would; no order is ever recorded as failed for money nobody was asked for. Repeating the request within 24 hours resumes the SAME order (and charges it, if a payment method has been added since) rather than placing another. Requires `billing.payment.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PbnBoostChoose"}}}},"responses":{"201":{"description":"The purchase was made and is being applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PbnBoostPurchase"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/pbn-boost/cancel":{"post":{"operationId":"cancelPbnBoost","tags":["extras"],"summary":"Stop the account's PBN Performance Boost.","description":"A paid boost stops renewing and keeps working until `ends_at` (the end of the paid month); nothing is refunded. A staff organization's boost ends at once. After it ends every PBN site returns to its plan's limits at the next converge. Refusal: `pbn_boost_none`. Requires `billing.payment.manage`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"The boost will stop.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoostCancelResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/code-care":{"get":{"operationId":"getCodeCare","tags":["code-care"],"summary":"The account's Code Care plan, this month's hours, and the fix rate.","description":"Code Care (`docs/1327`): a monthly add-on of included developer time (Basic 1 h, Standard 2.5 h, Pro 6 h) plus a discount on extra time. `tier` is null when the account has none. `plans` are priced in the caller's currency (EUR exact, others converted). `allowance` is the month the account is in now: included, used, reserved by approved jobs and left, in minutes; `frozen` is true while a fix invoice is unpaid. `rate` is the pay-as-you-go rate (15-minute blocks, 30-minute minimum per job). The organization is `org_id` or `X-Zinn-Org`. Requires `billing.view`.","parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The Code Care state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CodeCareState"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"post":{"operationId":"chooseCodeCare","tags":["code-care"],"summary":"Buy Code Care, or move to another tier.","description":"Buys the tier through the ordinary add-on purchase (charge, tax as a human professional service, invoice). A higher tier takes effect at once and charges the pro-rata difference; a lower tier is scheduled for the renewal and charges nothing now (`scheduled: true`). There is a 3-month minimum term. `PAYMENT_METHOD_REQUIRED` carries `error.payment`, the order to settle on-session, exactly as the add-on checkout does. Requires `billing.payment.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CodeCareChoose"}}}},"responses":{"200":{"description":"A downgrade was scheduled for the renewal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CodeCareChooseResult"}}}},"201":{"description":"The purchase was made.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CodeCareChooseResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/code-care/cancel":{"post":{"operationId":"cancelCodeCare","tags":["code-care"],"summary":"Stop Code Care renewing.","description":"Code Care keeps running to the later of the paid-through date and the end of the 3-month minimum, then stops; nothing is refunded. Refusals (`details[].code`): `code_care_none`, `already_cancelled`. Requires `billing.payment.manage`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"When it ends.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CodeCareCancelResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/dev-requests":{"get":{"operationId":"listDevRequests","tags":["code-care"],"summary":"The account's fix requests, newest first.","description":"Every fix request of the organization with its estimate, the covered/extra split and money, the logged time and the work notes. Requires `tickets.view`.","parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The fix requests.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DevRequestList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"post":{"operationId":"createDevRequest","tags":["code-care"],"summary":"Ask for a fix (a bug, an error, a plugin, theme or code change).","description":"Opens a fix request and its support ticket. Nothing is charged: the request is quoted first (an AI draft, sent automatically only when it is at most 30 minutes, fully covered by Code Care and bills nothing; otherwise staff approve or edit it) and work starts only after the customer approves. `access_consent` must be true (we may log in and change files). Refused while the account is not in good standing or a fix invoice is unpaid (`not_in_good_standing`, `dev_invoice_unpaid`). Requires `tickets.reply`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DevRequestCreate"}}}},"responses":{"201":{"description":"The request was opened.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DevRequest"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/dev-requests/{request_id}":{"get":{"operationId":"getDevRequest","tags":["code-care"],"summary":"One fix request.","description":"The request, its estimate and split, and its work log. Requires `tickets.view`.","parameters":[{"$ref":"#/components/parameters/DevRequestId"}],"responses":{"200":{"description":"The fix request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DevRequest"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/dev-requests/{request_id}/approve":{"post":{"operationId":"approveDevRequestEstimate","tags":["code-care"],"summary":"Approve the estimate; work may start.","description":"Reserves the covered time from the allowance of the month it is approved in and commits to the extra money shown (billed on completion for the real time, never above the approved estimate). `terms_version` must be the current Development services & Code Care terms. Refusals: `not_estimated`, `terms_not_accepted`, `split_changed` (the allowance moved; re-read and approve again), `dev_invoice_unpaid`, `not_in_good_standing`. Requires `billing.payment.manage`.","parameters":[{"$ref":"#/components/parameters/DevRequestId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DevRequestApprove"}}}},"responses":{"200":{"description":"The fix request after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DevRequest"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/dev-requests/{request_id}/decline":{"post":{"operationId":"declineDevRequestEstimate","tags":["code-care"],"summary":"Decline the estimate.","description":"Nothing is charged. Requires `tickets.reply`.","parameters":[{"$ref":"#/components/parameters/DevRequestId"}],"responses":{"200":{"description":"The fix request after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DevRequest"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/dev-requests/{request_id}/cancel":{"post":{"operationId":"cancelDevRequest","tags":["code-care"],"summary":"Cancel a fix request before any work is logged.","description":"Requires `tickets.reply`.","parameters":[{"$ref":"#/components/parameters/DevRequestId"}],"responses":{"200":{"description":"The fix request after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DevRequest"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/dev-requests/{request_id}/accept":{"post":{"operationId":"acceptDevRequest","tags":["code-care"],"summary":"Accept finished work.","description":"Closes a request that is ready for the check. Requires `tickets.reply`.","parameters":[{"$ref":"#/components/parameters/DevRequestId"}],"responses":{"200":{"description":"The fix request after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DevRequest"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/dev-requests/{request_id}/reopen":{"post":{"operationId":"reopenDevRequest","tags":["code-care"],"summary":"Reopen finished work within 7 days.","description":"Sends it back to the developer with a note. Requires `tickets.reply`.","parameters":[{"$ref":"#/components/parameters/DevRequestId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DevRequestNote"}}}},"responses":{"200":{"description":"The fix request after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DevRequest"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/account-boost":{"get":{"operationId":"getAccountBoost","tags":["extras"],"summary":"The account's Account Performance Boost — level, price, and which sites have it.","description":"The PBN boost's model for every OTHER hosting line we run on our own fleet (Q308, `docs/866` §3c): one level for the whole account, 1.5x, 2x or 3x every counted site's CPU and memory (capped at the most one server gives a site), including sites added later. Priced per site per month by the site's class — `standard` (WordPress, PHP, a PHP application) or `heavy` (WooCommerce, Node, Python, Ruby, .NET, Nextcloud, headless CMS, and every site on app, LMS, AI and developer hosting) — derived from measured box economics, with a monthly minimum, re-priced only at renewal. Static sites are not counted. `on_sale` is false until the owner approves the prices; the card then shows the figures without a buy button. The organization is `org_id` or `X-Zinn-Org`. Requires `billing.view`.","parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The account's boost state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountBoostState"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"post":{"operationId":"chooseAccountBoost","tags":["extras"],"summary":"Choose or change the account's Account Performance Boost level.","description":"Buys the level through the ordinary add-on purchase (charge, tax, invoice), priced `max(minimum, Σ per-site rate x sites)` on today's counted sites. Choosing another level replaces the current one and credits its unused days. Refusals (`details[].code`): `account_boost_not_on_sale`, `account_boost_unknown_level`, `account_boost_no_line`, `account_boost_same_level`. Paying in place works exactly as `choosePbnBoost` (Q225). Requires `billing.payment.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PbnBoostChoose"}}}},"responses":{"201":{"description":"The purchase was made and is being applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PbnBoostPurchase"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/account-boost/cancel":{"post":{"operationId":"cancelAccountBoost","tags":["extras"],"summary":"Stop the account's Account Performance Boost.","description":"A paid boost stops renewing and keeps working until `ends_at` (the end of the paid month); nothing is refunded. A staff organization's boost ends at once. Refusal: `account_boost_none`. Requires `billing.payment.manage`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"The boost will stop.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoostCancelResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/extras/{code}/tier-change":{"parameters":[{"$ref":"#/components/parameters/ExtraCode"}],"get":{"operationId":"getExtraTierChange","summary":"What choosing this SEO tool tier would do to the tier already held.","description":"Q321 (V1 parity, `zinnseo/pricing.py`). `tier_change` is `null` when the organisation holds no other tier of the same SEO tool — buying is an ordinary purchase. Otherwise `kind` says which change it is. An `upgrade`: `charge_now_minor` is charged at purchase (the share of the current period left × (new period price − the held tier's renewal), each share half-up; a difference under 1.00 is waived and reported in `waived_minor`), the held tier stops, and the new tier renews at `renewal_minor` on `renews_on` — the held tier's own day, term and currency; `POST /v1/extras/{code}/purchase` charges exactly this. A `downgrade` is never bought now: it is chosen for the renewal with `POST /v1/extras/{code}/tier-change` (nothing is charged; `charge_now_minor` is 0), and on `renews_on` it replaces the held tier and bills `renewal_minor` in its place. `scheduled` says whether this tier is already chosen; `scheduled_code` names whichever tier is.","tags":["extras"],"responses":{"200":{"description":"The tier change, or null.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtraTierChangeEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"post":{"operationId":"scheduleExtraTierSwitch","summary":"Choose this smaller SEO tool tier for the next renewal.","description":"Q321 (V1 parity: *\"lowering is chosen for the renewal and costs nothing now\"*). Records that the tier of the same tool the organisation holds renews as this SMALLER tier. Nothing is charged and nothing changes today: the held tier keeps working until `renews_on`, when a purchase of this tier replaces it and its period price is billed in place of the old renewal — same day, term and currency, with the SEO bundle and yearly savings applied as for any renewal. Idempotent; choosing another smaller tier replaces the choice. `422 refusal.extras.tierSwitchIsUpgrade` when this tier is bigger (buy it instead), `refusal.extras.tierSwitchNothingHeld` when no other tier of the tool is held. Requires `billing.payment.manage`.","tags":["extras"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"org_id":{"type":"string","format":"uuid","description":"The organisation, when the caller can act for several."}}}}}},"responses":{"200":{"description":"The scheduled switch (`kind` `downgrade`, `scheduled` true).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtraTierChangeEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"cancelExtraTierSwitch","summary":"Withdraw a switch to this tier chosen for the next renewal.","description":"Q321. The held tier renews as itself. `404` when this tier was not chosen. Requires `billing.payment.manage`.","tags":["extras"],"responses":{"204":{"description":"The choice is withdrawn."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/extras/{code}/purchase":{"parameters":[{"$ref":"#/components/parameters/ExtraCode"}],"post":{"operationId":"purchaseExtra","summary":"Purchase an extra service.","description":"Buys the extra: it is charged wallet-first then gateway, and handed to durable fulfilment (an automated workflow, or a staff task). The price and fulfilment path are server-decided (docs/26 §3). Requires `billing.payment.manage`.\n\nTwo different `422`s, and a client must tell them apart: `PAYMENT_METHOD_REQUIRED` means the organization holds no chargeable payment method, so nothing was presented to any gateway and nothing was refused — the remedy is to add a payment method — or pay with PayPal or cryptocurrency — and buy again. `UNPROCESSABLE_ENTITY` on this path is a genuine gateway decline. Reporting the first as the second tells a customer who has never entered a card that their bank refused them (`docs/491` §7).\n\n**Paying in place (Q225).** When nothing on file can settle it, the purchase is **placed** (order `pending_payment`, purchase `awaiting_payment`) and NOT charged: the `422 PAYMENT_METHOD_REQUIRED` envelope carries `error.payment` — the order to settle on-session with `payOrder` / `openPayPalOrder` / `openOrderCustomerAction`, exactly as the basket checkout does. Paying it completes the purchase and starts fulfilment as a stored-card buy would; no order is ever recorded as failed for money nobody was asked for. Repeating the request within 24 hours resumes the SAME order (and charges it, if a payment method has been added since) rather than placing another.","tags":["extras"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtraPurchaseCreate"}}}},"responses":{"201":{"description":"The purchase (charged, fulfilment under way).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtraPurchase"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/extra-purchases":{"get":{"operationId":"listExtraPurchases","summary":"List the organization's extra purchases.","description":"The org's extra purchases + their fulfilment outcome, newest first. Cursor-paginated, RLS-scoped; requires `billing.view`.","tags":["extras"],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"status","in":"query","required":false,"description":"Filter by purchase status.","schema":{"$ref":"#/components/schemas/ExtraPurchaseStatus"}}],"responses":{"200":{"description":"A page of extra purchases.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtraPurchasePage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/extra-purchases/{purchaseId}":{"parameters":[{"$ref":"#/components/parameters/ExtraPurchaseId"}],"get":{"operationId":"getExtraPurchase","summary":"Get an extra purchase.","description":"Returns one extra purchase in scope with its status and outcome. Requires `billing.view`.","tags":["extras"],"responses":{"200":{"description":"The extra purchase.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtraPurchase"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/platform-transfers/platforms":{"get":{"operationId":"listTransferPlatforms","summary":"Platforms we can move a store from and to, and what the calculator offers.","description":"Everything the price calculator is built from, in one response: the source and target platforms grouped for display, the optional add-ons, the aftercare levels, the store-access methods and the minimum price. Requires `billing.view`.\n\n**Targets (owner ruling 2026-10-25):** any platform we can land a store on is a target — Shopify, BigCommerce and Wix included. `can_host` says whether we can also BUILD the new store on our hosting, which the calculator offers first.\n\n`minimum_price_minor` is in the caller's currency, converted from the cached FX rates by the same function the charge captures. Send `X-Zinn-Currency` to choose.","tags":["platform-transfers"],"responses":{"200":{"description":"The selector payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferPlatformCatalogue"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/platform-transfers/quote":{"post":{"operationId":"quotePlatformTransfer","summary":"Price a transfer without buying it.","description":"The calculator: the price of this exact move (platforms, counts, add-ons and aftercare). Creates nothing and charges nothing. Requires `billing.view`. `422` when the exact move cannot be priced automatically (usually an add-on that is not available between the two platforms) or the calculator is briefly busy; the message says which.","tags":["platform-transfers"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferQuoteRequest"}}}},"responses":{"200":{"description":"The quote.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferQuote"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/platform-transfers":{"get":{"operationId":"listPlatformTransfers","summary":"Your organisation's platform transfers.","description":"Every transfer in scope, newest first, each with the customer-visible part of its progress trail. Requires `billing.view`.","tags":["platform-transfers"],"parameters":[{"name":"status","in":"query","required":false,"description":"Only transfers in this state.","schema":{"$ref":"#/components/schemas/PlatformTransferStatus"}},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"The transfers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformTransferList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createPlatformTransfer","summary":"Book a platform transfer (nothing is charged yet).","description":"Creates the request in `draft` at the calculator's price for the same move. **No money moves here** — call `payPlatformTransfer` to charge it. Store logins are not taken here; they go through `updatePlatformTransferIntake`. The row is written before the charge on purpose: a declined card then leaves a visible `payment_failed` transfer rather than a charge for a job nobody can see. Requires `billing.view`.","tags":["platform-transfers"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformTransferCreate"}}}},"responses":{"201":{"description":"The draft transfer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformTransfer"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/platform-transfers/{transferId}":{"parameters":[{"name":"transferId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getPlatformTransfer","summary":"One transfer and its progress.","tags":["platform-transfers"],"responses":{"200":{"description":"The transfer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformTransfer"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/platform-transfers/{transferId}/pay":{"parameters":[{"name":"transferId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"payPlatformTransfer","summary":"Pay for a transfer and queue it for a specialist.","description":"Charges the quoted price through the extras rails — wallet first, then the gateway — and sets the SLA. The transfer moves to `queued` when every intake detail is in, otherwise to `awaiting_customer` with `intake_missing` naming what is needed (nothing is placed with a specialist until it is complete). Requires `billing.payment.manage`, because it moves money; creating the draft needs only `billing.view`.\n\nA decline returns `422` and leaves the transfer in `payment_failed`; nothing is charged and the same transfer can be paid again with another method. An organization with **no** chargeable payment method gets `422` `PAYMENT_METHOD_REQUIRED` instead — nothing was presented to a gateway, so it is not a decline: the remedy is to choose a payment method (`getPaymentOptions` lists the rails this account can use) rather than to fix a card (`docs/491` §7). The transfer then stays `draft`, linked to the waiting purchase, and is queued the moment that order is paid.\n\n**Paying in place (Q225).** When nothing on file can settle it, the purchase is **placed** (order `pending_payment`, purchase `awaiting_payment`) and NOT charged: the `422 PAYMENT_METHOD_REQUIRED` envelope carries `error.payment` — the order to settle on-session with `payOrder` / `openPayPalOrder` / `openOrderCustomerAction`, exactly as the basket checkout does. Paying it completes the purchase and starts fulfilment as a stored-card buy would; no order is ever recorded as failed for money nobody was asked for. Repeating the request within 24 hours resumes the SAME order (and charges it, if a payment method has been added since) rather than placing another.","tags":["platform-transfers"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformTransferPay"}}}},"responses":{"200":{"description":"The paid transfer (`queued`, or `awaiting_customer` while details are missing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformTransfer"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/platform-transfers/{transferId}/intake":{"parameters":[{"name":"transferId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"operationId":"updatePlatformTransferIntake","summary":"Give or change the store details a transfer needs.","description":"The guided details step: store addresses, how we access each store, logins, the contact and the preferred window. Every field is optional; only those present are applied. **Logins are written to the secrets vault only** — the response carries a masked hint and `has_*_credentials`, never the secret — and are deleted when the job ends. Each address is checked for reachability (`intake_checks`). A paid transfer in `awaiting_customer` moves to `queued` once nothing is missing. Refused with `422` while the migration is running or after it has finished. Requires `billing.view`.","tags":["platform-transfers"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformTransferIntake"}}}},"responses":{"200":{"description":"The updated transfer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformTransfer"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/platform-transfers/platforms":{"get":{"operationId":"listPublicTransferPlatforms","summary":"The calculator's platforms and options, signed out.","description":"The same payload as `listTransferPlatforms`, for the public website's calculator. No authentication (a stale token is ignored, never a 401); rate-limited per client.","tags":["platform-transfers"],"security":[],"responses":{"200":{"description":"The calculator payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferPlatformCatalogue"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/platform-transfers/quote":{"post":{"operationId":"quotePublicPlatformTransfer","summary":"Price a store move, signed out.","description":"The same calculator as `quotePlatformTransfer`, for the public website. Creates nothing. No authentication; rate-limited per client (`429` with `Retry-After`).","tags":["platform-transfers"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferQuoteRequest"}}}},"responses":{"200":{"description":"The quote.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferQuote"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ip-allow":{"parameters":[{"name":"org_id","in":"query","required":false,"description":"The organization to act on. Omitted (or empty) means your own. A reseller managing a client org must name it - defaulting silently would edit the reseller's own list while the screen showed the client's.","schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listIpAllowEntries","summary":"Which addresses may open a shell on your sites.","description":"Your organisation's SSH/SFTP allow-list (#1493). While it is EMPTY your sites are reachable from anywhere; adding the first entry is what turns the restriction on.\n\n`restricted` says which of those two states you are in, in so many words. A client that inferred it from an empty array would be guessing at the difference between \"open to the whole internet\" and \"locked down\", which are opposite facts.\n\n`staff_ranges` is a COUNT, not the addresses. Zinn® support and provisioning are unioned into the effective list so a narrow entry of yours cannot lock us out of the site you have just called us about - but our infrastructure's ranges are not published to tenants.","tags":["security"],"responses":{"200":{"description":"The entries, and whether anything is actually restricted.","content":{"application/json":{"schema":{"type":"object","required":["entries","restricted","staff_ranges"],"properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/IpAllowEntry"}},"restricted":{"type":"boolean","description":"false = your sites are reachable from any address. An empty list is NOT a deny-all."},"staff_ranges":{"type":"integer","description":"How many Zinn® support ranges are unioned in."}}}}}}}},"post":{"operationId":"createIpAllowEntry","summary":"Allow an address or range.","description":"Adds one entry. A bare address is normalised to a host network (`203.0.113.7` becomes `203.0.113.7/32`) so the list holds one shape and you cannot add the same fact twice in two spellings.\n\n`0.0.0.0/0` and `::/0` are refused, and so is any prefix broader than /8 (IPv4) or /32 (IPv6): an entry that admits the whole internet is the same as having no allow-list, while reading on screen as though something is protected.","tags":["security"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IpAllowEntryWrite"}}}},"responses":{"201":{"description":"Added.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IpAllowEntry"}}}}}}},"/v1/ip-allow/{entry_id}":{"parameters":[{"name":"entry_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"patch":{"operationId":"updateIpAllowEntry","summary":"Change an entry.","description":"Partial update. Disabling an entry (`enabled: false`) is the reversible way to narrow access during an incident - it keeps the range visible so you can see what you turned off, which a deletion does not.","tags":["security"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IpAllowEntryWrite"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IpAllowEntry"}}}}}},"delete":{"operationId":"deleteIpAllowEntry","summary":"Remove an entry.","description":"Removing the LAST entry makes your sites reachable from anywhere again. That is the documented behaviour rather than a trap: a list nobody has filled in must never be read as a deny-all.","tags":["security"],"responses":{"204":{"description":"Removed."}}}},"/v1/outbound-mail":{"parameters":[{"name":"org_id","in":"query","required":false,"description":"The organization to act on. Omitted (or empty) means your own.","schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getOutboundMail","summary":"The mail service this organisation sends through.","description":"Agencies and resellers send their notifications through their OWN mail provider, at their own cost. This returns what is attached, whether it has been verified, and the form definition for every provider we support.\n\nAn organisation with nothing attached gets `account: null` and a `fallback_notice` saying in as many words that its mail is going out from the platform's domain on the platform's account. That sentence is part of the contract, not decoration: an empty state that does not say who is paying reads as \"nothing to do here\".","tags":["notifications"],"responses":{"200":{"description":"The attached service, or the reason there is not one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutboundMailState"}}}}}},"put":{"operationId":"setOutboundMail","summary":"Attach or replace this organisation's own mail service.","description":"PUT rather than POST because a From header is singular: an organisation has exactly one sending service, and the commonest reason to be on this screen is switching provider.\n\nThe credential is write-only. It goes straight to the secret vault and the row keeps only a pointer; it is never returned by any endpoint in any state.\n\nAttaching does NOT switch the sender. A new or replaced credential resets the account to `unverified`, and only a completed round trip - a real test message, and the code out of it - makes it the From address. A provider that accepts a message and then bounces it is indistinguishable from a working one at the moment of the call, so acceptance is not proof.","tags":["notifications"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["provider","from_domain","credential"],"properties":{"provider":{"type":"string","enum":["smtp","mailgun","sendgrid","postmark","ses","resend"],"description":"`ses` is Amazon SES over its documented SMTP interface, so the credential is an SES SMTP username and password rather than an AWS access key."},"from_domain":{"type":"string","maxLength":253,"description":"The domain your From address will use - a domain, not an address. The local part still comes from the message type, so a receipt leaves as `billing@` and a password reset as `no-reply@`, both on your domain."},"credential":{"type":"string","maxLength":1000,"writeOnly":true,"description":"The API key, server token or SMTP password. Never returned."},"config":{"type":"object","additionalProperties":true,"description":"The non-secret settings this provider needs - SMTP host/port/username, Mailgun domain and region, the SES region, the Postmark message stream. The exact fields are returned per provider by GET, so the form and its validation cannot drift apart. Unknown keys are dropped."}}}}}},"responses":{"200":{"description":"Attached, and awaiting the round-trip test.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutboundMailState"}}}}}},"delete":{"operationId":"deleteOutboundMail","summary":"Remove this organisation's own mail service.","description":"Removes the account and its stored credential. Notifications go back to the platform's sending identity from the next message.\n\nThe credential is removed from the vault BEFORE the row: if the vault cannot be reached the whole call fails and nothing changes, because the other order loses the pointer and leaves a live third-party credential under a prefix nothing enumerates.","tags":["notifications"],"responses":{"200":{"description":"Removed; you are back on the platform sender.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutboundMailState"}}}}}}},"/v1/outbound-mail/test":{"parameters":[{"name":"org_id","in":"query","required":false,"description":"The organization to act on. Omitted means your own.","schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"testOutboundMail","summary":"Send a real message through your provider, carrying a one-time code.","description":"Sends an actual email through the attached service to an address you nominate. It contains a code; enter that code at `/v1/outbound-mail/verify` to switch the account on.\n\nThe send happens before anything is stored. If your provider refuses the message the account stays exactly where it was and the error says what the provider said - a tenant with a wrong key must be told the key is wrong, not left waiting for a message that was never sent.","tags":["notifications"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["to"],"properties":{"to":{"type":"string","format":"email","description":"An inbox you can read. Use one OUTSIDE the domain you are configuring where you can: a message that never leaves your own server proves less than one that crossed the internet."}}}}}},"responses":{"200":{"description":"Sent; the account is now awaiting its code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutboundMailState"}}}}}}},"/v1/outbound-mail/verify":{"parameters":[{"name":"org_id","in":"query","required":false,"description":"The organization to act on. Omitted means your own.","schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"verifyOutboundMail","summary":"Enter the code from the test message.","description":"Completes the round trip. On success the account becomes the From address for every notification this organisation's brand sends, and the platform stops paying for them.\n\nThe code expires after an hour and survives five wrong attempts, after which a fresh test message is required. Each refusal says which of the three it is, because \"that did not work\" about a code with a TTL and an attempt limit is three problems with three different remedies.","tags":["notifications"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","maxLength":32}}}}}},"responses":{"200":{"description":"Verified; you are now sending as yourself.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutboundMailState"}}}}}}},"/v1/sites/{site_id}/notification-channels":{"parameters":[{"name":"site_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"description":"The organization to act on. Omitted resolves to your own ONLY when you belong to exactly one organisation; a principal in more than one must name it. A reseller managing a client org must name it - defaulting silently would write the reseller's own routing while the screen showed the client's.","schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getSiteNotificationChannels","summary":"Which channels this site's notifications go to.","description":"The destinations this site routes to, plus whether e-mail is currently being sent.\n\nThe response carries BOTH what the customer asked for (`email_muted`) and what is actually happening (`email_active`, `email_reason`), and they can differ. E-mail may be switched off only while another channel is connected and healthy; if every alternative goes bad, e-mail resumes on its own and `overriding_choice` is true. A client that rendered only the stored flag would show a toggle that disagrees with the customer's inbox - which is the exact failure this feature exists to prevent, because the notification telling you Slack has died would otherwise go to Slack.","tags":["notifications"],"responses":{"200":{"description":"The site's channels and the live e-mail decision.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteNotificationChannels"}}}}}},"put":{"operationId":"setSiteNotificationChannels","summary":"Replace this site's notification channels.","description":"The COMPLETE desired routing, sent as one document. A channel absent from the list is one the customer removed - a POST-only surface could not express removal, and the screen is a matrix the customer edits in several places before pressing save once.\n\nRefused `422` when `email_muted` is true and no listed destination is a non-e-mail channel that is verified and delivering. The check runs against the routing you are ABOUT to save, not the current one, so \"connect Slack and turn e-mail off\" works in a single request. It is refused at the point of asking rather than accepted and ignored: a toggle that accepts a value it will not honour reads as a broken setting.","tags":["notifications"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteNotificationChannelsUpdate"}}}},"responses":{"200":{"description":"The saved channels and the live e-mail decision.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteNotificationChannels"}}}},"422":{"description":"A destination this account cannot route to, or a mute with no healthy alternative.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/notification-phone":{"parameters":[{"name":"org_id","in":"query","required":false,"description":"The organization to act on, as for the other notification endpoints. Omitted resolves to your own only when you belong to exactly one organisation.","schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getNotificationPhone","summary":"Text-message and WhatsApp alerts for me in this organisation.","description":"Whether text messages (SMS) and WhatsApp alerts can be used here, the countries whose numbers we can text, my verified number on each channel and whether my consent is active, and the events a text can be sent for. A person only, never an API key. A white-label organisation sees both channels unavailable: texts come from Zinn®'s own sender, which would show our name to your clients.","tags":["notifications"],"responses":{"200":{"description":"What is available and which of my channels are on.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationPhoneState"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/notification-phone/start":{"parameters":[{"name":"org_id","in":"query","required":false,"description":"The organization to act on, as above.","schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"startNotificationPhone","summary":"Text a six-digit code to my number.","description":"Sends one code to the number by text message (and on WhatsApp when only WhatsApp is asked for). `consent` must be true: it records that I agreed to receive alert texts on this number (the wording version is `consent_text_version`). Refused when the channel is unavailable, the number's country is not open, the organisation is white-label or not in good standing, or too many codes were asked for (429). No topic is switched on by this: every topic stays off for texts until I turn it on in the routing grid. A +1 (US/Canada) number is single opt-in: no code is sent; the number is connected at once, one confirmation text is sent, and `confirmed` is true (skip the confirm step). A +1 number is texted only account notices (payments, orders, mail DNS action needed); its connection carries `us_ca_limited`.","tags":["notifications"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone","channels","consent"],"properties":{"phone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$","description":"The mobile number in international form, e.g. +447700900123."},"channels":{"type":"array","minItems":1,"maxItems":2,"items":{"type":"string","enum":["sms","whatsapp"]}},"consent":{"type":"boolean","description":"The consent tick. Must be true."},"locale":{"type":"string","maxLength":16}}}}}},"responses":{"201":{"description":"The code was sent, or (a +1 number) the number is connected.","content":{"application/json":{"schema":{"type":"object","required":["verification_id","expires_at","confirmed"],"properties":{"verification_id":{"type":"string","format":"uuid"},"expires_at":{"type":"string","format":"date-time"},"confirmed":{"type":"boolean","description":"True for a +1 number (single opt-in): it is already connected, there is no code to confirm."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/notification-phone/confirm":{"parameters":[{"name":"org_id","in":"query","required":false,"description":"The organization to act on, as above.","schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"confirmNotificationPhone","summary":"Confirm the code; my number is connected with every topic off.","description":"A code works once, for ten minutes, and five wrong tries spend it. On success each asked channel becomes a `kind=sms` or `kind=whatsapp` notification connection owned by me, with every topic off until I turn it on.","tags":["notifications"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["verification_id","code"],"properties":{"verification_id":{"type":"string","format":"uuid"},"code":{"type":"string","pattern":"^\\s*\\d{6}\\s*$"}}}}}},"responses":{"200":{"description":"Connected. The new state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationPhoneState"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/notification-phone/{channel}":{"parameters":[{"name":"org_id","in":"query","required":false,"description":"The organization to act on, as above.","schema":{"type":"string","format":"uuid"}},{"name":"channel","in":"path","required":true,"schema":{"type":"string","enum":["sms","whatsapp"]}}],"delete":{"operationId":"revokeNotificationPhone","summary":"Stop alert texts on one channel.","description":"Removes my connection on this channel and records my consent as withdrawn (the consent record itself is kept, as proof of when it was given and withdrawn).","tags":["notifications"],"responses":{"200":{"description":"Stopped. The new state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationPhoneState"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/me/push-devices":{"parameters":[{"name":"org_id","in":"query","required":false,"description":"The organization to act on, as for the other notification endpoints. Omitted resolves to your own only when you belong to exactly one organisation.","schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listPushDevices","summary":"The phones registered to me for alerts in this organisation.","description":"Every phone on which the signed-in person has installed the phone app and allowed notifications, newest first. Each phone is also a `kind=push` notification connection (`connection_id`), so the routing grid, health and delivery log treat it like any other destination. A person only, never an API key: an API key has no phone.","tags":["notifications"],"responses":{"200":{"description":"My phones.","content":{"application/json":{"schema":{"type":"object","required":["devices"],"properties":{"devices":{"type":"array","items":{"$ref":"#/components/schemas/PushDevice"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"registerPushDevice","summary":"Register (or re-register) this phone for alerts.","description":"Called by the app after the customer allows notifications, and again whenever the push token rotates. The token is PROVED first with a silent dry run at the push service, so the phone is created already verified and a token the service refuses is refused here (422) instead of being stored to fail on a real alert. One row per install: the same `installation_id` updates its row (200); a new install creates one (201). A token another person in this organisation held on the same phone moves to the caller.","tags":["notifications"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["installation_id","token","platform"],"properties":{"installation_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$","description":"A random id the app generates once per install and keeps."},"token":{"type":"string","minLength":20,"maxLength":320,"writeOnly":true,"description":"The push token the phone's operating system issued to the app."},"platform":{"type":"string","enum":["ios","android"]},"device_name":{"type":"string","maxLength":120},"os_version":{"type":"string","maxLength":60},"app_version":{"type":"string","maxLength":40},"locale":{"type":"string","maxLength":16},"time_zone":{"type":"string","maxLength":64,"description":"An IANA zone","e.g. Europe/London.":null}}}}}},"responses":{"200":{"description":"This install was already registered; its token and details were updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushDevice"}}}},"201":{"description":"The phone is registered and verified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushDevice"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"description":"The push service refused the token, or phone alerts are unavailable right now. The message says which and what to do.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/me/push-devices/{device_id}":{"parameters":[{"name":"device_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"patch":{"operationId":"updatePushDevice","summary":"Change this phone's name, language, time zone or quiet hours.","description":"Quiet hours are minutes after local midnight in the phone's `time_zone`. A window may cross midnight (22:00 to 07:00 is `quiet_start=1320`, `quiet_end=420`); equal start and end is an EMPTY window, never all day. During quiet hours an alert to this phone is skipped and recorded as skipped in the delivery log; every other destination still receives it.","tags":["notifications"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"device_name":{"type":"string","maxLength":120},"locale":{"type":"string","maxLength":16},"time_zone":{"type":"string","maxLength":64},"quiet_enabled":{"type":"boolean"},"quiet_start":{"type":"integer","minimum":0,"maximum":1439},"quiet_end":{"type":"integer","minimum":0,"maximum":1439}}}}}},"responses":{"200":{"description":"The updated phone.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushDevice"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"operationId":"deletePushDevice","summary":"Stop alerts on this phone.","description":"Removes the phone and its notification connection. The app calls this on sign-out.","tags":["notifications"],"responses":{"200":{"description":"Removed.","content":{"application/json":{"schema":{"type":"object","required":["deleted"],"properties":{"deleted":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/me/push-devices/{device_id}/test":{"parameters":[{"name":"device_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"testPushDevice","summary":"Send a real test alert to this phone now.","description":"Ignores quiet hours (the customer asked for it). A failure is returned as `sent=false` with its class, not as an error status; if the push service says the app is gone from the phone, the phone is removed (`removed=true`).","tags":["notifications"],"responses":{"200":{"description":"The outcome.","content":{"application/json":{"schema":{"type":"object","required":["sent","error_code","removed"],"properties":{"sent":{"type":"boolean"},"error_code":{"type":"string"},"removed":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/notification-connections":{"parameters":[{"name":"org_id","in":"query","required":false,"description":"The organization to act on. Omitted resolves to your own ONLY when you belong to exactly one organisation; a principal in more than one must name it, or the call is refused `422 org_id is required`. A reseller managing a client org must name it - defaulting silently would write the reseller's own destinations while the screen showed the client's.","schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listNotificationConnections","summary":"Connected destinations and the routing matrix.","description":"Every destination this organisation has connected - e-mail addresses, Slack channels, Telegram chats - with the full grid of which notification types go to each.\n\nThe grid is returned COMPLETE rather than as the stored deviations. Only the cells a human switched OFF are persisted (absence means enabled), so a client that had to infer \"everything not listed is on\" would be re-implementing that default - and two implementations of one decision is how a customer ends up on a ladder nobody chose.","tags":["notifications"],"responses":{"200":{"description":"The connections and the type registry.","content":{"application/json":{"schema":{"type":"object","properties":{"connections":{"type":"array","items":{"$ref":"#/components/schemas/NotificationConnection"}},"topics":{"type":"array","description":"The routing units. TOPICS, not notification types - the matrix used to address a type enum that no notification template declares, so no cell of it could ever have addressed a message whatever it was set to.","items":{"type":"object","required":["value","label"],"properties":{"value":{"type":"string"},"label":{"type":"string"}}}}}}}}}}},"post":{"operationId":"createNotificationConnection","summary":"Connect a destination.","description":"Adds a destination. Many of the same kind are supported and expected - two Telegram chats, three Slack channels, an accountant's e-mail that belongs to no platform user.\n\nA new connection is NOT usable until it has been verified: it must send a real test message first. A destination that has only been typed correctly has not been shown to work, and this whole surface exists because two channels sat configured and silent.","tags":["notifications"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kind","label","target"],"properties":{"kind":{"type":"string","enum":["email","slack","telegram","webhook"],"description":"A phone (`push`) is not connected here: the phone app registers itself through `POST /v1/me/push-devices`, which proves the token first. Text messages (`sms`) and WhatsApp are not connected here either: a person verifies their number and gives consent through `/v1/notification-phone`."},"label":{"type":"string","maxLength":120},"target":{"type":"string","maxLength":320,"description":"The NON-secret half - an address, a channel name, a chat id."},"credential":{"type":"string","maxLength":500,"writeOnly":true,"description":"The credential itself - a Slack incoming-webhook URL, or a Telegram bot token. Required for those two kinds and refused for the others: a webhook's signing secret is ours to mint (a customer-chosen one would be guessable), and an e-mail address has no credential, which is why it takes a confirmation click instead.\n\nIt is never persisted on the row and never returned. It goes straight to the secret vault and the row keeps only a pointer."},"personal":{"type":"boolean","default":false,"description":"true = this is MY destination and only my own matrix addresses it. The owning user is the authenticated principal, never a value in this body."}}}}}},"responses":{"201":{"description":"Connected, and awaiting verification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationConnection"}}}}}}},"/v1/notification-connections/{connection_id}/verify":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"description":"The organization to act on. Omitted resolves to your own ONLY when you belong to exactly one organisation; a principal in more than one must name it, or the call is refused `422 org_id is required`.","schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"verifyNotificationConnection","summary":"Send a real test message to a destination.","description":"Sends an actual message and records what happened. It does not check that the destination looks plausible; nothing may be routed to a connection until this has succeeded.","tags":["notifications"],"responses":{"200":{"description":"Whether it delivered, and why not if it did not.","content":{"application/json":{"schema":{"type":"object","properties":{"verified":{"type":"boolean"},"awaiting_confirmation":{"type":"boolean","description":"An e-mail destination has been sent its confirmation link and is waiting for the recipient to click it. Not verified, and not a failure."},"unknown":{"type":"boolean","description":"⛔⛔ We could not CHECK - which is not the same as *it failed*, and until W39-AM this response could not say the difference. Both were `verified: false`, so a credential-store blip reported every customer's Slack and webhook as broken.\n\nWhen this is true, `verified` retains its previous value and NOTHING may be concluded from the call. Show *\"we could not check just now\"*, never an error - the two sentences send the reader to two different systems and only one of them is theirs to fix."},"error":{"type":"string","description":"Safe to display - never contains a credential."}}}}}}}}},"/v1/notification-connections/{connection_id}/deliveries":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"description":"The organization to act on. Omitted resolves to your own ONLY when you belong to exactly one organisation; a principal in more than one must name it, or the call is refused `422 org_id is required`.","schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listNotificationConnectionDeliveries","summary":"A webhook destination's delivery log.","description":"Every delivery to this destination, newest first: each event sent and each Test press, with its status, how many attempts it has taken, the endpoint's last HTTP answer and when. A failed delivery is retried with backoff - after 1, 5, 25, 125 and 625 minutes, six attempts in all - and is then given up as `failed`. Rows are kept for 30 days.\n\nA row's `id` is the `X-Zinn-Delivery` header the endpoint received. Every retry of one delivery carries the SAME id (re-signed with a fresh `X-Zinn-Timestamp`), and every new delivery - including every Test press - has a new one, so a receiver can dedupe on it safely.","tags":["notifications"],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"A page of deliveries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationConnectionDeliveryPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/notification-connections/{connection_id}":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"description":"The organization to act on. Omitted resolves to your own ONLY when you belong to exactly one organisation; a principal in more than one must name it, or the call is refused `422 org_id is required`.","schema":{"type":"string","format":"uuid"}}],"delete":{"operationId":"deleteNotificationConnection","summary":"Disconnect a destination.","description":"Removes the destination, its routing cells, and its stored credential.\n\nThe credential is removed from the vault FIRST and the result is reported rather than assumed: if the row went first and the vault delete failed, a live Slack token or webhook secret would be orphaned under a path no row names - un-enumerable, which is worse than a leak you can list.","tags":["notifications"],"responses":{"200":{"description":"Disconnected.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"credential_removed":{"type":"boolean","description":"Whether the stored credential was actually removed. False means the vault could not be reached - the destination is gone but an operator must clean up. Reported rather than silently assumed."}}}}}}}}},"/v1/notification-connections/confirm":{"get":{"operationId":"describeNotificationConfirmation","summary":"What a confirmation link is asking.","description":"Public and unauthenticated: the person clicking is very often an accountant or a colleague with no account here, and a confirmation behind a login wall cannot be completed by the one person it is addressed to.\n\nGET only DESCRIBES. Mail clients and scanners fetch links before a human sees them, so a confirming GET would be auto-clicked by the recipient's own mail infrastructure and double opt-in would silently become single opt-in.\n\nAn unknown, expired or already-used token all answer `valid: false` identically - the endpoint must not become an oracle for which addresses an organisation has pending.","tags":["notifications"],"security":[],"parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Whether the link is live, and what it asks.","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"email":{"type":"string"},"organisation":{"type":"string"}}}}}}}},"post":{"operationId":"confirmNotificationRecipient","summary":"Confirm you want an organisation's notifications at this address.","description":"The double opt-in click. Until it happens nothing is routed to the address - a billing notification carries an amount, a legal address and a VAT identity, so a mistyped address is a disclosure and the person who mistyped it is the one who cannot notice.\n\nSingle-use and expiring.","tags":["notifications"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","maxLength":512}}}}}},"responses":{"200":{"description":"Confirmed; the address now receives.","content":{"application/json":{"schema":{"type":"object","properties":{"confirmed":{"type":"boolean"},"email":{"type":"string"}}}}}}}}},"/v1/notification-routes":{"parameters":[{"name":"org_id","in":"query","required":false,"description":"The organization to act on. Omitted resolves to your own ONLY when you belong to exactly one organisation; a principal in more than one must name it, or the call is refused `422 org_id is required`. A reseller managing a client org must name it - defaulting silently would write the reseller's own destinations while the screen showed the client's.","schema":{"type":"string","format":"uuid"}}],"put":{"operationId":"updateNotificationRoutes","summary":"Turn a notification topic on or off for one destination.","description":"Flips cells of the matrix. `enabled: true` DELETES the stored deviation, returning the cell to the default; `enabled: false` writes one. Keeping a true row would make \"on\" mean two different stored states and the grid would drift.","tags":["notifications"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["routes"],"properties":{"routes":{"type":"array","items":{"type":"object","required":["connection_id","topic","enabled"],"properties":{"connection_id":{"type":"string","format":"uuid"},"topic":{"type":"string","description":"A notification TOPIC (billing, sites, domains, ...) - the unit every template declares. It used to be a notification type, an enum no template declares, so no cell could address a message."},"enabled":{"type":"boolean"}}}}}}}}},"responses":{"200":{"description":"Applied.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}}}}},"/v1/notification-preferences":{"parameters":[{"name":"org_id","in":"query","required":false,"description":"The organization to act on. Omitted (or empty) means your own. A reseller managing a client org must name it - defaulting silently would write the reseller's own preferences while the screen showed the client's.","schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listNotificationPreferences","summary":"What you want to hear about, by topic.","description":"Every topic you receive mail on, with your current answer and whether it can be changed at all.\n\nA topic you may NOT silence is still returned, with `can_opt_out: false` and a `reason` naming the duty. Dropping it would be a screen that lies by omission: you would conclude we do not email about security, switch off everything visible, and be surprised by a suspension notice.\n\nA topic nobody receives anything on is omitted entirely - offering a switch for mail that does not exist invites you to turn it off and conclude the screen is broken.","tags":["notifications"],"responses":{"200":{"description":"One row per topic, in display order.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NotificationPreference"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"updateNotificationPreferences","summary":"Turn a topic's mail on or off.","description":"Sets your own answer, or the organization's default when `for_organization` is true.\n\nYour own answer outranks your organization's, in BOTH directions - so an admin silencing a topic for everyone does not lock out the one colleague who needs it.\n\n`user_id` is never read from the body. The row is written for the authenticated principal, because a member of an organization must not be able to silence a colleague's mail.\n\nTurning off a topic whose every message is one we are obliged to send answers **422** naming the topic and the duty - never a silent drop, which would leave you believing you had unsubscribed.","tags":["notifications"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["preferences"],"properties":{"preferences":{"type":"array","items":{"type":"object","required":["topic","enabled"],"properties":{"topic":{"type":"string","maxLength":16},"channel":{"type":"string","maxLength":16,"default":"email","description":"Email is the only channel implemented today."},"enabled":{"type":"boolean"}}}},"for_organization":{"type":"boolean","default":false,"description":"Write the ORGANIZATION's default instead of your own answer. A separate flag rather than an omitted `user_id`, because \"set this for everyone\" is a different intention and must be stated, not inferred.\n\nRequires `org.update` on the target organization, and is audit-logged. Setting your OWN preference requires nothing but membership - that is not a permission question - but deciding what every colleague receives is. Answers **403** without it."}}}}}},"responses":{"200":{"description":"The full preference set after the change, exactly as GET returns it.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NotificationPreference"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Either the organization is out of scope, or `for_organization` was set without `org.update` on it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A topic that cannot be silenced was turned off. The message names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/subscriptions":{"get":{"operationId":"listSubscriptions","summary":"List the organization's subscriptions.","description":"The subscriptions in scope — each pins the exact plan version it was sold and carries the **captured** price + entitlements (a purchase-time snapshot, never re-derived from the live catalog, docs/05 §1). Cursor-paginated, RLS-scoped; requires `billing.view`.","tags":["billing"],"parameters":[{"$ref":"#/components/parameters/ActiveOrg"},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"status","in":"query","required":false,"description":"Filter by subscription status.","schema":{"$ref":"#/components/schemas/SubscriptionStatus"}},{"name":"org_id","in":"query","required":false,"description":"Restrict to one organization in scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"A page of subscriptions.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/subscriptions/{subscriptionId}/plan":{"parameters":[{"name":"subscriptionId","in":"path","required":true,"description":"The subscription whose plan is being read or changed.","schema":{"$ref":"#/components/schemas/Uuid"}}],"get":{"operationId":"getSubscriptionPlanChoices","summary":"List the plans this subscription could move to, priced.","description":"The upgrade/downgrade ladder for a subscription the customer already holds — every purchasable plan on the same product line (and, for a subscription on a retired line, on the line that replaced it — `wordpress`/`fleet_enterprise` → `mainstream`), priced in their own currency and term, each carrying a prorated quote and each refusal already applied.\n\n⚖️ **It exists because a customer asked for it and could not find it.** He bought a 50-site plan and wanted more slots; the only thing he could find was the buy flow, which would have sold him a **second** subscription rather than a bigger one. `getSitePlanChoices` performs the identical read — but it is addressed by a **site**, and a customer who has bought slots and not filled any of them has none, so that endpoint was not merely hard to find but unaddressable.\n\n⭐ On a subscription that entitles at least one site whose platform a plan change can act on, this is `getSitePlanChoices` for that site, verbatim — same service, same refusals, same schema — so the two screens can never disagree about what is for sale. Where it entitles none, the package-type refusals (`no_package_type`, `unknown_package_type`, `platform_mismatch`, `different_target`) cannot arise, because every one of them is a statement about a site's placement.\n\n⛔ `blocked_reason` and `reason` are **stable codes, never prose** — the localised sentence is the client's, in 58 languages. Every money figure is an integer in minor units, and `total_minor` and `credit_minor` are two fields rather than one signed number, because a screen that renders a negative total as a charge is a screen that took money for a refund.\n\n`coverage` names the sites drawing on the plan and the slot arithmetic around them, so an upgrade can say what it will move before the customer commits. Its `slots_total` and `slots_free` are **nullable and null is not zero**: a plan stating no allowance is a different fact from one entitling nothing, and `slots_unlimited` is the third state.\n\n`404` for a subscription in another tenant as well as for one that does not exist — a `403` would confirm that an id belongs to somebody. Requires `billing.view`: this is a price list for the customer's own subscription, and support needs to see it to answer *\"what would an upgrade cost\"*.","tags":["billing"],"responses":{"200":{"description":"The current plan and every plan this subscription could move to.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePlanChoices"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"post":{"operationId":"changeSubscriptionPlan","summary":"Move a subscription onto a bigger or smaller plan.","description":"Charges the prorated difference for the remainder of the current period, moves every site the subscription entitles, and supersedes the subscription onto the new plan version — keeping the existing period window, so the customer's renewal date does not move and they are not handed a free extra period.\n\n⛔ **A plan change SUPERSEDES rather than mutates**, because a subscription pins the exact version it was sold so that a later catalogue edit cannot rewrite what a live subscriber pays. `subscription_id` in the response is therefore a **new** id and a client holding the old one must replace it.\n\n⭐⭐ **`slots_before` and `slots_after` are read back from the subscription rows**, not derived from the plan that was asked for. A plan change that answers `200` and silently does not take effect is the worst outcome on this path, and a status code cannot tell that apart from one that worked.\n\n**Mid-period money.** A larger plan is charged the difference **now** — the customer asked for more room today, and applying it at the next renewal is the buy-flow dead end in another costume. A smaller plan returns the unused difference as **account credit**, not a card refund: it is instant, it cannot be unavailable, it is idempotent, and it is spendable on their next order. ⛔ Account credit carries no VAT credit note; a proration credit spans the current period's invoice rather than reversing it.\n\n⛔ **`expected_total_minor` is a money guard, not a convenience.** It is the figure the customer was actually shown, and the change is refused `422` when the freshly-computed quote differs. Every other refusal is `422` as well, with nothing charged and nothing changed: a plan on another product line, the plan they are already on, a plan that has been re-priced since the page loaded, account usage above what a smaller plan allows, a card decline.\n\n⛔ **The downgrade guard is account-wide and there is no override.** The same `check_downgrade` the site endpoint and the staff tariff endpoint call: sites, mailboxes, mailbox storage and disk across the org's subtree. Staff have an audited override because they sometimes genuinely need to move an over-limit account; a customer overriding their own quota check is not an override, it is no check.\n\n**Repeating an identical request is the recovery and it is safe.** Every step is idempotent on a key anchored to the subscription being left, so an attempt that died part-way is finished rather than duplicated: one order, one charge, one credit, one supersede.\n\n`404` for a subscription in another tenant as well as for one that does not exist. `503` when the driver behind an entitled site cannot move a package between types at all — our gap, not theirs. Requires `billing.payment.manage` — it charges a card, so the key that gates paying is the key that gates committing to a payment.","tags":["billing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeSitePlanRequest"}}}},"responses":{"200":{"description":"What the plan change actually did, and what it cost.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionPlanChangeResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/subscriptions/{subscriptionId}/auto-renew":{"parameters":[{"name":"subscriptionId","in":"path","required":true,"description":"The subscription whose renewal is being changed.","schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"setSubscriptionAutoRenew","summary":"Turn a subscription's renewal on or off.","description":"**The customer's renewal switch, and the only one there is.** With `auto_renew` **false** the subscription runs to the end of the period already paid for and is then `expired` by the rebill sweep — nothing is minted, no card is charged, and the entitlements lapse at the same instant the period does. It is **not** an immediate cancellation: every day already bought is kept.\n\nWith it **true** the subscription is selected by the nightly sweep at `current_period_end`, an order is minted and the payment method is charged. The switch is reversible right up to that moment, which is the customer's way back after turning it off.\n\nFor a compute server the machine follows on its own: the provider's own renewal flag is pinned to \"hold\" for the life of every machine and is never exposed, so an unrenewed contract keeps serving for 24 hours, is powered down, and is deleted six days after that. Zinn® issues each vendor renewal explicitly, after the money is captured. Find a server's subscription with `subscription_id` on `GET /v1/compute/servers/{serverId}/renewal`.\n\nThe response is the subscription **as the database now holds it**, not an echo of the request. Requires `billing.payment.manage` — the authority to decide what this account is charged. It deliberately does **not** require `sites.view`: a subscription is not a site, and this endpoint governs every plan, including ones that own no site.\n\n`404` for a subscription in another tenant as well as for one that does not exist — a `403` would confirm that an id belongs to somebody. `422` when the subscription has already ended (`canceled`/`expired`): writing `true` to a row the sweep can never select again would tell the customer they were covered when nothing will charge or serve them.","tags":["billing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionAutoRenewRequest"}}}},"responses":{"200":{"description":"The subscription, with the switch as it now stands.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/subscriptions/renewal-options":{"get":{"operationId":"listSubscriptionRenewalOptions","summary":"Every renewal card's crypto auto-renew state and one-period prepay quote, in one read.","description":"For a page of the subscriptions the caller can manage billing for, what `GET /v1/subscriptions/{subscriptionId}/crypto-auto-renew` and `GET /v1/subscriptions/{subscriptionId}/prepay-quote?periods=1` would each answer — so the billing page makes one request instead of two per subscription. The crypto part is read once for the whole page. A subscription that cannot be prepaid carries `prepay_quote: null` with the refusal `code` and sentence the single quote's `422` would have carried. **Takes no money and creates no row.**\n\nCursor-paginated, RLS-scoped; requires `billing.payment.manage` (the key both single endpoints require: a quote names a price we will honour).","tags":["billing"],"parameters":[{"$ref":"#/components/parameters/ActiveOrg"},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"org_id","in":"query","required":false,"description":"Restrict to one organization in scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"A page of renewal options.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRenewalOptionsPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/subscriptions/{subscriptionId}/prepay-quote":{"parameters":[{"name":"subscriptionId","in":"path","required":true,"description":"The subscription being quoted for.","schema":{"$ref":"#/components/schemas/Uuid"}},{"name":"periods","in":"query","required":true,"description":"How many whole billing periods to price.","schema":{"type":"integer","minimum":1}}],"get":{"operationId":"getSubscriptionPrepayQuote","summary":"Price paying for several billing periods at once.","description":"What N more whole billing periods would cost, and the date the subscription would then run to. **Takes no money and creates no row**, so a slider can be moved without minting an order per keystroke.\n\nThe price is the **captured** per-period price multiplied — never re-derived from the catalogue. A live subscriber keeps the price they were sold (docs/05 §1), so a customer on a legacy or discounted rate is not silently re-priced for choosing to pay early.\n\n⛔ It makes **no claim about the customer's balance**. Funds are read once, at charge time. A quote that asserted \"you have enough\" would be quoting a number that can change before the customer presses the button — including by a downgrade crediting their account.\n\nRequires `billing.payment.manage`. `404` for a subscription in another tenant as well as for one that does not exist. `422` when the subscription cannot be prepaid — it has ended, it is comped, it is free, or it is on the PayPal rail — with a `code` in the error details naming which.","tags":["billing"],"responses":{"200":{"description":"The quote.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrepayQuote"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/subscriptions/{subscriptionId}/prepay":{"parameters":[{"name":"subscriptionId","in":"path","required":true,"description":"The subscription to pay ahead on.","schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"startSubscriptionPrepay","summary":"Create the order to pay for several billing periods at once.","description":"Mints an **unpaid** order for N whole billing periods. ⛔⛔ **No money is taken here.** The client then settles that order through `POST /v1/orders/{orderId}/pay`, which already knows how to pay from account balance, from a gateway, or from both.\n\nThat separation is the point rather than an implementation detail: it is what lets a customer with **no chargeable mandate** use this at all — somebody paying in crypto, or in a market whose regulator forbids an off-session charge. They top up once and pay six months from their balance, with no card anywhere in the flow.\n\nReplaying the same request returns the **same** order rather than a second one, so a double-clicked button cannot bill twice. Asking for a *different* number of periods supersedes the earlier unpaid prepay order and mints a fresh one — a customer changing their mind is not a collision. An unpaid order against this subscription that is **not** a prepayment (a plan change, say) is refused with `ORDER_IN_FLIGHT` instead, and is never cancelled on the customer's behalf.\n\nRequires `billing.payment.manage`. `422` carries a `code` in its details: `TOO_FEW` / `TOO_MANY` (outside the allowed range), `NOT_PREPAYABLE` (ended, comped or free), `RAIL_NOT_SUPPORTED` (billed by PayPal on its own schedule), `ORDER_IN_FLIGHT`, or `ARREARS_OUTSTANDING` — the subscription owes missed periods (`Subscription.periods_owed` > 0) and fewer periods than that were asked for: a payment that leaves the service paused is not sold here (W43-107; s1014 R40). Asking for `periods >= periods_owed` is the **pay everything owed** order: it extends from the date the subscription is paid through, so it covers every missed period first, brings the service back, and cancels the unpaid renewal order(s) it paid for so the same month is never chased twice.","tags":["billing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrepayRequest"}}}},"responses":{"201":{"description":"The unpaid order to settle.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrepayOrder"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/subscriptions/{subscriptionId}/billing-rail":{"parameters":[{"name":"subscriptionId","in":"path","required":true,"description":"The subscription whose recurring rail is being changed.","schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"setSubscriptionBillingRail","summary":"Choose which clock charges this subscription.","description":"Move a subscription between the **engine** rail (we invoice and charge on the renewal date) and the **PayPal** rail (PayPal charges on its own schedule under an agreement the customer approved). ADR 0029 records the boundary: PayPal owns only *when* the money is taken — the engine still owns what is owed, tax, entitlements, dunning and suspension.\n\n⛔⛔ **Switching to PayPal returns an `approval_url` and grants nothing.** Until the buyer approves in PayPal's own interface and PayPal sends us a **signed** `BILLING.SUBSCRIPTION.ACTIVATED` webhook, the agreement cannot charge and the subscription's clock has not started. `active` is `false` for exactly that reason. The browser's return from the approval URL is an attacker-supplied claim and is never treated as approval.\n\nSwitching **away** cancels the agreement at PayPal first and unbinds second. The reverse order would hand the subscription back to the engine's renewal sweep while PayPal was still entitled to charge it — a double charge for the window between the two calls. A 404 from PayPal on that cancel is success when a re-read shows the agreement cannot charge (never approved, cancelled, expired or gone); otherwise the subscription stays on PayPal and the answer is `422 PAYPAL_REFUSED`. A PayPal timeout or 5xx is `503` with `PAYPAL_REFUSED` (billing unchanged, safe to retry). No PayPal answer is ever a `500`.\n\nRequires `billing.payment.manage`. `422` carries a `code`: `ALREADY_ON_RAIL`, `NO_CATALOGUE_PRICE`, `PRICE_WOULD_CHANGE` (the subscription is on a price that differs from the published one, so switching would change what the customer pays — refused rather than done quietly), `NOT_SWITCHABLE`, `PAYPAL_REFUSED`, or `RENEWAL_UNPAID` (pay first: a renewal of this subscription is unpaid, so the switch onto PayPal is refused before PayPal is called; pay it on the billing page, then switch).","tags":["billing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingRailRequest"}}}},"responses":{"200":{"description":"The rail as it now stands, with an approval URL when one is needed.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingRailChange"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/subscriptions/{subscriptionId}/crypto-auto-renew":{"parameters":[{"name":"subscriptionId","in":"path","required":true,"description":"The subscription whose crypto auto-renew choice is read or changed.","schema":{"$ref":"#/components/schemas/Uuid"}}],"get":{"operationId":"getSubscriptionCryptoAutoRenew","summary":"Read this subscription's crypto auto-renew choice.","description":"Whether the subscription renews by a crypto payment link that NOWPayments e-mails before each renewal (`docs/1032`). `available` is `false` while staff have the feature switched off or the processor login is not configured — the dashboard hides the choice then. Requires `billing.payment.manage`.","tags":["billing"],"responses":{"200":{"description":"The choice as it stands.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CryptoAutoRenewState"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setSubscriptionCryptoAutoRenew","summary":"Turn crypto auto-renew on or off for this subscription.","description":"**On**: the subscription keeps renewing on the engine's own clock (the renewal invoice, its tax and the reminder ladder are unchanged), and at the first renewal that needs paying NOWPayments starts e-mailing a payment link for the renewal amount **including tax**. What the customer pays is credited to the account and settles the renewal invoice. ⛔ A subscription on crypto auto-renew is **never** charged on a stored card or PayPal — paying the link is the payment. Turning it on also turns renewal on.\n\n**Off**: NOWPayments is told to stop first; the next renewal is invoiced as usual. Turning renewal off, moving to PayPal billing or cancelling also turns this off.\n\n`email` defaults to the billing e-mail. Requires `billing.payment.manage`. `422` carries a `code`: `CRYPTO_AUTO_RENEW_UNAVAILABLE`, `CRYPTO_AUTO_RENEW_OTHER_RAIL`, `CRYPTO_AUTO_RENEW_NOT_LIVE`, `CRYPTO_AUTO_RENEW_NOT_BILLABLE` or `CRYPTO_AUTO_RENEW_EMAIL`.","tags":["billing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CryptoAutoRenewRequest"}}}},"responses":{"200":{"description":"The choice as it now stands.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CryptoAutoRenewState"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/invoices":{"get":{"operationId":"listInvoices","summary":"List the organization's billing documents.","description":"The organization's billing history — every **invoice and credit note** issued to it, newest first, with its lines, its payment summaries and the captured amounts. Cursor-paginated, filterable by `status`; RLS-scoped; requires `billing.view`.\n\n**These are the real legal documents (docs/34 §1).** Each is an immutable snapshot with a gapless, per-entity `ZD-INV-YYYY-NNNNNN` number, a captured tax treatment and its own frozen FX rates. `document_type` separates an invoice from a credit note; `credits_invoice_id` says which invoice a credit note un-bills.\n\n⚠️ **The document is issued by a sweep, a couple of minutes after payment, not synchronously at checkout** (docs/34 §4.1). Render a pending state for a just-placed order rather than assuming the document is there the moment checkout returns. `pdf_url` stays `null` until PDF rendering lands (#708).","tags":["billing"],"parameters":[{"$ref":"#/components/parameters/ActiveOrg"},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"status","in":"query","required":false,"description":"Filter by billing-document status.","schema":{"$ref":"#/components/schemas/InvoiceStatus"}},{"name":"org_id","in":"query","required":false,"description":"Restrict to one organization in scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"A page of billing documents.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoicePage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/invoices/{invoiceId}":{"parameters":[{"$ref":"#/components/parameters/InvoiceId"}],"get":{"operationId":"getInvoice","summary":"Get one billing document.","description":"One billing document — an invoice or a credit note — with its own lines and the payment summaries of the order it bills. RBAC + RLS scoped; an out-of-scope or unknown id is a `404`.","tags":["billing"],"responses":{"200":{"description":"The billing document.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/invoices/{invoiceId}/pdf":{"parameters":[{"$ref":"#/components/parameters/InvoiceId"}],"get":{"operationId":"getInvoiceDocument","summary":"Download the invoice or credit note as a PDF, in a chosen language.","description":"The rendered legal document (#708, `docs/34` §4.2) — server-side HTML→PDF, in all 58 locales including RTL, with embedded fonts covering Latin, Greek, Cyrillic, CJK, Arabic and Hebrew.\n\nRendered from the invoice's **immutable snapshot**, never from live data: a customer who has since moved still sees the address that was on the document, because a re-render that updated it would be a different legal document under the same number. That is also what makes the render deterministic and the cache disposable.\n\n⭐ **Labels translate; numbers, tax wording and the document identity do not.** The invoice number, the amounts and the dates keep their canonical form, and the **English document is the authoritative original** — a translated rendering is a copy of the same numbered document for the customer's convenience and says so in its footer.\n\nAnswers a short-lived signed URL rather than the bytes, so a multi-megabyte document never transits the engine twice. ⛔ When no document bucket is configured in an environment the response is the **PDF itself** (`application/pdf`) rather than a refusal: the cache is an optimisation, and a customer must not be unable to download their own invoice because a bucket is missing.","tags":["billing"],"parameters":[{"name":"locale","in":"query","schema":{"type":"string"},"description":"Language to render in. Defaults to the account's own. A language this platform does not ship is a `422` rather than a silent fallback — and it is validated because the value reaches a storage key."}],"responses":{"200":{"description":"A short-lived signed URL to the cached document — or, where no document bucket is configured, the rendered PDF itself.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceDocumentLink"}},"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"A language this platform does not ship.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The renderer is unavailable — WeasyPrint needs pango and harfbuzz at runtime, so this means the image is missing a system library rather than the request being bad.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/domains/routes":{"get":{"operationId":"listRegistrationRoutes","summary":"The registrar routes this organisation can buy a domain through.","description":"Cloudflare Registrar is offered as **an additional, deliberately-chosen way to register a domain**, beside the organisation's existing registrar — not as a cheaper source the platform switches to silently.\n\nThe reason the choice is the customer's is `locks_nameservers`. A Cloudflare registration cannot use external nameservers: the API exposes no way to set them, so the domain's DNS stays with Cloudflare for as long as we hold it. That is a constraint somebody has to accept knowingly, not one to discover the first time they try to point the domain elsewhere.\n\nEvery flag is derived from the registrar driver's advertised capabilities, so a driver that gains or loses an endpoint moves this copy with it. Routes the organisation cannot use are returned with `available: false` and a reason rather than filtered out — a one-option list is indistinguishable from a list whose second option failed to load.","tags":["domains"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"Whose routes to report. Required when the caller can act for more than one organisation: availability depends on that organisation's registrar connections, so guessing would grey out an option a customer has connected.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The routes on offer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistrationRoutes"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/domains/search":{"post":{"operationId":"searchDomains","summary":"Search domain availability.","description":"Checks availability + price for candidate names and returns a signed **availability token** for each name that is available in a TLD we offer. The token is what a `domain_register` cart line carries; checkout re-verifies it (a stale/taken one → `409`, no charge) — so registration/transfer happen through the cart/checkout flow, and this is the \"find one to buy\" half. A dotted `query` is checked as one exact FQDN; a bare name is checked across the requested `tlds` (or every offered TLD when none are given). Rate-limited. Requires `sites.view`. A `query` that cannot be a domain name (spaces, a label over 63 characters, a leading/trailing hyphen, an empty label) is `422` with refusal `refusal.domains.domainName`, before any registrar is asked; an internationalised name is judged by its IDNA A-label.","tags":["domains"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainSearchRequest"}}}},"responses":{"200":{"description":"The candidate results.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainSearchResults"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/domain-watches":{"get":{"operationId":"listDomainWatches","summary":"The domains this customer is watching — ours, theirs and third parties'.","description":"The domain monitor (⚖️ owner 2026-08-30, `docs/296` §5). Every domain registered with us and every domain attached to hosting with us is on this list automatically; the customer may add any other name they like, mute one, or remove it.\n\n⛔ **A removed watch is soft-removed and never returned here.** Auto-add runs on every provision, so a hard delete would let tomorrow's provision resurrect a domain the customer deliberately took off their list — for ever, with no way for them to make it stop.\n\n`last_checked_at` is when the registry last answered, and it is rendered beside every value on the row for a reason: these facts are a snapshot of the outside world and go stale silently (§2.36). A tick with no date on it is indistinguishable from a live one.\n\n`expires_at` and `days_until_expiry` are `null` when the registry did not say — which is a different fact from \"it expires in a decade\" and must not render as one.","tags":["domains"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Narrow to one organisation in the caller's subtree — what the dashboard's org switcher sends. ⛔ **Narrow only:** intersected with what the caller may already read, so it can never widen scope."},{"name":"source","in":"query","required":false,"schema":{"type":"string","enum":["registered","hosting","manual"]},"description":"Only watches that arrived this way."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"The watchlist page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainWatchPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createDomainWatch","summary":"Watch a domain — any domain, including one registered elsewhere.","description":"Adds `fqdn` to the caller's watchlist with `source: manual`.\n\n⭐ Idempotent by `(org, fqdn)`: watching a domain that is already watched returns the existing row rather than erroring, because the customer's intent — *\"I want this watched\"* — is already satisfied and a 409 would be a worse answer to it.\n\n⭐ Re-adding a domain the customer previously **removed** un-removes it. That is the one thing that clears `removed_at`, and it must be a deliberate act by the customer rather than a side effect of a provision.\n\n⛔ **Which org (D51530).** The org named by body `org_id`, else by the `X-Zinn-Org` header, else the caller's one org. A named org outside the caller's scope is refused (`404` for body `org_id`, `403` for the header); a caller in several orgs who names none gets `422` rather than a guess.","tags":["domains"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainWatchCreate"}}}},"responses":{"201":{"description":"The watch.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainWatch"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/domain-watches/{watchId}":{"parameters":[{"name":"watchId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"delete":{"operationId":"deleteDomainWatch","summary":"Stop watching a domain.","description":"⛔ **A soft removal.** The row is kept with `removed_at` set, which is what stops the next provision or registration silently putting the domain back. Re-add it with `POST /v1/domain-watches` at any time.","tags":["domains"],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/domain-watches/{watchId}/mute":{"parameters":[{"name":"watchId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"muteDomainWatch","summary":"Silence a watched domain's alerts without removing it.","description":"⚖️ Owner 2026-08-30: *\"can be removed at anytime or silenced at least.\"*\n\n⛔ A muted watch is **still checked** and its history still recorded — only its notifications are suppressed. Skipping the read would leave a hole, so un-muting would produce a burst of \"changes\" that are simply everything that happened while nobody was listening.\n\nSend `until: null` to un-mute.","tags":["domains"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainWatchMute"}}}},"responses":{"200":{"description":"The updated watch.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainWatch"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/domains":{"get":{"operationId":"listDomains","summary":"List the caller's domains.","description":"The registered/connected domains in scope. Cursor-paginated, RLS-scoped. Requires `sites.view`.","tags":["domains"],"parameters":[{"$ref":"#/components/parameters/ActiveOrg"},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"status","in":"query","required":false,"description":"Filter by domain lifecycle status.","schema":{"$ref":"#/components/schemas/DomainStatus"}},{"name":"org_id","in":"query","required":false,"description":"Restrict to one organization in scope.","schema":{"$ref":"#/components/schemas/Uuid"}},{"name":"tld","in":"query","required":false,"description":"Filter by TLD (e.g. `com`).","schema":{"type":"string","maxLength":63}},{"name":"site_id","in":"query","required":false,"description":"Restrict to the domain backing one site — the link a site's DNS screen follows to reach the zone it should edit. Scoped by the same RLS filter as everything else here, so a site id outside the caller's scope simply matches nothing (an empty page, never a `403`, which would confirm the site exists).","schema":{"$ref":"#/components/schemas/Uuid"}},{"name":"q","in":"query","required":false,"description":"Search: domains whose name contains this text (case-insensitive). Server-side so an account with thousands of domains finds one without paging the whole list.","schema":{"type":"string","maxLength":253}}],"responses":{"200":{"description":"A page of domains.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/domains/connect":{"post":{"operationId":"connectDomain","summary":"Host DNS for a domain the customer already owns.","description":"Creates the domain's zone at our DNS provider, branded with our vanity nameservers in the same operation, and returns the delegation to set at the customer's **own** registrar. This is the BYO path — we become the authoritative DNS, **not** the registrar — so it needs no registrar credential and is how \"premium DNS included on every plan\" is delivered.\n\nThe domain must be a zone apex (a subdomain is a `422`) and must not already exist on the platform (a `409` — worded so it never confirms another tenant holds it). Requires `domains.dns.manage`, the same authority that governs the records this makes editable.\n\n⛔ There is deliberately **no `product_line` field**: it is derived server-side from the org's subscriptions, because it decides whether shared fleet A/AAAA records are hidden from this customer. Accepting it would let a Footprint-Free customer connect a domain as `mainstream` and read the fleet IPs.","tags":["domains"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainConnectRequest"}}}},"responses":{"201":{"description":"The connected domain, with the delegation to set at the registrar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectedDomain"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/domains/{domainId}":{"parameters":[{"$ref":"#/components/parameters/DomainId"}],"get":{"operationId":"getDomain","summary":"Get a domain.","description":"Returns one domain the caller can view. RBAC + RLS scoped.","tags":["domains"],"responses":{"200":{"description":"The domain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Domain"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/domains/check":{"post":{"operationId":"checkDomain","summary":"Authority metrics for any domain, owned or not.","description":"Majestic Trust Flow, Citation Flow, referring domains and topical trust for a domain you are considering — it does not have to be one of yours. Gated on `sites.view` plus **two** entitlements, both asserted **before** the provider is called: every check spends a billed index-item unit against Zinn®'s shared subscription, so an organisation that cannot see the answer never costs one.\n\n⛔ The two keys answer different questions and neither implies the other. `domain_checker` says the plan includes **this product** — a checker for a domain you do not own. `majestic_metrics` says the plan includes the **authority data**, and it also gates the SEO tab on domains you already own. A plan may sell figures on your own domains without selling a pre-purchase checker, so one key could not express both.\n\n⭐ A cached reading inside its TTL is returned **without spending anything** — re-checking a domain from an hour ago is the commonest thing an operator does while comparing a shortlist. Pass `force` when you genuinely want a fresh number.\n\n⛔ A malformed hostname is refused **locally**, with a 422. A pasted URL is normalised rather than rejected (that is what is actually in the clipboard), but an email address or a sentence never reaches the provider — every one that did would be a billed unit answering a question nobody asked.\n\n⛔ `null` and `0` mean opposite things in the response: `null` is *the provider did not tell us*, `0` is *the provider said zero*. A brand-new domain genuinely has Trust Flow 0 and so does one nobody has ever crawled, and on a PBN that difference decides a purchase.\n\n**Metered per day.** Each check that reaches the provider spends one of the account's daily allowance, and the response carries the meter as it stands afterwards, plus `spent_lookup` saying whether this particular answer cost anything. A cached reading is free. Nothing is charged when the request fails — a provider outage, an unconfigured provider or a malformed domain all leave the allowance untouched.\n\n`429` means the daily allowance is used up: buy more with `POST /v1/seo/quota/top-up`, or wait for the reset at midnight UTC. That is distinct from `403`, which means this account may not use the checker at all — the plan does not include it, or the account is suspended or unpaid.","tags":["domains"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainCheckRequest"}}}},"responses":{"200":{"description":"The domain's metrics, or an honest \"not in the index\", plus the meter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainCheckResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"The hostname is one of our own free preview addresses (the same predicate the sweeps skip on, `seo_sweep.is_platform_subdomain`), so nothing was checked and nothing was spent. `error.refusal.key` = `refusal.seoMetrics.previewAddressNotMeasured`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"description":"No provider configured, its allowance is used up, or it is unreachable."}}}},"/v1/domains/checked":{"get":{"operationId":"listCheckedDomains","summary":"The domains this organisation has checked.","description":"Newest first, one row per domain, with the figures and the date attached. ⭐ This is V1's `DomainList` without a list model: every check stores a snapshot, so the domains you have looked at already are the collection. A second table would be a second place a domain can be remembered, drifting from the first the moment anyone adds a field.\n\n⛔ Gated on the same two entitlements as the check itself (`domain_checker` + `majestic_metrics`). The stored list is still the paid product, and gating only the path that spends money would leave a downgraded organisation browsing its candidate list indefinitely.","tags":["domains"],"responses":{"200":{"description":"The checked domains.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckedDomainPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/domains/{domainId}/seo-metrics":{"parameters":[{"$ref":"#/components/parameters/DomainId"}],"get":{"operationId":"getDomainSeoMetrics","summary":"Get a domain's SEO authority metrics.","description":"The **cached** authority reading for this domain — Trust Flow, Citation Flow, referring domains and backlinks. Included on every Footprint-Free plan.\n\nThis never calls the upstream provider, so it is free to render and poll. Use the refresh endpoint to fetch a new reading; each refresh consumes provider allowance.\n\n`state` distinguishes three cases that must not be conflated: `measured` (numbers, which may legitimately be zero), `not_in_index` (the provider answered and has never seen this domain), and `never_fetched` (nothing has been requested yet). Individual metrics are nullable — `null` means the provider did not supply that figure, `0` means it measured zero.","tags":["domains"],"responses":{"200":{"description":"The cached metrics, with their age.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainSeoMetrics"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/domains/{domainId}/seo-metrics/refresh":{"parameters":[{"$ref":"#/components/parameters/DomainId"}],"post":{"operationId":"refreshDomainSeoMetrics","summary":"Fetch a fresh SEO authority reading for a domain.","description":"Calls the upstream provider and stores a new snapshot, then returns it in the same shape as the GET. **Consumes provider allowance on every call**, so it is driven by an explicit user action or a scheduled sweep — never by rendering a page.\n\nReturns 503 when the provider is unreachable, unconfigured, or the allowance is exhausted; in every one of those cases the previously stored reading is left untouched and still served by the GET.","tags":["domains"],"responses":{"200":{"description":"The freshly fetched metrics.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainSeoMetrics"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/domains/{domainId}/seo-metrics/history":{"parameters":[{"$ref":"#/components/parameters/DomainId"}],"get":{"operationId":"getDomainSeoMetricsHistory","summary":"A domain's authority readings over time.","description":"Every stored reading for this domain, **oldest first** — the trend behind the current number. Free to call; it reads stored rows and never contacts the provider.\n\nReadings where the provider had never seen the domain are included with `null` metrics rather than dropped, because the gap is real: hiding it would draw a smooth trend through a month in which there was genuinely no data.","tags":["domains"],"responses":{"200":{"description":"The stored series, oldest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoMetricsHistory"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/sites/{siteId}/seo-metrics":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteSeoMetrics","summary":"A hosted site's SEO authority metrics.","description":"The cached authority reading for this site's primary domain, in the same shape as the domain endpoint — it is the same underlying reading, reached from the site.\n\nKept fresh by a monthly platform sweep rather than by a per-site refresh button: refreshing every site on demand across a large estate is an unbounded cost. To get today's figure for one specific name, use the domain research tool, where the spend is metered against your own allowance.","tags":["hosting"],"responses":{"200":{"description":"The cached metrics, with their age.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainSeoMetrics"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/sites/{siteId}/seo-metrics/history":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteSeoMetricsHistory","summary":"A hosted site's authority readings over time.","description":"Every stored reading for this site's primary domain, oldest first. Free to call.","tags":["hosting"],"responses":{"200":{"description":"The stored series, oldest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoMetricsHistory"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/sites/{siteId}/seo-metrics/check":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"checkSiteSeoMetrics","summary":"Run an on-demand authority check for a hosted site.","description":"Fetch this site's authority metrics now, against the customer's own metered daily allowance, and store the reading so it joins the site's history.\n\n⭐ **A fresh stored reading is returned WITHOUT spending anything.** If the site was measured within the caching window the response comes back with `spent_lookup: false` and neither the daily allowance nor the provider is touched — which is what lets the Domains screen and the site panel share one purchase rather than buying the answer twice.\n\n⛔ There is no `force`. The fleet sweep owns a hosted site's cadence; a flag that spent a unit however recently we measured would be a button whose whole purpose is to overpay. A customer who genuinely wants to re-ask uses `POST /v1/domains/check`.\n\nRequires the `majestic_metrics` entitlement, on the site's own plan or the org's. An account that is suspended or has no active subscription is refused before anything is spent (`403`), and its existing readings stay on screen.","tags":["hosting"],"responses":{"200":{"description":"The reading, plus the allowance as it stands after this call. `spent_lookup` says whether this request cost anything.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainCheckResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The site is still on its free preview address (`Site.preview_only`), so nothing was checked and nothing was spent — not the daily allowance, not our provider balance and not the customer's own SEO key. `error.refusal.key` = `refusal.seoMetrics.previewAddressNotMeasured`. The site is measured once its own domain is attached (owner 2026-10-29, s1014 row 111).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Today's allowance is used up. It resets at midnight UTC, or buy a pack.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/seo-settings":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteSeoSettings","summary":"How often this site's SEO metrics are checked, and what is shown.","description":"The schedule this site is checked on, which providers are asked, which metrics are rendered, and — importantly — **who is paying** for the checks.\n\n`funding` is the field to read before showing anything else. `own_key` means the checks run on a key you connected, against your own quota, and cost nothing here. `platform` means they run on Zinn®'s own accounts under your plan or add-on. `none` means no check can currently run, and `reason` says what to do about it.\n\nA site that has never been configured answers with the account defaults rather than 404 — there is nothing to create before this can be read.","tags":["hosting"],"responses":{"200":{"description":"The current settings and funding state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteSeoSettings"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"operationId":"updateSiteSeoSettings","summary":"Choose the schedule, providers and visible metrics for this site.","description":"Sets how often this site is checked, which of your connected providers to ask, and which metrics to display.\n\nChecks may not be scheduled more often than every 12 hours. Hiding a metric changes only what is rendered — the reading is still taken and its history is kept, so turning it back on shows the full series rather than starting from today.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteSeoSettingsUpdate"}}}},"responses":{"200":{"description":"The saved settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteSeoSettings"}}}},"422":{"description":"An unknown cadence, a provider name that is not offered, or a metric key that no connected provider supplies. Nothing is saved — a rejected cadence must never be silently replaced by a default, because the cadence decides what gets spent."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/seo/providers":{"get":{"operationId":"listSeoProviders","summary":"Which SEO data providers this account can use, and on whose key.","description":"Every provider you can connect your own key for, whether you have connected one, and whether Zinn®'s own data is available to you as an alternative.\n\nConnecting your own key is free — the checks run against your subscription with that provider, on whatever schedule you choose. Where Zinn® holds an account of its own, the `platform_available` flag says whether your plan or add-on lets you draw on it.\n\n`connected` is measured, not merely recorded: a provider is listed as connected only when a working client can be built from the stored credential, so a key that has been revoked at the provider stops being reported as connected.","tags":["seo"],"responses":{"200":{"description":"The providers and their state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoProviderList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/index-monitoring":{"get":{"operationId":"getIndexMonitoring","summary":"What this organisation monitors for search indexing, and what it may add.","description":"Both paid indexing allowances, and every target being monitored, in one call.\n\nThere are **three** indexing positions and only two of them have a row here. A site hosted with us has its whole-site check included free on every plan and appears in no list — that is what makes it free rather than discounted, and it is why `sections.used` can be `0` on an account that is checking fifty sites. A `section` target is a page or path prefix within a site, on top of that free check. An `external_site` target is a whole website hosted somewhere else, billed monthly per site.\n\n⛔ Each allowance is returned with its **denominator** as well as its remainder. A bare \"3 remaining\" reads identically on an account with an allowance of 3 and nothing used, and on one with an allowance of 100 — and a client that renders only the remainder cannot tell a customer whether buying more would help.\n\n⛔ `indexed` on a target is **three-valued**. `false` means the provider answered and does not list the page; `null` means no reading exists yet, or the row is beyond the current allowance and the sweep is not checking it. A client that renders `null` as `false` reports a customer's pages as deindexed on the morning their card expires. `monitored` is the field that says which of those two a `null` is.\n\nNever calls the upstream provider, so it is free to render and poll.","tags":["hosting"],"responses":{"200":{"description":"The plan, both allowances, and every monitored target.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndexMonitoring"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"createIndexMonitoringTarget","summary":"Monitor another page, or a whole site hosted elsewhere.","description":"Creates one monitored target. `kind` decides which product and therefore which allowance it consumes, and the two are **not** interchangeable: a `section` needs a `path` and consumes `indexing_targets`; an `external_site` takes no `path` and consumes `external_index_sites`.\n\nDoes **not** check the target. The next scheduled sweep does, on this account's normal cadence — so creating a target costs nothing, and a typo costs nothing.\n\nAnswers `409` when the same page is already monitored, rather than succeeding silently: a duplicate would consume a second allowance slot and a second check every day for the same answer.\n\nAnswers `422` with `ALLOWANCE_EXCEEDED` when the relevant allowance is full, carrying the limit in `details` and naming the add-on that raises it.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndexMonitoringTargetCreate"}}}},"responses":{"201":{"description":"The target that was created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndexMonitoringTarget"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/index-monitoring/targets/{targetId}":{"parameters":[{"name":"targetId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The monitored target to stop watching."}],"delete":{"operationId":"deleteIndexMonitoringTarget","summary":"Stop monitoring one target.","description":"Removes the target and frees its allowance slot.\n\n⛔ The **check history is kept**. Readings are keyed by organisation and hostname rather than by this row, so removing a target does not destroy measurements that were already paid for, and re-adding the same page later shows its history unbroken.","tags":["hosting"],"responses":{"204":{"description":"No longer monitored."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/sites/{siteId}/index-check":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteIndexCheck","summary":"A hosted site's search-index status.","description":"The **cached** search-index reading for this site's primary domain, in the same shape as the domain endpoint — it is the same underlying reading, reached from the site.\n\n⛔⛔ **This is the only door most customers have.** The reading is keyed by FQDN and a hosted site has one, so it was always expressible; until this endpoint existed the only way to reach it was `GET /v1/domains/{domainId}/index-check`, which requires a `Domain` row. A Footprint-Free customer who registers their names elsewhere and connects nothing has no such row, so the status of their sites was unreachable from anywhere in the product.\n\nNever calls the upstream provider, so it is free to render. `state` distinguishes the same four cases the domain endpoint documents, and `unknown` must not be rendered like `not_indexed` — a client that conflates them reports healthy sites as deindexed during any provider outage.\n\n⛔ There is deliberately **no** run counterpart on a site. Each check spends provider allowance, and a refresh button on every site across a large estate is an unbounded cost; freshness comes from the scheduled sweep. To force a check for one specific name, use the domain research tool, where the spend is metered against your own allowance.","tags":["hosting"],"responses":{"200":{"description":"The cached check, with its age.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainIndexCheck"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/sites/{siteId}/index-check/history":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"listSiteIndexCheckHistory","summary":"A hosted site's recent search-index checks.","description":"Recent checks for this site's primary domain, newest first. The **transition** is what this feature is for — a site that was indexed on the 12th and not on the 14th is the event worth acting on, and a single current value cannot express it. Free to call.","tags":["hosting"],"responses":{"200":{"description":"Recent checks, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainIndexCheckHistory"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/sites/{siteId}/registry":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteRegistry","summary":"What the public registry says about a hosted site's domain.","description":"The WHOIS card for a site: registration dates, the registrar, the EPP status set and the DNSSEC flag, read from the registry's own **RDAP** service. Same response shape as `getDomainRegistry`, reached from the site instead of from a `Domain` row.\n\n⭐ **It answers for a domain registered somewhere else**, which is the whole point: RDAP needs no credential, so a site whose name was registered at a registrar we have never integrated still returns its real expiry date and transfer lock. Nothing is spent and no allowance is consumed, which is why this is affordable on every site when a paid authority reading would not be.\n\n⛔ The site's `primary_domain` is a **hostname** and may sit below the registration — `blog.example.com` has no registry record of its own. The name that answered is returned in `fqdn`, so a client should render that rather than assuming it matches the site's hostname.\n\nEvery field is nullable and `null` means the registry did not publish it, never that the domain lacks it — `transfer_locked: null` is \"we did not read a status set\", not \"unlocked\". No registrant, admin or technical contact is returned, by decision.\n\nA registry that does not answer is a `503`, never an empty body and never a `404`. A site with no domain name yet is also a `503`, with a message saying so.","tags":["hosting"],"responses":{"200":{"description":"The registry's current record for the site's domain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistryProfile"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/seo/quota":{"get":{"operationId":"getSeoLookupQuota","summary":"The research allowance for this account.","description":"How many domain lookups this plan includes each day, how many are left, any purchased lookups still unspent, and what buying more costs.\n\n`can_look_up` is authoritative and is **not** the same as `remaining > 0`: an account that is suspended or unpaid may have lookups left and still not be permitted to spend them.","tags":["seo"],"responses":{"200":{"description":"The allowance meter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoLookupQuota"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/seo/quota/top-up":{"post":{"operationId":"buySeoLookupPack","summary":"Buy extra domain lookups.","description":"Buys a pack of additional lookups, paid from the account credit balance. Purchased lookups do not expire and are spent only once the daily plan allowance is used up.\n\nIdempotent on the `Idempotency-Key` header: repeating a request with the same key returns the same purchase rather than buying a second pack.\n\n`422` when the pack size is not sold or the credit balance does not cover it — in which case nothing is charged at all.","tags":["seo"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Caller-supplied replay key. Strongly recommended: without one, a retried request buys a second pack.","schema":{"type":"string","maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoLookupPackRequest"}}}},"responses":{"201":{"description":"Bought. The meter as it now stands.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoLookupQuota"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/domains/{domainId}/index-check":{"parameters":[{"$ref":"#/components/parameters/DomainId"}],"get":{"operationId":"getDomainIndexCheck","summary":"Get a domain's search-index status.","description":"The **cached** search-index reading for this domain — whether Google has the site, and roughly how much of it. Included on every Footprint-Free plan.\n\nThis never calls the upstream provider, so it is free to render and poll. Use the run endpoint to perform a new check; each check consumes provider allowance.\n\n`state` distinguishes four cases that must not be conflated: `indexed`, `not_indexed` (the provider answered and the search engine has nothing — a real measurement worth acting on), `unknown` (the provider could not tell us — an outage on our side, **not** a statement about the site) and `never_checked` (nothing has been requested yet). A client that renders `unknown` the same way as `not_indexed` will report healthy sites as deindexed during any provider outage.\n\n`estimated_indexed_pages` is the search engine's own loose upper bound and is **not** an authoritative page count — it routinely differs from Search Console by several times. Present it as a trend, never as \"N pages indexed\".","tags":["domains"],"responses":{"200":{"description":"The cached index check, with its age.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainIndexCheck"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/domains/{domainId}/index-check/history":{"parameters":[{"$ref":"#/components/parameters/DomainId"}],"get":{"operationId":"listDomainIndexCheckHistory","summary":"List a domain's recent search-index checks.","description":"Recent checks, newest first. The **transition** is what this feature is for — a site that was indexed on the 12th and not on the 14th is the event worth alerting on, and a single current value cannot express it.\n\nNever calls the upstream provider.","tags":["domains"],"responses":{"200":{"description":"Recent checks, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainIndexCheckHistory"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/domains/{domainId}/index-check/run":{"parameters":[{"$ref":"#/components/parameters/DomainId"}],"post":{"operationId":"runDomainIndexCheck","summary":"Run a fresh search-index check for a domain.","description":"Calls the upstream provider and stores a new check, then returns it in the same shape as the GET. **Consumes provider allowance on every call**, so it is driven by an explicit user action or the scheduled sweep — never by rendering a page.\n\nReturns 503 when the provider is unreachable, unconfigured, or the allowance is exhausted. In every one of those cases the previously stored reading is left untouched and still served by the GET — a failed check never writes a negative result.","tags":["domains"],"responses":{"200":{"description":"The freshly performed check.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainIndexCheck"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/domain-alerts":{"get":{"operationId":"getDomainAlerts","summary":"Domain alerts — the saved-search allowance, the plans and every saved search.","description":"Q321 (V1 parity, `pbn.ltd/domain-alerts/`). A saved search is the aged-domain list's own filters (`GET /v1/marketplace/aged-domains`), matched once a day; one e-mail per organisation names every domain newly on sale that matches and every one it was told about that is now at least 10% cheaper. Every organisation keeps `free` (1) active search with no plan; `domain_alerts_10` and `domain_alerts_50` (on the add-ons catalogue) add 10 and 50, summed. `allowed` is `null` and `unlimited` true for our own organisation. Paused searches are kept and do not count.","tags":["marketplace"],"responses":{"200":{"description":"The organisation's domain alerts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainAlerts"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/domain-alerts/searches":{"post":{"operationId":"createDomainAlertSearch","summary":"Save the aged-domain list's filters as a daily alert.","description":"`params` are the aged-domain list's query parameters exactly as the list sent them (`q`, `tld`, `language`, `category`, `min_`/`max_` for `dr`, `da`, `tf`, `cf`, `rd`, `uniques`, `added_year`, `price`, and the flags `indexed`, `wiki`, `gnews`); `sort` and anything else is ignored. Saving takes a baseline — the domains matching now are not announced. A blank `name` is built from the filters. `422` when no filter is set, the name is blank after trimming, the same active search exists, or the account's active searches are already at its allowance (pause one or choose a plan with more).","tags":["marketplace"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["params"],"properties":{"name":{"type":"string","maxLength":120},"params":{"type":"object","additionalProperties":{"type":"string","maxLength":200}}}}}}},"responses":{"201":{"description":"The saved search.","content":{"application/json":{"schema":{"type":"object","required":["search"],"properties":{"search":{"$ref":"#/components/schemas/DomainAlertSearch"}}}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/domain-alerts/searches/{search_id}":{"parameters":[{"name":"search_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"operationId":"updateDomainAlertSearch","summary":"Rename, pause or resume a saved search.","description":"`active: false` pauses (kept, not counted). `active: true` resumes it within the allowance (`422` past it) and takes a fresh baseline, so domains added while it was paused are not announced.","tags":["marketplace"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"The saved search.","content":{"application/json":{"schema":{"type":"object","required":["search"],"properties":{"search":{"$ref":"#/components/schemas/DomainAlertSearch"}}}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"deleteDomainAlertSearch","summary":"Delete a saved search.","tags":["marketplace"],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/domain-alerts/searches/{search_id}/matches":{"get":{"operationId":"listDomainAlertMatches","summary":"The domains a saved search has announced, newest first.","description":"The last 50 domains this search announced (new or 10%+ cheaper), each with the aged domain as the list shows it, the price when we told the customer, and whether it is still on sale.","tags":["marketplace"],"parameters":[{"name":"search_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The search and its announced matches.","content":{"application/json":{"schema":{"type":"object","required":["search","matches"],"properties":{"search":{"$ref":"#/components/schemas/DomainAlertSearch"},"matches":{"type":"array","items":{"type":"object","required":["notified_at","price_minor_when_told","domain","available"],"properties":{"notified_at":{"type":["string","null"],"format":"date-time"},"price_minor_when_told":{"type":"integer"},"domain":{"$ref":"#/components/schemas/AgedDomain"},"available":{"type":"boolean"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/domain-vetting":{"get":{"operationId":"getDomainVetting","summary":"Domain vetting — credits held, the packs, the markets and recent reports.","description":"Everything the domain vetting screen needs in one read: how many report credits the organisation holds (`unlimited` for our own organisation), the one-off packs that sell them (`domain_vetting_1`, `_10`, `_50` — priced on the add-ons catalogue), the search markets a report can be read for, how many days a re-vet of the same domain is free (`reuse_days`), the most recent reports and the most recent credit movements.","tags":["visibility"],"responses":{"200":{"description":"The organisation's domain vetting overview.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainVetting"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/domain-vetting/reports":{"get":{"operationId":"listDomainVettingReports","summary":"Your domain vetting reports, filtered and sorted.","description":"Up to 200 of the organisation's reports (V1 parity), newest first unless `sort` says otherwise. A free read of stored rows.","tags":["visibility"],"parameters":[{"name":"q","in":"query","required":false,"description":"Part of a domain name.","schema":{"type":"string","maxLength":100}},{"name":"verdict","in":"query","required":false,"schema":{"type":"string","enum":["clean","care","risk"]}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["queued","running","complete","partial","failed","refused"]}},{"name":"min_score","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"max_score","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"sort","in":"query","required":false,"description":"`score` best first, `worst` lowest first, `domain` A-Z; newest first by default.","schema":{"type":"string","enum":["score","worst","domain"]}}],"responses":{"200":{"description":"The reports.","content":{"application/json":{"schema":{"type":"object","required":["reports"],"properties":{"reports":{"type":"array","items":{"$ref":"#/components/schemas/DomainVetSummary"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"post":{"operationId":"requestDomainVettingReport","summary":"Vet a domain — spends one report credit.","description":"Starts a pre-purchase report on `domain` for the search market `location_code` (default `2840`, the United States). One report credit is taken when the report is created and the report is built in the background (poll `GET /v1/domain-vetting/reports/{report_id}`). A report where nothing could be read, or one the account's standing no longer allows by the time it runs, gives its credit back. Asking again about the same domain and market inside `reuse_days` returns the existing report with `200` and costs nothing.\n\nRefused with `403` when the organisation holds no credit or is not in good standing, `422` for something that is not a domain or a market we read, and `503` when reports cannot be started right now — in every refusal no credit is taken.","tags":["visibility"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainVetRequest"}}}},"responses":{"200":{"description":"A recent report on the same domain and market — returned free.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainVetRequested"}}}},"202":{"description":"The report was created, its credit taken, and it is being built.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainVetRequested"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/domain-vetting/reports/bulk":{"post":{"operationId":"requestDomainVettingBulk","summary":"Vet up to 25 domains as one run — spends one credit per new report.","description":"V1 `run_many` parity. Every domain is validated and the credits for the NEW reports are counted before any is taken, so a run the organisation cannot pay for in full is refused with `403` and takes nothing. A domain vetted in the last `reuse_days` returns its report free (`reused`). ONE e-mail goes out when the last report of the run has finished. `422` for more than 25 domains, one that is not a domain, or an unknown market.","tags":["visibility"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domains"],"properties":{"domains":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"string","maxLength":300}},"location_code":{"type":"integer","default":2840}}}}}},"responses":{"200":{"description":"Every domain had a recent report — returned free.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainVetBulkRequested"}}}},"202":{"description":"The new reports were created, their credits taken, and they are being built.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainVetBulkRequested"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/domain-vetting/reports/export":{"get":{"operationId":"exportDomainVettingReports","summary":"The filtered report list as a CSV file.","description":"V1 `export.csv` parity — the same filters as the list, up to 200 rows.","tags":["visibility"],"parameters":[{"name":"q","in":"query","required":false,"description":"Part of a domain name.","schema":{"type":"string","maxLength":100}},{"name":"verdict","in":"query","required":false,"schema":{"type":"string","enum":["clean","care","risk"]}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["queued","running","complete","partial","failed","refused"]}},{"name":"min_score","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"max_score","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"sort","in":"query","required":false,"description":"`score` best first, `worst` lowest first, `domain` A-Z; newest first by default.","schema":{"type":"string","enum":["score","worst","domain"]}}],"responses":{"200":{"description":"The CSV file.","content":{"text/csv":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/domain-vetting/reports/{report_id}":{"get":{"operationId":"getDomainVettingReport","summary":"One domain vetting report — verdict, reasons and evidence.","description":"The report as it stands. While `status` is `queued` or `running` poll again. A `complete` or `partial` report carries a 0-100 `score`, a `verdict` (`clean`, `care`, `risk`), the `reasons` behind it (worst first, each a stable `code` with `params` the screen renders in the reader's language) and the evidence in `parts`. `missing` names the parts that could not be read this time; they are left out of the score, never scored as clean. A `null` score means \"not scored\", never zero.","tags":["visibility"],"parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The report.","content":{"application/json":{"schema":{"type":"object","required":["report"],"properties":{"report":{"$ref":"#/components/schemas/DomainVetReport"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"deleteDomainVettingReport","summary":"Remove a finished report from your list.","description":"V1 parity. The credit it used is not returned. `422` while the report is still being built.","tags":["visibility"],"parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/domain-vetting/reports/{report_id}/pdf":{"get":{"operationId":"getDomainVettingReportPdf","summary":"The report as a PDF, in the reader's language.","description":"V1 `zinnvet/pdf.py` parity: rendered only from what the report stored, so an old report downloads exactly as it was. `locale` picks the language (an enabled language code; English otherwise). `404` until the report has a score; `503` when the PDF cannot be made right now.","tags":["visibility"],"parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"locale","in":"query","required":false,"schema":{"type":"string","maxLength":20}}],"responses":{"200":{"description":"The PDF.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/visibility/plan":{"get":{"operationId":"getVisibilityPlan","summary":"What visibility add-ons this organisation holds.","description":"Which visibility products the organisation has (`ai_visibility`, `reputation`, `onpage`, `product_data`, `rank`, `backlinks`, `keyword_research`, `competitors`, `domain_score` — see `VisibilityAuditKind`), how many external domains it may watch, how many it is using, how many products it may price-track, and the Zinn® credit balance an on-demand run would draw on.\n\n`from_plan` lists the products granted by the plan or a bundle rather than by a standalone add-on. An upsell surface must read it and say \"included in your plan\" instead of offering to sell a capability the customer already holds — a product is a switch you cannot hold twice, unlike the target allowance, which stacks.\n\n`credit_balance_micros` is the customer's own balance in USD micros. The response deliberately carries **no** figure for what a run costs Zinn® and no margin: that is on the admin surface only.","tags":["visibility"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"seoSiteConnection":[]}],"responses":{"200":{"description":"The organisation's visibility entitlements.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisibilityPlan"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/footprint":{"get":{"operationId":"getFootprintOverview","summary":"The footprint checker for this organisation — allowances, sites and latest verdict.","description":"Whether the PBN footprint checker is on for this organisation, how often it runs on its own (`cadence_days`), how many sites hosted elsewhere it may include and how many on-demand checks remain this month, the external sites added, the latest finished check and any check still running, and the score over time.\n\nEvery site hosted with us is always included and never counts against `external_allowance`. `-1` in an allowance means unlimited, and the matching `*_remaining` field is then `null`.","tags":["footprint"],"responses":{"200":{"description":"The organisation's footprint checker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FootprintOverview"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/footprint/sites":{"post":{"operationId":"addFootprintSite","summary":"Include a site hosted elsewhere in footprint checks.","description":"Adds a domain that is not hosted with us. The domain is normalised to its bare host (`https://www.Example.com/x` becomes `example.com`). Refused with `422` — never silently dropped — when the external-site allowance is used up, when the domain is already included, or when it is hosted with us (and therefore already in every check).","tags":["footprint"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FootprintSiteCreate"}}}},"responses":{"201":{"description":"The site was added.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FootprintSite"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/footprint/sites/{site_id}":{"parameters":[{"name":"site_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"delete":{"operationId":"removeFootprintSite","summary":"Stop including a site hosted elsewhere; its slot is free at once.","tags":["footprint"],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/footprint/sites/history":{"get":{"operationId":"getFootprintSiteHistory","summary":"One site across the organisation's finished footprint checks.","description":"Every finished check that covered the site, newest first: whether the site could be read, and the findings that named it. `404` — not an empty list — for a site that is in no finished check of this organisation, so an empty answer is never mistaken for a clean one.","tags":["footprint"],"parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string"},"description":"A site of the organisation's — hosted with us or added."}],"responses":{"200":{"description":"The site's history.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FootprintSiteHistory"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/public/footprint-checks":{"get":{"operationId":"getPublicFootprintCheckAvailability","summary":"Whether the free public footprint check is switched on.","description":"**Anonymous.** The free check is **off by default** and is turned on by the platform operator. This read always answers, in both states, so a page can decide whether to offer the check at all: while `enabled` is `false` the start and read operations below answer `404`.","tags":["public"],"security":[],"responses":{"200":{"description":"The switch, and how many sites one check may name.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicFootprintCheckAvailability"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"startPublicFootprintCheck","summary":"Check up to five sites for the public traces that tie them together — no account.","description":"**Anonymous.** Starts a free check of one to five public sites and returns a `token` to read it back with. The answer is the verdict — a score, a grade and how many things there are to look at — and nothing else: what each of them is, and how to fix it, is the signed-in product, for the customer's own sites.\n\nThe same set of sites asked again within a day is answered by the check that already exists (`200`, same `token`) and starts nothing. A new check is `202`; poll `GET /v1/public/footprint-checks/{token}` until `state` is `done`.\n\nAn address, a single-label name or more than five sites is refused with `422`. Charged against a per-visitor and a global budget before the body is parsed, and against a platform-wide daily ceiling on new checks (`429`).\n\n**Off by default.** While the free check is switched off this answers `404` with the refusal `refusal.footprint.publicDisabled`, charges no budget and starts nothing; see `GET /v1/public/footprint-checks`.","tags":["public"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicFootprintCheckCreate"}}}},"responses":{"200":{"description":"A check of these sites already exists; this is it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicFootprintCheck"}}}},"202":{"description":"The check that is now running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicFootprintCheck"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/footprint-checks/{token}":{"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","maxLength":64}}],"get":{"operationId":"getPublicFootprintCheck","summary":"Read a public footprint check back by its token.","description":"`404` for a token that names nothing — and for every token while the free check is switched off (`refusal.footprint.publicDisabled`).","tags":["public"],"security":[],"responses":{"200":{"description":"The check — running, or its verdict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicFootprintCheck"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/footprint/runs":{"get":{"operationId":"listFootprintRuns","summary":"The organisation's footprint checks, newest first.","tags":["footprint"],"responses":{"200":{"description":"Up to the 60 most recent checks.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FootprintRunList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"startFootprintRun","summary":"Check now — start an on-demand footprint check.","description":"Starts a check of every site (`scope: account`, the default), of one site group's hosted sites (`scope: group`), of one site on its own (`scope: site`) or of a chosen set of the organisation's sites compared with each other (`scope: custom`). A site named in `domains` that the organisation neither hosts with us nor has added is refused with `422` and named. It counts against the month's on-demand checks; a check that could read none of its sites is not counted. If a check is already running for the organisation it is returned instead (`already_running: true`) and nothing is counted. The check runs in the background: poll `GET /v1/footprint/runs/{run_id}` until its `state` is `done`.","tags":["footprint"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FootprintRunCreate"}}}},"responses":{"202":{"description":"The check that is now running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FootprintRunStarted"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/footprint/runs/{run_id}":{"parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getFootprintRun","summary":"One footprint check — its findings, its most linked site pairs and each site's state.","description":"A finding names the organisation's own sites it covers and a count. Its `code` is an opaque identifier the dashboard renders as a title, what it means and how to fix it; no measured value is ever returned. `owner: platform` marks something we fix for you, which never lowers the score.","tags":["footprint"],"responses":{"200":{"description":"The check.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FootprintRunDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/footprint/runs/{run_id}/links":{"parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getFootprintRunLinks","summary":"Every site one site is tied to in a check, and by which findings.","tags":["footprint"],"parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string"},"description":"A site covered by the check."}],"responses":{"200":{"description":"The site's partners, strongest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FootprintSiteLinks"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/visibility/targets":{"get":{"operationId":"listVisibilityTargets","summary":"List the domains this organisation is watching.","description":"Every watched domain, oldest first. A target need **not** be a domain hosted with us — a competitor or a prospect is a legitimate target, and `is_external` says which.","tags":["visibility"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"seoSiteConnection":[]}],"responses":{"200":{"description":"The watch-list.","content":{"application/json":{"schema":{"type":"object","required":["targets"],"properties":{"targets":{"type":"array","items":{"$ref":"#/components/schemas/VisibilityTarget"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"addVisibilityTarget","summary":"Watch a new domain.","description":"Adds a domain to the watch-list. A domain that is **not** hosted with us counts against the external-target allowance; the organisation's own sites do not.\n\n`category` and `market` decide what questions the answer engines are asked, and are the single most important thing a customer can supply — a reading taken on defaults is real and is worth less. `brand` is the trading name to look for in an answer, which is genuinely separate from the domain: a model that recommends a business by name without printing its URL has still mentioned them.\n\n`cadence_days: 0` pauses the schedule. It does **not** delete anything: history and settings survive and it resumes with no further action.","tags":["visibility"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisibilityTargetRequest"}}}},"responses":{"201":{"description":"The watched domain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisibilityTarget"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/visibility/domain-options":{"get":{"operationId":"listVisibilityDomainOptions","summary":"The organisation's own domains, to pick one to watch.","description":"Domains this organisation already has with us that match `q` — registered with us, connected to us, or attached to a site we host (even when registered elsewhere) — for the watch-a-domain picker. A type-ahead page of at most 20; narrow it by typing. Any other domain can still be watched by typing it in full. `watched` marks the ones already on the watch-list.","tags":["visibility"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"seoSiteConnection":[]}],"parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":253}}],"responses":{"200":{"description":"Matching domains.","content":{"application/json":{"schema":{"type":"object","required":["options"],"properties":{"options":{"type":"array","items":{"type":"object","required":["domain","source","site_id","site_name","watched"],"properties":{"domain":{"type":"string"},"source":{"type":"string","enum":["registered","connected","hosted"]},"site_id":{"type":"string","format":"uuid","nullable":true},"site_name":{"type":"string"},"watched":{"type":"boolean"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/visibility/targets/{targetId}":{"parameters":[{"$ref":"#/components/parameters/VisibilityTargetId"}],"patch":{"operationId":"updateVisibilityTarget","summary":"Change a watched domain's settings.","description":"Updates the label, brand, category, market, cadence or which products watch this domain. `cadence_days: 0` pauses rather than deletes.","tags":["visibility"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisibilityTargetRequest"}}}},"responses":{"200":{"description":"The updated target.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisibilityTarget"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"removeVisibilityTarget","summary":"Stop watching a domain.","description":"Removes the domain and its audit history. To keep the history and simply stop the schedule, set `cadence_days` to 0 instead.","tags":["visibility"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"seoSiteConnection":[]}],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/visibility/targets/{targetId}/review-profiles":{"parameters":[{"$ref":"#/components/parameters/VisibilityTargetId"}],"put":{"operationId":"setVisibilityReviewProfiles","summary":"Confirm which review profiles belong to this business.","description":"A business is identified by a `place_id` at Google, a domain at Trustpilot and a `url_path` at Tripadvisor, and a search for a common trading name legitimately returns several records. The **customer confirms** which are theirs and the confirmed set is what the weekly reputation check refreshes.\n\nNothing picks a profile automatically. Doing so would, for every chain and every shared trading name, report a stranger's reviews on a paying customer's dashboard.","tags":["visibility"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profiles"],"properties":{"profiles":{"type":"array","items":{"$ref":"#/components/schemas/ReviewProfile"}}}}}}},"responses":{"200":{"description":"The updated target.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisibilityTarget"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/visibility/targets/{targetId}/review-profile-lookup":{"parameters":[{"$ref":"#/components/parameters/VisibilityTargetId"}],"post":{"operationId":"lookupVisibilityReviewProfiles","summary":"Search the review sites for this business.","description":"Starts a search of Google, Trustpilot and Tripadvisor for the business and returns `202` with the target, its `profile_lookup.status` now `running`. The candidates land in `profile_candidates` when the search finishes; poll the target. Nothing is confirmed automatically — confirm with `setVisibilityReviewProfiles`.\n\nIncluded in the reputation add-on, and refused with `403` for an organisation that does not hold it or is not in good standing. One search runs per target at a time.","tags":["visibility"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"seoSiteConnection":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","maxLength":160,"description":"The business name. Defaults to the target's brand, label or domain."},"location":{"type":"string","maxLength":120,"description":"A town or country to narrow the search. Defaults to the target's market."}}}}}},"responses":{"202":{"description":"The search has started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisibilityTarget"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/visibility/local":{"get":{"operationId":"getLocalRankings","summary":"Local rankings — the allowances and every business followed.","description":"What the Local Rankings plan allows (businesses, towns per business, keyword rows and checks a month, and the fastest schedule a keyword may run at) with what is used, and a summary row per business. A `cap` of `null` means unlimited. Readable by any member.","tags":["visibility"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"seoSiteConnection":[]}],"responses":{"200":{"description":"The overview.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocalRankingsOverview"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/visibility/local/businesses":{"post":{"operationId":"addLocalBusiness","summary":"Follow a business on the map, by its website's domain.","description":"Creates the watched target for the business's website (or adds local rankings to a target already watching that domain). Refused with `422` once the plan's business allowance is used. A business is its OWN allowance: it never spends one of the competitor domains the visibility plan gives. Pick the business on the map next, with `POST /v1/visibility/targets/{targetId}/local/find`.","tags":["visibility"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocalBusinessRequest"}}}},"responses":{"201":{"description":"The business's local rankings, not set up yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocalRankings"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/visibility/local/places":{"get":{"operationId":"searchLocalPlaces","summary":"Towns a local search can be made from.","description":"Searches Google's own place list for one country — towns, post towns, counties, regions and the country itself. Free (it costs no check). The town's own name matches first. Returns at most twenty.","tags":["visibility"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"seoSiteConnection":[]}],"parameters":[{"name":"country","in":"query","required":true,"description":"ISO 3166-1 alpha-2 country code, such as `GB`.","schema":{"type":"string","minLength":2,"maxLength":2}},{"name":"q","in":"query","required":true,"description":"At least two characters of the place's name.","schema":{"type":"string","minLength":2,"maxLength":100}}],"responses":{"200":{"description":"Matching places.","content":{"application/json":{"schema":{"type":"object","required":["places"],"properties":{"places":{"type":"array","items":{"$ref":"#/components/schemas/LocalPlaceOption"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/visibility/targets/{targetId}/local/find":{"parameters":[{"$ref":"#/components/parameters/VisibilityTargetId"}],"post":{"operationId":"findLocalBusiness","summary":"Search the map for the business, so the customer can pick theirs.","description":"One live map search from the chosen town. It is metered as ONE check of the month's allowance (as V1 meters it) and refused with `422` when none is left. A search that finds no listing answers `200` with an empty list and uses NO check. Pick a result and save it with `PUT /v1/visibility/targets/{targetId}/local`.","tags":["visibility"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocalFindRequest"}}}},"responses":{"200":{"description":"The businesses the map showed, best first.","content":{"application/json":{"schema":{"type":"object","required":["results"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/LocalFindResult"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/visibility/targets/{targetId}/local":{"parameters":[{"$ref":"#/components/parameters/VisibilityTargetId"}],"get":{"operationId":"getLocalBusinessRankings","summary":"One business's local set-up, every row's positions and their trend.","description":"A row is one keyword searched from one town. Each carries its latest reading — the map position (of up to 100 listings read), the local 3-pack position on the results page and the website's organic position — the change since the previous reading, the businesses above it on the map, and up to twelve readings of trend. `null` positions mean \"we looked and the business was not there\", never zero; a row with `latest: null` has not been checked yet, and `pending: true` means its answer has been paid for and is on its way.","tags":["visibility"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"seoSiteConnection":[]}],"responses":{"200":{"description":"The business's local rankings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocalRankings"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"put":{"operationId":"setLocalBusinessRankings","summary":"Save the business, the towns and the keywords.","description":"Replaces the towns and keywords wholesale; every keyword is checked from every town. Refused with `422` naming the allowance when it would exceed the towns per business, the keyword rows or the checks a month the plan sells (planned as daily 30, weekly 4.3, monthly 1 check a month), or when a keyword asks for a faster schedule than the plan includes. It is never truncated. A keyword with no `frequency` runs at the plan's own cadence. Changing the business clears the previous business's history.","tags":["visibility"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocalSetup"}}}},"responses":{"200":{"description":"The updated local rankings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocalRankings"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"removeLocalBusiness","summary":"Stop following the business, and delete its history.","tags":["visibility"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"seoSiteConnection":[]}],"responses":{"204":{"description":"Stopped."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/visibility/targets/{targetId}/keywords":{"parameters":[{"$ref":"#/components/parameters/VisibilityTargetId"}],"put":{"operationId":"setVisibilityKeywords","summary":"Set the search phrases to track positions for.","description":"Replaces the phrase list wholesale. The phrases are customer-supplied and never derived: only the customer knows which searches they want to win, and the ones they already rank for are precisely the set this product has nothing to say about.\n\nEach phrase carries its own market. The same phrase in two countries is two different questions with two different answers and two separate costs, so `{phrase: \"hosting\", location: \"United Kingdom\"}` and `{phrase: \"hosting\", location: \"Germany\"}` are two entries rather than one.\n\nSending more phrases than the plan allows is refused with `422` naming the allowance. It is **not** truncated: silently checking the first twenty-five of two hundred reads as a complete list on the very screen the customer checks, and they would conclude the other one hundred and seventy-five were being watched.","tags":["visibility"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"keywords":{"type":"array","items":{"$ref":"#/components/schemas/TrackedKeyword"}}}}}}},"responses":{"200":{"description":"The updated target.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisibilityTarget"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/visibility/targets/{targetId}/prompts":{"parameters":[{"$ref":"#/components/parameters/VisibilityTargetId"}],"put":{"operationId":"setVisibilityPrompts","summary":"Set the customer's own questions for the AI answer engines.","description":"Replaces the question list wholesale; an empty list goes back to the default questions. Needs the AI Visibility plan. A question naming the customer is refused — it would always mention them and so measures nothing. Taking the organisation past its `prompts` allowance is refused with `422` naming the allowance, never truncated.","tags":["visibility"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompts":{"type":"array","items":{"type":"string","minLength":8,"maxLength":300}}}}}}},"responses":{"200":{"description":"The updated target.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisibilityTarget"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/visibility/targets/{targetId}/links":{"parameters":[{"$ref":"#/components/parameters/VisibilityTargetId"}],"put":{"operationId":"setVisibilityWatchedLinks","summary":"Set the individual links to watch pointing at this domain.","description":"Replaces the watched-link list wholesale. Needs Backlink Monitoring. A non-empty list enrols the domain in `link_watch` and makes it due at once, so the first reading lands within the hour; an empty list takes it back out. A `target_url` must be on this domain. Taking the organisation past its `links` allowance is refused with `422`, never truncated. Checks cost nothing — our own fetcher opens each page.","tags":["visibility"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"links":{"type":"array","items":{"$ref":"#/components/schemas/WatchedLink"}}}}}}},"responses":{"200":{"description":"The updated target.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisibilityTarget"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/visibility/targets/{targetId}/mention-phrases":{"parameters":[{"$ref":"#/components/parameters/VisibilityTargetId"}],"put":{"operationId":"setVisibilityMentionPhrases","summary":"Set the phrases to listen for across the web, and how often.","description":"Replaces this domain's phrase list wholesale. Only the list is written — each phrase's schedule belongs to the checks, so fixing a typo or changing a frequency never resets a phrase to \"due now\" and never buys a check nobody asked for. A newly added phrase is checked on the next sweep.\n\nRefused with `422`, never truncated: more phrases than the plan allows (counted across all the organisation's domains), a schedule that plans more checks a month than the plan includes, a phrase already listened for on another domain (it would be the same answer bought twice), or a phrase shorter than three characters.","tags":["visibility"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phrases":{"type":"array","items":{"$ref":"#/components/schemas/MentionPhrase"}}}}}}},"responses":{"200":{"description":"The updated target.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisibilityTarget"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/visibility/targets/{targetId}/brand-serp":{"parameters":[{"$ref":"#/components/parameters/VisibilityTargetId"}],"get":{"operationId":"getVisibilityBrandSerp","summary":"Brand page 1 — what Google's first page shows for this brand, with each result's tone.","description":"The results seen on the latest check of each brand search (or, with `history=true`, every result ever seen, newest first), each read as negative, neutral or positive, and the quote for one check and for a month of checks, read from the live per-check Zinn® credit price. Never calls the data provider. Readable before brand page 1 is switched on (`enabled` false), so the price is seen before any check is paid for.","tags":["visibility"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"seoSiteConnection":[]}],"parameters":[{"name":"sentiment","in":"query","required":false,"schema":{"type":"string","enum":["negative","neutral","positive","unclassified"]}},{"name":"history","in":"query","required":false,"schema":{"type":"boolean","default":false}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"The results, the searches and the quote.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandSerpPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"operationId":"setVisibilityBrandTerms","summary":"Set the brand searches whose first Google page is watched (the brand and up to four variants).","description":"Each search is one check per run at the per-check price, so the list is the bill the customer chooses. An empty list watches the brand name. `422` for more than five searches or one longer than 120 characters — refused, never truncated.","tags":["visibility"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["terms"],"properties":{"terms":{"type":"array","maxItems":50,"items":{"type":"string"}}}}}}},"responses":{"200":{"description":"The saved searches, the quote and the latest results.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandSerpPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/visibility/targets/{targetId}/mentions":{"parameters":[{"$ref":"#/components/parameters/VisibilityTargetId"}],"get":{"operationId":"listVisibilityMentions","summary":"The web pages that mention this domain's phrases, newest found first.","description":"Reads what the scheduled checks already found — it never calls the data provider, so paging through mentions costs nothing. `403` when brand mentions is not on the plan.","tags":["visibility"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"seoSiteConnection":[]}],"parameters":[{"name":"phrase","in":"query","required":false,"schema":{"type":"string"},"description":"Only mentions of this phrase."},{"name":"tone","in":"query","required":false,"schema":{"type":"string","enum":["positive","neutral","negative"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"One page of mentions and the total they were drawn from.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandMentionPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/visibility/targets/{targetId}/products":{"parameters":[{"$ref":"#/components/parameters/VisibilityTargetId"}],"put":{"operationId":"setVisibilityProducts","summary":"Set the products to price-track, and the seller names to look for.","description":"The products and the merchant names are set together because they are only useful together. With products and no seller name we can read the shelf and list who is on it, but we cannot say whether the customer is one of them — the audit reports `product_seller_unknown` and the score is `null`, which is honest rather than a claim that they are missing from Google Shopping.\n\nNothing infers a seller name from the customer's domain. Measured against a live Google Shopping response: every listing carries a `seller` name and a **null** `domain`, so a near-match on a trading name is the only thing a guess could use — and a wrong one would report a stranger's price as the customer's own, on a screen they pay for, with nothing downstream able to detect it.\n\nSending more products than the plan allows is refused with `422` naming the allowance. It is **not** truncated: silently auditing the first ten of two hundred reads as a complete list on the very screen the customer checks.","tags":["visibility"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/TrackedProduct"}},"merchant_names":{"type":"array","items":{"type":"string","maxLength":160}}}}}}},"responses":{"200":{"description":"The updated target.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisibilityTarget"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/visibility/targets/{targetId}/backlink-links":{"parameters":[{"$ref":"#/components/parameters/VisibilityTargetId"}],"get":{"operationId":"listVisibilityBacklinkLinks","summary":"The individual inbound links for a watched domain.","description":"The per-link table behind the backlink counts: which page links to you, with what anchor text, how strong that page and its domain are, and whether the link is new, lost or broken. The aggregate profile answers *how many*; this answers *which*.\n\nIncluded with the backlink monitoring the plan already carries — there is no separate add-on to buy. `403` when the plan does not include backlink monitoring, and also when the account is not in good standing, because this endpoint spends money with the data provider at the moment it is called rather than reading a stored row.\n\nThe page size is **not** a query parameter. It is derived in the adapter from the provider's measured price table, because it is a spend decision rather than a display preference: the provider charges a fixed fee per request plus a much smaller amount per row returned, so one large page costs barely more than one small page and paginating in small steps pays the fixed fee every time.\n\n`total` and `showing` are both returned and they are different facts. A response carrying only the list reads as complete however few rows it holds, so a caller that cannot say \"showing 100 of 40,000\" would present a page as the whole profile.\n\nEvery rank and score is nullable. `null` means the provider gave no reading; `0` means it measured one and it is zero. A missing reading rendered as `0` makes a whole column of links look worthless when they are merely unmeasured.","tags":["visibility"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"seoSiteConnection":[]}],"responses":{"200":{"description":"One page of links, newest-authority first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BacklinkLinkPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/visibility/targets/{targetId}/audits":{"parameters":[{"$ref":"#/components/parameters/VisibilityTargetId"},{"name":"kind","in":"query","required":false,"schema":{"$ref":"#/components/schemas/VisibilityAuditKind"},"description":"Which product's history to return. Defaults to `ai_visibility`."}],"get":{"operationId":"listVisibilityAudits","summary":"A watched domain's audit history.","description":"Recent audits for one product, newest first, bounded server-side. **The trend is the product** — \"three engines recommended you in July and one does now\" — and a single current reading cannot express it.\n\nThis never calls a provider, so it is free to render and poll.","tags":["visibility"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"seoSiteConnection":[]}],"responses":{"200":{"description":"Recent audits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisibilityAuditList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/visibility/targets/{targetId}/run":{"parameters":[{"$ref":"#/components/parameters/VisibilityTargetId"}],"post":{"operationId":"runVisibilityAudit","summary":"Run an audit now.","description":"Starts an on-demand audit and returns `202` with a workflow id. The scheduled audit is included in the add-on; an on-demand run **spends Zinn® credits**, and the request is refused with `403` when the balance will not cover it.\n\nThis is asynchronous by necessity, not by preference: one AI-visibility audit is a dozen provider calls and some answer engines take minutes. Poll the audit list for the result.\n\nThe workflow id is deterministic per target and product, so pressing the button twice while a run is in flight costs one audit rather than two. A run after a finished one always starts.\n\nRank tracking, product data and reputation measure only what the customer has supplied, so they are refused with `422` — before anything is spent — until the target has at least one search phrase, product or confirmed review profile respectively.\n\nA run a metered SEO allowance pays for — a site audit, a backlink refresh, a keyword list, a domain report, or a link-watch check — spends that allowance and **no credit**; once the month's allowance is used it is refused with `422` naming the allowance and the day it resets (see `VisibilityPlan.allowances`).\n\nKeyword research with no `page_url` reports the phrases the whole site is found for; with a `page_url` on the watched domain it reports the phrases that one page is found for (the audit summary's `basis` is `site` or `page`). A page on another host, or a `page_url` on any other kind, is refused with `422` before anything is spent.","tags":["visibility"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kind"],"properties":{"kind":{"$ref":"#/components/schemas/VisibilityAuditKind"},"page_url":{"type":"string","maxLength":2000,"description":"Keyword research only — one page of the watched site to research instead of the whole site, e.g. `https://example.com/pricing/`. Blank means the whole site."},"seed":{"type":"string","maxLength":120,"description":"Keyword research only — suggestions around one phrase, e.g. `blue widgets`. Blank means the site (or `page_url`) is the basis."},"location":{"type":"string","maxLength":120,"description":"Research kinds only (`keyword_research`, `competitors`, `domain_score`) — the market the question is asked in, in the customer's own words (\"Germany\", \"de\"), as on a tracked keyword. Ignored for any other kind. An unresolved market is reported on the audit summary (`market.resolved: false`), never guessed."},"language":{"type":"string","maxLength":8,"description":"Research kinds only — the results language for `location`."},"competitor":{"type":"string","maxLength":253,"description":"`competitors` only — one rival domain to draw a keyword-level gap against (the audit summary's `gap`; see `SeoResearchInput.competitor`)."}}}}}},"responses":{"202":{"description":"The audit has been started.","content":{"application/json":{"schema":{"type":"object","required":["workflow_id","kind","target_id"],"properties":{"workflow_id":{"type":"string"},"kind":{"$ref":"#/components/schemas/VisibilityAuditKind"},"target_id":{"type":"string","format":"uuid"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/visibility/audits/{auditId}":{"parameters":[{"name":"auditId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getVisibilityAudit","summary":"One audit, with every finding.","description":"The full result of one audit: its score, its product-specific summary and every individual check that was made — including the ones that **passed**, which are half the product. An audit that listed only faults would show a healthy site an empty screen, which reads as \"the audit did not run\".\n\n`score` is `null` when nothing could be measured. It is **not** zero. Zero means we asked and the answer engines do not mention this site; `null` means we could not ask.","tags":["visibility"],"security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"seoSiteConnection":[]}],"responses":{"200":{"description":"The audit and its findings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisibilityAudit"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/domains/{domainId}/dns/holder-rows/remove":{"parameters":[{"$ref":"#/components/parameters/DomainId"}],"post":{"operationId":"removeDnsHolderRows","tags":["domains"],"summary":"Remove the parking-holder rows from a hostname that also points at the site.","description":"s1014 DNSSTATE. A hostname publishing BOTH the parking holder's addresses and the site's own target sends some visitors to the holder page. This deletes only the holder rows at a name that, re-read from the DNS provider now, still carries a non-holder target; a name holding only holder rows (a parked name) is never touched, and the client sends no list. Answers what was removed (empty when nothing was mixed). Audited as `domain.dns.holder_rows_removed`. Requires `domains.dns.manage`.","responses":{"200":{"description":"The holder rows that were removed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DnsHolderRowsRemoved"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/domains/{domainId}/dns/records":{"parameters":[{"$ref":"#/components/parameters/DomainId"}],"get":{"operationId":"listDnsRecords","summary":"List a page of a domain's DNS records.","description":"The resource records in the domain's hosted authoritative zone. Requires `sites.view`, RLS-scoped. **Footprint-Free (PBN) line:** the A/AAAA records publish the shared fleet IP and are hidden entirely from this line (they are platform-managed) — the returned set never contains them (register #93).\n\n**Paginated (issue #466).** Keyset cursor over `(name, type, value, id)`, default page size 50, hard maximum 200. Filtering by product line happens **before** pagination, so a hidden record can never surface on a later page. A client must follow `page.next_cursor` until `page.has_more` is false; reading only the first page reads only the first page.\n\n**Two different 404s, and a client MUST branch on the `code` rather than the status.** `NOT_FOUND` is the ordinary miss — no such domain, or not in your scope. `DNS_NOT_HOSTED` means the domain exists and is yours, but its nameservers point at another DNS provider, so there is no zone here to read. The second is **permanent until the customer re-delegates** and retrying can never succeed; on a Footprint-Free estate, where most names are registered elsewhere and merely pointed at us, it is the normal answer for most domains rather than an edge case. Both carry the identical message, deliberately, so that a caller who may not see the domain cannot tell the two apart by wording.\n\n**`?not_hosted=empty`** asks for the `DNS_NOT_HOSTED` case as an ordinary answer instead: `200` with `data: []`, `has_more: false` and `hosted: false`. The dashboard sends it because it reads this list on every domain page and whether we host a zone cannot be told from `delegation_state` (a delegated domain can still have no zone here). `NOT_FOUND` is unchanged by it: a domain you cannot see is still a `404`.","tags":["domains"],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"not_hosted","in":"query","required":false,"description":"`empty` answers a domain whose DNS we do not host with an empty page and `hosted: false` instead of the `DNS_NOT_HOSTED` 404.","schema":{"type":"string","enum":["empty"]}}],"responses":{"200":{"description":"A page of the domain's visible DNS records.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DnsRecordList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"502":{"$ref":"#/components/responses/VendorCredentialRejected"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}},"post":{"operationId":"createDnsRecord","summary":"Create a DNS record.","description":"Adds a record to the domain's hosted zone. Requires `domains.dns.manage`. On the Footprint-Free line an A/AAAA record (or a `CNAME` to an IP literal, which resolves to one) is refused with a 422 — those are platform-managed.\n\n**Adding an apex `MX` is not additive** (issue #622). MX preference is lowest-number-wins, so a new record at or below the best existing preference takes delivery away from the host the customer's mail reaches today, without removing its record. That is refused `409 MAIL_CHANGE_REFUSED` unless `confirm_mail_change=true`; a strictly higher preference number is an ordinary backup MX and is allowed, as is the first `MX` on a domain that has none.","tags":["domains"],"parameters":[{"$ref":"#/components/parameters/ConfirmMailChange"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DnsRecordWrite"}}}},"responses":{"201":{"description":"The created record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DnsRecord"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/MailChangeRefused"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"502":{"$ref":"#/components/responses/VendorCredentialRejected"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/domains/{domainId}/dns/soa":{"parameters":[{"$ref":"#/components/parameters/DomainId"}],"get":{"operationId":"getDnsSoa","summary":"Read a domain's zone SOA (read-only).","description":"The zone's start-of-authority record as its own authoritative nameservers serve it — the provider's nameserver pair when it has one (`ns1`/`ns2.zinndigital.com`), else the domain's delegation. Read-only: the provider owns the SOA and bumps its serial on every change, so it is never written through the record editor. Requires `sites.view`, RLS-scoped. `soa` is `null` only when there are no nameservers to ask; a read that could not be made is a `503`, never an empty answer.","tags":["domains"],"responses":{"200":{"description":"The zone's SOA.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DnsSoa"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/domains/{domainId}/dns/records/{recordId}":{"parameters":[{"$ref":"#/components/parameters/DomainId"},{"$ref":"#/components/parameters/RecordId"}],"put":{"operationId":"updateDnsRecord","summary":"Update a DNS record.","description":"Replaces the record `recordId` in the domain's hosted zone. Requires `domains.dns.manage`. A record hidden from the caller's product line (an A/AAAA on the Footprint-Free line) is indistinguishable from an absent one — a 404 — so it cannot be probed by id (register #93).\n\n**Repointing a live apex `MX` is refused** `409 MAIL_CHANGE_REFUSED` unless `confirm_mail_change=true` (issue #622) — it silently stops the customer's email reaching the mailboxes it reaches today, which is data loss rather than a configuration change. So is moving the only apex `MX` onto a subdomain: the record survives, the domain's mail does not. A change that alters only TTL or preference is not refused, because mail still arrives at the same host.","tags":["domains"],"parameters":[{"$ref":"#/components/parameters/ConfirmMailChange"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DnsRecordWrite"}}}},"responses":{"200":{"description":"The updated record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DnsRecord"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/MailChangeRefused"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"502":{"$ref":"#/components/responses/VendorCredentialRejected"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}},"delete":{"operationId":"deleteDnsRecord","summary":"Delete a DNS record.","description":"Removes the record `recordId` from the domain's hosted zone. Requires `domains.dns.manage`. As for update, a record hidden from the caller's line 404s rather than confirming it exists.\n\n**Deleting an apex `MX` is refused** `409 MAIL_CHANGE_REFUSED` unless `confirm_mail_change=true` (issue #622). It fires on *any* apex MX deletion, not only the last one — \"delete every MX one at a time\" is the failure mode, and by the time the last one goes three deletions have already happened. The message says whether the domain would stop receiving mail entirely or merely fall back to a remaining host.","tags":["domains"],"parameters":[{"$ref":"#/components/parameters/ConfirmMailChange"}],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/MailChangeRefused"},"429":{"$ref":"#/components/responses/TooManyRequests"},"502":{"$ref":"#/components/responses/VendorCredentialRejected"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/domains/{domainId}/email-routing":{"parameters":[{"$ref":"#/components/parameters/DomainId"}],"get":{"operationId":"getDomainEmailRouting","tags":["domains"],"summary":"Read a domain's inbound email routing, and what enabling it would cost.","description":"Cloudflare Email Routing on the customer's **own** account: whether it is on, the forwarding rules, the catch-all, the verified destination addresses, and the DNS the provider would publish to make it work.\n\nScoped to the domain rather than a site, because routing is a **zone-level** feature — one switch and one rule set per zone however many sites hang off it.\n\n`impact` is the important field. Email Routing's DNS plan is **apex-only**: turning it on republishes the apex `MX` set *and* an apex SPF `TXT`, so a domain whose mail is at Google Workspace or Microsoft 365 would lose it. `impact` compares the provider's own published plan against the zone's live records on every read, so what the customer is warned about and what the enable endpoint refuses are the same value and cannot drift.\n\n`impact.zone_unreadable` is reported separately from `impact.safe` because \"we could not read your DNS\" and \"your domain already receives mail elsewhere\" are both unsafe and need completely different copy. `addresses_readable` is likewise separate from an empty `addresses` list: a credential may legitimately lack the account-level scope, and \"we could not look\" must not render as \"there are none\". `rules_readable` is the same distinction for the forwarding rules, which sit behind a **different** Cloudflare permission again — so a partially-scoped token returns a usable `status`, `plan` and `impact` with the rule list honestly marked unreadable, rather than failing the whole read. Requires `sites.view`.\n\n⛔ A credential that lacks a required scope answers **422**, never 503: a permission gap is the one failure a retry can never clear, and telling a customer to \"try again shortly\" sends them round a loop with no exit (D16780).","responses":{"200":{"description":"The zone's routing state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainEmailRouting"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/domains/{domainId}/email-routing/enabled":{"parameters":[{"$ref":"#/components/parameters/DomainId"}],"post":{"operationId":"enableDomainEmailRouting","tags":["domains"],"summary":"Turn inbound email routing on for a domain.","description":"**This can destroy a customer's inbound mail.** Enabling republishes the zone's apex `MX` and SPF, so any mail service the domain already uses stops receiving.\n\nThe endpoint therefore refuses with `409 MAIL_WOULD_BE_REPLACED` when the zone carries mail records that are not the provider's own, and the override is **typed, not clicked**: `confirm_domain` must be the domain's own name. A boolean would be settable by a client that never showed the customer anything.\n\nThe judgement runs on a confirmed call as well as a refused one, so the override is audit-logged with the same evidence as the refusal — otherwise the one case that actually replaced live mail would be the one case with no record of what was there.\n\nA zone that cannot be read is a refusal, never a pass. Requires `domains.dns.manage`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainEmailRoutingEnable"}}}},"responses":{"200":{"description":"Routing is on; the zone's state as read back.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainEmailRouting"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Enabling would replace the mail records this domain already uses. The body's `details` name the `MX` hosts that would be lost. Retry with `confirm_domain` set to the domain name to proceed anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}},"delete":{"operationId":"disableDomainEmailRouting","tags":["domains"],"summary":"Turn inbound email routing off for a domain.","description":"Ungated, deliberately: turning routing off gives the customer their mail back rather than taking it, and gating an exit is how a customer gets stuck. Requires `domains.dns.manage`.","responses":{"200":{"description":"Routing is off; the zone's state as read back.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainEmailRouting"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/domains/{domainId}/email-routing/rules":{"parameters":[{"$ref":"#/components/parameters/DomainId"}],"post":{"operationId":"createDomainEmailRoutingRule","tags":["domains"],"summary":"Add a forwarding rule.","description":"Forward mail for one address to one or more verified destinations, or drop it. `drop` is a chosen behaviour and is never inferred from an empty destination list. Requires `domains.dns.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainEmailRoutingRuleWrite"}}}},"responses":{"200":{"description":"The rule as the provider stored it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainEmailRoutingRule"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/domains/{domainId}/email-routing/rules/{ruleId}":{"parameters":[{"$ref":"#/components/parameters/DomainId"},{"$ref":"#/components/parameters/EmailRoutingRuleId"}],"put":{"operationId":"updateDomainEmailRoutingRule","tags":["domains"],"summary":"Change a forwarding rule.","description":"Requires `domains.dns.manage`. The catch-all is a separate resource at the provider and cannot be changed through this path — use `PUT .../email-routing/catch-all`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainEmailRoutingRuleWrite"}}}},"responses":{"200":{"description":"The rule as the provider stored it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainEmailRoutingRule"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}},"delete":{"operationId":"deleteDomainEmailRoutingRule","tags":["domains"],"summary":"Remove a forwarding rule.","description":"Requires `domains.dns.manage`.","responses":{"204":{"description":"The rule was removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/domains/{domainId}/email-routing/catch-all":{"parameters":[{"$ref":"#/components/parameters/DomainId"}],"put":{"operationId":"setDomainEmailRoutingCatchAll","tags":["domains"],"summary":"Set what happens to mail matching no other rule.","description":"The catch-all is a separate resource at the provider and cannot be deleted, only set to `drop`. Requires `domains.dns.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainEmailRoutingCatchAllWrite"}}}},"responses":{"200":{"description":"The catch-all as the provider stored it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainEmailRoutingRule"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/domains/{domainId}/email-routing/addresses":{"parameters":[{"$ref":"#/components/parameters/DomainId"}],"post":{"operationId":"createDomainEmailRoutingAddress","tags":["domains"],"summary":"Register a destination address.","description":"**This sends mail to a third party.** The provider emails the address a verification link and will not deliver anything to it until the recipient clicks, so the response carries `verified: false` rather than pretending the destination is usable.\n\nDestination addresses are **account-scoped** at the provider, not zone-scoped: one address book serves every domain on the account. Requires `domains.dns.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainEmailRoutingAddressWrite"}}}},"responses":{"200":{"description":"The address as registered, pending the recipient's verification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainEmailRoutingAddress"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/domains/{domainId}/email-routing/addresses/{addressId}":{"parameters":[{"$ref":"#/components/parameters/DomainId"},{"$ref":"#/components/parameters/EmailRoutingAddressId"}],"delete":{"operationId":"deleteDomainEmailRoutingAddress","tags":["domains"],"summary":"Remove a destination address from the account.","description":"Account-scoped: removing an address removes it for every domain on the provider account, not only this one. Requires `domains.dns.manage`.","responses":{"204":{"description":"The address was removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/domains/{domainId}/nameservers":{"parameters":[{"$ref":"#/components/parameters/DomainId"}],"get":{"operationId":"getNameservers","summary":"Get a domain's nameservers.","description":"The domain's current delegation (last-known set). Requires `sites.view`, RLS-scoped. Empty when the pair we hold for a domain that is not delegated to us serves no zone any more (D43760, `Delegation.expected_ready: false`): a dead pair is shown nowhere.","tags":["domains"],"responses":{"200":{"description":"The domain's nameservers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Nameservers"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setNameservers","summary":"Set a domain's nameservers.","description":"Re-delegates the domain via its registrar. Requires `domains.dns.manage`. Only a domain registered with us can be re-delegated here (a connected/BYO domain's nameservers live at the customer's own registrar) — otherwise a 409. The new nameservers are asked for the domain first: when they answer for the zone (SOA) but publish no address at the apex (no A, AAAA or CNAME), the move would take the domain dark, so it is refused with a 409 `refusal.dns.nameserversPublishNoApex` naming what is missing. Send `force: true` to move anyway. A nameserver set that cannot be asked yet (a zone not active) is not refused.","tags":["domains"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Nameservers"}}}},"responses":{"200":{"description":"The applied nameservers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Nameservers"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/domains/{domainId}/glue":{"parameters":[{"$ref":"#/components/parameters/DomainId"}],"get":{"operationId":"listDomainGlue","summary":"List the glue records the registry holds for nameservers inside this domain.","description":"TKT13577 (docs/845 §11). Read from the registry through the domain's registrar on every call (no mirror). Requires `sites.view`. Only a domain registered with us (409 otherwise, and 409 `refusal.dns.glueUnsupported` when its registrar cannot manage glue).","tags":["domains"],"responses":{"200":{"description":"The glue records.","content":{"application/json":{"schema":{"type":"object","required":["glue"],"properties":{"glue":{"type":"array","items":{"$ref":"#/components/schemas/GlueRecord"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}},"put":{"operationId":"setDomainGlue","summary":"Create or replace the glue record for one nameserver inside this domain.","description":"Requires `domains.dns.manage`. `host` must be strictly inside the domain (e.g. `ns1.example.com` for `example.com`); at least one of `ipv4`/`ipv6`, each a public unicast address (private, loopback, link-local, reserved, documentation and multicast addresses are refused with 422). Answers with the record as READ BACK from the registry. Audit-logged (`domain.glue.set`).","tags":["domains"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlueRecord"}}}},"responses":{"200":{"description":"The glue record as the registry now holds it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlueRecord"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/domains/{domainId}/glue/{host}":{"parameters":[{"$ref":"#/components/parameters/DomainId"},{"name":"host","in":"path","required":true,"description":"The nameserver host inside the domain, e.g. `ns1.example.com`.","schema":{"type":"string","maxLength":253}}],"delete":{"operationId":"deleteDomainGlue","summary":"Remove the glue record for one nameserver inside this domain.","description":"Requires `domains.dns.manage`. Refused with 409 `refusal.dns.glueInUse` while the domain's nameservers still name the host. Confirmed by reading the registry back. Audit-logged (`domain.glue.delete`).","tags":["domains"],"responses":{"200":{"description":"Removed from the registrar (confirmed by reading its list back). `registry` is what the registry's RDAP publishes NOW — measured 2026-10-19, it can keep publishing a host the registrar deleted.","content":{"application/json":{"schema":{"type":"object","required":["host","registry"],"properties":{"host":{"type":"string"},"registry":{"$ref":"#/components/schemas/GlueRegistryState"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/domains/{domainId}/nameservers/resync":{"parameters":[{"$ref":"#/components/parameters/DomainId"}],"get":{"operationId":"getDomainNameserverResync","summary":"Who can move this domain's nameservers, and what the last resync concluded.","description":"W43-79 (docs/719). Answered from our own records with no call to any registrar, so a screen may render it on every load. `holder` says whether a resync is possible at all: `zinn` (registered with us), `locked` (a route that keeps its own nameservers), a linked registrar vendor such as `godaddy`, `connected_unknown` (a registrar is connected but no import has placed this domain in it yet), or `none`. Requires `sites.view`, RLS-scoped.","tags":["domains"],"responses":{"200":{"description":"The resync state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainNameserverResync"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"resyncDomainNameservers","summary":"Point this domain's nameservers at its site — or at our DNS — now.","description":"Starts a durable resync (a Temporal workflow) that re-derives the nameservers the domain's site needs from the DNS provider actually holding its zone, and sets them at the registrar — ours, or the customer's connected one. Returns `202`; the outcome lands on `last_outcome` a few seconds later.\n\nA domain with **no site** (docs/844) is \"use our nameservers\": when we hold no zone for it (`has_zone: false`) the press PREPARES one on our DNS with a copy of what the domain publishes today and changes nothing at the registrar (`last_outcome: zone_prepared`), so the records can be checked first; when we do, the press delegates the domain to the nameservers that zone reports. `409` when no credential we hold can move it (`holder` `none` or `locked`). Requires `domains.dns.manage`.","tags":["domains"],"responses":{"202":{"description":"The resync was started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainNameserverResync"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/domains/{domainId}/disconnect":{"parameters":[{"$ref":"#/components/parameters/DomainId"}],"delete":{"operationId":"disconnectDomain","summary":"Stop hosting a connected domain's DNS, and delete its zone.","description":"The other half of `connectDomain`, and not optional: a create with no delete is how an estate fills with dead zones — config nobody serves, still counting against a provider's zone cap and indistinguishable from live config later.\n\nRemoves the zone at the DNS provider, releases the provider-account placement so the pool stops counting it, then deletes the row and emits `domain.disconnected`. ⛔ **Not `domain.deleted`** (W42-R): that event renders to the customer as a registry release — *\"it is no longer yours, anyone may now register it\"* — which is a statement about a registration **we held**. Stopping DNS hosting for a name somebody else registered is a statement about our service, and the two were one event until 2026-09-09. **The zone goes first**: if the provider call fails this is a `503` and nothing is changed, because deleting the row first would strand the zone with nothing left pointing at it. A zone already absent at the provider is a success, not an error — otherwise a row could exist that nobody can ever remove.\n\n⛔ Only a **connected** domain. One registered with us is held at a registrar with a renewal cycle attached, so removing it here would orphan the registration rather than end it — that is the transfer-out/expiry lifecycle. Attempting it is a `409`. Requires `domains.dns.manage`.","tags":["domains"],"responses":{"204":{"description":"The domain was disconnected and its zone deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/domains/{domainId}/delegation":{"parameters":[{"$ref":"#/components/parameters/DomainId"}],"get":{"operationId":"getDomainDelegation","summary":"Whether a domain's delegation actually points at us.","description":"The honest answer to \"is my domain live yet?\". `expected` is the delegation we ask the customer to set, `nameservers` is where the domain **actually** delegates right now, and `detected` says whether those agree.\n\n⛔ `detected` is resolved from a **public recursive resolver**, not from the DNS vendor. Bunny's own `NameserversDetected` flag was measured returning `true` for a domain that is not registered at all, so a surface keyed off it tells a customer their domain is served before they have touched their registrar (docs/72 D243).\n\nA lookup that FAILED is a `503`, never `detected: false`: \"not live yet\" and \"we could not check\" lead a customer to opposite actions. A domain whose authoritative DNS we do not host is a `404`. Requires `sites.view`, RLS-scoped.\n\nThe answer is **recorded**, not recomputed per request, so this read is cheap enough to poll — a background backoff poller keeps it fresh (see `POST`). A live lookup that fails on a domain last seen delegated leaves the recorded state alone, so the `503` now means *we have never established this domain's delegation* rather than *this one lookup failed*.","tags":["domains"],"parameters":[{"name":"not_hosted","in":"query","required":false,"description":"`no_content` answers a domain whose DNS we do not host with a `204` instead of the `DNS_NOT_HOSTED` 404. A domain outside the caller's scope is still a 404.","schema":{"type":"string","enum":["no_content"]}}],"responses":{"200":{"description":"Where the domain's delegation points.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Delegation"}}}},"204":{"description":"Only with `not_hosted=no_content`: we do not host this domain's DNS, so there is no delegation to report."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"post":{"operationId":"recheckDomainDelegation","summary":"Check the delegation again now, and restart the fast poll.","description":"Forces a live lookup regardless of how recently one ran, records it, and restarts the **backoff ladder** — 30-second checks for the next ten minutes, then 2 minutes, 15 minutes, hourly, giving up after 7 days.\n\nThe customer pressing \"Check again\" tells us the one thing we cannot otherwise know: they have just changed their nameservers at the registrar. That is exactly the window in which the answer is about to change, so it is the window worth checking aggressively.\n\nSame body and same status codes as the `GET`. Requires `sites.view`, not `domains.dns.manage`: it changes nothing about the domain — it reads the public internet and writes down what it saw — and gating it behind a management permission would leave a read-only user watching a page that can never refresh.","tags":["domains"],"responses":{"200":{"description":"The freshly-taken reading.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Delegation"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/domains/{domainId}/delegation/fresh-nameservers":{"parameters":[{"$ref":"#/components/parameters/DomainId"}],"post":{"operationId":"refreshDomainNameservers","summary":"Get a working nameserver pair again when the one we gave has expired.","description":"D43760. When the pair we hold for a domain serves no zone for it (`expected_ready: false`; the DNS provider dropped a zone nobody activated), this re-creates the domain's zone with our copy of its records and answers the `Delegation` carrying the NEW pair. Refused with `409` when the domain is delegated to us or its pair still works: a working zone is never replaced. Requires `domains.dns.manage`, because it creates a zone at the DNS provider.","tags":["domains"],"responses":{"200":{"description":"The reading after the zone was re-created, with the new pair.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Delegation"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/domains/{domainId}/registry":{"parameters":[{"$ref":"#/components/parameters/DomainId"}],"get":{"operationId":"getDomainRegistry","summary":"What the public registry says about a domain (the WHOIS card).","description":"Registration dates, the registrar, the EPP status set and the DNSSEC flag, read from the registry's own **RDAP** service — the structured replacement for port-43 WHOIS.\n\n⭐ **This answers for a domain registered somewhere else.** RDAP needs no credential, so a domain a customer registered at a registrar we have never integrated still returns its real expiry date and transfer lock. `GET /v1/domains/{domainId}` cannot: those columns are our own mirror of a registrar API, and for a connected (non-`registered`) domain we hold no account to mirror from, so they are empty and stay empty. Two sources, two endpoints, neither pretending to be the other.\n\n⛔⛔ **Every field is nullable, and `null` means the registry did not publish it — never that the domain lacks it.** `transfer_locked: null` is \"we did not read a status set\", not \"unlocked\"; rendering it as unlocked tells a customer to go and protect a domain that is already protected. `dnssec: null` is the same shape.\n\n⛔ No registrant, admin or technical contact is returned, by decision: most registries redact them post-GDPR, and republishing the ones that do not would export personal data through our UI for no product reason.\n\nA registry that does not answer is a `503`, never an empty body and never a `404` — \"the registry is quiet\" and \"this domain is not registered\" are different facts and RDAP cannot reliably tell them apart (a stale bootstrap map 404s from the wrong registry). Requires `sites.view`, RLS-scoped; a domain the caller cannot see is a `404`.","tags":["domains"],"responses":{"200":{"description":"The registry's current record for the domain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistryProfile"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/rename-domain":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteRenameStatus","summary":"What a site's running domain change is waiting for.","description":"Reads the site's rename saga. `waiting_for` is the new domain the saga is waiting to see pointed at the site (null when no change is waiting — none running, or one past its DNS wait), and `dns_record` is the record to add at the customer's DNS provider (null when nothing is waiting). The saga switches on its own as soon as the name reaches the site; nothing needs pressing again. `waiting_for_certificate` is the new domain while the saga secures its certificate: the site goes on serving its current address, with its current certificate, until the box presents one covering the new name, and only then switches. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The rename's waiting state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteRenameStatus"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"post":{"operationId":"renameSiteDomain","summary":"Change a site's primary domain (asynchronous).","description":"Starts the durable **rename-domain** saga for a site (new-side setup → flip → old-side teardown, register #91). Returns `202 Accepted` immediately — the work runs as a Temporal workflow; poll the site or subscribe to `site.*` events for completion. Requires `sites.create` (the same authority that provisions a site). Idempotent on the site: a repeat call while the saga is running is accepted and does not start a second run. ONE STEP for any site (whatever its current name): when the new name does not reach the site yet the reply is `status: waiting_for_dns` with the `dns_record` to add, and the saga waits (checking every minute, then every ten, for at most seven days) before switching, so the working address never breaks. A name on our preview domain starts at once; a name more than one label under a domain we own (`www.<name>.<preview domain>`) is refused with `422` and `refusal.rename.nameTooDeepForFreeAddress`, because no certificate on the estate can serve it. A different name while it waits retargets that run (its prepared zones are undone); `in_progress` means a run already past its DNS wait finishes first. A name in a zone the SAME org holds on our DNS, delegated to us, whose target carries only the holder page needs no record: the saga points it itself (apex and `www`) through that domain's own DNS placement, and its undo puts the holder page back (s1014 F10).","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenameDomainRequest"}}}},"responses":{"202":{"description":"The rename saga was accepted and started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenameDomainAccepted"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"delete":{"operationId":"cancelSiteRename","summary":"Cancel a domain change that is still waiting.","description":"Cancels the site's rename saga while it is still WAITING — for the new name to be pointed at the site (`waiting_for`) or for its certificate (`waiting_for_certificate`). The saga undoes the zones it prepared for the new name and ends; the site stays on its current address, which never stopped working. Returns `202 Accepted` with `status: cancelling` — the undo runs in the saga, so read `getSiteRenameStatus` until nothing is waiting. `409` with `refusal.rename.nothingToCancel` when no change is waiting (none running, or one already past its wait and finishing — it cannot be stopped half-way). Writes the `site.domain.rename_cancelled` audit row. Requires `sites.create` (the same authority that starts a change).","tags":["hosting"],"responses":{"202":{"description":"The cancel was sent to the waiting change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenameCancelAccepted"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/mail-smtp":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteMailSmtp","summary":"Get the site's own SMTP server for website mail.","description":"By default a site's website mail (WordPress `wp_mail()`, PHP `mail()`, contact forms, WooCommerce receipts) leaves through our mail relay as the site. A customer may instead send it through their OWN SMTP server (Google Workspace, Microsoft 365, their host). Returns `configured: false` when none is saved. **The password is never returned.** `status`: `unverified` (saved, not proven yet), `active` (proven from the site's server and in use), `failing` (the site's server could not log in; the site keeps sending through our relay meanwhile). `last_error` is a code — `auth`, `tls`, `unreachable`, `unsupported`, `password_unreadable`, `server`. Requires `mail.view`.","tags":["mail"],"responses":{"200":{"description":"The site's own SMTP server settings, or `configured` false.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMailSmtp"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setSiteMailSmtp","summary":"Save (and prove) the site's own SMTP server.","description":"Saves the settings — the password goes to the secret store and is write-only; omit it to keep the stored one (required the first time) — then proves the server FROM THE SITE'S SERVER, as the site (encrypted connection + login, nothing sent). Only a successful proof switches the site's mail to it; otherwise the site keeps sending through our relay and `status` is `failing` with the reason. Ports 587/2525 (STARTTLS), 465 (SSL/TLS) or 25. Requires `mail.manage`.","tags":["mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMailSmtpUpdate"}}}},"responses":{"200":{"description":"Saved; the body says whether it is now in use.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMailSmtp"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"deleteSiteMailSmtp","summary":"Stop using the site's own SMTP server.","description":"Removes the settings and the stored password and puts the site's website mail back on our relay at once. Idempotent. Requires `mail.manage`.","tags":["mail"],"responses":{"204":{"description":"Removed; the site sends through our relay."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/mail-smtp/test":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"testSiteMailSmtp","summary":"Prove the saved SMTP server again now.","description":"Proves the saved server from the site's server again and applies the result (in use, or back to our relay). `404` when none is saved. Requires `mail.manage`.","tags":["mail"],"responses":{"200":{"description":"The settings with the fresh result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMailSmtp"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/upgrade-to-php":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"upgradeSiteToPhp","summary":"Upgrade a static HTML site to PHP hosting, in place.","description":"A static HTML site becomes a PHP site IN PLACE, with no downtime (owner brief, queue Q111). On our servers every site's web server already runs PHP, so nothing is copied, re-placed or re-pointed: the site's stack becomes `php`, its PHP version the plan's default (or `php_version`, when the plan offers it) and the PHP tuning follows in the next maintenance pass. `422` with `details[].code` `SITE_NOT_STATIC` (already PHP, WordPress or another stack), `SITE_NOT_ACTIVE` (still setting up), `STATIC_ON_EDGE_HOST` (published to an edge host that cannot run PHP: move it onto our servers first) or `PHP_VERSION_NOT_OFFERED`. Audited as `hosting.site.upgrade_to_php`. An out-of-scope or unknown id is a `404`. Requires `hosting.php.manage`.","tags":["hosting"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteStackUpgradeRequest"}}}},"responses":{"200":{"description":"The site, now PHP.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteStackUpgrade"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/sites/{siteId}/php-version":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSitePhpVersion","summary":"Get a site's PHP version.","description":"Returns the site's current PHP version and `available` — the versions it may switch to (those offered for its product line, plus its own current version even if that has since been retired, so a grandfathered selection is still shown). RLS-scoped; an out-of-scope or unknown id is a `404`. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The site's PHP version and the versions it may switch to.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePhpVersion"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setSitePhpVersion","summary":"Switch a site's PHP version.","description":"Sets the site's desired PHP version and returns `202 Accepted`. The target must be a version currently offered for the site's product line (or the site's own current version); anything else is a `422`. A retired version an existing site already runs is kept — this call never forces a migration. Requires `hosting.php.manage`.\n\n**The machine serving the site is told before the row is written**, on both lines: one ack-checked vendor call on the resold range, and one idempotent `cloudlinux-selector set --current-version=` on our own fleet. A version the machine refuses is a `422` and the row is left alone, so the platform never claims a runtime the box is not running. `202` therefore under-promises rather than over-promises.\n\nA site with no hosting vendor and no placed worker has nothing serving it yet: the desired version is recorded and provisioning applies it.\n\n**The site's PHP extensions move with it.** The PHP selector keeps extensions per version, so once the machine confirms the switch, the site's composed extension set is pushed for the new version: the platform floor, the customer's own toggles, and whatever its one-click application needs. Without this, a site landed on the new version's default set; a Drupal site answered 500 on every page with no `dom` (D24906). If that push fails, the switch still stands, and the hourly PHP-settings converge pushes the set on its next pass.\n\nA machine that cannot be **reached at all** — its account does not exist yet, SSH is down, the vendor is unavailable — is a `503`, not a `422` and not a `500`: the request was valid and a retry can succeed. The stored version is left exactly as it was, so a `503` here means nothing changed anywhere.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePhpVersionUpdate"}}}},"responses":{"202":{"description":"The new desired PHP version was accepted; apply is pending.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePhpVersion"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/hosting/locations":{"get":{"operationId":"listHostingLocations","summary":"List the data centres a new site may be created in.","description":"Every data centre a new site may be placed in: the regions of our own fleet that currently have a worker able to take the site — active, accepting deploys, not full, serving the line, in the pool its sites are placed in. ⚖️ Owner ruling 2026-09-22: only regions with real fleet capacity are offered, so the managed-range (resold) locations this endpoint also returned until then are no longer offered. The same list, with city and name key, is `listHostingRegions`. The answer carries no tenant scope; it is authenticated only because it describes our estate rather than being marketing copy.\n\nAn empty list is a real answer, not an error: nothing is activated and no fleet worker can take the site, a managed-range location could not be pinned with the configuration present, or the line is one we do not offer a choice on. The client must then hide the picker and let the default placement apply — it must never substitute a list of its own, because creating a site in a location we have not activated is refused by the vendor after the customer has chosen, and a fleet region with no box behind it fails in placement for the same reason.\n\n`code` is the placement identifier (`lhr`, `nbg1`) and the suffix of the i18n key the client renders; `country` is ISO-3166 alpha-2 for a decorative flag. There is deliberately **no display name** — location names are translated like every other user-facing string, and a flag is never the accessible name.","tags":["hosting"],"parameters":[{"name":"product_line","in":"query","required":false,"description":"Narrow the answer to the lines a site of this product line could be placed on. A fleet region is offered only when a worker **serving this line** has capacity, and the footprint-free line is offered no choice at all — its sites are placed on EU boxes by the balancer and the customer is not asked.\n\nOmitting it returns the un-narrowed union, which is what a caller naming the data centre of an **existing** site needs: there is no line to pass, and an empty list would blank a location the customer already has.","schema":{"type":"string","maxLength":64}}],"responses":{"200":{"description":"The activated data centres, in the platform's configured order.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DataCentreLocation"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/preview-urls":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSitePreviewUrls","summary":"Get the URLs at which a site can be viewed before its DNS resolves.","description":"How a customer sees their site **before** they point their domain at us — the \"temporary URL\" the product has advertised on both lines since the first feature matrix (docs/37) and the import flow tells them to use (\"Check it over, then point your domain at us\"). Requires `sites.view`.\n\nEvery hostname is **read from the hosting platform, never derived**: they are not uniformly `<label>.<preview-domain>` and a formula produces confidently wrong links (one live package answers with a datacentre label in the middle of the hostname).\n\n`vendor_branded` marks a URL whose hostname is not under our configured preview domain — a docs/62 §3.7 breach. Such a URL is reported so staff can see it, and **must not be offered to a customer** by any client.\n\nA site with no preview URL returns `200` with an empty `urls` and a machine-readable `unavailable_reason` — that is an answer, not an error. ⛔ A fleet site is deliberately **not** a `404` here, unlike the `/hosting/*` reads: a vendor package is a property of the vendor, so a site without one has no such resource, but a preview URL is a property of the site and the reason it has none is something the customer is owed.\n\nSince W41-L a site on **our own fleet** has a real preview address of its own, minted under our preview domain and served over HTTPS, so `unsupported_driver` no longer describes the fleet. The reasons now mean: `not_needed` — the site is already reachable at its own address, which is the answer once the customer's domain points at us (⚖️ owner, 2026-09-08: *\"no one needs a preview url for something that is already pointing to us\"*); `none_issued` — the address is decided but not yet published, or a resold package's temporary URL is switched off; `unsupported_driver` — the site runs somewhere this platform cannot mint one, such as an edge host.\n\n⭐ A platform preview address is a **converged state, not an issuance**: it is withdrawn a fortnight after the customer's own domain starts reaching us, and it comes **back** on its own if their DNS later moves away again. `platform` and `retires_at` on each URL are what a client needs to say which of those is true.","tags":["hosting"],"responses":{"200":{"description":"The site's preview URLs, or the reason it has none.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePreview"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/quota":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteQuota","summary":"Get a site's enforced disk and inode ceilings, and its usage against them.","description":"The limits the platform **actually enforces** on this site and what it is using against them. On our own fleet the disk and inode caps are a real, kernel-enforced `setquota` applied at provision time (ADR 0013 §5), and until this endpoint they were applied and exposed nowhere — a site could hit an inode or disk cap and the customer's only signal was writes beginning to fail.\n\nEvery field is nullable and each `null` is meaningful. A `null` **limit** means no ceiling is enforced — never \"unlimited\" as a selling point and never \"we did not look\". `db_limit_mb` is `null` on every box we operate: MySQL Governor is not installed and an account's MySQL datadir lives outside its home, so no quota reaches it; database size is therefore reported as usage with no cap rather than a limit we do not apply.\n\nA site whose platform reports no ceilings at all answers `200` with every field `null`, **not** `404` — \"we do not cap this\" is a real answer. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The site's enforced ceilings and its usage against them.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteQuota"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/quota/resources":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteQuotaResources","summary":"What this site is allowed per resource, what it is using, and what more costs.","description":"The **lifecycle** view, where `GET /v1/sites/{siteId}/quota` is the live read of what the box is enforcing right now. Owner ruling 2026-08-16: a plan grants **site slots**; disk, inodes, bandwidth and database size (W43-78) are **per-site** resources with an admin-set default and a paid per-site upgrade.\n\nEach entry decomposes the allowance into `base` (the site's own copied default), `granted` (live grants — staff gestures and purchased upgrades) and `total`, because a card showing only the total cannot explain why the number changed when a grant expired. `reverts_at` is when the ceiling next **drops** because a temporary grant ends, so a customer learns before it happens rather than after.\n\n`measured_at` is surfaced deliberately: a bar drawn from a two-day-old reading looks identical to one drawn from a fresh reading, and `null` means nothing has ever measured this site. `price_minor` is `null` when no price is published in the caller's currency, and the client must then offer **no upgrade control** rather than one that cannot complete.\n\nOnly resources this site's driver can actually enforce are listed. On a managed shared package the disk ceiling belongs to the package *type* and an inode limit does not exist at any level, so the list is empty there — the control is absent rather than inert. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The site's per-resource allowances, usage and prices.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteQuotaResources"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/quota/resources/{resource}/upgrade":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"$ref":"#/components/parameters/QuotaResourceName"}],"post":{"operationId":"upgradeSiteQuotaResource","summary":"Buy more disk or file allowance for one site.","description":"Raises this site's ceiling by `steps` purchasable steps (1 GB of disk, 50,000 inodes) and applies it to the box. Recorded as an open-ended grant rather than by editing the base, so *what the site started with* and *what the customer bought* stay separately revocable.\n\n⛔⛔ **The charge is created BEFORE the ceiling is raised, and an upgrade that cannot be charged for is refused with `422` — no grant, nothing on the box.** Both refusals answer `422` and the body distinguishes them: no published price in the caller's currency, or no way to take the payment. Free capacity on a real box is the failure no customer reports, because they received what they asked for. An org with no way to pay at all (no usable stored payment method and no crypto election) is refused with `422` `refusal.siteQuota.noPaymentMethod` before anything is created: the upgrade renews monthly through the unattended ad-hoc sweep, which could never collect it. Spendable account credit that pays the first period INCLUDING tax (taxed exactly as the sweep will tax it) is a way to pay; credit covering only the pre-tax price is not. Credit must also cover everything it is already promised to: this upgrade is taxed together with the org's other ad-hoc items due in that currency, and every unpaid order the billing sweeps settle from that credit in that currency (ad-hoc orders, subscription renewals and final overage invoices) is added, so a second upgrade, or an upgrade beside a pending renewal, on credit that pays only one of them is refused. The check and the charge are serialised per organisation.\n\nCharge-then-apply is deliberate: a charged-but-unapplied upgrade is repaired by the ten-minute reconciler, and free capacity is repaired by nobody. An upgrade also **lifts a quota freeze immediately**, because paying is the remedy and waiting for a sweep would be the worst minute of the product to leave to a schedule.\n\nRequires `sites.view` **and** `hosting.quota.manage` — an upgrade commits the organisation to a recurring charge, which is a money authority rather than a hosting one.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteQuotaUpgradeRequest"}}}},"responses":{"201":{"description":"The resource's new allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteQuotaResource"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/quota/resources/{resource}/downgrade":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"$ref":"#/components/parameters/QuotaResourceName"}],"post":{"operationId":"downgradeSiteQuotaResource","summary":"Reduce a site's allowance — refused while the site is over the target.","description":"Owner ruling: downgrades are allowed **only when the site is not over the limit**. The check is made against a **live** reading of the box, not a stored sample: a downgrade is an irreversible narrowing the customer meets at their next write, so an hour-old figure could license one that is already breached.\n\n⛔ An **unreadable** usage is a refusal, not a pass. If the box cannot be measured the request answers `422`; \"we could not tell, so we allowed it\" is how a customer ends up above a ceiling they did not choose.\n\nThe `422` body names the real numbers — *\"This site is using 1.90 GB of disk, which is more than the 1.00 GB you asked for\"* — because a customer told only \"you cannot reduce this\" files a ticket, and one told the figures deletes something. Purchased grants for the resource are revoked so the ceiling **is** the number asked for; staff gestures are deliberately left alone. Requires `sites.view` and `hosting.quota.manage`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteQuotaDowngradeRequest"}}}},"responses":{"200":{"description":"The resource's new allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteQuotaResource"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/hosting/fleet-applications":{"get":{"operationId":"listFleetApplications","summary":"List the applications we install ourselves on our own fleet.","description":"The own-fleet counterpart of `GET /v1/hosting/applications`, and deliberately a separate operation rather than a flag on it, because the two answer different questions from different authorities. That one reports what the **resold platform's** installer offers and is read live from the vendor. This one reports what **we** have written an installer for, which is a fact about this platform at this release — Nextcloud, ownCloud, the headless-CMS choice (docs/139) and the PHP applications of the `php_app` stack: Drupal, Joomla, Moodle, PrestaShop and the rest of the application range (docs/681).\n\nAuthenticated but not tenant-scoped: like the locations and applications endpoints it is a statement about what this platform sells, and the create-site form needs it at the one moment no site exists to read it from.","tags":["hosting"],"parameters":[{"name":"stack_type","in":"query","required":false,"schema":{"$ref":"#/components/schemas/StackType"},"description":"Narrow to the applications that answer one stack. `headless_cms` returns the CMS choice and `php_app` the PHP application choice; `nextcloud` and `owncloud` return exactly one entry each, because for those the stack *is* the application. Omitted returns all of them."}],"responses":{"200":{"description":"The own-fleet applications.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FleetApplication"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/application-access":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteApplicationAccess","summary":"How to sign in to the application installed on a site (no password).","description":"Everything a customer needs to find their way in to the Moodle, Nextcloud, ownCloud, Joomla or headless CMS we installed for them: the application's name, where to sign in and the administrator username, plus whether a password can be revealed.\n\n⛔ **This read never carries the password and is not audit-logged** (docs/72 D52510). It is safe to call to render a \"Sign in to Moodle\" style button. The password is returned only by `revealSiteApplicationPassword`, which is the one audited call. `can_reveal` is `false` when there is nothing to reveal: either the deployment has no master key configured, or the customer changed the password themselves (`is_custom`), and the screen must say which rather than offer a reveal that produces a blank.","tags":["hosting"],"responses":{"200":{"description":"The sign-in details, without the password.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationAccess"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/application-access/reveal":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"revealSiteApplicationPassword","summary":"Reveal the administrator password of the application installed on a site.","description":"Returns the administrator password of the one-click application on this site. The password is **derived, never stored** (`engine.hosting.site_secrets`, the same design as `GET /v1/sites/{siteId}/wp-credentials`), and the response is `no-store`.\n\nA `POST` deliberately, despite reading: revealing a credential must not be something a page load, a prefetch or a cache can trigger. Each reveal is audit-logged as `site.application_credentials_viewed` with the real actor — and nothing else writes that row, so it answers \"who looked at this password\" truthfully. Requires `sites.view` and `sites.panel_access` in the site's organisation. **409** when `can_reveal` is false (the customer set the password, or none can be shown); no audit row is written then.","tags":["hosting"],"responses":{"200":{"description":"The administrator password.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationPassword"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/application-access/sign-in":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"signInSiteApplication","summary":"One-click sign-in to the application installed on a site.","description":"Mints a single-use, ~2-minute sign-in link for the site's application administrator (AbanteCart, Concrete CMS, Craft, Dolibarr, Drupal, Joomla, Matomo, Mautic, MediaWiki, MODX, Moodle, Nextcloud, OpenCart, osTicket, ownCloud, Payload, phpBB, Piwigo, PrestaShop, Silverstripe, Strapi, SuiteCRM, TYPO3 and Zenphoto; `can_sign_in` on `getSiteApplicationAccess` says which, and docs/139 §6a says why the others have none). The token is signed with a key derived for this site alone and is checked, spent and exchanged for the application's own session by `zinn-login.php` on the site (docs/139 §\"One-click sign-in\"). For a Node application (Strapi, Payload) the URL is `https://<domain>/zinn-login#t=<token>`: the token is in the fragment, which the browser never sends to a server, and the page at `/zinn-login` posts it. A Node site deployed before that page existed has its managed startup file brought up to date and its application restarted by this call (only when the file changed; never by the hourly converge), so the first click on such a site can take a little longer. Before minting, the platform makes sure that file and the site's key are on the server (idempotent). Requires `sites.view` and `sites.panel_access` in the site's organisation, like the password reveal. Each link is audit-logged as `site.application_sign_in` with the real actor, before it is returned. Refusals carry a `code` in `details[].code` (field `site`): `APP_SSO_UNSUPPORTED` (409, no sign-in for this application), `SITE_NOT_SERVING` (409), `PLATFORM_CANNOT_SSO` (422, the hosting platform has no shell), `REPAIR_FAILED` (503, the sign-in could not be prepared on the server); none of them writes an audit row.","tags":["hosting"],"responses":{"200":{"description":"The sign-in link.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"Always `no-store`."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationSignIn"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/wp-login":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"wpLogin","summary":"Mint a one-click WordPress admin login token.","description":"Returns a short-lived, signed SSO token (and the URL that carries it) for one-click sign-in to the site's `wp-admin` (V1 parity). The customer's browser is sent to the URL; the Zinn® plugin on the site verifies the token, enforces single-use, and establishes the wp-admin session. The token is bound to this site, expires in ~2 minutes, and its issuance is audit-logged with the real actor. Requires `sites.wp_login`. Only WordPress/WooCommerce sites that are **serving** are eligible (422 / 409 otherwise); if one-click login is not configured on the platform the endpoint returns 503 and mints nothing.\n\n⛔⛔ **A `201` from this endpoint is a claim about the SITE, not merely about the signature, and it did not used to be.** Minting is local, cheap and always succeeds; every reason a grant cannot work lives on the box. Before the preflight below existed this endpoint answered `201` with a correctly-signed URL for a site whose WordPress had no SSO key, no plugin to serve the route, and — measured on 2026-08-15 — was returning **HTTP 500 to every request**. Three such grants were issued and audit-logged in one day, each of which opened an error page.\n\nSo before signing anything the endpoint now checks, and repairs what it can:\n\n* the hosting platform can receive an SSO key at all — this platform exposes no shell and no\n  wp-cli, so its sites can never honour one and are refused `422`\n  (`PLATFORM_CANNOT_SSO`) rather than handed a token;\n* the plugin that serves the route is installed and active — **installed\n  automatically if it is not**, because a precondition the platform can satisfy\n  itself is not one the customer should read about;\n* the site's `ZINN_SSO_KEY` is present **on the box**, asked of the file rather than\n  of our own record of having written it — the two disagreed;\n* and the site actually answers HTTP without a server error, probed from the box\n  against the origin so a CDN cache cannot report health the site no longer has.\n  A site that fails this is `409` (`SITE_NOT_REACHABLE`).\n* the site's domain actually serves THIS site: while a partner move into it is not\n  yet `live` (the domain still opens the original copy) the answer is `409` with\n  `details[].code` `move_in_progress`, and while an import into it is unfinished,\n  `import_in_progress` — never a login URL that would open someone else's server.\n\n\nThe error body's `reason` carries which of those failed, so a client can say the true thing instead of \"something went wrong\".","tags":["hosting"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WpLoginRequest"}}}},"responses":{"201":{"description":"The one-click login grant.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WpLoginGrant"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/wordpress/plugin-directory":{"get":{"operationId":"searchWordPressPluginDirectory","summary":"Search the WordPress plugin directory.","description":"Plugins a customer can install, from the wordpress.org directory. **Collection-level and not under a site**, because choosing a plugin comes before choosing where to put it — the fleet-wide manager picks the plugin first and the sites second, and hanging this off `/v1/sites/{siteId}/…` would force it to name an irrelevant site to search.\n\nAn empty or whitespace-only `q` returns an empty page rather than the directory's popularity ranking: sixty thousand plugins nobody asked for, one upstream call per keystroke of nothing.\n\n`rating` is normalised to **0–5**. The upstream reports 0–100, and a client rendering that as stars without dividing shows every plugin as full marks. `author` is plain text — upstream sends it as an HTML anchor, which is stripped here so a vendor's markup never reaches our page.\n\nRequires `sites.view`. The upstream is unauthenticated and read-only; our egress routing for it is registered as `wordpress_org`.","tags":["hosting"],"parameters":[{"name":"q","in":"query","required":true,"description":"What to search for.","schema":{"type":"string","maxLength":200,"example":"security"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":24}}],"responses":{"200":{"description":"One page of matching plugins.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WordPressPluginDirectoryPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/wordpress/plugin-directory/{slug}":{"parameters":[{"name":"slug","in":"path","required":true,"description":"The directory slug, as the search returns it.","schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[a-z0-9][a-z0-9-]*$"}}],"get":{"operationId":"getWordPressDirectoryPlugin","summary":"One plugin from the WordPress directory.","description":"A single plugin, with its long-form `sections` (description, installation notes, changelog, FAQ) which the search deliberately omits — they are tens of kilobytes per plugin and no list view renders them.\n\n⛔ A slug the directory does not know is a **`404`**. The upstream answers `200` with an `error` field for an unknown slug, which a naive client would render as a real plugin whose every field is empty — one the customer could click Install on.\n\nRequires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The plugin.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WordPressDirectoryPlugin"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/wordpress/theme-directory":{"get":{"operationId":"searchWordPressThemeDirectory","summary":"Search the WordPress theme directory.","description":"Themes a customer can install, from the wordpress.org directory. **Collection-level and not under a site**, for the same reason as the plugin catalogue: choosing a theme comes before choosing where to put it.\n\nAn empty or whitespace-only `q` returns an empty page rather than the directory's popularity ranking.\n\n`rating` is normalised to **0–5** (upstream reports 0–100). `author` is plain text — upstream returns it as an **object** on this API and as an HTML anchor on the plugin one, so neither shape reaches our page. `screenshot_url` and `preview_url` are normalised to `https`: upstream emits them protocol-relative (`//ts.w.org/…`), which is a working URL in a browser and a broken one everywhere else.\n\n⚠️ `screenshot_url` and `preview_url` are **third-party URLs** a client will put in an `<img src>` and an anchor. Choosing a theme without seeing it is not a feature, so they travel; this is a considered risk, not an oversight. The engine never fetches them.\n\nRequires `sites.view`. Our egress routing for the upstream is registered as `wordpress_org` — the **same** service key as the plugin directory, because it is the same host, the same (absent) account and therefore the same throttling subject.","tags":["hosting"],"parameters":[{"name":"q","in":"query","required":true,"description":"What to search for.","schema":{"type":"string","maxLength":200,"example":"portfolio"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":24}}],"responses":{"200":{"description":"One page of matching themes.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WordPressThemeDirectoryPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/wordpress/theme-directory/{slug}":{"parameters":[{"name":"slug","in":"path","required":true,"description":"The directory slug, as the search returns it.","schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[a-z0-9][a-z0-9-]*$"}}],"get":{"operationId":"getWordPressDirectoryTheme","summary":"One theme from the WordPress directory.","description":"⛔ A slug the directory does not know is a **`404`**. The upstream answers `404` with an `error` field for an unknown slug — and, for some shapes, `200` with the same field — and both are turned into a real 404 here. Passing the payload through would render as a theme whose every field is empty, with an Install button on it.\n\nRequires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The theme.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WordPressDirectoryTheme"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/ftp-users":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"listSiteFtpUsers","summary":"List a site's FTP accounts.","description":"The FTP accounts on the site's hosting package, including the package's own primary account so the customer can see it exists. **No password is returned for any of them, and none can be read back**: the vendor does expose the primary account's live credentials in cleartext, and this platform deliberately never calls that endpoint.\n\nOn our own fleet, a plan that includes SSH lists its **SSH account as the SFTP login** (`is_primary: true`, `credential: ssh`), with `host` and `port`: SFTP rides the plan's SSH keys there, so the login always exists and is never an SFTP-only account to switch on.\n\n**Served stale-while-revalidate** (`docs/1081` §\"Freshness\"): a reading from the last 60 s is returned as is; an older one (up to 7 days) is returned at once while one background refresh reads the server again; only a site with no reading reads the server in the request. Any FTP or database change through this API drops the cached reading, so the customer's own change is always visible on the next call.\n\n`limit` is the **effective** ceiling — the lower of what the package permits and what the customer bought, with either side being unlimited yielding to the other. `permitted` and `can_create` are separate because the screen says different things: *\"your plan does not include this\"* is not *\"you have used all of them\"*.\n\n`404` for a site with no vendor hosting package. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The site's FTP accounts and its effective ceiling.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteFtpUserList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}},"post":{"operationId":"createSiteFtpUser","summary":"Create an FTP account on a site.","description":"Adds an account confined to one directory of the package or, on a site that runs on our own servers, switches SFTP on for the site's own account.\n\n**How it signs in depends on where the site runs, and `SiteFtpUserList.credential` says which.** A vendor package takes a `password` the caller chooses. Our own servers are **key-only**: send `public_key` (one OpenSSH public-key line) and no password — those servers refuse password authentication outright. The credential a site does not take is refused `422` with a sentence rather than silently ignored, and so is a private key pasted where the public one belongs. On our own servers a plan that includes SSH is refused `422` as well: SFTP already comes with its SSH keys, and an SFTP-only login would replace that shell.\n\nThe **caller supplies the credential** and it travels in the request only: it is never echoed in the response, never written to our records and never logged. That is the opposite of `createSiteDatabase`, and deliberately so — an FTP credential is a long-lived one a deployment pipeline will hold, so the person who owns that pipeline supplies it.\n\nThe effective ceiling is applied **before** the vendor is called: a package type that does not permit extra accounts, and a customer who has used the last of their allowance, are both refused `422` with a sentence they can act on. A username the package already carries is refused `409` — the vendor namespaces usernames per package, so this collides with the customer's own accounts, not with anyone else's.\n\n`404` for a site with no vendor hosting package. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"username":{"type":"string","maxLength":64,"description":"The login name to create, **required on a vendor package**. The vendor prefixes it per package on some package types, so the value that comes back in `SiteFtpUser.username` is the one that signs in — the client shows that, never this. Ignored on our own servers, where the SFTP account is the site's own account.","example":"deploy"},"password":{"type":"string","format":"password","minLength":12,"maxLength":128,"writeOnly":true,"description":"The account's password, **required on a vendor package and refused on our own servers**. Write-only: it is accepted here and appears in no response, no log line and no error body."},"public_key":{"type":"string","maxLength":8192,"writeOnly":true,"description":"One OpenSSH public-key line (`ssh-ed25519 AAAA… comment` or `ssh-rsa …`), **required on our own servers and refused on a vendor package**. It is written to the site account's `authorized_keys` and nowhere else; replacing it means switching SFTP off and on again with the new key.","example":"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIA7RXbUyn++t2JIgcwSXxPyF1oJAy0ZYAqzlflZndZKk laptop"},"path":{"type":"string","maxLength":255,"default":"/","description":"The directory the account is confined to, relative to the package root. Defaults to the whole site; narrowing it is how a deployment credential stops being a credential for everything.","example":"/public_html"}}}}}},"responses":{"201":{"description":"The created account. It carries no password.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteFtpUser"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/ftp-users/{ftpUserId}":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"ftpUserId","in":"path","required":true,"description":"The account id returned by `listSiteFtpUsers`.","schema":{"type":"string","minLength":1,"maxLength":128}}],"delete":{"operationId":"deleteSiteFtpUser","summary":"Delete an FTP account from a site.","description":"Removes the account and, with it, whatever was signing in with it — a deployment that still holds those credentials stops working immediately, which is the point.\n\nScoped to the organisation **and** the site, so an account id belonging to another of the caller's own sites does not resolve here either: the delete URL must not become a way to enumerate what exists elsewhere. The package's own **primary** account is refused `409` — deleting it takes the package's access with it, and no customer action can put it back.\n\n`404` for a site with no vendor hosting package, and for an id that is not on it. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/databases":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"listSiteDatabases","summary":"List a site's MySQL databases and the room to add more.","description":"The site's own database first, then every extra database it holds, each with its measured size (null when the server did not report one — never a made-up 0). Only sites on our own servers have this surface; any other site is `404`.\n\n**Served stale-while-revalidate** (`docs/1081` §\"Freshness\"): a reading from the last 60 s is returned as is; an older one (up to 7 days) is returned at once while one background refresh reads the server again; only a site with no reading reads the server in the request. Any database or FTP change through this API drops the cached reading, so the customer's own change is always visible on the next call.\n\n**The ceiling is `included + paid`** (`docs/1081` §1). `included` is the plan's database allowance — a plan that publishes no figure still includes the site's own database, so it is never 0 — and `paid` counts the site's `extra_database` add-ons that are paid up today. `can_create` says whether one more fits under `limit`; `can_buy` says whether this caller may buy one more database for this site now, and `extra_price` is that price in the caller's currency (null when not on sale). A cancelled add-on never drops a database: the customer is refused a NEW one until they are back under the ceiling. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"responses":{"200":{"description":"The site's databases and its ceiling.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMysqlDatabaseList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}},"post":{"operationId":"createSiteDatabase","summary":"Create an extra MySQL database on a site.","description":"Creates `<site database>_<name>` with its own user, and grants the site's own database user access to it as well, so the site's phpMyAdmin shows it. **The password is generated by the platform and returned once, in this response only** — it is stored nowhere on our side and cannot be read back. The ceiling is applied before the server is called: a site at its limit is refused `422` with a sentence that says how to buy another, and so is a name that is taken or not allowed. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["name"],"properties":{"name":{"type":"string","pattern":"^[a-z0-9]{1,16}$","description":"The part after `<site database>_`: lowercase letters and numbers, up to 16 characters. It cannot be changed later.","example":"shop"}}}}}},"responses":{"201":{"description":"The database, with its one-time password.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMysqlDatabaseCreated"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/databases/{databaseId}":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"databaseId","in":"path","required":true,"description":"The database id returned by `listSiteDatabases`.","schema":{"type":"string","minLength":1,"maxLength":64}}],"delete":{"operationId":"deleteSiteDatabase","summary":"Delete an extra database from a site — backed up first.","description":"Takes a full dump of the database, checks the dump is there and not empty, and only then drops the database and its user. If the dump fails nothing is dropped. The dump is kept on the server for 30 days, and support can restore it on request. The site's own database is refused `422`: deleting it would take the website down. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"responses":{"204":{"description":"Dumped, then deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/database-slots/{purchaseId}/stop":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"purchaseId","in":"path","required":true,"description":"The slot's `purchase_id` from `listSiteDatabases`.","schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"stopSiteDatabaseSlot","summary":"Stop a bought extra-database slot renewing.","description":"Stops the monthly renewal of one `extra_database` add-on bought for this site. The slot keeps working until the day before its next renewal date and is not refunded. No database is touched: a site left with more databases than its ceiling keeps them all and is refused a NEW one. A slot this site is not paying for is `422`. Requires `sites.view` and `billing.payment.manage`.","tags":["hosting"],"responses":{"200":{"description":"The renewal is stopped.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMysqlDatabaseSlotStopped"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/hourly-backups":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteHourlyBackups","summary":"Read a site's hourly backups add-on.","description":"Whether the paid hourly-backups add-on (`hourly_backups`, L40 B02) is on sale for this site, whether it is on, its price in the caller's currency, when it renews (or the last day it runs once stopped), how long each hourly restore point is kept (`keep_hours`, 48) and when the newest hourly backup was taken. `refusal` is the reason it cannot be bought right now (already on, a site hosted elsewhere, not on sale yet), or null. Buy it through `purchaseExtra` (`POST /v1/extras/hourly_backups/purchase` with `site_id`); the backups themselves are listed by `getSiteBackups` with trigger `hourly`. Every site keeps its nightly backup; hourly points are on top. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The site's hourly backups state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteHourlyBackups"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/hourly-backups/stop":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"stopSiteHourlyBackups","summary":"Stop a site's hourly backups renewing.","description":"Stops the monthly renewal of the `hourly_backups` add-on bought for this site. Hourly backups keep running until the day before the next renewal date and are not refunded; the hourly points already taken age out after `keep_hours` as usual. A site with no hourly backups is `422`. Requires `sites.view` and `billing.payment.manage`.","tags":["hosting"],"responses":{"200":{"description":"The renewal is stopped; the site's hourly backups state after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteHourlyBackups"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/moodle-upgrade":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteMoodleUpgrade","summary":"Read a Moodle site's installed release, the offered upgrade and recent runs.","description":"The one-click Moodle upgrade (s1014, docs/1160), free on every Moodle plan. `installed` is the release the last check found; `available` is the highest release THIS server can run that is newer (any branch, so a major upgrade is the same click); `blocked` lists newer releases it cannot run, each with the reason (database or PHP too old, a plugin that does not support it, requirements unknown). `refusal` says why the button is off (`refusal.moodleUpgrade.*`), or null when `can_upgrade` is true. `current_run` is the upgrade in flight; `runs` the newest ten. A pure database read. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The site's Moodle upgrade state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMoodleUpgrade"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"startSiteMoodleUpgrade","summary":"Start the one-click Moodle upgrade.","description":"Starts a Temporal workflow that backs up the files and database, switches maintenance mode on, installs the offered release, runs Moodle's non-interactive upgrade, and health-checks the site (login page, Moodle's environment check, cron). Any failure restores the backup automatically: the run ends `rolled_back` and the site is back on the release it had. `target_release` null takes the offered release; any other value must equal `available.release`. Refused with `409 MOODLE_UPGRADE_REFUSED` and a `refusal.moodleUpgrade.*` key (not checked yet, up to date, an upgrade already running, a release this server cannot run). Requires `sites.view` and `hosting.applications.manage`.","tags":["hosting"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"target_release":{"type":"string","nullable":true,"description":"The offered release (`available.release`), or null for it."}}}}}},"responses":{"202":{"description":"The upgrade is queued; `current_run` is set. Poll the GET.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMoodleUpgrade"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/moodle-upgrade/check":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"checkSiteMoodleUpgrade","summary":"Check a Moodle site for a newer release now.","description":"Queues an inspect of the site (installed release, plugins, database and PHP versions) against Moodle's update feed. Returns at once with `check_pending` true; poll `getSiteMoodleUpgrade` until it is false. Sites are also checked daily. `409 MOODLE_UPGRADE_REFUSED` for a site that is not on our servers or not live. Requires `sites.view`.","tags":["hosting"],"responses":{"202":{"description":"The check is queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMoodleUpgrade"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/moodle-upgrade/branch-pin":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"put":{"operationId":"setSiteMoodleBranchPin","summary":"Keep a Moodle site on its installed branch, or let it follow new major versions.","description":"`stay_on_branch` true offers only the installed branch's own weekly builds (security and bug fixes); a newer major is listed in `blocked` as `BRANCH_PINNED`. False follows new major versions again (plugins that do not support a release still hold it). The choice is the customer's and a later check never overwrites it; with no choice made, a site is kept on its branch automatically while a plugin would break on the newest major. `409 MOODLE_UPGRADE_REFUSED` for a site that is not on our servers or not live. Requires `sites.view` and `hosting.applications.manage`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["stay_on_branch"],"additionalProperties":false,"properties":{"stay_on_branch":{"type":"boolean"}}}}}},"responses":{"200":{"description":"The site's upgrade state with the new pin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMoodleUpgrade"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/moodle-auto-update":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteMoodleAutoUpdate","summary":"Read a Moodle site's automatic updates add-on and its window.","description":"The paid automatic-updates add-on (`moodle_auto_updates`, USD 50 a year per site, docs/1160): whether it is on sale and on, its price in the caller's currency, the renewal, the customer's quiet window and the last scheduled run. Each scheduled update is tried on a staging copy first; a plugin that does not support the release holds it, and an email report follows every run. Buy it through `purchaseExtra` (`POST /v1/extras/moodle_auto_updates/purchase` with `site_id`). Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The site's automatic updates state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMoodleAutoUpdate"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"updateSiteMoodleAutoUpdate","summary":"Turn automatic Moodle updates on or off and choose the window.","description":"Sets the quiet window (`window_weekday` 0 = Monday to 6 = Sunday, or null for every day; `window_hour` 0-23; an IANA `timezone`). Turning it on needs the add-on on this site (`422 refusal.moodleAutoUpdate.notOnSite`); a bad hour, weekday or time zone is `422`. Requires `sites.view` and `hosting.applications.manage`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["enabled","window_hour","timezone"],"properties":{"enabled":{"type":"boolean"},"window_weekday":{"type":"integer","minimum":0,"maximum":6,"nullable":true},"window_hour":{"type":"integer","minimum":0,"maximum":23},"timezone":{"type":"string","maxLength":64}}}}}},"responses":{"200":{"description":"The site's automatic updates state after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMoodleAutoUpdate"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/moodle-auto-update/stop":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"stopSiteMoodleAutoUpdate","summary":"Stop a site's automatic Moodle updates renewing.","description":"Stops the yearly renewal of the `moodle_auto_updates` add-on for this site. Updates keep running until the day before the renewal date and are not refunded. A site without the add-on is `422 refusal.moodleAutoUpdate.notOnSite`. Requires `sites.view` and `billing.payment.manage`.","tags":["hosting"],"responses":{"200":{"description":"The renewal is stopped; the state after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMoodleAutoUpdate"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/app-auto-update":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteAppAutoUpdate","summary":"Read a site's automatic app updates add-on and its window.","description":"The paid automatic-updates add-on for the app the site runs (`wordpress_auto_updates`, `woocommerce_auto_updates`, `joomla_auto_updates`, `drupal_auto_updates`, `mediawiki_auto_updates`, `phpbb_auto_updates`, `matomo_auto_updates`, `typo3_auto_updates`, `concretecms_auto_updates`, `strapi_auto_updates`, `payload_auto_updates`, `dolibarr_auto_updates`, `silverstripe_auto_updates`, `craft_auto_updates`, `osticket_auto_updates`, `piwigo_auto_updates`, `modx_auto_updates`, `suitecrm_auto_updates`, `zenphoto_auto_updates` or `mautic_auto_updates`, USD 29 a year per site; `nextcloud_auto_updates`, `owncloud_auto_updates`, `prestashop_auto_updates`, `magento_auto_updates`, `oscommerce_auto_updates`, `opencart_auto_updates` or `abantecart_auto_updates`, USD 50 a year per site; s1014 row 41): whether it is on sale and on, its price in the caller's currency, the renewal, the quiet window and the last run. Each run takes a safety backup first and rolls back to it when the homepage breaks. WordPress: core, plugins and themes (a held plugin version is never applied). Joomla!: the core only, through Joomla's own console; extensions and templates are not updated. Nextcloud: the server through its own updater, then every app with an update. Drupal: the core only (the newest release of the installed major version, then its database updates); contributed modules and themes are not updated. MediaWiki: the newest stable release with its bundled extensions and skins, then its own update script; extensions the customer added are not updated. phpBB: the newest release of the installed branch with its bundled style, language and extension, then its own `db:migrate`; styles, language packs and extensions the customer added are not updated. ownCloud: the newest release of the installed major version (the complete build, with its bundled apps), then its own `occ upgrade`; apps from the ownCloud marketplace are not updated. PrestaShop: the newest stable release of the installed major version through PrestaShop's own Update Assistant (files, database and native modules); modules the customer added are kept, never uninstalled, and are not updated. Magento: the newest security patch of the installed 2.x.y line (the source release's code, its Composer lock and `setup:upgrade`); modules and themes the customer added are kept and not updated, and a store that added Composer packages is refused with nothing changed. Strapi and Payload: the newest release of the installed major from npm (every package of the app's own family on the core's version moves together), then the app's own build (`strapi build`; for Payload a schema migration when the release needs one, `payload migrate` and `next build`) and a process restart; other npm packages the customer added are kept and not updated. osCommerce: the vendor's newest osCommerce 4 build (its code over the store's, then its own database migrations and cache rebuild); the store's configuration, images and uploads are kept, and extensions and themes the customer added are kept and not updated. Dolibarr: the newest release of the installed major version (the tag's `htdocs`), then its own CLI upgrade (`install/upgrade.php`, `upgrade2.php`, `step5.php`) until the database records the new version; modules the customer added in `custom/` are kept and not updated. Buy it through `purchaseExtra` with `site_id`. Requires Silverstripe CMS: Composer moves the site to the newest release of the installed major (the newest `silverstripe/installer` constraints for the packages the site already requires), then its own `sake db:build --flush`; packages the customer added move only within their own constraints. Craft CMS: Composer moves `craftcms/cms` and every plugin to the newest release the project's own `composer.json` allows (the installed major), then its own `craft up` (migrations and project config) and `clear-caches/all`; done only when both the code and the database report the new version. osTicket: the newest release of the installed version line (1.17 or 1.18; its `upload/` folder, the desk's `include/ost-config.php` kept), then its own `manage.php upgrade` until no upgrade is pending; plugins and language packs the customer added are kept and not updated. Piwigo: the newest release of the installed major (the gallery's `local/` settings and every photo kept), then its own database upgrades (`upgrade_feed.php`) until none is left; plugins and themes the customer added are kept and not updated. MODX: the newest release of the installed major (`core/config` and installed Extras kept), then its own setup in upgrade mode (`setup/` removed after every run) until the database records the new version; Extras the customer installed are kept and not updated. SuiteCRM: the newest release of the installed major through SuiteCRM 8's own console upgrader (`suitecrm:app:upgrade`, then `upgrade-finalize -m keep`, customisations kept) until `suitecrm:version` reports the new version; modules the customer added are kept and not updated. Zenphoto: the newest release of the installed major swapped in (zp-data, albums, uploaded and the caches kept; plugins and themes merged), then Zenphoto's own setup driven over loopback signed in as the site's administrator (setup's blind autorun stops on LiteSpeed), setup protected again on every exit, until the database's install signature records the new version; a run whose setup failed after its swap is finished by the next run. OpenCart: the newest patch release of the installed major.minor (its `upload/` folder; `config.php`, `admin/config.php` and the store's storage kept; extensions merged), then OpenCart's own upgrade steps (`install/controller/upgrade/upgrade_1` onwards) run on the command line through its own framework with the installer kept outside the web root, both config files restored byte for byte on every exit; a run whose steps failed after its swap is finished by the next run; extensions the customer added are kept and not updated. AbanteCart: every newer release of the installed major, one release at a time up to the newest (its `public_html` code over the store's, `system/config.php` kept, the installer never lands), then each release's own database upgrade (`upgrade.sql` run through AbanteCart's own database layer with the version row written last, then its `upgrade.php` trigger) until the database records the new version; a run that failed after its swap is finished by the next run; extensions the customer added are kept and not updated. Mautic: the newest stable release of the installed major, through Mautic's own updater (`mautic:update:apply` with the release's own update package, refused when the package's minimum Mautic or PHP range does not fit, then `--finish` for its database migrations); `config/local.php`, media and plugins the customer added are kept and not updated. `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The site's automatic app updates state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteAppAutoUpdate"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"updateSiteAppAutoUpdate","summary":"Turn automatic app updates on or off and choose the window.","description":"Sets the quiet window (`window_weekday` 0 = Monday to 6 = Sunday, or null for every day; `window_hour` 0-23; an IANA `timezone`). Turning it on needs the add-on on this site (`422 refusal.appAutoUpdate.notOnSite`); a bad hour, weekday or time zone is `422`. Requires `sites.view` and `hosting.applications.manage`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["enabled","window_hour","timezone"],"properties":{"enabled":{"type":"boolean"},"window_weekday":{"type":"integer","minimum":0,"maximum":6,"nullable":true},"window_hour":{"type":"integer","minimum":0,"maximum":23},"timezone":{"type":"string","maxLength":64}}}}}},"responses":{"200":{"description":"The site's automatic app updates state after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteAppAutoUpdate"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/app-auto-update/stop":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"stopSiteAppAutoUpdate","summary":"Stop a site's automatic app updates renewing.","description":"Stops the yearly renewal of the site's automatic app updates add-on. Updates keep running until the day before the renewal date and are not refunded. A site without the add-on is `422 refusal.appAutoUpdate.notOnSite`. Requires `sites.view` and `billing.payment.manage`.","tags":["hosting"],"responses":{"200":{"description":"The renewal is stopped; the state after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteAppAutoUpdate"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/exam-boost":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteExamBoost","summary":"Read a Moodle site's Exam Boost offer, its booking and its history.","description":"Exam Boost (docs/1160 §8): seven days at double CPU, memory, I/O and entry processes, then the site goes back to its plan by itself. The first boost in any twelve months is free for the site; after that each costs the `moodle_exam_boost` price (USD 9.99) in the caller's currency. Returns whether it is offered for this site (a Moodle site on our own servers), the free allowance, the price, the plan limits and the doubled limits, the current or scheduled boost and the last five finished ones. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The site's Exam Boost state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteExamBoost"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"bookSiteExamBoost","summary":"Book an Exam Boost now or for a scheduled start.","description":"Books a boost starting at `starts_at` (omitted or past = now; at most 180 days ahead). When the site's free boost of the year is available it is used and nothing is charged; otherwise the boost is bought as the `moodle_exam_boost` extra (wallet credit first, then the saved method on `gateway`). A site that already holds a live boost, an account not in good standing (§2.46), a bad start or a declined charge is `422` with a `refusal.examBoost.*` key; a missing payment method is `422 PAYMENT_METHOD_REQUIRED` with the payment step. Requires `sites.view` and `billing.payment.manage`.","tags":["hosting"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"starts_at":{"type":"string","format":"date-time","nullable":true},"gateway":{"type":"string","maxLength":32,"nullable":true},"currency":{"type":"string","minLength":3,"maxLength":3,"nullable":true}}}}}},"responses":{"201":{"description":"Booked; the site's Exam Boost state after the booking.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteExamBoost"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/exam-boost/{boostId}":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"boostId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"operationId":"moveSiteExamBoost","summary":"Move a scheduled Exam Boost's start.","description":"Moves a boost that has not started to a new `starts_at` (free or paid; at most 180 days ahead). A started, ended or cancelled boost is `422 refusal.examBoost.*`. Requires `sites.view` and `billing.payment.manage`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["starts_at"],"properties":{"starts_at":{"type":"string","format":"date-time"}}}}}},"responses":{"200":{"description":"Moved; the site's Exam Boost state after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteExamBoost"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/exam-boost/{boostId}/cancel":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"boostId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"cancelSiteExamBoost","summary":"Cancel a boost before it starts, or end a running one early.","description":"Before the start: a free boost is cancelled and the site's free boost of the year is given back; a paid boost is cancelled and its charge is refunded as Zinn® credit (never to the card). After the start: the boost ends now, the site goes back to its plan, and nothing is refunded. A finished boost is `422 refusal.examBoost.notCancellable`. Requires `sites.view` and `billing.payment.manage`.","tags":["hosting"],"responses":{"200":{"description":"Cancelled or ended; the site's Exam Boost state after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteExamBoost"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/own-vps":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteOwnVps","summary":"Read whether a website can move onto the customer's own server, and its move.","description":"Move a website onto a server that is the customer's alone while we keep managing it (s1014 VPS-r10, docs/88 §11). `offered` is false while the `site_own_vps` launch switch is off for the organization — then nothing else is filled in and the site panel shows no card. `refusal` is why this site cannot move right now (not live, not Managed WordPress, already on its own server, already moving, a payment to settle), or empty. `sizes` are our own-cloud server sizes in stock now that the move accepts (at least 2 cores and 4 GB, x86 only), each with its monthly price per location — the server plan is the whole price: the site runs on our standard managed stack (OpenLiteSpeed, multi-PHP, SSL, backups, logs) and needs no licence. `enrol_open` says whether a paid basket would be enrolled today (the `site_own_vps_enrol` switch) — while it is false, checkout refuses the basket before any charge. `move` is the latest move onto (or back from) the customer's server, with `can_roll_back` true inside the seven-day hold. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The site's own-server offer and move.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteOwnVps"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/own-vps/quote":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"quoteSiteOwnVps","summary":"Build the one basket that moves a website onto the customer's own server.","description":"Creates an OPEN basket with exactly one line — the server (`compute_server`, the chosen size and location, built from the fleet's worker image, marked with the site) — and returns it. Nothing is charged: the customer pays the basket (`cart_id`) through the ordinary checkout, which asks every rule again and refuses it while the move cannot be enrolled. Refused with `422` while the offer is off for the organization, or for any reason `getSiteOwnVps` names. Requires `sites.view` and `billing.payment.manage`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteOwnVpsQuoteRequest"}}}},"responses":{"201":{"description":"The basket, not yet paid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteOwnVpsQuote"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/own-vps/rollback":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"rollbackSiteOwnVps","summary":"Move a website back from the customer's own server, inside the seven-day hold.","description":"After a move onto the customer's own server the previous copy is kept for seven days. Inside that hold this moves the website back — copying its current state, so every edit made on the customer's server comes with it — then removes that server and refunds it. Outside the hold it is `422`. Requires `sites.view` and `billing.payment.manage`.","tags":["hosting"],"responses":{"202":{"description":"The move back has started; the site's own-server state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteOwnVps"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/storage":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteStorage","summary":"Read a site's storage, its extra storage packs and what it can buy.","description":"Extra storage for one website (s1014 STORAGE, docs/157 §S): the site's disk and file usage against its ceiling (`base` from its plan, `packs` added by extra storage), the packs it holds (each removable only while the site fits without it), and the three packs on sale — 10 GB, 50 GB and 100 GB a month, each adding 10,000 files per GB — priced in the caller's currency, with today's prorated first charge (`first_charge_minor`, to the plan's renewal day `renews_on`). `can_buy` is the purchase door's own answer; when the site's server cannot back the pack and another server in its pool can, `refusal_code` is `box_full` and `move_available` is true (see `moveSiteForStorage`). `plan_suggestion` names a plan upgrade that gives the same space for the pack's price or less, when one exists. `lapse` is set while a pack that ended is still in use (the site keeps its space for a grace period, then only new growth stops). Buy a pack through `purchaseExtra` (`POST /v1/extras/extra_storage_10gb/purchase` with `site_id`). Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The site's storage state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteStorage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/storage/packs/{purchaseId}/stop":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"purchaseId","in":"path","required":true,"description":"The storage pack's add-on purchase id (`packs[].purchase_id`).","schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"stopSiteStoragePack","summary":"Remove one extra storage pack at the end of its paid month.","description":"Stops the monthly renewal of one extra storage pack on this site. Refused (`422`) unless the site's measured disk and files fit the ceiling without the pack, or when usage has not been measured recently enough to tell. The pack keeps counting until the day before its next renewal date and is not refunded; after that the site's ceiling is lowered on its server. A pack that is not on this site is `404`. Requires `sites.view` and `billing.payment.manage`.","tags":["hosting"],"responses":{"200":{"description":"The renewal is stopped; the site's storage state after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteStorage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/storage/move-and-add":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"moveSiteForStorage","summary":"Move a site to a server with room and add extra storage there.","description":"For a site whose server cannot back the pack it asked for (`getSiteStorage` offer with `refusal_code` `box_full` and `move_available` true): moves the site to a server in its own pool and region that can, through the platform's site-move path, and buys the pack automatically once the site is live there. Nothing is charged now, and nothing is charged if the move does not complete. Needs a stored payment method or enough balance (`422` otherwise), and only one such move per site at a time. Requires `sites.view` and `billing.payment.manage`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["pack_code"],"additionalProperties":false,"properties":{"pack_code":{"type":"string","enum":["extra_storage_10gb","extra_storage_50gb","extra_storage_100gb"]}}}}}},"responses":{"202":{"description":"The move has started; the site's storage state with `move` set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteStorage"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/cleaner":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteCleaner","summary":"Read a site's Site Cleaner state.","description":"The Site Cleaner (`site_cleaner`, s1014 B01, docs/1081 §7) for this site: whether the add-on is on sale to the organisation and active on the account (one subscription cleans every website), its prices in the caller's currency (`site_cleaner` monthly, `site_cleaner_yearly` yearly), the scheduled clean, the latest scan (the free preview, with every item that could go), the job in flight and the recent jobs. `supported` is false for a site not hosted on our own servers or not online. Buy it through `purchaseExtra`. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The site's Site Cleaner state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCleaner"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/cleaner/scan":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"scanSiteCleaner","summary":"Scan a site for things to clean (free).","description":"Starts a read-only scan of the site (a job). Free for every account: it lists unused plugins and themes, leftovers of removed plugins, database junk, plugin log tables and junk files with their sizes. Poll `getSiteCleaner` for the result. One job runs per site at a time (`422` while another runs). Requires `sites.view` and `hosting.backup.manage`.","tags":["hosting"],"responses":{"202":{"description":"The scan is queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCleanerJob"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/cleaner/clean":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"cleanSiteCleaner","summary":"Clean a site.","description":"Starts a clean (a job). The database is dumped and every file that will go is archived FIRST; if the home page answers worse afterwards, both are put back and the job ends `restored`. `select` names the item ids to clean (from the latest scan); omitted means every item ticked by default. A site with nothing to clean ends `nothing`. Needs the Site Cleaner add-on on the account and an account in good standing (`422` otherwise). Requires `sites.view` and `hosting.backup.manage`.","tags":["hosting"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"select":{"type":"array","maxItems":500,"items":{"type":"string","maxLength":200},"description":"Item ids to clean; omit for every default-ticked item."}}}}}},"responses":{"202":{"description":"The clean is queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCleanerJob"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/cleaner/schedule":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"put":{"operationId":"setSiteCleanerSchedule","summary":"Set a site's scheduled clean.","description":"Turns the scheduled clean `off`, or on `daily`, `weekly` or `monthly`. A scheduled clean removes every default-ticked item except the ids in `skip`, with the same backup first and roll-back as a manual clean. Turning a schedule on needs the add-on; `off` always works. Requires `sites.view` and `hosting.backup.manage`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["schedule"],"additionalProperties":false,"properties":{"schedule":{"type":"string","enum":["off","daily","weekly","monthly"]},"skip":{"type":"array","maxItems":500,"items":{"type":"string","maxLength":120},"description":"Item ids a scheduled clean never removes."}}}}}},"responses":{"200":{"description":"The site's Site Cleaner state after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCleaner"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/cleaner/jobs/{jobId}/undo":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"jobId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"undoSiteCleanerJob","summary":"Undo a clean (restore its backup).","description":"Puts back the files and the database a clean removed, from the backup it took first. Backups are kept 7 days (`backup_expires_at`); an expired one is `422`. Needs the add-on. Requires `sites.view` and `hosting.backup.manage`.","tags":["hosting"],"responses":{"202":{"description":"The undo is queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCleanerJob"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/cleaner/stop":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"stopSiteCleaner","summary":"Stop the account's Site Cleaner renewing.","description":"Stops the renewal of the `site_cleaner` / `site_cleaner_yearly` add-on on the site's account (one subscription covers every website, so this stops it for all of them). The Site Cleaner keeps working until the day before the next renewal date (`ends_on`) and is not refunded, like every other add-on a customer stops themselves; backups already taken are kept their usual 7 days. An account without the add-on is `422`. Requires `sites.view` and `billing.payment.manage`.","tags":["hosting"],"responses":{"200":{"description":"The renewal is stopped; the site's Site Cleaner state after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCleaner"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/scheduled-tasks":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"listSiteScheduledTasks","summary":"List a site's scheduled tasks.","description":"The site's scheduled tasks (cron jobs): name, kind, what it runs, the schedule (UTC), whether it is on, and why it is paused if it is. Tasks managed here come first (`source: panel`); lines added to the crontab over SSH follow (`source: crontab`, read-only — they can be deleted here but are never rewritten by us).\n\n`kinds` lists what this site may run (`wpcron` only on WordPress, `php` not on a static site). `limit_per_site`/`limit_per_org` and `used`/`used_in_org` are the counts behind `can_create`; `permitted` is whether the plan includes scheduled tasks at all — \"your plan does not include this\" is not \"you have used them all\".\n\nAvailable on every hosting line whose site runs on our own servers. A task runs as the site's own user, inside its CageFS, from the site folder, and is stopped after 15 minutes. While the site is suspended its tasks are switched off on the server and come back when it is active again. Requires `sites.view` **and** `sites.panel_access`; `404` for a site not on our own servers.","tags":["hosting"],"responses":{"200":{"description":"The site's scheduled tasks and its limits.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteScheduledTaskList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}},"post":{"operationId":"createSiteScheduledTask","summary":"Create a scheduled task on a site.","description":"Adds a task and writes it to the site's server in the same request; if the server refuses, nothing is kept. Refused with a `422` naming the fix for: a schedule more often than every 5 minutes (checked across the whole day, including :55 to :00), a multi-line or over-long command, a PHP path outside the site folder, an address that is not http(s), a kind the site cannot run, 20 tasks on the site or 500 on the account, or a plan without scheduled tasks. A `*/N` minute field is moved to a fixed offset inside its window (`schedule` in the answer is what runs).\n\nThe old body (`schedule` + `command` only) still works and creates a `command` task. Audited as `site.cron.created`. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteScheduledTaskWrite"}}}},"responses":{"201":{"description":"The task as stored and written to the server.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteScheduledTask"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/scheduled-tasks/{taskId}":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"taskId","in":"path","required":true,"description":"The task's id from `listSiteScheduledTasks`: a UUID for a task managed here, or a 16-character id for a line added to the crontab over SSH.","schema":{"type":"string","minLength":1,"maxLength":128}}],"put":{"operationId":"updateSiteScheduledTask","summary":"Change a site's scheduled task.","description":"Changes the fields given and keeps the others (a full body, as older clients send, therefore behaves as before). `enabled: false` switches the task off on the server and keeps it listed; a task our team paused (`paused_reason: staff`) cannot be switched back on here. The same validation as `createSiteScheduledTask`. Only tasks managed here (`source: panel`) can be changed. Audited as `site.cron.updated`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteScheduledTaskWrite"}}}},"responses":{"200":{"description":"The task after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteScheduledTask"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}},"patch":{"operationId":"patchSiteScheduledTask","summary":"Change some fields of a site's scheduled task.","description":"The same as `updateSiteScheduledTask`; provided for clients that send PATCH.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteScheduledTaskWrite"}}}},"responses":{"200":{"description":"The task after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteScheduledTask"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}},"delete":{"operationId":"deleteSiteScheduledTask","summary":"Delete a site's scheduled task.","description":"Removes the task from the server and its run history with it; a run already going finishes. Works for a crontab line added over SSH too (by its 16-character id). Scoped to the organisation **and** the site: another site's task id is a `404`. Audited as `site.cron.deleted`.","tags":["hosting"],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/scheduled-tasks/{taskId}/run":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"taskId","in":"path","required":true,"description":"The task's id from `listSiteScheduledTasks`: a UUID for a task managed here, or a 16-character id for a line added to the crontab over SSH.","schema":{"type":"string","minLength":1,"maxLength":128}}],"post":{"operationId":"runSiteScheduledTask","summary":"Run a scheduled task now.","description":"Starts the task on its server at once, inside the site's own CageFS, in the background (`202`). The run is recorded like a scheduled one with `trigger: manual` and appears in `listSiteScheduledTaskRuns` within a few seconds. Rate-limited: once a minute per task and 10 times in 10 minutes per account (`429` with `Retry-After`). Refused (`422`) while the site is not active. Audited as `site.cron.run`.","tags":["hosting"],"responses":{"202":{"description":"Started."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/scheduled-tasks/{taskId}/runs":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"taskId","in":"path","required":true,"description":"The task's id from `listSiteScheduledTasks`: a UUID for a task managed here, or a 16-character id for a line added to the crontab over SSH.","schema":{"type":"string","minLength":1,"maxLength":128}}],"get":{"operationId":"listSiteScheduledTaskRuns","summary":"List a scheduled task's last runs and their output.","description":"Newest first, at most 20 (the server keeps 20 per task). `status`: `ok`, `failed` (non-zero exit code), `timeout` (stopped at 15 minutes), `skipped` (the previous run was still going) or `running`. `trigger`: `schedule` or `manual`. `output` keeps the first 1,000 and last 7,000 bytes of a long output. Read from the server on request, never cached.","tags":["hosting"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":20}}],"responses":{"200":{"description":"The runs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteScheduledTaskRunList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/scheduled-tasks":{"get":{"operationId":"listAccountScheduledTasks","summary":"List every scheduled task on the account.","description":"Every task managed here on every site the caller holds `sites.panel_access` for, each with its `site_id` and `site_domain` (crontab lines added over SSH are listed per site, not here).","tags":["hosting"],"responses":{"200":{"description":"The tasks.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SiteScheduledTask"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/web-logs":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteWebLogs","summary":"Get the tail of a site's access and error logs.","description":"The customer's own web-server logs for their own site. Until this endpoint existed a customer could not see their access log **at all**, which is why *\"why is my site slow\"* was a support ticket rather than a tab.\n\n⛔ **The path is `/web-logs`, deliberately not `/logs`.** `/v1/ops/logs` is Loki and staff-only, and two endpoints differing by a prefix are two endpoints somebody confuses in a runbook at three in the morning.\n\n⛔ `access` is a list of the customer's **visitors'** IP addresses — personal data held under the customer's lawful basis, not ours. It is served only to a principal entitled to the site, must not be cached by the client, and both streams are cut to their most recent bytes so a busy site cannot answer with tens of megabytes; `truncated` says so rather than implying the tail is the whole. `unreadable` is `true` when the vendor answered with a body naming neither log — which is **not** the same as a site with no traffic, and must never render as two empty panes.\n\n⭐ Serves sites on **our own servers** as well as vendor-hosted ones (W43-54). A fleet site's access log is its own account's file; its error log is filtered for that account **on the host**, so no other tenant's lines are ever transferred. Each stream carries its own `*_available`, because on the fleet one log can be readable while the other is not.\n\nRequires `sites.view` **and** `sites.panel_access`. `404` for a site that does not exist or is not in scope.","tags":["hosting"],"responses":{"200":{"description":"The tail of both logs.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWebLogs"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/subdomains":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"listSiteSubdomains","summary":"List a site's subdomains.","description":"The subdomains served by the site's hosting package and the document root each one points at. ⛔ Subdomains are the only surface here with a real **quantity** ceiling: `limit` is the lower of what the package template permits and what the customer bought, so `can_create` is arithmetic and not merely `permitted`.\n\n⚖️ **On the Footprint-Free / PBN line the ceiling is the plan's `max_sites`, because a subdomain spends one of them** (owner ruling 2026-09-01). `limit` is then the site cap and `used` carries how much of it is already spent — by the customer's **sites as well as their subdomains** — so a client must render the caption from `used` and not from `data.length`.\n\n⚖️ **On every other line (mainstream, app hosting) the ceiling is the plan's `subdomains` allowance plus every live `subdomains_10` pack (10 more each, USD 2.00 a month)** (owner ruling 2026-11-05). `used` counts the org's subdomains on those lines, `limit` is `null` when the plan states no cap, and a create at the cap is refused with `422 ALLOWANCE_EXCEEDED` (`details.limit`, `details.used`), whose message names the pack.\n\nRequires `sites.view`. `404` for a site with no managed hosting package and no own-fleet placement.","tags":["hosting"],"responses":{"200":{"description":"The site's subdomains and its effective ceiling.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteSubdomainList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}},"post":{"operationId":"createSiteSubdomain","summary":"Add a subdomain to a site.","description":"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.\n\n⛔ 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.\n\n⚖️ **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`.\n\n`404` for a site with no managed hosting package and no own-fleet placement. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"additionalProperties":false,"properties":{"name":{"type":"string","maxLength":253,"description":"The subdomain to add. What the vendor actually created comes back in `SiteSubdomain.name`, and that — never this — is what the client shows.","example":"blog.example.com"},"stack_type":{"type":"string","enum":["static","php","wordpress","woocommerce"],"default":"static","description":"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 deploy into, which is what a subdomain is on every panel; `wordpress`/`woocommerce` install WordPress into it, sharing the account's database under its own table prefix.\n\n⛔ **Own fleet only.** Sent for a site on a resold package it is a `422`, never ignored — there is no stack we install there, and silently dropping the choice would tell a customer their subdomain runs WordPress when it is an empty folder. Stacks that need their own runtime (`node`, one-click apps, Nextcloud) are refused with the sentence naming the door to use instead: they are their own site.","example":"wordpress"}}}}}},"responses":{"201":{"description":"The subdomain the vendor created.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteSubdomain"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/subdomains/{subdomainName}":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"subdomainName","in":"path","required":true,"description":"The subdomain exactly as `listSiteSubdomains` reports it. It contains dots; percent-encode it rather than assuming it is path-safe.","schema":{"type":"string","minLength":1,"maxLength":253}}],"delete":{"operationId":"deleteSiteSubdomain","summary":"Delete a subdomain from a site.","description":"Removes the subdomain from the package. Anything served on it stops resolving to the site immediately, which is the point — so the client names it back before calling.\n\n`404` for a site with no managed hosting package, and for a name that is not on it. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/performance/slow-requests":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"listSiteSlowRequests","summary":"List the slowest traced requests for a site.","description":"Real requests this site served, slowest first, measured on the machine by CloudLinux X-Ray. Each row carries how long the request took, how much of that time the account spent **stopped at its resource ceiling**, and why the request could not be served from the page cache.\n\n⭐ `throttled_ms` is reported separately from `duration_ms` on purpose: it is the number that turns *\"the site is slow\"* into *\"the plan is too small\"*, and folding it into the total hides the one thing the customer can act on.\n\n⛔ **An empty list is a `200`.** Tracing is enrolled when the box converges and fills over hours, so \"nothing traced yet\" is an ordinary state on a healthy machine, not a failure.\n\nRequires `sites.view`. No visitor IP addresses appear in the response — the field does not exist at any layer beneath this one.","tags":["hosting"],"parameters":[{"name":"limit","in":"query","required":false,"description":"How many requests to return (1–100, default 20).","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"The slowest traced requests, slowest first.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SiteSlowRequest"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/performance/slow-requests/{taskId}/{requestId}":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"taskId","in":"path","required":true,"description":"The tracing task the request belongs to, from `task_id` on the list row.\n\n⛔ Part of the path rather than inferred, because `requestId` restarts at 1 for **every** tracing task and a box runs several concurrently. Without it, request 7 is ambiguous and the API would answer about a different request than the row the customer clicked, with no error anywhere.","schema":{"type":"string","pattern":"^[0-9a-f]{32}$"}},{"name":"requestId","in":"path","required":true,"description":"The request's number within that tracing task.","schema":{"type":"integer","minimum":0}}],"get":{"operationId":"getSiteSlowRequest","summary":"Show where one request's milliseconds went.","description":"The cost breakdown for a single traced request: which WordPress plugin, PHP extension, PHP function or SQL query consumed the time, heaviest first, with the call site relative to the site's own document root.\n\n⭐ Rows are merged by name — the vendor emits one row per call site, so a plugin called from four places arrives four times and would otherwise render as four small percentages instead of one real one.\n\n⭐ SQL literals arrive already redacted by the vendor (`WHERE autoload IN ('xxx')`) and are neither restored nor re-redacted here.\n\nRequires `sites.view`. A task that does not belong to this site answers `503` with a sentence, never another tenant's data.","tags":["hosting"],"responses":{"200":{"description":"The request and what it spent its time on.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteSlowRequestBreakdown"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/apm":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteApm","summary":"Ranked transactions, ranked hotspots and the hourly timeline for a site.","description":"Stored, aggregated PHP profiling: which **pages** cost the most server time, which **plugin, PHP function or SQL query** is eating it, and how the site's PHP execution time has moved hour by hour.\n\n⭐ Read from rows, not from the machine. The sibling `…/performance/slow-requests` surface opens an SSH session to the worker box on every call; this one is a database query, which is why it can be rendered on a customer-facing tab without a §2.16 problem.\n\n⛔ **An empty payload is a `200` WITH A REASON.** `enrolment_state` says which of four things happened — `unknown` (not collected yet), `enrolled` (collected, and the site was genuinely quiet), `refused` (the server would not start tracing), `unsupported` (hosting that cannot trace). A surface that cannot tell a quiet site from a feature that is switched off was the live state of the fleet on 2026-09-03: one of two boxes had zero sites enrolled and every screen said \"nothing traced yet\".\n\nRequires `sites.view` and the `request_profiling` entitlement, which is included on every product line. No visitor IP addresses appear in the response — the field does not exist at any layer beneath this one.","tags":["hosting"],"parameters":[{"name":"hours","in":"query","required":false,"description":"How far back to aggregate (1–2160, default 24). Clamped rather than refused: a junk value answers the question that was asked with the default period.","schema":{"type":"integer","minimum":1,"maximum":2160,"default":24}},{"name":"limit","in":"query","required":false,"description":"How many ranked rows per table (1–50, default 10).","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}}],"responses":{"200":{"description":"The stored profiling picture for the requested window.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteApmSummary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/apm/traces":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"listSiteApmTraces","summary":"List the individual profiled requests kept for a site.","description":"The sampled requests stored whole, slowest first. A trace is one real request with its function-level breakdown attached; the aggregates above carry the honest averages so the sampling cannot mislead about typical performance.\n\n⛔ Kept for a bounded period (7 days) because a trace with its breakdown is the only row in this vertical that accumulates. The ranked tables keep far longer for a fortieth of the storage.\n\nRequires `sites.view` and the `request_profiling` entitlement.","tags":["hosting"],"parameters":[{"name":"transaction","in":"query","required":false,"description":"Only traces whose grouped transaction label matches exactly.","schema":{"type":"string","maxLength":200}},{"name":"limit","in":"query","required":false,"description":"How many traces to return (1–100, default 20).","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"The kept traces, slowest first.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SiteApmTrace"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/apm/traces/{traceId}":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"traceId","in":"path","required":true,"description":"One of our own trace ids, from `id` on the list row.\n\n⭐ A UUID, unlike the sibling live surface's vendor task id: this is a primary key we minted, so a non-UUID really is *\"no such trace\"* and `404` is the honest answer.","schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getSiteApmTrace","summary":"Show where one kept request's milliseconds went.","description":"The function-level breakdown for one stored request: which WordPress plugin, PHP extension, PHP function or SQL query consumed the time, heaviest first, with the call site relative to the site's own document root.\n\n⭐ SQL literals arrive already redacted by the vendor (`WHERE autoload IN ('xxx')`) and are neither restored nor re-redacted here. That redaction is why a slow query can be shown to a customer at all.\n\n⛔ A trace past retention answers `404` rather than `410`: the customer's next action is identical, and a distinct code would be an oracle for which trace ids ever existed.\n\nRequires `sites.view` and the `request_profiling` entitlement. A trace belonging to another site answers `404`, never another tenant's data.","tags":["hosting"],"responses":{"200":{"description":"The kept request and what it spent its time on.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteApmTraceDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/php-config":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSitePhpConfig","summary":"Get a site's changeable PHP settings.","description":"The `php.ini` settings this site's machine will let a customer change, **as the machine describes them** — each with its type (`bool`/`list`/`value`), its default, the legal values for a list, and a sentence explaining it.\n\n⭐ The schema is the box's, not ours. A hardcoded field list would drift the first time the hosting changed a range and nothing would go red: the write would simply be refused later, at the vendor, in the vendor's words.\n\n`value` is `null` when the site is **inheriting** the default rather than having set it — a different fact from setting it to the same text, and the only one of the two that survives a change of the platform default.\n\n`supported: false` with an empty `options` list is a real answer, not an error: the hosting may publish no changeable settings at all. `reason` says which silence it is. Requires `sites.view` + `sites.panel_access`.","tags":["hosting"],"responses":{"200":{"description":"The site's PHP settings, or a stated reason there are none.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePhpConfig"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}},"put":{"operationId":"setSitePhpConfig","summary":"Set a site's PHP settings.","description":"Applies the **complete** set of overrides. An omitted name is cleared, and `{}` resets every setting to the machine's defaults — deliberately not a PATCH, because *\"return this to the platform default\"* and *\"pin it to the value that default happens to have today\"* are different intentions and only a whole-set write can express the first.\n\nValues are validated against the **machine's own published range** before the vendor sees them, so a bad value is refused in our words rather than failing later as an unexplained vendor error. The write is then **read back off the machine** and a value it quietly declined is a failure here, never a success the customer discovers is untrue.\n\n`409` when the site has no machine to hold the setting. Requires `sites.view` + `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePhpConfigUpdate"}}}},"responses":{"200":{"description":"The settings as the machine reports them after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePhpConfig"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/php-settings":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSitePhpSettings","summary":"Get a site's PHP extensions, php.ini settings and resource tier.","description":"Everything the site's PHP screen needs, in one read.\n\n`extensions` lists Tier 0 and Tier 1 as `locked: true` — always on, not a choice — alongside the Tier 2 extensions the customer may switch. They are **rendered rather than hidden** because \"does this host have ImageMagick?\" is one of the commonest pre-sales and migration questions there is, and an empty list answers it worse than a locked switch does.\n\n`ini` carries only the two customer-editable bands. The staff-only band (`disable_functions`, `open_basedir`, `sendmail_path`, `upload_tmp_dir`, `expose_php` and extension loading itself) is **absent from the payload**, not merely hidden by the panel: those directives are the per-site isolation boundary, and a customer who can edit `disable_functions` can re-enable `shell_exec`.\n\nEach capped directive carries `cap` — the ceiling this site's **plan** allows — so the panel can stop the control at the right place rather than let the customer type a value and meet a refusal. `cap_raised_by_support` and `override_expires_at` are how a staff override is made **visible to the customer**, which is one of the three properties `docs/204` §7a requires of one.\n\n`lve` reports the site's resource tier and what each limit does when it is reached. ⭐ `ep` is the one that emits `508 Resource Limit Is Reached` — a status code that names no resource, no number and no remedy, so a customer who meets it concludes the host is broken.\n\n`applied_at` is `null` when no settings have ever been pushed to the machine — a different fact from \"pushed and confirmed\", and the only one of the two that needs an engineer. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The site's PHP settings, caps and resource tier.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePhpSettings"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setSitePhpSettings","summary":"Set a site's PHP extensions and php.ini settings.","description":"Applies the **complete** desired state. An omitted name is cleared — deliberately not a PATCH, because \"return this to the platform default\" and \"pin it to the value that default happens to have today\" are different intentions and only a whole-set write can express the first.\n\nThe change is **pushed to the machine as part of this call and read back**, so a `200` means the interpreter a visitor's request runs has actually loaded it. A value the box quietly declined is a failure here, never a success the customer discovers is untrue later.\n\nA value above the plan's ceiling is a `422` **naming the plan and the tier that would allow it**, so the panel can offer the upgrade rather than showing a dead end. A staff-only directive is also a `422` and not a `403`: the caller is entitled to change PHP settings, and this particular one is not among them — a `403` reads as \"you need a different key\" and sends them to support to ask for one that does not exist. Requires `sites.view` + `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePhpSettingsUpdate"}}}},"responses":{"200":{"description":"The settings as the machine reports them after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePhpSettings"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/wordpress":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteWordPress","summary":"Get the WordPress install on a site.","description":"What WordPress is on the package, what version, whether an update is waiting, and — in one read — which of the eleven WordPress operations the package type permits. One read gates eleven buttons, so a customer never learns their plan's shape by pressing one and reading a refusal.\n\n`is_latest` is **tri-state**: null means the vendor did not say, which is not \"out of date\". `update_available` is the flag a screen should act on, because it is derived from the vendor's update object being non-empty rather than from a comparison between two version strings nobody parsed — ⛔ `{}` is how this platform says *\"no update\"*, and it is falsy, so the presence of the key is not the signal.\n\nReading what is installed is **not** gated on a capability: a screen has to be able to render *\"your plan does not include plugin management\"* beside the list of what is installed. `404` for a site with no vendor hosting package. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The site's WordPress install and its permitted operations.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPress"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/update":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"updateSiteWordPressCore","summary":"Update WordPress core on a site.","description":"Asks the vendor to update WordPress itself. `202` and not `200`: the platform acknowledges and updates afterwards, so the state in the body is the install as it reads **now** and usually still shows the old version. Returning `200` with a version the site is not running is exactly the lie this status exists to avoid — the client re-reads `getSiteWordPress` rather than trusting the body as final.\n\nRefused `422` before the vendor is called when the package type does not carry `wp_updates`, or when WordPress is not installed. `404` for a site with no vendor hosting package. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"responses":{"202":{"description":"The update was accepted. The state is the install as it reads now.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPress"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/plugins":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"listSiteWordPressPlugins","summary":"List the plugins installed on a site's WordPress.","description":"Every plugin the install carries, with its activation status, its version, and the version waiting for it. `update_version` is a string and not a boolean because a screen that can name the waiting version is more useful than one that can only say \"update\"; it is `\"\"` when the plugin is current.\n\n⛔ `stack_cache_installed` is carried **separately and cannot be derived from `data`**: this platform excludes its own cache plugin from the listing, so a client deriving the flag from the rows would answer \"not installed\" for ever and the install button would never go away.\n\n`404` for a site with no vendor hosting package. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The installed plugins, and whether the vendor cache plugin is on.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressPluginList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}},"post":{"operationId":"installSiteWordPressPlugin","summary":"Install a plugin on a site's WordPress.","description":"Installs a plugin and, by default, activates it. Either from the **wordpress.org directory** by `slug` (what `searchWordPressPluginDirectory` returns), or from a **zip the customer uploads**.\n\n⛔ Exactly one of `slug` and `zip` — never both. A request carrying both is refused `422` rather than resolved by precedence, because a caller that sent the wrong one would otherwise install something it did not ask for and be told it succeeded.\n\nIdempotent: a plugin already present is activated rather than reinstalled, and an upload of a plugin that is already there replaces it in place. Nothing is ever removed — use `deleteSiteWordPressPlugin` for that.\n\n⚠️ An uploaded zip is **the customer's own code running on their own site**, and we do not review it. It is size-capped at **256 MB** — send it as `multipart/form-data` (`file`); the base64 `zip` field is bounded by the 32 MB JSON body cap — and rejected unless it is a valid archive containing a single top-level directory with a PHP plugin header, which is what WordPress itself requires — not a security review, and not presented as one.\n\nRefused `422` when the package type does not carry `wp_plugins`, or when WordPress is not installed. `404` for a site with no vendor hosting package. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"slug":{"type":"string","maxLength":200,"pattern":"^[a-z0-9][a-z0-9-]*$","description":"A wordpress.org directory slug. Lower-case, digits and hyphens — the directory's own alphabet, enforced here so a path separator or a URL can never reach the box as a \"slug\".","example":"wordfence"},"zip":{"type":"string","format":"byte","description":"A base64-encoded plugin zip, for small files only. The whole JSON body is capped at 32 MB, so base64 carries at most ~24 MB decoded — this field used to be the only door, which is why a 35 MB plugin could not be uploaded at all (D28102). A larger body is refused `413` with a sentence naming the multipart door."},"activate":{"type":"boolean","default":true,"description":"Activate after installing. `false` puts the files in place and leaves the plugin switched off — what a staged rollout of something risky wants. Deliberately not the default: \"installed but dormant\" is the surprising outcome, so it has to be asked for."}}}},"multipart/form-data":{"schema":{"type":"object","additionalProperties":false,"required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"The plugin zip, **up to 256 MB**. Streamed to a temporary file as it arrives (never held in memory) and to the server in bounded chunks; one byte over the limit is refused `413` with a sentence that states the limit. ⚠️ The upload itself must finish within 60 seconds (the edge's read timeout): 256 MB needs ~35 Mbit/s upstream."},"activate":{"type":"boolean","default":true}}}}}},"responses":{"200":{"description":"The site's plugins after the install, in the same shape as the `GET`. The whole list rather than the one plugin, because installing can change another row — activating a plugin that supersedes one already present deactivates it — and a client that patched a single row into its cache would show a state the site is not in.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressPluginList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/plugins/{pluginName}":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"pluginName","in":"path","required":true,"description":"The plugin's slug, exactly as `listSiteWordPressPlugins` reports it. It is WordPress's identifier, not ours, so percent-encode it; a slug containing a slash does not route and answers `404` rather than being truncated.","schema":{"type":"string","minLength":1,"maxLength":255}}],"put":{"operationId":"setSiteWordPressPlugin","summary":"Activate or deactivate a plugin on a site.","description":"Sets whether the plugin is active, and returns the whole plugin listing so the card re-renders from the server's answer. The plugin is addressed by **path** rather than by a field in the body, so activate and delete cannot be confused for one another by a caller that got a body wrong.\n\nDeactivating a plugin can take a live site's checkout, cache or security layer with it. Refused `422` when the package type does not carry `wp_plugins`, or when WordPress is not installed. `404` for a site with no vendor hosting package. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["active"],"additionalProperties":false,"properties":{"active":{"type":"boolean","description":"Whether the plugin should be running after this call.","example":true}}}}}},"responses":{"200":{"description":"The plugin listing after the change.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressPluginList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}},"delete":{"operationId":"deleteSiteWordPressPlugin","summary":"Remove a plugin from a site's WordPress.","description":"Runs the plugin's own uninstall routine (`uninstall.php` or its registered uninstall hook), deactivates it, then deletes its files — the same steps as deleting it in wp-admin, so whatever the plugin chooses to clean up on uninstall (its settings, a must-use loader) goes with it, and whatever it was doing for the site stops. The client confirms the name back before calling. A plugin whose own uninstall routine fails is still removed. A must-use plugin or a drop-in (both appear in the listing) is refused `422`: they are managed by the platform.\n\n⭐ On our own servers the files are removed by the platform as the site's own user, not by `wp plugin delete`, which shells out through PHP's `proc_open()` — disabled on every site by the hosting hardening — and failed `422` on every site until 2026-09-29 (D28100). The uninstall routine runs through `wp plugin uninstall --skip-delete`, which never shells out; until 2026-10-31 it did not run at all.\n\n⛔ The listing is re-read afterwards and a plugin that survived the removal is reported as a refusal rather than a success: the platform acknowledges a delete it did not perform, and a card that removed the row locally would show the customer a plugin that is still running.\n\n`200` and the whole listing, not `204`, because the card renders the remaining plugins from this answer. `404` for a site with no vendor hosting package. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"responses":{"200":{"description":"The plugin listing after the removal.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressPluginList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/stack-cache":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"installSiteWordPressStackCache","summary":"Install the server-side cache plugin on a site.","description":"Installs the platform's own caching plugin. It has its own operation rather than being a row in the plugin listing because the vendor **excludes it from that listing**, so it can neither be found there nor installed through it.\n\nSuccess is confirmed by the vendor's own `stackCacheInstalled` flag, never by searching the returned rows for it — searching a list the plugin is deliberately absent from would report failure on every successful install.\n\n`201` and the whole plugin listing, so the card re-renders. `404` for a site with no vendor hosting package. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"responses":{"201":{"description":"The plugin listing, with `stack_cache_installed` now true.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressPluginList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/uploads":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"startSiteWordPressUpload","summary":"Start a resumable upload of a plugin or theme zip.","description":"Opens a **resumable upload** of a plugin or theme zip of up to **256 MB**. Use it for anything larger than a few megabytes, and always on a slow or unreliable connection. The file travels as small parts, each its own request, so no request comes near a timeout and a dropped connection costs one part rather than the whole file (D28103).\n\nThe protocol: `start` (this call, declaring the file's size) → `PUT` every part (`uploadSiteWordPressUploadPart`, the platform decides `part_size`) → `complete` with the whole-file checksum. `GET` the upload at any point to see which parts have arrived, which is how a client resumes after a drop. Unfinished uploads expire after 24 hours and their parts are deleted.\n\nRefused up front, before any byte is sent: `413` for a file over 256 MB, `422` when the plan does not include uploading this kind. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["kind","size"],"properties":{"kind":{"type":"string","enum":["plugin","theme"]},"size":{"type":"integer","format":"int64","minimum":1,"maximum":268435456,"description":"The file's exact size in bytes."},"file_name":{"type":"string","maxLength":255,"description":"Shown back to the customer only. Never used as a path anywhere."},"activate":{"type":"boolean","nullable":true,"description":"Activate after installing. Omitted: a plugin is activated and a theme is not, the same defaults as the single-request install."}}}}}},"responses":{"201":{"description":"The new upload, with its part size, part count and expiry.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressUpload"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/uploads/{uploadId}":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"$ref":"#/components/parameters/WordPressUploadId"}],"get":{"operationId":"getSiteWordPressUpload","summary":"Read a resumable upload — its progress and which parts have arrived.","description":"While the upload is `open`, `received_parts` lists every part already stored with the right length, read from storage itself; a resuming client sends the rest. After `complete` the status moves to `assembling` and then `installed` or `failed` (with a `message` for the customer). An upload is bound to the site it was started on: any other site, or another organisation, gets `404`. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"responses":{"200":{"description":"The upload.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressUpload"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/wordpress/uploads/{uploadId}/parts/{partNumber}":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"$ref":"#/components/parameters/WordPressUploadId"},{"name":"partNumber","in":"path","required":true,"description":"1-based part number, up to the upload's `part_count`.","schema":{"type":"integer","minimum":1}}],"put":{"operationId":"uploadSiteWordPressUploadPart","summary":"Send one part of a resumable upload.","description":"The raw bytes of one part, as `application/octet-stream`. Every part is exactly `part_size` bytes except the last, which is the remainder; any other length is refused `422`. `X-Zinn-Part-Sha256` carries the part's SHA-256 (hex). A part whose bytes do not match it is refused `422` and not stored, so the client sends that part again. Sending a part twice is safe: it replaces itself. `409` once the upload has been completed or has expired.","tags":["hosting"],"parameters":[{"name":"X-Zinn-Part-Sha256","in":"header","required":true,"description":"Lower-case hex SHA-256 of this part's bytes.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"204":{"description":"The part is stored."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/wordpress/uploads/{uploadId}/complete":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"$ref":"#/components/parameters/WordPressUploadId"}],"post":{"operationId":"completeSiteWordPressUpload","summary":"Finish a resumable upload; the platform assembles and installs it.","description":"Every part must have arrived (`422` names the missing ones). `sha256` is the whole-file checksum, in either of two forms: the plain SHA-256 of the file (what `sha256sum` prints), or the composite form, the SHA-256 of the parts' raw SHA-256 digests concatenated in part order. A client can compute the composite one part at a time, without hashing the whole file at once. Answers `202` with the upload in `assembling`. The platform then streams the parts together and verifies the length and checksum. It installs with the same checks as `installSiteWordPressPlugin` / `installSiteWordPressTheme`, and the upload becomes `installed` or `failed`. Poll `getSiteWordPressUpload`. `503` if the installer is unreachable; the upload stays resumable and can be completed again.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["sha256"],"properties":{"sha256":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}}}}},"responses":{"202":{"description":"Accepted — the upload is being assembled and installed.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressUpload"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/wordpress/themes":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"listSiteWordPressThemes","summary":"List the themes installed on a site's WordPress.","description":"The same four facts as a plugin, from a different vendor endpoint: name, activation status, version, and the version waiting. `404` for a site with no vendor hosting package. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The installed themes.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressThemeList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}},"post":{"operationId":"installSiteWordPressTheme","summary":"Install a theme on a site's WordPress.","description":"Installs a theme, from the **wordpress.org directory** by `slug` (what `searchWordPressThemeDirectory` returns) or from a **zip the customer uploads**.\n\n⛔⛔ **This did not exist until W22-D, and its absence is the whole of the owner's complaint on 2026-08-16**: *\"no way in this or the main site manager bit to add new theme or uplaod one\"*. The platform could list, activate and delete a theme and had no way to put one on a site, so a customer could only ever choose among the three themes WordPress ships with — and could delete two of them.\n\n⛔ Exactly one of `slug` and `zip` — never both, refused rather than resolved by precedence.\n\n⛔ **`activate` defaults to `false` here and to `true` on the plugin path**, and the asymmetry is deliberate. Activating a plugin adds behaviour; activating a theme **replaces what every visitor sees**, immediately, on a live site. A customer uploading a theme to look at it must not have their shop re-skinned as a side effect of the upload.\n\n⚠️ An uploaded zip is **the customer's own code running on their own site**, and we do not review it. It is size-capped at **256 MB** (see the plugin install for how the limit is enforced and why a file must be sent as `multipart/form-data`) and rejected unless it is a valid archive containing a single top-level directory whose `style.css` carries a `Theme Name:` header, which is what WordPress itself requires. Note that a theme is **not** validated the way a plugin is: a block theme can legitimately contain no PHP at all, so a PHP-file check would refuse valid modern themes.\n\n⛔ **Fleet only.** this platform exposes no theme-install endpoint at any path, and its own control panel offers no install control on its Themes page either — both measured 2026-08-16. So this is refused on the managed hosting line, where `wp_theme_install` is `false`; the capability map on `getSiteWordPress` says so up front rather than letting the customer discover it by pressing the button.\n\nRequires `sites.view` and `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"slug":{"type":"string","maxLength":200,"pattern":"^[a-z0-9][a-z0-9-]*$","description":"A wordpress.org directory slug. Lower-case, digits and hyphens — the directory's own alphabet, enforced here so a path separator or a URL can never reach the box as a \"slug\".","example":"astra"},"zip":{"type":"string","format":"byte","description":"A base64-encoded theme zip, for small files only: the whole JSON body is capped at 32 MB, so this carries at most ~24 MB decoded and a larger body is refused `413`. Send anything bigger as `multipart/form-data`."},"activate":{"type":"boolean","default":false,"description":"Make this the site's active theme after installing. Defaults to `false` — see the asymmetry with the plugin path above."}}}},"multipart/form-data":{"schema":{"type":"object","additionalProperties":false,"required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"The theme zip, up to 256 MB. Streamed to disk on receipt, never held in memory; one byte over the limit is refused `413` with a sentence that states it."},"activate":{"type":"boolean","default":false}}}}}},"responses":{"201":{"description":"The site's themes after the install. The whole list rather than the one theme, because activating changes another row's status and a client that patched a single row into its cache would render two active themes.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressThemeList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/themes/{themeName}":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"themeName","in":"path","required":true,"description":"The theme's slug, exactly as `listSiteWordPressThemes` reports it. WordPress's identifier, not ours — percent-encode it.","schema":{"type":"string","minLength":1,"maxLength":255}}],"put":{"operationId":"setSiteWordPressTheme","summary":"Activate or deactivate a theme on a site.","description":"Switches the site's active theme and returns the whole theme list. Activating a theme changes what every visitor sees immediately, so the client confirms first. Refused `422` when the package type does not carry `wp_themes`, or when WordPress is not installed. `404` for a site with no vendor hosting package. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["active"],"additionalProperties":false,"properties":{"active":{"type":"boolean","description":"Whether the theme should be the site's active theme.","example":true}}}}}},"responses":{"200":{"description":"The theme list after the change.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressThemeList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}},"delete":{"operationId":"deleteSiteWordPressTheme","summary":"Remove a theme from a site's WordPress.","description":"Deletes the theme's files. The list is re-read afterwards, so a theme that survived the removal is a refusal rather than a reported success. `200` and the whole list, because the card renders the remainder from this answer. `404` for a site with no vendor hosting package. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"responses":{"200":{"description":"The theme list after the removal.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressThemeList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/themes/{themeName}/update":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"themeName","in":"path","required":true,"description":"The theme's slug, exactly as `listSiteWordPressThemes` reports it.","schema":{"type":"string","minLength":1,"maxLength":255}}],"post":{"operationId":"updateSiteWordPressTheme","summary":"Update one theme to its latest release.","description":"Updates a single theme and returns the whole theme list.\n\n⛔ **Its own path segment, not a field on the `PUT` beside activate/deactivate.** Updating replaces the theme's files on a live site; activating changes which one renders. A caller that got a body wrong must not be able to reach the first by aiming at the second — the rule every destructive operation on this surface follows.\n\nIdempotent: a theme already on its latest version is a successful no-op, so a caller may run this across a selection without first filtering to the ones that need it.\n\n⛔ **Fleet only** — this platform has no per-component update verb at any path (only `updateSiteWordPressCore`, which moves WordPress itself). Refused where `wp_component_updates` is `false`. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"responses":{"200":{"description":"The site's themes after the update.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressThemeList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/plugins/{pluginName}/update":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"pluginName","in":"path","required":true,"description":"The plugin's slug, exactly as `listSiteWordPressPlugins` reports it.","schema":{"type":"string","minLength":1,"maxLength":255}}],"post":{"operationId":"updateSiteWordPressPlugin","summary":"Update one plugin to its latest release.","description":"Updates a single plugin and returns the whole plugin list. The listing is re-read rather than patched: an update can deactivate a plugin whose new version declares a requirement the site does not meet, and a client shown an optimistic guess would render it as active.\n\nIdempotent, and its own path segment, for the same reasons as the theme twin above. ⛔ **Fleet only** — refused where `wp_component_updates` is `false`. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"responses":{"200":{"description":"The site's plugins after the update.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressPluginList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/cron":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"listSiteWordPressCronEvents","summary":"List a site's scheduled WordPress tasks.","description":"Every task in WordPress's own scheduler, soonest first, with when each is next due.\n\n⛔⛔ **This is the read that explains a site nobody can explain.** WP-cron does not run on a timer — WordPress fires it on an inbound page view — so a site with no traffic never runs it, and the customer sees no scheduled posts, no plugin licence renewals and **no error anywhere**. Every other control we own reports the site as healthy, because it is. A stuck queue is only visible if something looks at the queue.\n\n`next_run_relative` is the scheduler's own human phrasing (\"13 hours\", \"now\") carried through unchanged beside the machine timestamp, rather than a second derivation of \"when\" that would drift from it on every refresh.\n\n⛔ The **read is not gated** on the capability, so a client can render *\"scheduled tasks are not available on this line\"* alongside whatever it does know. this platform publishes no cron endpoint at any path, so this returns an empty list there and `wp_cron` is `false` on the capability map. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The site's scheduled tasks.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressCronEventList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}},"post":{"operationId":"runSiteWordPressCronEvent","summary":"Run one scheduled task now.","description":"Runs a single named task immediately and returns the queue as it then reads.\n\n⛔ The hook is **confirmed to exist before it is run**. Running an unknown hook fails with the scheduler's own words, which we would surface as \"we could not run it\" — true, unactionable, and indistinguishable from a real failure. Naming it back is the difference, so a hook that has since disappeared is a refusal that says so.\n\n⛔ This addresses **one named hook**, never \"everything currently due\". A button labelled with one task's name must not have the blast radius of the whole queue.\n\nRefused where `wp_cron` is `false`. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["hook"],"additionalProperties":false,"properties":{"hook":{"type":"string","maxLength":191,"pattern":"^[A-Za-z0-9_\\-]+$","description":"The hook name, exactly as `listSiteWordPressCronEvents` reports it. A closed alphabet, because this value reaches the scheduler as an argument — nothing a caller types can be read as a flag.","example":"wp_scheduled_delete"}}}}}},"responses":{"200":{"description":"The site's scheduled tasks after the run.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressCronEventList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/maintenance":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteWordPressMaintenance","summary":"Is the site showing WordPress's maintenance page?","description":"⛔ Asks **the site**, not our record of what we last set. The flag is a `.maintenance` file in the document root and WordPress writes it itself during a core update — so a site can be in maintenance mode without us ever having asked for it, and a screen reading our own memory would show \"live\" over a page serving *\"Briefly unavailable for scheduled maintenance\"*.\n\nUngated, like every read on this surface. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The current maintenance state.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressMaintenance"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}},"put":{"operationId":"setSiteWordPressMaintenance","summary":"Turn maintenance mode on or off.","description":"Hides the site behind WordPress's maintenance page, or brings it back.\n\n⛔ **Confirmed by re-reading the flag**, never by acknowledging our own request. The flag is a file in the document root, and a write that failed on a full disk or a read-only mount exits cleanly on some hosts — so acknowledging would tell a customer their shop is hidden while it is serving orders, or the reverse.\n\n⛔ `{\"enabled\": bool}` both ways, rather than two paths or a bare boolean body, so a client cannot turn maintenance mode **on** by sending a body it meant as \"off\".\n\n⛔ **Fleet only** — refused where `wp_maintenance` is `false`. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["enabled"],"additionalProperties":false,"properties":{"enabled":{"type":"boolean","description":"Whether the site should show the maintenance page.","example":true}}}}}},"responses":{"200":{"description":"The maintenance state after the change, re-read from the site.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressMaintenance"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/smart-updates":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"listSiteWordPressSmartUpdates","summary":"The site's recent smart updates, newest first.","description":"Up to five recent smart updates (docs/1135 §8) with their status, what they updated, how much of the page changed on the staging copy, and presigned before/after pictures. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"Recent smart updates.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteSmartUpdateList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"startSiteWordPressSmartUpdate","summary":"Update plugins and themes on a staging copy first, then live only if nothing broke.","description":"Queues a smart update (owner #1, docs/1135 §8): a fresh staging copy, a lab screenshot, the updates applied to the copy, a second screenshot, a health check (WordPress loads with its plugins; the copy answers without a 5xx) and a pixel comparison. Live is updated only when the copy is clean and less than `hold_at_permille` of the page changed; otherwise the run is `held` and live is untouched. The copy is removed on every path. Omit `plugins`/`themes` to take everything with an update available.\n\nRefused `422` when the plan has no staging, the account is not in good standing, the site already has a staging copy (it would be overwritten) or there is nothing to update; `409` while a run is in flight; `503` when the queue is unreachable. Requires `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartSmartUpdateRequest"}}}},"responses":{"202":{"description":"Queued. The body is the recent list, the new run first.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteSmartUpdateList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/smart-updates/schedule":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteWordPressSmartUpdateSchedule","summary":"The site's scheduled smart update window and what the last window did.","description":"Scheduled smart updates (docs/1135 §8.1): every day or one weekday, at an hour in the customer's time zone, a smart update starts on its own (the same run as `startSiteWordPressSmartUpdate`, listed with the others). A site with no schedule reads `enabled: false` with the default window. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The schedule.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteSmartUpdateScheduleResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setSiteWordPressSmartUpdateSchedule","summary":"Turn scheduled smart updates on or off and choose the window.","description":"Writes the window. Turning it on is refused `422` when the plan has no staging or the account is not in good standing (the same refusals as a clicked smart update), and for an unknown time zone. A window whose site has a staging copy, nothing to update, or a run already going is skipped and recorded in `last_outcome`; the schedule keeps its next window. Requires `sites.panel_access`; audited as `wordpress.smart_update_schedule`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteSmartUpdateScheduleInput"}}}},"responses":{"200":{"description":"The schedule as written.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteSmartUpdateScheduleResponse"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/wordpress/switches":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteWordPressSwitches","summary":"Search-engine visibility and debug mode, read from the site.","description":"The two on/off switches a WordPress manager offers: whether search engines are asked to index the site (`blog_public`) and whether `WP_DEBUG` is on.\n\n⛔ Read from **the site**, never our record of what we last set — a customer can tick \"Discourage search engines\" in wp-admin and a developer can edit `wp-config.php`. An empty object means the platform hosting this site has no such switches (a vendor package). Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The switches as the site reports them.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressSwitches"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}},"put":{"operationId":"setSiteWordPressSwitches","summary":"Turn search-engine visibility or debug mode on or off.","description":"Send one switch or both; an absent switch is left alone. Each is written, then **confirmed by re-reading the site**, and audit-logged as `wordpress.switch.<name>.<on|off>`. The response is the site's state as re-read.\n\n⛔ **Fleet only** — refused where `wp_maintenance` is `false`. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"additionalProperties":false,"properties":{"search_engines_visible":{"type":"boolean","description":"False ticks WordPress's \"Discourage search engines\" setting.","example":true},"debug_mode":{"type":"boolean","description":"Sets `WP_DEBUG` in `wp-config.php`.","example":false}}}}}},"responses":{"200":{"description":"The switches after the change, re-read from the site.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressSwitches"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/hardening":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteWordPressHardening","summary":"The site's security hardening checklist, read from the site.","description":"A WordPress manager's hardening checklist (Plesk WP Toolkit \"Security\" parity): the theme/plugin file editor, debug mode, `FORCE_SSL_ADMIN`, unique secret keys, an HTTPS site address, no account called `admin`, and XML-RPC.\n\n⛔ Read from **the site** (`wp-config.php`, options, users), never our memory. Only the named constants are read — never `DB_PASSWORD` — and a salt value never leaves the box, only whether the eight are unique. XML-RPC is the platform firewall's setting for the site. An empty `checks` list means the platform hosting this site has no checklist (a vendor package). Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The checklist as the site reports it.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressHardening"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/hardening/{check}":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"check","in":"path","required":true,"description":"The check to fix — one whose `fixable` is true.","schema":{"type":"string","enum":["file_editor_disabled","debug_off","force_ssl_admin","salts_unique"]}}],"post":{"operationId":"fixSiteWordPressHardening","summary":"Apply the one-click fix for one hardening check.","description":"Writes the fix (`DISALLOW_FILE_EDIT`, `WP_DEBUG` off, `FORCE_SSL_ADMIN`, or fresh secret keys with `wp config shuffle-salts`, which signs every user out), then **confirms it by re-reading the site**, and audit-logs `wordpress.hardening.<check>`. `force_ssl_admin` is refused while the site address is not HTTPS (it would lock the admin out). The response is the whole checklist as re-read.\n\n⛔ **Fleet only** — refused where `wp_maintenance` is `false`. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"responses":{"200":{"description":"The checklist after the fix, re-read from the site.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressHardening"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/update-policy":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteWordPressUpdatePolicy","summary":"What this site is set to update by itself, and where it has drifted.","description":"Returns three things that must never be collapsed into one: the **policy** an operator stored, what the site is **actually** configured to do, and the **drift** between them.\n\n⛔ A screen showing only the stored policy cannot tell a customer that the policy was never applied — which is the whole point. A decision is applied when a row changes, and the row that decides whether a WordPress updates itself lives on that WordPress, not in this platform's database. A customer can change any of it from wp-admin, a plugin can change it on activation, and a restored backup carries the old settings back.\n\n⛔ `observed_core` is `\"\"` when `WP_AUTO_UPDATE_CORE` is **not defined at all**, which is NOT the same as `off` — an undefined constant means WordPress applies its own default, which is `minor`. Rendering the first as the second would tell an operator their sites are not taking security releases when in fact they are.\n\n⛔ `observed_read` is `false` when the site could not be read (a managed hosting package, or a box that did not answer). An empty `drift` is only meaningful while it is `true`; otherwise an unreachable site renders as compliant, which is the worst default for a security setting.\n\nUngated read — requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The policy, the observation and the drift.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressUpdatePolicy"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}},"put":{"operationId":"setSiteWordPressUpdatePolicy","summary":"Set the site's auto-update policy and apply it to WordPress.","description":"Stores the policy **and writes it to the site in the same call**, then re-reads the site and returns what it found.\n\n⛔ Storing without applying is the defect this endpoint exists to avoid: a stored row saying `core: off` over a WordPress that is still updating itself is worse than no row, because the screen then says the operator's decision took effect. The response body is a fresh read, never an echo of the request.\n\n⛔ On a failed apply the policy row keeps `apply_error` **and** the call answers `422`. Only recording it would be a silent failure; only raising it would leave a stored policy nobody knows was never applied.\n\n`ring` is the **staged-rollout** ring this site belongs to — `canary`, `early` or `general`. It is a property of the site, not of the change, so an operator picks their canaries once and every later rollout inherits the choice.\n\n⛔ **Fleet only** — refused where `wp_update_policy` is `false`, because it is written with `wp config set` and `wp plugin auto-updates` and this platform publishes no equivalent. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["core","plugins","themes","ring"],"additionalProperties":false,"properties":{"core":{"type":"string","enum":["off","minor","all"],"description":"`minor` is WordPress's own default (security and maintenance releases); `all` includes major upgrades unattended; `off` disables core auto-updates.","example":"minor"},"plugins":{"type":"boolean","description":"Whether every plugin should auto-update.","example":false},"themes":{"type":"boolean","description":"Whether every theme should auto-update.","example":false},"ring":{"type":"string","enum":["canary","early","general"],"description":"The staged-rollout ring this site belongs to.","example":"general"}}}}}},"responses":{"200":{"description":"The policy after the change, re-read from the site.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressUpdatePolicy"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/cli":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"runSiteWordPressCli","summary":"Run one allow-listed WP-CLI command on the site.","description":"An audited WP-CLI console. Every invocation is recorded in the site's WordPress activity log with its argv and exit code — never its output.\n\n⛔ **Allow-listed, never arbitrary.** An unrestricted passthrough is remote code execution as the site user: `wp eval` runs arbitrary PHP, `wp db query` runs arbitrary SQL, and `wp --require=/tmp/x.php` loads code the caller chose before WP-CLI decides what to do. The permitted commands are reads and idempotent cache operations, listed by `listWordPressCliCommands`; anything else answers `422` naming the whole list.\n\n⛔ `config get` and `config list` are **deliberately absent** — they read `wp-config.php`, whose constants include the database password and the authentication salts.\n\n⛔ A **non-zero `exit_code` still answers `200`.** The console's product is what WP-CLI said, and mapping a bad argument onto a 4xx would put our error page over the diagnosis the customer asked for. A `422` means *we* refused the command, which is a different answer.\n\n⛔ The command travels in the **body**, not the path, so it never reaches a proxy or edge access log — `option get` names options a plugin may have stored a credential in.\n\n⛔ **Fleet only** — refused where `wp_cli` is `false`. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["command"],"additionalProperties":false,"properties":{"command":{"type":"string","maxLength":512,"description":"The WP-CLI command, with or without a leading `wp`.","example":"plugin list --format=json"},"allow_write":{"type":"boolean","default":false,"description":"Permit the write tier (plugin/theme install and update by WordPress.org slug, activate/deactivate, option update, cache flush, rewrite flush, search-replace…). `eval`, `db query`, `config`, credential commands, `--user_pass` and `--zip` are refused at every tier."}}}}}},"responses":{"200":{"description":"What WP-CLI said, whatever its exit code.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressCliResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/database/query":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"runSiteDatabaseQuery","summary":"Run one guarded SQL statement against the site's WordPress database.","description":"One statement, checked before anything reaches the site: a verb allow-list (reads `SELECT`, `SHOW`, `DESCRIBE`, `EXPLAIN`, `WITH`; writes `INSERT`, `UPDATE`, `DELETE`, `REPLACE` only with `allow_write`), no comments, no `INTO OUTFILE`/`LOAD_FILE`, no deliberate delays, and a `WHERE` clause on every `UPDATE`/`DELETE`. Schema changes and privileges are never run. Anything else answers `422` naming the rule.\n\n⛔ Reads run inside `START TRANSACTION READ ONLY`, so the database itself refuses a write the check missed. A write runs in a transaction that is **rolled back** when it touches more rows than the limit, and always when `dry_run` is set — that is the preview: it answers how many rows the write *would* change.\n\n⛔ `200` with `ok: false` when MySQL refuses the statement (its own diagnosis). The audit row records the verb and row counts — never the statement or its result. Requires `sites.view` and `sites.panel_access`. Fleet WordPress sites only.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sql"],"additionalProperties":false,"properties":{"sql":{"type":"string","maxLength":8000,"description":"One SQL statement. A trailing `;` is allowed.","example":"SELECT option_name FROM wp_options WHERE autoload = 'yes' LIMIT 10"},"allow_write":{"type":"boolean","default":false,"description":"Permit `INSERT`/`UPDATE`/`DELETE`/`REPLACE`."},"dry_run":{"type":"boolean","default":false,"description":"Run a write and roll it back, answering the rows it would change."},"max_rows":{"type":"integer","minimum":1,"maximum":500,"default":100,"description":"Rows returned for a read."}}}}}},"responses":{"200":{"description":"The result, or MySQL's refusal with `ok` false.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteDatabaseQueryResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/files":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"listSiteFiles","summary":"List one folder of the site, inside its WordPress root.","description":"The file editor's folder view. `path` is relative to the WordPress root (empty is the root). ⛔ `..`, absolute paths and links pointing outside the root are refused; `wp-config.php`, `.user.ini`, `php.ini` and the editor's backup folder are never listed or opened. Requires `sites.view` and `sites.panel_access`. Fleet only.","tags":["hosting"],"parameters":[{"name":"path","in":"query","required":false,"schema":{"type":"string","maxLength":1024,"default":""},"description":"The folder, relative to the WordPress root."}],"responses":{"200":{"description":"The folder's entries, or `ok` false with the reason.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteFileResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/files/content":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteFileContent","summary":"Read one text file of the site.","description":"Up to 1 MB of UTF-8 text, with its `sha256` — pass that back as `expected_sha256` when writing to refuse a write over a file that changed since. Same path rules as `listSiteFiles`. Requires `sites.view` and `sites.panel_access`. Fleet only.","tags":["hosting"],"parameters":[{"name":"path","in":"query","required":true,"schema":{"type":"string","maxLength":1024},"description":"The file, relative to the WordPress root."}],"responses":{"200":{"description":"The file, or `ok` false with the reason.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteFileResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}},"put":{"operationId":"putSiteFileContent","summary":"Replace or create one text file of the site.","description":"The current file is copied to `.zinn-file-backups/` (denied to the web) first, then the new content is written atomically (temporary file + rename). With `expected_sha256` the write is refused when the file changed since it was read. The audit row records the path, size and hashes — never the content. Requires `sites.view` and `sites.panel_access`. Fleet only.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["path","content"],"additionalProperties":false,"properties":{"path":{"type":"string","maxLength":1024},"content":{"type":"string","maxLength":1048576,"description":"The whole new content, UTF-8."},"expected_sha256":{"type":"string","pattern":"^([0-9a-f]{64})?$","description":"The `sha256` the file had when read."}}}}}},"responses":{"200":{"description":"Written (with the backup's path), or `ok` false with the reason.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteFileResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/abilities":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"listSiteWordPressAbilities","summary":"Our plugins' AI agent abilities on the site.","description":"The WordPress abilities Page Builder Sandwich, Tranzly, Zinn® Chat, Zinn® Cache, the Zinn® Reseller Toolkit and Zinn® SEO register on this site (pages, sections, blocks, kits, design, translation, jobs, SEO, support tickets, caching, reseller clients and more; docs/901), read from the site itself through each plugin's own MCP server, run on the worker as the site's administrator. `servers` says which plugin answered: `false` when it is not installed, is older than the version with AI agents, or its \"AI agents (MCP)\" switch is off.\n\n⛔ **Fleet only** (`wp_cli`). Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"responses":{"200":{"description":"The abilities, and which plugin servers answered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressAbilities"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/abilities/run":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"runSiteWordPressAbility","summary":"Run one of our plugins' abilities on the site.","description":"Runs a Page Builder Sandwich, Tranzly, Zinn® Chat, Zinn® Cache, Zinn® Reseller Toolkit or Zinn® SEO ability (see `listSiteWordPressAbilities`) as the site's administrator, with the plugin's own permission check, input validation and edition gate (free or Pro). Audited with the ability's name, never its input or result. No charge: AI abilities use the site owner's own AI key.\n\n⛔ Only our plugins' abilities (`pbs/…`, `tranzly/…`, `zinn-chat/…`, `zinn-cache/…`, `zinn-reseller/…`, `zinn-seo/…`); anything else answers `422`. The ability name travels in the body. **Fleet only.** Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ability"],"additionalProperties":false,"properties":{"ability":{"type":"string","maxLength":100,"pattern":"^(pbs|tranzly)/[a-z0-9][a-z0-9-]{0,80}$","example":"pbs/list-pages"},"input":{"type":"object","additionalProperties":true,"description":"The ability's input, matching its input schema."}}}}}},"responses":{"200":{"description":"The ability's result.","content":{"application/json":{"schema":{"type":"object","required":["ability","result"],"properties":{"ability":{"type":"string"},"result":{"description":"What the ability returned (its output schema)."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/wordpress/cli-commands":{"get":{"operationId":"listWordPressCliCommands","summary":"The WP-CLI commands the console will run.","description":"The allow-list, served rather than copied into each client.\n\n⛔ A client-side copy is a second authority that starts identical and drifts: the day a command is added, a stale client keeps refusing it while the engine runs it happily, and the day one is removed the client offers a command that answers `422`.\n\nPlatform-wide and identical for every customer; names no site. Requires authentication only.","tags":["hosting"],"responses":{"200":{"description":"Every permitted command, as space-joined strings, sorted.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WordPressCliCommandList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/wordpress/activity":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"listSiteWordPressActivity","summary":"What changed on this WordPress, and who changed it.","description":"Every change this platform made to the site's WordPress — plugins and themes installed, activated, updated or deleted, users created and demoted, core updates, search-replaces, maintenance mode, console commands and update-policy changes — newest first.\n\n⛔ Bounded twice, and both bounds are returned rather than assumed: a `window_days` window and a row `limit`. `AuditLog` is time-partitioned, so the window keeps the query off every historical partition and the limit keeps one very busy site from returning a response nobody can render. A screen that showed rows without stating the window would read as *\"this is everything\"*.\n\n⛔ `action` is a stable **code**, never a sentence — the client owns the wording, in every locale. `detail` carries the names of what changed and never a password, console output or an uploaded archive.\n\nRequires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The site's recent WordPress activity.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressActivityList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/vulnerabilities":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteWordPressVulnerabilities","summary":"Published advisories against the plugin and theme versions installed here.","description":"Joins the site's installed component versions to a public vulnerability feed, so the answer is about **the version this site runs** rather than about the plugin in general.\n\n⛔⛔ `checked: false` means **we could not assess this component**, not \"nothing found\". Every bespoke plugin, every premium plugin with no public listing and every advisory published in the last hour reads as unchecked. A client that renders an unchecked row as clean is making a safety claim the platform has no basis for — the one output this endpoint must never produce. `unchecked` counts them.\n\n⛔ `truncated` is `true` when the site has more components than one request will look up. A bounded answer that does not say it is bounded reads as a complete one.\n\n⛔ `fixed_in` is blank when the advisory is unfixed **or** names only an upper bound — \"affected at or below X\" does not mean \"fixed in X\", and reporting it as such would send a customer to a version that is still vulnerable.\n\nAvailable on **both** product lines: the inputs are the plugin and theme listings, which every WordPress surface answers. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"One row per installed plugin and theme.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressVulnerabilityReport"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/users":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"listSiteWordPressUsers","summary":"List the accounts on a site's WordPress.","description":"Every WordPress account on the install, with its roles and whether it is an administrator. ⛔ **This read requires `sites.panel_access`, unlike every other read on this surface**: it carries the email address of every account on the customer's site — personal data about the customer's own users — which a read-only member of the organisation has no reason to hold.\n\nThe rows come from two vendor endpoints behind two different capability flags (`wp_users` and `wp_admin_users`), and what the package permits decides which halves are merged. `is_administrator` is set from the endpoint a row came from, not guessed from a role string. `404` for a site with no vendor hosting package.","tags":["hosting"],"responses":{"200":{"description":"The WordPress accounts on the site.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressUserList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}},"post":{"operationId":"createSiteWordPressUser","summary":"Create an account on a site's WordPress.","description":"Adds a WordPress account. **The caller chooses the password** and it travels in the request only: it is never echoed in the response, never written to our records and never logged.\n\n`login` and `email` are checked against WordPress's own rules here, so the customer gets our sentence about a field they can see rather than WordPress's about one they cannot. Refused `422` when the package type does not carry `wp_users`, or when WordPress is not installed. `404` for a site with no vendor hosting package. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["login","email","display_name","password"],"additionalProperties":false,"properties":{"login":{"type":"string","maxLength":60,"pattern":"^[A-Za-z0-9 _.\\-@]+$","description":"The account's login name. WordPress caps `user_login` at 60 characters and rejects anything outside this character set, so both are enforced here rather than surfaced as a vendor error.","example":"editor"},"email":{"type":"string","format":"email","maxLength":100,"description":"The account's email address.","example":"editor@example.com"},"display_name":{"type":"string","maxLength":250,"description":"The name shown on the site's posts and comments.","example":"Site Editor"},"password":{"type":"string","format":"password","minLength":12,"maxLength":255,"writeOnly":true,"description":"The account's password. Write-only: it is accepted here and appears in no response, no log line and no error body."},"role":{"type":"string","maxLength":60,"description":"The role to create the account in — any role `listSiteWordPressRoles` reports for this install. Omit it (or send `\"\"`) for the platform's default, which is what a vendor with no role field must be sent.\n\n⛔ **Omitting this field used to be the only option, and the effect was that no customer could add an administrator to their own WordPress from our panel at all.** Every account created here landed as a `subscriber`, silently, including on hardware we own where any role can be created. The old refusal was correct about the managed platform — its create takes no role — and was applied to every platform, so a control the fleet has always supported was hidden behind a limitation of one vendor.\n\nRefused `422` on a platform that has no role field, rather than accepted and ignored. Asking for `administrator` additionally requires the package's administrator-management capability: creating one is taking over the site, so the lesser `wp_users` capability must not reach it.","example":"editor"}}}}}},"responses":{"201":{"description":"The created account. It carries no password.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressUser"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/users/{wpUserId}":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"wpUserId","in":"path","required":true,"description":"The account's WordPress id, exactly as `listSiteWordPressUsers` reports it. Carried as a string because it is the vendor's identifier, not ours.","schema":{"type":"string","minLength":1,"maxLength":64}}],"delete":{"operationId":"deleteSiteWordPressUser","summary":"Delete an account from a site's WordPress.","description":"Removes the account. ⛔ **The last remaining administrator cannot be removed** — the refusal is ours, `422`, before the vendor is called, because a WordPress with no administrator is a site the customer has locked themselves out of and no action of theirs restores it.\n\n`404` for a site with no vendor hosting package, and for an id that is not on it. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/users/{wpUserId}/password":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"wpUserId","in":"path","required":true,"description":"The account's WordPress id, as `listSiteWordPressUsers` reports it.","schema":{"type":"string","minLength":1,"maxLength":64}}],"put":{"operationId":"setSiteWordPressUserPassword","summary":"Set a WordPress account's password.","description":"Replaces the account's password with the one in the body. It has **its own path** rather than being a field on the user resource, for the same reason the destructive staging operations have theirs: a password reset and a delete must not be two shapes of one request.\n\n`204` and no body — there is nothing to return that is not either already known or a credential. The password is write-only: accepted here, echoed nowhere. `404` for a site with no vendor hosting package, and for an id that is not on it. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["password"],"additionalProperties":false,"properties":{"password":{"type":"string","format":"password","minLength":12,"maxLength":255,"writeOnly":true,"description":"The new password. Write-only: it appears in no response, no log line and no error body."}}}}}},"responses":{"204":{"description":"The password was changed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/users/{wpUserId}/role":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"wpUserId","in":"path","required":true,"description":"The account's WordPress id, as `listSiteWordPressUsers` reports it.","schema":{"type":"string","minLength":1,"maxLength":64}}],"put":{"operationId":"setSiteWordPressUserRole","summary":"Change a WordPress account's role.","description":"Replaces the account's roles with exactly the one in the body — the other half of \"add and remove administrators\", and the half that lets a customer fix a mistake without deleting somebody's account and their authorship along with it.\n\n⛔ **Replaces, never adds.** WordPress lets one account hold several roles at once, so granting the new role without removing the old one would leave a \"demoted\" administrator holding both — an account that reads as an editor on every screen and can still do everything. That outcome is indistinguishable from a successful demotion, which is why the distinction is stated here rather than left to the implementation.\n\nIts own path rather than a field on the user resource, for the same reason the password reset has one: a role change and a delete must not be two shapes of one request.\n\n**Promoting to `administrator` and demoting *from* one both** require the package's administrator-management capability, not merely `wp_users`. The promotion is obvious; the demotion matters just as much, because removing the last administrator's role locks every human out of the site as thoroughly as deleting them would. `422` for a role the install does not define, or a platform with no role field. `404` for a site with no vendor hosting package, and for an id that is not on it. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["role"],"additionalProperties":false,"properties":{"role":{"type":"string","minLength":1,"maxLength":60,"description":"The role the account should hold, from `listSiteWordPressRoles`.","example":"administrator"}}}}}},"responses":{"200":{"description":"The account, with its new role.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressUser"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/roles":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"listSiteWordPressRoles","summary":"List the roles a site's WordPress defines.","description":"The roles available on the install — the site's own, including any a plugin added, rather than a hardcoded list of WordPress's five defaults. `role` is the machine value and `name` the install's own label for it; a client renders `name` and sends `role`.\n\n`404` for a site with no vendor hosting package. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The roles the install defines.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressRoleList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/settings":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteWordPressSettings","summary":"Get a site's WordPress options.","description":"The WordPress options the vendor publishes, as an object keyed by the option name (`blogname`, `blogdescription`, …). An object and not a list, because the vendor publishes a map and the client renders one field per key — a new option therefore costs no change to this shape, the SDK, or any client that parses it.\n\n`404` for a site with no vendor hosting package. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The site's WordPress options.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressSettings"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}},"put":{"operationId":"setSiteWordPressSetting","summary":"Set one WordPress option on a site.","description":"Writes a single option and returns the whole option map. The option is named in the **body** rather than the path: unlike a plugin slug it is not a resource, and this platform writes one option per call, so one write endpoint is the honest shape.\n\n⛔ An option the vendor does not publish is refused `422` rather than written blindly — writing an unknown key into a live WordPress is how a site gets a setting nothing can read back and nothing can undo. `404` for a site with no vendor hosting package. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["option","value"],"additionalProperties":false,"properties":{"option":{"type":"string","maxLength":191,"description":"The option name, as `getSiteWordPressSettings` reports it. An option the vendor does not publish is refused.","example":"blogname"},"value":{"type":"string","maxLength":8192,"description":"The new value. May be empty — clearing a tagline is a legitimate edit, not a mistake to guess at.","example":"Example Shop"}}}}}},"responses":{"200":{"description":"The site's WordPress options after the write.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressSettings"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/checksum":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteWordPressChecksum","summary":"Check a site's WordPress core files against the published checksums.","description":"Compares the install's core files with WordPress.org's published checksums and names every file that differs. A modified core file is the classic signature of a compromise, so this is the read behind *\"has anything been tampered with\"*.\n\n`ok` is `true` when nothing differs. `404` for a site with no vendor hosting package. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The checksum report.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressChecksum"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}},"post":{"operationId":"repairSiteWordPressChecksum","summary":"Restore a site's modified WordPress core files.","description":"Asks the vendor to replace every core file that differs from the published checksum with the published one. Local modifications to core files are lost, which is the point — but a legitimate customisation living in core goes with them, so the client names the files back first.\n\n`202` and not `200`: the platform restores the files afterwards, so the report in the body may still list them. A security screen that says \"fixed\" before it is fixed is worse than one that says \"still checking\". `404` for a site with no vendor hosting package. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"responses":{"202":{"description":"The repair was accepted. The report is as it reads now.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressChecksum"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/database-check":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteWordPressDatabaseCheck","summary":"Check a site's WordPress database connection.","description":"Whether the install can reach its own database. One boolean, because that is the whole answer the vendor gives and inventing detail around it would be fiction: a `false` here is the difference between *\"my site is slow\"* and *\"my site is down\"*.\n\n`404` for a site with no vendor hosting package. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"Whether the install can reach its database.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressDatabaseCheck"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/search-replace":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"runSiteWordPressSearchReplace","summary":"Rewrite a string throughout a site's WordPress database.","description":"⛔ **Destructive and irreversible from this platform.** It rewrites every occurrence in the site's database, including inside serialised values, and this platform holds no copy of what was there before. the platform returns no body, so a refusal cannot be detected after the fact — every protection is in **front** of the call: the package must carry `wp_search_replace`, WordPress must be installed, and `search` must not be blank (an empty search rewrites every row in the database, and it is refused twice — at the field and again before the vendor call).\n\nThe client is required to take a typed confirmation naming the site.\n\n**Asynchronous.** Only the cheap refusals (capability, WordPress installed, blank search) run in the request; the safety backup and the rewrite run in the `SiteWordPressSearchReplaceWorkflow` (one per site, `hosting-provisioning` queue). In the request, a real site's backup outlived the request budget (BACKUPACCUM1114-SR). The two terms are held in a short-lived tenant-scoped row, never in workflow history (`search` can be a secret), and deleted when the rewrite ends. The `wordpress.search-replace` activity row (the search LENGTH only, never either term) is written when the rewrite HAS happened, `wordpress.search_replace_failed` (with a redacted reason) when it did not.\n\n`202` and no body. `404` for a site with no vendor hosting package. `409` (`refusal.hosting.wordpressSearchReplaceInFlight`) while a rewrite of this site is already running. `503` (`refusal.hosting.wordpressSearchReplaceUnavailable`) when the workflow engine cannot be reached; nothing was started and nothing was stored. The workflow starts once the request has committed; a start that fails after that writes `wordpress.search_replace_failed` (`reason` `in_flight` or `unavailable`) and deletes the terms. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["search","replace"],"additionalProperties":false,"properties":{"search":{"type":"string","minLength":1,"maxLength":8192,"description":"The string to find. Must not be blank: an empty search matches every row in the customer's database.","example":"http://example.com"},"replace":{"type":"string","maxLength":8192,"description":"What to put in its place. May be empty — deleting a string throughout the database is a legitimate migration step.","example":"https://example.com"}}}}}},"responses":{"202":{"description":"The rewrite was accepted and runs in the background, after its safety backup."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/reinstall":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"reinstallSiteWordPress","summary":"Reinstall the live WordPress on a site.","description":"⛔ **Destructive.** Replaces WordPress itself on the **live** site. It has its own path and takes no body, so it cannot be reached by flipping a field on `reinstallSiteWordPressStaging` — the platform separates the two with one nullable string, and one careless passthrough would make the live site reachable from a request that looks like a staging refresh.\n\nThe vendor's acknowledgement is checked separately from its result: this endpoint answers a success object rather than the result field every other vendor call uses, and an absent result is **not** a refusal — reading it as one would report a refused reinstall of a customer's live WordPress as completed.\n\n**Asynchronous.** Only the cheap refusals (capability, WordPress installed) run in the request; the pre-reinstall safety backup and the reinstall itself run in the `SiteWordPressReinstallWorkflow` (one per site, `hosting-provisioning` queue). In the request, a real site's backup outlived the request budget and every press answered `422` (BACKUPACCUM1114). The `wordpress.reinstall` activity row is written when the reinstall HAS happened, `wordpress.reinstall_failed` (with a reason) when it did not.\n\n`202` and no body. `404` for a site with no hosting package. `409` (`refusal.hosting.wordpressReinstallInFlight`) while a reinstall of this site is already running. `503` (`refusal.hosting.wordpressReinstallUnavailable`) when the workflow engine cannot be reached; nothing was started. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"responses":{"202":{"description":"The reinstall was accepted and runs on the platform's workflow queue."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/staging":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteWordPressStaging","summary":"Get a site's staging copies (any stageable hosting type).","description":"The staging copies of the site, and whether staging may be used at all. `permitted` travels beside `data` because they are different sentences to a customer: *\"your plan does not include staging\"* and *\"you have not made a staging copy yet\"* need different copy and different buttons, and collapsing them into an empty list produces wording that is wrong for one of the two cases in 58 languages.\n\n`404` for a site whose platform has no staging to manage. Requires `sites.view`.\n\n⭐ **Every stageable hosting type, not only WordPress** (owner 2026-11-05). Despite the `wordpress` segment, which is kept so existing SDKs and integrations keep working, this path serves WordPress, WooCommerce, plain PHP, static (PBN included), Node, headless CMS, Joomla and the other one-click PHP applications, Nextcloud, ownCloud, Python, Ruby and .NET. WordPress and WooCommerce (and a PHP site with a WordPress inside it) are copied with WordPress's own tools; every other stack is copied as a whole application (files, its own database and database user, and its stored address moved to the staging address). A stack that cannot have a staging copy is refused `422` with a sentence that names the reason, and a non-WordPress stack is refused `422` when the site is not on the Zinn® fleet.","tags":["hosting"],"responses":{"200":{"description":"The site's staging clones, and whether staging is permitted.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressStaging"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}},"post":{"operationId":"createSiteWordPressStaging","summary":"Copy a live site onto its staging copy (any stageable hosting type).","description":"⛔ **This copies live onto staging and can do nothing else.** It takes **no body**, so there is no field a caller could set to make it publish over the live site — that is `publishSiteWordPressStaging`, a different path with its own refusal. the platform itself distinguishes the two directions with one string in one field, which is precisely why they must not share an endpoint.\n\nAn existing staging copy is overwritten by the live site: that is what \"refresh my staging\" means, and it is the safe direction.\n\n⛔⛔ **`202` means accepted, never finished, and a client that treats it as finished will be wrong every time.** Copying a document root and a database takes far longer than any HTTP request may — ~30 s for an empty WordPress on the Zinn® fleet, and it scales with the site — so the copy runs on the platform's queue. The body carries the new entry in `operations`: poll `getSiteWordPressStaging` until it leaves `queued` and `running`, and read `message` if it ends `failed`.\n\n⭐ Refusals still arrive here, immediately: a site whose platform cannot stage is a `422` from this call, not a failed operation a minute later.\n\n`404` for a site whose platform has no staging to manage. `409` when another staging operation is already running for the site. Requires `sites.view` and `sites.panel_access`.\n\n⭐ **Every stageable hosting type, not only WordPress** (owner 2026-11-05). Despite the `wordpress` segment, which is kept so existing SDKs and integrations keep working, this path serves WordPress, WooCommerce, plain PHP, static (PBN included), Node, headless CMS, Joomla and the other one-click PHP applications, Nextcloud, ownCloud, Python, Ruby and .NET. WordPress and WooCommerce (and a PHP site with a WordPress inside it) are copied with WordPress's own tools; every other stack is copied as a whole application (files, its own database and database user, and its stored address moved to the staging address). A stack that cannot have a staging copy is refused `422` with a sentence that names the reason, and a non-WordPress stack is refused `422` when the site is not on the Zinn® fleet.","tags":["hosting"],"responses":{"202":{"description":"The clone was accepted. The state is the staging set as it reads now.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressStaging"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/staging/publish":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"publishSiteWordPressStaging","summary":"Push a site's staging copy back over the live site (any stageable hosting type).","description":"⛔ **The most destructive operation on the managed hosting line**: the live site's files and database are replaced by the staging clone's. Its own path, so no request aimed at any other staging operation can reach it.\n\n⛔⛤ **The one optional field, `mode`, selects SCOPE and never DIRECTION.** This path exists separately from `createSiteWordPressStaging` precisely so that no field can flip which way the copy runs — on managed shared hosting both directions are driven from a single value, and one passthrough endpoint would let a request reading as *\"refresh my staging copy\"* publish a stale clone over a live shop. Every value of `mode` copies staging onto live; it says only how much travels. A field that could change the direction must never be added here.\n\n⛔ **A scope the site's platform cannot honour is refused `422`.** Read `publish_modes` on `SiteWordPressStaging` first and offer only what it lists: the Zinn® autoscaling platform performs `files`, `db` and `both`, and managed shared hosting performs `both` only, because its staging operation takes no scope at all. That is a property of the platform, not of the customer's plan — a larger package does not add a database-only publish.\n\n⭐ **Every stageable hosting type, not only WordPress** (owner 2026-11-05): the same path pushes back a staging copy of WordPress, WooCommerce, PHP, static (PBN included), Node, headless CMS, Joomla and the other one-click PHP applications, Nextcloud, ownCloud, Python, Ruby and .NET. A safety backup of the live site is taken first. On a non-WordPress stack the live site keeps its own configuration files, every `.env` and its `robots.txt`, so it keeps its own database credentials (and its own runtime environment and .NET variables); the application's stored address is moved back to the live domain and the application is restarted on the new files. A stack that cannot have a staging copy is refused `422` with the reason.\n\nRefused `422` when the site has **no staging clone** — the platform does not check, and would happily publish an empty staging environment over a live shop. The client is required to take a typed confirmation naming the site.\n\n`202` because the publish continues at the vendor after the acknowledgement. `404` for a site whose platform has no WordPress to manage. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressStagingPublishRequest"}}}},"responses":{"202":{"description":"The publish was accepted and continues at the vendor.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressStaging"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/staging/reinstall":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"reinstallSiteWordPressStaging","summary":"Reinstall the WordPress on a site's staging copy (WordPress copies only).","description":"Replaces WordPress on the **staging** copy only. Refused `422` when there is no staging copy, so it can never be a live reinstall by another name — that is `reinstallSiteWordPress`, on its own path.\n\n`202` and the whole staging state, including the queued operation in `operations` — the reinstall runs on the platform's queue, so the status means *accepted* and the operation row is what says whether it finished. `404` for a site whose platform has no WordPress to manage. A staging copy of a non-WordPress stack has no WordPress to reinstall: `reinstallable` is `false` on its state and this call is refused `422`. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"responses":{"202":{"description":"The reinstall was accepted and is queued. The body is the staging state with the new operation in `operations`; poll `getSiteWordPressStaging` until it settles.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressStaging"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/wordpress/staging/{cloneId}":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"cloneId","in":"path","required":true,"description":"The clone id returned by `getSiteWordPressStaging`. The vendor's identifier, carried as a string.","schema":{"type":"string","minLength":1,"maxLength":128}}],"delete":{"operationId":"deleteSiteWordPressStagingClone","summary":"Delete a site's staging copy (any stageable hosting type).","description":"Removes one staging copy. The **live** site is untouched — this path is declared after the literal `publish` and `reinstall` segments precisely so a request to one of those can never resolve here.\n\n`202` and the whole staging state, because the removal continues at the vendor. `404` for a site whose platform has no WordPress to manage, and for an id that is not on it. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"responses":{"202":{"description":"The removal was accepted. The state is the staging set as it reads now.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteWordPressStaging"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/firewall":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteFirewall","summary":"Get a site's own firewall, the platform rules beneath it, and its flood status.","description":"The customer's own rules (`login`, `xmlrpc`, `rule_sets`, `trusted`, `admin_trusted_only`, `challenge_until`), the always-on platform rules (`platform_rules`, keys only — not editable), whether the newest save is live on the server (`apply_state`), and the flood guard's protection now (`flood`) and recently (`recent_floods`).\n\n`404` for a site that is not the caller's or is not on one of our servers. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The site's firewall.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteFirewall"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"updateSiteFirewall","summary":"Change a site's own firewall rules.","description":"A **partial** update: an absent field is left as it is. Every control only tightens the site; none can loosen a platform rule. `challenge_hours` turns on the \"check every visitor\" mode for that many hours (1-24; `0` switches it off) and it switches itself off on time. `admin_trusted_only` needs at least one trusted address, or the owner could not sign in — refused `422`. On a site whose `wordpress_controls` is false, a WordPress-only rule set, a stricter `login`, `xmlrpc: blocked` or `admin_trusted_only` is refused `422` too (docs/1170).\n\nAnswers `202`: the change is saved and pushed to the server as a background job; `apply_state` is `pending` until the server has proven it live, then `applied` (or `failed`, with `apply_error`). Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteFirewallUpdate"}}}},"responses":{"202":{"description":"Saved; being applied.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteFirewall"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/plugin-guard":{"parameters":[{"name":"siteId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getSitePluginGuard","summary":"What the plugin guard found on, or refused for, one site.","description":"L06 s1014 (docs/1027). The plugin guard refuses a blocked plugin or a phishing kit at every install and upload door, and a fleet scan finds what arrived another way (wp-admin, SFTP, a restore). Lists every open finding and everything resolved in the last 90 days, newest first: `state` is `reported` (found, left in place), `quarantined` (moved to the account's protected quarantine folder, nothing deleted), `refused` (stopped at a door), `restored`, or `gone`. Requires `sites.view`; 404 for a site that is not yours.","tags":["hosting"],"responses":{"200":{"description":"The site's findings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePluginGuard"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/sites/{siteId}/plugin-guard/hits/{hitId}/review":{"parameters":[{"name":"siteId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"hitId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"requestSitePluginGuardReview","summary":"Ask our team to check a plugin-guard finding you think is a mistake.","description":"Flags the finding for staff review (idempotent; it changes nothing on the site, so `sites.view` is enough). Audit-logged as `site.plugin_guard.review_requested`.","tags":["hosting"],"responses":{"200":{"description":"The finding, with `review_requested_at` set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginGuardHit"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/sites/{siteId}/plugin-guard/integrity/{findingId}/repair":{"parameters":[{"name":"siteId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"findingId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"repairSiteIntegrityFinding","summary":"Repair a site integrity finding now (re-install WordPress core files, quarantine unknown core files, put the site address back, or for an intrusion finding move the malware files to quarantine, demote the rogue administrators or remove the attacker hooks).","description":"L06 s1014 (docs/1027 §6). Runs in the background (202); the finding's state changes when it is done. Core files are re-installed at the site's OWN WordPress version, never wp-content. Requires `sites.panel_access`. Audit-logged as `site.integrity.repair_requested`.","tags":["hosting"],"responses":{"202":{"description":"The repair has started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteIntegrityFinding"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/plugin-guard/holds/{holdId}/release":{"parameters":[{"name":"siteId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"holdId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"releaseSitePluginUpdateHold","summary":"Release an update hold on your site so the held version can be applied again.","description":"L06 s1014 (docs/1027 §4). Only this site's own holds (a hold on every site is our team's to release). Requires `sites.panel_access`: releasing lets a version that broke this site be applied again. Audit-logged as `site.plugin_guard.hold_released`.","tags":["hosting"],"responses":{"200":{"description":"The site's holds after the release.","content":{"application/json":{"schema":{"type":"object","required":["holds"],"properties":{"holds":{"type":"array","items":{"$ref":"#/components/schemas/SitePluginUpdateHold"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/sites/{siteId}/turnstile":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteLoginCheck","summary":"Get whether the Turnstile login check is on for a site, and where a change is.","description":"Q335. The Cloudflare Turnstile check on the site's WordPress login, registration, lost password, comment and form pages (V1's method: one widget per site). `enabled` is what was last asked for; `status` is what the site has (`active` once the site read back the same plugin, sitekey and secret fingerprint). `busy` while a change is running; `step` is where it is (`queued`, `widget`, `site`, then `idle`). `stale` when a change has not finished 15 minutes after it was asked for (it never started) — the switch can be used again. `error_code` is a code the console words (`readonly`, `no_widget`, `not_supported`, `failed`), never an English sentence. `available` is `false` for a site that cannot carry the check (not WordPress, or not on one of our servers).\n\n`404` for a site that is not the caller's. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The login check's state.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteLoginCheck"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"updateSiteLoginCheck","summary":"Switch the Turnstile login check on or off for a site.","description":"Answers `202`: the request is saved and the change runs as a background job (it creates or deletes the site's widget and writes the site, which takes seconds). Poll the `GET` while `busy`. `places` chooses the forms the check protects (V1's `forms`; `all_places` on the `GET` lists them). `409` while an earlier change is still running, or when the site cannot carry the check. Audit-logged. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteLoginCheckUpdate"}}}},"responses":{"202":{"description":"Saved; the change is running.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteLoginCheck"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/turnstile/keys":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"put":{"operationId":"setSiteLoginCheckOwnKeys","summary":"Use your own Cloudflare Turnstile keys for a site's login check.","description":"Owner 1105#26. Paste the sitekey and secret of a Turnstile widget in YOUR Cloudflare account (its hostnames must include the site's domain). The secret is checked with one Cloudflare siteverify call, kept in Vault and never returned. `422` for keys that are malformed, Cloudflare's test keys, or a secret Cloudflare rejects. When the check is on, the site is switched to your keys by the background job (`202`; poll the `GET`) and the platform widget is deleted; when it is off, the keys are saved for when it is switched on (`200`). `409` while a change is running or for a site that cannot carry the check. Audit-logged. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteLoginCheckKeys"}}}},"responses":{"200":{"description":"Saved; the check is off, so nothing ran.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteLoginCheck"}}}},"202":{"description":"Saved; the site is being switched to your keys.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteLoginCheck"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"removeSiteLoginCheckOwnKeys","summary":"Stop using your own Turnstile keys; go back to the platform widget.","description":"Forgets your keys. When the check is on, the background job creates a platform widget and writes it to the site (`202`), and your secret is deleted from Vault once it is replaced; otherwise `200`. `409` while a change is running. Audit-logged. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"responses":{"200":{"description":"Done; the check is off.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteLoginCheck"}}}},"202":{"description":"The site is being switched to the platform widget.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteLoginCheck"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/turnstile/rotate":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"rotateSiteLoginCheckSecret","summary":"Give a site's platform Turnstile widget a new secret key.","description":"V1's `turnstile_rotate`. The background job asks Cloudflare for a new secret (the old one stays valid for two hours, so a visitor mid-login is not refused), writes it to the site and reads it back (`202`; poll the `GET`). `409` for a site on your own keys (rotate those in your Cloudflare account), with no widget yet, or while a change is running. Audit-logged. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"responses":{"202":{"description":"The secret is being replaced.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteLoginCheck"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/forms":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteForms","summary":"Get whether a site's own forms are on, and what its form needs.","description":"docs/1185. A static site's own `<form>` posts to `submitSiteForm` and is e-mailed to a mailbox on the site's own domain. `enabled` says whether the engine accepts that site's forms; `sitekey` is the PUBLIC Cloudflare Turnstile sitekey the page's widget carries (empty until forms were first switched on; the secret is never returned); `endpoint` is the form's `action`; `mailboxes` are the addresses a form may send to (active, receiving mailboxes on the site's own domain in the site's own organisation). `available` is `false` when there are none.\n\n`404` for a site that is not the caller's. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The site's form settings.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteForms"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"updateSiteForms","summary":"Switch a site's own forms on or off.","description":"ON creates the site's own Turnstile widget the first time (one Cloudflare call) and afterwards only flips a flag, so the sitekey on the page stays valid. OFF keeps the widget and refuses the site's submissions from the next request on (`not_enabled`). `409` (`refusal.siteForms.noMailbox`) when the site's domain has no mailbox to send to; `503` (`refusal.siteForms.notReady`) when the widget cannot be created just now. Audit-logged. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteFormsUpdate"}}}},"responses":{"200":{"description":"Saved; the new state.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteForms"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/origin-key":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteOriginKey","summary":"Where a site's origin-lock key rotation is.","description":"The key's `generation` (0 = the key the site was created with), whether a rotation is running (`state` `staged` or `overlap`), when the last one finished and, during the grace overlap, when the old key stops being accepted. Never the key itself.\n\n`404` for a site that is not the caller's or is not on one of our servers. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The site's origin-lock key state.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteOriginKey"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/origin-key/rotate":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"rotateSiteOriginKey","summary":"Rotate a site's origin-lock key, with no downtime.","description":"Replaces this ONE site's origin-lock key; no other site's key changes. Runs as a background job: the server is taught the new key alongside the old one and proven to accept it, the platform switches to the new key, and after a 15-minute grace window the old key is removed and proven refused. The site keeps serving throughout. Audit-logged.\n\nAnswers `202` with `state: staged`. `409` while a rotation is already running. `404` for a site that is not the caller's or is not on one of our servers. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"responses":{"202":{"description":"Rotation started.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteOriginKey"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/firewall/blocked":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"listSiteFirewallBlocked","summary":"List the newest requests the site's firewall refused.","description":"Refused requests (`403`/`429`) for the site's own hostnames, newest first, from the server's access log — at most 100, over the last `hours` (1-72, default 24). `reason` is a hint at the layer that answered (`secret_files`, `core_files`, `attack_tools`, `login`, `xmlrpc`, `admin_trusted_only`, a rule-set key, or `rule`), never a verdict. `available` is `false` when the log store could not be read — never an empty list that would read as \"nothing was blocked\". Requires `sites.view`.","tags":["hosting"],"parameters":[{"name":"hours","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":72,"default":24}}],"responses":{"200":{"description":"Refused requests.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteFirewallBlocked"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/protection":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteProtection","summary":"Get every protection control for a site.","description":"Blocked countries, blocked addresses, hotlink rules and password-protected folders, in **one** read. One endpoint rather than four, deliberately: each vendor read costs a driver build and an HTTP transport, the card renders all four together, and four endpoints would be four transports and four package lookups per render on an API that rate-limits per source IP (§2.16).\n\nThe `*_permitted` flags travel with the state so a screen never offers a control whose request is already known to be refused. `hotlink_allow_direct` is **null** when the vendor did not state it — distinct from `false`, because a toggle rendered from an unknown lies about the customer's site.\n\n`404` for a site with no vendor hosting package. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"Every protection control for the site.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteProtection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/protection/countries":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"put":{"operationId":"setSiteBlockedCountries","summary":"Replace a site's country rule.","description":"A **replace, not a patch**: the platform's endpoint replaces the list, and an empty list is its documented way to clear every country restriction — so *\"unblock everywhere\"* needs no second verb.\n\n⛔ `allow_only` inverts who can reach the customer's site: `false` blocks the listed countries, `true` blocks everyone **except** them. It is its own boolean rather than a mode string precisely because a free-form word invites each consumer to re-derive that, and getting it backwards takes the site off the internet for everybody.\n\nA value that is not a two-letter country code is refused `422` before the vendor is called, with our sentence. `404` for a site with no vendor hosting package. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["countries"],"additionalProperties":false,"properties":{"countries":{"type":"array","description":"The whole rule, as two-letter ISO 3166-1 alpha-2 codes. An empty array clears the restriction entirely.","items":{"type":"string","maxLength":8},"example":["CN","RU"]},"allow_only":{"type":"boolean","default":false,"description":"`false` blocks the listed countries. `true` makes the list an **allow**-list — only those countries reach the site, and everyone else is blocked.","example":false}}}}}},"responses":{"200":{"description":"Every protection control for the site, after the change.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteProtection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/protection/ip-addresses":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"put":{"operationId":"setSiteBlockedAddresses","summary":"Replace a site's blocked IP addresses.","description":"A replace, like the country rule: the array is the whole list, and an empty array clears it. Each address is canonicalised before it is stored, so the same address typed two ways cannot appear twice and a rule the customer thinks they removed cannot survive under another spelling.\n\nAn input that is neither an address nor a CIDR range is refused `422` before the vendor is called. `404` for a site with no vendor hosting package. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["addresses"],"additionalProperties":false,"properties":{"addresses":{"type":"array","description":"The whole block list. An empty array unblocks everybody. Values are canonicalised, so what comes back in `SiteProtection.blocked_addresses` is what is actually in force.","items":{"type":"string","maxLength":64},"example":["203.0.113.7","198.51.100.0/24"]}}}}}},"responses":{"200":{"description":"Every protection control for the site, after the change.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteProtection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/protection/hotlink":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"put":{"operationId":"setSiteHotlinkProtection","summary":"Replace a site's hotlink-protection rules.","description":"Decides who may embed the site's files from another site. `allowed_hostnames` are the sites permitted to do so; `extensions` are the file types the rule covers; `redirect_url` is where a refused request is sent instead, and an empty string means the request is simply refused.\n\nA replace rather than a patch, for the same reason as the two block lists: the vendor endpoint replaces the set. Extensions are normalised before they are sent — a leading dot and capitals are stripped — so what the customer typed and what is enforced cannot differ.\n\n`404` for a site with no vendor hosting package. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["allow_direct","allowed_hostnames","extensions"],"additionalProperties":false,"properties":{"allow_direct":{"type":"boolean","description":"Whether a request with no referrer — somebody opening the file's URL directly, and every search-engine image crawler — is allowed through.","example":true},"allowed_hostnames":{"type":"array","description":"The sites permitted to embed these files. The customer's own domain is included by the vendor; list the others.","items":{"type":"string","maxLength":253},"example":["cdn.example.com"]},"redirect_url":{"type":"string","maxLength":2048,"description":"Where a refused request is sent instead. Empty means the request is refused outright rather than redirected.","example":""},"extensions":{"type":"array","description":"The file extensions the rule covers, without a leading dot. An empty array means the rule covers nothing and is therefore off.","items":{"type":"string","maxLength":16},"example":["jpg","png","webp"]}}}}}},"responses":{"200":{"description":"Every protection control for the site, after the change.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteProtection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/protection/directories":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"protectSiteDirectory","summary":"Password-protect a folder on a site.","description":"Puts an HTTP password on one folder under the document root. `POST` and not a `PUT` of the whole set even though the vendor endpoint replaces it: the set is rebuilt by the engine from the entries the platform itself returned, precisely because we do not hold the other folders' passwords and must not ask a customer to re-enter them to protect a new one.\n\n⛔ **The response carries a password, and it is the only one on this surface that does.** Omit `password` and the engine generates a strong one; either way the value is returned **exactly once**, written to no record of ours, and readable back by no endpoint. The whole response is therefore a credential: a client displays it once and does not cache it, store it in a query cache, put it in a URL, or include it in an error report. `username` may not contain a colon or a space — `:` separates the name from the hash in an `.htpasswd` file, so a name containing one produces a file that parses into something other than what was written.\n\n`404` for a site with no vendor hosting package. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["directory","username"],"additionalProperties":false,"properties":{"directory":{"type":"string","maxLength":255,"description":"The folder to protect, relative to the document root. It is normalised before it is compared with what the vendor holds, so what is protected is the folder the customer meant.","example":"/staging"},"username":{"type":"string","maxLength":64,"pattern":"^[A-Za-z0-9._-]{1,64}$","description":"The name a visitor types. No colon and no space, because this is written into an `.htpasswd` file where `:` is the field separator.","example":"preview"},"password":{"type":"string","format":"password","minLength":12,"maxLength":128,"writeOnly":true,"description":"Optional. Omitting it means *generate one for me*, which is the path that guarantees a strong value. Write-only: whatever is sent here appears in no response, no log line and no error body."}}}}}},"responses":{"201":{"description":"The protected folder **and its password, returned exactly once**. Nothing stores it and no endpoint reads it back — a customer who does not keep it protects the folder again.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteProtectedDirectoryCreated"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/protection/directories/remove":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"unprotectSiteDirectory","summary":"Take the password off a folder on a site.","description":"Removes the folder's HTTP password. Everything in it becomes publicly readable again the moment this returns, so the client names the folder back before calling.\n\n⛔ A `POST` to a `/remove` sub-path rather than a `DELETE` with the folder in the URL, and the folder travels in the **body**: a directory contains slashes, and a percent-encoded `/` inside a path segment is rejected or silently decoded by enough proxies that it is not a contract worth betting a security control on.\n\nThe whole protection state comes back, so the card re-renders from the server's answer. `404` for a site with no vendor hosting package. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["directory"],"additionalProperties":false,"properties":{"directory":{"type":"string","maxLength":255,"description":"The folder, exactly as `SiteProtection.directories` reports it. Normalised the same way on both sides, so the folder that is unprotected is the one that was named.","example":"/staging"}}}}}},"responses":{"200":{"description":"Every protection control for the site, after the removal.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteProtection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/protection/file-permissions":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"checkSiteFilePermissions","summary":"Run the vendor's file-permission check on a site.","description":"⛔ **This `GET` RUNS the scan — it is not a cached read.** The vendor's read *is* the check, so it walks the site's filesystem. It is an explicit *\"check my permissions\"* action and must never fire on mount or on window focus.\n\n`check_id` is the handle the fix needs, and it is **nullable**: null means the vendor gave us no handle, so `actionable` is false and there is nothing to apply. `recommended` on each failure is nullable for the same reason — the platform sometimes names a file without naming a mode, and a guessed `644` would be applied to the customer's file.\n\n`404` for a site with no vendor hosting package. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The permission report the scan produced.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePermissionReport"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}},"post":{"operationId":"fixSiteFilePermissions","summary":"Apply the vendor's recommended permissions on a site.","description":"Changes file modes on the customer's **live** files to the vendor's own recommendation.\n\n⛔ **It takes no body, and that is the security property.** The check is re-run inside the same vendor conversation and the recommendation is applied against the handle that conversation just produced, so a stale `check_id` from a client cannot be replayed against files that have changed since. The only defensible input to an operation that alters file modes is the number the platform running it published moments ago.\n\nA report with nothing to fix is a `422` refusal rather than a silent success: *\"we changed nothing\"* and *\"there was nothing to change\"* are different sentences, and only one of them is reassuring. Files the vendor named without naming a mode are skipped, never sent with a guess.\n\n`404` for a site with no vendor hosting package. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"responses":{"200":{"description":"The permission report after the fix was applied.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePermissionReport"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/bulk-vendor-operation":{"post":{"operationId":"runBulkVendorOperation","summary":"Run one hosting-platform operation across many of your sites at once.","description":"Purge caches, fetch malware-scan results, regenerate sitemaps or set IP blocks for a whole selection of sites in **one call to the underlying hosting platform**, instead of one call per site.\n\n⛔ **This is a rate-limit control, not a convenience.** The upstream platform limits by source IP — the one thing an API key cannot smooth — so 400 sites purged one at a time is 400 requests through a shared outbound pool that every other integration also uses. Here it is 8. `vendor_calls` in the response is that number, returned so a client can see the guarantee holding; if it ever equals the number of sites, the batching has regressed.\n\n⛔⛔ **The response is per site and is never a bare success.** The platform answers per package and a batch can come back partially acknowledged, so results arrive in three disjoint lists that add up to `requested`:\n`succeeded` (the vendor confirmed it), `failed` (the vendor was asked and did not confirm, or the batch errored) and `skipped` (we could not ask at all — the site is not on a vendor hosting package, or it has no recorded package id). A client that renders only `succeeded` will tell a customer about 42 sites when they selected 50.\n\n⚠️ Only site ids are accepted, never vendor package ids: a package id is an integer anyone could type and the upstream platform would act on it regardless of which customer it belongs to. Ids are resolved inside the caller's own organisation.\n\n⛔ Two of the platform's bulk operations are deliberately **not** offered. Country-blocking appends a line to the site's `.htaccess` on every call and never removes it, so it is not safe behind a retry — set it per site instead. Bulk deletion would bypass the quarantine, audit and undo that the normal delete flow provides. Asking for either answers `422` naming the reason and the alternative.\n\nRequires `sites.view` and `sites.restart`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkVendorOperationRequest"}}}},"responses":{"200":{"description":"The operation ran. ⚠️ A `200` does **not** mean every site succeeded — read `failed` and `skipped`.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkVendorOperationResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/deleted":{"get":{"operationId":"listDeletedSites","summary":"List my deleted sites, and when each stops being recoverable.","description":"Sites deleted from the principal's orgs **in the last 90 days**, newest first, with **an unambiguous date for when its backup is purged and the site becomes permanently unrecoverable** (`purge_due_at`).\n\n⚖️ **Only rows that still have an action (owner ruling 2026-09-15, D26270).** A record deleted more than 90 days ago, a record already **purged** (the data is gone) and a record already **restored** (the site is back in `GET /v1/sites`) are never returned. The bound is enforced here rather than by a client, because a client filter over a cursor-paginated list is a claim about one page. The staff list, `GET /v1/admin/deleted-sites`, is not bounded.\n\n⛔ **`purge_due_at` is computed by the engine from the live retention policy and must never be recomputed by a client.** It comes from the same function the purge sweep selects on, so the date shown and the date acted on cannot drift. A client adding `deleted_at + 30` would be a second hardcoded number, and it would be wrong the moment an operator edits the policy (D-W15-10b).\n\n⛔ **`restorable` is a measurement, not a status.** It reflects a real check that the backup object exists in storage, so it is `false` — with `reason_code: no_backup` — for a site whose backup row claims success over bytes that were never written. A restore button over a backup that does not exist is worse than no button.\n\nRequires `sites.view` only: knowing which of your own sites were deleted, and by when they become unrecoverable, is not a privileged fact.","tags":["hosting"],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"within_days","in":"query","required":false,"description":"Only sites deleted in the last N days (at most the 90-day window). The sites list's collapsed \"Recently deleted\" panel asks for `within_days=7&limit=5` (owner decision D11, 2026-10-06).","schema":{"type":"integer","minimum":1,"maximum":90}}],"responses":{"200":{"description":"A page of deleted sites.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedSitePage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/deleted/{deletedSiteId}/restore":{"parameters":[{"name":"deletedSiteId","in":"path","required":true,"description":"The `DeletedSite` record id (not the site id).","schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"restoreDeletedSite","summary":"Restore a deleted site.","description":"Brings a deleted site back. Answers `202` — the site is rebuilt by a workflow, and returns to `suspended` rather than `active` until it is actually serving again.\n\n⛔ **The guard is re-evaluated on this request, never trusted from the button.** Between the list rendering and the click the customer may have recreated a site on the same domain, the retention window may have closed, or the purge may have run. A `422` carries the machine-readable reason (`no_backup`, `purged`, `domain_in_use`, `already_restored`, `abuse_hold`) so the client can say which it was.\n\nRequires `sites.create` as well as `sites.view`: a restore *creates* a live site.","tags":["hosting"],"responses":{"202":{"description":"The restore has started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedSite"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/deletion":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteDeletion","summary":"Get a site's scheduled deletion.","description":"Whether anything is scheduled for this site, when it fires, and whether it can still be stopped. This is also where the client reads `primary_domain` — the value the customer must type into `deleteSite` — so the instruction on screen and the check on the server come from one place and cannot drift apart.\n\n⛔ **`can_cancel` is its own field and must never be recomputed as `state == \"scheduled\"`.** Once the teardown starts, the request row still says `scheduled` while the site is already being deleted; a client doing its own arithmetic would offer the cancel button at the exact moment it can only fail.\n\nRequires `sites.view` only — a read-only member learning that their site is about to be deleted is the whole point, and hiding the countdown from them would mean the first they hear of it is the site being gone. `404` for a site with no vendor hosting package, or one that is not theirs.","tags":["hosting"],"responses":{"200":{"description":"The site's deletion state.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteDeletion"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"delete":{"operationId":"cancelSiteDeletion","summary":"Stop a site's scheduled deletion.","description":"Cancels the countdown and returns the site's deletion state, which will read `none`. Takes no body.\n\nScheduled backups paused while the deletion was scheduled; a successful cancel resumes them by queuing an immediate backup of the site (when its plan includes daily backups), which appears in `getSiteBackups` with trigger `scheduled` and does not use the on-demand allowance.\n\n⛔ **`DELETE` on the *deletion*, not `POST …/cancel`.** The resource being removed is the scheduled request, and giving the undo its own noun means no request body can ever turn a cancel into a delete by being slightly wrong.\n\nThe teardown is stopped **before** the row is marked cancelled, never the other way round: a failed stop leaves a still-scheduled row the customer can retry, while the reverse leaves a row saying \"cancelled\" above a workflow that deletes their site. `422` when nothing is scheduled or the teardown has already started; `503` when the stop could not be performed, in which case the deletion is still scheduled and the request is safe to repeat.\n\n`404` for a site with no vendor hosting package, or one that is not theirs. Requires `sites.view` **and** `sites.delete`.","tags":["hosting"],"responses":{"200":{"description":"The site's deletion state after the cancellation.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteDeletion"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/transfer/preview":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"previewSiteTransfer","summary":"Check whether a site could be transferred to another organization.","description":"Answers *\"would this go through, and what would it take with it\"* without writing anything. The sender's form calls this before it offers, so arrears and structural problems read as a checklist rather than as a failure after the fact.\n\n⛔ **`POST` for a read**, deliberately: the proposal has a body (a target organization and a domain choice), and putting a UUID in a query string would leave the receiving account's id in access logs and `Referer` headers.\n\n⛔ **The receiving account's arrears are NOT itemised to the sender.** When the target organization is what blocks the transfer, `details` carries a single `target_account` entry saying only that the receiving account has an outstanding balance its owner must settle. Itemising it would make this endpoint a way to read any organization's financial position by offering it a site. The receiver sees every number on their own accept screen, where it is their own data.\n\nRequires `sites.view` **and** `sites.transfer`. `404` for a site that is not theirs.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteTransferProposal"}}}},"responses":{"200":{"description":"Whether the transfer is allowed, and what would move.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteTransferPreview"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/transfer":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteTransfer","summary":"Get this site's most recent transfer offer.","description":"The latest offer for this site, in any state, so the site page can show either a pending handover or the outcome of the last one. A site that has never been offered answers `200` with `offer: null` — an empty state, not an error.\n\n`404` only when the caller cannot see the site: another tenant's id and an id that does not exist give the same body, so this is never an existence oracle. A caller who can see the site already knows it exists, so telling them it has no offer discloses nothing. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The site's most recent transfer offer, or `null` when it has never been offered.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteTransferState"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"offerSiteTransfer","summary":"Offer this site to another organization.","description":"Creates a transfer offer the receiving organization must accept. **Nothing moves until they do** — consent is two-sided in both directions, push and pull alike (owner ruling 2026-08-14).\n\n**What the receiver inherits.** The remaining paid term travels with the site: the subscription moves as-is, same period end, same locked price, same currency, so the receiver has the paid period free and is billed normally at renewal. No money moves, no credit note, no VAT event. Renewal is in the **subscription's** currency, not the receiver's.\n\n**`include_domain`** decides whether the domain registration, its DNS zone and records, and its mail travel too. Default `true`. With `false` the site moves alone and the receiver points a domain of their own at it — the sender keeps a renewable asset, and the receiver's site is not hostage to DNS somebody else controls.\n\n`409` when this site already has an offer waiting for a reply. `422` when the guard refuses: unpaid invoices, failed payments, active dunning, unbilled page-view or bandwidth overage, an unpaid wholesale statement, a plan shared with other sites, a staff-granted plan, a busy or non-active site, a running migration or import, a scheduled deletion, or a DNS zone the receiving account already holds. **Both organizations are checked, and both are checked again at accept time** — an offer may stand for fourteen days, and an account that was clear when it was made can be in arrears when it is accepted.\n\nRequires `sites.view` **and** `sites.transfer`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSiteTransfer"}}}},"responses":{"201":{"description":"The offer, now awaiting the receiving organization.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteTransfer"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"withdrawSiteTransfer","summary":"Withdraw this site's pending transfer offer.","description":"The sender takes the offer back. Takes no body and returns the offer, which will read `cancelled`.\n\n⛔ **`DELETE` on the *offer*, not `POST …/cancel`** — the resource being removed is the pending offer, and giving the undo its own noun means no request body can turn a withdrawal into something else by being slightly wrong.\n\n`404` when there is no pending offer. Requires `sites.view` **and** `sites.transfer`.","tags":["hosting"],"responses":{"200":{"description":"The withdrawn offer.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteTransfer"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/transfers":{"get":{"operationId":"listSiteTransfers","summary":"List every site transfer this account is a party to.","description":"Both directions in one list. `direction` is computed per request from the caller's own organizations — the same row is `outgoing` to one party and `incoming` to the other, so a stored direction would be wrong for one of its two readers.\n\n`org_ids` carries the caller's own organization ids. That is the value a customer gives to somebody who is transferring them a site: transfers are addressed by organization id rather than by email address, because resolving a recipient by email would turn the offer form into a way to discover whether an address has an account with us and whether it is in arrears.\n\nRequires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"Transfers in and out, newest first.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteTransferList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/transfers/{transferId}/accept":{"parameters":[{"$ref":"#/components/parameters/TransferId"}],"post":{"operationId":"acceptSiteTransfer","summary":"Accept an incoming site transfer.","description":"Takes ownership of the site. **This is the moment everything moves**, in one database transaction: the site, its subscription and paid term, its backups, links, CDN and edge bindings, security posture, placement and — when the offer included the domain — the registration, its DNS and its mail. Traffic, resource and vitals samples, support tickets, abuse reports and paid add-ons stay with the previous owner, because they are that party's record rather than a property of the site.\n\nTwo references into the previous owner's own accounts are **detached** on the way: the site's CDN/edge `connection` and the domain's registrar credential. Carried across, the new owner would be operating a stranger's provider account.\n\nMailbox passwords do **not** travel — they are vendor-side and are not ours to hand over. The new owner resets each one from the mail panel.\n\nThe guard runs again here, on both organizations, and `422` refuses with the reasons. Addressable only by the **receiving** organization: a sender cannot accept their own offer. `409` when the offer was already decided. Requires `sites.view` **and** `sites.transfer`.","tags":["hosting"],"responses":{"200":{"description":"The completed transfer.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteTransfer"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/transfers/{transferId}/decline":{"parameters":[{"$ref":"#/components/parameters/TransferId"}],"post":{"operationId":"declineSiteTransfer","summary":"Decline an incoming site transfer.","description":"Refuses the offer. Nothing moves and the sender keeps the site. The row is kept rather than deleted, so both parties can see what happened. `409` when the offer was already decided. Requires `sites.view` **and** `sites.transfer`.","tags":["hosting"],"responses":{"200":{"description":"The declined offer.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteTransfer"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/collaborators":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"listSiteCollaborators","summary":"Who this site is shared with.","description":"Per-site collaborators — one person's access to ONE site, rather than to the whole organisation. Every grant on this site, newest first, live and lapsed alike: a revoked grant is kept because *\"who could reach this site in March\"* is the question an incident asks, and a deleted row cannot answer it.\n\n⛔ Read and write share the `sites.collaborators.manage` permission. The list is the access-control state of the site — who else is in it, at what level, and why — and that is an account owner's business rather than a developer's. Among the customer roles only `owner` holds the key; `dev` deliberately does not, because a developer who could grant site access could grant it to themselves on a site they were never given.\n\nA site outside the caller's scope, and a site they can see but may not administer, both answer `404`. Same code, two reasons: a `403` on the second would tell a developer that a collaborator list exists on their client's site, and a `403` on the first is an existence oracle.","tags":["access"],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"The grants on this site, newest first.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SiteCollaborator"}},"page":{"$ref":"#/components/schemas/PageMeta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"shareSiteWithCollaborator","summary":"Share this site with one person.","description":"Grants one person access to this one site at one role, optionally until a date. The narrowing is enforced by Postgres row-level security on the site table itself, not by a filter in a query, so it applies to every endpoint on this API rather than to the ones somebody remembered.\n\n⛔ **Nobody is put into an organisation they did not agree to join.** Unless the address already belongs to a member of this site's organisation, it is invited in the same call — whether or not it has an account with us: an ordinary organisation invitation is sent at the `site_collaborator` role, the grant is returned with `status: pending` and a null `user_id`, and the organisation gains no membership for them until they accept. The answer has the same shape for an address with an account and one without, so this operation never discloses which is which. A person who is already a member at the `site_collaborator` role (they accepted before) is shared with directly and the grant is `active`. The moment they accept — which proves control of that inbox through the identity provider, so no id is ever guessed — the grant activates for that person. A pending grant narrows nobody: nothing is reachable until the accept. If the address already holds a pending invitation to the *whole* organisation the call is refused with `SITE_COLLABORATOR_ALREADY_INVITED` rather than quietly downgrading that invitation to one site.\n\n**What a collaborator may then do is the per-site role, on that site only.** A request whose path names a granted site is evaluated with the role's keys (`viewer` reads; `editor` adds `hosting.deploy.manage`, `sites.cache.purge`, `hosting.performance.manage`, `sites.wp_login`, `sites.panel_access`, `sites.restart`, `hosting.php.manage`; `manager` adds `hosting.backup.manage`, `hosting.ssl.manage`, `hosting.cdn.manage`, `hosting.applications.manage`, `hosting.import.manage`). A request naming any other site answers `404`, and a request naming no site — the collection endpoints and every organisation-level surface such as members, API keys and billing — carries only `sites.view`, so it is refused with `403`. Revoking a grant takes effect on the next request, whatever token the person is holding.\n\nEvery refusal carries its OWN `error.code`, because the status says what happened and only the code says what to do about it. `409` is about the world: `SITE_COLLABORATOR_ALREADY_GRANTED` (this person already has a live or pending grant here), `SITE_COLLABORATOR_ALREADY_A_MEMBER` (they are already an unrestricted member, so a grant would imply a restriction we are not applying — a lie in an access table) and `SITE_COLLABORATOR_ALREADY_INVITED` (above). `422` is about the request: `SITE_COLLABORATOR_EXPIRY_IN_THE_PAST` and `SITE_COLLABORATOR_REASON_REQUIRED`.\n\n⛔ Key on the code, never on `error.message`. The message is a sentence written for a person and it is translated; the code is the contract.","tags":["access"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCollaboratorCreate"}}}},"responses":{"201":{"description":"The grant, as created.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCollaborator"}}}},"400":{"description":"`INVITE_EMAIL_UNDELIVERABLE` — the address is on a reserved or undeliverable domain (RFC 2606 / RFC 6761), so the invitation email could never arrive. Nothing was written; enter the person's real address. The sentence is keyed (`refusal.invitation.emailUndeliverable`) and rendered in the reader's language.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/collaborators/{grantId}":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"grantId","in":"path","required":true,"description":"The grant to revoke.","schema":{"type":"string","format":"uuid"}}],"delete":{"operationId":"revokeSiteCollaborator","summary":"Revoke one person's access to this site.","description":"Ends the grant. The row is kept and marked revoked rather than deleted, so the audit question survives. When it was that person's last live grant in this organisation their `site_collaborator` membership is removed too — left behind it is a dormant unrestricted membership waiting for somebody to add a second role to it.\n\nIdempotent: revoking an already-revoked grant answers `204`, not `404` or `409`. A client retrying after a dropped response must not be told it failed.","tags":["access"],"responses":{"204":{"description":"Revoked, or already revoked."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/collaborator-roles":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"listSiteCollaboratorRoles","summary":"The per-site roles that may be granted here.","description":"The roles a collaborator may be given on this site, so a form offers only choices the engine will accept. Fixed today; it exists because the first time a plan tier or a reseller policy limits which per-site roles may be conferred, every screen that hardcoded three choices is silently wrong and one that asked is not.\n\n`collaborator_role_seeded` reports whether the underlying organisation role exists in this deployment. It distinguishes *\"nobody has been granted anything yet\"* from *\"the role catalogue was never seeded, so every grant will fail to narrow\"* — two states that otherwise look identical from an empty list.","tags":["access"],"responses":{"200":{"description":"The grantable per-site roles.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCollaboratorRoles"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/orgs/{orgId}/delegated-access":{"parameters":[{"$ref":"#/components/parameters/OrgId"}],"get":{"operationId":"listDelegatedAccess","summary":"Everybody this organisation has shared sites with, one row per person.","description":"Delegated access, seen from the person rather than from the site (W43-96, docs/736). One row per person — an address that has been invited and not yet accepted is a person too — with every site they hold, the role on each, and when they were invited, accepted and were last active. Paged over PEOPLE, keyset on the address, so a freelancer holding forty sites is one row and never split across a page boundary.\n\nLapsed grants (past their end date, not revoked) are listed with `status: expired`; revoked ones are not — they are history, and a site's own collaborator list keeps them. `last_active_at` is the last request the person made while a grant was live, stamped at most every five minutes; null means they have not used the access since it shipped.\n\nRequires `sites.collaborators.manage` in the organisation. An organisation outside the caller's scope, and one they can see without that key, both answer `404`.","tags":["access"],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"A page of people.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DelegatedPerson"}},"page":{"$ref":"#/components/schemas/PageMeta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setDelegatedAccess","summary":"Set exactly which sites one person holds, and the role on each.","description":"One call for every change to one person: invite them, add a site, change a role, remove a site. After it the person holds EXACTLY the sites in `sites`. Sites they already hold keep their grant and have the role (and, when `expires_at` is sent, the end date) updated in place; new sites are granted to somebody already in this organisation, and for anybody else — with an account or without — invited, with one invitation however many sites and no membership until they accept (the answer does not disclose whether the address has an account); sites left out are revoked. The whole call is atomic: one refused site leaves every other site as it was.\n\nThe same rules as sharing one site (`shareSiteWithCollaborator`) apply, with the same codes: `SITE_COLLABORATOR_ALREADY_A_MEMBER` (409), `SITE_COLLABORATOR_ALREADY_INVITED` (409), `SITE_COLLABORATOR_EXPIRY_IN_THE_PAST` (422) and `SITE_COLLABORATOR_REASON_REQUIRED` (422 — a new site for somebody with no reason on record). Two are this endpoint's own: `SITE_COLLABORATOR_SITE_NOT_IN_ORG` (422 — one code for \"no such site\" and \"a site of another organisation\", so it is not an oracle) and `SITE_COLLABORATOR_DUPLICATE_SITE` (422).\n\nSaving a person whose invitation has lapsed sends it again; saving one whose invitation is still live does not. To remove every site, use the revoke endpoint — an empty `sites` is refused, so an accidental untick of the last box is never a revoke.","tags":["access"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DelegatedAccessSet"}}}},"responses":{"200":{"description":"The person as they now stand.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DelegatedPerson"}}}},"400":{"description":"`INVITE_EMAIL_UNDELIVERABLE` — the address is on a reserved or undeliverable domain (RFC 2606 / RFC 6761), so the invitation email could never arrive. Nothing was written; enter the person's real address. The sentence is keyed (`refusal.invitation.emailUndeliverable`) and rendered in the reader's language.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/orgs/{orgId}/delegated-access/revoke":{"parameters":[{"$ref":"#/components/parameters/OrgId"}],"post":{"operationId":"revokeDelegatedAccess","summary":"Revoke one person from every site, or from chosen sites.","description":"Revokes the person's grants in this organisation — all of them when `site_ids` is omitted, or only those sites. Rows are kept and marked revoked. A pending person's invitation is withdrawn with their last pending grant. When nothing is left their `site_collaborator` membership is removed (`membership_removed`). Takes effect on the person's next request, in the app, the API and the CLI alike, whatever token they hold: a collaborator's reach is resolved from their live grants on every request.\n\nIdempotent — revoking somebody who holds nothing answers `200` with `revoked: 0`.","tags":["access"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DelegatedAccessRevoke"}}}},"responses":{"200":{"description":"What was revoked.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DelegatedAccessRevokeResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/ssh-keys":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteSshAccess","summary":"List a site's authorised SSH keys.","description":"Every public key that can open a shell on the site's hosting package, together with whether the package restricts SSH to a list of addresses. `ssh` has been rendered as an included plan feature since the Hosting tab shipped — from a vendor flag that really is `true` on both package types we sell — with no way anywhere in the product to upload a key, so until this resource existed the entitlement was sold and read by nothing.\n\n⛔ `ip_restricted` is its own field and must never be derived from `ip_allowlist == []`. The vendor answers \"no restriction\" as null, and an empty list rendered as a restriction would tell the customer they are protected when the truth is the opposite. `ip_allowlist_editable` is false today for a **vendor** reason rather than a plan one, so a client renders the list read-only instead of an editor that cannot save.\n\nA site that is not on a vendor hosting package has no such resource and returns `404`, exactly as an out-of-scope or unknown id does — never a `403`, never an existence oracle. Requires `sites.view` **and** `sites.panel_access`: the list is the access-control state of a shell on the customer's server, which is strictly more than the phpMyAdmin and file-manager access that key already names.","tags":["hosting"],"responses":{"200":{"description":"The site's authorised keys and its address restriction.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteSshAccess"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"post":{"operationId":"addSiteSshKey","summary":"Authorise a public key for SSH on a site.","description":"Files one public key under a handle and returns the key as it was stored. `201` and the created key rather than the whole list, because the list is re-read anyway: `can_create` is a property of the collection and the vendor's own key count moves with it.\n\n⛔ **What makes a key valid is checked in the service, not in this schema**, and the sentence the customer reads is the same whichever door they came through — including the one that says *\"that is your private key\"*. A line that is not a public key we accept, a handle outside `[A-Za-z0-9][A-Za-z0-9._-]{0,63}`, a duplicate handle, or a package type that does not include SSH are all `422` with our wording, before the vendor is called. So is an account that is not paying yet (a trial or unpaid account, `refusal.ssh.paidOnly`; it unlocks by itself once the account pays).\n\n`404` for a site with no vendor hosting package, or one that is not the caller's. Requires `sites.view` **and** `sites.panel_access` — this write grants a shell.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddSiteSshKeyRequest"}}}},"responses":{"201":{"description":"The key as it was stored on the package.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteSshKey"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/ssh-keys/{handle}":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"handle","in":"path","required":true,"description":"The handle the key is filed under, exactly as `getSiteSshAccess` reports it. Constrained to `[A-Za-z0-9][A-Za-z0-9._-]{0,63}`, so it never contains a slash — but it is the customer's own string, so percent-encode it rather than assuming.","schema":{"type":"string","minLength":1,"maxLength":64}}],"delete":{"operationId":"deleteSiteSshKey","summary":"Withdraw an authorised SSH key from a site.","description":"Removes the key from the package's authorised list. Whatever was signing in with it stops immediately, which is the point — a laptop that was lost is a key that has to stop working now rather than at the next deploy.\n\n`204` and no body: the client re-reads the list, because `can_create` and the vendor's key count both move with the removal and neither can be derived from the response to a delete.\n\n`404` for a site with no vendor hosting package, one that is not the caller's, or a handle that is not on it — the delete URL must not become a way to enumerate what exists elsewhere. Requires `sites.view` **and** `sites.panel_access`.","tags":["hosting"],"responses":{"204":{"description":"Withdrawn."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/cache/purge":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"purgeSiteCache","summary":"Clear a site's server-side cache.","description":"Drops what the hosting platform has cached for the site — everything, or one path. `202` and no body rather than `200`: the platform acknowledges the purge and the edge drops the object afterwards, so claiming \"done\" would be a promise about a moment we never observed. The client re-reads the cache resource, whose cacheability report is stale the instant a purge lands.\n\n⛔ Gated on `sites.cache.purge`, which this platform already minted for exactly this, and deliberately **not** on `sites.panel_access`: clearing a cache destroys nothing, *\"my change isn't showing\"* is the most common thing a customer or a support agent needs to do, and softer is correct here. `sites.view` is required alongside it, as everywhere on this surface.\n\nOn our own fleet it clears, in order, the site's object cache (Redis, by the site's key prefix), its LiteSpeed page cache and its CDN zone. ⭐ **Both server caches are cleared WITHOUT loading WordPress**, so the purge works on a site whose plugins crash — the site a customer is most likely to be rescuing. The page cache is purged at the server by this site's own LiteSpeed Cache tag (never the whole server's cache); the plugin's own purge also runs when the site loads. A purge that cleared nothing (the page cache exists and neither path reached it) is a `422`, never a `202`.\n\n`404` for a site that is not on our own fleet, or one that is not the caller's; `422` when the purge could not be completed.","tags":["hosting"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurgeSiteCacheRequest"}}}},"responses":{"202":{"description":"The purge was accepted by the hosting platform.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/plan":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSitePlanChoices","summary":"List the plans a site could move to, priced.","description":"Every catalogue plan this site could move onto, each already scored against the site, each priced with a prorated quote, and each refusal already applied. A customer who outgrew their package previously had no path at all: the adapter's `resize()` deliberately raises, pointing at a package-type change that nothing could perform.\n\n⛔ `blocked_reason` and `reason` are **stable codes, never prose**. The engine never sends a sentence a customer reads, because it would be one language on every screen (§2.7); the localised text is the client's. `blocked_detail` carries the numbers behind `usage_exceeds` so the screen can say *which* limit and by how much. Every money figure is an integer in minor units (§2.8) — never a float, never a formatted string — and `total_minor` and `credit_minor` are two fields rather than one signed number, because a screen that renders a negative total as a charge is a screen that took money for a refund.\n\nServes **our own fleet as well as the managed shared range** (#2271). On the fleet a plan names no vendor package template — the plan *is* its entitlement set, and applying it is a real `setquota` on a box we own — so `package_type` is an empty string there and the package-type refusals (`no_package_type`, `unknown_package_type`, `platform_mismatch`) cannot occur.\n\n`404` for a site whose platform has no plan to change, and **that set is narrower than \"not managed shared\"**: a **VPS** or **cloud server** is a machine we hand over where the billed unit is the machine (a resize belongs on the compute seam, and the platform itself refuses a cross-platform package-type change), and an **edge host** has no account at all. Also `404` for a site that is not the caller's. Requires `sites.view` **and** `billing.view`: this is a price list for the customer's own site, and support needs to see it to answer *\"what would an upgrade cost\"*.","tags":["hosting"],"responses":{"200":{"description":"The site's current plan and every plan it could move to.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePlanChoices"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"post":{"operationId":"changeSitePlan","summary":"Move a site onto another plan.","description":"Charges the prorated difference, moves the vendor package to the new type, and moves the subscription — in that order, for the reasons the engine's plan-change module records. The response states what actually happened rather than what was asked for: `package_type` is read back from the vendor after the move, and `charged_minor` is what the gateway captured.\n\n⛔ **`expected_total_minor` is a money guard, not a convenience.** It is the figure the customer was actually shown, and the change is refused `422` when the freshly-computed quote differs — a price that moved between the page rendering and the button being pressed (an FX recompute, a catalogue edit, the period rolling) must never be charged silently. It is optional only so a script may omit it deliberately. Every other refusal is `422` as well, with nothing charged and nothing changed: an incompatible package type, usage above what the smaller plan allows, a card decline.\n\n⛔⛔ **Two usage refusals, checked in this order** (#2089). First, **this site's** vendor-live counts against the target package type — databases, FTP accounts, subdomains — so a customer is told about the thing they can fix on the screen in front of them. Then **the whole account** against the plan being applied: sites, mailboxes, mailbox storage and disk, anywhere in the org's subtree, from the same `check_downgrade` the staff tariff endpoint uses. Until #2089 this endpoint ran only the first of those and the staff endpoint only the second, so the owner's ruling held on the path he does not use and failed on the one his customers do.\n\n⛔ **There is no override here.** The staff tariff endpoint has an audited `override_over_limit` because staff sometimes genuinely need to move an over-limit account; a customer overriding their own quota check is not an override, it is no check. A customer who cannot proceed must reduce usage or contact support.\n\n⭐ `getSitePlanChoices` marks an unaffordable plan `blocked_reason: \"account_over_limit\"` **before** the button is pressed, so this refusal should be unreachable from the UI. It is still enforced here: the picker is an affordance, not the control.\n\nServes **our own fleet as well as the managed shared range** (#2271). The money path is identical on both — prorate, order, charge, credit, supersede — and only the middle step differs: on managed hosting the vendor package moves to another template, on the fleet the box is told the plan's new disk and file allowances. ⛔ On the fleet that happens **after** the subscription is superseded, because the numbers to apply are read from the governing subscription; a failure there leaves the customer out of sync (their site's Storage card says the new allowance is still being applied) and never out of pocket.\n\n`404` for a site whose platform has no plan to change — a **VPS** or **cloud server** (the billed unit is the machine) or an **edge host** (no account at all) — or for a site that is not the caller's. Requires `sites.view` **and** `billing.payment.manage` — it charges a card, so the key that gates paying is the key that gates committing to a payment.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeSitePlanRequest"}}}},"responses":{"200":{"description":"What the plan change actually did, and what it cost.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePlanChangeResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/catalogue":{"get":{"operationId":"getComputeCatalogue","summary":"Get everything the server order screen is built from.","description":"The live provider / data-centre / machine-size matrix, merged with the tiers we actually sell. Nothing about a provider, a zone, a size or a stack optimisation is authored in a client: a combination a client invented is one the provider refuses *inside provisioning*, minutes after the customer chose it, where all they see is a machine that failed.\n\n⛔ **Sizes carry no price, ever.** Retail price is catalogue data the customer sees on the plan; the provider's own figure is cost, and a cost rendered beside a size is a margin leak. Every numeric on a size is nullable and a null stays null — a size rendered as \"0 GB RAM\" reads as a broken product where a blank reads as \"not stated\", which is what it is. `spec_source` says whether the sizes came from the provider or, when it published none, from our own sold tiers — in which case a size id **is** a plan code and the two collapse at order time. `can_order` is what lets a screen say *\"this cannot be ordered yet\"* instead of rendering a button that `422`s.\n\n`?target=` selects the range (Zinn® Cloud by default); a target that is not a compute product is `404`, never a `403`. `?org_id=` is required only of a caller who belongs to more than one organisation, and is `422` when omitted by one who does — picking \"the first org in scope\" would configure against an arbitrary tenant. Requires `sites.view`.","tags":["compute"],"parameters":[{"name":"target","in":"query","required":false,"description":"Which compute range to describe. Defaults to Zinn® Cloud, the branded product; the VPS range is the same seam with a different target.","schema":{"type":"string","maxLength":64}},{"name":"org_id","in":"query","required":false,"description":"The organisation to configure against. Required only when the caller belongs to more than one; omitted, it is their own.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The providers, our sold tiers, and whether anything can be ordered.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeCatalogue"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/offers":{"get":{"operationId":"listComputeOffers","summary":"List the dedicated server-auction machines on sale now, at our price.","description":"One-of-a-kind dedicated machines, each priced at quote time from its live measured cost (monthly, USD) beside its one-off setup fee. An offer can be sold to someone else at any second: the list is live, and a basket line holds the quoted figure for `lock_seconds` while the offer stands at the same cost, is re-priced when it changes, and refuses with the sold-out sentence when it is gone. Add one to the basket as a `compute_server` line with `plan_code` `metal_offer`, the offer's `spec` and `zone`. An organisation whose range has no account behind it gets an empty list. Requires `sites.view`.","tags":["compute"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"The organisation to list for. Required only when the caller belongs to more than one; omitted, it is their own.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The offers on sale now, cheapest first, and the quote lock window.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeOfferList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/compute/regions":{"get":{"operationId":"listComputeRegions","summary":"List the cloud regions a machine can be bought in right now.","description":"Every region of the Zinn® Cloud range that is both **buildable** (the live catalogue lists a machine size there) and **sold** (an orderable size carries a price there). Either alone is a region a customer could choose and then not buy, so neither is enough on its own.\n\nA region is a city identified by `slug`; the client translates it. `zone` and `provider` are echoed only so an order form can send the choice back to `POST /v1/compute/servers`. `closest` is the available region nearest the visitor's country (a geo hint, `null` when the country is unknown), for the order screen's \"closest to you\" default. Requires `sites.view`.","tags":["compute"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"The organisation to read for. Required only when the caller belongs to more than one; omitted, it is their own.","schema":{"$ref":"#/components/schemas/Uuid"}},{"name":"country","in":"query","required":false,"description":"ISO 3166-1 alpha-2 country to answer `closest` for. Omitted, Cloudflare's `CF-IPCountry` is used when present, else the organisation's own stored location (billing profile, order billing country, card country, recorded IP country — the chain that places an un-chosen site). It only pre-selects a region; the customer still chooses.","schema":{"type":"string","minLength":2,"maxLength":2}}],"responses":{"200":{"description":"The regions available now.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeRegionList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/regions/resolve":{"get":{"operationId":"resolveComputeRegion","summary":"Answer \"can I have a machine in this place?\" without placing anything.","description":"Free text — a city or a country — resolved against the regions available now.\n\n⛔ **A place we do not serve is never silently replaced by one we do.** `status` is one of `exact` (build there — `match` is set), `nearest` (we know the place and do not serve it: `alternatives` are the closest regions, with great-circle distance and an estimated round trip), `country` (a country was named: `alternatives` are our regions in it, with no distance, because a country is not a point) or `unrecognised` (nothing is guessed). `requires_confirmation` is `true` for everything but `exact`, and the customer's own choice goes back through the ordinary order. `latency_ms` is an estimate from distance, never a measurement. Requires `sites.view`.","tags":["compute"],"parameters":[{"name":"location","in":"query","required":true,"description":"Where the machine is wanted — a city or a country, in any spelling.","schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"org_id","in":"query","required":false,"description":"The organisation to resolve for. Required only when the caller belongs to more than one; omitted, it is their own.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The resolver's answer.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeRegionResolutionEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/vps/options":{"get":{"operationId":"getVpsAddonOptions","summary":"The paid options a VPS of a given size can carry.","description":"cPanel licences, backup tiers and additional disks, **already filtered to what this machine size can actually take** — with our price on each, in integer minor units.\n\n⛔⛔ **Filtered, not merely listed, and the filtering is the point.** this platform refuses cPanel below 2 GB of memory and price backups per machine size, so an unfiltered menu is a set of choices the vendor rejects *after* the customer has configured and paid. Their own order form disables exactly these; this endpoint is how ours does the same.\n\n⛔ `resizable` is `false` on this range and its `resize_reason` says why: this platform publishes no operation that changes a VPS's processor or memory after purchase. Disk, cPanel and backups are all separately purchasable; the machine itself is not. Requires `sites.view`.","tags":["compute"],"parameters":[{"name":"size","in":"query","required":true,"description":"The vendor's machine token (`vps-a` … `vps-i`).","schema":{"type":"string"}}],"responses":{"200":{"description":"The options this size can carry.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/ComputeVpsOptions"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/compute/vps/quote":{"get":{"operationId":"quoteVpsConfiguration","summary":"What one configured VPS costs, itemised.","description":"A **pure read** - it opens no transport, writes nothing and charges nothing. The order screen calls it on every change so the customer sees the real total before committing, rather than a machine price that grows at checkout once the options are applied.\n\n⛔ The machine's own figure comes from its **plan**, never from the add-on catalogue. Two sources for one price is how a configurator and a checkout come to disagree. Requires `sites.view`.","tags":["compute"],"parameters":[{"name":"size","in":"query","required":true,"schema":{"type":"string"},"description":"The vendor's machine token (`vps-a` … `vps-i`)."},{"name":"interval","in":"query","schema":{"type":"string","enum":["monthly","yearly"],"default":"monthly"}},{"name":"image","in":"query","schema":{"type":"string"},"description":"The operating-system token. Only Windows carries a price."},{"name":"cpanel","in":"query","schema":{"type":"string"},"description":"A cPanel licence (`cpaneladmin`, `cpanelpro`, `cpanelplus`, `cpanelpremier`)."},{"name":"backup","in":"query","schema":{"type":"boolean"}},{"name":"disk_gb","in":"query","schema":{"type":"integer"},"description":"An additional disk in GB. 50-250 in tens, 250-1000 in fifties, 1000-2000 in hundreds."}],"responses":{"200":{"description":"The itemised price.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/ComputeVpsQuote"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/compute/servers":{"get":{"operationId":"listComputeServers","summary":"List the servers in scope.","description":"Every machine the caller can see, or — with `?org_id=` — one organisation's. The scoped form is what a reseller's console sends. An organisation outside the readable scope narrows to nothing rather than `403`-ing, exactly as `listSites` does: a `403` would confirm the organisation exists.\n\n⛔ **Resolved from our own rows, not from the provider's listing**, which is every customer on the reseller account. `status` is ours (how far the order got) and `power_state` is the machine's (what it is doing now); they are separate facts and rounding the provider's word into ours would silently make an unrecognised state `active`, which is what unlocks the power and resize controls. `operable` is read rather than re-derived from `status`, so a screen never offers a control the engine refuses.\n\nRequires `sites.view`.","tags":["compute"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"Narrow the list to one organisation the caller can read.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The servers in scope.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServerList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"post":{"operationId":"orderComputeServer","summary":"Order a server.","description":"Buys a machine. `202` and the pending server: the purchase is durable and runs off the request path as a Temporal workflow (§2.9), so the client polls the returned server until `status` leaves `provisioning`.\n\n⛔ **The row is written first and the workflow started second.** The reverse would mean a workflow whose row does not exist yet, and its first activity would fail on a race it can never win. The row's id is also the workflow id and the machine's name at the provider, which is what makes the whole path idempotent. If the workflow service cannot be reached the order is refused `503` with nothing charged — an acceptance is never fabricated, because the customer would watch a spinner for a server that was never ordered and then order it again.\n\nSend either `spec` or `plan_code`; neither is `422`, not a `500`. `org_id` is required only of a caller who belongs to more than one organisation, and naming one they cannot create in is `403`. A size, zone or disk/bandwidth pair the provider does not offer, or a name already taken, is `422` in our wording. Requires `sites.view` **and** `billing.entitlement.manage` — ⛔ **not** `sites.create`, which is what this was until #1682. Ordering a machine charges Zinn®'s reseller balance immediately and bills nobody, so it is deliberately a STAFF key; `sites.create` is held by the customer `dev` role.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderComputeServerRequest"}}}},"responses":{"202":{"description":"The order was accepted; the server is being provisioned.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServer"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/metered":{"post":{"operationId":"orderMeteredComputeServer","summary":"Order a server paid for by the hour from the account balance.","description":"W43-47, `docs/687`. **Charges nothing now.** The same refusals as any order apply (verification, SSH keys, zones, sizes), and three more: the account must be active, the range must be one we hold the provider account for, and the balance must cover `min_funded_hours` (24) at the machine's rate. A first pay-by-the-hour order grants the one-time Cloud trial credit — $10, converted into the account's own currency — before that check. Every started hour is then rated at the pinned rate, never exceeding the monthly price in a calendar month, and drawn from the balance with tax as a `compute_usage` order. A card on file is never charged for these hours. `term_months` is ignored: a metered machine has no term.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderComputeServerRequest"}}}},"responses":{"202":{"description":"The machine is recorded as `pending` and its build has started.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServer"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/spend-cap":{"get":{"operationId":"getComputeSpendCap","summary":"Read the organisation's monthly limit on metered compute.","tags":["compute"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"Required only when the caller belongs to more than one organisation.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The limit, and what has been rated against it this month.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeSpendCap"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setComputeSpendCap","summary":"Set or clear the organisation's monthly limit on metered compute.","description":"When this month's usage (pay-by-the-hour hours plus traffic over any server's allowance) reaches the limit, the organisation's pay-by-the-hour machines are stopped within the hour (a warning is sent at 80 % and at 100 %), and they start again within the hour of the limit being raised or the month turning. ⛔ A stopped machine still exists and is still rated by the hour; deleting it is what stops the billing.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetComputeSpendCapRequest"}}}},"responses":{"200":{"description":"The limit as it now stands.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeSpendCap"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/compute/trial-credit":{"get":{"operationId":"getComputeTrialCredit","summary":"Read the organisation's one-time Cloud trial credit.","description":"Whether the organisation may claim the trial credit now (and if not, why), the amount a claim gives in its billing currency, and what is left of a claimed one. The credit pays only for the trial products (the entry VPS, managed Redis and Kubernetes nodes), never for GPU servers or bare metal (docs/1124).","tags":["compute"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"Required only when the caller belongs to more than one organisation.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The trial credit's state for this organisation.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeTrialCredit"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"claimComputeTrialCredit","summary":"Claim the one-time Cloud trial credit.","description":"For a new customer with a confirmed e-mail address and a verified card on file. Nothing is charged. One per person, card and browser across accounts; refused with 422 and the reason otherwise.","tags":["compute"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimComputeTrialCreditRequest"}}}},"responses":{"201":{"description":"The credit was given; the state as it now stands.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeTrialCredit"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/compute/servers/{serverId}":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"get":{"operationId":"getComputeServer","summary":"Get one server, with the provider's live state merged in.","description":"One machine, refreshed against the provider. The refresh is best-effort and never fails the screen: the row is what we know, the merge is an improvement on it, and a `503` on a detail page would hide a server the customer owns.\n\n`power_state` has six values rather than two, and the four extra ones are the whole point — a machine mid-transition is not \"on\". A `stopping` server rendered as running with an enabled Stop button is a customer pressing Stop twice and filing a ticket, and an unread state rendered as \"off\" is worse: it invites a Start on a machine that is already running. `unknown` is the honest answer when the provider stated none and is never collapsed into `off`. A client polls on the three transitional values and on `status: provisioning`.\n\n`404` for a server that is not the caller's or does not exist — the tenancy boundary of this surface is our own rows, and out-of-scope and nonexistent give the same answer on purpose. Requires `sites.view`.","tags":["compute"],"responses":{"200":{"description":"The server.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServer"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/resize/quote":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"post":{"operationId":"quoteComputeServerResize","summary":"Get what resizing a server would cost, before the charge.","description":"The provider's own figure for moving this machine to another size. A `POST` that changes nothing, deliberately: the size being quoted is a body field, and a quote is not a cacheable representation of a resource. ⛔ Showing it is not optional — an upgrade charged at an unstated amount is a refund request (§2.8).\n\n⛔ `amount` is the provider's own **string**, unparsed, and it carries **no currency field**. Inventing one to fit a money type would put a number in front of a customer in the wrong currency, so a client renders it exactly as the provider stated it and labels it as the provider's estimate.\n\n`404` for a server that is not the caller's; `422` for a size the provider does not offer or a machine that is not in an operable state. Requires `sites.view` — reading a price commits to nothing.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeResizeRequest"}}}},"responses":{"200":{"description":"The provider's estimate for the resize.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeResizeQuote"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/usage":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"get":{"operationId":"getComputeServerUsage","summary":"One server's metered hours, charges and ledger check for a month.","tags":["compute"],"parameters":[{"name":"period","in":"query","required":false,"description":"The month, `YYYY-MM` (UTC). Defaults to the current month.","schema":{"type":"string","pattern":"^[0-9]{4}-(0[1-9]|1[0-2])$"}}],"responses":{"200":{"description":"The month's usage.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServerUsage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/compute/servers/{serverId}/resize":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"post":{"operationId":"resizeComputeServer","summary":"Move a server onto another machine size.","description":"Performs the upgrade and returns the server's new state. ⛔ **This charges immediately at every provider we support**, so it is only ever reached from a quote the customer has read (`quoteComputeServerResize`). The engine attaches an idempotency key derived from the server and the target size, so a retry cannot buy the resize twice.\n\n⛔⛔ **A size whose disk is smaller than what the machine is already using is refused with a `422`, and that is a data-loss gate rather than a tidiness check.** The provider's endpoint is an *upgrade* endpoint and usually refuses a shrink, but \"usually\" is not a promise to make about a customer's files. Before a shrink the engine reads the machine's live disk usage and requires the target to be strictly larger. It **fails closed**: if the provider does not answer, or answers `-1` (\"did not say\"), the resize is refused rather than attempted — `-1 < anything` would otherwise read as \"plenty of room\". Growing is never gated, never pays for the extra read, and never fails because usage statistics were unavailable. RAM is not gated: running with less memory loses nothing on disk and is the customer's call.\n\n`404` for a server that is not the caller's; `422` for a size the provider does not offer, a machine that is not `active` — an order still running would have two writers, and a failed or released one has nothing to write to — or a shrink below the disk in use; `422` `refusal.compute.accountHoldResize` when the account is on hold (§2.46, checked before anything moves; staff organisations are exempt). The MCP `compute_server_resize` tool runs this same path. Requires `sites.view` **and** `billing.payment.manage` — ⛔ **not** `sites.create`, which is what this was until #1682.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeResizeRequest"}}}},"responses":{"202":{"description":"On every range whose provider account we hold (`own_cloud`, `aws_cloud`, `gcp_cloud`) the resize runs as a durable workflow — stop, wait until off, change size, start again — and the server comes back at `resizing`. It returns to `active` when the workflow settles, with `message` saying why if it could not finish. A metered machine is re-priced from the next hour.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServer"}}}},"200":{"description":"The server after the resize.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServer"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/power":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"post":{"operationId":"setComputeServerPower","summary":"Start, stop or reboot a server.","description":"Asks the provider to change the machine's power state and returns the server's whole new state, which the client writes straight into its cache.\n\n⛔ **The answer carries the transitional state, never the destination.** Power at the provider is asynchronous — the request is accepted long before the machine is up — so writing `on` the instant Start is accepted would be a dashboard asserting an observation it never made. The engine answers `starting`, the detail screen begins polling on that, and nothing in between ever renders the old state as if the button had done nothing.\n\n`404` for a server that is not the caller's; `422` for a machine that is not `active`. Requires `sites.view` **and** `sites.restart`, which is already the \"make this thing stop and start again\" authority.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputePowerRequest"}}}},"responses":{"200":{"description":"The server after the power request was accepted.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServer"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/renew":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"post":{"operationId":"renewComputeServer","summary":"Extend a server's term.","description":"Buys more months on an existing machine and returns the server with `term_months` grown by what was asked. ⛔ **This charges immediately**, and — unlike a resize — there is deliberately **no quote operation to read first**. That asymmetry is real rather than an omission: a resize is priced by the provider, whereas a renewal is priced by the plan the customer is already on, and no figure on this surface carries it (a machine size has no price by design, and a server carries only a `plan_code`). A client says out loud that it cannot show a figure rather than inventing one (§2.8). The engine attaches an idempotency key derived from the server and the term, so a retry cannot buy the extension twice.\n\n`404` for a server that is not the caller's; `422` for a term outside 1…36 months, or a machine that is not `active`. Requires `sites.view` **and** `billing.payment.manage` — ⛔ **not** `sites.create`, which is what this was until #1682.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeRenewRequest"}}}},"responses":{"200":{"description":"The server after the term was extended.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServer"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/health":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"get":{"operationId":"getComputeServerHealth","summary":"Read a server's hardware and live resource usage.","description":"What the machine is made of - cores, memory, disk, operating system - and how hard it is working right now: CPU, memory, disk and this month's bandwidth. Read live from the provider on every call and never stored, for the same reason the renewal is: a cached CPU reading is stale the moment it is written, and a customer looking at a usage gauge is asking about now.\n\nEvery usage figure is `-1` when the provider did not answer, which is **not** the same as zero. A client must render the difference: `0%` says the machine is idle, `-1` says we could not ask. Memory and disk are byte counts with both halves of the ratio, so a screen can say \"224 MB of 1 GB\" rather than only a percentage.\n\n`power_state` is the provider's own word (`running`, `shut off`), carried verbatim and never rounded to a boolean.\n\nThis response deliberately carries **no hostname**. The provider also states the guest hostname and the physical KVM host; both name our supplier and are never exposed to a customer. Requires `sites.view`.","tags":["compute"],"responses":{"200":{"description":"The machine's hardware and live usage.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServerHealth"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/services":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"get":{"operationId":"listComputeServerServices","summary":"List the services running inside a server.","description":"The machine's own service units - its web server, its database, its FTP daemon and a PHP-FPM pool per website - with the state the provider reports for each, read live.\n\nThis is the answer to \"is my database actually running\", which is otherwise only visible by the site being down. Read-only: it reports state and changes none of it. Acting on what it reports is `runComputeServerServiceAction`. Requires `sites.view`.","tags":["compute"],"responses":{"200":{"description":"The machine's services.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServerServices"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/services/action":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"post":{"operationId":"runComputeServerServiceAction","summary":"Start, stop or restart one service inside a server.","description":"Acts on a single service unit inside the machine - Apache, MariaDB, ProFTPD - while the machine itself stays up. This is the difference between a customer whose site is down fixing it themselves in ten seconds and a customer opening a ticket.\n\n⛔ **Not the same blast radius as `setComputeServerPower`.** That one moves the whole machine; this moves one unit inside a machine that keeps running. Stopping a web server or a database still takes every website on that box off the air, so the operation is audit-logged with the real actor.\n\n⛔ **`unit` must be a service the machine is currently running.** The engine checks the name against the machine's own live service list before sending anything, so an arbitrary systemd unit - `sshd.service`, a firewall, the enrolment agent - is refused with a `422` that names what is available instead. The list this endpoint's sibling `listComputeServerServices` returns is exactly the set that may be named here.\n\nThe response carries the provider's own confirmation sentence, which is worth showing to the customer verbatim. `404` for a server that is not the caller's; `422` for a machine that is not `active`, a unit it does not run, or a verb outside start/stop/restart. Requires `sites.view` **and** `sites.restart`.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServiceActionRequest"}}}},"responses":{"200":{"description":"The action was performed.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServiceActionResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/software":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"get":{"operationId":"listComputeServerSoftware","summary":"List the software available on a server.","description":"The provider's catalogue of software for this machine - runtimes and frameworks such as Node.js or Django - and whether each one is installed.\n\nRead-only. Installing from the catalogue is a separate operation and is not offered here. Requires `sites.view`.","tags":["compute"],"responses":{"200":{"description":"The machine's software catalogue.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServerSoftwareList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/limits":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"get":{"operationId":"getComputeServerLimits","summary":"What a server may hold.","description":"The machine's ceilings — today, how many websites it may host. Read live from the provider, because it is the provider's fact about the contract and a cached ceiling is wrong exactly when a plan changes.\n\n⛔ **The answer can be \"unlimited\", and a client must be able to say so.** The field is three-state: `null` the provider did not say, `-1` unlimited, `>= 0` a count. On the resold range this genuinely is unlimited, which is why adding a website to a machine the customer already owns costs nothing — a claim the platform previously made in a code comment and could not put on a screen. Requires `sites.view`.","tags":["compute"],"responses":{"200":{"description":"The machine's ceilings.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServerLimits"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/add-ons":{"get":{"operationId":"listComputeAddOns","summary":"What can be bought to run ON a Zinn® Private Cloud machine.","description":"The add-on catalogue — bare, CloudLinux, Plesk, and the managed service — priced in the currency asked for and filtered to what is actually in stock.\n\n⭐ These are the decisions `docs/127` §2 took on 2026-08-15 (D1–D5), expressed as rows a customer can buy. They are **orthogonal to the machine size**: a customer picks a size *and* an add-on, and the two multiply rather than choosing between each other. What the API calls a `ComputeTier` elsewhere is the SIZE; this is the software.\n\n⛔ **An empty list is the correct answer on the resold range**, not an error. There the supplier installs its own managed image and exposes no `user_data` seam, so there is no add-on question to answer — and rendering a picker with one disabled option would imply the others are coming.\n\n⛔ **A row absent from this list in one currency is not sold in that currency**, never converted at today's rate: a machine and the add-on beside it must not be quoted from two different sources, or the same basket costs two different amounts on two days. Requires `sites.view`.","tags":["compute"],"parameters":[{"in":"query","name":"currency","required":false,"schema":{"type":"string","minLength":3,"maxLength":3,"default":"USD"},"description":"ISO 4217 code to price in. An add-on with no price in it is omitted."},{"in":"query","name":"target","required":false,"schema":{"type":"string","default":"own_cloud"},"description":"The deploy target. Only `own_cloud` sells add-ons; anything else answers with an empty list."}],"responses":{"200":{"description":"The add-ons on sale.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ComputeAddOnOffer"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/compute/servers/{serverId}/add-on":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"get":{"operationId":"getComputeServerAddOn","summary":"The add-on this machine carries.","description":"⭐ **Singular, and three verbs on one path**, because a machine carries exactly one add-on at a time — a partial unique index in the database says so. A `/add-ons` collection would imply a list the customer can grow and then refuse the second one.\n\n⛔ Answers `200` with `data: null` for a bare machine, **never** `404`. \"This machine has no add-on\" is an answer; a 404 here would mean \"no such machine\", and a client cannot tell those apart from a status code alone. Requires `sites.view`.\n\n⭐ **A failed last attempt is shown, not hidden** (`docs/1104` §7). A failed install leaves the machine bare, so `data` stays `null` — the machine can buy again — and `last_failure` carries that failed row (`state: failed`, the step in `install_step`, the reason in `message`) while it is the machine's NEWEST add-on row. A later purchase or cancel replaces it, and it is then `null`.","tags":["compute"],"responses":{"200":{"description":"The machine's add-on, or `null` if it is bare — plus its last failed attempt.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"type":"object","required":["data","last_failure"],"additionalProperties":false,"properties":{"data":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ComputeAddOnAssignment"}]},"last_failure":{"nullable":true,"description":"The newest add-on attempt on this machine when it FAILED and nothing has replaced it; otherwise `null`. Always `null` while `data` is set.","allOf":[{"$ref":"#/components/schemas/ComputeAddOnAssignment"}]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"buyComputeServerAddOn","summary":"Buy an add-on for this machine.","description":"Requires `sites.view` and `billing.payment.manage`. ⛔⛔ **It was `billing.entitlement.manage` until 2026-08-17, which no customer role holds**, so the add-on designed to be turned on later could be turned on by nobody who owns a machine. The gate moved because the property behind it did: the add-on's price now joins the machine's subscription (priced into the cart line at order, moved from the next period when taken later), so this no longer spends Zinn®'s money and bills nobody.\n\n⚖️ `billing.payment.manage` is the key the owner ruled for this class of control on 2026-08-17 (`docs/136` §2e) — `owner` and `billing`, and deliberately **not** `dev`: a developer creates sites, and does not commit the organisation to a recurring licence.\n\n⛔ **A machine with no subscription is refused `422`** unless the caller also holds `billing.entitlement.manage`. Nothing would charge for the add-on there — that is the staff \"on the house\" path, and it stays deliberate rather than accidental.\n\n⭐ **Staff move access (`docs/1104` §7).** Staff acting through a staff-arranged delegation (`X-Zinn-Org` names the account) may buy with `billing.entitlement.manage` alone, in that one account only, and the add-on is then **forced on the house**: a machine that has a subscription is refused `422` `refusal.computeAddon.delegationBillableMachine`, because an add-on there would move the customer's recurring price. Audited with `staff_delegation_id` and `on_the_house: true`.\n\n⛔⛤ **AN ADD-ON WITH `applies_at` OF `running` OR `running_reboot` IS INSTALLED ON THE MACHINE AS IT STANDS, AND THE DATA ON IT IS NOT TOUCHED.** Until 2026-08-31 this endpoint refused every one of them with a sentence about rebuilding the disk. That sentence described a limitation of **cloud-init**, which runs only at create, and not of Plesk or CloudLinux — both of which ship installers whose documented purpose is converting a server that is already running. `docs/314` carries the vendor evidence.\n\nSuch a request starts a Temporal workflow and answers `201` with `state` of `installing` (or `queued`, when a pooled licence is out of stock). The client polls `GET` for `install_step`. Plesk takes around fifteen minutes; CloudLinux restarts the machine once.\n\n⛔⛔ **It requires `access` — one-time root credentials — and it is refused `422` without them.** This range hands SSH keys to the *customer* at build and the platform holds no key to any machine on it, so there is no standing credential to reach a running box with, and `docs/127` D4 chose deliberately never to create one. The credential is written to Vault under a path scoped to this one assignment, read only inside the install activities, kept out of the workflow history, and **deleted on every terminal outcome** — success, failure or refusal.\n\n⛔ **A genuinely build-only add-on is still refused `422`** with a sentence naming the remedy. Nothing in the catalogue is build-only today; the refusal is kept for the day something is.\n\n⛔ `503`, not `422`, when a pooled licence is out of stock **at order time**: the customer's next action is to try again, not to change their order. ⚖️ On a machine that is already running the same condition **queues** instead, by the owner's ruling of 2026-08-31 — the two paths differ because the moment differs, and at order time a refusal still reaches the customer before they have committed.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code"],"additionalProperties":false,"properties":{"code":{"type":"string","maxLength":64,"description":"The add-on's catalogue code. `bare` records nothing."},"currency":{"type":"string","minLength":3,"maxLength":3,"default":"USD","description":"The currency to charge in. ⛔ Frozen onto the assignment at purchase, so a later admin repricing does not move an existing customer's bill."},"access":{"type":"object","additionalProperties":false,"description":"One-time root access to the machine, required for any add-on whose `applies_at` is `running` or `running_reboot` and ignored for the rest.\n\n⛔⛔ **Write-only. Never echoed in a response, never logged, never recorded in an audit entry.** It is stored in Vault under a path scoped to this assignment and destroyed the moment the install reaches a terminal state. Supply `private_key` **or** `password`.","properties":{"private_key":{"type":"string","writeOnly":true,"description":"PEM private key. Preferred — the customer can revoke it."},"private_key_passphrase":{"type":"string","writeOnly":true},"password":{"type":"string","writeOnly":true,"description":"Root password. Accepted because much of this range is handed over with keys the customer holds and some have only ever set a password."},"username":{"type":"string","maxLength":64,"writeOnly":true,"description":"Defaults to `root`. Carried so a machine whose root login is disabled can be reached through a sudo-capable account."}}}}}}}},"responses":{"200":{"description":"`bare` was chosen — nothing was bought and nothing recorded, so `data` is `null`.","content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"nullable":true,"type":"object"}}}}}},"201":{"description":"The add-on was bought.","content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/ComputeAddOnAssignment"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"delete":{"operationId":"cancelComputeServerAddOn","summary":"Cancel this machine's add-on and release its licence.","description":"Stops the charge and gives the licence back to the vendor.\n\nRequires `sites.view` and `billing.payment.manage`, the same pair as buying one. Through a staff-arranged delegation, `billing.entitlement.manage` in the delegated account is enough, on the same terms as buying (`docs/1104` §7). ⛔ Not `sites.delete`: cancelling destroys no customer data, it stops a cost — and putting it behind the wipe key would stop a customer turning off something they are paying for. ⛔⛔ And not `billing.entitlement.manage`, which is what it was until 2026-08-17: no customer role holds that key, so the customer paying $29 a month for the managed service was the one person who could not stop paying it.\n\nThe machine's recurring price falls by the add-on's amount **from the next period**. The period already paid for is honoured rather than clawed back.\n\n⛔ **The vendor is released before our row is marked**, deliberately. If the vendor call fails we keep an active row and go on paying, which is visible and swept for; the other order loses the licence from our side while the vendor keeps billing it — an orphan no sweep can find, because the row naming the address is gone.\n\n⭐ For a pooled licence (LiteSpeed) the seat goes to `releasing`, not `free`: the serial is IP-bound and the release is manual in the vendor's own portal, so returning it to stock would hand the next customer a serial still locked to somebody else.","tags":["compute"],"responses":{"200":{"description":"The released add-on.","content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/ComputeAddOnAssignment"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/compute/servers/{serverId}/managed-care":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"get":{"operationId":"getComputeServerManagedCare","summary":"Who looks after this machine — self-managed or Zinn® Managed — and the care add-on's live price.","description":"SERVERCARE-r1 (owner 2026-11-11). `management_mode` is `self_managed` (no care add-on: server work is the customer's, and a request for it is answered with this add-on), `zinn_managed` (we patch, monitor and are on call), or `zinn_managed_paused` (the add-on is held but the account is not in good standing, §2.46 — care pauses and resumes by itself on payment). `offer` is the LIVE `managed` catalogue row in `currency`. Requires `sites.view`.","tags":["compute"],"parameters":[{"name":"currency","in":"query","required":false,"schema":{"type":"string","minLength":3,"maxLength":3},"description":"ISO currency to price the offer in. Defaults to USD."}],"responses":{"200":{"description":"The machine's care state.","content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/ManagedCareState"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"addComputeServerManagedCare","summary":"Add managed care to this machine.","description":"Moves the machine's recurring price up by the live `managed` row from the next period and the rest of the current one is charged pro rata; audit-logged `compute.managed_care.add`. Care is its own lane (`slot=care`), so it coexists with a software add-on (CloudLinux, Plesk, …). Requires `sites.view` and `billing.payment.manage`. `422` when the machine already has care or is not on a range we can look after.","tags":["compute"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"currency":{"type":"string","minLength":3,"maxLength":3}}}}}},"responses":{"201":{"description":"Care added; the new state.","content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/ManagedCareState"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"removeComputeServerManagedCare","summary":"Remove managed care — the machine becomes self-managed.","description":"The recurring price falls by the care amount from the next period; the paid period is honoured. Audit-logged `compute.managed_care.remove`. Requires `sites.view` and `billing.payment.manage`.","tags":["compute"],"responses":{"200":{"description":"Care removed; the new state.","content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/ManagedCareState"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/compute/servers/{serverId}/managed-care/connect":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"post":{"operationId":"connectComputeServerManagedCare","summary":"Connect a Zinn® Managed machine so we can patch and watch it.","description":"SERVERCARE-r2 (docs/1321). Borrows one-time root access, installs the care report agent (a systemd timer that posts `POST /v1/compute/care/report` with a per-machine token) and enables unattended security updates. Runs as a Temporal workflow; answers `202` with the connection as it stands. Audit-logged `compute.managed_care.connect` with NO body (the body is a root credential). Requires `sites.view` and `billing.payment.manage`. `422 refusal.compute.careNotOnThisServer` when the machine is self-managed, `422 refusal.compute.carePausedSettleAccount` when care is paused for an unpaid account, `503` when the workflow service is unreachable.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["access"],"additionalProperties":false,"properties":{"access":{"type":"object","additionalProperties":false,"description":"⛔⛔ Write-only. Never echoed, never logged, never audited; stored in Vault and destroyed when the connect run ends. Supply `private_key` **or** `password`.","properties":{"private_key":{"type":"string","writeOnly":true},"private_key_passphrase":{"type":"string","writeOnly":true},"password":{"type":"string","writeOnly":true},"username":{"type":"string","maxLength":64,"writeOnly":true}}}}}}}},"responses":{"202":{"description":"The connect run started; the connection as it stands.","content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/ManagedCareConnection"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/care/report":{"post":{"operationId":"reportManagedCare","summary":"A cared machine's own patch report (machine-to-engine).","description":"SERVERCARE-r2 (docs/1321). Called by the care agent's timer on the customer's machine, never by a person. The `Authorization: Bearer <token>` header carries the per-machine token minted at connect (stored as a digest only); there is no session. `401` for an unknown token, `410 CARE_ENDED` once care is removed (the agent uninstalls itself). Throttled `care-report` 60/min.","tags":["compute"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"os":{"type":"string","maxLength":200},"kernel":{"type":"string","maxLength":200},"pending_updates":{"type":"integer","minimum":0},"pending_security":{"type":"integer","minimum":0},"reboot_required":{"type":"boolean"},"last_patched_at":{"type":"integer","minimum":0,"description":"Unix seconds of the last unattended-upgrade run."},"packages":{"type":"string","maxLength":8000,"description":"The packages that run changed, newline-separated."}}}}}},"responses":{"200":{"description":"Recorded; when to report next.","content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"object","required":["next_report_seconds"],"additionalProperties":false,"properties":{"next_report_seconds":{"type":"integer"}}}}}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"410":{"description":"Care has ended on this machine; the agent removes itself.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/compute/servers/{serverId}/add-on/panel-login":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"post":{"operationId":"enableComputeServerPanelLogin","summary":"Enable one-click Plesk sign-in on this machine, with your consent.","description":"PLESK-SSO self-serve (`docs/1112` §6). For a machine whose Plesk add-on is `active` but was installed before one-click sign-in existed, so the server page shows no **Open Plesk**. With your consent and a one-time access to the machine, the platform creates a Plesk API key on it that is **bound to one address of ours** (the pinned egress for \"Plesk on our servers\"), proves it can mint a single-use login, and stores it in Vault. **Open Plesk** then works for you and for our support, every login single-use and audited.\n\nRequires `sites.view` and `sites.panel_access` — the key that already opens the panel. It changes no price.\n\n⛔⛔ `access` is **write-only**: never echoed, logged or audited. It is stored in Vault under a path scoped to this add-on, used once by a Temporal workflow, and **deleted when that run ends**, whatever the outcome. `consent` must be `true`.\n\nAnswers `202`: `panel_login_step` reads `enabling` until the run ends, then `\"\"` with `panel_connection_id` set (enabled), or the reason token it stopped on (`panel_unreachable`, `panel_key_refused`, `egress_not_pinned`, …). Refused `422` when the machine has no active Plesk add-on, is already enabled, or a run is in progress. `503` when the run could not be started — the access is deleted before it answers.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["consent","access"],"additionalProperties":false,"properties":{"consent":{"type":"boolean","description":"Must be `true` — the customer agrees to the sign-in key."},"access":{"type":"object","additionalProperties":false,"description":"One-time access to the machine, as for an add-on install on a running machine. ⛔⛔ Write-only. Supply `private_key` **or** `password`.","properties":{"private_key":{"type":"string","writeOnly":true},"private_key_passphrase":{"type":"string","writeOnly":true},"password":{"type":"string","writeOnly":true},"username":{"type":"string","maxLength":64,"writeOnly":true,"description":"Defaults to the machine's own sign-in account, else `root`."}}}}}}}},"responses":{"202":{"description":"The enable run has started.","content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/ComputeAddOnAssignment"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/certificates/products":{"get":{"operationId":"listCertificateProducts","summary":"TLS certificates a customer can buy.","description":"The Sectigo catalogue, priced per term in the currency asked for.\n\n⭐ **Every row carries `free_alternative_exists`, and a client should show it.** Let's Encrypt issues domain-validated certificates and wildcards for nothing, and our own Plesk panels already do it — so five of the fifteen compete with free. The other ten (organisation-validated, extended-validation, code-signing and S/MIME) are impossible with Let's Encrypt. Selling alongside a free option is only honest if the screen says which is which.\n\n⛔ A product with no price in the requested currency is omitted, never returned at zero: it cannot be bought in that currency, and rendering it free is the one error a customer would happily accept. Requires `sites.view`.","tags":["compute"],"parameters":[{"in":"query","name":"currency","required":false,"schema":{"type":"string","minLength":3,"maxLength":3,"default":"USD"},"description":"ISO 4217 code to price in. A product with no price in it is omitted."}],"responses":{"200":{"description":"The certificates on sale, with a price per term.","content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CertificateProduct"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/certificates/orders":{"get":{"operationId":"listCertificateOrders","summary":"This organisation's certificate orders.","description":"Every order except cancelled ones. ⛔ An order in `awaiting_validation` is listed and is **already paid for** — it is waiting on the customer, not on us. Requires `sites.view`.","tags":["compute"],"responses":{"200":{"description":"The orders.","content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CertificateOrder"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createCertificateOrder","summary":"Start a certificate order. Spends nothing.","description":"⭐ **This does NOT buy anything** — `submit` does. The split exists so the refusals a customer can act on arrive while they are still on the screen rather than as a failed background job, and so a half-filled form can never place an order.\n\n⛔ Answers `422` when the product does not cover what was asked for: a wildcard name on a non-wildcard certificate, more domains than the **price** includes, a term the authority does not sell, or an account not in good standing. Each of those is an order the authority would happily charge for and never issue. Requires `billing.payment.manage`.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCertificateOrderRequest"}}}},"responses":{"201":{"description":"The order, recorded and not yet purchased.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertificateOrder"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/certificates/orders/{orderId}":{"parameters":[{"$ref":"#/components/parameters/CertificateOrderId"}],"get":{"operationId":"getCertificateOrder","summary":"One certificate order.","description":"Requires `sites.view`.","tags":["compute"],"responses":{"200":{"description":"The order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertificateOrder"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"cancelCertificateOrder","summary":"Cancel an order inside the authority's refund window.","description":"⛔⛔ Answers `503` and leaves the order **unchanged** if the authority cannot be reached. Reporting a cancellation we did not achieve would remove the order from every screen while the charge stands. Requires `billing.payment.manage`.","tags":["compute"],"responses":{"200":{"description":"The cancelled order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertificateOrder"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/certificates/orders/{orderId}/submit":{"parameters":[{"$ref":"#/components/parameters/CertificateOrderId"}],"post":{"operationId":"submitCertificateOrder","summary":"Buy the certificate. This spends money.","description":"⛔⛔ **This is the call that charges.** It is a separate endpoint from the one that creates the order precisely so a client cannot buy while a form is half filled in.\n\n⛔⛔ **The CSR is required and is checked three times** — here, in the service and in the driver. That is not belt-and-braces: the authority accepts an order **without** one, charges for it, and issues nothing. Two such orders were created against our own account on 2026-08-29 by a probe reading validation errors, and the giveaway is how unlike a purchase they look — no common name, no issue date (`docs/272` §9).\n\n⭐ A customer-generated CSR is the better path and the one to encourage: the private key then never leaves their machine. Answers `503` when the authority could not be reached — in which case the order is recorded and reconciled rather than lost. Requires `billing.payment.manage`.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["csr_pem"],"additionalProperties":false,"properties":{"csr_pem":{"type":"string","description":"The certificate signing request, PEM. ⛔ Required. Without it the authority has nothing to sign and the order is billed and permanently unusable."}}}}}},"responses":{"200":{"description":"The order after purchase — usually `awaiting_validation`, carrying the authority's own instructions for proving domain control.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertificateOrder"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/certificates/orders/{orderId}/refresh":{"parameters":[{"$ref":"#/components/parameters/CertificateOrderId"}],"post":{"operationId":"refreshCertificateOrder","summary":"Ask the authority where this order actually got to.","description":"⭐⭐ **The load-bearing call on this surface.** An order can sit paid-and-unissued indefinitely while nothing on our side looks wrong — the customer has been charged, no certificate exists, and no error was raised anywhere. Only the authority knows, and only this asks it. A screen that shows a certificate as \"in progress\" without calling this is showing a guess. Requires `sites.view`.","tags":["compute"],"responses":{"200":{"description":"The order, as the authority now reports it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertificateOrder"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/certificates/orders/{orderId}/renew":{"parameters":[{"$ref":"#/components/parameters/CertificateOrderId"}],"post":{"operationId":"renewCertificateOrder","summary":"Start the successor order for an expiring certificate.","description":"⛔⛔ **A renewal is a FRESH ORDER with a FRESH VALIDATION, not a flag.** The authority re-issues against a new CSR and re-runs domain control, so this creates a `pending` successor seeded from the expiring order and **spends nothing**. The customer then supplies a CSR to `submitCertificateOrder` exactly as they did the first time, which is the call that charges. Anything modelling renewal as an auto-renew toggle silently produces orders nobody validates — paid for, `awaiting_validation`, and never issued.\n\n⭐ **Idempotent**, so it answers `200` rather than `201`: a double-click, a retried activity and an impatient customer all reach this, and it returns the existing live successor rather than buying a second certificate. Requires `billing.payment.manage`.\n\n⚠️ An organisation that is not in good standing is refused **with a reason** (§2.46), never silently — the existing certificate keeps working until it expires either way, and \"my renew button does nothing\" is indistinguishable from a broken product.","tags":["compute"],"responses":{"200":{"description":"The successor order, `pending` and awaiting a CSR.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertificateOrder"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/panels/products":{"get":{"operationId":"listPanelProducts","summary":"Control-panel editions and extensions a customer can buy.","description":"The Plesk catalogue — every edition (Web Admin, Web Pro, Web Host, WordPress, Business & Collaboration) and the extensions that attach to one — priced in the currency asked for.\n\n⛔ **`hostType` is not cosmetic and the wrong value sells a key the panel refuses.** Plesk prices a VPS licence and a dedicated-server licence as different SKUs at different money (measured 2026-08-29: `EUR 21.20` against `EUR 24.00` for Web Host). Filtering by `hostType` always also returns `any` products, because most extensions genuinely do not care which kind of machine they run on.\n\n⛔ **A product with no price in the requested currency is omitted, never returned at zero.** It cannot be bought in that currency, and rendering it free is the one error a customer would happily accept. Requires `sites.view`.","tags":["compute"],"parameters":[{"in":"query","name":"currency","required":false,"schema":{"type":"string","minLength":3,"maxLength":3,"default":"USD"},"description":"ISO 4217 code to price in. A product with no price in it is omitted."},{"in":"query","name":"hostType","required":false,"schema":{"type":"string","enum":["vps","dedicated"]},"description":"The kind of machine the licence is for. Products marked `any` are always included as well."},{"in":"query","name":"kind","required":false,"schema":{"type":"string","enum":["edition","extension"]},"description":"Narrow to base editions or to the extensions that attach to one."}],"responses":{"200":{"description":"The products on sale.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PanelProduct"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/panels/licences":{"get":{"operationId":"listPanelLicences","summary":"The control-panel licences this organisation holds.","description":"Every licence except released ones. ⛔ A `suspended` licence is still listed: the charge has stopped but the record has not, and it comes back automatically when the account returns to good standing. Requires `sites.view`.","tags":["compute"],"responses":{"200":{"description":"The licences held.","content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PanelLicence"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"buyPanelLicence","summary":"Buy a control-panel licence.","description":"⛔ **This spends money at the supplier**, monthly, until the licence is released.\n\n⭐ **On the customer's OWN machine the licence is bought immediately**, because the address is known at order time. On one of ours it is recorded `pending` and bought the moment the machine has an IP — Openprovider Plesk licences are IP-bound, and one bought before an address exists is bound to nothing and cannot be released.\n\n⛔ Answers `422` when the account is not in good standing, when the product is not on sale, when a licence for the customer's own server arrives without its IP, or when an extension is ordered for a machine holding no matching base edition. Answers `503` when the supplier could not be reached — in which case the licence is recorded and reconciled automatically rather than silently lost. Requires `billing.payment.manage`.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyPanelLicenceRequest"}}}},"responses":{"201":{"description":"The licence, active if it could be bound immediately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PanelLicence"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/panels/licences/{licenceId}":{"parameters":[{"$ref":"#/components/parameters/PanelLicenceId"}],"get":{"operationId":"getPanelLicence","summary":"One control-panel licence.","description":"Requires `sites.view`.","tags":["compute"],"responses":{"200":{"description":"The licence.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PanelLicence"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"releasePanelLicence","summary":"Release a licence — the only thing that stops the charge.","description":"⛔⛔ **Answers `503` and leaves the licence UNCHANGED if the supplier cannot be reached.** Reporting a release we did not achieve would remove the licence from every screen while the supplier kept billing for it — the orphan this product exists to prevent. Requires `billing.payment.manage`.","tags":["compute"],"responses":{"200":{"description":"The released licence.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PanelLicence"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/panels/connections":{"get":{"operationId":"listPanelConnections","summary":"The control panels this organisation has connected.","description":"Requires `sites.view`.","tags":["compute"],"responses":{"200":{"description":"The panels connected.","content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PanelConnection"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"connectPanel","summary":"Connect a running Plesk panel so it can be managed from here.","description":"The credential is stored in Vault and **never** in a row. Supply either an API key (preferred — it can be revoked in Plesk without changing the administrator password) or the administrator login and password.\n\n⭐ **The panel is probed before the connection is kept.** A panel that cannot be reached, or whose credential is refused, is rejected while the customer still has their Plesk tab open and can fix it — rather than failing later, when nobody remembers what they typed.\n\n⛔ `422` distinguishes *we could not reach it* from *it refused our credential*. Those send the customer to their firewall and to their password respectively, and merging them makes people change a password that was working. Requires `connections.manage`.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectPanelRequest"}}}},"responses":{"201":{"description":"The connected panel, with what it proved it can do.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PanelConnection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/panels/connections/{connectionId}":{"parameters":[{"$ref":"#/components/parameters/PanelConnectionId"}],"get":{"operationId":"getPanelConnection","summary":"One connected control panel.","description":"Requires `sites.view`.","tags":["compute"],"responses":{"200":{"description":"The panel.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PanelConnection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"forgetPanel","summary":"Disconnect a panel and delete its stored credential.","description":"⛔ Removes the Vault entry as well as the row. Leaving it would keep an administrator credential for a machine we no longer show anywhere. The panel itself is untouched and keeps running. Requires `connections.manage`.","tags":["compute"],"responses":{"204":{"description":"Disconnected."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/panels/connections/{connectionId}/check":{"parameters":[{"$ref":"#/components/parameters/PanelConnectionId"}],"post":{"operationId":"checkPanelConnection","summary":"Re-probe what this panel can actually do.","description":"⛔⛔ **Rewrites `provedCapabilities` from what the panel DEMONSTRATED**, never from what the adapter can express. A Plesk box can answer every read perfectly and refuse `/cli/*/call` outright, because the command-line gateway is separately licensed and separately permissioned — and both one-click login and licence installation go through it. Re-probing matters because the answer changes without telling us: the customer's own administrator can restrict it, or the licence can lapse.\n\n⛔ A failed check CLEARS `provedCapabilities` rather than keeping yesterday's list, so the screen stops offering buttons against a panel we can no longer reach. Requires `connections.manage`.","tags":["compute"],"responses":{"200":{"description":"The panel, with `checkedAt` and `lastError` updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PanelConnection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/panels/connections/{connectionId}/login-link":{"parameters":[{"$ref":"#/components/parameters/PanelConnectionId"}],"post":{"operationId":"createPanelLoginLink","summary":"One-click login — a one-time administrative session on the panel.","description":"⚖️ The owner's ask of 2026-08-28, verbatim: *\"one click login to the plesk panels\"*.\n\n⛔⛔ **The returned `url` is a LIVE CREDENTIAL.** It is an authenticated administrative session on the customer's panel. It is never logged, never persisted and never emailed — it is returned to one authenticated caller and belongs straight in their browser. Plesk's links are single-use and die on first redemption, which is a stronger guarantee than any expiry clock; `expiresAt` is therefore absent rather than guessed.\n\n⛔ Gated on `sites.panel_access` — **not** `sites.view`. That key means *direct server-level access to a customer's hosting*: it is held by `owner`, `dev` and staff `ops`, and deliberately not by `support` or any read-only role. A read-only role must never be able to mint an administrative session.\n\n⛔ Answers `422` when this connection has not proved it can create login links, and refuses BEFORE calling the panel. A button that reaches a panel which will refuse it fails on a third-party domain, where neither we nor the customer can see why.\n\nEvery mint is written to the audit trail with the actor and the panel — never the URL.","tags":["compute"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"username":{"type":"string","description":"A panel user to sign in as. Omit for the panel's administrator."}}}}}},"responses":{"200":{"description":"A one-time login URL. Treat it as a credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PanelLoginLink"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/panels/connections/{connectionId}/domains":{"parameters":[{"$ref":"#/components/parameters/PanelConnectionId"}],"get":{"operationId":"listPanelDomains","summary":"The websites this panel is serving.","description":"⛔ Complete, never the first page: a panel with 900 domains is a normal panel, and truncating would hide a customer's largest site precisely because their account is large. Requires `sites.view`.","tags":["compute"],"responses":{"200":{"description":"The panel's websites.","content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PanelDomain"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/panels/connections/{connectionId}/clients":{"parameters":[{"$ref":"#/components/parameters/PanelConnectionId"}],"get":{"operationId":"listPanelClients","summary":"The customer accounts held on this panel.","description":"Complete, never the first page. Requires `sites.view`.","tags":["compute"],"responses":{"200":{"description":"The panel's customer accounts.","content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PanelClient"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/panels/connections/{connectionId}/install-licence":{"parameters":[{"$ref":"#/components/parameters/PanelConnectionId"}],"post":{"operationId":"installPanelLicence","summary":"Install a licence we bought onto this panel.","description":"⛔⛔ **Buying a licence and installing it are different acts, and doing only the first is a recurring charge for nothing.** This is the step that makes a purchase useful.\n\n⭐ The panel is read back afterwards rather than the call being trusted, so the response states what the panel now actually holds. Requires `connections.manage`.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["licence_id"],"additionalProperties":false,"properties":{"licence_id":{"type":"string","format":"uuid","description":"A licence this organisation holds."}}}}}},"responses":{"200":{"description":"The panel, re-probed after the key was installed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PanelConnection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/ddos-protection":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"get":{"operationId":"getComputeServerDdosProtection","summary":"A server's DDoS protection add-on.","description":"Whether this server's location offers DDoS protection (`available`), whether it is on, and what it costs a month while on, in the server's billing currency (docs/1124). Requires `sites.view`.","tags":["compute"],"responses":{"200":{"description":"The add-on's state on this server.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServerDdosProtection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"post":{"operationId":"setComputeServerDdosProtection","summary":"Switch a server's DDoS protection add-on on or off.","description":"⛔ Chargeable: on adds the price the `GET` shows to what the server is billed (its hourly rate on a pay-by-the-hour server, its subscription from the next renewal otherwise); off takes exactly that off. The response is re-read from the provider. `422` when the account is on hold; `503` `refusal.compute.ddosNotInLocation` where the location does not offer it. A refusal changes nothing and charges nothing. Requires `billing.payment.manage`.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServerSetBackupsRequest"}}}},"responses":{"200":{"description":"The add-on's state, re-read from the provider.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServerDdosProtection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/backups":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"get":{"operationId":"getComputeServerBackups","summary":"A server's automatic backup arrangement.","description":"Whether the provider is backing this machine up, which tier it is on, when backups run and how many are kept.\n\n⛔⛔ **Read `manageable` before rendering a control.** The two ranges differ: on the resold range the tier is readable and there is no verb to change it, so the honest surface is a statement and an upgrade route; on our own cloud it is a switch. A client that assumed it could always write would show half the estate a toggle that fails. Requires `sites.view`.","tags":["compute"],"responses":{"200":{"description":"The machine's backup arrangement.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServerBackups"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"post":{"operationId":"setComputeServerBackups","summary":"Turn a server's automatic backups on or off.","description":"⛔⛔ **Chargeable one way and destructive the other.** Enabling costs a percentage of the machine's price for as long as it runs — a recurring change to what the customer pays. Disabling **deletes the restore points that already exist**, at the provider, with no undo anywhere. Both belong behind a confirmation that says which one is happening.\n\nThe response is the arrangement **re-read from the provider**, never an echo of the request: an asynchronous write followed by an immediate synchronous read has been measured on a real machine reporting \"saved\" over the old value.\n\n`503` on a range whose provider exposes no verb for this — that is a permanent property of the range, not a temporary failure, and a client should render the statement rather than invite a retry. Requires `billing.payment.manage`.\n\n**Billing (s1014 L35, owner ruling 2026-10-23).** On a range we run on our own account, switching on adds the price the `GET` shows (the range's `ComputeAddonOffer` row: the provider's cost plus its markup, charm-rounded, in the machine's billing currency) to what the machine is billed: its hourly rate on a pay-by-the-hour machine, its subscription from the next renewal on a monthly or yearly one. Switching off takes exactly that off. `422` `refusal.compute.accountHoldBackupsSnapshots` when the account is not in good standing; `503` `refusal.compute.backupsSnapshotsCannotPriced` when no price can be stated. Both change nothing and charge nothing.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServerSetBackupsRequest"}}}},"responses":{"200":{"description":"The arrangement, re-read from the provider.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServerBackups"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/plan":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"get":{"operationId":"getComputeServerPlan","summary":"What this machine costs, and what else it could have.","description":"Everything the \"change what I am paying for\" card renders: the paid options already on the machine, the ones it could still take, and whether its size can change at all.\n\n⛔⛔ **Read `resizable` and `addons_removable` before rendering any control.** They are different answers on the two ranges and both are vendor facts, not preferences. A cloud server resizes in place and its extended-backup tier can be cancelled; a VPS can do neither - this platform publishes no operation that changes a VPS's processor or memory, and no way to remove one of its add-ons. `resize_reason` and `addons_removal_reason` carry the sentence to show instead of the control. Requires `sites.view`.","tags":["compute"],"responses":{"200":{"description":"The machine's paid options.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/ComputeServerPlan"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"purchaseComputeServerAddon","summary":"Buy one paid option for this machine.","description":"⛔⛔ **Chargeable twice over, and both are immediate.** It debits Zinn®'s reseller balance at the provider *and* starts a recurring charge on the customer, so it sits behind `billing.payment.manage` rather than `sites.create`.\n\nThe provider offers no idempotency header on this operation, so the request is keyed by (machine, option) on our side and a repeat returns the original purchase rather than buying a second one. `422` when the machine cannot carry the option — cPanel below 2 GB, a second cPanel licence, backups already on.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeAddonPurchaseRequest"}}}},"responses":{"201":{"description":"The purchase.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/ComputeAddonPurchase"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/plan/{purchaseId}":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"},{"$ref":"#/components/parameters/ComputeAddonPurchaseId"}],"delete":{"operationId":"removeComputeServerAddon","summary":"Stop paying for one option — where the provider permits it.","description":"⛔⛔ **Not a delete at the provider, and the response says so.** this platform charges the option's term up front and refund nothing, so this stops the *renewal*: the thing stays attached and the customer keeps what they paid for until the contract expires. The purchase comes back as `cancelling`, never `ended`, precisely so no screen can claim otherwise.\n\n⛔ **`422` on the VPS range, always.** A VPS add-on is a sub-contract of the machine and this platform exposes no way to cancel one - not through the reseller API, not through the contract (the write is accepted and ignored), and not in their own control panel, where the row carries no action at all and is labelled \"renews with\" the machine. Read `addons_removable` from `getComputeServerPlan` and do not offer the control at all rather than inviting a refusal. Requires `billing.payment.manage`.","tags":["compute"],"responses":{"200":{"description":"The purchase, now cancelling.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/ComputeAddonPurchase"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/compute/servers/{serverId}/backups/tier":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"get":{"operationId":"getComputeServerBackupTier","summary":"The machine's backup tier, and what upgrading would cost.","description":"A **pure read** — it charges nothing. `amount_minor` is our price for moving this machine to extended backups, derived from the provider's own live quote for **this** machine rather than from a published percentage: the two disagree, and the provider's figure is the one we are charged.\n\n⛔ `upgrade_available: false` with a `reason` when the machine is already on the extended tier, is still building, or is on a range that has no tier concept — the VPS range buys backups as a separate contract instead, from `getComputeServerPlan`. Requires `sites.view`.","tags":["compute"],"responses":{"200":{"description":"The tier and the upgrade price.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/ComputeBackupTier"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"setComputeServerBackupTier","summary":"Move the machine between the standard and extended backup tiers.","description":"⛔⛔ **Chargeable one way and lossy the other.** Upgrading starts a recurring charge for as long as it runs. Downgrading returns the machine to the standard retention, and what happens to the snapshots already taken is the provider's decision and is not documented — so a confirmation should say the tier changes and must **not** promise a date for the older restore points.\n\nThe response is the tier **re-read from the provider**, never an echo of the request. Requires `billing.payment.manage`.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeSetBackupTierRequest"}}}},"responses":{"200":{"description":"The tier, re-read from the provider.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/ComputeBackupTier"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/snapshots":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"get":{"operationId":"listComputeServerSnapshots","summary":"List a server's on-demand disk images.","description":"Every snapshot taken from this machine, newest first.\n\n⛔ Scoped to the machine by the image's `created_from`, because at the provider a snapshot is **not bound** to the server it came from — an unscoped listing would show one customer the whole account's snapshots. Requires `sites.view`.","tags":["compute"],"responses":{"200":{"description":"The machine's snapshots.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServerSnapshots"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"post":{"operationId":"createComputeServerSnapshot","summary":"Take a snapshot of a server now.","description":"Images the machine's disk as it is right now, so the customer has a point to come back to before an upgrade or a risky change.\n\n**Billing (s1014 L35).** On a range we run on our own account the snapshot is charged for its stored size, per month, once the provider has measured it (minutes after the call), until it is deleted: the provider's per-GB cost plus the range's snapshot markup, charm-rounded. The same `422` and `503` refusals as switching backups on apply, before anything is taken.\n\n⛔ **It bills for storage until it is deleted.** It is not destructive — snapshotting a running machine changes nothing about it — but it is a recurring cost, so it is gated on the spend key rather than on the operate key.\n\nThe snapshot comes back with `ready: false`: imaging a disk takes minutes and the request is not held for it. Poll the listing; a restore must not be offered until `ready` is true. Requires `billing.payment.manage`.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServerCreateSnapshotRequest"}}}},"responses":{"201":{"description":"The snapshot has been started.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServerSnapshot"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/snapshots/{snapshotId}":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"},{"name":"snapshotId","in":"path","required":true,"schema":{"type":"string"},"description":"The **provider's** id for the image, as the listing reported it — not one of ours. The engine re-checks that the snapshot was created from this machine before touching it, because the provider's own delete and restore know nothing about which server an image came from."}],"post":{"operationId":"restoreComputeServerSnapshot","summary":"Roll a server back to a snapshot.","description":"⛔⛔ **The most destructive operation on this API, and more so than `rebuildComputeServer`.** A rebuild gives the customer the clean machine they asked for; a restore **overwrites the live disk** with an older one. Everything written since the snapshot is gone, the current state is not itself snapshotted first, and there is no undo at the provider or here.\n\nRefused on a snapshot that is not `ready` — an image still being written restores an incomplete disk, and the provider will happily start it. Requires `sites.view` and `sites.delete`, the same key as deleting a website, because the blast radius is the same: data the customer cannot get back.","tags":["compute"],"responses":{"200":{"description":"The machine, with the restore under way.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServer"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"delete":{"operationId":"deleteComputeServerSnapshot","summary":"Delete a snapshot.","description":"⛔ Irreversible, and it is one of the customer's restore points. Requires `sites.view` and `sites.delete`.","tags":["compute"],"responses":{"204":{"description":"The snapshot has been deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/floating-ips":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"get":{"operationId":"listComputeServerFloatingIps","summary":"The floating IPs routed to a server.","description":"W43-49 (`docs/689`). Every address this organisation holds on the machine that has not been released. Requires `sites.view`.","tags":["compute"],"responses":{"200":{"description":"The machine's floating IPs.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeFloatingIpList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"post":{"operationId":"addComputeServerFloatingIp","summary":"Reserve a floating IP and route it to a server.","description":"⛔ **Chargeable.** The address's monthly price is folded into the machine's hourly rate from the next hour and stays there until it is released, so it is only offered on pay-by-the-hour machines. Quote it first with `quoteComputeServerFloatingIp`.\n\nThe machine does not answer on the address until its operating system is told the address exists; a client shows the commands beside the address. Requires `billing.payment.manage`.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeFloatingIpRequest"}}}},"responses":{"201":{"description":"The address, reserved and routed.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeFloatingIp"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/floating-ips/quote":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"post":{"operationId":"quoteComputeServerFloatingIp","summary":"What a floating IP on this server costs per month.","description":"A POST that changes nothing: the price in the machine's billing currency, before the charge. Requires `sites.view`.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeFloatingIpRequest"}}}},"responses":{"200":{"description":"The monthly price.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeFloatingIpQuote"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/floating-ips/{floatingIpId}":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"},{"name":"floatingIpId","in":"path","required":true,"description":"The floating IP's id, as `listComputeServerFloatingIps` reports it.","schema":{"$ref":"#/components/schemas/Uuid"}}],"delete":{"operationId":"releaseComputeServerFloatingIp","summary":"Release a floating IP.","description":"⛔ Irreversible: the address returns to the provider and cannot be asked for again. It comes off the machine's rate from the next hour. Requires `sites.delete`.","tags":["compute"],"responses":{"204":{"description":"Released."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/networks":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"post":{"operationId":"attachComputeServerNetwork","summary":"Join a server to one of the organisation's private networks.","description":"The machine and the network must be in the same region. No charge. Requires `sites.restart`.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeAttachNetworkRequest"}}}},"responses":{"200":{"description":"The private address the machine was given.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeNetworkAttachment"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/networks/{networkId}":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"},{"$ref":"#/components/parameters/ComputeNetworkId"}],"delete":{"operationId":"detachComputeServerNetwork","summary":"Take a server off a private network.","description":"Refused for a cluster's own machine on the cluster's network. Requires `sites.restart`.","tags":["compute"],"responses":{"204":{"description":"Detached."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/networks":{"get":{"operationId":"listComputeNetworks","summary":"The organisation's private networks.","description":"Each with the organisation's own machines on it and their private addresses. ⛔ Built from our records, never from the provider's account listing. Requires `sites.view`.","tags":["compute"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The networks.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputePrivateNetworkList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"post":{"operationId":"createComputeNetwork","summary":"Create a private network from a server.","description":"The network is created in the server's region and the server joins it. Ranges must be a private IPv4 block between a /8 and a /24, outside 10.42.0.0/16 and 10.43.0.0/16. No charge. Requires `sites.restart`.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeCreateNetworkRequest"}}}},"responses":{"201":{"description":"The network, with the server on it.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputePrivateNetwork"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/networks/{networkId}":{"parameters":[{"$ref":"#/components/parameters/ComputeNetworkId"}],"delete":{"operationId":"deleteComputeNetwork","summary":"Delete a private network.","description":"Refused while any machine is on it, and for a cluster's own network (delete the cluster). Requires `sites.delete`.","tags":["compute"],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/clusters":{"get":{"operationId":"listComputeClusters","summary":"The organisation's Kubernetes clusters.","description":"W43-49 (`docs/689`). Every cluster not yet deleted, with its machines. Requires `sites.view`.","tags":["compute"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The clusters.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeClusterList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"post":{"operationId":"createComputeCluster","summary":"Create a k3s cluster, optionally with Argo CD.","description":"**202.** One control-plane machine and `worker_count` workers, each an ordinary pay-by-the-hour server, built into a private network. Kubernetes comes from the k3s stable channel and Argo CD from its stable manifests; the versions actually installed are read back from the cluster.\n\n⛔ The balance must cover every machine's runway before anything is built. Quote it first with `quoteComputeCluster`. Requires `billing.payment.manage`.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeCreateClusterRequest"}}}},"responses":{"202":{"description":"The cluster, being built.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeCluster"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/clusters/quote":{"post":{"operationId":"quoteComputeCluster","summary":"What a cluster costs, before it is built.","description":"A POST that changes nothing. Requires `sites.view`.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeClusterQuoteRequest"}}}},"responses":{"200":{"description":"The price and the balance it needs.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeClusterQuote"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/clusters/{clusterId}":{"parameters":[{"$ref":"#/components/parameters/ComputeClusterId"}],"get":{"operationId":"getComputeCluster","summary":"One cluster, with its machines and what it reports.","description":"Requires `sites.view`.","tags":["compute"],"responses":{"200":{"description":"The cluster.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeCluster"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"delete":{"operationId":"deleteComputeCluster","summary":"Delete a cluster and every machine in it.","description":"**202.** ⛔ Irreversible: every node is deleted with its disk, its floating IPs are released, its meter is settled, and the network and the cluster's keys are removed. Refused while the cluster is still being built. Requires `sites.delete`.","tags":["compute"],"responses":{"202":{"description":"The cluster, being deleted.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeCluster"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/clusters/{clusterId}/kubeconfig":{"parameters":[{"$ref":"#/components/parameters/ComputeClusterId"}],"get":{"operationId":"getComputeClusterKubeconfig","summary":"Download the cluster's kubeconfig.","description":"⛔ A cluster-admin credential. Every read is audit-logged and the response is `no-store`. Refused until the cluster is ready. Requires `sites.delete`.","tags":["compute"],"responses":{"200":{"description":"The kubeconfig, pointed at the cluster's public API address.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/yaml":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/firewall":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"get":{"operationId":"getComputeServerFirewall","summary":"A server's network filter.","description":"The firewall applied to this machine and the rules in force.\n\n⛔ Read `attached` before reading `rules`. No firewall and an empty firewall both come back looking empty and mean opposite things — one is \"nothing is protecting this machine\", the other is \"a filter is in place and permits nothing\". Requires `sites.view`.","tags":["compute"],"responses":{"200":{"description":"The machine's firewall.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServerFirewall"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"put":{"operationId":"setComputeServerFirewall","summary":"Replace a server's firewall rules.","description":"⭐ **PUT, and the verb is the contract**: this replaces the entire rule set. The provider's write is atomic, and an add/remove surface layered over an atomic replace is how two people editing at once discard each other's rule with both requests reporting success.\n\n⛔⛔ **This can lock the customer out of their own machine.** A set with no inbound SSH is applied exactly as asked and their next connection is refused. That is why `openComputeServerConsole` exists, and why a client should say so beside this control.\n\nRefused when more than one firewall is applied to the machine: the effective policy is their union, so editing one and reporting the result would be false in the dangerous direction. The whole rule set is audit-logged, not a count — when a customer reports being locked out, \"12 rules were set\" answers nothing. Requires `sites.restart`.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServerSetFirewallRequest"}}}},"responses":{"200":{"description":"The firewall, re-read from the provider.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServerFirewall"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/console":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"post":{"operationId":"openComputeServerConsole","summary":"Open an out-of-band console onto a server.","description":"⭐⭐ **The control that works when SSH does not** — a bad firewall rule, a broken `sshd` config, a full disk, a kernel that will not boot. It is what turns \"my server is unreachable, open a ticket\" into something the customer fixes themselves.\n\n⛔ **POST, not GET, because it MINTS a credential.** It is not idempotent, not cacheable, and must never end up in a browser history, a proxy log or a prefetch. The response carries a one-shot URL that reaches the machine's console as if sitting at its keyboard; it is returned once and stored nowhere. Every call is audit-logged — that one was opened and by whom, never the URL or the password.\n\n⛔⛔ **A `wss` address is ours and is SINGLE-USE** (W43-49). It is relayed by Zinn®'s own gateway, so the session's `url` names `api.zinndigital.com` and never the machine's supplier; a client that needs a second connection calls this again rather than reconnecting with the first address.\n\n`503` on a range whose provider offers no console. Requires `sites.restart`.","tags":["compute"],"responses":{"200":{"description":"A live console session.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServerConsole"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/console/allow":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"post":{"operationId":"allowComputeServerConsoleIp","summary":"Let one address reach an IP-gated console.","description":"⭐⭐ **Without this, the console on an IP-gated range is a password for a bolted door.** Such a range starts with an empty allow-list, meaning *nobody* may connect — the credential is real and useless until an address is added.\n\n⛔ The response is the console session **re-read from the provider**, never an echo of the request: a `200` is not evidence on every provider, and the allow-list coming back containing the address is the only proof it landed.\n\nRequires `sites.restart` — granting an address console access **is** granting console access. Audited with the address, unlike opening a console, because an allow-list entry is a lasting change to who may reach the machine rather than a credential. `503` on a range whose console is not restricted by address.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ip"],"additionalProperties":false,"properties":{"ip":{"type":"string","maxLength":45,"description":"The public address that should be allowed to connect."}}}}}},"responses":{"200":{"description":"The console session, re-read after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServerConsole"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"delete":{"operationId":"lockComputeServerConsole","summary":"Revoke every address's console access.","description":"⛔ **Revokes ALL of them, not one.** The provider publishes no per-entry removal, so this is \"shut the console\" rather than \"revoke that laptop\" — a caller expecting the second gets the first, including their own access. Requires `sites.restart`.","tags":["compute"],"responses":{"200":{"description":"The console session, re-read after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServerConsole"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/metrics":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"get":{"operationId":"getComputeServerMetricsHistory","summary":"How hard a server has worked over a window — CPU, network and disk rates.","description":"Read live from the provider and stored nowhere. `window` is one of `1h`, `24h`, `7d` or `30d` (default `24h`); anything else is a `422` naming the four, never widened to the nearest.\n\n⛔ A sample the provider did not have is `null` — a gap in the line, never zero. ⛔ A quantity this range does not measure is ABSENT from `series`, which is a different state from a series with no points.\n\n`503` on a range with no metrics history (see the `compute:metrics_history` capability). Requires `sites.view`.","tags":["compute"],"parameters":[{"name":"window","in":"query","required":false,"schema":{"type":"string","enum":["1h","24h","7d","30d"],"default":"24h"}}],"responses":{"200":{"description":"The series across the window.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServerMetricsHistory"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/terminal":{"get":{"operationId":"getComputeTerminalAccess","summary":"Whether the web terminal is turned on for an organisation.","description":"`enabled` is true only when BOTH halves exist — the organisation's terminal key is registered as one of its SSH keys, and its private half is in our secret store. `public_key` is the one line to add to `authorized_keys` on a machine built before the terminal was turned on. `?org_id=` is required only of a caller in more than one organisation. Requires `sites.view`.","tags":["compute"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The organisation's terminal switch.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeTerminalAccess"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"enableComputeTerminal","summary":"Turn the web terminal on — mint the organisation's terminal key.","description":"Mints one ed25519 key for the organisation. ⛔ The private half is written to our secret store and never returned by any API; the public half is registered as one of the organisation's SSH keys, so every machine ordered afterwards carries it from first boot. Idempotent. Audit-logged. Requires `billing.payment.manage` — the same authority that registers an SSH key.","tags":["compute"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The terminal is on.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeTerminalAccess"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"delete":{"operationId":"disableComputeTerminal","summary":"Turn the web terminal off — destroy the organisation's terminal key.","description":"⛔ Destroys the private key and unregisters the public one. The public line stays in each machine's `authorized_keys`, but with the private half gone nothing anywhere can use it. Audit-logged. Requires `billing.payment.manage`.","tags":["compute"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"204":{"description":"The terminal is off and its key is destroyed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/terminal":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"post":{"operationId":"openComputeServerTerminal","summary":"Mint a single-use ticket for one web terminal session on a server.","description":"⛔⛔ **The ticket is a credential: one use, sixty seconds.** Open `wss://<this API's host><path>` and send it as the FIRST message — `{\"type\":\"auth\",\"ticket\":\"…\",\"cols\":N,\"rows\":N}` — never in the URL, which access logs keep. After that, binary frames are keystrokes and terminal output; text frames are `{\"type\":\"resize\",…}` from the client and `{\"type\":\"status\",\"state\",\"code\",\"message\"}` from the gateway.\n\nThe gateway logs in over SSH with the organisation's terminal key and pins the machine's host key on first use; a changed key is refused (`code: host_key_changed`). Every ticket, connection, failure and close is audit-logged — who, when, how long and how many bytes, never what was typed. `422` when the terminal is off, the login name is not one a server accepts, or the machine has no public address. Requires `sites.restart`.","tags":["compute"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"username":{"type":"string","maxLength":32,"description":"The login name. `\"\"` means `root`."}}}}}},"responses":{"200":{"description":"A single-use session ticket.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeTerminalTicket"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/terminal/host-key":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"delete":{"operationId":"forgetComputeServerTerminalHostKey","summary":"Trust a server's new SSH identity on the next terminal connection.","description":"Drops the host key the web terminal pinned. A rebuild does this itself, because a fresh image is a fresh key. ⛔ A key that changed when nobody rebuilt the machine is what an interception looks like — the screen says so before offering this. Audit-logged. Requires `sites.restart`.","tags":["compute"],"responses":{"204":{"description":"The pin is gone; the next connection pins whatever the machine presents."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/compute/servers/{serverId}/images":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"get":{"operationId":"listComputeServerImages","summary":"What this machine may be rebuilt to.","description":"⭐⭐ **Distinct from the catalogue's per-provider image list, and the duplication is the provider's rather than ours.** `GET /v1/compute/catalogue` answers *\"what can I build in this data centre\"* — a property of the location. This answers *\"what may THIS machine become\"*, which is not the same question at every provider: some return only the variants inside the machine's current pricing tier and refuse a Linux↔Windows switch, so two identical-looking machines in one zone can differ.\n\n⛔ Falls back to the provider's list where a provider has no per-machine answer, so an empty result means *this machine cannot be rebuilt*, never *we did not ask*. Requires `sites.view`.","tags":["compute"],"responses":{"200":{"description":"The operating systems and applications this machine may be rebuilt to.","content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ComputeImage"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/compute/servers/{serverId}/root-password":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"post":{"operationId":"setComputeServerRootPassword","summary":"Reset a server's root password. ⛔ Reboots the machine.","description":"⭐⭐ **The other half of \"I am locked out of my own server\"**, and the half a console alone does not solve: the console gets you to a login prompt, and this is what you type into it when the password is the thing you lost.\n\n⛔⛔ **The machine reboots.** The provider restarts the guest as part of applying the change, so everything running on it goes offline for a minute or two. A surface offering this must say so *before* the button, not in the result.\n\n⛔ Requires `sites.delete`, **not** `sites.restart`: a root password is total control of the machine and everything on it, which is the same order of trust as destroying it. The server's name must be typed to confirm, and that is checked server-side — a dialog the client owns is a dialog an API caller never sees.\n\n⛔ At least 16 characters, length only and no composition rules: this credential faces the public internet on port 22, and length is what makes it hard to guess. The value is never logged, never audited and never echoed back. `503` on a range whose provider publishes no reset (our own cloud installs an SSH key instead and mints no root password at all).","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["password","confirm"],"additionalProperties":false,"properties":{"password":{"type":"string","maxLength":128,"description":"The new root password. At least 16 characters."},"confirm":{"type":"string","maxLength":255,"description":"The server's name, typed exactly."}}}}}},"responses":{"204":{"description":"Accepted. The machine is restarting."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/administrator-password":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"post":{"operationId":"revealComputeServerAdministratorPassword","summary":"Show a Windows server's Administrator password.","description":"A Windows Server machine is reached over Remote Desktop with the Administrator password minted when it was built (SSH keys do not apply). We keep that password in our secret store until you delete it, and this call shows it. It is a POST so nothing caches or prefetches it, and the response is `Cache-Control: no-store`.\n\n⛔ Requires `sites.delete`, like the root-password reset: the password is total control of the machine. Each read is audit-logged as a fact (who, which machine), never with the value. `422` when no password is held: a Linux machine never has one, and a Windows one loses it once deleted. `503` when the secret store cannot be read.","tags":["compute"],"responses":{"200":{"description":"The Administrator credential.","content":{"application/json":{"schema":{"type":"object","required":["username","password"],"additionalProperties":false,"properties":{"username":{"type":"string","description":"Always `Administrator`."},"password":{"type":"string","description":"The password. Shown, never logged or audited."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"delete":{"operationId":"deleteComputeServerAdministratorPassword","summary":"Delete our copy of a Windows server's Administrator password.","description":"Once you have saved the password (or changed it on the machine), delete our copy. After this, nobody at Zinn Digital® can show it again. The deletion is audit-logged. It is also deleted automatically when the machine is cancelled.","tags":["compute"],"responses":{"204":{"description":"Deleted (or there was nothing to delete)."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/recovery":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"get":{"operationId":"getComputeServerRecovery","summary":"Read a server's rescue mode and installer-disc state.","description":"Whether the machine will boot a rescue system, which installer disc (ISO) is in its drive, and the discs this machine may mount (its own architecture only). Read live from the provider. Windows installer discs are never offered. `503` on a range that offers neither rescue mode nor installer discs.","tags":["compute"],"responses":{"200":{"description":"The recovery state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServerRecovery"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/rescue":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"post":{"operationId":"setComputeServerRescue","summary":"Turn rescue mode on or off. ⛔ Restarts the machine.","description":"On: the machine restarts into a rescue system that can read and change everything on its disk, with the machine's SSH keys installed. Requires `sites.delete` and the server's name typed in `confirm` (checked server-side). The rescue system's root password is in the response once; it is never logged, audited or stored. Off: requires `sites.restart`; the machine restarts from its own disk. `restarted` is `false` when the machine could not be restarted (for example a billing hold) — start it yourself.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["enabled"],"additionalProperties":false,"properties":{"enabled":{"type":"boolean"},"confirm":{"type":"string","maxLength":255,"description":"The server's name, typed exactly. Required when `enabled` is true."}}}}}},"responses":{"200":{"description":"Rescue mode changed.","content":{"application/json":{"schema":{"type":"object","required":["rescue_enabled","restarted","root_password"],"additionalProperties":false,"properties":{"rescue_enabled":{"type":"boolean"},"restarted":{"type":"boolean"},"root_password":{"type":["string","null"],"description":"The rescue system's root password, shown once. `null` when off."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/install-media":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"put":{"operationId":"setComputeServerInstallMedia","summary":"Mount an installer disc (restarts the machine) or eject it.","description":"`media_id` is an `id` from `available_install_media`; any other value is refused, so a disc the server is not offered (a Windows disc, another architecture) cannot be mounted by id. Mounting requires `sites.delete` and the server's name in `confirm`, because the machine restarts into an installer that can erase its disk. `null` ejects the disc (`sites.restart`); the machine keeps running.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["media_id"],"additionalProperties":false,"properties":{"media_id":{"type":["string","null"],"maxLength":64},"confirm":{"type":"string","maxLength":255,"description":"The server's name, typed exactly. Required when mounting."}}}}}},"responses":{"200":{"description":"The recovery state after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServerRecovery"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/name":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"post":{"operationId":"renameComputeServer","summary":"Rename a server.","description":"Set the machine's display name. The provider is changed first and our own record only if it agreed, so a customer is never shown a name their provider has never heard of.\n\nNames are limited to 37 characters because that is what the provider enforces. A name the provider refuses - too long, or already used on the account - returns 422 and changes nothing. Requires `sites.restart`.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServerRenameRequest"}}}},"responses":{"200":{"description":"The machine, with its new name.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServer"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/renewal":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"get":{"operationId":"getComputeServerRenewal","summary":"Read a server's billing contract.","description":"When the machine lapses at the provider, when **Zinn®** charges for it next, what that charge will be, and whether it renews at all. The provider's half is read live on every call rather than served from a stored copy: a cached copy is wrong exactly when somebody has just changed it.\n\n`renews_at` may be `\"\"` - that means the provider did not state one, never \"never\" and never \"free\". `auto_renew`, `subscription_id`, `charge_at`, `price_amount_minor` and `price_currency` are **ours**, not the provider's, and `charge_at` rather than `renews_at` is the date the money moves - see the schema. Requires `sites.view`.","tags":["compute"],"responses":{"200":{"description":"The machine's billing contract.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServerRenewal"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/cancel":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"post":{"operationId":"cancelComputeServer","summary":"Retire a server at the provider.","description":"**A scheduled retirement, not an immediate deletion, and a client MUST say so.** The machine keeps running until the term already paid for runs out; the provider then powers it down 24 hours later and deletes it after a further six days. The response carries `renews_at`, which is the date that countdown starts from - a \"Cancel\" button that silently means \"in 31 days\" is worse than no button at all.\n\nThe row is deliberately **not** marked terminated: it is still a working machine the customer is entitled to use, and marking it otherwise would strip every control off a server they are still paying for.\n\nRequires `sites.view` **and** `sites.delete` - ending a machine is a different order of trust from paying for one.","tags":["compute"],"responses":{"202":{"description":"On every range whose provider account we hold, the teardown runs as a durable workflow — release any add-on licence, stop the renewal, delete the machine, and settle its last metered hours from the balance — and the server comes back at `terminating`. It reaches `terminated` when the workflow finishes; a failure puts it back with `message` saying why.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServer"}}}},"200":{"description":"The contract after renewal was stopped.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServerRenewal"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/rebuild":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"post":{"operationId":"rebuildComputeServer","summary":"Reinstall a server's operating system.","description":"⛔⛔ **Destructive: everything on the disk is erased and cannot be recovered.** The machine comes back on a fresh image, so the answer carries `power_state: rebooting` and a client polls from there.\n\nThree guards, and none of them is optional. The caller needs `sites.delete` rather than the key that merely spends money — `dev` may commit the organisation to a billable resource without being trusted to destroy data, so this is deliberately **not** the key `resizeComputeServer` uses. The typed confirmation is re-checked **server-side**, because a dialog a client owns is a dialog an API caller skips: `confirm` must equal the server's `name` exactly, compared case-sensitively after surrounding whitespace, and anything else is `422`. And the action is audit-logged **before** the provider is called and left in place whatever happens, because an audit row written only on success leaves no trace of an attempted wipe that errored halfway — precisely the event an investigation is looking for.\n\n⛔ **`503` is the expected answer today, and it is honest.** No adapter currently advertises rebuild: a usable one needs the provider's own operating-system list, and an OS token we guessed would wipe a customer's machine and reinstall the wrong thing. It is a `503` rather than a `422` because it is **our** gap, and a customer told \"invalid input\" for a control nobody wired would retype the same thing for ever. `404` for a server that is not the caller's; `422` for an empty `operating_system` or a machine that is not `active`. Requires `sites.view` **and** `sites.delete`.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeRebuildRequest"}}}},"responses":{"200":{"description":"The server after the rebuild was accepted, rebooting into a fresh image.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServer"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/servers/{serverId}/reverse-dns":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"get":{"operationId":"getComputeServerReverseDns","summary":"The PTR of every public address on a machine.","description":"⭐ **The highest-value control on a machine we source ourselves**, and the platform had none anywhere before it. A freshly built machine's IPv4 PTR is the *supplier's* own hostname, which does two things at once: it **names our supplier** to anyone who runs `dig -x`, and it **breaks outbound mail**, because every receiving mail server of consequence checks forward-confirmed reverse DNS.\n\n⛔⛔ **A blank `hostname` means the address has NO PTR at all — it does not mean \"the default\".** Measured across every machine on our own account: each IPv4 carries a supplier default and each IPv6 carries nothing. Render the two differently, or you tell a customer their IPv6 leaks when it does not, and hide the address that does.\n\nRead live on every request and never cached: a PTR can be changed at the provider, and a cached one is a claim about the past presented as the present. Requires `sites.view`.","tags":["compute"],"responses":{"200":{"description":"One record per public address, IPv4 first.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeReverseDnsList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"put":{"operationId":"setComputeServerReverseDns","summary":"Point one address's PTR at a hostname, or reset it.","description":"⛔ `ip` is required and is never inferred from the machine: a machine has an IPv4 and an IPv6 address with **different** default states, so \"set the PTR of this server\" is not a well-formed request. An empty `hostname` resets that address to the provider's own default, which is a real thing to want and is not the same as leaving it alone.\n\n⛔⛔ **The hostname must resolve forward to this address, and that is checked before anything is written.** Receiving mail servers check forward-confirmed reverse DNS, so a PTR whose name does not point back is *worse* than the supplier's default: it looks configured on the screen and still fails delivery. A name that does not resolve at all is refused too — \"we could not look it up\" is not evidence the record exists.\n\nAn `ip` the machine does not hold is `422`, and that refusal is the tenancy boundary: the provider would happily set a PTR for any address on the account, including another customer's. Requires `sites.restart`.","tags":["compute"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeReverseDnsRequest"}}}},"responses":{"200":{"description":"Every record on the machine, re-read from the provider after the write.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeReverseDnsList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/ssh-keys":{"get":{"operationId":"listComputeSshKeys","summary":"The SSH keys this organisation has registered.","description":"⛔⛔ **Scoped to the organisation from our own rows, never the provider's list.** The provider's key list is account-wide — ours, our fleet's and every other customer's — so a screen built from it would show one customer another's key names and fingerprints.\n\n`?org_id=` is required only of a caller who belongs to more than one organisation. Requires `sites.view`.","tags":["compute"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The organisation's registered keys, oldest first.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeSshKeyList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"addComputeSshKey","summary":"Register a public key so a future order can install it.","description":"The provider is asked **first** and our row is written from its answer. A row written optimistically and then refused by the provider is a key the customer can select in the order form and that no machine can be built with — the refusal arriving after payment.\n\n⛔ The **public** half only. A private key is refused `422` with a sentence telling the customer to treat it as compromised and rotate it, rather than quietly stripped: somebody who has just pasted a private key needs to know they exposed it.\n\n⛔ A key already registered on the account is `422`. Key names and fingerprints are unique account-wide at the provider, which our tenancy cannot change, so this is a collision the screen has to explain rather than hide. Requires `billing.payment.manage`.","tags":["compute"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeSshKeyCreateRequest"}}}},"responses":{"201":{"description":"The registered key, with the provider's own fingerprint.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeSshKey"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/ssh-keys/{keyId}":{"parameters":[{"name":"keyId","in":"path","required":true,"description":"The provider's id for the key, as `listComputeSshKeys` reported it.","schema":{"type":"string","maxLength":64}}],"delete":{"operationId":"removeComputeSshKey","summary":"Forget a registered key.","description":"⛔⛔ **This does NOT revoke the key on machines already built.** It was copied into `authorized_keys` when each machine was created and lives on that disk afterwards. Removing it here stops it being offered on future orders and nothing else — say so on the screen, because a customer who believes this locked somebody out has been told something false about who can reach their machine. Requires `billing.payment.manage`.","tags":["compute"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"204":{"description":"Forgotten."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/eligibility":{"get":{"operationId":"getComputeEligibility","summary":"Whether this organisation may buy a machine on our own cloud.","description":"What stands between this organisation and a server on our own cloud (W43-50, owner ruling 2026-09-11): a **verified email** on an owner and a **verified card** before the first server; an **ID check only when a fraud signal fires** (or staff ask for one); and **limits** on what a new account may run — servers, vCPUs and committed monthly spend.\n\n`blockers` lists what is missing in the order the customer can act on it and `may_order` is true exactly when it is empty. ⛔ The signals that raised an ID check are deliberately absent: telling an applicant which detector fired tells a fraudster which input to change. Reading this may record a newly fired signal. Requires `sites.view`.","tags":["compute"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The organisation's verification state.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeEligibility"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"submitComputeEligibility","summary":"Submit an organisation for verification.","description":"Moves the organisation to `pending` for a human to review. **202**, because the answer is a decision somebody makes rather than something this call performs.\n\n⛔ An organisation that is already verified, or already pending, is refused `422` rather than silently re-queued: resubmitting would otherwise let a customer suspend their own verification, and let a rejected applicant re-enter the queue for ever. Requires `billing.payment.manage` — ⛔ **not** `billing.entitlement.manage`, a staff key no customer role holds, which is what this said until D10689.","tags":["compute"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeEligibilityRequest"}}}},"responses":{"202":{"description":"Submitted, and now awaiting review.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeEligibility"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/compute/eligibility/document":{"post":{"operationId":"registerComputeIdDocument","summary":"Get a presigned upload slot for the ID-check document.","description":"The bytes go straight from the browser to the private identity-document bucket and never through the engine: `PUT` the file to `upload.url` with `upload.headers` before `upload.expires_at`, then submit the check. ⛔ Refused `422` unless an ID check is required and not already under review — an identity document nobody asked for is one we would be holding without a purpose. JPEG, PNG or PDF, up to 10 MB. `503` when document storage is not configured (nothing is stored). Requires `billing.payment.manage`.","tags":["compute"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeIdDocumentUploadRequest"}}}},"responses":{"201":{"description":"An upload slot. The URL is a credential until it expires.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeIdDocumentUpload"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/compute/eligibility/verify-email":{"post":{"operationId":"sendComputeVerifyEmail","summary":"Email the caller a link that verifies their address.","description":"Sends the signed-in person a fresh verification link, so they can clear the verified-email step before their first server. ⛔ Only to the **caller**, and only when the caller is an owner of the organisation whose address is not yet verified — the step asks for an owner's address, and mailing anybody else from this button would be a way to spam any member. At most three links an hour per person (`422` beyond that). `503` when the email could not be sent. Requires `sites.view`.","tags":["compute"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"202":{"description":"The email was handed to the identity provider.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"type":"object","required":["sent","email"],"additionalProperties":false,"properties":{"sent":{"type":"boolean"},"email":{"type":"string","description":"The address the link was sent to."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/ads/connections":{"get":{"operationId":"listAdsConnections","summary":"The organisation's connected ad accounts.","description":"Gated on `ads.view`. Disconnected accounts are not listed. `pending_changes` counts the changes waiting for approval on each.","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"Narrow to one organisation in the caller's subtree. Never widens scope.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The connections.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsAccountConnection"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"operationId":"updateAdsConnection","summary":"The account's autopilot settings — modes, ceilings, hold, ROAS, markets, competitors.","description":"Gated on `ads.manage`; audit action `ads.connection_update` (metadata: what changed and, for modes, the classes that moved and to what). `status: paused` stops every write to the account. `modes` sets `off`, `approve` (the default) or `auto` per action class. Ceilings are integer minor units of the account's own currency; a raise that would take the enabled daily budgets past `daily_ceiling_minor`, or a month of them (x 30.4) past `monthly_ceiling_minor`, is refused. A plan rule refuses with 422 and `refusal.adsconnect.autopilotNotIncluded` / `competitorNotIncluded` / `languagesNotIncluded` / `badMarkets`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsConnectionSettingsUpdate"}}}},"responses":{"200":{"description":"The saved connection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsAccountConnection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/disconnect":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"disconnectAdsConnection","summary":"Disconnect an ad account; its token and all its data are deleted.","description":"Gated on `ads.manage`; audit actions `ads.connection_disconnect` and (once a revoke is final) `ads.grant_revoke`. Our copy of the token is forgotten and every row of the account's data is deleted (`deleted` counts rows per table). za-97: when this was the LAST live connection, in any organisation, made with that person's sign-in, the grant is revoked at the network too (Google, Meta, X); a network revoke withdraws the person's WHOLE grant to our app, so it is never sent while another connection still uses it (Q475). `revoke` says what happened: `revoked`, `already_invalid` (nothing left there), `retrying` (the network did not answer; retried on Temporal, never blocking the disconnect) or `kept` with its `reason` — `shared` (another connection uses the sign-in, or the same person is choosing accounts on the picker right now: the revoke then waits and goes ahead only if that picker is abandoned with nothing picked), `unsupported` (Microsoft, Pinterest: no revoke we may call) or `unconfirmed` (we could not prove no other connection uses it); `remove_url` is the network's own page where the person can remove Zinn® Ads themselves.","tags":["ads"],"responses":{"200":{"description":"Disconnected.","content":{"application/json":{"schema":{"type":"object","required":["id","status","forgotten","deleted","revoke"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["disconnected"]},"forgotten":{"type":"boolean"},"deleted":{"type":"object","additionalProperties":{"type":"integer"}},"revoke":{"$ref":"#/components/schemas/AdsGrantRevokeOutcome"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/relist":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"relistAdsConnectionAccounts","summary":"Add accounts from the sign-in this account was connected with.","description":"ADSUI1 (za-245). Gated on `ads.manage`; audit action `ads.connection_relist`. Lists again every ad account the connection's sign-in reaches now (accounts made at the network since appear), stores the list on that sign-in's grant and returns its id: the dashboard opens the ordinary account picker on it (`GET /v1/ads/connect/{network}/grants/{grant_id}`), where the accounts already connected are marked. `grant_id` is `null` when only a new sign-in can list them (the sign-in is gone, or the network refused its token).","tags":["ads"],"responses":{"200":{"description":"The grant to open the picker on, or null.","content":{"application/json":{"schema":{"type":"object","required":["grant_id","platform"],"properties":{"grant_id":{"type":["string","null"],"format":"uuid"},"platform":{"type":"string","enum":["google","microsoft","x","meta","chatgpt"]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/warm-start/end":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"endAdsWarmStart","summary":"End a new ad account's learning period early.","description":"za-264. Gated on `ads.manage`; audit action `ads.warm_start_end`. A new Google connection learns for 14 days (`warm_start_until`): its automatic changes are proposed for a person, and no bid-strategy switch is made by itself. Ending it sends the automatic changes by themselves from now on, each with its Undo. Refuses `notInWarmStart` when the account is not learning. Returns the connection.","tags":["ads"],"responses":{"200":{"description":"The connection, `warm_start_until` now null.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsAccountConnection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/universal-negatives":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsUniversalNegatives","summary":"The ad account's one list of universal negative keywords and its sync state.","description":"za-333. Gated on `ads.view`. The za-217 junk set (searches for a free host or a free blog platform) kept as ONE account-level negative keyword list on Google (at most 1,000 entries; an existing account-level list is used) and ONE shared negative keyword list associated with every campaign on Microsoft (at most 5,000), instead of a copy on every campaign. Each audit reads the account, adds what is missing through the change queue (approve-first, kill switches, good standing, the collision replay), reads the list back, and only then removes the per-campaign copies it covers, each with its Undo. `sync` is what the latest audit read and did (null before the first); read from the stored audit, never from the network in this request.","tags":["ads"],"responses":{"200":{"description":"The terms, the cap and the latest sync state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsUniversalNegatives"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connect/google":{"post":{"operationId":"startAdsConnectGoogle","summary":"Google's consent URL to connect Google Ads accounts.","description":"Gated on `ads.manage`. The browser goes to `authorize_url`; Google returns it to `/v1/ads/connect/google/callback`, which sends it on to the dashboard's account picker (`/ads?connect=pick&grant=<id>`). The state is signed and expires in ten minutes.","tags":["ads"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"The consent URL.","content":{"application/json":{"schema":{"type":"object","required":["authorize_url"],"properties":{"authorize_url":{"type":"string","format":"uri"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connect/google/callback":{"get":{"operationId":"adsConnectGoogleCallback","summary":"Google returns the browser here after consent.","description":"Unauthenticated by design: its authority is the signed `state`. Always answers with a redirect to the dashboard (`/ads?connect=pick&grant=<id>`, `cancelled`, `scope` or `failed`). Once the state verifies, the redirect also carries `&org=<id>` (the org the state names), so a person in several orgs lands on the org Connect was started from. ⛔ ALWAYS a redirect, never a JSON error (CBRETRY, 2026-11-02): this is the browser coming back from consent. A failed code exchange (a vendor timeout, a refusal, anything unexpected) redirects with `connect=failed&why=<class>`, `why` being the §2.57 class (`provider_outage`, `credential_problem` or `our_fault`) from the one classifier; the dashboard explains it (an outage links the network's `status_url` from `listAdsNetworks`) and offers a fresh Connect. The exchange retries a CONNECT failure (nothing reached the vendor) up to 5 times within the request; a read timeout or a vendor answer is never replayed, because the code is single-use. Every network's callback below behaves the same way.","tags":["ads"],"security":[],"parameters":[{"name":"state","in":"query","required":false,"schema":{"type":"string"}},{"name":"code","in":"query","required":false,"schema":{"type":"string"}},{"name":"error","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"302":{"description":"Back to the dashboard."}}}},"/v1/ads/connect/google/grants/{grant_id}":{"parameters":[{"name":"grant_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsConnectGoogleAccounts","summary":"The Google Ads accounts one sign-in reaches.","description":"Gated on `ads.manage`. Google: the whole manager tree the sign-in reaches (za-52) — an agency manager account (MCC), its sub-managers and every client account below them, each naming the manager it sits under (`parent_id`, `parent_name`); a manager itself is reached through, never connected. `connected` marks accounts the organisation already has.","tags":["ads"],"responses":{"200":{"description":"The accounts.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsGrantAccount"}},"failure":{"description":"Why the list is empty when the vendor REFUSED it (the §2.57 class, never the raw vendor text) — e.g. Microsoft's `IdentityTypeMismatch` (the Ads user signs in with Google). `null` when the vendor answered.","nullable":true,"allOf":[{"$ref":"#/components/schemas/VendorFailure"}]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"addAdsConnectGoogleAccounts","summary":"Connect the picked Google Ads accounts — one connection each.","description":"Gated on `ads.manage`; audit action `ads.connection_create`. Every action class starts `approve`. Up to 100 accounts a call.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["customer_ids"],"properties":{"customer_ids":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","pattern":"^\\d{6,12}$"}},"org_id":{"type":"string","format":"uuid"},"client_org_id":{"type":"string","format":"uuid","nullable":true,"description":"za-52: file the picked accounts under one of this organisation's CLIENT organisations (an agency signs in once with its manager account). The person must manage ads there; `noSuchClient` when it is not in this organisation's tree, `connectedElsewhere` when a picked account is already connected under another organisation of the tree."}}}}}},"responses":{"201":{"description":"The connections.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsAccountConnection"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connect/microsoft":{"post":{"operationId":"startAdsConnectMicrosoft","summary":"Microsoft's consent URL to connect Microsoft Advertising accounts (za-39).","description":"Gated on `ads.manage`. The same flow as Google's: the browser goes to `authorize_url` (the Microsoft identity platform, scope `https://ads.microsoft.com/msads.manage offline_access`); Microsoft returns it to `/v1/ads/connect/microsoft/callback`, which sends it on to the dashboard's account picker (`/ads?connect=pick&grant=<id>&platform=microsoft`). `msNotConfigured` until the Zinn® Ads Entra app's client is in Vault. Every refusal on the Microsoft path carries the Microsoft code (`msNoSuchGrant`, `msRefused`, …) whose words name Microsoft Advertising, never Google (MSFT1b).","tags":["ads"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"The consent URL.","content":{"application/json":{"schema":{"type":"object","required":["authorize_url"],"properties":{"authorize_url":{"type":"string","format":"uri"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connect/microsoft/callback":{"get":{"operationId":"adsConnectMicrosoftCallback","summary":"Microsoft returns the browser here after consent.","description":"Unauthenticated by design: its authority is the signed `state`, which must have been signed for Microsoft (a Google state is refused). Always answers with a redirect to the dashboard, as the Google callback does. When Microsoft returns an `error`, the AADSTS code in `error_description` decides the outcome: none (or `AADSTS65004`, declined) is `connect=cancelled`; any other is `connect=refused&reason=AADSTS<digits>` — only that fixed-shape code is forwarded, never the description text.","tags":["ads"],"security":[],"parameters":[{"name":"state","in":"query","required":false,"schema":{"type":"string"}},{"name":"code","in":"query","required":false,"schema":{"type":"string"}},{"name":"error","in":"query","required":false,"schema":{"type":"string"}},{"name":"error_description","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"302":{"description":"Back to the dashboard."}}}},"/v1/ads/connect/microsoft/grants/{grant_id}":{"parameters":[{"name":"grant_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsConnectMicrosoftAccounts","summary":"The Microsoft Advertising accounts one sign-in reaches.","description":"Gated on `ads.manage`. Every ad account the signed-in Microsoft user can reach, with its manager (customer) id as `login_customer_id`. `connected` marks accounts the organisation already has.","tags":["ads"],"responses":{"200":{"description":"The accounts.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsGrantAccount"}},"failure":{"description":"Why the list is empty when the vendor REFUSED it (the §2.57 class, never the raw vendor text) — e.g. Microsoft's `IdentityTypeMismatch` (the Ads user signs in with Google). `null` when the vendor answered.","nullable":true,"allOf":[{"$ref":"#/components/schemas/VendorFailure"}]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"addAdsConnectMicrosoftAccounts","summary":"Connect the picked Microsoft Advertising accounts — one connection each.","description":"Gated on `ads.manage`; audit action `ads.connection_create`. Every action class starts `approve`. Up to 100 accounts a call; `customer_ids` are Microsoft account ids.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["customer_ids"],"properties":{"customer_ids":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","pattern":"^\\d{4,20}$"}},"org_id":{"type":"string","format":"uuid"},"client_org_id":{"type":"string","format":"uuid","nullable":true,"description":"za-52: file the picked accounts under one of this organisation's CLIENT organisations (an agency signs in once with its manager account). The person must manage ads there; `noSuchClient` when it is not in this organisation's tree, `connectedElsewhere` when a picked account is already connected under another organisation of the tree."}}}}}},"responses":{"201":{"description":"The connections.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsAccountConnection"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connect/x":{"post":{"operationId":"startAdsConnectX","summary":"X's authorize URL to connect X ad accounts (XADS1).","description":"Gated on `ads.manage`. The same flow as Google's and Microsoft's, over OAuth 1.0a: the engine asks X for a request token (its secret waits in Vault, never in a URL), the browser goes to `authorize_url` (`api.x.com/oauth/authorize`), and X returns it to `/v1/ads/connect/x/callback`, which sends it on to the dashboard's account picker (`/ads?connect=pick&grant=<id>&platform=x`). Every refusal on the X path carries the X code (`xNotConfigured`, `xNoSuchGrant`, `xRefused`, …) whose words name X Ads, never Google or Microsoft.","tags":["ads"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"The authorize URL.","content":{"application/json":{"schema":{"type":"object","required":["authorize_url"],"properties":{"authorize_url":{"type":"string","format":"uri"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connect/x/callback":{"get":{"operationId":"adsConnectXCallback","summary":"X returns the browser here after the person authorises Zinn® Ads.","description":"Unauthenticated by design: its authority is the signed `state` (carried on the return address the engine gave X, and signed for X — a Google or Microsoft state is refused) plus the request token's secret kept in Vault, used once. `denied` (the person said no) is `connect=cancelled`; a missing token or verifier, or an expired sign-in, is `connect=failed`. Always answers with a redirect to the dashboard.","tags":["ads"],"security":[],"parameters":[{"name":"state","in":"query","required":false,"schema":{"type":"string"}},{"name":"oauth_token","in":"query","required":false,"schema":{"type":"string"}},{"name":"oauth_verifier","in":"query","required":false,"schema":{"type":"string"}},{"name":"denied","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"302":{"description":"Back to the dashboard."}}}},"/v1/ads/connect/x/grants/{grant_id}":{"parameters":[{"name":"grant_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsConnectXAccounts","summary":"The X ad accounts one X sign-in reaches — live and sandbox.","description":"Gated on `ads.manage`. Every ad account the signed-in X user can reach on X's live Ads API, then every SANDBOX account (`sandbox: true`, id `sbx-<id>`): a sandbox account runs no ads and spends nothing, for trying Zinn® Ads safely. `connected` marks accounts the organisation already has.","tags":["ads"],"responses":{"200":{"description":"The accounts.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsGrantAccount"}},"failure":{"description":"Why the list is empty when X REFUSED it (the §2.57 class, never the raw vendor text). `null` when X answered.","nullable":true,"allOf":[{"$ref":"#/components/schemas/VendorFailure"}]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"addAdsConnectXAccounts","summary":"Connect the picked X ad accounts — one connection each.","description":"Gated on `ads.manage`; audit action `ads.connection_create`. Every action class starts `approve`. Up to 100 accounts a call; `customer_ids` are X ad account ids (lower-case base-36, a sandbox one as `sbx-<id>`). A change approved for a LIVE X account is refused with `xWritesOff` until live X writes are switched on (Vault `secret/platform/x-ads` `production_writes`); a sandbox account is written normally.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["customer_ids"],"properties":{"customer_ids":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","pattern":"^(?:sbx-)?[a-z0-9]{1,24}$"}},"org_id":{"type":"string","format":"uuid"},"client_org_id":{"type":"string","format":"uuid","nullable":true,"description":"za-52: file the picked accounts under one of this organisation's CLIENT organisations (an agency signs in once with its manager account). The person must manage ads there; `noSuchClient` when it is not in this organisation's tree, `connectedElsewhere` when a picked account is already connected under another organisation of the tree."}}}}}},"responses":{"201":{"description":"The connections.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsAccountConnection"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connect/meta":{"post":{"operationId":"startAdsConnectMeta","summary":"Meta's authorize URL to connect Meta (Facebook and Instagram) ad accounts (za-40).","description":"Gated on `ads.manage`. The same flow as Google's and Microsoft's, over Facebook Login for Business (OAuth 2, scope `ads_read`): the browser goes to `authorize_url` (`www.facebook.com/<version>/dialog/oauth`) and Meta returns it to `/v1/ads/connect/meta/callback`, which sends it on to the dashboard's account picker (`/ads?connect=pick&grant=<id>&platform=meta`). Meta is READ-ONLY in Zinn® Ads for now: campaigns and spend are read, nothing is changed (a write is refused `readOnlyNetwork`). Every refusal on the Meta path carries the Meta code (`metaNotConfigured`, `metaNoSuchGrant`, `metaScopeNotGranted`, …) whose words name Meta, never Google.","tags":["ads"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"The authorize URL.","content":{"application/json":{"schema":{"type":"object","required":["authorize_url"],"properties":{"authorize_url":{"type":"string","format":"uri"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connect/meta/callback":{"get":{"operationId":"adsConnectMetaCallback","summary":"Meta returns the browser here after the person authorises Zinn® Ads.","description":"Unauthenticated by design: its authority is the signed `state` (signed for Meta — a Google, Microsoft or X state is refused). `error` (the person said no) is `connect=cancelled`; a missing code, a sign-in without `ads_read` (`connect=scope`) or an expired sign-in is refused. The short-lived token is exchanged for a long-lived one and kept in Vault only. Always answers with a redirect to the dashboard.","tags":["ads"],"security":[],"parameters":[{"name":"state","in":"query","required":false,"schema":{"type":"string"}},{"name":"code","in":"query","required":false,"schema":{"type":"string"}},{"name":"error","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"302":{"description":"Back to the dashboard."}}}},"/v1/ads/connect/meta/grants/{grant_id}":{"parameters":[{"name":"grant_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsConnectMetaAccounts","summary":"The Meta ad accounts one Facebook sign-in reaches.","description":"Gated on `ads.manage`. Every ad account the signed-in person can reach (`/me/adaccounts`), id without the `act_` prefix. `connected` marks accounts the organisation already has.","tags":["ads"],"responses":{"200":{"description":"The accounts.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsGrantAccount"}},"failure":{"description":"Why the list is empty when Meta REFUSED it (the §2.57 class, never the raw vendor text). `null` when Meta answered.","nullable":true,"allOf":[{"$ref":"#/components/schemas/VendorFailure"}]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"addAdsConnectMetaAccounts","summary":"Connect the picked Meta ad accounts — one connection each — and read them.","description":"Gated on `ads.manage`; audit action `ads.connection_create`. Up to 100 accounts a call; `customer_ids` are Meta ad account ids (digits, no `act_`). Each new connection's first campaigns-and-spend read starts on its own (Temporal), read back with `getAdsMetaCampaigns`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["customer_ids"],"properties":{"customer_ids":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","pattern":"^\\d{4,20}$"}},"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"201":{"description":"The connections.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsAccountConnection"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connect/linkedin":{"post":{"operationId":"startAdsConnectLinkedIn","summary":"LinkedIn's authorize URL to connect LinkedIn ad accounts (za-41).","description":"Gated on `ads.manage`. The same flow as Google's and Meta's, over LinkedIn OAuth 2 (scopes `r_ads r_ads_reporting`): the browser goes to `authorize_url` (`www.linkedin.com/oauth/v2/authorization`) and LinkedIn returns it to `/v1/ads/connect/linkedin/callback`, which sends it on to the dashboard's account picker (`/ads?connect=pick&grant=<id>&platform=linkedin`). LinkedIn is READ-ONLY in Zinn® Ads for now: campaigns and spend are read, nothing is changed (a write is refused `readOnlyNetwork`). Every refusal on the LinkedIn path carries the network-neutral code (`netNotConfigured`, `netNoSuchGrant`, `netScopeNotGranted`, …) whose words name LinkedIn Ads through `{network}`, never Google.","tags":["ads"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"The authorize URL.","content":{"application/json":{"schema":{"type":"object","required":["authorize_url"],"properties":{"authorize_url":{"type":"string","format":"uri"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connect/linkedin/callback":{"get":{"operationId":"adsConnectLinkedInCallback","summary":"LinkedIn returns the browser here after the member authorises Zinn® Ads.","description":"Unauthenticated by design: its authority is the signed `state` (signed for LinkedIn — a state signed for another network is refused). `error` (the member cancelled, e.g. `user_cancelled_login`) is `connect=cancelled`; a missing code, a sign-in without both ad scopes or an expired sign-in is refused. The code is exchanged for a refresh token (a year; LinkedIn does not rotate it) kept in Vault only. Always answers with a redirect to the dashboard.","tags":["ads"],"security":[],"parameters":[{"name":"state","in":"query","required":false,"schema":{"type":"string"}},{"name":"code","in":"query","required":false,"schema":{"type":"string"}},{"name":"error","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"302":{"description":"Back to the dashboard."}}}},"/v1/ads/connect/linkedin/grants/{grant_id}":{"parameters":[{"name":"grant_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsConnectLinkedInAccounts","summary":"The LinkedIn ad accounts one LinkedIn sign-in reaches.","description":"Gated on `ads.manage`. Every ad account the signed-in member can reach (`/rest/adAccounts?q=search`), by its numeric id. `connected` marks accounts the organisation already has.","tags":["ads"],"responses":{"200":{"description":"The accounts.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsGrantAccount"}},"failure":{"description":"Why the list is empty when LinkedIn REFUSED it (the §2.57 class, never the raw vendor text). `null` when LinkedIn answered.","nullable":true,"allOf":[{"$ref":"#/components/schemas/VendorFailure"}]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"addAdsConnectLinkedInAccounts","summary":"Connect the picked LinkedIn ad accounts — one connection each — and read them.","description":"Gated on `ads.manage`; audit action `ads.connection_create`. Up to 100 accounts a call; `customer_ids` are LinkedIn ad account ids (digits). Each new connection's first campaigns-and-spend read starts on its own (Temporal), read back with `getAdsNetworkCampaigns`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["customer_ids"],"properties":{"customer_ids":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","pattern":"^\\d{4,20}$"}},"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"201":{"description":"The connections.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsAccountConnection"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connect/chatgpt":{"post":{"operationId":"connectAdsChatGPTKey","summary":"Connect ChatGPT Ads with an Advertiser API key (za-318).","description":"Gated on `ads.manage`. ChatGPT Ads (OpenAI) has no OAuth app open to us (OpenAI publishes no client registration for its `AdsOAuth` scheme; it is the API-partner path), so the customer pastes an Advertiser API key made at https://ads.openai.com/settings. One key reaches ONE ad account. The key is read against OpenAI's `GET /v1/ad_account` at once and kept in Vault as the grant (never in the database, never echoed); the answer is the grant id the ordinary account picker reads (`listAdsConnectChatGPTAccounts`). A value that cannot be a key is a `422` `netBadKey` before any call. A key OpenAI refuses still answers a grant whose picker carries the §2.57 `failure` (a rejected key links the keys page). Not gated on \"Coming soon\" (that gates the dashboard's offer). ChatGPT Ads writes (an ad group paused or resumed, a campaign's daily spend limit) are ON for a customer's own connection (owner 2026-11-09): an approved change goes through the approve-first queue, ceilings and Undo. The emergency switch `ZINN_ADS_CHATGPT_WRITES` set to anything but `on` (or unset) refuses every write `chatgptWritesOff`, and a house connection (the platform org or a staff org) is always refused the same way; nothing reaches OpenAI when refused.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["api_key"],"properties":{"api_key":{"type":"string","writeOnly":true,"maxLength":512,"description":"The Advertiser API key (a secret; never returned)."},"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"201":{"description":"The grant the account picker reads.","content":{"application/json":{"schema":{"type":"object","required":["grant_id"],"properties":{"grant_id":{"type":"string","format":"uuid"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connect/chatgpt/grants/{grant_id}":{"parameters":[{"name":"grant_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsConnectChatGPTAccounts","summary":"The ChatGPT Ads account one Advertiser API key reaches.","description":"Gated on `ads.manage`. The one ad account the key reaches (`GET /v1/ad_account`), with its currency, time zone, status and brand `review_status` (an account cannot serve until OpenAI approves its brand). `connected` marks an account the organisation already has.","tags":["ads"],"responses":{"200":{"description":"The account.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsGrantAccount"}},"failure":{"description":"Why the list is empty when OpenAI REFUSED the key (the §2.57 class, never the raw vendor text). `null` when OpenAI answered.","nullable":true,"allOf":[{"$ref":"#/components/schemas/VendorFailure"}]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"addAdsConnectChatGPTAccounts","summary":"Connect the key's ChatGPT Ads account and start reading its figures.","description":"Gated on `ads.manage`; audit action `ads.connection_create`. `customer_ids` is the account id the picker listed (`adacct_…`, lower case). The new connection's day figures (spend, clicks, impressions and conversions per ad group and day, money as integer micros of the account currency) start reading on their own (Temporal), READ ONLY, then the history backfill.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["customer_ids"],"properties":{"customer_ids":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,63}$"}},"client_org_id":{"type":"string","format":"uuid","nullable":true},"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"201":{"description":"The connections.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsAccountConnection"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connect/amazon":{"post":{"operationId":"startAdsConnectAmazon","summary":"Login with Amazon's authorize URL to connect Amazon Ads profiles (za-45).","description":"Gated on `ads.manage`. The same flow as Meta's, over Login with Amazon (scope `advertising::campaign_management`): the browser goes to `authorize_url` (`www.amazon.com/ap/oa`) and Amazon returns it to `/v1/ads/connect/amazon/callback`, which sends it on to the dashboard's account picker (`/ads?connect=pick&grant=<id>&platform=amazon`). Zinn® Ads reads Amazon's Sponsored Products campaigns, spend and search terms; the daily audit proposes exact campaign negatives and phrase keywords, each sent only through the approve-first change queue with its Undo (never a bid or a budget). A change approved while Amazon Ads writes are switched off, or for a house connection, is refused `amazonWritesOff`. Every refusal on the Amazon path carries the network-neutral code (`netNotConfigured`, `netNoSuchGrant`, `netScopeNotGranted`, …) whose words name the network through `{network}` (Amazon Ads), never Google.","tags":["ads"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"The authorize URL.","content":{"application/json":{"schema":{"type":"object","required":["authorize_url"],"properties":{"authorize_url":{"type":"string","format":"uri"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connect/amazon/callback":{"get":{"operationId":"adsConnectAmazonCallback","summary":"Login with Amazon returns the browser here after the person authorises Zinn® Ads.","description":"Unauthenticated by design: its authority is the signed `state` (signed for Amazon — a state for any other network is refused). `error` (the person said no) is `connect=cancelled`; a missing code, a sign-in without `advertising::campaign_management` (`connect=scope`) or an expired sign-in is refused. The refresh token is kept in Vault only (Login with Amazon refresh tokens do not rotate). Always answers with a redirect to the dashboard.","tags":["ads"],"security":[],"parameters":[{"name":"state","in":"query","required":false,"schema":{"type":"string"}},{"name":"code","in":"query","required":false,"schema":{"type":"string"}},{"name":"error","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"302":{"description":"Back to the dashboard."}}}},"/v1/ads/connect/amazon/grants/{grant_id}":{"parameters":[{"name":"grant_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsConnectAmazonAccounts","summary":"The Amazon Ads profiles one Login with Amazon sign-in reaches.","description":"Gated on `ads.manage`. Every advertising profile the signed-in person can reach on each regional host (North America, Europe, Far East; `GET /v2/profiles`), each as `<region>-<profileId>`. `connected` marks accounts the organisation already has.","tags":["ads"],"responses":{"200":{"description":"The accounts.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsGrantAccount"}},"failure":{"description":"Why the list is empty when Amazon REFUSED it (the §2.57 class, never the raw vendor text). `null` when Amazon answered.","nullable":true,"allOf":[{"$ref":"#/components/schemas/VendorFailure"}]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"addAdsConnectAmazonAccounts","summary":"Connect the picked Amazon Ads profiles — one connection each — and read them.","description":"Gated on `ads.manage`; audit action `ads.connection_create`. Up to 100 profiles a call; `customer_ids` are `<region>-<profileId>` (`na`, `eu` or `fe`). Each new connection's first campaigns-and-spend read starts on its own (Temporal). Amazon builds reports asynchronously: the workflow requests a v3 Sponsored Products report and polls it with durable timers (up to 6 h) — no worker waits on it; read back with `getAdsNetworkCampaigns`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["customer_ids"],"properties":{"customer_ids":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","pattern":"^(?:na|eu|fe)-\\d{1,20}$"}},"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"201":{"description":"The connections.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsAccountConnection"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connect/pinterest":{"post":{"operationId":"startAdsConnectPinterest","summary":"Pinterest's authorize URL to connect Pinterest ad accounts (za-44).","description":"Gated on `ads.manage`. The same flow as Meta's, over Pinterest OAuth 2 (scopes `ads:read` and `user_accounts:read`): the browser goes to `authorize_url` (`www.pinterest.com/oauth/`) and Pinterest returns it to `/v1/ads/connect/pinterest/callback`, which sends it on to the dashboard's account picker (`/ads?connect=pick&grant=<id>&platform=pinterest`). Pinterest is READ-ONLY in Zinn® Ads for now: campaigns and spend are read, nothing is changed (a write is refused `readOnlyNetwork`). Every refusal on the Pinterest path carries the network-neutral code (`netNotConfigured`, `netNoSuchGrant`, `netScopeNotGranted`, …) whose words name the network through `{network}` (Pinterest Ads), never Google.","tags":["ads"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"The authorize URL.","content":{"application/json":{"schema":{"type":"object","required":["authorize_url"],"properties":{"authorize_url":{"type":"string","format":"uri"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connect/pinterest/callback":{"get":{"operationId":"adsConnectPinterestCallback","summary":"Pinterest returns the browser here after the person authorises Zinn® Ads.","description":"Unauthenticated by design: its authority is the signed `state` (signed for Pinterest — a state for any other network is refused). `error` (the person said no) is `connect=cancelled`; a missing code, a sign-in without `ads:read` (`connect=scope`) or an expired sign-in is refused. The refresh token is kept in Vault only; Pinterest rotates it on every refresh and the driver writes each new one back. Always answers with a redirect to the dashboard.","tags":["ads"],"security":[],"parameters":[{"name":"state","in":"query","required":false,"schema":{"type":"string"}},{"name":"code","in":"query","required":false,"schema":{"type":"string"}},{"name":"error","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"302":{"description":"Back to the dashboard."}}}},"/v1/ads/connect/pinterest/grants/{grant_id}":{"parameters":[{"name":"grant_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsConnectPinterestAccounts","summary":"The Pinterest ad accounts one Pinterest sign-in reaches.","description":"Gated on `ads.manage`. Every ad account the signed-in person can reach (`GET /v5/ad_accounts`). `connected` marks accounts the organisation already has.","tags":["ads"],"responses":{"200":{"description":"The accounts.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsGrantAccount"}},"failure":{"description":"Why the list is empty when Pinterest REFUSED it (the §2.57 class, never the raw vendor text). `null` when Pinterest answered.","nullable":true,"allOf":[{"$ref":"#/components/schemas/VendorFailure"}]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"addAdsConnectPinterestAccounts","summary":"Connect the picked Pinterest ad accounts — one connection each — and read them.","description":"Gated on `ads.manage`; audit action `ads.connection_create`. Up to 100 accounts a call; `customer_ids` are Pinterest ad account ids (digits). Each new connection's first campaigns-and-spend read starts on its own (Temporal), read back with `getAdsNetworkCampaigns`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["customer_ids"],"properties":{"customer_ids":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","pattern":"^\\d{4,20}$"}},"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"201":{"description":"The connections.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsAccountConnection"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connect/tiktok":{"post":{"operationId":"startAdsConnectTikTok","summary":"TikTok's authorize URL to connect TikTok advertisers (za-42).","description":"Gated on `ads.manage`. The same flow as Meta's, over TikTok's advertiser authorization (TikTok API for Business v1.3): the browser goes to `authorize_url` (`business-api.tiktok.com/portal/auth`) and TikTok returns it to `/v1/ads/connect/tiktok/callback`, which sends it on to the dashboard's account picker (`/ads?connect=pick&grant=<id>&platform=tiktok`). TikTok is READ-ONLY in Zinn® Ads for now: campaigns and spend are read, nothing is changed (a write is refused `readOnlyNetwork`). Every refusal on the TikTok path carries the network-neutral code (`netNotConfigured`, `netNoSuchGrant`, …) whose words name the network through `{network}` (TikTok Ads), never Google.","tags":["ads"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"The authorize URL.","content":{"application/json":{"schema":{"type":"object","required":["authorize_url"],"properties":{"authorize_url":{"type":"string","format":"uri"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connect/tiktok/callback":{"get":{"operationId":"adsConnectTikTokCallback","summary":"TikTok returns the browser here after the person authorises Zinn® Ads.","description":"Unauthenticated by design: its authority is the signed `state` (signed for TikTok — a state for any other network is refused). TikTok sends the code as `auth_code` (`code` is accepted too); no code, or an expired sign-in, is `connect=failed`. The token is kept in Vault only: a long-lived advertiser access token, or a refresh token TikTok rotates on each refresh (the driver writes each new one back). Always answers with a redirect to the dashboard.","tags":["ads"],"security":[],"parameters":[{"name":"state","in":"query","required":false,"schema":{"type":"string"}},{"name":"auth_code","in":"query","required":false,"schema":{"type":"string"}},{"name":"code","in":"query","required":false,"schema":{"type":"string"}},{"name":"error","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"302":{"description":"Back to the dashboard."}}}},"/v1/ads/connect/tiktok/grants/{grant_id}":{"parameters":[{"name":"grant_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsConnectTikTokAccounts","summary":"The TikTok advertisers one TikTok sign-in reaches.","description":"Gated on `ads.manage`. Every advertiser the signed-in person granted, with its name and currency (`GET /open_api/v1.3/advertiser/info/`). `connected` marks accounts the organisation already has.","tags":["ads"],"responses":{"200":{"description":"The accounts.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsGrantAccount"}},"failure":{"description":"Why the list is empty when TikTok REFUSED it (the §2.57 class, never the raw vendor text). `null` when TikTok answered.","nullable":true,"allOf":[{"$ref":"#/components/schemas/VendorFailure"}]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"addAdsConnectTikTokAccounts","summary":"Connect the picked TikTok advertisers — one connection each — and read them.","description":"Gated on `ads.manage`; audit action `ads.connection_create`. Up to 100 accounts a call; `customer_ids` are TikTok advertiser ids (digits). Each new connection's first campaigns-and-spend read starts on its own (Temporal), read back with `getAdsNetworkCampaigns`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["customer_ids"],"properties":{"customer_ids":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","pattern":"^\\d{4,20}$"}},"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"201":{"description":"The connections.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsAccountConnection"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/meta/campaigns":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsMetaCampaigns","summary":"A Meta account's campaigns and spend over the last 30 days (za-40).","description":"Gated on `ads.view`. The stored reading (never a call to Meta in the request): `reading` is `null` until the first read finishes. `figures` carries `currency`, `since`, `until`, `spend_micros` (integer micros of the account currency) and `campaigns[]` (`campaign_id`, `name`, `status`, `objective`, `spend_micros`, `impressions`, `clicks`), biggest spend first; a campaign with no delivery is listed with zeros. A failed read replaces the figures with `failure` (the §2.57 class). A connection that is not Meta is a `422` `refusal.adsconnect.campaignsNotOnNetwork` (FIX13).","tags":["ads"],"responses":{"200":{"description":"The reading.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["connection_id","reading"],"properties":{"connection_id":{"type":"string","format":"uuid"},"reading":{"oneOf":[{"$ref":"#/components/schemas/AdsInsightReading"},{"type":"null"}]}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/meta/campaigns/refresh":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"refreshAdsMetaCampaigns","summary":"Read a Meta account's campaigns and spend again now.","description":"Gated on `ads.manage`. Starts one read on Temporal (one per connection per minute, so a double click is one read) and answers 202; 503 when the workflow could not be started.","tags":["ads"],"responses":{"202":{"description":"Started.","content":{"application/json":{"schema":{"type":"object","required":["connection_id","started"],"properties":{"connection_id":{"type":"string","format":"uuid"},"started":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"description":"The read could not be started; try again shortly.","content":{"application/json":{"schema":{"type":"object","required":["connection_id","started"],"properties":{"connection_id":{"type":"string","format":"uuid"},"started":{"type":"boolean"}}}}}}}}},"/v1/ads/networks":{"get":{"operationId":"listAdsNetworks","summary":"Every ad network Zinn® Ads has a driver for (za-54).","description":"Gated on `ads.view`. Read from the one network registry (docs/1006 §66), never a call to a vendor. Each row names the network (`label`, a proper noun), the click id it adds to a landing URL, what the autopilot does there (`capabilities[]`, stable codes from `search_terms`, `keywords`, `negatives`, `bids`, `budgets`, `audiences`, `creatives`, `placements`), whether its campaigns and spend are read into the stored reading (`campaign_feed`), whether the daily audit runs on it (`audit`) and whether it can be connected now (`available`: its app credentials are configured).","tags":["ads"],"responses":{"200":{"description":"The networks, in registry order.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["platform","label","click_id","capabilities","campaign_feed","audit","conversion_upload","truth_check","writes","available","status_url"],"properties":{"platform":{"type":"string"},"label":{"type":"string"},"click_id":{"type":"string"},"capabilities":{"type":"array","items":{"type":"string","enum":["search_terms","keywords","negatives","bids","budgets","audiences","creatives","placements"]}},"campaign_feed":{"type":"boolean"},"audit":{"type":"boolean"},"conversion_upload":{"type":"boolean","description":"ZA320-FU2: conversion tracking UPLOADS to this network (missed-conversion recovery, upload actions, profit values, CRM / checkout / product sources)."},"truth_check":{"type":"boolean","description":"ZA320-FU2: the tracking truth check reads what this network credited (ChatGPT Ads: read only, no upload)."},"writes":{"type":"boolean","description":"ADSINTRO r2: Zinn® Ads sends changes to this network (approve-first, 30-day undo). `false` = reports only: its driver refuses every write and the audit proposes nothing there."},"available":{"type":"boolean"},"status_url":{"type":"string","description":"The network's own status board (the §2.57 vendor registry), `\"\"` when it publishes none. The Connect screen links it when a sign-in failed with `why=provider_outage` (CBRETRY)."}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/imported":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsImportedAccount","summary":"The connected Google Ads account's whole structure as last read (za-262).","description":"Gated on `ads.view`. Read on Temporal when the account is connected, on Refresh and weekly by the daily audit — never Google in the request. `state` is `notRead` until the first read, `ok` with `import`, or `failed` with `error` (a failed read never shows old figures as current). `import` carries the account's campaigns (status, channel, daily budget in micros, shared budget, bid strategy and its target, Google's bidding-strategy status, ad groups, keywords by match type, ads, negatives, location targets), its conversion actions and totals. Read only: nothing is written to the account. A connection on another network is a `422` `refusal.adsconnect.platformNotSupported`. `history` (za-263) is the account's OWN history read back month by month to the retention edge (400 days) after the first read — `null` until it starts; its figures are the ad-group totals now stored. `plan` (za-265) is the optimisation plan built from that history once it is read (and at most weekly after) — `null` until then: what WORKS (kept and protected from automatic pauses), the measured waste and the structural steps, every write a PENDING change in the approvals queue (`change_id`), never applied by itself.","tags":["ads"],"responses":{"200":{"description":"The stored reading.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["connection_id","state","read_at","import","error","history","plan"],"properties":{"connection_id":{"type":"string","format":"uuid"},"state":{"type":"string","enum":["notRead","ok","failed"]},"read_at":{"type":["string","null"],"format":"date-time"},"import":{"oneOf":[{"$ref":"#/components/schemas/AdsImportedAccount"},{"type":"null"}]},"error":{"type":["string","null"]},"history":{"oneOf":[{"$ref":"#/components/schemas/AdsImportedHistory"},{"type":"null"}]},"plan":{"oneOf":[{"$ref":"#/components/schemas/AdsImportedPlan"},{"type":"null"}]}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/imported/refresh":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"refreshAdsImportedAccount","summary":"Read the connected Google Ads account's structure again now (za-262).","description":"Gated on `ads.manage`. Starts one read on Temporal (one per connection per minute) and answers 202; 503 when the workflow could not be started. A disconnected connection is a `422` `refusal.adsconnect.disconnected`.","tags":["ads"],"responses":{"202":{"description":"Started.","content":{"application/json":{"schema":{"type":"object","required":["connection_id","started"],"properties":{"connection_id":{"type":"string","format":"uuid"},"started":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"description":"The read could not be started (Temporal unreachable); try again.","content":{"application/json":{"schema":{"type":"object","required":["connection_id","started"],"properties":{"connection_id":{"type":"string","format":"uuid"},"started":{"type":"boolean"}}}}}}}}},"/v1/ads/connections/{connection_id}/network-campaigns":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsNetworkCampaigns","summary":"Any campaign-feed network account's campaigns and spend over the last 30 days (za-54).","description":"Gated on `ads.view`. The same stored reading as `getAdsMetaCampaigns`, for every network whose registry row is a campaign feed (`campaign_feed` in `listAdsNetworks`). `reading` is `null` until the first read finishes; a failed read carries `failure` (the §2.57 class). A connection on a network that is not a campaign feed is a `422` `refusal.adsconnect.campaignsNotOnNetwork` (FIX13). A network whose report is built asynchronously (Amazon Ads, za-45) stores nothing while the report is being built, so `reading` stays at the previous reading (or `null`); a report Amazon fails is `reportFailed`, and one still not ready after 6 hours is `reportNotReady`.","tags":["ads"],"responses":{"200":{"description":"The reading.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["connection_id","reading"],"properties":{"connection_id":{"type":"string","format":"uuid"},"reading":{"oneOf":[{"$ref":"#/components/schemas/AdsInsightReading"},{"type":"null"}]}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/network-campaigns/refresh":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"refreshAdsNetworkCampaigns","summary":"Read a campaign-feed network account's campaigns and spend again now (za-54).","description":"Gated on `ads.manage`. Starts one read on Temporal (one per connection per minute) and answers 202; 503 when the workflow could not be started.","tags":["ads"],"responses":{"202":{"description":"Started.","content":{"application/json":{"schema":{"type":"object","required":["connection_id","started"],"properties":{"connection_id":{"type":"string","format":"uuid"},"started":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"description":"The read could not be started; try again shortly.","content":{"application/json":{"schema":{"type":"object","required":["connection_id","started"],"properties":{"connection_id":{"type":"string","format":"uuid"},"started":{"type":"boolean"}}}}}}}}},"/v1/ads/connections/{connection_id}/budget-flags":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsBudgetFlags","summary":"Campaigns held back by their budget while they convert (za-142).","description":"Gated on `ads.view`. Refreshed by the connection's daily audit (AUTO3); a campaign no longer held back is no longer listed. Most impressions lost first, at most 200.","tags":["ads"],"responses":{"200":{"description":"The open flags.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsBudgetFlag"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/findings":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsFindings","summary":"What the daily audit found on the account, with its figures (FINDALL1, za-211).","description":"Gated on `ads.view`. Every detector of the audit (docs/1006 §38) writes what it finds here — never a count alone: open suggestions first (most recently seen first), then the automatic changes of the last 30 days. `why` is the reason the screen says in words (an empty `why` → the `kind`'s own words); `figures` are the finding's numbers (estimates say so in `estimate`), never an internal resource name. Read from the rows the audit stored — never a network call in the request. At most 200.","tags":["ads"],"responses":{"200":{"description":"The findings.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsFinding"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/landing-pages":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsLandingPages","summary":"Every ad final URL's last landing-page check (LPDIAG2, za-205/za-209).","description":"Gated on `ads.view`. The daily audit renders each enabled ad's final URL once on a phone (390x844) through our own Lighthouse runner and judges it (docs/1006 §41): the status and where it redirects, the page's language and main heading, whether the call to action is in the first screen (`cta_above_fold`, `null` when the page has no button we recognise), mobile LCP and CLS, the ad groups landing there, and the problems found — each one is also a finding (`GET .../findings`, `why` `lp_*`) carrying its concrete fix. `checked: false` means the page could not be read that day (never \"ok\"). Read from the state the audit stored — never a network call in the request.","tags":["ads"],"responses":{"200":{"description":"The pages.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"checked_at":{"type":"string","format":"date-time","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsLandingPage"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/findings/{finding_id}/{action}":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"finding_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"action","in":"path","required":true,"schema":{"type":"string","enum":["apply","dismiss"]}}],"post":{"operationId":"actOnAdsFinding","summary":"The one click on a finding — apply it, or dismiss it (FINDALL1, za-211).","description":"Gated on `ads.manage`; audit action `ads.finding_apply` / `ads.finding_dismiss`. `apply` on a suggestion (`suggested: true`) approves it and starts the account's audit, which makes exactly that change through the account's own guards (kill switches, good standing, the spend ceilings, the tracking hold) with its Undo; on a budget-limited campaign with a campaign that can give (`can_apply`), it proposes the move — the giving campaign's budget down and this one's up by the same amount, in ONE request — and approves it in one step (the apply workflow sends it; 30-day Undo); on the off-intent negative rule's approval item (`why: rule_approval`, za-219) it approves the rule, and from the audit it starts every search sharing no word with the account's keywords that spent without converting is blocked as an exact negative (the first list waits for this click). A dead campaign (`why: suggest_dead_campaign`, za-218) is a suggestion: apply pauses it with its Undo. Off-intent searches past the 24 h SLA (`why: off_intent_sla`, za-325; `figures.terms_count`, `cost_micros`, `days`, `examples`): apply blocks every search it lists as an exact negative on the audit it starts, each through its own guards with its Undo. Paused-ad clutter (`why: suggest_paused_clutter`, za-170): an ad group's paused ads its live ads replaced, paused 7+ days; apply deletes them through the approve-first gate, each with its snapshot and 30-day Rebuild. BUDGETMV1 (za-186): a budget move's body may name the option from `figures.options` — `move` (the default: total unchanged) or `increase` (this campaign alone raised, only when the ceiling has room; the spend ceilings are checked again when it is sent). `dismiss` closes it; a dismissed finding stays dismissed. `422 notPending` when it is no longer open, `422 badAction` when there is nothing to apply (or no such option).","tags":["ads"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsFindingApplyOption"}}}},"responses":{"200":{"description":"Dismissed.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsFinding"}}}}}},"202":{"description":"Applied — approved; the audit or the apply workflow makes the change.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsFinding"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/quality-score":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsQualityScore","summary":"The Quality Score fixer — weak keywords, their weakest part and its fix (QSFIX, za-N11).","description":"Gated on `ads.view`. Each day the connection's audit reads Google's Quality Score and its three parts for every enabled keyword (`ad_group_criterion.quality_info`: `creative_quality_score` = `ad_relevance`, `search_predicted_ctr` = `expected_ctr`, `post_click_quality_score` = `landing_page`; each `BELOW_AVERAGE` / `AVERAGE` / `ABOVE_AVERAGE`, empty while Google has too little data). A keyword at or below the account's own `max_score` with at least `min_impressions` in 30 days is diagnosed: its WEAKEST part (`weakest`) and the fix for it (`fix.kind`): `move_keyword` (to the ad group whose name carries it) or `ad_with_keyword` (a new ad whose headline says it, passed through the ad-quality gate first; `fix.status` `gateRefused` with `reasons` when the gate would refuse it) or `split_group` (advice) for ad relevance; `rsa_assets` (a new ad with more distinct lines from the AI writer) for expected CTR; `page_speed` (the page's mobile LCP/CLS and biggest opportunities, `report`; on a site this organisation hosts with us, `report.hosting.fixes` — page cache, object cache, CDN — each with the dashboard page that switches it) for the landing page. Every Google Ads write is a change waiting for approval (`change`), never sent by itself; nothing changes a site. Read from what the audit stored — never a network call in the request.","tags":["ads"],"responses":{"200":{"description":"The settings and the diagnosed keywords.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsQsFixer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateAdsQualityScoreSettings","summary":"The account's own Quality Score fixer values (QSFIX, za-N11).","description":"Gated on `ads.manage`; audit action `ads.qs_fix_settings`. Each value is the customer's to set; `null` puts it back to the recommended value. `422 badQsFixSetting` (naming the field) outside the bounds shown on `GET`, for a value that is not a whole number, or for an unknown field.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsQualityScoreSettingsUpdate"}}}},"responses":{"200":{"description":"Saved; the same body as `GET`.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsQsFixer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/autopilot":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsAutopilot","summary":"What the autopilot does on this account.","description":"Gated on `ads.view` (za-14, docs/1006 §53). Each step the house autopilot runs on a customer's account (add a wasteful search term as a negative, pause a keyword that spent its maturity clicks with no conversion, add a converting search term as a phrase keyword) with the account's mode for it: `auto` (sent, with a 30-day Undo), `approve` (kept as a change for a person to approve) or `off` (never tried). Every write still passes the account's guards (good standing, spend ceilings, hold until a sale, ROAS target). `last_run` is what the latest finished audit did, `null` before the first one. Read from stored rows — never a network call in the request.","tags":["ads"],"responses":{"200":{"description":"The steps with their modes and the latest audit's counts.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsAutopilot"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/insights":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsInsights","summary":"Spend pacing, tracking still firing, missed clicks and the signal ladder.","description":"Gated on `ads.view`. The latest readings the connection's daily audit stored (BUILDA, docs/1006 §30; the signal ladder BUILDL2, §34 — za-152 / za-161) — never a network call in the request. Each reading is `null` until the first audit after the account was connected (a Google account only).","tags":["ads"],"responses":{"200":{"description":"The three readings.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsInsights"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/pmax":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsPmax","summary":"The account's Performance Max reading (za-185).","description":"Gated on `ads.view`. The reading the connection's daily audit stored (docs/1006 §78) — never a network call in the request: each enabled Performance Max campaign with its asset groups and Google's ad strength, each asset rated `best` / `good` / `low` / `learning` against the other assets of its kind (Google API v25 has no performance label), Google's search categories and the real searches, cost and conversions per channel, whether a brand list is excluded, and its negative keywords against Google's limit of 10,000. `reading` is `null` until the first audit after the account was connected (a Google account only). Changes are approve-first findings (`GET /v1/ads/connections/{id}/findings`).","tags":["ads"],"responses":{"200":{"description":"The Performance Max reading.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["connection_id","currency","reading"],"properties":{"connection_id":{"type":"string","format":"uuid"},"currency":{"type":"string"},"reading":{"$ref":"#/components/schemas/AdsPmaxReading"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/crm-sources":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsCrmSources","summary":"The account's CRM, sheet and call-log sources and their stage mapping (za-160).","description":"Gated on `ads.view` (za-160, docs/1006 §101). Every source feeding this ad account's offline conversions: HubSpot, Pipedrive, Salesforce, a link-shared Google Sheet, or CSV uploads of leads or calls. A credential is never returned (`has_secret`). Read from stored rows only.","tags":["ads"],"responses":{"200":{"description":"The sources and the choices the mapping UI offers.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsCrmSources"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/crm-sources/{vendor}":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"vendor","in":"path","required":true,"schema":{"type":"string","enum":["hubspot","pipedrive","salesforce","sheet","csv","calls_csv","telnyx"]}}],"put":{"operationId":"putAdsCrmSource","summary":"Connect or update one CRM / sheet / call-log source and its stage mapping (za-160).","description":"Gated on `ads.manage`; audit action `ads.crm_source_saved` (the credential is never in its metadata). A credential (`token` for HubSpot / Pipedrive, `client_id` + `client_secret` of the customer's own Salesforce connected app) is proven with one read, then kept in Vault only; omit it to change only the mapping. Each `stage_map` action and the `call_action` must be one of THIS account's conversion actions. A vendor refusal answers 422 with `failure` (CLAUDE.md §2.57) and nothing is stored. A pulled source starts a sync.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsCrmSourceIn"}}}},"responses":{"200":{"description":"The stored source.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsCrmSource"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"deleteAdsCrmSource","summary":"Remove one CRM / sheet / call-log source (za-160).","description":"Gated on `ads.manage`; audit action `ads.crm_source_removed`. Forgets the credential in Vault and stops the sync; outcomes already made stay (the network may already hold them).","tags":["ads"],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/crm-sources/{vendor}/stages":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"vendor","in":"path","required":true,"schema":{"type":"string","enum":["hubspot","pipedrive","salesforce","sheet","csv","calls_csv","telnyx"]}}],"get":{"operationId":"listAdsCrmStages","summary":"The stages the connected CRM holds, to map to conversion actions (za-160).","description":"Gated on `ads.view`. One read of the customer's own CRM (lifecycle stages, deal stages, lead statuses, a sheet's stage column); an upload source answers an empty list. A vendor refusal answers 422 with `failure`.","tags":["ads"],"responses":{"200":{"description":"The stages.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsCrmStages"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/crm-sources/{vendor}/sync":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"vendor","in":"path","required":true,"schema":{"type":"string","enum":["hubspot","pipedrive","salesforce","sheet"]}}],"post":{"operationId":"syncAdsCrmSource","summary":"Read the CRM's changes now, instead of waiting for the daily audit (za-160).","description":"Gated on `ads.manage`; audit action `ads.crm_source_sync`. Starts the durable Temporal sync (it resumes from the stored cursor, no cap on records) and answers at once; a second press in the same minute joins the running sync. 422 `uploadOnly` for a CSV source.","tags":["ads"],"responses":{"202":{"description":"The sync was started.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["started"],"properties":{"started":{"type":"boolean"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/crm-sources/{vendor}/upload":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"vendor","in":"path","required":true,"schema":{"type":"string","enum":["csv","calls_csv"]}}],"post":{"operationId":"uploadAdsCrmCsv","summary":"Send one CSV file of leads or of calls (za-160).","description":"Gated on `ads.manage`; audit action `ads.crm_upload`. At most 5,000 rows / 5 MB per file (send any number of files). A lead at a mapped stage, and a call at least `min_call_seconds` long, become one outcome each, only with consent; the same file twice stores nothing twice. Stored outcomes are uploaded to the network by the outcome push.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content"],"properties":{"content":{"type":"string","description":"The CSV text, header row first."}}}}}},"responses":{"200":{"description":"What the file held and what was stored.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsCrmSyncResult"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/call-numbers":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsCallNumbers","summary":"The ad account's Zinn® tracking numbers and their prices (za-160).","description":"Gated on `ads.view`. Numbers held, ordering or releasing (released and failed ones are left out), the per-minute price of a forwarded call, the account's number cap and the `pool_key` the customer's site snippet sends (not a secret). The call-tracking rules (60-second minimum, conversion action, consent) are the CRM source `telnyx`.","tags":["ads"],"responses":{"200":{"description":"The numbers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsCallNumberList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"orderAdsCallNumber","summary":"Buy one tracking number that forwards to the customer's own number (za-160).","description":"Gated on `ads.manage`; audit action `ads.call_number_ordered` (no phone number in its metadata). The price is the voice vendor's own answer for that number, re-read now, times the platform margin; the first charge (the vendor's upfront fee plus the first month, both taken by the vendor at purchase) is taken from the org's prepaid Zinn® credit BEFORE the order and returned if the vendor refuses it. Refused (422) when call tracking is not open (`callNotOpen`), the CRM source `telnyx` is not set up (`callNoSource`), the forward-to number is not a United States number or is one of our own tracking numbers (a call loop, `callForwardToNotOffered`), the account holds its cap (`callTooMany`), the account is not in good standing (`callAccountOnHold`), the credit is short (`callNoCredit`), the only credit left is AI Hosting plan-included credit, which pays for AI Hosting only (`callPlanCreditsOnly`, 402), the number was taken (`callNumberGone`) or its price is no longer the `first_month_usd_micros` the customer was shown (`callPriceChanged`, nothing charged). An order the vendor has not finished yet leaves the number `ordering` and starts the account's number sweep at once (retried until it completes); a vendor that does not answer the order leaves it `ordering` too: it is found by its reference, or refunded.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone_number","forward_to"],"properties":{"phone_number":{"type":"string","maxLength":20,"description":"E.164","from the search.":null},"forward_to":{"type":"string","maxLength":20,"description":"The customer's own US number","E.164.":null},"name":{"type":"string","maxLength":80},"first_month_usd_micros":{"type":"integer","format":"int64","minimum":0,"description":"The first-month price the customer was shown by `searchAdsCallNumbers` (USD micros). A different price now is refused (`callPriceChanged`), never charged."}}}}}},"responses":{"201":{"description":"The number (status `active`, or `ordering` until the vendor completes it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsCallNumber"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/call-numbers/available":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"country","in":"query","required":false,"schema":{"type":"string","default":"US","minLength":2,"maxLength":2}},{"name":"area_code","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{3}$"}}],"get":{"operationId":"searchAdsCallNumbers","summary":"Local numbers the customer could buy, each at its measured price (za-160).","description":"Gated on `ads.view`. A read at the voice vendor (costs nothing): up to ten local voice numbers, each with the customer's first-month and monthly price in USD micros (the vendor's own `cost_information` plus the platform margin). Only countries whose call rates were measured are offered (`callCountryNotOffered`).","tags":["ads"],"responses":{"200":{"description":"The offers.","content":{"application/json":{"schema":{"type":"object","required":["numbers"],"properties":{"numbers":{"type":"array","items":{"$ref":"#/components/schemas/AdsCallNumberOffer"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/call-numbers/{number_id}":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"number_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"operationId":"updateAdsCallNumber","summary":"Change where a tracking number forwards, or its name (za-160).","description":"Gated on `ads.manage`; audit action `ads.call_number_updated`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"forward_to":{"type":"string","maxLength":20,"description":"The US phone number (E.164) calls are forwarded to; `\"\"` switches forwarding off — the number is kept and every call to it is refused unanswered (no minute is billed). One of our own tracking numbers is refused (`callForwardToNotOffered`)."},"name":{"type":"string","maxLength":80}}}}}},"responses":{"200":{"description":"The number.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsCallNumber"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"releaseAdsCallNumber","summary":"Release a tracking number — it stops costing anything (za-160).","description":"Gated on `ads.manage`; audit action `ads.call_number_released`. The number is marked `releasing` and given back to the voice vendor by a Temporal workflow; no further month is charged.","tags":["ads"],"responses":{"202":{"description":"Release started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsCallNumber"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/ads/call-numbers/{pool_key}":{"parameters":[{"name":"pool_key","in":"path","required":true,"schema":{"type":"string","maxLength":40}},{"name":"gclid","in":"query","required":false,"schema":{"type":"string","maxLength":200}},{"name":"msclkid","in":"query","required":false,"schema":{"type":"string","maxLength":200}},{"name":"consent","in":"query","required":false,"schema":{"type":"string","maxLength":20}}],"get":{"operationId":"getAdsCallPoolNumber","tags":["ads"],"security":[],"summary":"The tracking number a site visitor from an ad is shown (dynamic number insertion).","description":"**Anonymous and cross-origin by design** (`Access-Control-Allow-Origin: *`): the customer's site snippet calls it with the visit's click id, and it answers one of the account's pool numbers (the one given out longest ago), remembered with that click id for the session window so a call to it is attributed. No click id, an unknown key or no active number → `204` (the site keeps its own number). No cookie is read.","responses":{"200":{"description":"The number to show.","content":{"application/json":{"schema":{"type":"object","required":["phone_number"],"properties":{"phone_number":{"type":"string"}}}}}},"204":{"description":"Nothing to swap."},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/webhooks/ads/telnyx-voice":{"post":{"operationId":"receiveAdsTelnyxVoice","tags":["ads"],"security":[],"summary":"Call events for Zinn® tracking numbers from our voice vendor (za-160).","description":"**Unauthenticated by design**: the vendor's Ed25519 signature over `timestamp|raw body` (`telnyx-signature-ed25519`, `telnyx-timestamp`), checked with the same public key as the Campaigns SMS webhook, is the authentication — `401` when it does not verify or is outside its time window, `503` while no key is configured (never accepted unverified). `call.initiated` to a tracking number is answered (or refused when the account cannot pay for it), `call.answered` dials the customer's own number and bridges the two legs, `call.hangup` ends the other leg and prices the call; a call of at least the source's `min_call_seconds` becomes an offline conversion. An event id already handled is a no-op (`duplicate`); a vendor command that fails answers `503` so the event is re-delivered.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Accepted.","content":{"application/json":{"schema":{"type":"object","required":["ok","handled"],"properties":{"ok":{"type":"boolean"},"handled":{"type":"string"},"refusal":{"type":"string"},"talk_seconds":{"type":"integer"},"stored":{"type":"integer"}}}}}},"400":{"description":"Not JSON."},"401":{"description":"Signature missing, wrong or stale."},"503":{"description":"No signing key configured, or the vendor did not take a command (re-deliver)."}}}},"/v1/ads/connections/{connection_id}/video":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsVideo","summary":"The account's Video and Demand Gen reading and its YouTube channel (za-201).","description":"Gated on `ads.view`. The reading the connection's daily audit stored (docs/1006 §80) — never a network call in the request: each enabled Video and Demand Gen campaign with the people it reached and how often each saw an ad, its frequency caps, the placements its money went to, click-through beside view-through conversions; what all video campaigns claim against the sales the customer's own source recorded (`real_sales`, `null` with no source); and the YouTube link state of the videos the ads use. `reading` is `null` until the first audit (a Google account only). Changes are approve-first findings (`GET /v1/ads/connections/{id}/findings`).","tags":["ads"],"responses":{"200":{"description":"The Video and Demand Gen reading.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsVideoResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"putAdsVideo","summary":"Save (or clear) the customer's own YouTube channel on a Google connection (za-201).","description":"Gated on `ads.manage`; audit action `ads.youtube_channel_set` / `ads.youtube_channel_cleared`. `youtube_channel_id` is the channel ID from YouTube Studio (`UC` + 22 characters); `\"\"` clears it. Nothing changes at Google: the next daily audit suggests linking each video of this channel the ads use (Google Ads DataLinkService), each one a person's approval with an Undo, and the channel owner then approves the link in YouTube Studio. A saved channel also unlocks the `reach` objective on Video and Demand Gen campaigns. `422 youtubeChannelInvalid` for any other value; `422 platformNotSupported` on a connection that is not Google.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["youtube_channel_id"],"properties":{"youtube_channel_id":{"type":"string","maxLength":24,"pattern":"^(UC[A-Za-z0-9_-]{22})?$"}}}}}},"responses":{"200":{"description":"The connection's Video reading with the channel saved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsVideoResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/product-analytics":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsProductAnalytics","summary":"The customer's product analytics source and the lead quality it measures (za-190).","description":"Gated on `ads.view` (za-190, docs/1006 §71). The connected product analytics project (PostHog, `us` or `eu` cloud) whose events tell the ads truth which clicks became sign-ups, activations, day-7 and day-30 retained people and upgrades. `source` is `null` until one is connected; the key is never returned (`has_key`). `quality` is per keyword and country, read from stored rows — never a network call in the request.","tags":["ads"],"responses":{"200":{"description":"The source (or `null`), the choices and the measured lead quality.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsProductAnalytics"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"putAdsProductAnalytics","summary":"Connect or update the product analytics project (za-190).","description":"Gated on `ads.manage`; audit action `ads.product_analytics_connected`. The project's personal API key is checked against the vendor once, then kept in Vault only. At least one of the stage event names is required. A vendor refusal answers 422 with `failure` (which kind of failure, whose key, where to fix it — CLAUDE.md §2.57); nothing is stored.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsProductAnalyticsIn"}}}},"responses":{"200":{"description":"The stored source.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsProductSource"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"deleteAdsProductAnalytics","summary":"Disconnect the product analytics project (za-190).","description":"Gated on `ads.manage`; audit action `ads.product_analytics_disconnected`. Forgets the key in Vault and stops the sync; outcomes already measured stay.","tags":["ads"],"responses":{"204":{"description":"Disconnected."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/product-analytics/sync":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"syncAdsProductAnalytics","summary":"Read the product analytics now, instead of waiting for the daily audit (za-190).","description":"Gated on `ads.manage`; audit action `ads.product_analytics_sync`. Starts the durable Temporal sync (it resumes from the stored cursor) and answers at once; a second press in the same minute joins the running sync. 404 when no source is connected; 422 `disconnected` on a disconnected account; 422 `refusal.adsconnect.syncNotStarted` when the sync could not be started (try again in a minute; FIX-REFUSED).","tags":["ads"],"responses":{"202":{"description":"The sync was started.","content":{"application/json":{"schema":{"type":"object","required":["started"],"properties":{"started":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/budget-flags/{flag_id}/raise":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"flag_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"raiseAdsBudgetFlag","summary":"The one-click raise of a budget-limited campaign (za-142).","description":"Gated on `ads.manage`; audit action `ads.budget_flag_raise`. Approves the waiting suggestion, or proposes the +25% raise and approves it in one step; the apply workflow sends it through the same gate as every write (kill switches, the spend ceiling, its 30-day Undo). `422 notPending` when the campaign was already raised or is no longer held back.","tags":["ads"],"responses":{"202":{"description":"Approved; the apply workflow sends it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsChange"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/scorecard":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsScorecard","summary":"Did each automatic change do what it said? The 14-day scorecard (za-214).","description":"Gated on `ads.view`. Every automatic change of the last 30 days, newest first (at most 500), read from the rows the daily scorecard stored (docs/1006 §42) — never a network call in the request. Each change states its expected effect when it is made (`expected`: the metric, the direction, the size it should move by, the harm that counts as worse, the 14-day window); 14 days on the scorecard measures the 14 days after against the 14 days before on its campaign — first-party outcomes where we have them (`basis: first_party`), else the ad network's own conversions (`basis: google`). Outcomes are thousandths, spend is micros of `currency`, `change_bp` is the move in the stated direction in basis points. `verdict`: `pending` (not due yet), `better`, `same`, `worse`, `no_data` (too little to say: never undone on noise), `gone` (undone before it was judged). A worse change's `undo_state`: `proposed` (one click on the findings list: `suggestion_id`), `undone` (automatic changes on for its kind), `owner_lock`, `freeze` (the campaign is learning a new bid strategy), `standing` (the organisation is not in good standing), `not_undoable`, `failed`, `expired`. A customer's change keeps its own 30-day Undo (`change_id`).","tags":["ads"],"responses":{"200":{"description":"The scored changes and their totals.","content":{"application/json":{"schema":{"type":"object","required":["data","totals","window_days"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsScoreRow"}},"totals":{"type":"object","required":["pending","better","same","worse","no_data","gone","undone","proposed"],"properties":{"pending":{"type":"integer"},"better":{"type":"integer"},"same":{"type":"integer"},"worse":{"type":"integer"},"no_data":{"type":"integer"},"gone":{"type":"integer"},"undone":{"type":"integer"},"proposed":{"type":"integer"}}},"window_days":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/competitor-groups":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsCompetitorGroups","summary":"Competitor ad groups in every language - thresholds and the last run (za-15, za-71).","description":"za-71 (docs/1006 §89): a rival the house table says must not be built (a free host, or a local brand searched off its market) is BLOCKED with EXACT campaign negatives instead, each verdict behind its own customer switch (`block_free_hosts`, `block_off_market`, Recommended on); in the customer's Automatic mode builds and blocks are sent through the change gate (kill switch, good standing) with an Undo, otherwise queued for approval. Gated on `ads.view`. On the caller's own connection. The daily audit (Temporal) reads the account's own search terms and proposes, for approval, one ad group `<Rival> alternative` per rival per language market whose searches reach the thresholds, with PHRASE keywords and one responsive search ad copied from an approved ad in that campaign (or the English ad translated in one batched call), with no competitor name in the ad text (docs/1006 §81). Proposals are ordinary approve-first changes (`listAdsChanges`). `enabled` is the competitor switch AND a plan carrying `ads_competitor_groups`. Read from stored rows, never a network call in the request.","tags":["ads"],"responses":{"200":{"description":"The thresholds, each with its Recommended value, and the last run.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsCompetitorGroupsEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateAdsCompetitorGroups","summary":"Edit a competitor ad group threshold; null puts it back on Recommended (audited).","description":"Gated on `ads.manage`. Audit action `ads.competitor_groups_update`. Each field is a whole number inside its bounds (see `settings.<field>.min/max` in the GET), or `null` for the Recommended value. Any unknown field or out-of-range value refuses the whole request with `competitorGroupsInvalid` (nothing is half-applied).","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsCompetitorGroupsPatch"}}}},"responses":{"200":{"description":"The settings after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsCompetitorGroupsEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/prospecting":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsProspecting","summary":"The Prospecting template's choices - business types, starter negatives, budget (za-158).","description":"Gated on `ads.view`. On the caller's own connection. The intents (category, problem, paid-competitor alternative, brand), the match types every keyword starts on (EXACT and PHRASE), each business type with its starter negatives and whether it is paid by default, the Recommended daily budget (five whole units of the account currency, also the floor) and how many prospecting templates wait for approval (docs/1006 §93). Read from stored rows, never a network call in the request.","tags":["ads"],"responses":{"200":{"description":"The template's choices.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsProspectingInfoEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"buildAdsProspecting","summary":"Start building a Prospecting campaign preview from intent groups (za-158).","description":"Gated on `ads.manage`. Validates the template and its gates from stored rows, then STARTS the preview workflow and answers 202 with its `preview_id`; the account read (collision replay), the ONE batched translation and the ONE batched AI-writer request run in that workflow, never in the request. Poll `getAdsProspectingPreview`. The same input the same day is the same preview (a running or built one is not started again). The preview is one new Search campaign: a `category` group, a `problem` group, one `<Rival> alternative` group per PAID competitor (a free host is skipped, `notPaidCompetitor`; all are skipped without the competitor switch and plan, `competitorsOff`) and a `brand` group, every keyword on EXACT and PHRASE. The business type's starter negatives, plus the free-seeker class when `paid` is true; every negative passes the collision replay over the account's keywords and searches and the template's own keywords, and one that would block any of them is `dropped` with its reasons. Each group's ad names its topic and must reach GOOD (`waiting`, `adBelowGood` otherwise); the whole request passes the ad-quality gate (`status: refused`, `refused`). Refusals: `prospectingInvalid` (with the field), `killed`, `notInGoodStanding`, `needsReconnect`, `prospectingUnavailable`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsProspectingRequest"}}}},"responses":{"202":{"description":"The preview is being built; poll it by `preview_id`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsProspectingPreviewEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/prospecting/{preview_id}":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"preview_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"operationId":"getAdsProspectingPreview","summary":"One Prospecting preview - building, ready with the plan, failed or expired (za-158).","description":"Gated on `ads.view`. On the caller's own connection. `building` while the workflow runs, `ready` with the plan, `failed` with the refusal (`error.code`, as for `buildAdsProspecting`), `expired` once the run is no longer kept or finished more than a day ago (its account read is stale: build it again).","tags":["ads"],"responses":{"200":{"description":"The preview.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsProspectingPreviewEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/prospecting/{preview_id}/propose":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"preview_id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"operationId":"proposeAdsProspecting","summary":"Queue a ready Prospecting preview as ONE approve-first change (za-158).","description":"Gated on `ads.manage`. Fast: nothing is rebuilt. The gates (kill switch, good standing, campaign changes on) and the ad-quality gate run again on the preview's stored request, then it is queued as ONE pending change (`listAdsChanges`; audit action `ads.prospecting_propose`); proposing the same preview twice is the same pending change, and once that change is approved or applied it is that change again (never a second campaign). Nothing is sent to Google here: the metered gate runs when a person approves it. Refusals: `prospectingInvalid` (field `preview_id`: not ready), `killed`, `notInGoodStanding`, `needsReconnect`, `prospectingUnavailable`.","tags":["ads"],"responses":{"200":{"description":"The plan with `status` `proposed` and its `change_id`, or `refused`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsProspectingPreviewEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/copy-winners":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsCopyWinners","summary":"Copy winners across your own accounts and countries - settings and the last run (za-N5).","description":"Gated on `ads.view`. On the caller's own connection. The daily audit (Temporal) finds the responsive search ads that win in a campaign on FIRST-PARTY conversions only (a one-sided two-proportion test against the campaign's other ads at `confidence_pct`, with at least `min_clicks` clicks and `min_conversions` conversions over `lookback_days`) and offers each winner - its ad and keyword set - to the same org's other campaigns, countries and connected accounts on the same website, translated in one batched call where the language differs and checked by the ad-quality gate (docs/1006 §91). Copies are ordinary changes on the TARGET connection (`listAdsChanges`): approve-first in mode `suggest`; approved at once with Undo in mode `auto` when that account's `campaigns` class is Automatic. `pending` counts this account's copies waiting anywhere in the org. Read from stored rows, never a network call in the request.","tags":["ads"],"responses":{"200":{"description":"The switch, mode, thresholds (each with its Recommended value) and the last run.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsCopyWinnersEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateAdsCopyWinners","summary":"Edit copy winners - switch, mode, thresholds; null puts a threshold back on Recommended (audited).","description":"Gated on `ads.manage`. Audit action `ads.copy_winners_update`. `on` is a boolean; `mode` is `suggest` or `auto`; each threshold is a whole number inside its bounds (see `settings.<field>.min/max` in the GET), or `null` for the Recommended value. Any unknown field or invalid value refuses the whole request with `copyWinnersInvalid` (nothing is half-applied).","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsCopyWinnersPatch"}}}},"responses":{"200":{"description":"The settings after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsCopyWinnersEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/allowed-terms":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsAllowedTerms","summary":"Competitor names allowed in one ad group each (za-237).","description":"Gated on `ads.view`. On the caller's own connection. Every ad-copy gate refuses another company's name in ad text (`competitorInText`) unless the ad group carries an allowance for that name (docs/1006 §53); each allowance names ONE ad group and stays there. Read from the stored rows — never a network call in the request.","tags":["ads"],"responses":{"200":{"description":"The allowances in force.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsAllowedTermList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createAdsAllowedTerm","summary":"Allow a competitor's name in ONE ad group's ad text (audited).","description":"Gated on `ads.manage`. Audit action `ads.allowed_term_add`. `ad_group_id` is the ad group's id or resource name (as the ads list returns it); `term` the company name (up to 60 characters). The name stays refused in every other ad group. Allowing a name already allowed there changes nothing (200); a new or re-allowed one answers 201. Refusal codes: `allowNoAdGroup`, `allowTermEmpty`, `allowTermTooLong`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsAllowedTermCreate"}}}},"responses":{"200":{"description":"Already allowed in that group; nothing changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsAllowedTermEnvelope"}}}},"201":{"description":"Allowed in that group.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsAllowedTermEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/allowed-terms/{allowance_id}":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"allowance_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"delete":{"operationId":"deleteAdsAllowedTerm","summary":"Withdraw an allowance; the name is refused in that group again (audited).","description":"Gated on `ads.manage`. Audit action `ads.allowed_term_remove`. The gates refuse the name in that group at their next call. Undo is allowing it again (POST). An allowance of another account is 404 (`noSuchAllowance`).","tags":["ads"],"responses":{"200":{"description":"The withdrawn allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsAllowedTermEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/measurement-health":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsMeasurementHealth","summary":"Optimisation score, conversion goals, offline uploads and PMax automation (za-253).","description":"Gated on `ads.view`. What the daily audit's measurement-health step stored for the caller's own connection (docs/1006 §ADSOPT), never a network call in the request: Google's optimisation score in basis points (`score_bp`, 9307 = 93.07%) with one point per day (`trend`, last 30 days), each enabled campaign's score, the conversion goals that count nothing because their category has no enabled primary action (`goals.missing`: a campaign with nothing left to bid for, a person must choose one; `goals.suggested`: one click to take a goal out of bidding; `goals.switched_off`: done by the autopilot, with Undo on the findings list), the offline-conversion uploads Google reports failing in the last two days (`uploads`, with Google's error code), and each Performance Max campaign's asset-automation switches (`automation`, read only). `checked_at` is null before the first audit.","tags":["ads"],"responses":{"200":{"description":"The measurement health of this connection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsMeasurementHealth"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/account-checks":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsAccountChecks","summary":"The house checks on this account, in figures (za-82, za-83, za-88, za-89).","description":"Gated on `ads.view`. What the daily audit's house checks concluded on the caller's own connection (docs/1006 §55), read from the rows it stored — never a network call in the request. `maturity` (za-82): the account's conversion rate as a Bayesian estimate (a prior of `prior_clicks` clicks at `prior_rate`, updated with the account's own ad-group clicks and conversions over `window_days`) and `clicks_needed`, the clicks a search term or keyword needs before \"no conversion\" is judged. `shared_budgets` (za-83): campaigns moved off a shared budget in the last `window_days` days (`moved`), shared budgets waiting for one click with automatic changes off (`waiting`, each with its `suggestion_id` on the findings list), and campaigns Google refused to move (`refused`). `recommendations` (za-88): Google's recommendations as our rules reviewed them — `ignored` (dismissed at Google), `part` (our own version is written instead), `owner` (the customer's to decide), `accepted`. `self_audit` (za-89): what the automatic changes of the last 28 days did — the audit's own negatives and what those searches cost before and since, each keyword it added and its figures since, and the changes the collision check refused this week. Money is micros of `currency`; conversions are thousandths.","tags":["ads"],"responses":{"200":{"description":"The checks for this connection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsAccountChecks"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/google-changes":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsGoogleChanges","summary":"Changes Google made in this account by itself, judged against the customer's rules (za-194).","description":"Gated on `ads.view`. The last 30 days of changes the account's change history says GOOGLE made (docs/1006 §Google's own changes): `actor` is `auto_apply` (an auto-applied recommendation), `recommendation` (applied from Google's recommendations or its assistant) or `google` (a Google tool). Read once a day by the audit and stored — never a network call in the request. Each carries the `action_class` our own modes put that kind of write in and a `verdict`: `breaks_rule` (the customer set that class to off), `needs_approval` (Google skipped their approve-first), `risky` (within an auto class but a risky kind — see `reasons`: `budget_raised`, `broad_match_added`, `bidding_changed`, `ad_written`, `removed`) or `within_rules`. `undoable` says whether `…/undo` can put it back; `undo` is the approve-first change that does, once asked. `auto_apply` lists the account's auto-apply types as last read, `risky` ones first. A connection on any other network is not found here (these are Google's own changes only).","tags":["ads"],"responses":{"200":{"description":"Google's own changes on this connection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsGoogleChanges"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/google-changes/{change_id}/undo":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"change_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"undoAdsGoogleChange","summary":"Put back a change Google made by itself (za-194).","description":"Gated on `ads.manage`. Builds the inverse of the Google change (the old values of the changed fields; a removal of what Google created) as an approve-first change approved by the caller and sent by the queue's own apply workflow — kill switches, ceilings and our own Undo still apply. Twice is once: a second call returns the same change. Refusals `googleNoUndo` (a removal, or no such change on this connection) and the kill-switch codes. Audited (`ads.google_change_undo`).","tags":["ads"],"responses":{"202":{"description":"The Undo is queued to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsChange"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/auto-apply":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"setAdsAutoApply","summary":"Switch one of Google's auto-apply types off, or back on (za-194).","description":"Gated on `ads.manage`. Sets the account's recommendation subscription for `type` to `PAUSED` (`enabled: false`) or `ENABLED`, as an approve-first change approved by the caller and sent by the queue's apply workflow. `type` must be one the account lists in `google-changes` `auto_apply`. Refusal `unknownType` and the kill-switch codes. Audited (`ads.auto_apply_set`).","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["type","enabled"],"properties":{"type":{"type":"string","pattern":"^[A-Z][A-Z0-9_]{1,63}$"},"enabled":{"type":"boolean"}}}}}},"responses":{"202":{"description":"The switch is queued to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsChange"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/x/campaigns":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsXCampaigns","summary":"An X Ads account's campaigns with their daily and total budgets and 7-day spend (za-43).","description":"Gated on `ads.view`. Read from X now (docs/1006 §35 \"Budgets\"): one row per campaign with its status, currency, daily and total budget (micros of the account currency, `null` when the campaign has none) and its spend over the last `days` days. `sandbox` is true for an X sandbox account. `422 xBudgetsXOnly` for a connection that is not X, `422 xReadFailed` when X did not answer (try again), `422 needsReconnect` when X refused the token. An `xReadFailed` refusal carries `error.failure` (§2.57 `VendorFailure`): `provider_outage` with X's status board for a 5xx, a rate limit or no answer, `credential_problem` with X's billing door for a 402, `our_fault` for any other 4xx or our own deadline. `needsReconnect` (401/403, or X's token codes on a 400) carries none: its remedy is \"connect it again\", which the refusal says.","tags":["ads"],"responses":{"200":{"description":"The account's campaigns.","content":{"application/json":{"schema":{"type":"object","required":["connection_id","sandbox","days","data"],"properties":{"connection_id":{"type":"string","format":"uuid"},"sandbox":{"type":"boolean"},"days":{"type":"integer"},"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsXCampaign"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/x/campaigns/{campaign_id}/budget":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9]{1,24}$"}}],"post":{"operationId":"setAdsXCampaignBudget","summary":"Change an X campaign's daily budget — the click is the approval (za-43).","description":"Gated on `ads.manage`; audit action `ads.x_budget_set`. Proposed as a `budgets` change and approved in one step, then sent by the apply workflow through the same gate as every write (kill switches, good standing, the connection's spend ceilings weighed against X's active daily budgets — a raise past a ceiling is refused, a cut never is), with a 30-day Undo that puts the previous daily budget back. Live (non-sandbox) X accounts are sent only once live X writes are switched on. Refusals (`422`): `xBudgetsXOnly`, `xBadBudget`, `xNoSuchCampaign`, `xNoDailyBudget` (a campaign with no daily budget), `xBudgetUnchanged`, `xBudgetOverTotal` (a daily budget above the campaign's total budget), `xReadFailed`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["daily_budget_micros"],"properties":{"daily_budget_micros":{"type":"integer","format":"int64","minimum":1,"maximum":1000000000000,"description":"The new daily budget in micros of the account currency (1 unit = 1,000,000)."}}}}}},"responses":{"202":{"description":"Approved; the apply workflow sends it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsChange"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/tiktok/objects":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsTiktokObjects","summary":"A TikTok advertiser's campaigns, ad groups and ads with status, budget, bid and 7-day spend (TTFULL).","description":"Gated on `ads.view`. Read from TikTok now (TTFULL, docs/1006 §TikTok writes): every campaign, ad group and ad TikTok lists (deleted ones it does not), whether each is serving, its own budget and bid (null where it has none), the audiences an ad group excludes and its spend over the last `since_days` days. `grants` is what this connection's grant may do, measured from TikTok's answers (`writes`, `audiences`, `diagnosis`; absent = not measured yet). Refusals (`422`): `noSuchConnection` (not a TikTok connection), `needsReconnect`.","tags":["ads"],"responses":{"200":{"description":"The advertiser's objects.","content":{"application/json":{"schema":{"type":"object","required":["since_days","currency","grants","campaigns","adgroups","ads"],"properties":{"since_days":{"type":"integer"},"currency":{"type":"string","description":"ISO 4217 code of the ad account."},"grants":{"type":"object","additionalProperties":{"type":"boolean"}},"campaigns":{"type":"array","items":{"type":"object","required":["id","name","campaign_id","adgroup_id","status","serving","budget_micros","bid_micros","excluded_audience_ids","spend_micros"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"campaign_id":{"type":"string"},"adgroup_id":{"type":"string"},"status":{"type":"string","description":"TikTok's operation_status (ENABLE, DISABLE)."},"serving":{"type":"boolean","description":"TikTok reports it delivering now (secondary_status *_DELIVERY_OK)."},"budget_micros":{"type":["integer","null"],"description":"Its own budget (micros of the account currency); null when it has none of its own."},"bid_micros":{"type":["integer","null"],"description":"Its own bid (ad groups); null when TikTok bids automatically."},"excluded_audience_ids":{"type":"array","items":{"type":"string"}},"spend_micros":{"type":["integer","null"],"description":"Spend over the last since_days days; null when TikTok's figure is unreadable."}}}},"adgroups":{"type":"array","items":{"type":"object","required":["id","name","campaign_id","adgroup_id","status","serving","budget_micros","bid_micros","excluded_audience_ids","spend_micros"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"campaign_id":{"type":"string"},"adgroup_id":{"type":"string"},"status":{"type":"string","description":"TikTok's operation_status (ENABLE, DISABLE)."},"serving":{"type":"boolean","description":"TikTok reports it delivering now (secondary_status *_DELIVERY_OK)."},"budget_micros":{"type":["integer","null"],"description":"Its own budget (micros of the account currency); null when it has none of its own."},"bid_micros":{"type":["integer","null"],"description":"Its own bid (ad groups); null when TikTok bids automatically."},"excluded_audience_ids":{"type":"array","items":{"type":"string"}},"spend_micros":{"type":["integer","null"],"description":"Spend over the last since_days days; null when TikTok's figure is unreadable."}}}},"ads":{"type":"array","items":{"type":"object","required":["id","name","campaign_id","adgroup_id","status","serving","budget_micros","bid_micros","excluded_audience_ids","spend_micros"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"campaign_id":{"type":"string"},"adgroup_id":{"type":"string"},"status":{"type":"string","description":"TikTok's operation_status (ENABLE, DISABLE)."},"serving":{"type":"boolean","description":"TikTok reports it delivering now (secondary_status *_DELIVERY_OK)."},"budget_micros":{"type":["integer","null"],"description":"Its own budget (micros of the account currency); null when it has none of its own."},"bid_micros":{"type":["integer","null"],"description":"Its own bid (ad groups); null when TikTok bids automatically."},"excluded_audience_ids":{"type":"array","items":{"type":"string"}},"spend_micros":{"type":["integer","null"],"description":"Spend over the last since_days days; null when TikTok's figure is unreadable."}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/tiktok/changes":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"createAdsTiktokChange","summary":"Pause, resume, re-budget, re-bid, exclude audiences or add a negative keyword on TikTok — the click is the approval (TTFULL).","description":"Gated on `ads.manage`; audit action `ads.tiktok_change`. The object is read from TikTok first (the value it holds is kept as the Undo); the change is proposed and approved in one step, then sent by the apply workflow through the same gate as every write (kill switches, good standing, spend ceilings), with a 30-day Undo that puts back exactly what TikTok held. `action`: `pause` / `enable` (`kind` campaigns, adgroups or ads), `budget` (`kind` campaigns or adgroups, `amount_micros`), `bid` (an ad group, `amount_micros`), `exclude_audiences` (an ad group, `audience_ids`; needs TikTok's Audience management permission), `negative` (a Search Ads campaign, `text`, EXACT match). Refusals (`422`): `noSuchConnection`, `netScopeNotGranted` (TikTok said this grant cannot: reconnect), `noSuchAd`, `netNotEditable` (no budget or bid of its own, or nothing would change), `paused`, `killed`, `disconnected`, `notInGoodStanding`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["action","object_id"],"properties":{"action":{"type":"string","enum":["pause","enable","budget","bid","exclude_audiences","negative"]},"kind":{"type":"string","enum":["campaigns","adgroups","ads"]},"object_id":{"type":"string","pattern":"^[0-9]{1,24}$"},"amount_micros":{"type":"integer","minimum":1,"description":"Micros of the account currency (1 unit = 1,000,000)."},"audience_ids":{"type":"array","maxItems":100,"items":{"type":"string","pattern":"^[0-9]{1,24}$"}},"text":{"type":"string","maxLength":80}}}}}},"responses":{"202":{"description":"Approved; the apply workflow sends it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsChange"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/linkedin/campaigns":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsLinkedinCampaigns","summary":"A LinkedIn ad account's campaigns with status, daily budget, bid and 7-day spend (LIFULL).","description":"Gated on `ads.view`. Read from LinkedIn now: every campaign that is not removed, with its status, whether it serves now, its daily and total budget and its bid (micros of the campaign's currency, `null` when it has none) and its spend over the last `days` days. `write` is the connection's `linkedin_write` (whether LinkedIn granted `rw_ads`, so a change can be sent). Refusals (`422`): `noSuchConnection` (not a LinkedIn connection), `needsReconnect` (LinkedIn refused the sign-in: revoked or expired), `linkedinReadFailed` (LinkedIn did not answer; the error carries the §2.57 `failure` class and, on an outage, LinkedIn's status board).","tags":["ads"],"responses":{"200":{"description":"The account's campaigns.","content":{"application/json":{"schema":{"type":"object","required":["connection_id","days","currency","write","data"],"properties":{"connection_id":{"type":"string","format":"uuid"},"days":{"type":"integer"},"currency":{"type":"string","description":"ISO 4217 code of the ad account."},"write":{"type":["object","null"],"required":["granted","needs_reconnect"],"properties":{"granted":{"type":"boolean"},"needs_reconnect":{"type":"boolean"}}},"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsLinkedinCampaign"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/linkedin/changes":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"createAdsLinkedinChange","summary":"Pause, resume, re-budget or re-bid one LinkedIn campaign — the click is the approval (LIFULL).","description":"Gated on `ads.manage`; audit action `ads.linkedin_change`. The request is built from the campaign as LinkedIn holds it now, proposed and approved in one step, then sent by the apply workflow through the same gate as every write (kill switches, good standing, the spend ceilings weighed against the serving campaigns' daily budgets), with a 30-day Undo that puts back exactly what LinkedIn held. `amount_micros` is the new daily budget (`budget`) or bid (`bid`) in micros of the campaign's currency. Refusals (`422`): `noSuchConnection`, `linkedinNeedsWriteScope` (the grant is read-only: reconnect), `noSuchAd` (no such campaign), `linkedinNotEditable` (no budget or bid of its own, a bad amount, nothing would change, or the request carries a `placements` key: placement changes are never sent, so such a request is refused whole), `killed`, `paused`, `disconnected`, `notInGoodStanding`, `needsReconnect` and `linkedinReadFailed` (reading the campaign from LinkedIn failed; nothing is kept or sent). LinkedIn's Development Tier accepts changes only on the ad accounts listed on our app; a change it refuses fails on the change itself with `linkedinWriteNotAllowed`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["action","campaign_id"],"properties":{"action":{"type":"string","enum":["pause","enable","budget","bid"]},"campaign_id":{"type":"string","pattern":"^[0-9]{1,20}$"},"amount_micros":{"type":"integer","format":"int64","minimum":1,"maximum":100000000000,"description":"The new daily budget or bid in micros of the campaign's currency (1 unit = 1,000,000)."}}}}}},"responses":{"202":{"description":"Approved; the apply workflow sends it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsChange"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/amazon/campaigns":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsAmazonCampaigns","summary":"An Amazon Ads profile's Sponsored Products campaigns with their daily budgets (AMZBIDS).","description":"Gated on `ads.view`. Read from Amazon now (`POST /sp/campaigns/list`, every page): each enabled or paused Sponsored Products campaign with its state and its daily budget (micros of the profile currency; `null` when the campaign's budget is not a daily one). `step_pct` is the most one change may move a budget or a bid. Refusals (`422`): `amazonOnly`, `amazonReadFailed` (carries `error.failure`, §2.57: `provider_outage` with Amazon Ads' status board, `our_fault` for our own 4xx), `needsReconnect`.","tags":["ads"],"responses":{"200":{"description":"The profile's campaigns.","content":{"application/json":{"schema":{"type":"object","required":["connection_id","step_pct","currency","campaigns"],"properties":{"connection_id":{"type":"string","format":"uuid"},"step_pct":{"type":"integer"},"currency":{"type":"string","description":"ISO 4217 code of the profile."},"campaigns":{"type":"array","items":{"$ref":"#/components/schemas/AdsAmazonCampaign"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/amazon/campaigns/{campaign_id}/ad-groups":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9]{1,24}$"}}],"get":{"operationId":"listAdsAmazonAdGroups","summary":"One Amazon Ads campaign's ad groups with their default bids and keyword bids (AMZBIDS).","description":"Gated on `ads.view`. Read from Amazon now (`/sp/adGroups/list` and `/sp/keywords/list`, every page): each enabled or paused ad group with its default bid, and each keyword in it with its own bid (`null`: the keyword bids its ad group's default). Refusals (`422`): `amazonOnly`, `amazonNoSuchCampaign`, `amazonReadFailed`, `needsReconnect`.","tags":["ads"],"responses":{"200":{"description":"The campaign's ad groups.","content":{"application/json":{"schema":{"type":"object","required":["connection_id","campaign_id","step_pct","ad_groups"],"properties":{"connection_id":{"type":"string","format":"uuid"},"campaign_id":{"type":"string"},"step_pct":{"type":"integer"},"ad_groups":{"type":"array","items":{"$ref":"#/components/schemas/AdsAmazonAdGroup"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/amazon/campaigns/{campaign_id}/budget":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9]{1,24}$"}}],"post":{"operationId":"setAdsAmazonCampaignBudget","summary":"Change an Amazon Ads campaign's daily budget — the click is the approval (AMZBIDS).","description":"Gated on `ads.manage`; audit action `ads.amazon_budget_set`. The campaign is read from Amazon first; the change is proposed as a `budgets` change and approved in one step, then sent ONCE by the apply workflow through the same gate as every write (kill switches, good standing, the connection's spend ceilings weighed against the profile's enabled daily budgets — a raise past a ceiling is refused, a cut never is; `ZINN_ADS_AMAZON_WRITES=off` and any house connection refuse `amazonWritesOff`). An unconfirmed send is never re-sent. The 30-day Undo puts the daily budget Amazon held back. Refusals (`422`): `amazonOnly`, `amazonBadBudget` (zero, past the cap, or finer than the currency's smallest unit), `amazonNoSuchCampaign`, `amazonNoDailyBudget`, `amazonBudgetUnchanged`, `amazonStepTooBig` (more than `step_pct` of the current budget either way), `amazonWritesOff`, `notInGoodStanding`, `amazonReadFailed`, `needsReconnect`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["daily_budget_micros"],"properties":{"daily_budget_micros":{"type":"integer","format":"int64","minimum":1,"maximum":21000000000000,"description":"The new daily budget in micros of the profile currency (1 unit = 1,000,000)."}}}}}},"responses":{"202":{"description":"Approved; the apply workflow sends it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsChange"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/amazon/campaigns/{campaign_id}/ad-groups/{ad_group_id}/bid":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9]{1,24}$"}},{"name":"ad_group_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9]{1,24}$"}}],"post":{"operationId":"setAdsAmazonAdGroupBid","summary":"Change an Amazon Ads ad group's default bid — the click is the approval (AMZBIDS).","description":"Gated on `ads.manage`; audit action `ads.amazon_bid_set`. Read from Amazon first, proposed as a `bids` change and approved in one step, sent once through the gate with a 30-day Undo that puts the default bid Amazon held back. Refusals (`422`): `amazonOnly`, `amazonBadBid`, `amazonNoSuchCampaign`, `amazonNoSuchAdGroup`, `amazonBidUnchanged`, `amazonStepTooBig`, `amazonBidOverBudget` (a bid above the campaign's daily budget), `amazonWritesOff`, `notInGoodStanding`, `amazonReadFailed`, `needsReconnect`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsAmazonBidRequest"}}}},"responses":{"202":{"description":"Approved; the apply workflow sends it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsChange"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/amazon/campaigns/{campaign_id}/keywords/{keyword_id}/bid":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9]{1,24}$"}},{"name":"keyword_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9]{1,24}$"}}],"post":{"operationId":"setAdsAmazonKeywordBid","summary":"Change an Amazon Ads keyword's bid — the click is the approval (AMZBIDS).","description":"Gated on `ads.manage`; audit action `ads.amazon_bid_set`. As `setAdsAmazonAdGroupBid`, for one keyword that has its own bid; a keyword bidding its ad group's default is refused `amazonKeywordNoBid` (the Undo could not take a set bid away again). Also `amazonNoSuchKeyword`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsAmazonBidRequest"}}}},"responses":{"202":{"description":"Approved; the apply workflow sends it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsChange"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/meta/adsets":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsMetaAdsets","summary":"A Meta ad account's ad sets with their status, daily budget and 7-day spend (METABUILD).","description":"Gated on `ads.view`. Read from Meta now (docs/1006 §Meta App Review): every ad set that is not deleted or archived. `daily_budget_micros` is `null` when the ad set has no daily budget of its own (its campaign holds the budget, or a lifetime budget). Needs the connection to have granted `ads_management`. Refusals (`422`): `metaOnly`, `metaNeedsScope` (reconnect and allow it), `metaReadFailed` (try again), `needsReconnect`.","tags":["ads"],"responses":{"200":{"description":"The account's ad sets.","content":{"application/json":{"schema":{"type":"object","required":["connection_id","currency","offset","days","adsets"],"properties":{"connection_id":{"type":"string","format":"uuid"},"currency":{"type":"string","description":"ISO 4217 code of the ad account."},"offset":{"type":"integer","description":"Meta's minor-unit offset for the currency (1 or 100; 0 = unknown, budgets cannot be changed here)."},"days":{"type":"integer"},"adsets":{"type":"array","items":{"$ref":"#/components/schemas/AdsMetaAdset"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/meta/adsets/{adset_id}/status":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"adset_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9]{1,24}$"}}],"post":{"operationId":"setAdsMetaAdsetStatus","summary":"Pause or resume a Meta ad set — the click is the approval (METABUILD).","description":"Gated on `ads.manage`; audit action `ads.meta_adset_status_set`. The ad set is read from Meta first; the change is proposed as a `pauses` change and approved in one step, then sent by the apply workflow through the same gate as every write (kill switches, good standing), with a 30-day Undo that puts back the status Meta held. Refusals (`422`): `metaOnly`, `metaNeedsScope`, `metaBadStatus`, `metaNoSuchAdset`, `metaAdsetNotEditable`, `metaStatusUnchanged`, `metaReadFailed`, `paused`, `killed`, `notInGoodStanding`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["status"],"properties":{"status":{"type":"string","enum":["ACTIVE","PAUSED"]}}}}}},"responses":{"202":{"description":"Approved; the apply workflow sends it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsChange"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/meta/adsets/{adset_id}/budget":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"adset_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9]{1,24}$"}}],"post":{"operationId":"setAdsMetaAdsetBudget","summary":"Change a Meta ad set's daily budget — the click is the approval (METABUILD).","description":"Gated on `ads.manage`; audit action `ads.meta_adset_budget_set`. Proposed as a `budgets` change and approved in one step, then sent through the gate (kill switches, good standing, the spend ceilings weighed against Meta's active daily budgets — a raise past a ceiling is refused, a cut never is), with a 30-day Undo that restores the exact previous budget. Sent to Meta in the currency's own units (offset 1 or 100). Refusals (`422`): `metaOnly`, `metaNeedsScope`, `metaBadBudget` (zero, or finer than the currency's smallest unit), `metaNoSuchAdset`, `metaNoDailyBudget`, `metaBudgetUnchanged`, `metaUnknownCurrency`, `metaReadFailed`, `paused`, `killed`, `notInGoodStanding`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["daily_budget_micros"],"properties":{"daily_budget_micros":{"type":"integer","format":"int64","minimum":1,"maximum":1000000000000,"description":"The new daily budget in micros of the account currency (1 unit = 1,000,000)."}}}}}},"responses":{"202":{"description":"Approved; the apply workflow sends it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsChange"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/meta/pages":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsMetaPages","summary":"The Facebook Pages a Meta connection runs ads from, with name, picture and followers (METABUILD).","description":"Gated on `ads.view`. Read from Meta now (`/me/accounts`, never a Page access token). Needs `pages_show_list` and `pages_read_engagement`. Refusals (`422`): `metaOnly`, `metaNeedsScope`, `metaReadFailed`, `needsReconnect`.","tags":["ads"],"responses":{"200":{"description":"The Pages, most followers first.","content":{"application/json":{"schema":{"type":"object","required":["connection_id","data"],"properties":{"connection_id":{"type":"string","format":"uuid"},"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsMetaPage"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/quality-segments":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsQualitySegments","summary":"Sign-ups, activations and sales per keyword, search term, country and device (za-156).","description":"Gated on `ads.view`. The latest reading the connection's daily audit stored (docs/1006 §91) — never a network call in the request. Each segment's funnel comes from the account's conversion actions put on the signal ladder (stage 1 sign-up, 2 activation, 3 sale; `activated` is the larger of 2 and 3). `verdict`: `learning` (under the minimum sign-ups, or the account is blind — `state` `noActivationSignal` while it has fewer than `min_account_activations` activations), `ok`, `low` (activation rate under `cut_ratio_pct` percent of the account's), `never` (the minimum sign-ups and no activation). What was proposed (`action` `pause` / `bidDown` / `negative`, `outcome` `queued` / `applied` / `held` with the collision guard's reasons) waits in the change queue. Every threshold is the customer's own (`value`, `null` = following `recommended`). `reading` is `null` before the first audit.","tags":["ads"],"responses":{"200":{"description":"The reading, the thresholds and the mode.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsQualitySegments"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateAdsQualitySegmentsSettings","summary":"The mode and the customer's own thresholds for quality by segment (za-156).","description":"Gated on `ads.manage`; audit action `ads.quality_segments_settings` (before and after). `mode`: `off` (not read), `suggest` (every proposal waits for approval; recommended), `auto` (sent through the change gate, which still applies each action class's own mode, the kill switches, the spend ceilings and good standing). A threshold set to `null` goes back to the recommended value; outside its `min`..`max` it is refused (422). Takes effect at the next daily audit.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["off","suggest","auto"]},"min_signups":{"type":["integer","null"],"minimum":2,"maximum":500},"window_days":{"type":["integer","null"],"minimum":14,"maximum":180},"cut_ratio_pct":{"type":["integer","null"],"minimum":1,"maximum":90},"bid_down_pct":{"type":["integer","null"],"minimum":5,"maximum":50}}}}}},"responses":{"200":{"description":"The settings as stored, with the latest reading.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsQualitySegments"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/diagnosis":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsCampaignDiagnosis","summary":"Every campaign's \"not showing — why\" and budget pacing (za-76).","description":"Gated on `ads.view`. One row per enabled campaign of the connection — the house account and every customer connection alike — refreshed by the connection's daily job (docs/1006 §78), never a network call in the request. `reasons` are most decisive first: `held` (the whole ad account is on hold), `policy` (ads disapproved, limited by policy or under review), `not_eligible` (nothing in it can serve), `new` (live under 3 days, too early to judge), `budget` / `rank` (the share of impressions lost to the budget or to ad rank, at least 20%, bigger first), `learning` (the bid strategy is learning — the network's status, or our bid-ladder freeze until `frozen_until`), `no_auctions` (no impression share: nobody searched), `low_volume` (eligible, few searches). `state` is `held`, `not_showing`, `limited`, `new` or `showing`, worst first. Pacing: `today_micros` against `budget_micros` (`today_pct`), the month's spend so far (`month_micros`) and its projection (`projection_micros` = month so far + the campaign's own 7-day daily rate × `days_left`) against what the daily budget plans for the month (`plan_micros`); `pace` is `over` (above 105%), `under` (below 50%, from the 3rd of the month), `on_track`, `shared` (a shared budget: no per-campaign verdict) or `no_budget`. `why` is the plain English sentence the daily e-mail carries; the dashboard words each reason in the reader's language. An account with no reading yet answers `state: none`.","tags":["ads"],"responses":{"200":{"description":"The diagnosed campaigns, worst state first.","content":{"application/json":{"schema":{"type":"object","required":["data","state","currency","read_at"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsCampaignDiagnosis"}},"state":{"type":"string","enum":["held","not_showing","limited","new","showing","none"]},"currency":{"type":"string","description":"ISO 4217 code of the account."},"read_at":{"type":["string","null"],"format":"date-time"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/country-campaigns":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsCountryCampaigns","summary":"A customer's country campaigns, and the converting countries without one (za-75).","description":"Gated on `ads.view`. Read from the reading the connection's daily job keeps (docs/1006 COUNTRYCAMP), never a network call in the request; READ ONLY — the build (za-105), the split (za-179) and the budget raise (za-144) keep their own gates. `campaigns`: every enabled campaign whose only location is one country, with its 7-day budget, share of impressions lost to budget, spend, conversions and cost per conversion, who built it (`autopilot` — an applied new-country or country-split change, `change_id` — or `you`), and what happened about its budget (`budget_flag`, za-142: `raised`, `suggested`, `ceiling`, `recent`, `flagged`); `held_by_budget` from 50% lost to budget. `countries`: every country that converted in the last 30 days inside campaigns that are not its own, against the customer's trigger (`trigger`, set with `PATCH /v1/ads/connections/{id}`): `standing` is `proposed` (a change waits for approval), `ready` (meets the trigger; the next audit proposes it), `watching` (not yet), `monthly_limit`, `excluded` (the account excludes the country) or `off` (new-country campaigns or the Campaigns mode are off). `state` is `held`, `ready`, `ok` or `none` (no reading yet, or nothing to watch). Money in micros of the account currency. The house account answers `state: none`.","tags":["ads"],"responses":{"200":{"description":"The country campaigns and the countries without one.","content":{"application/json":{"schema":{"type":"object","required":["campaigns","countries","trigger","account_cost_per_conversion_micros","state","currency","read_at"],"properties":{"campaigns":{"type":"array","items":{"$ref":"#/components/schemas/AdsCountryCampaign"}},"countries":{"type":"array","items":{"$ref":"#/components/schemas/AdsCountryCandidate"}},"trigger":{"type":["object","null"],"required":["on","min_conversions","min_clicks","max_per_month","left_this_month"],"properties":{"on":{"type":"boolean"},"min_conversions":{"type":"integer"},"min_clicks":{"type":"integer"},"max_per_month":{"type":"integer"},"left_this_month":{"type":"integer"}}},"account_cost_per_conversion_micros":{"type":["integer","null"],"format":"int64"},"state":{"type":"string","enum":["held","ready","ok","none"]},"currency":{"type":"string","description":"ISO 4217 code of the account."},"read_at":{"type":["string","null"],"format":"date-time"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/bid-ladder":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsBidLadder","summary":"Every campaign's bid-strategy step, verdict, figures and learning freeze (za-183).","description":"Gated on `ads.view`. One row per campaign, refreshed by the connection's daily audit (docs/1006 §39) — never a network call in the request. The ladder is clicks → Maximise conversions → target CPA (or target ROAS for a campaign that sends values), one step at a time; each step needs the network's published minimum conversions times our 1.5 margin (`need` in `window_days`; `vendor_min` and `source` say whose figure it is, `verified` when it was read). `verdict`: `up` / `down` (a one-click switch), `not_yet`, `top`, `learning` (switched in the last 14 days: no automatic budget raise, bid, keyword, negative or pause touches it until `frozen_until`), `kept` (a portfolio strategy, a goal the customer chose, or a type that picks its own bidding). `review` is the measured result 14 days after a switch. Steps first, `kept` last; at most 500.","tags":["ads"],"responses":{"200":{"description":"The ladder rows.","content":{"application/json":{"schema":{"type":"object","required":["data","freeze_days","margin"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsBidLadderRow"}},"freeze_days":{"type":"integer"},"margin":{"type":"string","description":"Our margin over the vendor minimum, as a fraction (3/2)."},"focus_min_conversions":{"type":["integer","null"],"description":"ADSFOCUS-GUARD: the customer's own floor of account conversions (30 days, enabled primary actions) before a clicks campaign moves to Maximise conversions with no target; null = following `focus_min_recommended`. Set through the autopilot settings (`focus_min_conversions`)."},"focus_min_recommended":{"type":"integer","description":"Our recommended floor (15, the ladder's own figure for Maximise conversions)."},"auto_bid_switch":{"type":"boolean","description":"LADDERFIX: the account's toggle — false (the default) keeps every move onto a conversion strategy as a pending change for a person."},"sufficiency":{"type":"object","description":"LADDERFIX: the data-sufficiency gate — the campaign's own primary conversions in 30 days a move onto each conversion strategy needs (config, 15 by default).","required":["conversions","target_cpa","value"],"properties":{"conversions":{"type":"integer"},"target_cpa":{"type":"integer"},"value":{"type":"integer","description":"Conversions WITH a value, for Maximise conversion value and target ROAS."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/bid-ladder/{campaign_id}/switch":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9]{1,20}$"}}],"post":{"operationId":"switchAdsBidStrategy","summary":"The one click that moves a campaign the step its ladder row proposes (za-183).","description":"Gated on `ads.manage`; audit action `ads.bid_ladder_switch`. Only a row whose `verdict` is `up` or `down` (`422 notPending` otherwise, while a switch is already waiting, or before `no_switch_until` when the serving watch put a switch back). The switch is proposed as a `bids` change and approved in one step (the click is the approval); the apply workflow sends it through the same gate as every write (kill switches, good standing) with its 30-day Undo. A new target starts at the campaign's own last-30-day cost per conversion or return. The 14-day learning freeze starts now.","tags":["ads"],"responses":{"202":{"description":"Approved; the apply workflow sends it.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["change","ladder"],"properties":{"change":{"$ref":"#/components/schemas/AdsChange"},"ladder":{"$ref":"#/components/schemas/AdsBidLadderRow"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/bid-ladder/{campaign_id}/dismiss":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9]{1,20}$"}}],"post":{"operationId":"dismissAdsBidStrategySwitch","summary":"Say no to the step a ladder row proposes (za-183).","description":"Gated on `ads.manage`; audit action `ads.bid_ladder_dismiss`. The row is asked again only for a DIFFERENT step. `422 notPending` when the row proposes nothing.","tags":["ads"],"responses":{"200":{"description":"Dismissed.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsBidLadderRow"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/objectives":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsCampaignObjectives","summary":"Every campaign's objective, the proposal waiting and the judgement against it (za-184).","description":"Gated on `ads.view`. One row per campaign the daily audit has read (docs/1006 §43) — never a network call in the request. `objective` is the one in force (`null`: none — the campaign is judged and bid exactly as before objectives existed); `pending` a proposal that changes nothing until a person approves it; `judgement` the latest daily verdict against the objective (`on_target` / `off_target` / `no_data`) with its figures in words; `ladder` the bid-strategy ladder's verdict, which the objective steers (§39). Campaigns with an objective or a proposal first; at most 500.","tags":["ads"],"responses":{"200":{"description":"The campaigns and their objectives.","content":{"application/json":{"schema":{"type":"object","required":["data","kinds"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsCampaignObjectiveRow"}},"kinds":{"type":"array","items":{"type":"string","enum":["leads","revenue","profit","top_of_page","brand_defence","traffic","reach"]}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/objectives/{campaign_id}":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9]{1,20}$"}}],"put":{"operationId":"proposeAdsCampaignObjective","summary":"Propose a campaign's objective — approve-first, it changes nothing yet (za-184).","description":"Gated on `ads.manage`; audit action `ads.objective_propose`. Stores the proposal as `pending`; a person approves it (`approveAdsCampaignObjective`) before it is in force. `objective: none` proposes clearing it. Each objective needs its own fields: `leads` a `target_cpa_micros`; `revenue` a `target_roas_pct` (400 = 4.00x); `profit` a `margin_pct` (the target return is break-even, 100 / margin); `top_of_page` a `share_pct`, a `placement` and a `max_cpc_micros`; `brand_defence` a `max_cpc_micros` (90% at `absolute_top` unless given); `traffic` an optional `max_cpc_micros`; `reach` (za-201) an optional `max_cpm_micros`, and only on a `VIDEO` / `DEMAND_GEN` campaign of a connection whose YouTube channel is saved (`putAdsVideo`; otherwise `422 badPick` on `objective`). Money is integer micros of the account's currency. `422 badPick` names the field that is missing or wrong; `404` for a campaign the daily audit has not read.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsObjectiveTargets"}}}},"responses":{"202":{"description":"Proposed; waiting for a person's approval.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsCampaignObjectiveRow"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/objectives/{campaign_id}/approve":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9]{1,20}$"}}],"post":{"operationId":"approveAdsCampaignObjective","summary":"A person's approval puts the proposed objective in force (za-184).","description":"Gated on `ads.manage`; audit action `ads.objective_approve`. `422 badState` when nothing is proposed. The account's audit starts at once: the bid-strategy ladder then judges the campaign against the objective. Any switch it implies is the ladder's own proposal — one step at a time, on the networks' minimums plus our margin, never while the campaign learns (the 14-day freeze), and sent only through the change queue with its Undo.","tags":["ads"],"responses":{"200":{"description":"In force.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsCampaignObjectiveRow"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/objectives/{campaign_id}/reject":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9]{1,20}$"}}],"post":{"operationId":"rejectAdsCampaignObjective","summary":"Drop a proposed objective; nothing changes (za-184).","description":"Gated on `ads.manage`; audit action `ads.objective_reject`. `422 badState` when nothing is proposed.","tags":["ads"],"responses":{"200":{"description":"Dropped.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsCampaignObjectiveRow"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/paid-geo":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsPaidGeo","summary":"Paid revenue by country and by campaign device, and what it proposes (za-168).","description":"Gated on `ads.view`. The latest reading the connection's daily audit stored (docs/1006 §PAIDGEO) — never a network call in the request. Only conversion actions on stage 3 of the signal ladder (a sale) count: `sales` and `revenue_minor` (integer minor units of `currency`) are PAID-customer figures; sign-ups, trials and activations never move a country or a device. Country `verdict`: `campaign` (at least `min_sales` sales and `country_share_pct` percent of the account's paid revenue — proposed its own campaign), `ownCampaign`, `excluded`, `belowShare`, `learning`. Device `verdict`: `up` / `down` (with `proposed_modifier`), `hold`, `learning`, `deviceExcluded`. `outcome`: `queued`, `approved`, `alreadyProposed`, `campaignsOff`, `bidsOff`, `refused:adBelowGood`, `noAdGroups`, or empty. `state` `noPaidSignal` while the account has fewer than `min_account_sales` paid sales in the window (nothing is judged). Every threshold is the customer's own (`value`, `null` = following `recommended`). `reading` is `null` before the first audit.","tags":["ads"],"responses":{"200":{"description":"The reading, the thresholds and the mode.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsPaidGeo"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateAdsPaidGeoSettings","summary":"The mode and the customer's own thresholds for paid revenue by country and device (za-168).","description":"Gated on `ads.manage`; audit action `ads.paid_geo_settings` (before and after). `mode`: `off` (not read), `suggest` (every proposal waits for approval; recommended), `auto` (each proposal is approved at once where the action class — `campaigns` for a country campaign, `bids` for a device modifier — is Automatic; the apply gate still checks the kill switches, the spend ceilings and good standing). A threshold set to `null` goes back to the recommended value; outside its `min`..`max` it is refused (422). Takes effect at the next daily audit.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["off","suggest","auto"]},"window_days":{"type":["integer","null"],"minimum":30,"maximum":365},"min_sales":{"type":["integer","null"],"minimum":1,"maximum":500},"country_share_pct":{"type":["integer","null"],"minimum":1,"maximum":90},"device_gap_pct":{"type":["integer","null"],"minimum":5,"maximum":90},"device_step_pct":{"type":["integer","null"],"minimum":5,"maximum":50}}}}}},"responses":{"200":{"description":"The settings as stored, with the latest reading.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsPaidGeo"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/next-country":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsNextCountry","summary":"The countries this account could open next, ranked, and the one approve-only proposal (za-N10).","description":"Gated on `ads.view`. The latest reading the connection's audit stored (docs/1006 §NEXTCOUNTRY; refreshed at most every `cadence_days` days) — never a network call in the request. Evidence is FIRST-PARTY only: for the platform's own account our billing (paid, non-refunded invoices NET in USD and sign-ups, by billing country, `basis` `billing`); for a customer's account their product's upgrades and sign-ups on this connection (`basis` `product`). A candidate is a country Google can target that brought evidence and that no campaign reaches yet. `searches` and `cpc_micros` come from Google's Keyword Planner for the core campaign's keywords (the searches-weighted mid-point of the top-of-page bid range, account currency micros). Country `verdict`: `open` (qualifies; the best is proposed), `notBuying` (buying countries only, no sale), `fewSignals`, `excluded`, `noSearchVolume`, `noCoreKeywords`. `risks`: `signupsOnly`, `thinEvidence`, `noSearchVolume`, `cpcAboveAccount`, `adsNotInLocalLanguage`, `noVatRateOnFile`. `tax` (platform account only): `regime` `uk` / `eu_oss` / `outside` and the `rate_bps` row in force. `outcome`: `queued`, `alreadyProposed`, `proposalWaiting`, `campaignsOff`, `refused:adBelowGood`, `refused:collision` (with the `collisions` dropped), `noAdGroups`, or empty. `state` `noFirstParty` when the window holds no first-party evidence at all (nothing is judged); `nothingNew` when every evidenced country is already reached. `reading` is `null` before the first audit. The proposal is ONE pending change in the connection's change queue (`pending_change_id`), approve-only: never approved by the autopilot, whatever the modes say.","tags":["ads"],"responses":{"200":{"description":"The reading and the settings.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsNextCountry"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateAdsNextCountrySettings","summary":"The next-country advisor's mode, \"buying countries only\" and the customer's own thresholds (za-N10).","description":"Gated on `ads.manage`; audit action `ads.next_country_settings` (before and after). `mode`: `suggest` (rank and queue one approve-only proposal; recommended) or `off` (not read). `buying_only`: only a country with at least `min_sales` sales qualifies. A threshold set to `null` goes back to the recommended value; outside its `min`..`max` it is refused (422). Takes effect at the next reading.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["suggest","off"]},"buying_only":{"type":"boolean"},"window_days":{"type":["integer","null"],"minimum":30,"maximum":365},"min_sales":{"type":["integer","null"],"minimum":1,"maximum":100},"min_signups":{"type":["integer","null"],"minimum":1,"maximum":500}}}}}},"responses":{"200":{"description":"The settings as stored, with the latest reading.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsNextCountry"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/acquisition-quality":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsAcquisitionQuality","summary":"Customer quality per keyword, ad group and country — bad-customer rate against the rest of the account (za-215).","description":"Gated on `ads.view`. Refreshed by the connection's daily audit (docs/1006 §45) — never a network call in the request. Every paid customer is traced to the keyword, ad group and country that acquired them; a customer is BAD when (per `basis`) they were refunded, charged back, cancelled within `rule.early_cancel_days` days, or opened many support tickets. A customer's account reads only its own checkout connectors' sales (za-119): a connector reports refunds only, so its `basis` is `[refund]` and it has no country rows. Rates are integer basis points; `baseline_bp` on a row is the REST of the account (the term left out). `verdict`: `finding` (an open one-click suggestion to pause the keyword or ad group, or exclude the country; Apply is `POST …/findings/{id}/apply`, with Undo), `owner_locked`, `held_sample` (fewer than `rule.min_bad` bad customers), `held_baseline` (the rest of the account has fewer than `rule.min_baseline_paid` paid customers), `held_rate` (below `rule.rate_factor` times the rest). No buyer is ever named. Paged, never capped: `total` is every term in the report; follow `page.next_cursor` until `page.has_more` is false to read them all, in the report's order. A cursor is tied to one day's report — after the next audit re-writes it, an old cursor is a `422`, never a page of a different list.","tags":["ads"],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"One page of the stored report (`as_of` null before the first audit).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsAcquisitionQuality"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/asks":{"get":{"operationId":"listAdsAsks","summary":"The organisation's recent \"Ask your ads\" questions and their checked answers (za-N7).","description":"Gated on `ads.view`; the 20 most recent asks of the caller's organisation (narrow with `?org_id=`), newest first. Never another organisation's (docs/1006 §ASKADS).","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The recent asks.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsAsk"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createAdsAsk","summary":"Ask a plain question about the organisation's own ads; the answer is checked figure by figure against cited facts (za-N7).","description":"Gated on `ads.view` in ONE organisation (`org_id` in the body or `X-Zinn-Org` when the caller holds several). Interactive: one Zinn® AI call in the request, no job queue. The facts are read ONLY from the organisation's own synced figures (account totals, spend per day for up to 31 recent days, campaigns ranked by spend, Google keywords and search terms that spend with no conversion, open findings, changes waiting). `status`: `answered` (every number in `answer` appears in a fact it cites — ids in `cites`, figures in `facts`), `facts_only` (the written answer failed that check and is withheld; the cited facts are the answer), `refused` (no AI credit, or the organisation is not in good standing — `error.failure` class `refused`, nothing was spent) or `failed` (the AI provider failed — `error.failure` names the class: outage with its status page, a customer key problem, or ours). Who pays is the one meter's decision: the organisation's own AI key, else its Zinn® AI credit. At most ONE `fix` is offered, built from a fact (never by the model): `pause_campaign` or `pause_keyword` for a Google campaign or keyword that spends with no conversion. `focus_day` (za-285, \"Ask your ads\" from a chart point on /ads/analytics): the day the person clicked; that day's spend per account is always a fact, however far back inside `days`. `422` codes: `askQuestion` (1 to 500 characters), `askDays` (1 to 90), `askNoAccounts`, `askHourly` (60 asks per organisation per hour), `askFocusDay` (`focus_day` not a date inside the last `days` days). `404` for a `connection_id` that is not the organisation's.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["question"],"properties":{"question":{"type":"string","minLength":1,"maxLength":500},"org_id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid","description":"Narrow to one ad account."},"days":{"type":"integer","minimum":1,"maximum":90,"default":30},"locale":{"type":"string","maxLength":16,"description":"The answer's language, e.g. en, ar."},"focus_day":{"type":"string","format":"date","description":"za-285: the chart point (day) the question was asked from."}}}}}},"responses":{"201":{"description":"The ask, its status and (when answered) the checked answer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsAsk"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/asks/{ask_id}/fix":{"parameters":[{"name":"ask_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"proposeAdsAskFix","summary":"Keep the answer's one fix as a change waiting for approval (za-N7).","description":"Gated on `ads.manage` in the ask's organisation and written to its activity log. Keeps the fix as ONE pending change in the approval queue (`proposed_by` the person, `summary` `auto_action` `ask_pause_campaign` or `ask_pause_keyword`). Nothing reaches the ad network until a person approves it (`POST /v1/ads/changes/{change_id}/approve`), where the kill switches, ceilings and standing still decide; an applied pause keeps its 30-day Undo. Asking twice returns the same change. `422 askNoFix` when the answer offered none.","tags":["ads"],"responses":{"201":{"description":"The pending change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsChange"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/ai-max":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsAiMax","summary":"The AI Max for Search guard — expanded searches against keyword-matched ones, their return, and the customer's own rules (za-204).","description":"Gated on `ads.view`. Refreshed by the connection's daily audit (docs/1006 §97) — never a network call in the request. Google reports which door each search came through (`segments.search_term_match_source`): `expanded` sums `AI_MAX_BROAD_MATCH` and `AI_MAX_KEYWORDLESS`, `keyword` is `ADVERTISER_PROVIDED_KEYWORD`. An expanded search's waste is judged by the za-99 negatives path with the customer's own `rules` (`waste_min_clicks`, `waste_min_cost_minor` in minor units of the account currency) and the collision replay; `waste_terms` lists those findings (Apply / Dismiss are the ordinary `POST …/findings/{id}/{action}`). `return_pct` is the expanded searches' conversion value per unit of cost (`basis: value`) — or conversions per unit of cost (`basis: conversions`) when no value is recorded — as a percent of the keyword searches'. `verdict`: `none` (no AI Max traffic), `learning` (fewer than `rules.compare_min_clicks` clicks in either group), `no_keyword_return`, `ok`, `below` (under `rules.min_return_pct`). `skipped`: `notInGoodStanding` or `readRefused`.","tags":["ads"],"responses":{"200":{"description":"The stored report (`as_of` null before the first audit).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsAiMax"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateAdsAiMaxRules","summary":"Set the customer's own AI Max guard rules; a rule sent as null is Reset to recommended (za-204).","description":"Gated on `ads.manage` and written to the organisation's activity log. `rules` is merged over the stored rules; a key sent as `null` returns to its Recommended value and `\"rules\": null` resets every rule. A number outside `bounds` refuses with `badAiMaxRule` naming the field.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rules"],"properties":{"rules":{"type":"object","nullable":true,"properties":{"guard":{"type":"boolean","nullable":true},"waste_min_clicks":{"type":"integer","nullable":true,"minimum":1,"maximum":1000},"waste_min_cost_minor":{"type":"integer","nullable":true,"minimum":1,"maximum":1000000000},"compare_min_clicks":{"type":"integer","nullable":true,"minimum":10,"maximum":100000},"min_return_pct":{"type":"integer","nullable":true,"minimum":1,"maximum":100}}}}}}}},"responses":{"200":{"description":"The report with the rules now in force.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsAiMax"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/placement-goals":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsPlacementGoals","summary":"Every top-of-page goal, measured, diagnosed and priced (za-187).","description":"Gated on `ads.view`. One row per campaign with a top-of-page goal (docs/1006 §47) — its main keywords, the target share of the top (`top`) or absolute top (`absolute_top`) of the page, the max CPC and daily budget (0: priced for you) — and `report`, the daily audit's latest reading: the measured share and verdict (`on_target` / `off_target` / `no_data`) and, below target, the `causes` in order (`missing_keywords`, `ad_relevance`, `landing_page`, `expected_ctr`, then `bid` and `budget`) with each fix, and the priced `proposals` (Target impression share with a max CPC from the network's own top-of-page bid estimates; the budget that buys about `min_top_clicks` top-of-page clicks a day; or `concentrate` when the monthly ceiling cannot fund it as well). `campaigns`: the Search campaigns a goal can be set on. Never a network call in the request; at most 500.","tags":["ads"],"responses":{"200":{"description":"The goals and the campaigns a goal can be set on.","content":{"application/json":{"schema":{"type":"object","required":["data","campaigns","placements","min_top_clicks","max_keywords"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsPlacementGoal"}},"campaigns":{"type":"array","items":{"type":"object","required":["campaign_id","campaign","currency"],"properties":{"campaign_id":{"type":"string"},"campaign":{"type":"string"},"currency":{"type":"string"}}}},"placements":{"type":"array","items":{"type":"string","enum":["top","absolute_top"]}},"min_top_clicks":{"type":"integer","description":"The budget floor: a budget must buy about this many top-of-page clicks a day."},"max_keywords":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/placement-goals/{campaign_id}":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9]{1,20}$"}}],"put":{"operationId":"setAdsPlacementGoal","summary":"Set a campaign's top-of-page goal — it sends nothing to the ad account (za-187).","description":"Gated on `ads.manage`; audit action `ads.placement_goal_set`. Replaces the campaign's goal; the account's audit starts at once so it is measured today. A goal is a target, never a change: below target the audit proposes its fixes as one finding a person applies (approve-first, each with its Undo). `422 badPick` names the field that is missing or wrong; `404` for a Search campaign the daily audit has not read.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsPlacementGoalInput"}}}},"responses":{"200":{"description":"Set.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsPlacementGoal"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"removeAdsPlacementGoal","summary":"Remove a campaign's top-of-page goal (za-187).","description":"Gated on `ads.manage`; audit action `ads.placement_goal_remove`. Nothing is sent to the ad account.","tags":["ads"],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/organic":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsOrganic","summary":"Each paid keyword beside the same query's organic clicks and position (za-191).","description":"Gated on `ads.view`. The Search Console property picked for this Google Ads account, whether its grant can read Search Console (`granted`; a grant made before the scope was offered reconnects — `scope_offered` says whether Connect asks for it now), the paid-vs-organic saver's thresholds (`settings`, the customer's own; `recommended` our defaults; `bounds`), and every enabled keyword over the last `window_days` days with its paid clicks, cost and conversions beside its organic clicks, impressions and average position. Read from our own rows, refreshed by the daily audit in Temporal — never a network call (docs/1006 §78). `422 organicGoogleOnly` for a non-Google account.","tags":["ads"],"responses":{"200":{"description":"The paid-vs-organic screen.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsOrganic"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateAdsOrganic","summary":"Pick the Search Console property and edit the paid-vs-organic saver (za-191, za-N3).","description":"Gated on `ads.manage`; audit action `ads.organic_settings`. Every threshold is the customer's; each must sit inside its `bounds`. Where the site ranks at the top organically (`organic_top_position`, with `organic_min_clicks`) and paid adds nothing measured (`organic_paid_min_clicks` clicks, no conversion), the daily audit PROPOSES lowering the bid by `organic_lower_pct` or pausing the keyword (`organic_saver_action`); where organic is weaker than `organic_weak_position` and the keyword converts, it proposes raising the bid by `organic_raise_pct`. Every proposal waits for approval in the changes queue; a keyword proposed is left alone for `organic_cooldown_days`. `site` must be one of the properties `listAdsOrganicSites` returns (empty string stops the reading). `422 organicInvalid` (the field is named) · `organicSiteUnknown` · `organicNeedsScope` · `organicUnavailable` · `organicGoogleOnly`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsOrganicUpdate"}}}},"responses":{"200":{"description":"The screen after the edit.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsOrganic"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/organic/sites":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsOrganicSites","summary":"The Search Console properties this account's Google sign-in can read (za-191).","description":"Gated on `ads.view`. One read of Google Search Console (`sites.list`) on the customer's own grant while they choose — never the platform's own-sites account. `422 organicNeedsScope` (the grant lacks `webmasters.readonly`: connect Google again) · `organicUnavailable` (Search Console did not answer) · `organicGoogleOnly`.","tags":["ads"],"responses":{"200":{"description":"The properties.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsOrganicSite"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/merchant-feed":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsMerchantFeed","summary":"The account's Shopping + Merchant Center feed audit (za-188).","description":"Gated on `ads.view`. The settings and the last daily audit of the product feed: products the network disapproved or limited (missing GTIN, price or availability mismatch, policy, landing page), our own landing-page read of every product that spent, out-of-stock products still spending (linked to the stock pause), and product-level waste — spend with no sale over the threshold (the customer's own, or Recommended: the account's own cost per sale) — with each exclusion queued for approval. Read from our own row; the audit runs in the connection's daily Temporal child, never in the request (docs/1006 §80).","tags":["ads"],"responses":{"200":{"description":"The feed audit.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsMerchantFeed"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateAdsMerchantFeed","summary":"Change the feed audit's settings (za-188).","description":"Gated on `ads.manage`; audit action `ads.merchant_feed_update`. `mode` `off` stops the audit; `waste_threshold_micros` `null` resets the waste threshold to Recommended; `store_id` is the Microsoft Merchant Center store (digits). Refusals: `badState` (an unknown field, mode or store id), `badFeedSetting` (a threshold that is not a positive whole number of micros), `platformNotSupported` (a network with no Shopping feed).","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"mode":{"type":"string","enum":["off","suggest"]},"waste_threshold_micros":{"type":["integer","null"],"format":"int64","minimum":1,"maximum":1000000000000},"store_id":{"type":"string","pattern":"^[0-9]{0,20}$"}}}}}},"responses":{"200":{"description":"The feed audit with its new settings.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsMerchantFeed"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/site-guards":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsSiteGuards","summary":"The account's site guards — pause the ads while the site is down (za-N1).","description":"Gated on `ads.view`. Every site guard of the connection (newest first) and the org's own uptime monitors to choose from. Read from our own rows — never a network call (docs/1006 §91).","tags":["ads"],"responses":{"200":{"description":"The guards and the monitors.","content":{"application/json":{"schema":{"type":"object","required":["data","monitors","settings"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsSiteGuard"}},"monitors":{"type":"array","items":{"$ref":"#/components/schemas/AdsSiteGuardMonitor"}},"settings":{"$ref":"#/components/schemas/AdsSiteGuardSettings"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createAdsSiteGuard","summary":"Guard one of the org's uptime monitors for this ad account (za-N1).","description":"Gated on `ads.manage`; audit action `ads.site_guard_create`. While the monitor is DOWN the enabled campaigns in `campaign_ids` (empty = every enabled campaign) are paused, each an ordinary change with its 30-day Undo through every guard a write passes (kill switches, good standing); when it is UP again exactly the campaigns the guard paused are re-enabled — never one the customer paused. Runs in Temporal on the monitor's transition, never in the request. A site already down when the guard is made is held at once. `422 siteGuardNoMonitor` (not one of the org's monitors) · `siteGuardExists` · `siteGuardInvalid` · `siteGuardNetwork` (Google accounts only).","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["monitor_id"],"properties":{"monitor_id":{"type":"string","format":"uuid"},"campaign_ids":{"type":"array","maxItems":500,"items":{"type":"string","pattern":"^[0-9]{1,20}$"}}}}}}},"responses":{"201":{"description":"The guard.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsSiteGuard"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/site-guard-settings":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"operationId":"updateAdsSiteGuardSettings","summary":"Hosting-aware ads — the switch and thresholds (za-207).","description":"Gated on `ads.manage`; audit action `ads.site_guard_settings` (before/after). A partial update of the customer's own values; `reset: true` restores every recommended value. Every guard of the account is re-judged on Temporal against the site's state now. Refusal `siteGuardInvalid` (422) names the field outside its bounds (docs/1006 §64a).","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"auto":{"type":"boolean"},"down_minutes":{"type":"integer","minimum":1,"maximum":1440},"slow_ms":{"type":"integer","minimum":0,"maximum":60000},"recovery_minutes":{"type":"integer","minimum":1,"maximum":1440},"reset":{"type":"boolean"}}}}}},"responses":{"200":{"description":"The stored settings.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsSiteGuardSettings"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/site-guards/{guard_id}":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"guard_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"operationId":"updateAdsSiteGuard","summary":"Switch a site guard on or off, or change its campaigns (za-N1).","description":"Gated on `ads.manage`; audit action `ads.site_guard_update`. Switching a holding guard off re-enables the campaigns it paused; switching it on while the site is down holds them.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean"},"campaign_ids":{"type":"array","maxItems":500,"items":{"type":"string","pattern":"^[0-9]{1,20}$"}}}}}}},"responses":{"200":{"description":"The guard.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsSiteGuard"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"deleteAdsSiteGuard","summary":"Remove a site guard (za-N1).","description":"Gated on `ads.manage`; audit action `ads.site_guard_delete`. A guard still holding campaigns is switched off and releases them first (`422 siteGuardHolding`); delete it once it shows `watching`, so no campaign is ever left paused.","tags":["ads"],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/site-guards/{guard_id}/sync":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"guard_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"syncAdsSiteGuard","summary":"Check now — reconcile a site guard to its monitor (za-N1).","description":"Gated on `ads.manage`. Starts the guard's Temporal workflow, which pauses or re-enables the campaigns to match the monitor's current state; the card shows the result once it has run.","tags":["ads"],"responses":{"202":{"description":"Started (`started` false when Temporal could not be reached).","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["started","guard"],"properties":{"started":{"type":"boolean"},"guard":{"$ref":"#/components/schemas/AdsSiteGuard"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/geo-holdouts":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsGeoHoldouts","summary":"The account's geo hold-outs — incrementality tests by country (za-202).","description":"Gated on `ads.view`. Every geo hold-out of the connection (newest first, at most 200) and the customer's thresholds. Before a budget raise at or over the threshold, one country is held out of the campaign for `days`, resumed by its own Undo, and the account's real first-party sales are compared with their trend: `lift` (with the measured incrementality), `noLift`, or `inconclusive` with its `reason` (`tooFewSales`, `underpowered`, `noSignal`, `endedEarly`). Read from our own rows — never a network call (docs/1006 §80).","tags":["ads"],"responses":{"200":{"description":"The tests and the settings.","content":{"application/json":{"schema":{"type":"object","required":["data","settings"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsGeoHoldout"}},"settings":{"$ref":"#/components/schemas/AdsGeoHoldoutSettings"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/geo-holdouts/settings":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsGeoHoldoutSettings","summary":"The customer's geo hold-out thresholds, with the Recommended values (za-202).","description":"Gated on `ads.view`. The stored values (Recommended where never set) and their bounds.","tags":["ads"],"responses":{"200":{"description":"The settings.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsGeoHoldoutSettings"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"updateAdsGeoHoldoutSettings","summary":"Store the customer's geo hold-out thresholds (za-202).","description":"Gated on `ads.manage`; audit action `ads.geo_holdout_settings`. `mode` suggest (propose for approval, the default) · auto (start without asking, never for a country in the customer's markets) · off. `reset: true` puts every value back to Recommended. A value outside its bounds is `422 geoHoldoutInvalid`. A test already proposed keeps the values it was proposed with.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"mode":{"type":"string","enum":["auto","suggest","off"]},"raise_pct":{"type":"integer","minimum":5,"maximum":500},"days":{"type":"integer","minimum":7,"maximum":56},"min_sales":{"type":"integer","minimum":5,"maximum":100000},"reset":{"type":"boolean"}}}}}},"responses":{"200":{"description":"The stored settings.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsGeoHoldoutSettings"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/geo-holdouts/{holdout_id}/approve":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"holdout_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"approveAdsGeoHoldout","summary":"Approve a proposed geo hold-out (za-202).","description":"Gated on `ads.manage`; audit action `ads.geo_holdout_approve`. Approves the hold-out change (a negative location on the campaign, with its Undo) and starts the test's durable timer in Temporal; the country resumes on its own at the end. `422 geoHoldoutState` when the test is not proposed.","tags":["ads"],"responses":{"200":{"description":"The test.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsGeoHoldout"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/geo-holdouts/{holdout_id}/decline":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"holdout_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"declineAdsGeoHoldout","summary":"Decline a proposed geo hold-out (za-202).","description":"Gated on `ads.manage`; audit action `ads.geo_holdout_decline`. The hold-out change is rejected and the test never runs. `422 geoHoldoutState` when the test is not proposed.","tags":["ads"],"responses":{"200":{"description":"The test.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsGeoHoldout"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/geo-holdouts/{holdout_id}/stop":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"holdout_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"stopAdsGeoHoldout","summary":"End a running geo hold-out now (za-202).","description":"Gated on `ads.manage`; audit action `ads.geo_holdout_stop`. Starts the hold-out change's Undo in Temporal (the country serves again); the test is then reported `inconclusive` / `endedEarly`. `422 geoHoldoutState` when the test is not running.","tags":["ads"],"responses":{"200":{"description":"The test.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsGeoHoldout"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/matching-pages":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsMatchingPages","summary":"Matching landing pages — the connection's pages and candidate ad groups (za-N6).","description":"Gated on `ads.view`. Every open page of the connection (a `candidate` ad group found by the scan, a page being written, ready to preview, publishing, live or being unpublished) and the 20 most recent closed ones. Read from our own rows — never a network call (docs/1006 §94). `alternatives_only=true` keeps only competitor alternative pages (za-109, a non-empty `rival`), as the MCP `ads_matching_pages` tool does.","tags":["ads"],"parameters":[{"name":"alternatives_only","in":"query","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"The pages.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["pages","history"],"properties":{"pages":{"type":"array","items":{"$ref":"#/components/schemas/AdsMatchingPage"}},"history":{"type":"array","items":{"$ref":"#/components/schemas/AdsMatchingPage"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/matching-pages/scan":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"scanAdsMatchingPages","summary":"Find the ad groups whose ads land on a site hosted with us (za-N6).","description":"Gated on `ads.manage`, audit-logged. Starts a Temporal workflow that reads the enabled responsive search ads and keeps one `candidate` per ad group landing on a site this organisation hosts with us; a group that no longer qualifies is retired. Google Ads only (`422 landingGoogleOnly`).","tags":["ads"],"responses":{"202":{"description":"The scan has started.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["scanning"],"properties":{"scanning":{"type":"boolean"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/matching-pages/{page_id}":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"page_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsMatchingPage","summary":"One matching landing page (za-N6).","description":"Gated on `ads.view`. Read from our own rows.","tags":["ads"],"responses":{"200":{"description":"The page.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsMatchingPage"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/matching-pages/{page_id}/preview":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"page_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"locale","in":"query","required":false,"schema":{"type":"string"}}],"get":{"operationId":"previewAdsMatchingPage","summary":"The server-rendered page, exactly as it will be published (za-N6).","description":"Gated on `ads.view`. The full HTML document (title, description, canonical, hreflang alternates, JSON-LD, the language's own direction) in the site's own language or, with `locale`, one of its translations. `422 landingPageState` before the page is written.","tags":["ads"],"responses":{"200":{"description":"The page.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["html","locale","url"],"properties":{"html":{"type":"string"},"locale":{"type":"string"},"url":{"type":"string","format":"uri"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/matching-pages/{page_id}/write":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"page_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"writeAdsMatchingPage","summary":"Write (or rewrite) the page with the AI writer (za-N6).","description":"Gated on `ads.manage`, audit-logged. A Temporal workflow reads the site's own pages and writes the headline, intro, points and button, every line citing the sentence it restates (no invented price or claim), then translates it into the site's other languages in one batched call. Spends AI credit on the organisation's own meter; an organisation not in good standing is refused before any spend (`422 landingNotInGoodStanding`), and a run already started stops before the writer.","tags":["ads"],"responses":{"202":{"description":"The page, as it now stands.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsMatchingPage"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/matching-pages/{page_id}/approve":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"page_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"approveAdsMatchingPage","summary":"Approve and publish the page, then switch the ad group's final URL (za-N6).","description":"Gated on `ads.manage`, audit-logged. Approve-first: nothing is published before this. A Temporal workflow writes the page into the site's document root, waits until it answers 200, and only then switches the ad group's final URL through the metered gate, as an Undo-able change. `422 landingNotInGoodStanding` when the organisation is not in good standing.","tags":["ads"],"responses":{"202":{"description":"The page, as it now stands.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsMatchingPage"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/matching-pages/{page_id}/unpublish":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"page_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"unpublishAdsMatchingPage","summary":"Undo — put the old final URL back, then remove the page (za-N6).","description":"Gated on `ads.manage`, audit-logged. The final-URL change is undone first (or a waiting one rejected); only then is the page's folder removed, so no ad points at a missing page.","tags":["ads"],"responses":{"202":{"description":"The page, as it now stands.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsMatchingPage"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/matching-pages/{page_id}/discard":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"page_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"discardAdsMatchingPage","summary":"Throw away a written page that was never published (za-N6).","description":"Gated on `ads.manage`, audit-logged. `422 landingPageState` for a page that is not a never-published `ready` page.","tags":["ads"],"responses":{"200":{"description":"The page, as it now stands.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsMatchingPage"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/page-fixes":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsPageFixes","summary":"Landing-page fixes applied on sites hosted with us (za-210).","description":"Gated on `ads.view`. Every open fix of the connection (being written, ready to preview, being applied, applied and still undoable, being undone) and the 20 most recent closed ones. Read from our own rows — never a network call (docs/1006 §111).","tags":["ads"],"responses":{"200":{"description":"The fixes.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["fixes","history","fixable"],"properties":{"fixable":{"type":"array","description":"Open landing-page findings a fix can be written for now (editable reason, a page file on a site hosted with us, no open fix).","items":{"$ref":"#/components/schemas/AdsPageFixable"}},"fixes":{"type":"array","items":{"$ref":"#/components/schemas/AdsPageFix"}},"history":{"type":"array","items":{"$ref":"#/components/schemas/AdsPageFix"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createAdsPageFix","summary":"Write the fix for one landing-page finding on a page hosted with us (za-210).","description":"Gated on `ads.manage`, audit-logged. For a landing-page finding whose page title, H1, meta description or button misses the ad group's words (`lp_intent`, `lp_competitor`, `lp_cta_wrong`) on a page FILE of a site this organisation hosts with us, a Temporal workflow reads the whole file (kept byte-exact as the Undo snapshot) and the AI writer proposes the text edits — charged on the one AI meter (BYO key, else AI credits) now, on this request. Nothing is written to the site until `approve`. Twice is once (the open fix for the same page is returned). 422 `pageFixNotHosted`, `pageFixNotEditable`, `pageFixNotAFile`, `pageFixNoWords`, `pageFixNotInGoodStanding`, `landingGoogleOnly`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["finding_id"],"properties":{"finding_id":{"type":"string","format":"uuid"}}}}}},"responses":{"202":{"description":"The fix is being written.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsPageFix"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/page-fixes/{fix_id}":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"fix_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsPageFix","summary":"One landing-page fix (za-210).","description":"Gated on `ads.view`. Read from our own rows.","tags":["ads"],"responses":{"200":{"description":"The fix.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsPageFix"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/page-fixes/{fix_id}/preview":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"fix_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"previewAdsPageFix","summary":"The page as it is and as it will be after the fix (za-210).","description":"Gated on `ads.view`. `before` and `after` are the whole page HTML with a `<base>` for its own assets; the dashboard shows them in a sandboxed iframe (nothing on the page runs). 422 `pageFixState` before the fix is written.","tags":["ads"],"responses":{"200":{"description":"The two versions.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["before","after","url","edits"],"properties":{"before":{"type":"string"},"after":{"type":"string"},"url":{"type":"string"},"edits":{"type":"array","items":{"$ref":"#/components/schemas/AdsPageFixEdit"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/page-fixes/{fix_id}/approve":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"fix_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"approveAdsPageFix","summary":"Apply the fix to the page on the site (za-210).","description":"Gated on `ads.manage`, audit-logged. Writes the edited page through a compare-and-swap on the box: only over the exact bytes snapshotted when the fix was written (a page changed since fails with `pageFixChangedSince` and keeps the customer's edit). Twice is once. 422 `pageFixState`, `pageFixNotInGoodStanding`.","tags":["ads"],"responses":{"202":{"description":"The fix.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsPageFix"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/page-fixes/{fix_id}/undo":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"fix_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"undoAdsPageFix","summary":"Put the snapshot back (za-210, one click, 30 days).","description":"Gated on `ads.manage`, audit-logged. Writes the whole original page back, byte-exact, only over the file exactly as the fix wrote it — a later edit is kept (`pageFixChangedSince`). 422 `pageFixCannotUndo` after 30 days or when not applied.","tags":["ads"],"responses":{"202":{"description":"The fix.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsPageFix"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/page-fixes/{fix_id}/discard":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"fix_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"discardAdsPageFix","summary":"Drop a fix never applied (za-210).","description":"Gated on `ads.manage`, audit-logged. Nothing was written to the site. 422 `pageFixState`.","tags":["ads"],"responses":{"200":{"description":"The fix.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsPageFix"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/stock-pause":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsStockPause","summary":"Out-of-stock pause — the settings and the connected WooCommerce shops (za-N2).","description":"Gated on `ads.view`. The connection's out-of-stock pause settings (each with our Recommended value and its bounds) and every connected shop with its products and what each holds paused. Read from our own rows — never a network call (docs/1006 §64b). The webhook secret is never in this response.","tags":["ads"],"responses":{"200":{"description":"The settings and the shops.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["settings","stores"],"properties":{"settings":{"$ref":"#/components/schemas/AdsStockPauseSettings"},"stores":{"type":"array","items":{"$ref":"#/components/schemas/AdsStockStore"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateAdsStockPause","summary":"Change the out-of-stock pause settings, or reset them to Recommended (za-N2).","description":"Gated on `ads.manage`, audit-logged with the before and after values. Every number is the customer's own (owner 2026-10-30); `reset: true` puts each back to our Recommended value. Switching `stock_pause_auto` off resumes every ad it is holding paused. `422 stockInvalid` for an unknown field or a value outside its bounds.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"stock_pause_auto":{"type":"boolean"},"stock_pause_hold_minutes":{"type":"integer","minimum":0,"maximum":10080},"stock_resume_hold_minutes":{"type":"integer","minimum":0,"maximum":10080},"reset":{"type":"boolean"}}}}}},"responses":{"200":{"description":"The stored settings.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["settings"],"properties":{"settings":{"$ref":"#/components/schemas/AdsStockPauseSettings"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/stock-pause/stores":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"createAdsStockStore","summary":"Connect a WooCommerce shop for the out-of-stock pause (za-N2).","description":"Gated on `ads.manage`, audit-logged. Returns the shop with OUR webhook URL and the secret to paste into WooCommerce → Settings → Advanced → Webhooks (topic \"Product updated\", API version WP REST API Integration v3). The secret is derived, never stored, and can be shown again with `…/secret`. `422 stockStoreUrl` for an address that is not a web address, `stockStoreExists` for a shop already connected.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["store_url"],"properties":{"store_url":{"type":"string","maxLength":2048},"label":{"type":"string","maxLength":80}}}}}},"responses":{"201":{"description":"Connected.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"allOf":[{"$ref":"#/components/schemas/AdsStockStore"},{"type":"object","required":["secret"],"properties":{"secret":{"type":"string"}}}]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/stock-pause/stores/{store_id}":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"store_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"operationId":"updateAdsStockStore","summary":"Switch a connected shop on or off, or rename it (za-N2).","description":"Gated on `ads.manage`, audit-logged. Switching a shop off resumes every ad it holds paused.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean"},"label":{"type":"string","maxLength":80}}}}}},"responses":{"200":{"description":"The shop.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsStockStore"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"deleteAdsStockStore","summary":"Disconnect a shop (za-N2).","description":"Gated on `ads.manage`, audit-logged. A shop still holding ads paused is switched off and its ads resumed first (`422 stockHolding`); remove it once no product shows Paused.","tags":["ads"],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/stock-pause/stores/{store_id}/secret":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"store_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"revealAdsStockStoreSecret","summary":"Show a shop's webhook secret again (za-N2).","description":"Gated on `ads.manage`, audit-logged. The secret is derived from the engine's key, the shop's id and its rotation generation, so it is the same value every time until the shop is rotated, and is never stored.","tags":["ads"],"responses":{"200":{"description":"The secret.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["secret"],"properties":{"secret":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/stock-pause/stores/{store_id}/secret/rotate":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"store_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"rotateAdsStockStoreSecret","summary":"Rotate a shop's webhook secret (OWNERFIX-C).","description":"Gated on `ads.manage`; audit action `ads.stock_store_secret_rotated` (the generation and the window end only, never a secret). Issues the next generation's secret and returns it; paste it into WooCommerce. The previous secret still verifies deliveries until `previous_valid_until` (24 hours), then stops; rotating again inside that window retires the older secret at once. Still derived, never stored.","tags":["ads"],"responses":{"200":{"description":"The new secret.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["secret","previous_valid_until"],"properties":{"secret":{"type":"string"},"previous_valid_until":{"type":"string","format":"date-time"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/stock-pause/products/{product_id}/sync":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"syncAdsStockProduct","summary":"Check now — reconcile one product's ads to its stock (za-N2).","description":"Gated on `ads.manage`; audit action `ads.stock_product_check` (`started`, OWNERFIX-D). Starts the product's Temporal workflow, which waits out any hold still running and then pauses or resumes its ads to match its current stock.","tags":["ads"],"responses":{"202":{"description":"Started (`started` false when Temporal could not be reached).","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["started"],"properties":{"started":{"type":"boolean"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/webhooks/ads-stock/{store_id}":{"parameters":[{"name":"store_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"receiveAdsStockWebhook","summary":"A WooCommerce \"Product updated\" delivery for the out-of-stock pause (za-N2).","description":"Unauthenticated: WooCommerce's `X-WC-Webhook-Signature` (base64 HMAC-SHA256 of the raw body) is the authentication, verified with the shop's derived secret before the body is read. A product whose `stock_status` flips to `outofstock` starts its pause after the customer's hold; back to `instock` or `onbackorder` starts its resume. A product link on another host, a body without stock, or an unchanged stock answers 200 and does nothing; a signed body whose `date_modified_gmt` is older than the newest already seen for the product is a replay and answers 200 (`stale`) without changing anything. WooCommerce's unsigned set-up ping (`webhook_id=N`) answers 200 and writes nothing; nor does a refused signature. `404` unknown or switched-off shop, `400` missing or bad signature, `413` body over 1 MB, `503` the engine key is unavailable (retry).","tags":["ads"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Handled.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["note"],"properties":{"note":{"type":"string","enum":["ping","changed","same","otherHost","noStock","notJson"]}}}}}}}},"400":{"description":"The signature is missing or did not verify.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsCheckoutWebhookError"}}}},"404":{"description":"No such shop, or it is switched off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsCheckoutWebhookError"}}}},"413":{"description":"The body is over 1 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsCheckoutWebhookError"}}}},"503":{"description":"The engine key could not be read; WooCommerce retries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsCheckoutWebhookError"}}}}}}},"/v1/ads/connections/{connection_id}/brand-watch":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsBrandWatch","summary":"Competitor watch — who started bidding on this account's brand terms (za-N9).","description":"Gated on `ads.view`. The watch's settings (each threshold beside its Recommended value and bounds), the last daily check, and every competitor seen bidding on the brand keywords, newest first (`new` = not yet marked seen). Read from our own rows — never a network call; the reading runs in the connection's daily audit on Temporal (docs/1006 §80). A read never writes: an account never edited answers with the Recommended values.","tags":["ads"],"responses":{"200":{"description":"The watch.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsBrandWatch"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateAdsBrandWatch","summary":"Edit the competitor watch — switch, thresholds, extra brand terms (za-N9).","description":"Gated on `ads.manage`; audit action `ads.brand_watch_update`. Every threshold is the customer's: a whole number inside its bounds, or `null` to reset it to Recommended. `terms` replaces the extra brand terms (lower-cased, de-duplicated; the build plan's brand is always watched). `422 brandWatchInvalid` names the field (unknown fields are refused).","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean"},"min_share_pct":{"type":["integer","null"],"minimum":1,"maximum":100},"top_floor_pct":{"type":["integer","null"],"minimum":1,"maximum":100},"rank_lost_pct":{"type":["integer","null"],"minimum":1,"maximum":100},"min_impressions":{"type":["integer","null"],"minimum":1,"maximum":1000000},"terms":{"type":"array","maxItems":50,"items":{"type":"string","maxLength":80}}}}}}},"responses":{"200":{"description":"The watch, as saved.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsBrandWatch"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/brand-watch/seen":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"markAdsBrandWatchSeen","summary":"Mark every new competitor alert on this account as seen (za-N9).","description":"Gated on `ads.manage`. The dashboard's \"Got it\": each alert is shown as new once; a bidder already seen is never alerted again (docs/1006 §80).","tags":["ads"],"responses":{"200":{"description":"The watch, with no new alerts.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsBrandWatch"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/rules":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsRules","summary":"The account's own rules — \"if a figure over a window then an action\" (za-196).","description":"Gated on `ads.view`. Every rule of the connection (newest first) with its last run, and the closed sets a rule is built from (`catalogue`: metrics with their unit, windows, comparators, actions, the percentage and cooldown bounds) so a builder offers only what the engine accepts. Read from our own rows — never a network call (docs/1006 §46).","tags":["ads"],"responses":{"200":{"description":"The rules and the catalogue.","content":{"application/json":{"schema":{"type":"object","required":["data","catalogue"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsRule"}},"catalogue":{"$ref":"#/components/schemas/AdsRuleCatalogue"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createAdsRule","summary":"Create a rule; it runs on its own daily Temporal schedule (za-196).","description":"Gated on `ads.manage`; audit action `ads.rule_create`. Only the closed sets of the catalogue are accepted — no expression, formula or code (`422 badRule`, `details[0].field` names the field). Money thresholds are integer minor units of the account's currency (§2.8). A rule's write goes through the approve-first change queue and every guard a write passes (kill switches, good standing, the spend ceilings, owner-locked campaigns, the 14-day bid-strategy freeze, the ad-quality gate) and keeps its 30-day Undo. `mode: approve` (the default) queues each change for a person; `auto` sends it (a plan without autopilot still queues it). A rule that acted on a campaign does not act on it again inside `cooldown_days`. Google accounts only (`422 rulesGoogleOnly`).","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AdsRuleSpec"},{"type":"object","required":["name","metric","window_days","comparator","threshold","action"],"properties":{"name":{"type":"string"},"metric":{"type":"string","enum":["cost","cost_without_conversions","clicks","impressions","conversions","cpa","ctr","conversion_rate","roas"]},"window_days":{"type":"integer","enum":[1,3,7,14,30]},"comparator":{"type":"string","enum":["gt","gte","lt","lte"]},"threshold":{"type":"integer"},"action":{"type":"string","enum":["notify","pause_campaign","budget_down","budget_up"]}}}]}}}},"responses":{"201":{"description":"Created, with its schedule.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsRule"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/experiments":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsExperiments","summary":"The account's dated budget tests (za-193).","description":"Gated on `ads.view`. Every budget test of the connection, newest first: its state (`awaiting_approval`, `starting`, `running`, `ended`, `failed`, or the change's own status once rejected or undone), the campaigns with their budget before and during the test, the step in percent, the days, its change and — once applied — its dated review with the verdict and the keep / revert / extend offer. `supported` is false for a network other than Google Ads; `campaigns` are the campaigns with stored figures a new test can cover. Read from our own rows — never a network call (docs/1006 §69). The same rows answer the MCP tool `ads_experiment_read`.","tags":["ads"],"responses":{"200":{"description":"The tests.","content":{"application/json":{"schema":{"type":"object","required":["supported","data","campaigns"],"properties":{"supported":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsExperiment"}},"campaigns":{"type":"array","items":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"startAdsExperiment","summary":"Start a dated budget test — kept as ONE change waiting for approval (za-193).","description":"Gated on `ads.manage`. Reads the chosen campaigns' budgets from Google now (one read, the caller waits for it) and keeps the new budgets as ONE pending change in the approval queue, `summary.auto_action = \"experiment\"`. Nothing reaches Google until a person approves it; the kill switches, spend ceilings and the organisation's standing still decide at send time, and an applied test keeps its 30-day Undo, which puts every budget back. The measured window starts the day it is applied; its own Temporal workflow judges it on the end day. Refusals: `422 experimentBadRequest` (outside the closed ranges), `422 experimentBusy` (a campaign on a shared budget, or already in a waiting or running test), `422 experimentGoogleOnly`, `422 needsReconnect`. The MCP tool `ads_experiment_create` takes this same path.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsExperimentSpec"}}}},"responses":{"201":{"description":"Kept, waiting for approval.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsExperiment"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/reviews":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsReviews","summary":"The account's scheduled reviews, and what a new one can cover (AUTOREVIEW1).","description":"Gated on `ads.view`. Every scheduled review of the connection (latest due first, at most 300): what it judges, its due day, its status (`scheduled`, `due`, `decided`, `cancelled`) and, once due, the measured verdict and the recommended decision. `campaigns` are the campaigns with stored figures in the last 30 days and `changes` the changes applied in the last 30 days, which a new review can cover. Read from our own rows — never a network call; the verdict is written by the review's own Temporal workflow on its due day (docs/1006 §54).","tags":["ads"],"responses":{"200":{"description":"The reviews and what to pick from.","content":{"application/json":{"schema":{"type":"object","required":["data","campaigns","changes"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsReview"}},"campaigns":{"type":"array","items":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}}},"changes":{"type":"array","items":{"type":"object","required":["id","applied_at","action_class","label"],"properties":{"id":{"type":"string","format":"uuid"},"applied_at":{"type":"string","format":"date-time","nullable":true},"action_class":{"type":"string"},"label":{"type":"string"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createAdsReview","summary":"Schedule a review; its own Temporal workflow judges it on the due day (AUTOREVIEW1).","description":"Gated on `ads.manage`; audit action `ads.review_create`. Closed sets only: `subject` (`results`, `change`, `experiment`, `quality`, `funnel`), `options` (`keep`, `pause`, `revert`, `extend`; default per subject). The due day is `due_on` or `days` from today (after today, within a year); `measure_from` (default today) starts the judged window, and the same number of days before it is the baseline. A `change` review names the applied change (`change_id`) whose Undo is its `revert`. Pause and Quality Score reviews are Google only (`422 reviewPauseGoogleOnly`, `reviewQualityGoogleOnly`). Creating a review changes nothing in the ad account.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsReviewSpec"}}}},"responses":{"201":{"description":"Scheduled.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsReview"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/reviews/{review_id}":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"review_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"delete":{"operationId":"cancelAdsReview","summary":"Cancel a scheduled or due review (AUTOREVIEW1).","description":"Gated on `ads.manage`; audit action `ads.review_cancel`. A decided or cancelled review is refused (`422 reviewNotOpen`).","tags":["ads"],"responses":{"204":{"description":"Cancelled."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/reviews/{review_id}/decide":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"review_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"decideAdsReview","summary":"The one-click decision on a due review (AUTOREVIEW1).","description":"Gated on `ads.manage`; audit action `ads.review_decide`. `keep` records it; `extend` moves the due day 7 days on and schedules it again; `pause` pauses its campaigns (for a funnel review, the campaigns that spent with no result), each through the approve-first queue as a person's approved change with its 30-day Undo; `revert` starts the reviewed change's Undo. A dated campaign's `ending` review (MS-WP60, made only by the engine, never through this API) offers `extend30` / `extend60` / `extend90`: the campaign's end date moves that many days later on the ad platform, as the clicker's approved change with its Undo, and the review is due again 7 days before the new end. Refused when the option is not offered (`reviewOptionNotOffered`) or the review is not due (`reviewNotDue`).","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsReviewDecision"}}}},"responses":{"200":{"description":"Decided.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsReview"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/reviews/{review_id}/undo":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"review_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"undoAdsReviewDecision","summary":"Put a review's decision back and open the review again (AUTOREVIEW1).","description":"Gated on `ads.manage`; audit action `ads.review_undo`. Within 30 days: a pause's changes are undone, a revert is applied again as a new change (with its own Undo), an extension gets its old due day back (until it is judged again). Otherwise `422 reviewNothingToUndo`.","tags":["ads"],"responses":{"200":{"description":"The review, due again.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsReview"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/webhooks":{"get":{"operationId":"listAdsWebhooks","summary":"The org's webhook endpoints and the Zinn® Ads events each one receives (za-192).","description":"Gated on `ads.view`. Lists every organisation-level webhook notification connection (created at `POST /v1/notification-connections` with `kind: webhook`: HTTPS only, a signing secret we mint, verified by a real test POST) with the Zinn® Ads events it is subscribed to. The event shapes are this spec's top-level `webhooks` section (`ads.finding.opened`, `ads.change.applied`, `ads.alert.started`). Every delivery is signed `X-Zinn-Signature: sha256=<hmac-sha256 over \"<X-Zinn-Timestamp>.<raw body>\">`, carries `X-Zinn-Delivery` (dedupe on it) and `X-Zinn-Event`, is retried 1, 5, 25, 125 and 625 minutes after a failure and appears in `GET /v1/notification-connections/{id}/deliveries`. Read from our own rows (docs/1006 §70).","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The endpoints.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsWebhooks"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/webhooks/{connection_id}":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"put":{"operationId":"setAdsWebhookEvents","summary":"Choose which Zinn® Ads events a webhook endpoint receives (za-192).","description":"Gated on `ads.manage`; audit action `ads.webhook_events`. `events` is a subset of `ads.finding.opened`, `ads.change.applied` and `ads.alert.started` (an empty list turns Zinn® Ads events off for the endpoint; anything else is a `422` `refusal.adsconnect.webhookBadEvent`, FIX-REFUSED). `404` when the connection is not one of this organisation's webhook connections. Nothing is sent to an endpoint until it is verified.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["events"],"properties":{"org_id":{"type":"string","format":"uuid"},"events":{"type":"array","items":{"$ref":"#/components/schemas/AdsWebhookEventName"}}}}}}},"responses":{"200":{"description":"Saved.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsWebhookEndpoint"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/webhooks/{connection_id}/test":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"testAdsWebhook","summary":"Send one signed example of a Zinn® Ads event to a webhook endpoint (za-192).","description":"Gated on `ads.manage`; audit action `ads.webhook_test`. Queues one example `event` (marked `\"test\": true`, ids all zero) to the endpoint; the delivery sweep sends it within a minute, signed exactly like a real event, and it appears in the endpoint's delivery log. A `422` `refusal.adsconnect.webhookBadEvent` for an unknown event and `refusal.adsconnect.webhookNotVerified` for an endpoint not verified yet (FIX-REFUSED).","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["event"],"properties":{"org_id":{"type":"string","format":"uuid"},"event":{"$ref":"#/components/schemas/AdsWebhookEventName"}}}}}},"responses":{"202":{"description":"Queued.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["delivery_id","event"],"properties":{"delivery_id":{"type":"string","format":"uuid"},"event":{"$ref":"#/components/schemas/AdsWebhookEventName"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/grow":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsGrowPlan","summary":"The account's operating plan — this week's \"Suggestions to grow\" and the calendar (za-85).","description":"Gated on `ads.view`. The week's 3 to 5 ideas for the account, best evidence first — `scale_test` (a campaign earning at least the account's ROAS target over 14 days and losing at least 20% of its impressions to budget: +50% budget for 14 days, money in integer micros with its ISO currency), `country` (converts without its own campaign), `competitor` (a new brand on searches naming it) and `experiment` (a 50/50 landing-page test) — and the next 21 days' calendar (seasonal peaks, the monthly ad-copy refresh, the quarterly structure review and the account's scheduled reviews due in the next 7 days). Read from our own rows — never a network call; the suggestions are written once a week by the `zinn-ads-grow` Temporal schedule (docs/1006 §60). Nothing here changes the ad account.","tags":["ads"],"responses":{"200":{"description":"The plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsGrowPlan"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/grow/{suggestion_id}/decide":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"suggestion_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"decideAdsGrowSuggestion","summary":"Mark a suggestion done or dismissed, or open again (za-85).","description":"Gated on `ads.manage`; audit action `ads.grow_decide`. `decision` is `done`, `dismissed` or `open` (`422 suggestionBadDecision` otherwise). A note for the people on the account: it changes nothing in the ad account.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["decision"],"properties":{"decision":{"type":"string","enum":["done","dismissed","open"]}}}}}},"responses":{"200":{"description":"Marked.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsGrowSuggestion"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/budget-decisions":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsBudgetDecisions","summary":"The customer's own budget decisions on this Google Ads account (za-84).","description":"Gated on `ads.view`. Every decision in force (`active`, or `awaiting` — a dated test past its end date waiting for the customer's answer), dated ahead (`pending`), or ended in the last 30 days. Each carries the amount a day and the amount before (integer micros of the account's currency, `currency`), the customer's reason verbatim, who decided and when, the figures since it started against the same number of days before it, `live_micros` (the budget the latest audit saw) with `drifted` when it no longer matches (changed outside — reported, never changed back), and `held_back` (how many automatic budget changes the decision refused). Our own rows only — never a network call (docs/1006 §84).","tags":["ads"],"responses":{"200":{"description":"The decisions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsBudgetDecisionList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"recordAdsBudgetDecision","summary":"Record the customer's own budget for one campaign (za-84).","description":"Gated on `ads.manage`; audit action `ads.own_budget_record`. The campaign is read from Google Ads now: it must exist and have a budget of its own. `kind` `budget` stays until the customer changes it (no `ends_on`); `test` runs 7 to 90 days and on `ends_on` becomes ONE question (keep, or go back) — the amount stays until answered. Starting today (default), an earlier decision on the campaign ends and, when Google does not already hold the amount, the budget change is proposed and approved together (recording it is the approval) and sent by the apply workflow through the account's gate (kill switches, good standing, spend ceilings); `change` is that change. Dated up to 90 days ahead (`starts_on`), nothing is written until its day. While in force no automatic budget change moves the campaign. Refusals (`422`): `ownBudgetGoogleOnly`, `ownBudgetBadRequest`, `ownBudgetNoSuchCampaign`, `ownBudgetShared`, `ownBudgetReadFailed`; `decisionPinned` / `decisionHeld` when the campaign is pinned or held and the caller is not a person (an API key or an MCP connection): only a signed-in person's decision moves such a campaign, and nothing is recorded (GATE-PERSON).","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["campaign_id","budget_micros","kind","reason"],"properties":{"campaign_id":{"type":"string","pattern":"^[0-9]{1,20}$"},"budget_micros":{"type":"integer","format":"int64","minimum":1},"kind":{"type":"string","enum":["budget","test"]},"reason":{"type":"string","maxLength":500},"starts_on":{"type":["string","null"],"format":"date"},"ends_on":{"type":["string","null"],"format":"date"}}}}}},"responses":{"201":{"description":"Recorded.","content":{"application/json":{"schema":{"type":"object","required":["data","change"],"properties":{"data":{"$ref":"#/components/schemas/AdsBudgetDecision"},"change":{"oneOf":[{"$ref":"#/components/schemas/AdsChange"},{"type":"null"}]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/budget-decisions/{key}/settle":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"key","in":"path","required":true,"schema":{"type":"string","maxLength":60}}],"post":{"operationId":"settleAdsBudgetDecision","summary":"Answer or end one of the customer's budget decisions (za-84).","description":"Gated on `ads.manage`; audit action `ads.own_budget_settle`. `answer` `keep` — the amount stays; `revert` — back to the amount before the decision (proposed and approved together, sent by the apply workflow; `change` is it). Either way the decision ends, its question closes, and the autopilot may look after the budget again. Refusals (`422`): `ownBudgetBadAnswer`, `ownBudgetNotOpen`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["answer"],"properties":{"answer":{"type":"string","enum":["keep","revert"]}}}}}},"responses":{"200":{"description":"Answered.","content":{"application/json":{"schema":{"type":"object","required":["data","change"],"properties":{"data":{"$ref":"#/components/schemas/AdsBudgetDecision"},"change":{"oneOf":[{"$ref":"#/components/schemas/AdsChange"},{"type":"null"}]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/rules/preview":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"previewAdsRule","summary":"What a rule WOULD have done on the account's last N days of real figures (za-196).","description":"Gated on `ads.view`; writes nothing anywhere. The rule (saved or not) is replayed day by day over the last `days` (1-90, default 30) of the figures the daily audit stored for the account: on each day the metric is read over the window ending that day, the condition tested, and the cooldown and a simulated pause honoured exactly as a scheduled run would. `firings` lists each day and campaign it would have acted on with the reading. Campaigns the owner locked, or learning after a bid-strategy switch, are listed in `held`. `stale: true` when the stored figures are older than two days (the preview then says so instead of claiming nothing would have happened).","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AdsRuleSpec"},{"type":"object","required":["name","metric","window_days","comparator","threshold","action"],"properties":{"name":{"type":"string"},"metric":{"type":"string","enum":["cost","cost_without_conversions","clicks","impressions","conversions","cpa","ctr","conversion_rate","roas"]},"window_days":{"type":"integer","enum":[1,3,7,14,30]},"comparator":{"type":"string","enum":["gt","gte","lt","lte"]},"threshold":{"type":"integer"},"action":{"type":"string","enum":["notify","pause_campaign","budget_down","budget_up"]},"days":{"type":"integer","minimum":1,"maximum":90,"description":"Default 30."}}}]}}}},"responses":{"200":{"description":"The replay.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsRulePreview"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/rules/{rule_id}":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"rule_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"operationId":"updateAdsRule","summary":"Change a rule, or switch it on or off (za-196).","description":"Gated on `ads.manage`; audit action `ads.rule_update`. Any field of the spec, validated as on create; `enabled: false` pauses its schedule (nothing runs), `true` resumes it. The cooldown history is kept, so editing a rule never makes it re-act on a campaign it just changed.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsRuleSpec"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsRule"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"deleteAdsRule","summary":"Delete a rule and its schedule (za-196).","description":"Gated on `ads.manage`; audit action `ads.rule_delete`. The rule stops and its schedule is removed; its run log and the changes it made stay, each with its own 30-day Undo.","tags":["ads"],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/rules/{rule_id}/runs":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"rule_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsRuleRuns","summary":"A rule's run log — every run, what it read and what it did (za-196).","description":"Gated on `ads.view`. Newest first, the last 90 days. Each run says how many campaigns it checked and, for every campaign that met the condition, the reading and the outcome: `applied` / `queued` (waiting for approval) / `refused` (a guard said no — `reason` is its code) / `cooldown` / `ownerLocked` / `learning` / `notified` / `failed`, with the change id to approve or undo.","tags":["ads"],"responses":{"200":{"description":"The runs.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsRuleRun"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/rules/{rule_id}/runs/{run_id}/undo":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"rule_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"undoAdsRuleRun","summary":"Undo every change one run made, within 30 days (za-196).","description":"Gated on `ads.manage`; audit action `ads.rule_undo_run`. Each applied change of the run that can still be undone (30 days) is put back by the undo workflow; `count` is how many were started. `422 nothingToUndo` when none can.","tags":["ads"],"responses":{"202":{"description":"The undos were started.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["count","change_ids"],"properties":{"count":{"type":"integer"},"change_ids":{"type":"array","items":{"type":"string","format":"uuid"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/ads":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsAccountAds","summary":"The account's campaigns, ad groups and ads, read from Google now (ADMGMT1).","description":"Gated on `ads.view`. Everything not removed, every page (three Google Ads reads, counted on the connection's op meter). `?status=paused` lists only the paused ads — the preview of \"Delete all paused ads\". A Microsoft Advertising account is refused with `422 msAdManageNotOffered` (words that name Microsoft); a disconnected one `422 disconnected`; a connection whose access ended `422 needsReconnect`.","tags":["ads"],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["paused"]}}],"responses":{"200":{"description":"The account's structure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsAccountAds"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/ads/actions":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"actOnAdsAccountAd","summary":"Pause, unpause or delete one ad, ad group or campaign (ADMGMT1).","description":"Gated on `ads.manage`; audit action `ads.ad_action`. The status is read from Google first; the change is proposed and approved in one step (the request is the approval) and the apply workflow sends it through the same gate as every write (kill switches, the organisation's standing). Pause and unpause carry the 30-day Undo. Delete is for a PAUSED ad or ad group only (`422 notPausedYet`; never a campaign, `422 badAction`): a snapshot is saved (headlines, descriptions, paths, final URLs; for an ad group its name, bid, ads and keywords) and the change's Undo is a Rebuild that creates a NEW paused copy from it — a deleted ad itself cannot be brought back. `422 alreadyThatStatus`, `422 noSuchAd`, `422 killed` / `paused`, `422 msAdManageNotOffered`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsAdActionRequest"}}}},"responses":{"202":{"description":"Approved; the apply workflow sends it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsChange"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/paused-ads/delete":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"deleteAdsAccountPausedAds","summary":"Delete all paused ads of one account (ADMGMT1).","description":"Gated on `ads.manage`; audit action `ads.paused_ads_delete` (metadata `count`, `started`). Reads the paused ads now and makes one approved delete per ad (narrowed to `resources` when given — the list the person saw in the preview; an ad no longer paused is left alone), each with its snapshot and Rebuild; ONE workflow sends them all. `503` when the workflow could not be started (the changes stay approved).","tags":["ads"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"resources":{"type":"array","maxItems":10000,"items":{"type":"string","maxLength":128}}}}}}},"responses":{"202":{"description":"The deletes, approved and being sent.","content":{"application/json":{"schema":{"type":"object","required":["connection_id","count","started","changes"],"properties":{"connection_id":{"type":"string","format":"uuid"},"count":{"type":"integer"},"started":{"type":"boolean"},"changes":{"type":"array","items":{"$ref":"#/components/schemas/AdsChange"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/ads/connections/{connection_id}/audits":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsConnectionAudits","summary":"The connection's recent audit runs (newest first, at most 20).","description":"Gated on `ads.view`. Counts only: `summary.proposed` changes waiting for approval, `summary.applied` sent on autopilot, `summary.found` per kind (negative, keyword, pause). A run that could not read the account carries `summary.failure` (a `VendorFailure`: the customer's own network named, with its status or billing page).","tags":["ads"],"responses":{"200":{"description":"The runs.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsAuditRun"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"runAdsConnectionAudit","summary":"Run the connection's audit now (a Temporal workflow).","description":"Gated on `ads.manage`; audit action `ads.audit_run`. Starts the same per-connection workflow the daily fan-out runs; twice in one minute is one run. Every change it finds is sent through the approve-first queue (nothing is applied unless that class is `auto`). `503` when the workflow could not be started. The networks covered are exactly the daily audit's (`ads_networks.audited()`: Google, Microsoft, X, Amazon and ChatGPT, AMZAUDITNOW); a connection on a network the audit does not cover is a `422` `refusal.adsconnect.auditNotOnNetwork` (FIX13).","tags":["ads"],"responses":{"202":{"description":"Started.","content":{"application/json":{"schema":{"type":"object","required":["connection_id","started"],"properties":{"connection_id":{"type":"string","format":"uuid"},"started":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"description":"The workflow could not be started.","content":{"application/json":{"schema":{"type":"object","required":["connection_id","started"],"properties":{"connection_id":{"type":"string","format":"uuid"},"started":{"type":"boolean"}}}}}}}}},"/v1/ads/connections/{connection_id}/microsoft/import-google":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"previewAdsMicrosoftImportGoogle","summary":"What importing the org's Google Ads Search campaigns into this Microsoft account would queue (za-39).","description":"Gated on `ads.view`. `connection_id` is a Microsoft Advertising connection, `google_connection_id` a Google Ads connection of the same org (else `422` `refusal.adsconnect.importNotOnNetwork`; different currencies `importCurrency`; an account whose currency is unknown `importCurrencyUnknown`; a failed read `importReadFailed`, whose `error.failure` is the classified `VendorFailure` of the network that failed: an outage, the customer's own credential, or ours, §2.57). Reads both networks, writes nothing. Each enabled Google campaign is listed: a Search campaign is `ready` or says why it cannot be copied, any other type (Performance Max, Display, Shopping, Video) is `notSearch`; a name already live in Microsoft or already imported is `alreadyThere`; a campaign with no daily budget (a Google total budget) is `noDailyBudget`, never `ready` (docs/1006 §103).","tags":["ads"],"parameters":[{"name":"google_connection_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"max_cpc_micros","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":10000,"maximum":1000000000},"description":"Max CPC for campaigns Google gives none."}],"responses":{"200":{"description":"The preview.","content":{"application/json":{"schema":{"type":"object","required":["connection_id","google_connection_id","currency","data"],"properties":{"connection_id":{"type":"string","format":"uuid"},"google_connection_id":{"type":"string","format":"uuid"},"currency":{"type":"string"},"data":{"type":"array","items":{"type":"object","required":["google_campaign_id","name","state","daily_budget_micros","max_cpc_micros","ad_groups","keywords","negatives","dropped_targets","change_id"],"properties":{"google_campaign_id":{"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ready","queued","alreadyThere","notSearch","noMicrosoftLocation","noMicrosoftLanguage","noAdGroups","needsMaxCpc","noDailyBudget"]},"daily_budget_micros":{"type":"integer","format":"int64","description":"Account currency micros; a shared Google budget split between its campaigns."},"max_cpc_micros":{"type":"integer","format":"int64"},"ad_groups":{"type":"integer"},"keywords":{"type":"integer"},"negatives":{"type":"integer"},"dropped_targets":{"type":"integer","description":"Google location targets with no Microsoft equivalent (regions, cities)."},"change_id":{"type":["string","null"],"format":"uuid","description":"The pending Microsoft change (after POST)."}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"queueAdsMicrosoftImportGoogle","summary":"Queue the ready Google Ads Search campaigns as pending Microsoft changes (za-39).","description":"Gated on `ads.manage`; audit action `ads.microsoft_import_google`. Each `ready` campaign (or only `campaign_ids`) becomes ONE pending `campaigns:mutate` `build` change on the Microsoft connection — nothing is sent until a person approves it, and the kill switch, good standing and spend ceiling are checked again when it is applied. A month of the imported daily budgets is checked against the Zinn® Ads plan first (`noAdsPlan`, `spendBracket`). Nothing left to queue is `422` `refusal.adsconnect.importNothing`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["google_connection_id"],"properties":{"google_connection_id":{"type":"string","format":"uuid"},"campaign_ids":{"type":"array","maxItems":1000,"items":{"type":"string","pattern":"^\\d{1,20}$"}},"max_cpc_micros":{"type":"integer","format":"int64","minimum":10000,"maximum":1000000000}}}}}},"responses":{"201":{"description":"Queued.","content":{"application/json":{"schema":{"type":"object","required":["connection_id","google_connection_id","currency","data"],"properties":{"connection_id":{"type":"string","format":"uuid"},"google_connection_id":{"type":"string","format":"uuid"},"currency":{"type":"string"},"data":{"type":"array","items":{"type":"object","required":["google_campaign_id","name","state","daily_budget_micros","max_cpc_micros","ad_groups","keywords","negatives","dropped_targets","change_id"],"properties":{"google_campaign_id":{"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["ready","queued","alreadyThere","notSearch","noMicrosoftLocation","noMicrosoftLanguage","noAdGroups","needsMaxCpc","noDailyBudget"]},"daily_budget_micros":{"type":"integer","format":"int64","description":"Account currency micros; a shared Google budget split between its campaigns."},"max_cpc_micros":{"type":"integer","format":"int64"},"ad_groups":{"type":"integer"},"keywords":{"type":"integer"},"negatives":{"type":"integer"},"dropped_targets":{"type":"integer","description":"Google location targets with no Microsoft equivalent (regions, cities)."},"change_id":{"type":["string","null"],"format":"uuid","description":"The pending Microsoft change (after POST)."}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/tracking":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsTracking","summary":"The account's tracking truth check, confidence gate, fix assistant and recovery.","description":"Gated on `ads.view`. Real outcomes from the customer's own source (the events API below, a connected store, plugin or CRM) against what the network credited over the settled days (`thresholds.days`, the newest `thresholds.processing_days` excluded). `latest.status` `gap` (more than `thresholds.gap_pct` apart, either direction) or `unreadable` (the network's count could not be read — never a pass) sets `hold`: the autopilot judges, cuts and pauses nothing on the network's counts until a check says `ok` again. `latest.diagnoses` are the fix assistant's findings as codes + figures (the dashboard words them). `latest.recovered` / `credited_after` are the before/after of the missed- conversion recovery. `fix_offer` is the paid \"Fix it for me\" add-on priced from the catalogue, or null when it is not offered. A ChatGPT Ads account (za-320) is checked too: its credits are read through OpenAI's `POST /conversions/insights` (goal conversions by conversion date; a too-big answer is split by date range, never capped), and as it takes no upload from us its `latest.recovery.refused` is `uploadNotSupported`. Every other network is a `422` `refusal.adsconnect.platformNotSupported` (FIX-189); ChatGPT Ads also gets that `422` from the upload-side routes (profit values, conversion setup, CRM, product and checkout sources). Its `refusal.params.networks` names the networks the refusing route serves (registry labels, comma-joined: \"Google Ads, Microsoft Advertising\" on an upload route, plus \"ChatGPT Ads\" on a truth-check route).","tags":["ads"],"responses":{"200":{"description":"The tracking state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsTracking"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"updateAdsTracking","summary":"Which actions are compared, where missed outcomes upload, recovery on/off.","description":"Gated on `ads.manage`; audit action `ads.tracking_settings`. A Google action is a resource name of THIS account (`customers/<id>/conversionActions/<id>`); a Microsoft one is the offline goal's name; a ChatGPT Ads one is a conversion event setting id (`ces_…`, `GET /tracking/actions`). Giving a kind an upload action re-opens its outcomes that were waiting for one. `recovery_mode` `validate` makes the network check uploads and keep nothing.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsTrackingSettings"}}}},"responses":{"200":{"description":"Saved; the tracking state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsTracking"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/tracking/check":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"runAdsTrackingCheck","summary":"Run the tracking check and the recovery upload now (a Temporal workflow).","description":"Gated on `ads.manage`; audit action `ads.tracking_check`. The same step the daily per-connection job runs before every audit; twice in one minute is one run. `recovery_mode: validate` checks the upload at the network and keeps nothing (a network with no validate-only mode is checked locally and sent nothing). `503` when the workflow could not be started.","tags":["ads"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"recovery_mode":{"type":"string","enum":["","validate"]}}}}}},"responses":{"202":{"description":"Started.","content":{"application/json":{"schema":{"type":"object","required":["connection_id","started"],"properties":{"connection_id":{"type":"string","format":"uuid"},"started":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"description":"The workflow could not be started.","content":{"application/json":{"schema":{"type":"object","required":["connection_id","started"],"properties":{"connection_id":{"type":"string","format":"uuid"},"started":{"type":"boolean"}}}}}}}}},"/v1/ads/connections/{connection_id}/tracking/retry":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"retryAdsTrackingGivenUp","summary":"Send the uploads Google never gave a verdict on again (a person's retry).","description":"Gated on `ads.manage`; audit action `ads.tracking_retry`. Google accepted these uploads and no verdict was read within 3 days, so nothing more is sent automatically (`AdsTracking.given_up`). Each goes back to pending ONCE and the tracking check starts, which sends them the normal way (good standing is checked at the send; a refusal waits the normal back-off). Idempotent: a second call finds none given up and re-queues nothing (`requeued: 0`, `started: false`). A refunded upload, or one past the network's upload window, is never sent again; a refund of a re-queued one is still a retraction (Google may have recorded the original).","tags":["ads"],"responses":{"200":{"description":"The given-up uploads were re-queued (or none were left).","content":{"application/json":{"schema":{"type":"object","required":["connection_id","requeued","started","given_up"],"properties":{"connection_id":{"type":"string","format":"uuid"},"requeued":{"type":"integer","description":"Uploads put back to pending by this call."},"started":{"type":"boolean","description":"The tracking check workflow started."},"given_up":{"type":"integer","description":"Uploads still given up after this call."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/tracking/actions":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsTrackingActions","summary":"The account's offline-upload conversion actions, read live from the network.","description":"Gated on `ads.view`. One read at the network. A read that failed returns an empty list with `failure` (a `VendorFailure`: the customer's own network named, its status page).","tags":["ads"],"responses":{"200":{"description":"The actions.","content":{"application/json":{"schema":{"type":"object","required":["data","failure","needs_reconnect"],"properties":{"needs_reconnect":{"type":"boolean","description":"No token for this account (never connected or lost) — nothing was read."},"data":{"type":"array","items":{"type":"object","required":["resource","name","status","primary"],"properties":{"resource":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"primary":{"type":"boolean"}}}},"failure":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/VendorFailure"}]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/rsa-tests":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsRsaTests","summary":"RSA A/B tests — variants rotated, winners called at the customer's confidence (za-197).","description":"Gated on `ads.view`. Reads only Zinn® Ads' own rows (no network request, nothing spent). The tests themselves run in the connection's daily audit: an ad group with two enabled responsive search ads is rotated evenly through the `campaigns` mode, measured from the day rotation is even, and a winner is called only when both variants have the minimum impressions and clicks, the minimum days have passed and a two-sided two-proportion test is below 1 - confidence. The swap (pause the loser, add a new challenger built from the winner without its weakest assets) goes through the `ads` mode and the za-171 gate. `settings` are the connection's stored values, `recommended` what \"Reset to recommended\" restores; edit them with `PATCH /v1/ads/connections/{connection_id}`.","tags":["ads"],"responses":{"200":{"description":"The connection's tests, open ones first.","content":{"application/json":{"schema":{"type":"object","required":["supported","platform","settings","recommended","tests"],"properties":{"supported":{"type":"boolean"},"platform":{"type":"string"},"settings":{"$ref":"#/components/schemas/AdsRsaTestSettings"},"recommended":{"$ref":"#/components/schemas/AdsRsaTestSettings"},"tests":{"type":"array","items":{"$ref":"#/components/schemas/AdsRsaTest"}}}}}}},"404":{"description":"Not one of the caller's connections."}}}},"/v1/ads/connections/{connection_id}/conversion-setup":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsConversionSetup","summary":"Conversion setup — GA4 key-event import or the server-side upload, each measured (za-12).","description":"Gated on `ads.view`. Reads the account live (every conversion action, the upload actions and, for the chosen GA4 key events, the conversions credited over the last `quiet_days`) and spends nothing. `ga4` (Google only; `{}` on Microsoft) lists the key events of every GA4 property linked to the ad account — Google shows one not yet imported as `HIDDEN`. `server` says whether the upload action exists, which outcome kinds use it and how many real outcomes arrived and were uploaded in the window. Each step carries a measured `state`. `quiet_days` is the customer's own window; `recommended_quiet_days` our default. A read that failed leaves the steps `unreadable` with `failure` (a `VendorFailure`).","tags":["ads"],"responses":{"200":{"description":"The setup.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsConversionSetup"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setAdsConversionSetup","summary":"Choose the conversion method, the GA4 property and key events, and the working window.","description":"Gated on `ads.manage`; audit-logged (`ads.conversion_setup_saved`). Nothing is sent to the network. `quiet_days` outside 1..90 is refused (422), never clamped. `ga4` on a Microsoft account is refused (`convGa4GoogleOnly`).","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"conversion_method":{"type":"string","enum":["","ga4","server"]},"ga4_property_id":{"type":"string","pattern":"^[0-9]{0,20}$"},"ga4_key_events":{"type":"array","maxItems":30,"items":{"type":"string","pattern":"^[A-Za-z][A-Za-z0-9_]{0,39}$"}},"quiet_days":{"type":"integer","minimum":1,"maximum":90}}}}}},"responses":{"200":{"description":"The setup after saving.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsConversionSetup"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/conversion-setup/queue":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"queueAdsConversionSetup","summary":"Queue one approve-first change — import the chosen GA4 key events, or create the upload action.","description":"Gated on `ads.manage`; audit-logged (`ads.conversion_setup_queued`). Nothing is sent to the network: the change waits in the connection's change queue for a person to approve it. `ga4_import` sets the chosen key events `ENABLED`, primary when the method is `ga4` and secondary when it is `server` (so a sale is never counted twice). `upload_action` creates the `UPLOAD_CLICKS` action (Google) or offline goal (Microsoft) the server-side upload reports into. Asking again returns the change already waiting.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["step"],"properties":{"step":{"type":"string","enum":["ga4_import","upload_action"]},"kind":{"type":"string","enum":["purchase","lead"],"default":"purchase"}}}}}},"responses":{"202":{"description":"Queued for approval.","content":{"application/json":{"schema":{"type":"object","required":["connection_id","step","change_id"],"properties":{"connection_id":{"type":"string","format":"uuid"},"step":{"type":"string"},"change_id":{"type":"string","format":"uuid"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/plugin-feed":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsPluginFeed","summary":"The plugin conversion actions on your own ad account and what each recorded (za-96).","description":"Gated on `ads.view`. Read from our database only (no network call). For a plugin seller: four conversion actions on the account — the purchase is PRIMARY (what the campaigns bid on), the trial, the free install and the renewal are SECONDARY (observed, never bid on). Each role has a `state`: `mapped` (the action exists and its outcome kind uploads to it), `kept_yours` (the action exists but you had already mapped that kind to another action — yours is kept), `queued` (the create is waiting in your change queue for approval), `declined` (you rejected or undid the create; switch the feed off and on to be asked again) or `missing` (the next tracking step looks). `received` / `uploaded` count that kind's outcomes over the last `window_days`.","tags":["ads"],"responses":{"200":{"description":"The plugin feed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsPluginFeed"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setAdsPluginFeed","summary":"Switch the plugin conversion feed on or off for this ad account.","description":"Gated on `ads.manage`; audit-logged (`ads.plugin_feed_saved`). Nothing is sent to the network here. Switching it on starts the account's tracking step (a background workflow, `run_started`): it finds the four actions by NAME, queues ONE approve-first change creating any that are missing (applied only when approved, inside the account's kill switches and good standing), and maps the ones that exist to their outcome kinds — never replacing a mapping you made yourself. A Freemius checkout source then also reports free installs and renewals. Switching it off stops that; nothing already on the account is removed.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["enabled"],"properties":{"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"The plugin feed after saving.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AdsPluginFeed"},{"type":"object","required":["run_started"],"properties":{"run_started":{"type":"boolean"}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/ad-quality":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsAdQuality","summary":"Ad quality — Limited Ad Serving, weak ads and their rewrites (za-150, za-162..165).","description":"Gated on `ads.view`. Reads the account (three bounded queries) and spends nothing; the rewrite itself runs in the connection's daily audit under the customer's `ads` mode. `limited_serving` is read from what the network's API gives (ads approved-limited, a limited-serving policy topic, a first spend inside 90 days) with the brand-clarity checks and the fix list. `weak_ads` lists every enabled responsive search ad the network rates POOR or AVERAGE, or that a guard refuses (brand not pinned in headline 1, another company's name, \"free\" for a software advertiser, generic-only lines, two lines that say the same thing or pins beyond the brand — za-334), with the rewrite's own score and its reasons when it cannot reach GOOD, and `google_says`: Google's own action items for the ad. The rewrite shown (and the one the audit sends) also takes Google's own suggested lines for the ad group (its `RESPONSIVE_SEARCH_AD_ASSET` / `…_IMPROVE_AD_STRENGTH` / `RESPONSIVE_SEARCH_AD` recommendations, one more bounded read) through the same checks. Cached 10 minutes per connection; `refresh=1` reads again. A Microsoft connection answers `supported: false`. A read that failed returns `report: null` with `failure` (a `VendorFailure`).","tags":["ads"],"parameters":[{"name":"refresh","in":"query","required":false,"schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"The ad-quality report.","content":{"application/json":{"schema":{"type":"object","required":["supported","platform","report"],"properties":{"supported":{"type":"boolean"},"platform":{"type":"string"},"needs_reconnect":{"type":"boolean"},"failure":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/VendorFailure"}]},"report":{"nullable":true,"type":"object","required":["connection_id","mode","limited_serving","strengths","weak_ads","rewrites","checked_at"],"properties":{"connection_id":{"type":"string","format":"uuid"},"mode":{"type":"string","enum":["off","approve","auto"],"description":"The connection's `ads` mode — how a rewrite is applied."},"checked_at":{"type":"string","format":"date-time"},"strengths":{"type":"object","description":"Enabled responsive search ads per network ad strength (POOR, AVERAGE, GOOD, EXCELLENT, PENDING, …).","additionalProperties":{"type":"integer"}},"limited_serving":{"type":"object","required":["state","reasons","fixes"],"properties":{"state":{"type":"string","enum":["limited","atRisk","clear"]},"confirmed_topics":{"type":"array","items":{"type":"string"}},"limited_ads":{"type":"integer"},"new_advertiser":{"type":"boolean"},"first_spend":{"type":"string","format":"date","nullable":true},"enabled_ads":{"type":"integer"},"reasons":{"type":"array","items":{"type":"string","enum":["newAdvertiser","unclearBrand","otherBrands","genericCopy"]}},"fixes":{"type":"array","items":{"type":"object","required":["code","ads"],"properties":{"code":{"type":"string","enum":["pinDomain","removeOtherBrands","addBrandToCopy","specificLines"]},"ads":{"type":"integer"}}}}}},"weak_ads":{"type":"array","items":{"type":"object","required":["resource","campaign","ad_group","final_url","google_strength","guards","rewrite"],"properties":{"resource":{"type":"string"},"campaign":{"type":"string"},"ad_group":{"type":"string"},"final_url":{"type":"string"},"google_strength":{"type":"string"},"headlines":{"type":"array","items":{"type":"string"}},"guards":{"type":"array","items":{"$ref":"#/components/schemas/AdsQualityFinding"}},"google_says":{"type":"array","items":{"$ref":"#/components/schemas/AdsGoogleSays"}},"rewrite":{"$ref":"#/components/schemas/AdsQualityScore"}}}},"rewrites":{"type":"array","items":{"type":"object","properties":{"change_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"old_ad":{"type":"string"},"round":{"type":"integer"},"strength_before":{"type":"string"},"score_after":{"type":"string"},"retired":{"type":"boolean"},"proposed_at":{"type":"string","format":"date-time"}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/outcomes":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsOutcomes","summary":"The real outcomes received for this account (newest first, at most 200).","description":"Gated on `ads.view`. Click ids are masked to a prefix; an e-mail is never stored or returned (only whether a hash exists).","tags":["ads"],"parameters":[{"name":"recovery_status","in":"query","required":false,"schema":{"type":"string","enum":["pending","uploaded","skipped","failed"]}}],"responses":{"200":{"description":"The outcomes.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsOutcome"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"sendAdsOutcomes","security":[{"bearerAuth":[]},{"apiKeyAuth":["ads.manage"]},{"apiKeyAuth":["ads.outcomes.write"]}],"summary":"The events API — send real outcomes (sales, trials, leads, sign-ups).","description":"Gated on `ads.manage` or `ads.outcomes.write` (KEYSCOPE — the narrow site-server key: exact-org, never inherited by a sub-account, accepted by this route and `retractAdsOutcomes` and by NO other route); audit action `ads.outcomes_received`. Up to 500 per request (send pages for a back-fill; no limit on pages). Idempotent per `(kind, external_ref)`: the same order twice is stored once, and a later copy that carries a click id the first lacked fills it in. `external_ref` is the order / trial id in YOUR system and is the transaction id every upload carries, so the network never counts one outcome twice. A plain `email` is SHA-256-hashed at the door and dropped. `201` when any was new. `free_listing` is a free sign-up that is not a sale: omit `value_minor` (or send `0` with `currency`) and map it to its own, usually secondary, upload action. `renewal` is a plugin subscription / licence renewed (za-96): it goes to its own secondary action (the plugin feed, `getAdsPluginFeed`), never counted as a new sale. `consent` is stored per conversion and passed to the network exactly as sent; withdraw an outcome with `retractAdsOutcomes`. A long-lived API key (`zdk_…`) holding `ads.outcomes.write` (or `ads.manage`) in the connection's organisation authenticates here. Anything new starts the upload within minutes (the daily run is the safety net).","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["outcomes"],"properties":{"outcomes":{"type":"array","minItems":1,"maxItems":500,"items":{"$ref":"#/components/schemas/AdsOutcomeIn"}}}}}}},"responses":{"200":{"description":"Nothing new.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsOutcomesIngested"}}}},"201":{"description":"Stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsOutcomesIngested"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/outcomes/retractions":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"retractAdsOutcomes","security":[{"bearerAuth":[]},{"apiKeyAuth":["ads.manage"]},{"apiKeyAuth":["ads.outcomes.write"]}],"summary":"Withdraw outcomes you sent, by your own id (a full refund).","description":"Gated on `ads.manage` or `ads.outcomes.write` (KEYSCOPE — exact-org, see `sendAdsOutcomes`); audit action `ads.outcomes_retracted`. Up to 500 per request. Each `(kind, external_ref)` is treated exactly like a sale refunded in full (za-122): one not uploaded yet is never uploaded (`withheld`); one already uploaded gets ONE retraction, which the next upload run sends to the network as a conversion adjustment (`retracted`; the run is started now when any was). Idempotent: an outcome withdrawn before, or refunded by its checkout provider, is `already`; an id this connection never received is `not_found`. The adjustment's progress shows on `listAdsTrackingEvents`. Nothing is charged. Open to a ChatGPT Ads account too (za-320, the outcomes its truth check compares): it takes no upload from us, so they are `withheld` and nothing is sent.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["retractions"],"properties":{"retractions":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"object","required":["kind","external_ref"],"properties":{"kind":{"type":"string","enum":["purchase","trial","lead","signup","activation","free_listing","renewal"]},"external_ref":{"type":"string","pattern":"^[\\w.:\\-/#]{1,128}$"}}}}}}}}},"responses":{"200":{"description":"What happened to each outcome named.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsOutcomesRetracted"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/events":{"get":{"operationId":"listAdsServerEvents","summary":"The server events you sent, newest first, with what each connected network did.","description":"Gated on `ads.view`. docs/1006.d/features/za-129-server-events.md, za-129. The newest 50 events sent to `sendAdsServerEvents`, each with one `deliveries` row per connected ad account: `pending` (waiting to upload), `uploaded`, `failed` (the network refused it; tried again later, `reason` says why), `skipped` (no click id or hashed e-mail for that network, consent `DENIED` for a network that cannot carry consent, no upload action for its kind, or older than the network's window), or `waiting` (not yet fanned out). `networks` lists the accounts an event goes to (Google Ads, Microsoft Advertising, Meta, X — never a disconnected one) and `waiting` counts events not yet fanned out. The org is the caller's only org, or `org_id`.","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The newest events.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsServerEventList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"post":{"operationId":"sendAdsServerEvents","summary":"The server events API — send a conversion once; it goes to every connected network.","description":"Gated on `ads.manage`; audit action `ads.server_events_received`. docs/1006.d/features/za-129-server-events.md, za-129. Your server sends each conversion ONCE with your own `event_id`; it is stored once per organisation (a retry or a double send is a duplicate, listed in `duplicate_event_ids`) and then fanned out, in the background, to every connected ad account of the organisation (Google Ads offline / enhanced conversions, Microsoft offline conversions, the Meta Conversions API, the X Conversion API). `event_id` is the transaction / event id every network receives, so no network counts one conversion twice — send the same id from your browser pixel to dedupe the pair. A plain `email` is SHA-256-hashed at the door and dropped; never send other personal data. `consent` is kept as sent: Google receives it, and Meta and X are never sent an event whose consent is `DENIED`. Money is integer minor units plus an ISO 4217 currency. Up to 500 events per request (no limit on requests). Uploads follow each account's tracking settings (an upload action per kind, recovery on) and stop while an account is paused or its kill switch is on, or the subscription is not in good standing — they resume by themselves. `202` when any event was new; `200` when all were duplicates. A long-lived API key (`zdk_…`) holding `ads.manage` in the organisation authenticates here.","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["events"],"properties":{"org_id":{"type":"string","format":"uuid"},"events":{"type":"array","minItems":1,"maxItems":500,"items":{"$ref":"#/components/schemas/AdsServerEventIn"}}}}}}},"responses":{"200":{"description":"Every event was already stored (nothing new).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsServerEventsReceived"}}}},"202":{"description":"Stored; the fan-out to every connected network has started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsServerEventsReceived"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/tracking-hub":{"get":{"operationId":"getAdsTrackingHub","summary":"The tracking hub — every network tag, conversion id and server-side key status.","description":"Gated on `ads.view` (docs/1006 §104, za-126). One hub per organisation: the browser tag id of each network (Google Ads, GA4, Microsoft UET, Meta pixel, TikTok, LinkedIn Insight, X, Pinterest, Amazon), the conversion id per network and outcome kind, and WHICH server-side keys are set (never the key: it is kept only in Vault). `server_routes` says per network how server-side conversions travel: through a connected ad account, through a key in the hub, or not at all. Every site tag (za-128) serves the hub's ids where it leaves its own blank. An organisation with no hub yet answers `version: 0`.","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Required when you belong to more than one organisation."}],"responses":{"200":{"description":"The organisation's tracking hub.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsTrackingHub"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"put":{"operationId":"updateAdsTrackingHub","summary":"Change the hub's tag ids and conversion ids.","description":"Gated on `ads.manage`; audit-logged (`ads.tracking_hub_updated`). `tags` and `conversions` each REPLACE the stored map when present (a blank id removes it). Each tag id is checked against its network's format; a wrong one is a `422` (`refusal.adsconnect.trackingHub.*`) naming the field, e.g. `tags.ga4`. The version goes up by one and the cached script of every site tag of the organisation is rewritten.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsTrackingHubUpdate"}}}},"responses":{"200":{"description":"The hub after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsTrackingHub"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/ads/tracking-hub/keys/{kind}":{"parameters":[{"name":"kind","in":"path","required":true,"schema":{"type":"string","enum":["meta_capi","tiktok_events","ga4_mp","linkedin_capi","pinterest_capi","openai_capi"]}},{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Required when you belong to more than one organisation."}],"put":{"operationId":"setAdsTrackingHubKey","summary":"Store one server-side key (write-only; kept in Vault).","description":"Gated on `ads.manage`; audit-logged (`ads.tracking_hub_key_set`, the kind only). The key is written to Vault and never returned, logged or stored in the database; the hub keeps the time it was set and its last four characters. `503` when Vault could not be written (nothing is saved; retry). From then on the key SENDS the organisation's real outcomes server-side (docs/1006 §122): see `server_sends` on the hub for what it really sent.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["key"],"properties":{"key":{"type":"string","minLength":16,"maxLength":512,"writeOnly":true},"account_id":{"type":"string","pattern":"^[0-9]{1,20}$","description":"pinterest_capi only, and required there: the numeric Pinterest ad account id the conversion token belongs to (the Conversions API posts to /ad_accounts/{id}/events). Any other kind refuses it (badAccount)."},"test_code":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$","description":"Optional network test code (docs/1006 §122): Meta / TikTok test_event_code, Pinterest test=true, GA4's validation server, OpenAI validate_only for openai_capi (za-335: any value; OpenAI checks each event and saves none). Events sent with it appear in the network's test view only and are not counted as conversions. LinkedIn has no test mode and refuses it (badTestCode)."}}}}}},"responses":{"200":{"description":"The hub after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsTrackingHub"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"delete":{"operationId":"deleteAdsTrackingHubKey","summary":"Remove one server-side key from Vault and from the hub.","description":"Gated on `ads.manage`; audit-logged (`ads.tracking_hub_key_removed`). The record is removed only after Vault confirmed the delete. Removing a key that is not set is a `204`.","tags":["ads"],"responses":{"204":{"description":"Removed (or was not set)."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/ads/site-tags":{"get":{"operationId":"listAdsSiteTags","summary":"Install on any site — the organisation's site tags with their install code.","description":"Gated on `ads.view` (docs/1006 §84, za-128). One row per non-WordPress site: the network tag ids (Google Ads `AW-…`, GA4 `G-…`, Microsoft UET, Meta pixel), the Google Ads conversion label per outcome kind and the consent default. `install` holds the universal snippet, the Shopify custom-pixel code and the GTM container path, all generated from the same row. `suggested_hosts` are sites already named as an ad account's tracking site that have no tag yet.","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Narrow to one of your organisations (default: all you can view)."}],"responses":{"200":{"description":"The site tags (up to 200) and the hosts to suggest.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsSiteTagList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createAdsSiteTag","summary":"Add a site and mint its public tag key.","description":"Gated on `ads.manage`; audit-logged (`ads.site_tag_created`). `site_host` may be pasted as a URL (it is reduced to the host). The `public_key` is in the customer's page source and is NOT a secret: it only selects public tag ids. A second tag for the same host in the organisation is a `409` (`refusal.adsconnect.siteTag.duplicateHost`); a value in the wrong format is a `422` (`refusal.adsconnect.siteTag.*`).","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsSiteTagCreate"}}}},"responses":{"201":{"description":"The new site tag.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsSiteTag"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/ads/site-tags/{tag_id}":{"parameters":[{"name":"tag_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsSiteTag","summary":"One site tag with its install code.","description":"Gated on `ads.view` (docs/1006 §84). Another organisation's tag is a `404`.","tags":["ads"],"responses":{"200":{"description":"The site tag.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsSiteTag"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"operationId":"updateAdsSiteTag","summary":"Change a site tag (every install route follows within five minutes).","description":"Gated on `ads.manage`; audit-logged (`ads.site_tag_updated`). Only the fields sent change. `version` goes up by one and the cached script is dropped, so the snippet and the Shopify pixel serve the new settings within the edge lifetime (300 s). A GTM container already imported does not change: download and import it again.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsSiteTagUpdate"}}}},"responses":{"200":{"description":"The changed site tag.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsSiteTag"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"deleteAdsSiteTag","summary":"Remove a site tag; its script answers 404 from then on.","description":"Gated on `ads.manage`; audit-logged (`ads.site_tag_deleted`). A first-party setup (za-123) is removed first, as `DELETE …/first-party` does; a temporary Cloudflare failure refuses the delete (503) so nothing is left on the customer's account.","tags":["ads"],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/ads/site-tags/{tag_id}/gtm-container":{"parameters":[{"name":"tag_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsSiteTagGtmContainer","summary":"The Google Tag Manager container to import, built from the same site tag.","description":"Gated on `ads.view` (docs/1006 §84). A GTM export (format 2) the customer imports in Admin → Import container (choose Merge): consent defaults on Consent Initialization, the Conversion Linker and Google tag, one Google Ads conversion tag per label (fired by the data-layer event `zinn_<kind>`), Microsoft UET and the Meta pixel (the Meta tags require `ad_storage` consent). The site pushes `{event: \"zinn_purchase\", zinn: {value_minor, currency, transaction_id}}`.","tags":["ads"],"responses":{"200":{"description":"The container JSON (sent as an attachment).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/ads/site-tags/{tag_id}/first-party":{"parameters":[{"name":"tag_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsSiteTagFirstParty","summary":"First-party tracking for this site on the customer's own Cloudflare (za-123).","description":"Gated on `ads.view` (docs/1006 §105). `status` is `off` until a token is connected, then `ok`, `needs_token` (the customer must fix the token or zone) or `failed` (`last_error`). `snippet` is the first-party install: the universal script from `/ztag/{public_key}.js` on the site's own host. Never returns the token: `token_hint` is its last four characters.","tags":["ads"],"responses":{"200":{"description":"The first-party setup.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsSiteTagFirstParty"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"operationId":"connectAdsSiteTagFirstParty","summary":"Deploy first-party tracking with the customer's own Cloudflare API token.","description":"Gated on `ads.manage`; audit-logged (`ads.first_party_connected`, zone and route only). The token (Zone Read, Workers Scripts Edit, Workers Routes Edit) is checked by using it: one Worker `zinn-ads-<id>` is uploaded to the account of the site's zone and routed on `<site_host>/ztag/*` only. It serves the site's universal script and passes Google's tag gateway through, so gtag.js loads same-origin. Google decides where hits go: outside Europe they use `<site_host>/ztag/` too; for visitors in Europe Google's library sends them to its regional endpoint, and it always sends a load-health probe and a session beacon straight to Google. Consent Mode v2 defaults are still set before any Google tag loads; before consent Google may send cookieless pings, and nothing is stored. No HTML, DNS or zone setting is changed. The token is kept only in Vault; sending a new one replaces it and destroys the old one. Refusals: `refusal.adsconnect.firstParty.*` (`badToken`, `tokenRejected`, `permissionMissing`, `zoneNotFound` 422; `rateLimited`, `unavailable`, `vaultUnavailable` 503).","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsSiteTagFirstPartyConnect"}}}},"responses":{"200":{"description":"Deployed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsSiteTagFirstParty"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"delete":{"operationId":"deleteAdsSiteTagFirstParty","summary":"Remove the first-party route, Worker and stored token.","description":"Gated on `ads.manage`; audit-logged (`ads.first_party_removed`). `removed_at_edge` is false when the stored token no longer works: our record and token are gone, and the customer deletes the `zinn-ads-…` Worker in their Cloudflare dashboard. A temporary Cloudflare failure changes nothing (503) so the call can be retried. 204 when there was nothing to remove.","tags":["ads"],"responses":{"200":{"description":"Removed.","content":{"application/json":{"schema":{"type":"object","required":["removed_at_edge"],"properties":{"removed_at_edge":{"type":"boolean"}}}}}},"204":{"description":"Nothing to remove."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/ads/site-tags/{tag_id}/first-party/check":{"parameters":[{"name":"tag_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"checkAdsSiteTagFirstParty","summary":"Ask Cloudflare whether the first-party route still serves this site.","description":"Gated on `ads.manage` (docs/1006 §105). Records `ok`, `failed` (`routeMissing`: the route was removed or repointed) or `needs_token`; a temporary Cloudflare failure keeps the previous status. The served script uses the first-party path only while `ok`.","tags":["ads"],"responses":{"200":{"description":"The first-party setup after the check.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsSiteTagFirstParty"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/public/ads-tag/{public_key}.js":{"parameters":[{"name":"public_key","in":"path","required":true,"schema":{"type":"string","pattern":"^zat_[A-Za-z0-9_-]{22}$"}}],"get":{"operationId":"getAdsSiteTagScript","summary":"The universal Zinn® Ads script for one site (public, cached).","description":"Public (docs/1006 §84, za-128): sites load it as `https://zinndigital.com/zat/{public_key}.js`, which the public site's edge caches and fills from here. Answered from the cache, never a database read per page view. Sets Google Consent Mode v2 defaults BEFORE any tag loads, then the configured Google, Microsoft and (only after ad consent) Meta tags, and defines `zinnAds.conversion(kind, {value_minor | amount, currency, id})`, `zinnAds.consent({...})` and `zinnAds.clickIds()`. No personal data. An unknown, removed or switched-off key is a `404` whose body is a JavaScript comment.","tags":["ads"],"security":[],"responses":{"200":{"description":"The script.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"public, max-age=300, s-maxage=300, stale-while-revalidate=86400"}},"content":{"application/javascript":{"schema":{"type":"string"}}}},"404":{"description":"No such site tag (a JavaScript comment).","content":{"application/javascript":{"schema":{"type":"string"}}}}}}},"/v1/public/house-tags":{"get":{"operationId":"getPublicHouseTags","summary":"The ad networks our own public sites load (public, cached).","description":"TRACK-ALWAYS (owner 2026-11-08): our own public sites load only the advertising tags of networks we use. `networks` lists every platform with an ACTIVE house ad connection (sorted); `tags` is the platform tracking hub's public tag id per hub network (`ga4`, `google_ads`, `microsoft_uet`, `meta_pixel`, `pinterest_tag`, …). A network in `networks` with no id in `tags` loads only where the site carries its own id. Every value is public by nature (page source). Answered from a one-minute cache; the public site reads it server-side every five minutes, never per page view.","tags":["ads"],"security":[],"responses":{"200":{"description":"The networks in use and their public tag ids.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"public, max-age=60, s-maxage=300"}},"content":{"application/json":{"schema":{"type":"object","required":["networks","tags"],"additionalProperties":false,"properties":{"networks":{"type":"array","items":{"type":"string"}},"tags":{"type":"object","additionalProperties":{"type":"string"}}}}}}}}}},"/v1/public/ads-tag/{public_key}/signals":{"parameters":[{"name":"public_key","in":"path","required":true,"schema":{"type":"string","pattern":"^zat_[A-Za-z0-9_-]{22}$"}}],"post":{"operationId":"sendAdsSiteTagSignal","summary":"The universal tag's click-shield beacon (public, rate-limited, per-site key).","description":"Public (SHIELDTAG, docs/1006.d/features/za-316-shieldtag.md): the universal script sends it with `navigator.sendBeacon` as `text/plain` JSON (no CORS preflight), so the click-fraud shield works on ANY website, not only sites Zinn® hosts. `k` is `landing` (a paid-click visit; `q` holds ONLY the recognised click ids — gclid, msclkid, fbclid, ttclid, li_fat_id, twclid, epik), `engaged` (the visitor scrolled, tapped or typed), `page` (a later page view, only after ad consent) or `conversion` (`zinnAds.conversion` ran). The visitor address and user agent are the REQUEST's (our ingress's trusted client address), never the body's; the host is the tag's own site; the time is the engine's. The `Origin` must be the tag's site or a subdomain of it. A follow-up is kept only when the same address landed from a paid click inside the 10-minute dwell window. Landings are scored by the same shield as hosted sites every 5 minutes once the dwell window closed (same weights, verdicts, IP exclusions and claim packs), only while the organisation has the shield and is in good standing; a site already scored as a hosted site or by the Zinn® Ads WordPress plugin is not scored twice. Beacons are deleted after 3 days. Always `204` for a well-formed beacon, stored or not (no oracle).","tags":["ads"],"security":[],"requestBody":{"required":true,"content":{"text/plain":{"schema":{"type":"string","description":"JSON, at most 4096 bytes: `{\"k\": \"landing\"|\"engaged\"|\"page\"|\"conversion\", \"p\": \"<page path>\", \"q\": {\"gclid\": \"…\"}}` (`q` only on a landing, required there)."}}}},"responses":{"204":{"description":"Received (stored, or ignored on purpose).","headers":{"Access-Control-Allow-Origin":{"schema":{"type":"string"},"description":"*"}}},"400":{"description":"Not a beacon (bad JSON, unknown kind, a landing without a click id, too large)."},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/tracking/events":{"get":{"operationId":"listAdsTrackingEvents","summary":"The event debugger — every real outcome and what each ad network did with it.","description":"Gated on `ads.view`; read-only (nothing is uploaded or retried). docs/1006 §21, za-130. Every real outcome (sale, trial, lead, sign-up, activation) the organisation's connected ad accounts received in the window, ONE row per event `(kind, external_ref)` — the same order sent to a Google and a Microsoft account is one row with two `networks` — newest first. Each network row says whether the network `accepted` it (uploaded), `rejected` it (with the network's `reason`), it is `waiting` to send, or it is `not_sendable` (no click id or hashed e-mail, outside the network's window, or a kind the network takes no upload for), plus the value corrections (refunds, a trial that became a sale) sent after it. `summary` counts the same window and filters per network. Keyset-paged over `(occurred_at, kind, external_ref)`: follow `page.next_cursor` until `page.has_more` is false (no limit on pages). A filter, window, page size or cursor this endpoint did not issue is a `422` (`refusal.adsconnect.badEventsQuery`), never a silent default.","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Narrow to one of your organisations (default: all you can view)."},{"name":"network","in":"query","required":false,"schema":{"type":"string","enum":["google","microsoft","meta","linkedin","tiktok","x","pinterest","amazon"]}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["accepted","rejected","waiting","not_sendable"]},"description":"Only events with a network row in this state."},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":90,"default":30},"description":"How many days back (by when the outcome happened)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"The `page.next_cursor` of the previous page, passed back verbatim."}],"responses":{"200":{"description":"One page of events, the per-network summary and the window read.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsTrackingEventsPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/ads/connections/{connection_id}/profit":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsProfit","summary":"Profit bidding (POAS) — value basis, product costs, fee estimates and the margin sent.","description":"Gated on `ads.view` (docs/1006 §68, za-189). With `value_basis` `profit`, every checkout sale (Stripe, Paddle, Freemius) uploads to the network as its MARGIN: price minus the tax inside it, the provider's fee (reported by Paddle and Freemius, else the source's estimate), the product's cost (`products`, in the sale's currency, else `default_cost_bp` of the price) and any refund — so tROAS optimises profit, not revenue. `summary` is the last `summary.days` of checkout sales: revenue against the margin, per currency, and the products sold that have no cost yet. An account on a network other than Google or Microsoft is a `422` `refusal.adsconnect.platformNotSupported`; a write naming a duplicate or blank product, or another account's checkout source, is a `422` `refusal.adsconnect.profitBadSettings` (FIX-189).","tags":["ads"],"responses":{"200":{"description":"The profit-bidding state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsProfit"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setAdsProfit","summary":"Turn profit bidding on or off, set product costs and fee estimates.","description":"Gated on `ads.manage`; audit action `ads.profit_settings`. Every field is optional. `products` REPLACES the account's product costs as a whole (each `product_ref` once); `sources` sets the fee estimate of named checkout sources of THIS account. A cost change applies to sales that arrive after it: a sale keeps the margin it arrived with.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsProfitSettings"}}}},"responses":{"200":{"description":"Saved; the profit-bidding state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsProfit"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/product-trials":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsProductTrials","summary":"Each product's free-trial length, our recommendation, and the longest trial.","description":"Gated on `ads.view` (docs/1006 §83, za-100). Every product the account is known to sell (its sales and trials, its product costs, its own choices) with its free-trial length: `0` = no free trial, else 7, 14 or 30 days. A product with no choice of its own follows `recommended_days` (our recommendation for the account's business type) and reads `custom: false`. The autopilot judges SALES only after a trial has ended: a conversion still inside its trial counts as pending, never as a failure; a campaign (which carries no product) waits for `longest_days`.","tags":["ads"],"responses":{"200":{"description":"The trial lengths.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsProductTrials"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setAdsProductTrials","summary":"Set the free-trial length of named products (null resets to recommended).","description":"Gated on `ads.manage`; audit action `ads.product_trials`. Each named product gets its `trial_days` (0, 7, 14 or 30); `null` deletes its own choice so it follows the recommendation again. Products not named are left as they are. A product named twice (or a blank id) is a field-level `422` naming `products` (never `refused`), and nothing is saved.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsProductTrialsSettings"}}}},"responses":{"200":{"description":"Saved; the trial lengths.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsProductTrials"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/signal-values":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsSignalValues","summary":"What one sign-up and one activation are worth, measured, and what the network counts.","description":"Gated on `ads.view` (docs/1006 §34, za-155). For each signal (`signup` = sign-ups, trials and leads; `activation`): the measured chance one becomes a paid customer (`measured_bp`, over the signals of the last `window_days` that are past the account's `wait_days`, joined to a sale by e-mail hash, click id or checkout reference; a signal with nothing to join on is counted in `unjoined` and left out), the business type's default (`prior_bp`), the blend of the two with `prior_weight` pseudo-signals (`blended_bp`), the average first sale (`revenue_minor`, account currency, at the value sales are uploaded with), the value they give (`value_minor`), what the network's conversion action counts now (`network_minor`) and the `status` of the last daily run: `sent`, `queued` (waits for approval, `change_id`), `unchanged` (within `change_pct`), `refused`, `failed`, `off`, `no_action`, `no_revenue`, `unsupported` (only Google Ads takes the value), `unreadable`, or `not_measured` before the first run. Reads stored rows only; no network call.","tags":["ads"],"responses":{"200":{"description":"Both signals.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsSignalValues"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"setAdsSignalValues","summary":"Send or only measure a signal's value, set your own value, or choose its action.","description":"Gated on `ads.manage`; audit action `ads.signal_values`. Per named signal: `auto` (true = the daily step sets the measured value on the conversion action whenever it moves, through the account's approval setting for conversion changes; false = measure only), `override_minor` (the customer's own value, minor units of the account currency; `null` = the measured one) and `action` (a Google Ads conversion action resource name; `\"\"` = the account's upload action for that kind). Fields not sent are left as they are. A signal named twice, or an action that is not a conversion action, is a 422 and nothing is saved. Nothing is sent to the network here.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsSignalValuesSettings"}}}},"responses":{"200":{"description":"Saved; both signals.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsSignalValues"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/audiences":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsAudiences","summary":"The customer's own Customer Match lists for this Google Ads account.","description":"Gated on `ads.view`. Each list carries its recorded consent, member counts (wanted, at the network, waiting to be added or removed), what blocks it if anything, and its last sync. Never an identifier: members are stored as SHA-256 hashes only. A connection that is not Google Ads is a `422` `refusal.adsconnect.audiencesGoogleOnly` on every audiences path (FIX13). docs/1006 §72.","tags":["ads"],"responses":{"200":{"description":"The lists.","content":{"application/json":{"schema":{"type":"object","required":["data","max_per_call"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsAudience"}},"max_per_call":{"type":"integer","description":"Most people one upload call may carry."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createAdsAudience","summary":"Create a Customer Match list, recording the consent its people gave.","description":"Gated on `ads.manage`; audit action `ads.audience_created` (consent values only). Nothing is sent to the network until both consents are GRANTED, the basis is recorded and Google's Customer Match terms are accepted (`accept_terms`). Google accounts only; at most 50 live lists per account (`422` `refusal.adsconnect.audienceLimit`); names are unique among an account's live lists (`422` `refusal.adsconnect.audienceNameTaken`) (FIX-REFUSED). A deleted list frees its slot and its name (OWNERFIX-B).","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","consent_ad_user_data","consent_ad_personalization","consent_basis","accept_terms"],"properties":{"name":{"type":"string","maxLength":100},"description":{"type":"string","maxLength":300},"consent_ad_user_data":{"type":"string","enum":["GRANTED","DENIED"]},"consent_ad_personalization":{"type":"string","enum":["GRANTED","DENIED"]},"consent_basis":{"type":"string","maxLength":500,"description":"How the consent was collected","in the customer's words.":null},"accept_terms":{"type":"boolean","description":"The customer accepts Google's Customer Match terms for this account."}}}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsAudience"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/audiences/{audience_id}":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"audience_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"operationId":"updateAdsAudience","summary":"Rename a Customer Match list or change its recorded consent and terms.","description":"Gated on `ads.manage`; audit action `ads.audience_updated`. Any consent change is re-stamped with who made it and when. Renaming a live list onto another live list's name is a `422` `refusal.adsconnect.audienceNameTaken` (OWNERFIX-B).","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":100},"description":{"type":"string","maxLength":300},"consent_ad_user_data":{"type":"string","enum":["GRANTED","DENIED"]},"consent_ad_personalization":{"type":"string","enum":["GRANTED","DENIED"]},"consent_basis":{"type":"string","maxLength":500},"accept_terms":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsAudience"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"emptyAdsAudience","summary":"Empty a Customer Match list — everyone on it is removed at the network.","description":"Gated on `ads.manage`; audit action `ads.audience_emptied`. A removal needs no consent. The list then stays idle; its hashes are dropped once the network confirms the removal. A deleted list no longer counts toward the 50-list limit and its name can be used again (OWNERFIX-B); a new list of that name is created at the network with a short id tail, because the old remote list keeps its name there.","tags":["ads"],"responses":{"202":{"description":"Emptying; the sync workflow was started.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AdsAudience"},{"type":"object","properties":{"sync_started":{"type":"boolean"}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/audiences/{audience_id}/members":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"audience_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"uploadAdsAudienceMembers","summary":"Add, remove or replace the people on a Customer Match list (hashed on arrival).","description":"Gated on `ads.manage`; audit action `ads.audience_members_uploaded` (counts only). Each person is an e-mail and/or a phone in E.164 (`+` and country code), or `email_sha256` / `phone_sha256` you hashed yourself (SHA-256 hex of the normalised value); a name is used only with `country` and `postcode`. Plain values are normalised and hashed the moment they are parsed and never stored, logged or returned. `replace` makes the list exactly this upload. The same upload twice changes nothing. Starts the sync workflow. A deleted list is a `422` `refusal.adsconnect.audienceDeleted` (FIX-REFUSED).","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["mode","members"],"properties":{"mode":{"type":"string","enum":["add","remove","replace"]},"members":{"type":"array","minItems":1,"maxItems":10000,"items":{"type":"object","properties":{"email":{"type":"string","maxLength":320,"writeOnly":true},"phone":{"type":"string","maxLength":32,"writeOnly":true},"email_sha256":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"},"phone_sha256":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"},"first_name":{"type":"string","maxLength":100,"writeOnly":true},"last_name":{"type":"string","maxLength":100,"writeOnly":true},"country":{"type":"string","maxLength":2},"postcode":{"type":"string","maxLength":16}}}}}}}}},"responses":{"202":{"description":"Staged (counts only).","content":{"application/json":{"schema":{"type":"object","required":["received","accepted","unusable","added","removed","unchanged","sync_started","audience"],"properties":{"received":{"type":"integer"},"accepted":{"type":"integer"},"unusable":{"type":"integer"},"added":{"type":"integer"},"removed":{"type":"integer"},"unchanged":{"type":"integer"},"sync_started":{"type":"boolean"},"audience":{"$ref":"#/components/schemas/AdsAudience"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/audiences/{audience_id}/sync":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"audience_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"syncAdsAudience","summary":"Send a Customer Match list's difference to the network now.","description":"Gated on `ads.manage`; audit action `ads.audience_sync_requested`. Starts the sync workflow for the account (one run per account per minute). The daily run does the same.","tags":["ads"],"responses":{"202":{"description":"Started.","content":{"application/json":{"schema":{"type":"object","required":["sync_started","audience"],"properties":{"sync_started":{"type":"boolean"},"audience":{"$ref":"#/components/schemas/AdsAudience"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/audiences/{audience_id}/crm-feed":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"audience_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"put":{"operationId":"setAdsAudienceCrmFeed","summary":"Fill a Customer Match list automatically from one of your CRM sources.","description":"za-95 (docs/1006 §72a). Gated on `ads.manage`; audit action `ads.audience_crm_feed_set` (counts and the attestation, never a person). Any change to the attestation re-stamps who and when; withdrawing either consent removes everyone at the next sync; changing the stages or the source re-reads the CRM from the start. Refusals: `audienceHasUploads` (the list holds uploaded people), `crmFeedBadSource`, `crmFeedBadStages`, `audienceDeleted`, `disconnected`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsAudienceCrmFeedPut"}}}},"responses":{"200":{"description":"The list, with its feed.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AdsAudience"},{"type":"object","required":["sync_started"],"properties":{"sync_started":{"type":"boolean"}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"removeAdsAudienceCrmFeed","summary":"Stop filling a list from the CRM; everyone it added is removed.","description":"za-95. Gated on `ads.manage`; audit action `ads.audience_crm_feed_removed`. The list stays and can take uploads again.","tags":["ads"],"responses":{"202":{"description":"Removed; the removals are sent at the next sync.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AdsAudience"},{"type":"object","required":["sync_started"],"properties":{"sync_started":{"type":"boolean"}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/checkout-sources":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listAdsCheckoutSources","summary":"The checkout providers sending this ad account their sales by webhook.","description":"Gated on `ads.view`. Each carries the webhook URL to paste into the provider.","tags":["ads"],"responses":{"200":{"description":"The sources.","content":{"application/json":{"schema":{"type":"object","required":["data","providers"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsCheckoutSource"}},"providers":{"type":"array","items":{"type":"string"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"addAdsCheckoutSource","summary":"Add a checkout provider (Stripe, Paddle or Freemius) with its webhook signing secret.","description":"Gated on `ads.manage`; audit action `ads.checkout_source_added`. The signing secret (Stripe `whsec_…`, Paddle's notification secret, the Freemius product secret key) is stored in Vault and never returned. At most 20 sources per ad account; one more is a `422` `refusal.adsconnect.checkoutSourceLimit` (FIX-REFUSED).","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["provider"],"properties":{"provider":{"type":"string","enum":["stripe","paddle","freemius"]},"signing_secret":{"type":"string","minLength":8,"maxLength":200,"writeOnly":true,"description":"Optional here — Stripe and Paddle show it only after our URL is pasted in; send it later with PATCH. Until then deliveries answer 503 (the provider retries)."},"label":{"type":"string","maxLength":80},"test_mode":{"type":"boolean","default":false}}}}}},"responses":{"201":{"description":"Added.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsCheckoutSource"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/checkout-sources/{source_id}":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"source_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"operationId":"updateAdsCheckoutSource","summary":"Replace the signing secret, rename, or switch a checkout source on or off.","description":"Gated on `ads.manage`; audit action `ads.checkout_source_changed`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"signing_secret":{"type":"string","minLength":8,"maxLength":200,"writeOnly":true},"label":{"type":"string","maxLength":80},"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Saved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsCheckoutSource"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"removeAdsCheckoutSource","summary":"Remove a checkout source and forget its signing secret.","description":"Gated on `ads.manage`; audit action `ads.checkout_source_removed`. Outcomes it already delivered are kept.","tags":["ads"],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/webhooks/ads-checkout/{source_id}":{"parameters":[{"name":"source_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"receiveAdsCheckoutWebhook","summary":"A checkout provider's signed delivery (Stripe, Paddle, Freemius).","description":"Unauthenticated: the provider's signature over the raw body is the authentication (Stripe `Stripe-Signature`, Paddle `Paddle-Signature`, Freemius `X-Signature`), verified with the source's secret from Vault. Sales and trials become outcomes (idempotent per the provider's id, which is also the upload's transaction id); refunds mark the sale refunded; events of the other mode (test vs live) and types not acted on answer 200. New outcomes start the server-side push to the ad network within about two minutes. `404` unknown or switched-off source, `400` missing or bad signature, `413` body over 1 MiB, `503` the secret could not be read (retry).","tags":["ads"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Handled.","content":{"application/json":{"schema":{"type":"object","required":["action","created","updated","refunded","ignored_other_mode","push_started"],"properties":{"action":{"type":"string","enum":["received","ignored","otherMode"]},"created":{"type":"integer"},"updated":{"type":"integer"},"refunded":{"type":"integer"},"ignored_other_mode":{"type":"integer"},"push_started":{"type":"boolean"}}}}}},"400":{"description":"The signature is missing or did not verify.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsCheckoutWebhookError"}}}},"404":{"description":"No such source, or it is switched off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsCheckoutWebhookError"}}}},"413":{"description":"The body is over 1 MiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsCheckoutWebhookError"}}}},"503":{"description":"The signing secret could not be read; the provider should retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsCheckoutWebhookError"}}}}}}},"/v1/ads/changes":{"get":{"operationId":"listAdsChanges","summary":"The approve-first queue and the change history.","description":"Gated on `ads.view`. Newest first (`proposed_at`, then `id`), at most `limit` (default and maximum 200) a page. `pending` changes wait for a person; `applied` ones carry `undoable` and `undo_until` (30 days). `page.next_cursor` follows on to the next page, so every change is reachable (the History tab pages with `history=true` and \"Show more\", ZAPOLISH1115). An unreadable `cursor` or a non-integer `limit` is a 422.","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","required":false,"schema":{"$ref":"#/components/schemas/AdsChangeStatus"}},{"name":"connection_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"history","in":"query","required":false,"description":"`true`: every change except the pending ones (the History tab).","schema":{"type":"boolean"}},{"name":"limit","in":"query","required":false,"description":"Page size, clamped to 1..200.","schema":{"type":"integer","minimum":1,"maximum":200,"default":200}},{"name":"cursor","in":"query","required":false,"description":"The previous page's `page.next_cursor`.","schema":{"type":"string"}}],"responses":{"200":{"description":"The changes.","content":{"application/json":{"schema":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsChange"}},"page":{"$ref":"#/components/schemas/PageMeta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/changes/{change_id}/{action}":{"parameters":[{"name":"change_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"action","in":"path","required":true,"schema":{"type":"string","enum":["approve","reject","undo","allow_again","undo_allow_again","withdraw"]}}],"post":{"operationId":"decideAdsChange","summary":"Approve, reject, undo, withdraw, or allow a rejected change again.","description":"Gated on `ads.manage`; audit action `ads.change_<action>`. `approve` sends exactly the proposed request to Google in the background (202); a kill switch, the spend ceiling or the organisation's standing can still refuse it (`refused`). When the send meets Google's daily operation allowance the change stays `approved` with `summary.deferred_to` (when it is sent — automatically, by the same workflow), never refused. za-326 r3: an approval does not override a network's learning phase — an automatic change approved while the network says its unit is learning stays `approved` with `summary.learning` (`rule`, `network`) and `summary.deferred_to` (when learning is read again), and is sent once learning ends. ZA326-FU: the wait stops — the change is `refused` with `error` `learningUnread` after 4 re-checks in a row that could not read the learning state, or `learningNoEnd` 14 days after the wait began. ZA326-FU5: an approved change whose earlier send was interrupted before its answer was recorded is sent again automatically only when it is an absolute set (a pause, a budget, a bid); any other change (a create) is `refused` with `error` `sendUnconfirmed` and is never sent again blind — the person checks the account — and `withdraw` (200) takes the person's approval back while it waits (`rejected`, `summary.withdrawn` `{by, at}`, audit action `ads.change_withdraw`; else `notWaitingForLearning`). `undo` sends the change's inverse (202) — allowed with the kill switch on; an Undo that meets the same allowance leaves the change `applied` with `summary.undo_deferred_to` and is sent after the reset by the same Undo workflow (never recorded as failed), even when that is past the Undo window. A rejection binds the item on Google, Microsoft Ads and X alike. `reject` answers 200. A rejected negative keyword or keyword (same account, text, match type and level) is never proposed or sent again by any producer — the gate refuses it `rejectedBefore`, whether or not it still collides — until `allow_again` (200, a rejected change only, else `notRejected`; leaves `summary.allowed_again` `{by, at}`); `undo_allow_again` (200, else `notAllowedAgain`) puts the rejection back.","tags":["ads"],"responses":{"200":{"description":"Rejected, withdrawn, or allowed again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsChange"}}}},"202":{"description":"Approved or undo started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsChange"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/client-approval-links":{"get":{"operationId":"listAdsClientApprovalLinks","summary":"The client approval links the caller made (za-104).","description":"Gated on `ads.manage`, over every org the caller holds it in (an agency holds it on its clients through the reseller tree); narrowed by `?org_id=`. Newest first, at most 200. Never carries a token.","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The links.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","maxItems":200,"items":{"$ref":"#/components/schemas/AdsClientApprovalLink"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createAdsClientApprovalLink","summary":"Make an approval link for a client org (za-104).","description":"Gated on `ads.manage` on `org_id` (the CLIENT org); another org answers `404`. `days` 1-30 (default 14, else `badDays`); `label` is the agency's own note (plain text, else `badText`). The `201` carries `url` once — only the token's SHA-256 is stored. Audit action `ads.client_approval_link_created` on the client org.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["org_id"],"properties":{"org_id":{"type":"string","format":"uuid"},"days":{"type":"integer","minimum":1,"maximum":30,"default":14},"label":{"type":"string","maxLength":120}}}}}},"responses":{"201":{"description":"Made; copy `url` now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsClientApprovalLink"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/client-approval-links/{link_id}/revoke":{"parameters":[{"name":"link_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"revokeAdsClientApprovalLink","summary":"Stop a client approval link working, now (za-104).","description":"Gated on `ads.manage` on the link's client org (else `404`). Twice is once. Audit action `ads.client_approval_link_revoked`.","tags":["ads"],"responses":{"200":{"description":"Revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsClientApprovalLink"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/ads-approvals/{token}":{"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","maxLength":128}}],"get":{"operationId":"viewAdsClientApprovalPortal","summary":"The agency client approval portal — what waits on the client's accounts. Unauthenticated.","description":"⛔ **No authentication.** The reader is the agency's client and has no account; the token is the whole authorisation and reaches the pending changes of ONE client org (never a sibling's, the agency's own, or an applied change). Unknown, revoked and expired tokens all answer the same `404`. Throttled per client address.","security":[],"tags":["ads"],"responses":{"200":{"description":"The brand, the pending changes and what this link decided.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsClientPortal"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/ads-approvals/{token}/changes/{change_id}/{action}":{"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","maxLength":128}},{"name":"change_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"action","in":"path","required":true,"schema":{"type":"string","enum":["approve","reject"]}}],"post":{"operationId":"decideAdsChangeOnClientPortal","summary":"The agency's client approves or rejects one pending change. Unauthenticated.","description":"Token-authorised like the page. `name` is required (1-80 characters, plain text, else `badName`); `reason` up to 500 (else `badReason`) and required to reject (`reasonRequired`). Runs the same decision as `decideAdsChange`: `approve` starts the send (202) and the kill switch, the spend ceilings and the account's good standing can still refuse it; `reject` answers 200. A change that is not pending on the link's org answers `404`. Audit action `ads.change_<action>` on the client org with `metadata.via = client_portal`, the link, the name and the reason.","security":[],"tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":80},"reason":{"type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"Rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsClientPortalChange"}}}},"202":{"description":"Approved; the send started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsClientPortalChange"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/email-actions":{"post":{"operationId":"actOnAdsEmailLink","summary":"Act on an e-mailed Approve, Undo or Apply link (signed in).","description":"Gated on `ads.manage` in the change's organisation. The token is signed and expires (Approve and Apply 7 days, Undo 30). `?preview=1` only describes the action. A change's link (`approve` / `undo`) answers with `change`; a waste suggestion's one-click Apply from the daily e-mail (za-224: a step's suggestion or the off-intent rule's approval, never a budget move) answers with `finding` and runs the same path as `actOnAdsFinding`'s `apply`. One click-shield exclusion's Undo from the daily e-mail (za-59) answers with `exclusion` and runs the same path as `undoAdsShieldExclusion`. The link never signs anyone in.","tags":["ads"],"parameters":[{"name":"preview","in":"query","required":false,"schema":{"type":"string","enum":["1"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string"}}}}}},"responses":{"200":{"description":"The action and the change (or, for an Apply link, the finding).","content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["approve","undo","apply"]},"change":{"$ref":"#/components/schemas/AdsChange"},"finding":{"$ref":"#/components/schemas/AdsFinding"},"exclusion":{"$ref":"#/components/schemas/AdsShieldExclusion"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/plan":{"get":{"operationId":"getAdsPlan","summary":"The organisation's Zinn® Ads plan, what it uses and what it allows.","description":"Gated on `ads.view`. `source` is `plan` (a `zinn_ads` subscription, the org's own or an ancestor's), `staff` or `none` — with `none` no ad account can be connected until a plan is chosen (the Free plan is $0). `connections.limit` -1 is unlimited; `connections.used` counts every connection the plan pays for (the paying org and its client orgs). `monthly_spend_usd` is the managed ad spend a month the plan covers across all those accounts, in whole US dollars, including Extra-spend add-on blocks; `managed_spend_usd` is the sum of the monthly ceilings set now (`null` when a ceiling's currency has no stored FX rate). `addons` counts the Extra-accounts (+10) and Extra-spend (+$25k) blocks applied. `overage.automatic` is the Agency plan: spend above the allowance is billed on the renewal at +$99 per extra $25k (`overage.blocks`, `overage.usd_minor`). `click_shield.source` is `hosting` when a Zinn® hosting plan includes it free, `addon` when bought, `plan`, `staff` or `none`. Plans are bought through the cart like any plan (`listInAppCatalogPlans`, `product_line=zinn_ads`).","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsPlan"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/report":{"get":{"operationId":"getAdsReport","summary":"Reporting per ad account and per agency client (za-23).","description":"Gated on `ads.view`. Every connected ad account in the organisations the person can view — for an agency its own organisation and every client organisation below it — with spend, clicks, impressions, conversions, conversion value and ROAS over the last `days` days, the fraud the click shield blocked (exclusions added, their clicks and measured cost), the invalid-activity credit recovered, and what the autopilot changed (applied in the window, waiting now). `clients` totals the accounts per client organisation, one row PER CURRENCY (money is never summed across currencies). `org_id` narrows to that organisation and its clients. `connection_id` adds `detail`: that account's figures by campaign, product and country. Stored rows only (the daily audit's figures) — never a network call in the request. Spend and value are micros of the account currency; conversions are thousandths; ROAS is basis points (10000 = 1x, `null` with no spend); shield figures are minor units.","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"days","in":"query","required":false,"schema":{"type":"integer","enum":[7,30,90],"default":30}},{"name":"connection_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The report.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsReport"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/analytics/summary":{"get":{"operationId":"getAdsAnalyticsSummary","summary":"Zinn® Ads analytics KPI tiles for a period and its comparison (za-280).","description":"The period and comparison-period totals with a sparkline per figure, and the totals per account currency. Gated on `ads.view` over the organisations the person can view; `org_id` narrows to that organisation and its client organisations. Stored rows only (the daily audit's figures), never a network call. Money is integer micros of the reporting `currency`: each account's currency is converted at the CURRENT stored rate, named in `fx`; a currency with no rate is left out of the blended figures and listed in `unconverted`. Conversions are thousandths; ROAS, CTR and conversion rate are basis points; CPA and CPC are micros; a ratio with no denominator is null (za-280).","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/AdsAnalyticsRange"},{"$ref":"#/components/parameters/AdsAnalyticsFrom"},{"$ref":"#/components/parameters/AdsAnalyticsTo"},{"$ref":"#/components/parameters/AdsAnalyticsCompare"},{"$ref":"#/components/parameters/AdsAnalyticsGrain"},{"$ref":"#/components/parameters/AdsAnalyticsNetwork"},{"$ref":"#/components/parameters/AdsAnalyticsConnection"},{"$ref":"#/components/parameters/AdsAnalyticsCampaign"},{"$ref":"#/components/parameters/AdsAnalyticsCountry"},{"$ref":"#/components/parameters/AdsAnalyticsDevice"},{"$ref":"#/components/parameters/AdsAnalyticsOffering"},{"$ref":"#/components/parameters/AdsAnalyticsClient"},{"$ref":"#/components/parameters/AdsAnalyticsCurrency"}],"responses":{"200":{"description":"The figures.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsAnalyticsSummary"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/analytics/timeseries":{"get":{"operationId":"getAdsAnalyticsTimeseries","summary":"Zinn® Ads analytics trend per day, week or month (za-280).","description":"Every bucket of the period (zero-filled) with all figures, the comparison period bucket by bucket, and spend and value per network for the stacked network share. Gated on `ads.view` over the organisations the person can view; `org_id` narrows to that organisation and its client organisations. Stored rows only (the daily audit's figures), never a network call. Money is integer micros of the reporting `currency`: each account's currency is converted at the CURRENT stored rate, named in `fx`; a currency with no rate is left out of the blended figures and listed in `unconverted`. Conversions are thousandths; ROAS, CTR and conversion rate are basis points; CPA and CPC are micros; a ratio with no denominator is null (za-280).","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/AdsAnalyticsRange"},{"$ref":"#/components/parameters/AdsAnalyticsFrom"},{"$ref":"#/components/parameters/AdsAnalyticsTo"},{"$ref":"#/components/parameters/AdsAnalyticsCompare"},{"$ref":"#/components/parameters/AdsAnalyticsGrain"},{"$ref":"#/components/parameters/AdsAnalyticsNetwork"},{"$ref":"#/components/parameters/AdsAnalyticsConnection"},{"$ref":"#/components/parameters/AdsAnalyticsCampaign"},{"$ref":"#/components/parameters/AdsAnalyticsCountry"},{"$ref":"#/components/parameters/AdsAnalyticsDevice"},{"$ref":"#/components/parameters/AdsAnalyticsOffering"},{"$ref":"#/components/parameters/AdsAnalyticsClient"},{"$ref":"#/components/parameters/AdsAnalyticsCurrency"}],"responses":{"200":{"description":"The figures.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsAnalyticsTimeseries"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/analytics/breakdown":{"get":{"operationId":"getAdsAnalyticsBreakdown","summary":"Zinn® Ads analytics leaderboard by network, account, campaign, country, device or product/site (za-280, za-282).","description":"Rows sorted by spend, paged with `offset` and `limit` (`total` counts every row), each with its comparison figures and a spend sparkline. Gated on `ads.view` over the organisations the person can view; `org_id` narrows to that organisation and its client organisations. Stored rows only (the daily audit's figures), never a network call. Money is integer micros of the reporting `currency`: each account's currency is converted at the CURRENT stored rate, named in `fx`; a currency with no rate is left out of the blended figures and listed in `unconverted`. Conversions are thousandths; ROAS, CTR and conversion rate are basis points; CPA and CPC are micros; a ratio with no denominator is null (za-280).","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/AdsAnalyticsRange"},{"$ref":"#/components/parameters/AdsAnalyticsFrom"},{"$ref":"#/components/parameters/AdsAnalyticsTo"},{"$ref":"#/components/parameters/AdsAnalyticsCompare"},{"$ref":"#/components/parameters/AdsAnalyticsGrain"},{"$ref":"#/components/parameters/AdsAnalyticsNetwork"},{"$ref":"#/components/parameters/AdsAnalyticsConnection"},{"$ref":"#/components/parameters/AdsAnalyticsCampaign"},{"$ref":"#/components/parameters/AdsAnalyticsCountry"},{"$ref":"#/components/parameters/AdsAnalyticsDevice"},{"$ref":"#/components/parameters/AdsAnalyticsOffering"},{"$ref":"#/components/parameters/AdsAnalyticsClient"},{"$ref":"#/components/parameters/AdsAnalyticsCurrency"},{"name":"by","in":"query","required":false,"schema":{"type":"string","enum":["network","connection","campaign","country","device","offering","client"],"default":"campaign"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":25}}],"responses":{"200":{"description":"The figures.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsAnalyticsBreakdown"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/analytics/impact":{"get":{"operationId":"getAdsAnalyticsImpact","summary":"How Zinn® Ads helped - money saved, fraud blocked, refunds won, conversions recovered, changes and before vs after (za-281).","description":"Over the same filters as the other analytics reads: wasted spend blocked (search terms and keywords the audit found spending with no conversion, then blocked or paused, with the measured cost and clicks before the block), invalid clicks excluded by the click shield (their measured cost), credits the network granted for invalid activity, conversions Zinn® Ads uploaded that the network's own tag had missed, the changes Zinn® Ads made by kind (changes the customer made, in the dashboard or with their own API key, are not counted) with how many can still be undone, the self-check verdicts of the changes scored in the period, and ROAS over the 90 days before the first account was connected and since. `money_saved_micros` is waste blocked plus, per account and currency, the larger of fraud blocked and refunds won (a credit refunds the same invalid clicks the exclusions measured, so that money is counted once), all measured. `hours_saved` is a MODEL (changes times the stated minutes per change), flagged `modelled: true`. Each list is the latest 20 items with the full `count` beside it; a waste item carries the change that blocked it and whether it can still be undone. Network and account filters apply to every section. The campaign filter narrows waste blocked, fraud blocked (account-level exclusions stay), the self-check verdicts and before vs after; refunds won, conversions recovered and changes made are account-wide and ignore it. Country and product/site filters apply to before vs after only. A fraud item's Undo is offered only where the server accepts it: Google has named it, no removal is under way, and it was applied inside the 30-day undo window. Gated on `ads.view` over the organisations the person can view; `org_id` narrows to that organisation and its client organisations. Stored rows only, never a network call. Money is integer micros of the reporting `currency` at the current stored rate (`fx`).","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/AdsAnalyticsRange"},{"$ref":"#/components/parameters/AdsAnalyticsFrom"},{"$ref":"#/components/parameters/AdsAnalyticsTo"},{"$ref":"#/components/parameters/AdsAnalyticsCompare"},{"$ref":"#/components/parameters/AdsAnalyticsGrain"},{"$ref":"#/components/parameters/AdsAnalyticsNetwork"},{"$ref":"#/components/parameters/AdsAnalyticsConnection"},{"$ref":"#/components/parameters/AdsAnalyticsCampaign"},{"$ref":"#/components/parameters/AdsAnalyticsCountry"},{"$ref":"#/components/parameters/AdsAnalyticsDevice"},{"$ref":"#/components/parameters/AdsAnalyticsOffering"},{"$ref":"#/components/parameters/AdsAnalyticsClient"},{"$ref":"#/components/parameters/AdsAnalyticsCurrency"}],"responses":{"200":{"description":"The figures.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsAnalyticsImpact"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/analytics/funnel":{"get":{"operationId":"getAdsAnalyticsFunnel","summary":"The funnel impression -> click -> conversion -> paid, and the customer's own measured outcomes beside the network's conversions (za-282).","description":"Over the same filters as the other analytics reads. Impressions, clicks and conversions are the networks' stored daily figures under every filter. `paid` is the sales (purchases and upgrades, not refunded in full) the customer's OWN source recorded (store, checkout, plugin, CRM or the events API); a sale recorded on more than one ad account counts once per organisation. `truth` puts, per ad account that has ever sent an outcome, the conversions the network counted beside the outcomes the customer's own source recorded on the same days (the kinds the account's tracking settings compare), the gap, and the latest daily tracking-truth check. An account that never sent an outcome has no truth (never zero): it is counted in `untracked_accounts` and left out of both sides. Outcomes carry no campaign, country, device or product/site: with any of those filters `attributable` is false, `not_split_by` names them, `truth` and the `paid` step are null. Gated on `ads.view` over the organisations the person can view; `org_id` narrows to that organisation and its client organisations. Outcomes are windowed on each ad account's own day, in the account's stored time zone (UTC when none is stored yet), the same days as the network's figures and the daily tracking-truth check. A person who may view no organisation is refused (404), never answered with an empty frame. Stored rows only, never a network call. Money is integer micros of the reporting `currency` at the current stored rate (`fx`).","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/AdsAnalyticsRange"},{"$ref":"#/components/parameters/AdsAnalyticsFrom"},{"$ref":"#/components/parameters/AdsAnalyticsTo"},{"$ref":"#/components/parameters/AdsAnalyticsCompare"},{"$ref":"#/components/parameters/AdsAnalyticsGrain"},{"$ref":"#/components/parameters/AdsAnalyticsNetwork"},{"$ref":"#/components/parameters/AdsAnalyticsConnection"},{"$ref":"#/components/parameters/AdsAnalyticsCampaign"},{"$ref":"#/components/parameters/AdsAnalyticsCountry"},{"$ref":"#/components/parameters/AdsAnalyticsDevice"},{"$ref":"#/components/parameters/AdsAnalyticsOffering"},{"$ref":"#/components/parameters/AdsAnalyticsClient"},{"$ref":"#/components/parameters/AdsAnalyticsCurrency"}],"responses":{"200":{"description":"The funnel and the comparison.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsAnalyticsFunnel"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/analytics/markers":{"get":{"operationId":"getAdsAnalyticsMarkers","summary":"What happened on each day of the chart - the changes made and the anomalies, each anomaly linked to the changes before it (za-284).","description":"Over the same filters as the other analytics reads. Per bucket of the chart's grain: the changes APPLIED to an ad account in scope (an undone change too - it happened, then it was taken back), split by who made them (`zinn`: the daily audit, the autopilot, Simple mode, the assistant; `you`: a person in the dashboard or the customer's own API key), and the changes Google made in the account by itself (`google`; `google_breaks` of them broke one of the customer's own rules). `anomalies` are the days whose spend or conversions left the account's own pattern of the 14 days before (at least 7 of them with data): beyond three standard deviations, half the mean and a floor of one unit of the currency or two conversions. Today is never judged. Each anomaly counts the changes in the `link_days` days up to it (`linked`), and `linked_first_day`..`linked_last_day` is the window `GET /v1/ads/analytics/markers/items` lists them in. Changes are account-level: with a campaign, country, device or product/site filter they are still the whole account's, and `narrowed` says so. Gated on `ads.view` over the organisations the person can view; `org_id` narrows to that organisation and its client organisations; no organisation is a 404. Stored rows only, counted in the database. Anomaly values are integer micros of the reporting `currency` (conversions in thousandths).","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/AdsAnalyticsRange"},{"$ref":"#/components/parameters/AdsAnalyticsFrom"},{"$ref":"#/components/parameters/AdsAnalyticsTo"},{"$ref":"#/components/parameters/AdsAnalyticsCompare"},{"$ref":"#/components/parameters/AdsAnalyticsGrain"},{"$ref":"#/components/parameters/AdsAnalyticsNetwork"},{"$ref":"#/components/parameters/AdsAnalyticsConnection"},{"$ref":"#/components/parameters/AdsAnalyticsCampaign"},{"$ref":"#/components/parameters/AdsAnalyticsCountry"},{"$ref":"#/components/parameters/AdsAnalyticsDevice"},{"$ref":"#/components/parameters/AdsAnalyticsOffering"},{"$ref":"#/components/parameters/AdsAnalyticsClient"},{"$ref":"#/components/parameters/AdsAnalyticsCurrency"}],"responses":{"200":{"description":"The markers per bucket.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsAnalyticsMarkers"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/analytics/markers/items":{"get":{"operationId":"listAdsAnalyticsMarkerItems","summary":"The changes behind a chart marker, newest first, paged, each with its Undo state (za-284).","description":"The changes applied (`changes`) and the changes Google made by itself (`google`) in `marker_first`..`marker_last` (UTC days; default the screen's window), each list paged by the same `offset` and `limit` with its own full `count`. The window must lie inside the screen's window or the `link_days` before it (an anomaly's link window), else 422. A change carries `can_undo` while its 30-day Undo is open (`POST /v1/ads/changes/{change_id}/undo`); a Google change carries `undoable` while its Undo can still be asked for (`POST /v1/ads/connections/{connection_id}/google-changes/{change_id}/undo`). Same gate and filters as `GET /v1/ads/analytics/markers`.","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/AdsAnalyticsRange"},{"$ref":"#/components/parameters/AdsAnalyticsFrom"},{"$ref":"#/components/parameters/AdsAnalyticsTo"},{"$ref":"#/components/parameters/AdsAnalyticsCompare"},{"$ref":"#/components/parameters/AdsAnalyticsGrain"},{"$ref":"#/components/parameters/AdsAnalyticsNetwork"},{"$ref":"#/components/parameters/AdsAnalyticsConnection"},{"$ref":"#/components/parameters/AdsAnalyticsCampaign"},{"$ref":"#/components/parameters/AdsAnalyticsCountry"},{"$ref":"#/components/parameters/AdsAnalyticsDevice"},{"$ref":"#/components/parameters/AdsAnalyticsOffering"},{"$ref":"#/components/parameters/AdsAnalyticsClient"},{"$ref":"#/components/parameters/AdsAnalyticsCurrency"},{"name":"marker_first","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"marker_last","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":25}}],"responses":{"200":{"description":"One page of each list.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsAnalyticsMarkerItems"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/analytics/forecast":{"get":{"operationId":"getAdsAnalyticsForecast","summary":"This month's spend so far, the month-end forecast with its band, and the spend ceiling it is held against (za-284).","description":"Always the CURRENT month (UTC), over the screen's network, account, campaign, country, device and product/site filters (its date range does not apply). The forecast is the pacing card's own, per account: what it spent this month before today plus its mean daily spend over the last `rate_days` complete days for every day left, today included (on the account's own weekday pattern when its pacing strategy is `day_of_week`). The band is a MODEL: each day left varies like the last `rate_days` did, days independent, accounts summed by variance; `low`..`high` is the central `band_pct`% and never below what is spent. `days` is one point per day of the month: `actual` (cumulative spend) before today, `mid`/`low`/`high` from today to the month's last day. `ceiling`: the organisation's one cross-network monthly ceiling when every live account of it is in scope, else the sum of the accounts' own monthly ceilings; `complete` is false when an account in scope that spends has none (`missing` counts them), and `comparable` is false under a campaign, country, device or product/site filter (a ceiling is per account). `state`: `no_spend`, `no_ceiling`, `at_ceiling` (spent), `over` (the forecast passes it), `at_risk` (the band's top passes it) or `under`. Gated on `ads.view` like the other analytics reads. Stored rows only. Money is integer micros of the reporting `currency` at the current stored rate (`fx`).","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/AdsAnalyticsRange"},{"$ref":"#/components/parameters/AdsAnalyticsFrom"},{"$ref":"#/components/parameters/AdsAnalyticsTo"},{"$ref":"#/components/parameters/AdsAnalyticsCompare"},{"$ref":"#/components/parameters/AdsAnalyticsGrain"},{"$ref":"#/components/parameters/AdsAnalyticsNetwork"},{"$ref":"#/components/parameters/AdsAnalyticsConnection"},{"$ref":"#/components/parameters/AdsAnalyticsCampaign"},{"$ref":"#/components/parameters/AdsAnalyticsCountry"},{"$ref":"#/components/parameters/AdsAnalyticsDevice"},{"$ref":"#/components/parameters/AdsAnalyticsOffering"},{"$ref":"#/components/parameters/AdsAnalyticsClient"},{"$ref":"#/components/parameters/AdsAnalyticsCurrency"}],"responses":{"200":{"description":"The month-end forecast.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsAnalyticsForecast"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/analytics/narrative":{"post":{"operationId":"createAdsAnalyticsNarrative","summary":"The selected period in plain words - what moved, why, and where the month is heading - with every figure checked (za-285).","description":"Gated on `ads.view` (none anywhere is a `404`, nothing spent); the paying organisation is ONE organisation (`org_id` in the body, the query or `X-Zinn-Org` when the caller holds several; two that differ are a `422` `orgRequired` with detail code `mismatch`), and the figures are that organisation's and its client organisations' only - the same filters as every analytics read, in the query. Written by Zinn® AI from numbered facts built from the stored figures: the period's totals against the comparison period, the campaigns whose spend moved most, the unusual days with the changes made in the days before them (by Zinn® Ads, by people on the account, by Google), the change counts and, when the period reaches this month, the month-end forecast against the spend ceiling. Every number in `text` must be a figure of a fact it cites (`cites`, `facts`), or the narrative is `withheld` and never shown. Cached per (organisation, scope, period, data hash): the same view over the same figures is read back (`cached: true`) and never paid for twice; any changed figure is a new hash, a new narrative, and the old one for that scope and period is retired. A percentage must carry its fact's direction (`fell 20%` against `+20%` is withheld), a percent word is a percentage, and no number - not a small count, not a word such as `doubled` - is shown unless a cited fact holds it. Other languages: ONE batched translation for the reader's `locale` (normalised to a language we ship, e.g. `ar-EG` is `ar`; any other value is answered in English and buys nothing) and the languages the organisation's people read, each re-checked against the same facts the same way (a translation that changed a figure, or added a direction or a number word the English lacks, is dropped and never bought again for that text; a language the check cannot read is never bought and is answered in English; translations take at most half of the hourly brake and are metered under `ads_narrative` on the PLATFORM's own scope, never the customer's included allowance, and only for an org in good standing); `locale` in the reply is the language `text` is in (`en` until a translation is held). A percentage whose direction cannot be read, or a rise/fall word against a cited money figure's own direction, is withheld. `status`: `empty` (no spend in the period or before it; no model is asked), `writing` (another request is writing it; ask again shortly), `written`, `withheld`, `refused` (no AI credit, or not in good standing - `failure` class `refused`, nothing spent) or `failed` (the AI provider failed - `failure` names the class; nothing charged; the next view tries again). Who pays is the one meter's decision: the organisation's own AI key, else its Zinn® AI credit; the model is the cheapest verified, priced one. `422` codes: `analyticsFilter`, `narrativeHourly` (60 billed calls - writes and translations, failed ones included - per organisation per hour), `orgRequired`.","tags":["ads"],"parameters":[{"$ref":"#/components/parameters/AdsAnalyticsRange"},{"$ref":"#/components/parameters/AdsAnalyticsFrom"},{"$ref":"#/components/parameters/AdsAnalyticsTo"},{"$ref":"#/components/parameters/AdsAnalyticsCompare"},{"$ref":"#/components/parameters/AdsAnalyticsGrain"},{"$ref":"#/components/parameters/AdsAnalyticsNetwork"},{"$ref":"#/components/parameters/AdsAnalyticsConnection"},{"$ref":"#/components/parameters/AdsAnalyticsCampaign"},{"$ref":"#/components/parameters/AdsAnalyticsCountry"},{"$ref":"#/components/parameters/AdsAnalyticsDevice"},{"$ref":"#/components/parameters/AdsAnalyticsOffering"},{"$ref":"#/components/parameters/AdsAnalyticsClient"},{"$ref":"#/components/parameters/AdsAnalyticsCurrency"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"org_id":{"type":"string","format":"uuid"},"locale":{"type":"string","maxLength":16,"description":"The reader's language, e.g. en, ar."}}}}}},"responses":{"200":{"description":"The narrative (read back, or written now).","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsAnalyticsNarrative"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/analytics/views":{"get":{"operationId":"listAdsAnalyticsViews","summary":"The saved analytics views of the organisations the caller can see (za-286).","description":"Gated on `ads.view`. A saved view is a name over the `/ads/analytics` filters (`params`, exactly the analytics API's query parameters) and chart choices (`chart`: `metric`, `board`), shared by everyone in the organisation it was saved on. `org_id` narrows to that organisation. Ordered by organisation, then name.","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The saved views.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsSavedView"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createAdsSavedView","summary":"Save the current analytics view under a name (za-286).","description":"Gated on `ads.view`; scheduling its e-mail (`mail_cadence`, `mail_recipients`) needs `ads.manage` (`422 viewMailManage`). Audit action `ads.saved_view.save`. `params` is validated by the analytics filters themselves, so a view never stores a filter the page would refuse (`422 savedView` naming the field). A name already used in the organisation answers `422 viewNameTaken`. Recipients are user ids of MEMBERS of the organisation (`GET /v1/ads/analytics/views/recipients`), at most 20, else `422 viewRecipients`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsSavedViewInput"}}}},"responses":{"201":{"description":"The new view.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsSavedView"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/analytics/views/recipients":{"get":{"operationId":"listAdsSavedViewRecipients","summary":"The members of an organisation who can receive a saved view by e-mail (za-286).","description":"Gated on `ads.manage` (only a manager schedules a view). Name and e-mail of every member of `org_id` whose role grants `ads.view` there (a member who may not open the report is not a recipient).","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The members.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsSavedViewRecipient"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/analytics/views/{view_id}":{"patch":{"operationId":"updateAdsSavedView","summary":"Rename, re-save or schedule a saved view (za-286).","description":"Gated on `ads.view`; any e-mail field needs `ads.manage` (`422 viewMailManage`), and so does `name`, `params` or `chart` on a view that is e-mailed (`422 viewMailedManage`): that is what its recipients receive (the name is their subject line). Every recipient must be a member of the view's organisation whose role grants `ads.view` there, checked when it is scheduled and again at every send (a member who loses it stops receiving it). Only the fields sent change. `mail_cadence` `daily` sends at 06:00 UTC each day, `weekly` on Monday at 06:00 UTC, `monthly` on the 1st at 06:00 UTC, by a Temporal workflow; `\"\"` stops the e-mail. Each copy is in the recipient's own language and carries the view's headline figures, its top 10 leaderboard rows, a link to the view and the whole leaderboard as CSV. An organisation not in good standing is skipped for that period and resumes once it is. A refusal is per recipient: the others are still mailed, a retried send mails only the recipients not yet mailed that period, and a recipient refused 3 times is left until the next period (`mail_last_error` `recipientRefused`); while a refused recipient has had fewer than 3 refusals the view is retried within the hour. `mail_last_sent_at` moves only when a copy is accepted, and a period in which nobody received a copy is never reported as sent. Every copy carries its recipient's own one-click unsubscribe (`List-Unsubscribe` + `List-Unsubscribe-Post`, and a line in the body), `/v1/public/ads/views/u/{token}`. Audit action `ads.saved_view.save`.","tags":["ads"],"parameters":[{"name":"view_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsSavedViewPatch"}}}},"responses":{"200":{"description":"The view.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsSavedView"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"deleteAdsSavedView","summary":"Remove a saved view (za-286).","description":"Gated on `ads.view`; a view with a scheduled e-mail needs `ads.manage` (`422 viewMailManage`; removing it stops the e-mail). Audit action `ads.saved_view.delete`.","tags":["ads"],"parameters":[{"name":"view_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/analytics/views/{view_id}/send":{"post":{"operationId":"sendAdsSavedViewNow","summary":"E-mail a saved view to its recipients now (za-286).","description":"Gated on `ads.manage`; audit action `ads.saved_view.send`. Does not move the schedule. Refused (`422 notInGoodStanding`) when the organisation is not in good standing, `422 viewRecipients` when the view has no recipient, `422 mailRefused` when the mail service refused. Throttled per caller (`ads_report_send`, 300 per hour).","tags":["ads"],"parameters":[{"name":"view_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"How many were sent.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsSavedViewSent"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/ads/views/u/{token}":{"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"get":{"operationId":"unsubscribeAdsSavedViewByLink","summary":"The saved-view unsubscribe link opened in a browser - a confirm page whose button POSTs; GET itself changes nothing (za-286).","description":"Never unsubscribes: a mail scanner or link previewer fetching the link must not remove anyone. Renders a small page in the visitor's language (right to left where it reads so) with one button that POSTs `confirm=1` back to this URL. The same page whatever the token (no oracle); `Cache-Control: no-store`, `noindex`, `Referrer-Policy: no-referrer`.","tags":["public"],"security":[],"responses":{"200":{"description":"The confirm page.","content":{"text/html":{"schema":{"type":"string"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"oneClickUnsubscribeAdsSavedView","summary":"RFC 8058 one-click unsubscribe from one saved-view e-mail (the List-Unsubscribe URL on each copy, za-286).","description":"RFC 8058 one-click (`List-Unsubscribe=One-Click` from a mail client) answers `200` with no body; the confirm page's button (`confirm=1`) answers `303` to the site's unsubscribed page in the visitor's language. The same whatever the token (no oracle). Takes that one recipient off that one saved view; when they were the last, the view's e-mail is turned off. Nothing else they receive changes. Its own token budget (`public_ads_view_unsubscribe`, 600 per hour per address: one-click POSTs come from a mail provider's few shared servers), separate from the newsletter's.","tags":["public"],"security":[],"requestBody":{"required":false,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"List-Unsubscribe":{"type":"string","enum":["One-Click"]},"confirm":{"type":"string","enum":["1"]}}}}}},"responses":{"200":{"description":"Unsubscribed (or nothing to do)."},"303":{"description":"From the confirm page - redirect to the site's unsubscribed page."},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/ads/analytics/export/{token}":{"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"get":{"operationId":"downloadAdsAnalyticsExportByLink","summary":"One analytics table as CSV or XLSX from the signed download link the ads_analytics_export MCP tool returns (za-286).","description":"Auth model: no session and no bearer header (`security: []`) - the path `token` IS the credential, a signed single-use capability. The view enforces `ads.view` by proxy: the `ads_analytics_export` MCP tool checks `ads.view` on the caller's MCP grant, resolves the caller's organisations exactly as `GET /v1/ads/analytics/export` does (narrowed by `org_id` to that organisation and its clients) and signs them (HMAC, Django signing with its own salt), with the filters, `table`, `file`, `by`, `locale`, the issuing MCP grant and its organisation, into a link valid for 15 minutes. Each link is also a durable row (`AdsExportLink`, tenant-scoped by RLS); every signed value must equal that row. The file is the same one `exportAdsAnalyticsTable` streams. Every unusable link - tampered, expired, the MCP grant that minted it revoked since, an organisation no longer in good standing, or a table or filter that no longer parses - answers the same `404` (no oracle). A link is single-use: a second download answers `410`. Every answer, refusals included, carries `Cache-Control: no-store` and `Referrer-Policy: no-referrer`; the token is kept out of access logs, traces and the audit trail. Its own budget (`public_ads_analytics_export_link`, 120 per hour per address, fails closed).","tags":["public"],"security":[],"responses":{"200":{"description":"The file, as an attachment.","headers":{"Cache-Control":{"schema":{"type":"string","enum":["no-store"]}},"Referrer-Policy":{"schema":{"type":"string","enum":["no-referrer"]}}},"content":{"text/csv":{"schema":{"type":"string"}},"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}},"404":{"$ref":"#/components/responses/NotFound"},"410":{"description":"The link was already downloaded once; it is single-use. Ask the AI assistant for a new one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/analytics/export":{"get":{"operationId":"exportAdsAnalyticsTable","summary":"One analytics table as CSV or XLSX, every row (za-286).","description":"Gated on `ads.view`, over the same filters as the analytics reads. `table`: `breakdown` (the leaderboard, grouped by `by`), `currencies`, `truth` (network-reported vs measured conversions per account), `impact_changes`, `impact_fraud`, `impact_waste` or `impact_refunds`. EVERY row is written, streamed - the page's 25-row page and the panels' latest 20 are page sizes, not export sizes. Column names are in `locale`; each money column is written twice, formatted in `locale` and as an integer in MINOR units of the stated currency (`... (minor units)`); ratios are plain numbers (ROAS 3.25, CTR in per cent). CSV is UTF-8 with a byte-order mark and guards formula-like cells with a leading apostrophe; XLSX is right to left for Arabic and Hebrew. Throttled per caller (`ads_analytics_export`, 600 per hour). A bad `table` or `file` answers `422 exportTable`.","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"table","in":"query","required":false,"schema":{"type":"string","enum":["breakdown","currencies","truth","impact_changes","impact_fraud","impact_waste","impact_refunds"],"default":"breakdown"}},{"name":"file","in":"query","required":false,"schema":{"type":"string","enum":["csv","xlsx"],"default":"csv"}},{"name":"by","in":"query","required":false,"schema":{"type":"string","enum":["network","connection","campaign","country","device","offering","client"],"default":"campaign"}},{"name":"locale","in":"query","required":false,"schema":{"type":"string","default":"en"}},{"$ref":"#/components/parameters/AdsAnalyticsRange"},{"$ref":"#/components/parameters/AdsAnalyticsFrom"},{"$ref":"#/components/parameters/AdsAnalyticsTo"},{"$ref":"#/components/parameters/AdsAnalyticsCompare"},{"$ref":"#/components/parameters/AdsAnalyticsGrain"},{"$ref":"#/components/parameters/AdsAnalyticsNetwork"},{"$ref":"#/components/parameters/AdsAnalyticsConnection"},{"$ref":"#/components/parameters/AdsAnalyticsCampaign"},{"$ref":"#/components/parameters/AdsAnalyticsCountry"},{"$ref":"#/components/parameters/AdsAnalyticsDevice"},{"$ref":"#/components/parameters/AdsAnalyticsOffering"},{"$ref":"#/components/parameters/AdsAnalyticsClient"},{"$ref":"#/components/parameters/AdsAnalyticsCurrency"}],"responses":{"200":{"description":"The file.","content":{"text/csv":{"schema":{"type":"string","format":"binary"}},"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/report/rows":{"get":{"operationId":"listAdsReportRows","summary":"Daily campaign rows for Looker Studio (za-200).","description":"Gated on `ads.view`. One row per day, ad account and campaign over `start`..`end` (inclusive, at most 400 days) for the organisations the caller may view; `org_id` narrows to that organisation and its clients. Built for the Zinn® Ads Looker Studio community connector, which authenticates with an API key minted on ONE client organisation with only the `ads.view` scope, so the key reads that client and nothing else. Spend and value are integer micros of the account currency (`currency` on every row); conversions are thousandths. Paged: follow `next_offset` until it is `null`. Stored rows only - never a network call in the request.","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"start","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"end","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"One page of rows.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsReportRows"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/report/pdf":{"get":{"operationId":"getAdsReportPdf","summary":"One client's white-label advertising report as a PDF (za-200).","description":"Gated on `ads.view`. The same document a scheduled report e-mails: the client organisation's figures (and its sub-organisations') over the last `days` days, under the brand that organisation renders under (the agency's white label), in `locale` (any of the 58 platform languages; Arabic and Hebrew right to left). Stored rows only. Throttled per caller (`ads_report_render`, 300 per hour) on top of the account limits.","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"days","in":"query","required":false,"schema":{"type":"integer","enum":[7,30,90],"default":30}},{"name":"locale","in":"query","required":false,"schema":{"type":"string","default":"en"}}],"responses":{"200":{"description":"The PDF.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/report/schedules":{"get":{"operationId":"listAdsReportSchedules","summary":"The scheduled white-label PDF reports (za-200).","description":"Gated on `ads.view`. Every schedule in the organisations the caller may view; `org_id` narrows to that organisation and its clients.","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The schedules.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsReportSchedule"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"saveAdsReportSchedule","summary":"Create or replace a client's weekly or monthly PDF report (za-200).","description":"Gated on `ads.manage`; audit action `ads.report_schedule.save`. One schedule per client organisation and cadence: posting the same cadence again replaces it (200), a new one answers 201. Weekly reports are sent on Monday at 06:00 UTC, monthly ones on the 1st at 06:00 UTC, by a Temporal workflow. A bad field answers `422 badLimit` naming it.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsReportScheduleInput"}}}},"responses":{"200":{"description":"The replaced schedule.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsReportSchedule"}}}}}},"201":{"description":"The new schedule.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsReportSchedule"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/report/schedules/{schedule_id}":{"patch":{"operationId":"updateAdsReportSchedule","summary":"Change a scheduled report's recipients, language, window or on/off (za-200).","description":"Gated on `ads.manage`; audit action `ads.report_schedule.save`.","tags":["ads"],"parameters":[{"name":"schedule_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"recipients":{"type":"array","items":{"type":"string","format":"email"},"minItems":1,"maxItems":10},"locale":{"type":"string"},"window_days":{"type":"integer","enum":[7,30,90]},"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"The schedule.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsReportSchedule"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"deleteAdsReportSchedule","summary":"Stop and remove a scheduled report (za-200).","description":"Gated on `ads.manage`; audit action `ads.report_schedule.delete`.","tags":["ads"],"parameters":[{"name":"schedule_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/report/schedules/{schedule_id}/send":{"post":{"operationId":"sendAdsReportScheduleNow","summary":"E-mail this period's report now, without moving the schedule (za-200).","description":"Gated on `ads.manage`; audit action `ads.report_schedule.send`. Refused with `422 notInGoodStanding` when the paying organisation is not in good standing. Throttled per caller (`ads_report_send`, 300 per hour) on top of the account limits.","tags":["ads"],"parameters":[{"name":"schedule_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"How many recipients the report went to.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["schedule_id","recipients"],"properties":{"schedule_id":{"type":"string","format":"uuid"},"recipients":{"type":"integer"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/network-notices":{"get":{"operationId":"listAdsNetworkNotices","summary":"The ad-network changes that affect this organisation's accounts (za-195).","description":"Gated on `ads.view`. Each item is one staff-curated vendor change (dated, with the vendor's own source page) matched against one connection by the daily audit: which campaigns or ad groups it affects, what to do, and the pending safe fix (`change_id`) where one exists. Acknowledged notices are not listed.","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The open notices.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsNoticeMatch"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/network-notices/{match_id}/acknowledge":{"post":{"operationId":"acknowledgeAdsNetworkNotice","summary":"Mark a network notice as seen; it never shows, mails or re-proposes again.","description":"Gated on `ads.manage`; idempotent; audit action `ads.network_notice.acknowledge`. Another organisation's id answers `422 noSuchNotice`.","tags":["ads"],"parameters":[{"name":"match_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The acknowledged notice.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsNoticeMatch"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/chat-channels":{"get":{"operationId":"listAdsChatChannels","summary":"The organisation's Slack and Microsoft Teams alert channels (za-198).","description":"Gated on `ads.view`. Never returns a webhook URL (it is the credential and lives in Vault); `hint` is its host only. `alerts`, `kinds` and `max_items` describe the choices.","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The channels.","content":{"application/json":{"schema":{"type":"object","required":["data","alerts","kinds","max_items"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsChatChannel"}},"alerts":{"type":"array","items":{"type":"string","enum":["needs","changes","alerts"]}},"kinds":{"type":"array","items":{"type":"string","enum":["slack","teams"]}},"max_items":{"type":"integer","description":"Most items in one chat message (§2.50)."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createAdsChatChannel","summary":"Connect a Slack incoming webhook or a Microsoft Teams Workflows webhook.","description":"Gated on `ads.manage`; audit action `ads.chat_channel_create`. The URL must be a Slack incoming webhook (`https://hooks.slack.com/services/…`) or a Teams Workflows webhook (`*.logic.azure.com` / `*.api.powerplatform.com`, path `/workflows/`), else `422 chatChannelUrl`. It is stored in Vault and never returned. Each day's Zinn® Ads alert is posted there by Temporal, capped at `max_items` items with a \"+N more\" count; each change carries its 30-day Undo link.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kind","webhook_url"],"properties":{"org_id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["slack","teams"]},"label":{"type":"string","maxLength":80},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"writeOnly":true},"alerts":{"type":"array","minItems":1,"items":{"type":"string","enum":["needs","changes","alerts"]},"description":"Defaults to all three."}}}}}},"responses":{"201":{"description":"Connected.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsChatChannel"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/chat-channels/{channel_id}":{"parameters":[{"name":"channel_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"operationId":"updateAdsChatChannel","summary":"Rename a chat channel, choose its alerts, switch it on or off, or replace its URL.","description":"Gated on `ads.manage`; audit action `ads.chat_channel_update`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"org_id":{"type":"string","format":"uuid"},"label":{"type":"string","maxLength":80},"enabled":{"type":"boolean"},"alerts":{"type":"array","minItems":1,"items":{"type":"string","enum":["needs","changes","alerts"]}},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"writeOnly":true}}}}}},"responses":{"200":{"description":"The channel.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsChatChannel"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"deleteAdsChatChannel","summary":"Disconnect a chat channel and delete its webhook from Vault.","description":"Gated on `ads.manage`; audit action `ads.chat_channel_delete`.","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Disconnected."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/chat-channels/{channel_id}/test":{"parameters":[{"name":"channel_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"testAdsChatChannel","summary":"Post a test message to the channel now.","description":"Gated on `ads.manage`; audit action `ads.chat_channel_test`. One real post (interactive, never queued). A failure is a class, never the vendor's text: `channel_gone` (the webhook was removed or is not allowed — reconnect it), `channel_unreachable` (Slack or Teams could not be reached — try again), `bad_url`, `our_fault`.","tags":["ads"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"The result of the test post.","content":{"application/json":{"schema":{"type":"object","required":["ok","failure","data"],"properties":{"ok":{"type":"boolean"},"failure":{"type":"string","enum":["","channel_gone","channel_unreachable","bad_url","our_fault"]},"data":{"$ref":"#/components/schemas/AdsChatChannel"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/controls":{"get":{"operationId":"getAdsControls","summary":"The organisation's kill switch and daily e-mail setting.","description":"Gated on `ads.view`. `global_killed` is the platform-wide switch.","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The controls.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsControls"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"updateAdsControls","summary":"Turn the organisation's kill switch or daily e-mail on or off.","description":"Gated on `ads.manage`; audit action `ads.controls_update`. With `killed: true` nothing is written to any of the organisation's ad accounts (Undo still works).","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"org_id":{"type":"string","format":"uuid"},"killed":{"type":"boolean"},"daily_email":{"type":"boolean"},"report_email":{"type":"boolean","description":"The weekly return-on-ad-spend e-mail and the monthly growth review (za-08)."}}}}}},"responses":{"200":{"description":"The controls.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsControls"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/history-imports":{"get":{"operationId":"listAdsHistoryImports","summary":"The Recommended history-import thresholds and this ad account's history imports.","description":"Gated on `ads.view` (za-159, docs/1006 §80). `recommended` is the default threshold set (the settings card's \"Reset to Recommended\"); `imports` lists this connection's imports, newest first, each with its evidence and the starting values it seeded.","tags":["ads"],"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The thresholds and the imports.","content":{"application/json":{"schema":{"type":"object","required":["recommended","imports"],"properties":{"recommended":{"$ref":"#/components/schemas/AdsHistoryThresholds"},"imports":{"type":"array","items":{"$ref":"#/components/schemas/AdsHistoryImport"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"startAdsHistoryImport","summary":"Import an older ad account's history and the revenue to seed the autopilot's starting values.","description":"Gated on `ads.manage`; audit action `ads.history_import_start`. Reads the older account (`source_connection_id`, a Google Ads or Microsoft Advertising connection of the SAME organisation, read-only) month by month in a resumable workflow, with the revenue Zinn® Ads already holds (`first_party`), an uploaded CSV (`csv`: `source,country,device,revenue,customers`, at most 2 MB) or none. It seeds a target CPA and ROAS, the countries to start with and to exclude, and device bid modifiers, each with its evidence. Account seeds become pending changes in the approval queue; nothing is written to an ad account here. A source in another organisation answers 422 `sourceNotYours` (or 404 when the caller cannot see it). Other 422 codes: `sameAccount`, `sourceUnsupported`, `badRevenueSource`, `nothingToImport`, `badThreshold`, `csvTooLarge`, `badCsvHeader`, `badCsvCountry`, `badCsvDevice`, `badCsvAmount`, `emptyCsv`.","tags":["ads"],"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"org_id":{"type":"string","format":"uuid"},"source_connection_id":{"type":"string","description":"The older connection (uuid); empty = revenue only."},"revenue_source":{"type":"string","enum":["first_party","csv","none"],"default":"first_party"},"csv":{"type":"string","maxLength":2000000},"thresholds":{"$ref":"#/components/schemas/AdsHistoryThresholdsInput"}}}}}},"responses":{"202":{"description":"The import, queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsHistoryImport"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/history-imports/{import_id}":{"get":{"operationId":"getAdsHistoryImport","summary":"One history import — its progress, its evidence and the starting values it seeded.","description":"Gated on `ads.view` (za-159, docs/1006 §80).","tags":["ads"],"parameters":[{"name":"import_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The import.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsHistoryImport"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/history-imports/{import_id}/seeds/{key}/accept":{"post":{"operationId":"acceptAdsHistorySeed","summary":"Accept one seeded Zinn® Ads setting (countries to start with, countries to exclude, target ROAS).","description":"Gated on `ads.manage`; audit action `ads.history_seed_accept`. Writes the seed to the ad account's Zinn® Ads settings: `start_countries` ADDS its countries to the markets and removes none (OWNERFIX-A); a market is removed only when it is listed in `drop`, and only a country in the seed's `value.drop` (spent, nothing back) can be (422 `badDrop` otherwise). The seed records `added` and `dropped`, as does the audit entry. `excluded_countries` adds to the customer's own exclusion list, `roas_target_pct` sets the ROAS target. An account seed is approved in the change queue instead; it answers 422 `noSuchSeed`.","tags":["ads"],"parameters":[{"name":"import_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"key","in":"path","required":true,"schema":{"type":"string","enum":["start_countries","excluded_countries","roas_target_pct"]}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"drop":{"type":"array","description":"`start_countries` only: the markets the person ticked to remove, each from the seed's `value.drop`.","items":{"type":"string","pattern":"^[A-Za-z]{2}$"}}}}}}},"responses":{"200":{"description":"The import, with the seed marked accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsHistoryImport"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/autopilot-decisions":{"get":{"operationId":"getAdsAutopilotDecisions","summary":"The organisation's autopilot decisions — pinned and held campaigns, protected keywords.","description":"Gated on `ads.view` (za-166, docs/1006 §77). One record per organisation; every automatic change (auto-raise, budget shift, waste-term and conflict negatives, poor-keyword pauses, new-country campaigns, ad fixes, the tidy) is checked against it at the write gate. `held_back` lists the latest automatic changes it held back (\"what would I have done\"), newest first; `held_back_total` counts every one.","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The decisions record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsAutopilotDecisions"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateAdsAutopilotDecisions","summary":"Set the campaigns the autopilot must not touch and the keywords it must protect.","description":"Gated on `ads.manage`; audit action `ads.autopilot_decisions_update`. A field left out keeps its value. A held campaign gets no automatic change at all; a pinned campaign keeps its budget and bidding; a protected keyword is never paused or added as a negative by itself. A person's approved change and an Undo are never bound. Campaign ids are digits; keywords are compared without match-type brackets, case-insensitively. A refused list answers 422 with one `code`: `notAList`, `notStrings`, `entryLength`, `campaignNotDigits` or `tooManyEntries`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"org_id":{"type":"string","format":"uuid"},"pinned_campaigns":{"type":"array","maxItems":5000,"items":{"type":"string","pattern":"^[0-9]+$"}},"held_campaigns":{"type":"array","maxItems":5000,"items":{"type":"string","pattern":"^[0-9]+$"}},"protected_keywords":{"type":"array","maxItems":5000,"items":{"type":"string","maxLength":200}}}}}}},"responses":{"200":{"description":"The decisions record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsAutopilotDecisions"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/seasonal":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsSeasonalPlanner","summary":"The seasonal planner per country — demand by month, thresholds and dated proposals.","description":"Gated on `ads.view`. Read from our own rows (no network call): every country the account advertises in with its demand index by calendar month (100 = the country's average month) and its `source` — `history` (the account's own clicks by month and country), `planner` (Keyword Planner monthly search volumes, read on the house account where the history is thin) or `none` (no proposal is made from a guess). `plans` are the dated proposals ahead of a peak or quiet month: a budget change for the month (restored after `ends_on`) and, where the conversion rate moves and the campaigns use Smart Bidding, a Google Ads seasonality adjustment for the first days. Every write is an ads change that a person approves (`/v1/ads/changes/{id}/approve`). `settings` carries each threshold's value, Recommended default and bounds. Measured weekly by the daily audit (Temporal; docs/1006 §81).","tags":["ads"],"responses":{"200":{"description":"The seasonal planner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsSeasonalPlanner"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setAdsSeasonalPlanner","summary":"Edit the seasonal planner's thresholds or mode, or reset them to Recommended.","description":"Gated on `ads.manage`; audit action `ads.seasonal_settings`. `settings` keys: `peak_pct`, `quiet_pct`, `lead_days`, `budget_max_pct`, `min_history_months`, `min_clicks`, `bid_days`, `bid_min_change_pct`, `bid_min_conversions`; `null` sets one back to Recommended. `mode` `suggest` or `off`. `reset: true` sets every one back to Recommended. A value outside its bounds is refused `refusal.adsconnect.badSeasonalSetting`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reset":{"type":"boolean"},"mode":{"type":"string","enum":["suggest","off"]},"settings":{"type":"object","additionalProperties":{"type":["integer","null"]}}}}}}},"responses":{"200":{"description":"The seasonal planner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsSeasonalPlanner"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/connections/{connection_id}/seasonal/plans/{plan_id}/dismiss":{"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"plan_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"dismissAdsSeasonalPlan","summary":"Dismiss one seasonal proposal; its pending changes are rejected.","description":"Gated on `ads.manage`; audit action `ads.seasonal_dismiss`. Only a `proposed` plan can be dismissed (`refusal.adsconnect.badState`); an unknown plan is `refusal.adsconnect.badPick`. A dismissed period is never proposed again.","tags":["ads"],"responses":{"200":{"description":"The seasonal planner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsSeasonalPlanner"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/brief":{"get":{"operationId":"getAdsBrief","summary":"The one brief across every ad network, and the split it drives.","description":"Gated on `ads.view`. Read from our own rows (no network call): the objective (`leads` or `revenue`), the monthly budget, the optional target and the test share, and per network its current and proposed monthly ceiling and `why` (`bestReturn`, `offTarget`, `testShare`, `held`, `unreadable`, `otherCurrency`, `noReturn`), plus the versions saved in the last 30 days. The split is the cross-network budget's proposal (docs/1006 §113, §67), measured daily by a Temporal workflow and applied with `applyAdsCrossBudget`.","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The brief and the split it drives.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsBrief"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setAdsBrief","summary":"State the objective and the budget once, for every network.","description":"Gated on `ads.manage`; audit action `ads.brief_set`. Sets the cross-network monthly ceiling to `budget_minor` and ranks the split by `objective`; the brief it replaces is kept 30 days for `undoAdsBrief`. Measured again now by a Temporal workflow, never in the request; nothing is applied (approve-first unless `mode: auto`). Refusals `refusal.adsconnect.briefBadObjective`, `briefBadBudget`, `briefBadCurrency`, `briefBadTarget`, `briefBadTestShare`, `briefBadMode`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["objective","budget_minor","currency"],"properties":{"org_id":{"type":"string","format":"uuid"},"objective":{"type":"string","enum":["leads","revenue"]},"budget_minor":{"type":"integer","minimum":1,"maximum":1000000000,"description":"The monthly budget, integer minor units of `currency` (§2.8)."},"currency":{"type":"string","maxLength":3,"description":"ISO 4217"},"target":{"type":["integer","null"],"minimum":1,"description":"`leads` — a cost per conversion in minor units; `revenue` — a ROAS in %."},"test_share_pct":{"type":"integer","minimum":0,"maximum":30,"description":"The share the networks with no measured return test with (recommended 10)."},"mode":{"type":"string","enum":["suggest","auto"]}}}}}},"responses":{"200":{"description":"The brief and the split it drives.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsBrief"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"clearAdsBrief","summary":"Remove the brief (the budget stays, split by conversions per spend).","description":"Gated on `ads.manage`; audit action `ads.brief_clear`. Kept as a version, so it can be undone within 30 days.","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The brief and the split it drives.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsBrief"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/brief/undo":{"post":{"operationId":"undoAdsBrief","summary":"Put back the brief the last save replaced.","description":"Gated on `ads.manage`; audit action `ads.brief_undo`. Refused with `refusal.adsconnect.briefNothingToUndo` when no version from the last 30 days is left.","tags":["ads"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"The brief and the split it drives.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsBrief"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/cross-budget":{"get":{"operationId":"getAdsCrossBudget","summary":"The organisation's one monthly ceiling across every ad network, and today's proposal.","description":"Gated on `ads.view`. Read from our own rows (no network call): each network's last-30-day spend, conversions and value, why money does not move to or from one (`reason`: `otherCurrency`, `held`, `unreadable`, `noReturn`), and the proposal (the new monthly ceiling per network, never past the one ceiling; `blocked: noReturnYet` until at least one network has a measured return). Measured once a day by a Temporal workflow (docs/1006 §67).","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The cross-network budget.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsCrossBudget"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setAdsCrossBudget","summary":"Set or clear the one monthly ceiling across every network, and the mode.","description":"Gated on `ads.manage`; audit action `ads.cross_budget_set`. `ceiling_minor: null` clears it. `mode` `suggest` (the person applies) or `auto` (applied daily, Undo still works). A new ceiling is measured now by a Temporal workflow, never in the request. Refusals `refusal.adsconnect.crossBadCeiling`, `crossBadCurrency`, `crossBadMode`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ceiling_minor"],"properties":{"org_id":{"type":"string","format":"uuid"},"ceiling_minor":{"type":["integer","null"],"minimum":1,"maximum":1000000000,"description":"Integer minor units of `currency` (§2.8)."},"currency":{"type":"string","maxLength":3,"description":"ISO 4217"},"mode":{"type":"string","enum":["suggest","auto"]}}}}}},"responses":{"200":{"description":"The cross-network budget.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsCrossBudget"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/cross-budget/apply":{"post":{"operationId":"applyAdsCrossBudget","summary":"Apply today's proposal to each network's monthly ceiling.","description":"Gated on `ads.manage`; audit action `ads.cross_budget_apply`. Changes our own per-network ceilings only, never an ad account. Refused when the organisation is not in good standing (`refusal.adsconnect.notInGoodStanding`), when there is nothing to apply (`crossNothingToApply`) or when the result would pass the ceiling (`crossOverCeiling`).","tags":["ads"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"The cross-network budget.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsCrossBudget"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/cross-budget/undo":{"post":{"operationId":"undoAdsCrossBudget","summary":"Put back the monthly ceilings from before the last apply.","description":"Gated on `ads.manage`; audit action `ads.cross_budget_undo`. Refused with `refusal.adsconnect.crossNothingToUndo` when the last apply was already undone.","tags":["ads"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"The cross-network budget.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsCrossBudget"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/own-share":{"get":{"operationId":"getAdsOwnShare","summary":"What this company learned across its own ad accounts, and the sharing setting.","description":"Gated on `ads.view`. Read from our own rows (no network call). A company is a client organisation and its own descendant orgs; sibling clients under an agency or reseller are separate businesses, and an agency's own accounts share only among themselves, never with its clients. Learning is shared only inside the company, never with another customer. `learned` holds, per kind (negative, placement, ip, term, keyword, country, adcopy), the count and the strongest few, each with the account it was learned in, for the whole company of the org asked about (an org the caller may see). `shared_changes` counts the shared changes by status. The sharing runs daily on the `zinn-ads-own-share` Temporal schedule (docs/1006 §OWNSHARE).","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The company's shared learning.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsOwnShare"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"setAdsOwnShare","summary":"Turn sharing across this company's own accounts on or off, and choose the mode.","description":"Gated on `ads.manage`; audit action `ads.own_share_set`. `share_learning: false` stops this org's accounts giving or receiving. `share_mode` `approve` (default: every shared change waits for a person through the change gate) or `auto` (applied, metered, Undo kept). A rejected shared change is never offered again.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"org_id":{"type":"string","format":"uuid"},"share_learning":{"type":"boolean"},"share_mode":{"type":"string","enum":["approve","auto"]}}}}}},"responses":{"200":{"description":"The company's shared learning.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsOwnShare"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/social":{"get":{"operationId":"getAdsSocial","summary":"The social-network autopilot on this org's X, Meta and TikTok accounts.","description":"Gated on `ads.view`. Read from our own rows (no network call). Per X and Meta account: `levers` says what the autopilot judges there (`audiences` and `creatives` are judged by the scheduled audit; Meta `placements` by the placement guard and `budgets` by the cross-network budget, `elsewhere` with the screen in `where`; X offers no placement change on a running line item, `not_offered`). `review` is the latest audit: audiences (X line items, Meta ad sets) and creatives (X promoted Tweets, Meta ads) judged, the spend found wasted (`waste_micros`, micros of the account currency: spend with no conversion), what was proposed or applied and `findings` (at most 50). A creative is stopped only while its audience keeps another creative that is not waste. `needs_permission` means Meta has not granted Zinn® Ads `ads_management` (Pinterest: `ads:write`, PINFULL), or (TTFULL) TikTok answered that this grant cannot write (measured, `vendor_grants.writes` false): judged, nothing proposed. TikTok and Pinterest audiences are ad groups and their creatives are ads (Pinterest: promoted Pins), and only SERVING ones are judged. `pending` counts the pauses waiting for a person (docs/1006 §121, za-55).","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The social accounts and their latest review.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsSocial"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/builds":{"get":{"operationId":"listAdsBuilds","summary":"The organisation's Simple-mode Google Ads plans, newest first (at most 20).","description":"Gated on `ads.view` (docs/1006 §4.2). The list carries each plan's inputs and status, not its full plan; read one plan with `getAdsBuild`.","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The plans.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsBuild"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createAdsBuild","summary":"Start a Simple-mode plan from a website, a monthly budget and markets.","description":"Gated on `ads.manage`; audit action `ads.build_create`. Records the inputs and starts the site scan as a Temporal workflow (status `scanning` -> `scanned`), in which the AI pre-fills `offer` (\"what do you sell\") from the site. `monthly_budget_minor` is integer minor units of `currency` (§2.8); `markets` are 1-8 `{country: ISO 3166-1 alpha-2, language}` pairs Google Ads can target. Nothing reaches Google.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","monthly_budget_minor","currency","markets"],"properties":{"org_id":{"type":"string","format":"uuid"},"url":{"type":"string","maxLength":500},"monthly_budget_minor":{"type":"integer","minimum":1,"maximum":1000000000000},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$"},"markets":{"type":"array","minItems":1,"maxItems":8,"items":{"$ref":"#/components/schemas/AdsBuildMarket"}},"offer":{"type":"string","maxLength":1000},"offers_free":{"type":"boolean","description":"za-251 (NEGPLAN): \"This product has a free plan / free listing\". `true`: the plan adds no \"free\" class negative (free, for free, gratis, freebie…) and keeps \"free …\" searches as keywords; `false` (the default): they are blocked."}}}}}},"responses":{"201":{"description":"The plan, scanning.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsBuild"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/builds/{build_id}":{"parameters":[{"name":"build_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsBuild","summary":"One Simple-mode plan in full.","description":"Gated on `ads.view`. `plan` holds the campaigns per market (brand / generic / competitor) with keywords (measured monthly volume, CPC in minor units), negatives, daily budgets (Google micros), the responsive search ads per language with the page words each line quotes, the ad-policy findings, and the forecast as a low / expected / high range with its assumptions.","tags":["ads"],"responses":{"200":{"description":"The plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsBuild"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateAdsBuild","summary":"Change what they sell, the budget, the currency, the markets or the site languages before (re)building.","description":"Gated on `ads.manage`. Refused (`busy`) while it is scanning, building or launched.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"monthly_budget_minor":{"type":"integer","minimum":1,"maximum":1000000000000},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$"},"markets":{"type":"array","minItems":1,"maxItems":8,"items":{"$ref":"#/components/schemas/AdsBuildMarket"}},"offer":{"type":"string","maxLength":1000},"offers_free":{"type":"boolean","description":"za-251 (NEGPLAN): \"This product has a free plan / free listing\". `true`: the plan adds no \"free\" class negative (free, for free, gratis, freebie…) and keeps \"free …\" searches as keywords; `false` (the default): they are blocked."},"languages":{"type":"array","maxItems":60,"description":"za-106: confirm or override the detected site languages — Google codes, or rows with the language's own https address. `[]` = use what was detected.","items":{"oneOf":[{"type":"string"},{"$ref":"#/components/schemas/AdsSiteLanguage"}]}}}}}}},"responses":{"200":{"description":"The plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsBuild"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/builds/{build_id}/build":{"parameters":[{"name":"build_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"runAdsBuild","summary":"Build (or rebuild) the plan from the current inputs.","description":"Gated on `ads.manage`; audit action `ads.build_run`. Starts the build workflow (status `building` -> `ready` or `failed` with an `error.code`): keyword research per market (billed vendor spend — refused for an organisation not in good standing, §2.46), the ads (AI on the organisation's own key or its Zinn® AI credits, one meter), the policy pre-check and the forecast. Nothing reaches Google.","tags":["ads"],"responses":{"202":{"description":"The plan, building.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsBuild"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/builds/{build_id}/launch":{"parameters":[{"name":"build_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"launchAdsBuild","summary":"Turn a ready plan into approve-first queued changes on one connected account.","description":"Gated on `ads.manage`; audit action `ads.build_launch`. Each campaign becomes ONE pending change (a `googleAds:mutate` request creating its budget, campaign, targeting, negatives, ad groups, keywords and ads), plus one for the conversion action. NOTHING is sent: every change waits in the approval queue (`listAdsChanges`) whatever the account's modes, and the kill switches, spend ceilings and good standing still decide when it is approved. Refused when the account is paused or killed, or its currency is not the plan's. Also refused `briefLaunched` once a brief made from this plan has queued a network (its budget is shared there: add Google Ads from the brief), and `offeringCeiling` when the whole budget would take the brief's product over its own monthly ceiling (za-290). Refused `planStale` when the budget or currency was edited after the plan was built: rebuild the plan first (its campaign budgets carry the number it was built for).","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["connection_id"],"properties":{"connection_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"The plan, launched (its `change_ids` wait for approval).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsBuild"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/offerings":{"get":{"operationId":"listAdsOfferings","summary":"Search the things the organisation advertises (sites, products, services, apps, locations, events, lead forms, offers).","description":"Gated on `ads.view` (za-290). No cap on how many an organisation has: the list is keyset paginated by name (`next_cursor`), filtered by `q` (name or host), `kind` and `tag`, and costs two queries per page whatever its size. Archived offerings are listed only with `archived=true`. `campaigns` is how many campaigns are assigned to each.","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"q","in":"query","schema":{"type":"string","maxLength":120}},{"name":"kind","in":"query","schema":{"$ref":"#/components/schemas/AdsOfferingKind"}},{"name":"tag","in":"query","schema":{"type":"string","maxLength":40}},{"name":"archived","in":"query","schema":{"type":"boolean"}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"One page of offerings.","content":{"application/json":{"schema":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsOffering"}},"next_cursor":{"type":"string","nullable":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createAdsOffering","summary":"Add one thing the organisation advertises.","description":"Gated on `ads.manage`; audit action `ads.offering_create`. `domains` are derived from `urls` and used to match imported campaigns. `monthly_budget_minor` (integer minor units of `currency`) is this offering's own ceiling beside the account's.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsOfferingInput"}}}},"responses":{"201":{"description":"The offering.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsOffering"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/offerings/match":{"post":{"operationId":"matchAdsOfferings","summary":"Assign a Google Ads account's campaigns to offerings by their ads' final URLs.","description":"Gated on `ads.manage`; audit action `ads.offering_match`. Reads the account's ads and Performance Max asset groups (nothing is written to Google) and assigns each campaign whose final-URL host (or a parent domain) belongs to exactly one offering. A campaign a person assigned is never changed; a re-run changes nothing that has not moved.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["connection_id"],"properties":{"connection_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"What was matched.","content":{"application/json":{"schema":{"type":"object","required":["matched","unchanged","kept_person","unmatched"],"properties":{"matched":{"type":"integer"},"unchanged":{"type":"integer"},"kept_person":{"type":"integer"},"unmatched":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/offerings/{offering_id}":{"parameters":[{"name":"offering_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsOffering","summary":"One offering.","description":"Gated on `ads.view`.","tags":["ads"],"responses":{"200":{"description":"The offering.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsOffering"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateAdsOffering","summary":"Change an offering, or archive or restore it.","description":"Gated on `ads.manage`; audit action `ads.offering_update`. Only the fields sent change. A monthly ceiling cannot be set in a currency other than the one its launched campaigns committed (`currencyCommitted`).","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AdsOfferingInput"},{"type":"object","properties":{"archived":{"type":"boolean"}}}]}}}},"responses":{"200":{"description":"The offering.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsOffering"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/campaign-offerings":{"post":{"operationId":"setAdsCampaignOffering","summary":"Set (or clear, with no offering) which offering one campaign advertises.","description":"Gated on `ads.manage`; audit action `ads.campaign_offering_set`. Recorded as set by a person.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["connection_id","campaign_id"],"properties":{"connection_id":{"type":"string","format":"uuid"},"campaign_id":{"type":"string","maxLength":64},"campaign_name":{"type":"string","maxLength":255},"offering_id":{"type":"string","format":"uuid","nullable":true}}}}}},"responses":{"200":{"description":"The assignment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsCampaignOffering"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/campaign-offerings/lookup":{"post":{"operationId":"lookupAdsCampaignOfferings","summary":"Which offering each of many campaigns advertises, in one call.","description":"Gated on `ads.view`. Up to 5,000 pairs, answered in one database query. A campaign with no offering answers `offering_id: null` (Unassigned). `source` is `auto`, `person` or `launch`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["pairs"],"properties":{"pairs":{"type":"array","maxItems":5000,"items":{"type":"object","required":["connection_id","campaign_id"],"properties":{"connection_id":{"type":"string","format":"uuid"},"campaign_id":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"One row per pair, in the order sent.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsCampaignOffering"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/briefs/networks":{"get":{"operationId":"listAdsBriefNetworks","summary":"The ad networks a brief can launch on now.","description":"Gated on `ads.view` (za-292). `state` is `ready` (live, Zinn® Ads builds there, and the organisation has an active account on it), `connect` (live and buildable; connect an account first) or `coming_soon`. A network that is not `ready` cannot be ticked.","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Every network.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsBriefNetwork"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/briefs":{"get":{"operationId":"listAdsLaunchBriefs","summary":"The organisation's saved briefs, newest first (50).","description":"Gated on `ads.view`. Filter with `offering_id`. Each lists its networks and their state.","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"offering_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"build_id","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The briefs.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsLaunchBrief"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createAdsLaunchBrief","summary":"Save one brief for many networks and start reading the site.","description":"Gated on `ads.manage`; audit action `ads.brief_create` (za-291). The brief belongs to an offering (`offering_id`, else a website offering is made from `url`) and owns ONE Simple-mode build: the site is read once (`getAdsBuild` follows it; review and build the plan there), then each network's plan is made from it with `planAdsLaunchBrief`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Either `build_id` (adopt a Simple-mode build), or `monthly_budget_minor` and `currency` with `url` or `offering_id`.","properties":{"org_id":{"type":"string","format":"uuid"},"offering_id":{"type":"string","format":"uuid"},"build_id":{"type":"string","format":"uuid","description":"Adopt an existing Simple-mode build as the brief (its budget, currency and markets); one brief per build, returned as it is when it exists. A build already launched through its own door is refused `offeringCeiling` when its budget does not fit what the offering's monthly ceiling has left, and `offeringCurrency` when its currency is not the offering's."},"url":{"type":"string","maxLength":500},"name":{"type":"string","maxLength":120},"monthly_budget_minor":{"type":"integer","minimum":1},"currency":{"type":"string","minLength":3,"maxLength":3},"markets":{"type":"array","items":{"type":"object","properties":{"country":{"type":"string"},"language":{"type":"string"}}}},"offer":{"type":"string","maxLength":1000},"offers_free":{"type":"boolean"},"objective":{"type":"string","enum":["","leads","revenue","traffic","installs"]}}}}}},"responses":{"201":{"description":"The brief.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsLaunchBrief"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/briefs/{brief_id}":{"parameters":[{"name":"brief_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAdsLaunchBrief","summary":"One brief with each network's plan and the networks it could add now.","description":"Gated on `ads.view`. `can_add` lists the live, connected networks not on the brief yet (za-293).","tags":["ads"],"responses":{"200":{"description":"The brief.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsLaunchBrief"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/briefs/{brief_id}/plans":{"parameters":[{"name":"brief_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"planAdsLaunchBrief","summary":"Make each named network's plan from the brief (now, or later to add a network).","description":"Gated on `ads.manage`; audit action `ads.brief_plans` (za-292/za-293). Every network's plan comes from the same build: Google and Microsoft campaigns natively, X as a campaign with a line item and a promoted Tweet per ad group. Each network gets `split[network]` percent of the brief's budget (default: the room left, shared equally); shares across the brief never pass 100. A network already launched is never rebuilt. Nothing is queued.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["networks"],"properties":{"networks":{"type":"array","minItems":1,"maxItems":3,"items":{"oneOf":[{"type":"string","enum":["google","microsoft","x"]},{"type":"object","required":["network"],"properties":{"network":{"type":"string","enum":["google","microsoft","x"]},"connection_id":{"type":"string","format":"uuid"}}}]}},"split":{"type":"object","additionalProperties":{"type":"integer","minimum":1,"maximum":100}}}}}}},"responses":{"200":{"description":"The brief with its plans.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsLaunchBrief"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/briefs/{brief_id}/launch":{"parameters":[{"name":"brief_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"launchAdsLaunchBrief","summary":"Queue the named networks' plans as approve-first changes, together.","description":"Gated on `ads.manage`; audit action `ads.brief_launch` (za-292). All or nothing. NOTHING is sent to any network: every change waits in the approval queue (`listAdsChanges`) with its Undo, and the kill switches, spend ceilings and good standing still decide when it is approved. Refused over the plan's spend bracket, over the offering's own ceiling (`offeringCeiling`), or when an account is paused or in another currency. Refused `planStale` when the build's budget or currency was edited after its plan was built (rebuild it first). Each campaign is assigned to the brief's offering (source `launch`).","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["networks"],"properties":{"networks":{"type":"array","minItems":1,"maxItems":3,"items":{"type":"string","enum":["google","microsoft","x"]}}}}}}},"responses":{"200":{"description":"The brief with its plans queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsLaunchBrief"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/briefs/{brief_id}/unlaunch":{"parameters":[{"name":"brief_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"previewAdsLaunchBriefUnlaunch","summary":"What Unlaunch would pause or cancel now (nothing is written).","description":"Gated on `ads.view` (za-317). Each launched change and campaign with the state Unlaunch would move it to (`will_cancel`, `will_pause`, `in_flight`, …). Once an Unlaunch has started, its recorded progress.","tags":["ads"],"responses":{"200":{"description":"The Unlaunch preview or progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsBriefUnlaunch"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"unlaunchAdsLaunchBrief","summary":"Unlaunch a brief - pause everything it launched, approve-first, deleting nothing.","description":"Gated on `ads.manage`; audit action `ads.brief_unlaunch` (za-317, owner ruling 2026-11-04). Every launch change still pending is rejected (nothing was sent for it); every campaign a launch change created gets a PAUSE change in the approval queue (`listAdsChanges`) on its own network (Google, Microsoft, X), which a person approves. An Unlaunch pause cannot be undone from Zinn® Ads. Once every item is paused or gone the brief is `done`: its plans become `paused`, the offering stops counting it against its ceiling, and its currency can change. Calling again moves it on and re-proposes a pause a person rejected or the network refused. An unlaunched brief is never launched again (`unlaunched`); make a new brief. Refused `notLaunched` when nothing was launched and `unlaunchDone` once done.","tags":["ads"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"The brief with its Unlaunch progress (`unlaunch`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsLaunchBrief"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/shield":{"get":{"operationId":"getAdsShield","summary":"The organisation's click-fraud shield and its totals for a period.","description":"Gated on `ads.view` (docs/1006 §15). Paid clicks (gclid, msclkid, fbclid, ttclid, li_fat_id, twclid, epik) that landed on the organisation's sites hosted by Zinn®, scored from the sites' own access logs. `estimated_wasted` is an ESTIMATE in integer minor units — suspected clicks times the organisation's own `avg_cpc_minor` — never a refund promise; Google decides what is invalid. The shield is free on all Zinn® hosting and on by default. With a connected Google Ads account the estimate uses Google's own measured average CPC for the click's keyword (else campaign) that day (`estimate_sources`).","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"days","in":"query","required":false,"schema":{"type":"integer","enum":[7,30,90],"default":30}}],"responses":{"200":{"description":"The shield.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsShield"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"updateAdsShield","summary":"Switch the shield off or on, and set the figures its estimate uses.","description":"Gated on `ads.manage`; audit action `ads.shield_update`. `avg_cpc_minor` is the organisation's average cost per click in integer minor units of `currency` (0 = show no estimate). `conversion_paths` are URL path prefixes that count as a conversion: a click followed by one is never flagged.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"org_id":{"type":"string","format":"uuid"},"enabled":{"type":"boolean"},"avg_cpc_minor":{"type":"integer","minimum":0,"maximum":1000000000},"currency":{"type":"string","pattern":"^([A-Z]{3})?$"},"conversion_paths":{"type":"array","maxItems":20,"items":{"type":"string","pattern":"^/"}},"exclusions_enabled":{"type":"boolean","description":"Propose IP and placement exclusions to the connected Google Ads accounts."},"placements_enabled":{"type":"boolean","description":"The placement guard (za-N18): propose excluding Display, Video and Performance Max placements (websites, apps, YouTube channels and videos) that spend with no result, and junk classes (mobile apps, children's videos). Approve-first by default; the first batch on a connection always waits for a person."}}}}}},"responses":{"200":{"description":"The shield.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsShield"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/shield/clicks":{"get":{"operationId":"listAdsShieldClicks","summary":"Scored paid clicks on the organisation's hosted sites, newest first.","description":"Gated on `ads.view`. Each click carries its score (0-100), the reasons and an estimated cost. The visitor's address is never returned whole — only its network (`ip_masked`) and only while the claim-window evidence is kept (60 days); after that it is blanked.","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"verdict","in":"query","required":false,"schema":{"type":"string","enum":["suspected","clean","converted"]}},{"name":"before","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"A page of clicks.","content":{"application/json":{"schema":{"type":"object","required":["data","next_before"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsShieldClick"}},"next_before":{"type":["string","null"],"format":"date-time"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/shield/exclusions":{"get":{"operationId":"listAdsShieldExclusions","summary":"The IP, placement and audience exclusions the shield asked Google for.","description":"Gated on `ads.view` (docs/1006 §15, SHIELD2, IPROTATE za-59). Per campaign, the suspected sources ranked by measured cost are kept inside Google's 500-per-campaign IP cap (the customer's own exclusions count against it); at the cap the cheapest of ours (most stale on a tie) rotates out for a costlier newcomer, never one whose source cost money within the connection's `shield_stale_days`. Placements (Display / Video per campaign, Performance Max account-wide) and audience segments (Display / Video) with `shield_waste_min_clicks` clicks, cost and no conversion are excluded too. A source that converted is never excluded. Every exclusion is an ad-account change: approve-first unless `exclusions` is automatic, each with its own Undo (`undoAdsShieldExclusion`). Never on the platform's own account.","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["queued","applied","rejected","removed","undone","failed"]}},{"name":"before","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"A page of exclusions.","content":{"application/json":{"schema":{"type":"object","required":["data","next_before","per_campaign_cap"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsShieldExclusion"}},"next_before":{"type":["string","null"],"format":"date-time"},"per_campaign_cap":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/shield/exclusions/{exclusion_id}/undo":{"post":{"operationId":"undoAdsShieldExclusion","summary":"Undo one click-shield exclusion (one click).","description":"Gated on `ads.manage` (IPROTATE, za-59). The person's click approves the removal of that one exclusion at Google (sent by the apply workflow, through the metered driver) and the exclusion is never proposed again for its campaign. Refused (422) when it is not at Google (`notApplied`), Google has not confirmed it yet (`notYetAtGoogle`), a removal is already on its way (`alreadyRemoving`) or it was applied more than 30 days ago (`refusal.adsconnect.undoExpired`, the same undo window as every Zinn® Ads change). The daily e-mail's Undo link for one exclusion runs this same path through `actOnAdsEmailLink`. A Microsoft website exclusion is removed from the campaign's list the same way; a Meta `listed` one only leaves the Zinn-held block list (nothing is sent to Meta) and is never listed again.","tags":["ads"],"parameters":[{"name":"exclusion_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"The exclusion, now `undone`; its removal is on its way to Google.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsShieldExclusion"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/shield/meta-block-list":{"get":{"operationId":"getAdsShieldMetaBlockList","summary":"A Meta connection's Zinn-held publisher block list (PLACEGUARD2, za-N18).","description":"Gated on `ads.view`. The Audience Network publisher URLs the placement guard listed for this Meta connection (status `listed`), to upload in Meta's Brand Safety screen as a publisher block list. ⛔ Zinn® does not apply it: Meta's API takes a block list only as a business-level upload that needs the app feature `block_list_management_v2_api_access` and `ads_management`, which our Meta app (`ads_read`) does not hold — so `applied_by_zinn` is always false and `why_not_applied` names that. 404 for an unknown or non-Meta connection.","tags":["ads"],"parameters":[{"name":"connection_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The list.","content":{"application/json":{"schema":{"type":"object","required":["connection_id","urls","count","applied_by_zinn","why_not_applied"],"properties":{"connection_id":{"type":"string","format":"uuid"},"urls":{"type":"array","items":{"type":"string"}},"count":{"type":"integer"},"applied_by_zinn":{"type":"boolean","enum":[false]},"why_not_applied":{"type":"string","enum":["metaApiNotGranted"]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/shield/claims":{"get":{"operationId":"listAdsShieldClaims","summary":"Refund evidence packs, one per Google Ads account per month.","description":"Gated on `ads.view` (za-22, za-N8). A pack exists while its clicks' evidence does (the 60-day claim window). Nothing is ever filed automatically: a person sends the pack through Google's invalid-click form; the credit Google gives is then read from the account's invoices.","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The packs.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsShieldClaim"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/shield/claims/{claim_id}":{"get":{"operationId":"getAdsShieldClaim","summary":"One refund evidence pack with every suspected click.","description":"Gated on `ads.view`. Each click: time, gclid, campaign, keyword, network (masked) and ASN, behaviour (requests after the click, repeats), the rebuilt access-log line (address masked) and the reasons it was judged invalid. Up to 2,000 clicks.","tags":["ads"],"parameters":[{"name":"claim_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The pack.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AdsShieldClaim"},{"type":"object","required":["first_click_at","last_click_at","claim_deadline","by_reason","campaigns","clicks_list"],"properties":{"first_click_at":{"type":["string","null"],"format":"date-time"},"last_click_at":{"type":["string","null"],"format":"date-time"},"claim_deadline":{"type":["string","null"],"format":"date-time"},"by_reason":{"type":"object","additionalProperties":{"type":"integer"}},"campaigns":{"type":"array","items":{"type":"string"}},"clicks_list":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/AdsShieldClick"},{"type":"object","required":["gclid","ad_group_id","requests_after","same_ip_clicks_24h","same_network_clicks_24h","log_line"],"properties":{"gclid":{"type":"string"},"ad_group_id":{"type":"string"},"requests_after":{"type":"integer"},"same_ip_clicks_24h":{"type":"integer"},"same_network_clicks_24h":{"type":"integer"},"log_line":{"type":"string"}}}]}}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/shield/claims/{claim_id}/sent":{"post":{"operationId":"markAdsShieldClaimSent","summary":"Record that a person sent the pack through Google's form.","description":"Gated on `ads.manage`; audit action `ads.shield_claim_sent`. Zinn® never files a claim itself (owner ruling) — this records the person's word and, optionally, Google's reference, so the credit can be looked for on the following invoices.","tags":["ads"],"parameters":[{"name":"claim_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"org_id":{"type":"string","format":"uuid"},"reference":{"type":"string","pattern":"^[A-Za-z0-9._:/-]{0,64}$"}}}}}},"responses":{"200":{"description":"The pack.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsShieldClaim"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/zaraz/zones":{"post":{"operationId":"listAdsZarazZones","summary":"The Cloudflare zones a pasted Zaraz token can reach (the zone picker).","description":"za-131 (docs/1006 §88). Gated on `ads.manage`. The customer's scoped Cloudflare API token (Zone Read + Zaraz Edit) is used for this one call and NOT stored; it is never echoed back. Every page of zones is read. A refusal carries `refusal.adsconnect.zaraz.<code>`: `tokenShape`, `tokenRejected`, `rateLimited`, `unavailable` (Cloudflare answered 5xx), `unexpected` (our side failed or Cloudflare's answer was not understood; names no vendor).","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"org_id":{"type":"string","format":"uuid"},"token":{"type":"string","minLength":30,"maxLength":120,"writeOnly":true}}}}}},"responses":{"200":{"description":"The zones, by name.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsZarazZone"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/zaraz/connections":{"get":{"operationId":"listAdsZarazConnections","summary":"The organisation's Cloudflare zones connected for Zaraz.","description":"za-131 (docs/1006 §88). Gated on `ads.view`. Our own rows; no Cloudflare call.","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The connections.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsZarazConnection"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createAdsZarazConnection","summary":"Connect one Cloudflare zone for Zaraz with a scoped token.","description":"za-131 (docs/1006 §88). Gated on `ads.manage`; audit action `ads.zaraz_connect`. The token must reach the zone and be able to READ and EDIT Zaraz on it (proved by reading the zone's Zaraz workflow, then a config PUT whose body can never be a config — Cloudflare answers 400 to a token with Zaraz Edit and 403 without; nothing is written). The token goes to Vault (`secret/orgs/<org>/ads/zaraz/<id>`) before the row is saved and is never stored in the database or returned. Connecting a zone again replaces its token. Refusals: `refusal.adsconnect.zaraz.<code>` — `tokenShape`, `tokenRejected`, `permissionMissing`, `zoneNotFound`, `rateLimited`, `unavailable`, `unexpected`, `vaultUnavailable`.","tags":["ads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token","zone_id"],"properties":{"org_id":{"type":"string","format":"uuid"},"token":{"type":"string","minLength":30,"maxLength":120,"writeOnly":true},"zone_id":{"type":"string","pattern":"^[a-f0-9]{32}$"}}}}}},"responses":{"201":{"description":"The connection.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsZarazConnection"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/zaraz/connections/{connection_id}":{"delete":{"operationId":"deleteAdsZarazConnection","summary":"Disconnect a Cloudflare zone (the stored token is deleted from Vault).","description":"za-131 (docs/1006 §88). Gated on `ads.manage`; audit action `ads.zaraz_disconnect`. Nothing on the zone is changed. A Vault failure refuses with `vaultUnavailable` and keeps the row.","tags":["ads"],"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Disconnected."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/zaraz/connections/{connection_id}/check":{"post":{"operationId":"checkAdsZarazConnection","summary":"Re-prove the stored token can read and edit Zaraz on the zone.","description":"za-131 (docs/1006 §88). Gated on `ads.manage`; audit action `ads.zaraz_check`. A token Cloudflare refuses sets `status: needs_token`; a rate limit or an outage is reported in `last_error` and leaves the status as it was. Answers 200 either way.","tags":["ads"],"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The connection after the check.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsZarazConnection"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/zaraz/connections/{connection_id}/install":{"post":{"operationId":"installAdsZaraz","summary":"One-click install - write the tracking hub's tools, triggers and consent into the zone.","description":"za-132 (docs/1006 §110). Gated on `ads.manage`; audit action `ads.zaraz_install`. Reads the zone's whole Zaraz configuration, replaces only the `zinn_*` tools and triggers and our two consent purposes from the org's tracking hub (za-126), keeps everything else of the customer's, and writes it back (published when the zone uses the preview workflow). No site code. Networks Zaraz cannot run from a public id are listed in `skipped`. Refusals (422, `refusal.adsconnect.zarazSync.<code>` or `refusal.adsconnect.zaraz.<code>`): `hubEmpty`, `foreignSecrets` (the zone holds secret variables that a write could erase), `consentShape`, `tokenRejected`, `permissionMissing`, `zoneNotFound`, `rateLimited`, `unavailable` (Cloudflare answered 5xx), `unexpected` (our side failed, §2.57), `vaultUnavailable`.","tags":["ads"],"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"consent":{"type":"boolean","default":true,"description":"Ask visitors for consent with Zaraz's banner (a banner already on stays on)."}}}}}},"responses":{"200":{"description":"Installed.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsZarazActionResult"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/zaraz/connections/{connection_id}/sync":{"get":{"operationId":"getAdsZarazSync","summary":"The zone's sync state - drift against the agreed version and the hub, and the versions.","description":"za-133 (docs/1006 §110). Gated on `ads.view`. `drift.state` is `not_installed`, `in_sync`, `edited_in_cloudflare`, `hub_ahead` or `both`, as of `drift_checked_at` (the daily sweep, or a refresh). Versions from the last `undo_days` days can be restored.","tags":["ads"],"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The sync card.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsZarazSync"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/zaraz/connections/{connection_id}/sync/refresh":{"post":{"operationId":"refreshAdsZarazSync","summary":"Read the zone now and compare it (nothing is written to Cloudflare).","description":"za-133 (docs/1006 §110). Gated on `ads.manage`. A change found in Cloudflare is recorded as a `seen` version. Refusals as for install (`tokenRejected`, `rateLimited`, ...).","tags":["ads"],"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The sync card after the read.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsZarazSync"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/zaraz/connections/{connection_id}/sync/adopt":{"post":{"operationId":"adoptAdsZarazSync","summary":"Keep Cloudflare's version - it becomes the agreed version and its ids go back into the hub.","description":"za-133 (docs/1006 §110), the second way of the two-way sync. Gated on `ads.manage`; audit action `ads.zaraz_adopt`. The tag and conversion ids found in the zone's `zinn_*` tools are written into the tracking hub (other hub ids are kept; a tool removed in Cloudflare does not remove its hub id). Refusals: `hubRefused`, `hubUnavailable`, and the token codes.","tags":["ads"],"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Kept.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsZarazActionResult"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/zaraz/connections/{connection_id}/versions/{version_id}/restore":{"post":{"operationId":"restoreAdsZarazVersion","summary":"Undo - write an earlier version of the zone's Zaraz configuration back (30 days).","description":"za-133 (docs/1006 §110). Gated on `ads.manage`; audit action `ads.zaraz_undo`. A version of another connection is 404; one older than 30 days is `undoExpired`; a zone holding secret variables not ours is `foreignSecrets`.","tags":["ads"],"parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"version_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Restored.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsZarazActionResult"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/shield/claims/{claim_id}/outcome":{"post":{"operationId":"recordAdsShieldClaimOutcome","summary":"Record Google's answer to a sent pack (credit received or none).","description":"Gated on `ads.manage`; audit action `ads.shield_claim_outcome` (za-22, za-N8). For a pack marked sent, a person records the credit Google gave (integer minor units, §2.8) or that Google gave none: card-paying accounts have no invoices to read, so Google's reply is the only answer. Zinn® never moves money here; this is a record of a credit Google gave the ad account. 409 when the pack is not sent yet, or when its answer was read from the account's invoices (those are never overwritten). A person-recorded answer can be corrected; the write is conditional, so an invoice answer landing while the request runs is a 409, never overwritten.","tags":["ads"],"parameters":[{"name":"claim_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["outcome"],"properties":{"org_id":{"type":"string","format":"uuid"},"outcome":{"type":"string","enum":["credited","declined"]},"credited_minor":{"type":["integer","null"],"minimum":1,"maximum":10000000000000,"description":"Required when `outcome` is `credited`; minor units of the pack's currency."},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"Only used when neither the pack nor its ad account has a currency yet; 422 when it differs from the pack's (Google credits in the account's currency)."}}}}}},"responses":{"200":{"description":"The pack.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsShieldClaim"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/wordpress/sites":{"get":{"operationId":"listAdsWordPressSites","summary":"The organisation's WordPress sites connected with the Zinn® Ads plugin.","description":"Gated on `ads.view` (docs/1006 §102). Connected sites and pairing codes that have not expired yet. Each site says whether Cloudflare fronts it (`cloudflare_detected`, measured by the plugin), its tag mode (`browser` or `zaraz`), whether to offer Zaraz mode, and in Zaraz mode the purchases sent through Zaraz against what the ad networks credited over the latest tracking-check window (`zaraz_health`). Cursor-paged newest first: follow `page.next_cursor` while `page.has_more` is true (there is no cap on the total).","tags":["ads"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"One page of sites.","content":{"application/json":{"schema":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsWordPressSite"}},"page":{"$ref":"#/components/schemas/PageMeta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createAdsWordPressPairing","summary":"Make a one-time code that connects a WordPress site with the Zinn® Ads plugin.","description":"Gated on `ads.manage`; audit action `ads.wordpress_pairing_created`. The `code` is shown ONCE (only its SHA-256 hash is stored) and is valid for 30 minutes. The customer pastes it into the plugin's settings page; the plugin redeems it at `claimAdsWordPressSite`.","tags":["ads"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"201":{"description":"The pending site and its code.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AdsWordPressSite"},{"type":"object","required":["code"],"properties":{"code":{"type":"string","example":"7KQ2-M9XD-4RTB"}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ads/wordpress/sites/{site_id}":{"parameters":[{"name":"site_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"delete":{"operationId":"disconnectAdsWordPressSite","summary":"Disconnect a WordPress site (its token stops working at once).","description":"Gated on `ads.manage`; audit action `ads.wordpress_site_disconnected`. Another organisation's site answers 404.","tags":["ads"],"responses":{"204":{"description":"Disconnected."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/ads-wordpress/claim":{"post":{"operationId":"claimAdsWordPressSite","summary":"The Zinn® Ads plugin exchanges a one-time code for its site token.","description":"⛔ **No authentication** — the one-time code is the whole authorisation (docs/1006 §102). Unknown, used and expired codes are one answer (422 `codeInvalid`). The `token` is returned ONCE; we keep only its SHA-256 hash. Re-connecting a host that is already connected retires its old token in the same step. Audit action `ads.wordpress_site_connected`.","tags":["ads"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code","site_url"],"properties":{"code":{"type":"string","maxLength":40},"site_url":{"type":"string","format":"uri","maxLength":2048,"description":"The site's home_url()."},"plugin_version":{"type":"string","maxLength":32},"wp_version":{"type":"string","maxLength":32},"cloudflare":{"type":"boolean","description":"A CF-Ray header reached PHP."}}}}}},"responses":{"201":{"description":"Connected.","content":{"application/json":{"schema":{"type":"object","required":["token","config"],"properties":{"token":{"type":"string","description":"zwp_… — store it; it is never shown again."},"config":{"$ref":"#/components/schemas/AdsWordPressConfig"}}}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/ads-wordpress/heartbeat":{"post":{"operationId":"adsWordPressHeartbeat","summary":"The plugin reports in and reads its config.","description":"Site token only. Records the plugin and WordPress versions, whether Cloudflare fronts the site, the tag mode and, per UTC day, how many purchases the plugin sent through Zaraz (`zaraz_sent`, running totals; days in the future or older than 35 days are dropped). WPPAID: also each path's own per-day counts, so the dashboard measures the browser path and the server upload apart — `zaraz_delivered` (handed to Zaraz in the visitor's browser), `zaraz_declined` (withheld: no ad consent) and `orders_reported` (paid orders queued for the server upload). A counter not sent keeps what it had. The site calls us; nothing calls the site (§2.56).","tags":["ads"],"security":[{"adsWordPressToken":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"plugin_version":{"type":"string","maxLength":32},"wp_version":{"type":"string","maxLength":32},"cloudflare":{"type":"boolean"},"mode":{"type":"string","enum":["browser","zaraz"]},"zaraz_sent":{"type":"object","additionalProperties":{"type":"integer","minimum":0},"description":"{\"YYYY-MM-DD\": purchases sent through Zaraz that day}"},"zaraz_delivered":{"type":"object","additionalProperties":{"type":"integer","minimum":0},"description":"{\"YYYY-MM-DD\": of those, handed to Zaraz in the browser}"},"zaraz_declined":{"type":"object","additionalProperties":{"type":"integer","minimum":0},"description":"{\"YYYY-MM-DD\": of those, withheld because the visitor declined ad cookies}"},"orders_reported":{"type":"object","additionalProperties":{"type":"integer","minimum":0},"description":"{\"YYYY-MM-DD\": paid orders queued for the server-side upload}"}}}}}},"responses":{"200":{"description":"The site's config.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsWordPressConfig"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/ads-wordpress/clicks":{"post":{"operationId":"sendAdsWordPressClicks","summary":"The plugin's click-fraud tag sends paid-click visits for scoring.","description":"Site token only. Up to 500 visits a batch, the facts an access log holds. Visits that carry a paid-click id (gclid, msclkid, fbclid, ttclid, li_fat_id, twclid, epik) and are older than the 10-minute dwell window are scored by the same click-fraud shield as sites hosted by Zinn® (docs/1006 §15), on the connected host whatever host a visit names. Each click is stored once, so a re-sent batch stores nothing new. Nothing is scored when the organisation switched the shield off.","tags":["ads"],"security":[{"adsWordPressToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["hits"],"properties":{"hits":{"type":"array","maxItems":500,"items":{"type":"object","required":["at","ip"],"properties":{"at":{"type":"string","format":"date-time"},"ip":{"type":"string","maxLength":45},"method":{"type":"string","maxLength":10},"path":{"type":"string"},"query":{"type":"string","maxLength":2000},"status":{"type":"integer"},"user_agent":{"type":"string","maxLength":500}}}}}}}}},"responses":{"200":{"description":"What was scored.","content":{"application/json":{"schema":{"type":"object","required":["received","clicks","stored","suspected"],"properties":{"received":{"type":"integer"},"clicks":{"type":"integer"},"stored":{"type":"integer"},"suspected":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/ads-wordpress/outcomes":{"post":{"operationId":"sendAdsWordPressOutcomes","summary":"The plugin sends the site's paid orders, free trials and sent forms to the outcome pipeline.","description":"Site token only. The same outcome shape and store as the events API (`POST /v1/ads/connections/{connection_id}/outcomes`), for every connection of the site's organisation that is not disconnected, then pushed to the networks within minutes. Only `purchase`, `trial` and `lead` (a 422 otherwise). A `lead` is a form sent, reported from the form plugin's own server hook with the reference the browser tag sends for it (`<ref_prefix>-lead-<form plugin>-<random id>`), so the network counts it once; it carries no value, no e-mail, no referrer and no page (dropped whatever the request says: nothing a visitor typed leaves the site), and at most 300 a site per hour are stored (the rest are counted in `rate_limited`). The reference is forced into the site's own namespace (`<ref_prefix>-<order number>`, the same transaction id the browser tag sends, so the network counts a sale once), the host is the connected site's whatever `outcome_url` says, and the source is `store`. Click ids and the e-mail are stored and forwarded only when an outcome's `consent` is `GRANTED` (the order page's own consent); otherwise they are dropped, whatever the request carries. Idempotent per order: a re-sent order stores nothing new. Audit action `ads.outcomes_received` when something was stored.","tags":["ads"],"security":[{"adsWordPressToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["outcomes"],"properties":{"outcomes":{"type":"array","minItems":1,"maxItems":500,"items":{"$ref":"#/components/schemas/AdsOutcomeIn"}}}}}}},"responses":{"200":{"description":"Nothing new (every outcome was already stored).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsOutcomesIngested"}}}},"201":{"description":"At least one outcome stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdsOutcomesIngested"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/ads-wordpress/refunds":{"post":{"operationId":"sendAdsWordPressRefunds","summary":"The plugin withdraws or restates orders cancelled, failed or refunded after they were reported.","description":"Site token only (WPPAID). An order the plugin reported (only once PAID) and that was then cancelled, failed or refunded in full is withdrawn exactly as the events API's retraction does: not uploaded yet, it never goes; uploaded, the network gets ONE retraction. Refunded in part (`refunded_minor` = refunded so far, with `currency`), the sale is restated to what was kept. The reference is forced into the site's own namespace, so a site can withdraw only its own orders. `not_found` counts references the pipeline does not have yet (the plugin tries again later). Idempotent. Audit action `ads.outcomes_retracted` when something changed.","tags":["ads"],"security":[{"adsWordPressToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["refunds"],"properties":{"refunds":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"object","required":["kind","external_ref"],"properties":{"kind":{"type":"string","enum":["purchase","trial"]},"external_ref":{"type":"string","pattern":"^[\\w.:\\-/#]{1,128}$"},"refunded_minor":{"type":"integer","minimum":1,"description":"Refunded so far, in minor units (refunded in part). Absent, or a total reaching the order's value in the same currency = withdrawn in full."},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$","description":"Required with refunded_minor."}}}}}}}}},"responses":{"200":{"description":"What was done, summed over the organisation's ad accounts.","content":{"application/json":{"schema":{"type":"object","required":["retracted","restated","already","not_found"],"properties":{"retracted":{"type":"integer"},"restated":{"type":"integer"},"already":{"type":"integer"},"not_found":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/ads-wordpress/site":{"delete":{"operationId":"disconnectAdsWordPressSelf","summary":"The plugin's Disconnect button revokes its own site token.","description":"Site token only; audit action `ads.wordpress_site_disconnected`.","tags":["ads"],"security":[{"adsWordPressToken":[]}],"responses":{"204":{"description":"Disconnected."},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/ads-wordpress/zaraz":{"get":{"operationId":"getAdsWordPressZaraz","summary":"The plugin's Zaraz step list - the zone connected for this site and what an install would write.","description":"za-312 (docs/1006.d/features/za-132-133-zarazsync.md §za-312). Site token only. The zone is found from the site's own host (its name, then each parent): `zone_names` lists the candidates, `connection` is the org's za-131 connection for that zone (or null), `hub_networks` the tracking-hub networks an install would write and `skipped` those Zaraz cannot run from a public id. The same connection row the dashboard's sync, drift and 30-day undo cover.","tags":["ads"],"security":[{"adsWordPressToken":[]}],"responses":{"200":{"description":"The step list's state.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsWordPressZaraz"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/ads-wordpress/zaraz/connect":{"post":{"operationId":"connectAdsWordPressZaraz","summary":"Connect the Cloudflare zone serving this site for Zaraz, from wp-admin.","description":"za-312. Site token only; audit action `ads.zaraz_connect`. Among the zones the pasted token reaches, the one serving the site's host is connected exactly as the dashboard's `createAdsZarazConnection` does (READ and EDIT proved, nothing written). The token goes to Vault and is never stored on the site, in the database or returned. Refusals (422, `refusal.adsconnect.zaraz.<code>`): `tokenShape`, `tokenRejected`, `permissionMissing`, `zoneNotFound` (no reached zone serves this site), `zoneNotActive` (the zone's nameservers are not switched yet), `rateLimited`, `unavailable`, `unexpected`, `vaultUnavailable`.","tags":["ads"],"security":[{"adsWordPressToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","writeOnly":true,"description":"A Cloudflare API token with Zaraz Read + Edit on the site's zone."}}}}}},"responses":{"201":{"description":"Connected.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsZarazConnection"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/ads-wordpress/zaraz/check":{"post":{"operationId":"checkAdsWordPressZaraz","summary":"Re-check the connected zone's token and permissions, from wp-admin (writes nothing).","description":"za-312. Site token only; audit action `ads.zaraz_check`. When the token passes, the zone's configuration is also read (nothing written) so `getAdsWordPressZaraz` knows the zone's consent switch before the first install; a failed read leaves the check's answer. 404 (`refusal.adsconnect.zaraz.noSuchConnection`) until the site's zone is connected. Refusals as `checkAdsZarazConnection`.","tags":["ads"],"security":[{"adsWordPressToken":[]}],"responses":{"200":{"description":"The connection after the check.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsZarazConnection"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/ads-wordpress/zaraz/install":{"post":{"operationId":"installAdsWordPressZaraz","summary":"One-click install of the tracking hub into the site's zone, from wp-admin.","description":"za-312. Site token only; audit action `ads.zaraz_install`. The dashboard's `installAdsZaraz` on the connection for this site's zone: only the `zinn_*` tools, triggers and our two consent purposes are written, Zaraz is switched on (`autoInjectScript`) and everything else of the customer's is kept; the zone is versioned first so the dashboard's 30-day undo reaches it. 404 (`refusal.adsconnect.zaraz.noSuchConnection`) until the zone is connected. Refusals as `installAdsZaraz`.","tags":["ads"],"security":[{"adsWordPressToken":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"consent":{"type":["boolean","null"],"description":"Ask visitors for consent with Zaraz's banner (a banner already on stays on). Omitted or null keeps the zone's current consent switch."}}}}}},"responses":{"200":{"description":"Installed.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsZarazActionResult"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/access/impersonation/current":{"get":{"operationId":"getImpersonationStatus","summary":"The current impersonation status (drives the banner).","description":"Whether the calling session is an impersonation, and if so who (the real staff actor), which org, and when it expires — the source for the non-dismissable `\"you are viewing as <customer>\"` banner. Any authenticated caller may ask; a normal session gets `active: false`.","tags":["access"],"responses":{"200":{"description":"The impersonation status.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImpersonationStatus"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/access/impersonation/redeem":{"post":{"operationId":"redeemImpersonationTicket","summary":"Exchange a single-use impersonation ticket for a session token.","description":"Called by the customer dashboard when a staff member follows an `ImpersonationGrant.url`. **Unauthenticated by design** — the caller is the app at the instant it has no session, which is the whole point. Authorisation is the ticket: single-use, five minutes, 32 bytes of entropy, stored only as a SHA-256 digest, and bound to a grant a staff member is on the audit log for opening.\n\nEvery refusal returns the same 401 message. Distinguishing \"no such ticket\" from \"already redeemed\" from \"expired\" would tell a caller which of their guesses was once real.","tags":["access"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImpersonationRedeemRequest"}}}},"responses":{"200":{"description":"The customer session for this grant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImpersonationRedeemed"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/access/impersonation/end":{"post":{"operationId":"endImpersonation","summary":"Exit the current impersonation session (revoke).","description":"Ends the calling impersonation session. Marking the grant ended **is** the revocation: the authenticator re-reads the row on every request, so the token stops working on the very next call rather than when it happens to expire. Audit-logged with the real staff actor. Returns 409 if the caller is not in an impersonation session.","tags":["access"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImpersonationExitRequest"}}}},"responses":{"200":{"description":"The session was ended.","content":{"application/json":{"schema":{"type":"object","required":["ended"],"properties":{"ended":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/orgs/{orgId}/members":{"parameters":[{"$ref":"#/components/parameters/OrgId"}],"get":{"operationId":"listOrgMembers","summary":"List the people in an organization.","description":"The org's members with their roles, paged over **users** (a person holding two roles is one row, not two). Each row carries `removable` and, when false, `not_removable_reason` — the engine's own answer, so a client never re-derives the removal policy and offers a button that will be refused. Requires `members.read`; a caller without `members.remove` sees `removable: false` on everyone.","tags":["access"],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"A page of members.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgMemberPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/orgs/{orgId}/roles":{"parameters":[{"$ref":"#/components/parameters/OrgId"}],"get":{"operationId":"listAssignableRoles","summary":"List the roles the caller may grant in an organization.","description":"Filtered by the same escalation rule the invite flow enforces (a role holding a permission the caller lacks is not grantable, register #31), so every role returned is one an invitation will accept. Requires `members.read`. Unpaged — the role catalogue is a fixed, small set.","tags":["access"],"responses":{"200":{"description":"The grantable roles.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignableRoleList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/orgs/{orgId}/members/{userId}":{"parameters":[{"$ref":"#/components/parameters/OrgId"},{"name":"userId","in":"path","required":true,"description":"The user to remove from the organization.","schema":{"$ref":"#/components/schemas/Uuid"}}],"patch":{"operationId":"changeOrgMemberRole","summary":"Change a member's role.","description":"Sets this member's role in the organization. Requires `members.role.assign` **on that org**.\n\n⛔ **Replaces** the member's roles with the one given rather than adding to them — a person may hold several `Membership` rows, and collapsing them can only ever reduce what they hold, so no path through this endpoint escalates by accident.\n\nThree refusals, and they are the same rules an invitation is held to: **403** if the member holds a permission the caller does not (`more_privileged`), **403** if the *role being granted* holds one (`role_not_grantable` — this is what stops any holder of the key promoting themselves to `owner`), and **409** for the org's last owner (`last_owner`). An unknown role is a **422**, never a 403, so a typo is distinguishable from a permission you lack.","tags":["access"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemberRoleChange"}}}},"responses":{"200":{"description":"The member, as the list endpoint would now report them.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgMember"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"removeOrgMember","summary":"Remove a member and offboard them (docs/35","description":"Removes the user from the org and runs the offboarding cascade: revokes their org access (immediate — a principal is resolved fresh per request), their Keycloak sessions (best-effort), and their own API keys, and emits `member.removed` so the hosting side rotates their per-site credentials. Audit-logged with the remover. Requires `members.remove`. Refuses (403) to remove a member more privileged than the caller, and (409) to remove the org's last owner.","tags":["access"],"responses":{"204":{"description":"The member was removed and offboarded."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/orgs/{orgId}/auth-policy":{"parameters":[{"$ref":"#/components/parameters/OrgId"}],"get":{"operationId":"getOrgAuthPolicy","summary":"Read an org's authentication policy.","description":"The org's per-org authentication policy (docs/35 #4). Requires `org.read`.","tags":["access"],"responses":{"200":{"description":"The auth policy.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthPolicy"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setOrgAuthPolicy","summary":"Set an org's authentication policy (require MFA).","description":"Require (or stop requiring) a second factor for this org's members (docs/35 #4). When required, a member on a password-only session gets none of the org's permissions until they re-authenticate with MFA. Requires `org.update`; **enabling** additionally requires the caller's own session to be MFA (403 otherwise) so an admin cannot lock themselves out.","tags":["access"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthPolicy"}}}},"responses":{"200":{"description":"The updated auth policy.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthPolicy"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/marketplace/overview":{"get":{"operationId":"getMarketplaceOverview","summary":"The marketplace hub — every vertical, the latest Zinn®s, what recently sold.","description":"docs/83 §6's hub, and the front door of the storefront. Anonymous, single-variant, no user-agent branch: these pages exist to rank, and a hub behind auth is a hub no crawler and no first-time visitor ever sees.\n\nEach vertical declares its own `storefront_layout`, which is what makes *\"layouts suited to what is sold\"* (owner, 2026-08-08) a row an operator can change rather than a map compiled into the frontend — a guest post renders as a comparison row, a website as a showcase, and the ninth marketplace is data entry rather than a deploy.\n\n⛔ `recently_sold` respects the mask: a sold website's domain stays `site****.com` exactly as a live listing's does. Selling a site does not make its domain public.","tags":["marketplace"],"parameters":[{"name":"locale","in":"query","schema":{"type":"string"},"description":"Explicit, never `Accept-Language`. A response that varied on a request header would need `Vary`, at which point the edge can serve a crawler a different page from the one a visitor gets."}],"responses":{"200":{"description":"The hub.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceOverview"}}}}}}},"/v1/launch-network":{"get":{"operationId":"getLaunchNetworkCard","summary":"The launch-network card — the newest launches and one network site to launch on.","description":"s1006 slice 8 (owner). The owner's launch network, promoted in one small card in the dashboard and in V1. `newest` is at most three launches from thelaunchdirectory.com, newest first, read server-side and held for 900 seconds for every caller, so no customer's browser ever calls the network itself. `launch_on` is ONE network site, rotated by UTC day: the flagships alternate on even days and the rest of the network takes turns on odd days. When the directory cannot be read, `newest` is empty and `launch_on` is still present, so the card is never an error. Anonymous, no tenant data.","tags":["marketplace"],"security":[],"responses":{"200":{"description":"The card.","headers":{"Cache-Control":{"schema":{"type":"string","example":"public, max-age=900"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LaunchNetworkCard"}}}}}}},"/v1/marketplace/valuation-estimate":{"get":{"operationId":"getMarketplaceValuationEstimate","summary":"A free instant estimate of what an online business might sell for (an estimate, not advice).","description":"s1014 L69 (docs/1068 Q9). Anonymous; nothing is stored. Every input is typed by the visitor, so every input is `declared` (unverified) and verification coverage is `none`. Refusals (422, `refusal.marketplaceValuation.<code>`): `noProfit`, `notApplicable` (domains), `assetClass`, `profitRange`, `noBand`, `fxUnavailable`, `invalid`. ⛔ Behind the valuation switch, OFF: 404 `refusal.marketplaceValuation.off` unless the switch is ON or the caller is a signed-in principal of a pilot organisation.","tags":["marketplace"],"security":[],"parameters":[{"name":"asset_class","in":"query","required":true,"schema":{"type":"string","enum":["websites","shopify_stores","amazon_fba","etsy_shops","domains"]}},{"name":"monthly_profit_minor","in":"query","required":true,"description":"Average monthly profit over the last 12 months, in minor units of `currency`.","schema":{"type":"integer"}},{"name":"currency","in":"query","required":false,"schema":{"type":"string","default":"USD","minLength":3,"maxLength":3}},{"name":"age_years","in":"query","required":false,"schema":{"type":"string","description":"Decimal years, 0-100."}},{"name":"trend","in":"query","required":false,"schema":{"type":"string","enum":["growing","flat","declining"]}},{"name":"top_source_share","in":"query","required":false,"description":"Percent (0-100) of revenue or traffic from the single largest source.","schema":{"type":"integer","minimum":0,"maximum":100}}],"responses":{"200":{"description":"The estimate.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceValuationEstimate"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/marketplace/valuation-status":{"get":{"operationId":"getMarketplaceValuationStatus","summary":"Whether the public valuation estimate is switched on.","description":"s1014 L69 (docs/1068 Q9). Anonymous. What the storeflips calculator asks before it shows itself; the pilot is never disclosed here.","tags":["marketplace"],"security":[],"responses":{"200":{"description":"The switch.","content":{"application/json":{"schema":{"type":"object","required":["enabled"],"properties":{"enabled":{"type":"boolean"}}}}}}}}},"/v1/marketplace/latest":{"get":{"operationId":"getMarketplaceLatestListings","summary":"The newest live listings, for a site that is not the storefront.","description":"docs/760 §2. A public, read-only feed of the newest live listings, built from the same card as the hub (`MarketplaceHubCard`): the domain is only ever the masked form, the price is the listing's public price, and no seller detail beyond the public display name is present. Anonymous, single variant, no cookie. Held for 60 seconds on the server and advertised with `Cache-Control: public, max-age=60`, because it is read by a browser island on every page view of `zinnguestposts.com` — a new listing appears within a minute, with no deploy.","tags":["marketplace"],"security":[],"parameters":[{"name":"locale","in":"query","schema":{"type":"string"},"description":"Explicit, never `Accept-Language` — see `getMarketplaceOverview`."},{"name":"vertical","in":"query","schema":{"type":"string"},"example":"guest_posts,seo_services","description":"Comma-separated vertical keys. Omitted means every live vertical. An unknown or archived key is dropped, not an error; `verticals` in the response says which were served."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":12,"default":8}},{"name":"facet","in":"query","required":false,"style":"form","explode":true,"schema":{"type":"array","maxItems":20,"items":{"type":"string","example":"niche:eq:pets"}},"description":"A choice filter, `key:eq:value`, repeatable — the same grammar and semantics as `searchPublicMarketplace`: values of one key are OR-ed, different keys are AND-ed. The keys a landing page filters on are the listing taxonomy (`platform`, `site_type`, `store_type`, `niche`, `monetization`; docs/83 §1a). Only `eq` exists here. ⛔ A filter that cannot match (malformed, another operator) empties the feed rather than being dropped, so a stale \"pet stores\" link never serves every store."},{"name":"category","in":"query","required":false,"style":"form","explode":true,"schema":{"type":"array","maxItems":20,"items":{"type":"string","example":"seo_services:audits"}},"description":"A category allow-list, `<vertical>:<category path>`, repeatable (s1006). A vertical named by any clause serves ONLY listings in those categories, a path covering its descendants (`content` covers `content/x`, not `content_writing`); a vertical with no clause is unrestricted. ⛔ A malformed clause empties the feed rather than being dropped, so an allow-list can never widen to \"everything\". Part of the cache key."}],"responses":{"200":{"description":"The newest live listings, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceLatestFeed"}}}},"422":{"description":"`limit` is not a whole number between 1 and 12.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/marketplace/freelancers":{"get":{"operationId":"listMarketplaceFreelancers","summary":"The freelancer directory — published profiles of approved Zinner® sellers.","description":"s1006 (Q60), docs/10 §3d. Anonymous and read-only. Only profiles the freelancer published, and only while their Zinner® account is approved — a suspended seller disappears from the directory at once. Held for 60 seconds.","tags":["marketplace"],"security":[],"parameters":[{"name":"q","in":"query","description":"Words in the headline, introduction, name or skills.","schema":{"type":"string","maxLength":120}},{"name":"skill","in":"query","schema":{"type":"string","maxLength":40}},{"name":"kind","in":"query","description":"A kind of work (marketplace vertical key).","schema":{"type":"string","enum":["seo_services","link_building","guest_posts","ai_automation","web_development"]}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"One page of profiles, most recently updated first.","content":{"application/json":{"schema":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceFreelancer"}},"next_cursor":{"type":"string"}}}}}}}}},"/v1/marketplace/freelancers/{slug}":{"get":{"operationId":"getMarketplaceFreelancer","summary":"One freelancer's public profile, with their live Zinn® listings.","tags":["marketplace"],"security":[],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The profile and up to 24 of the freelancer's live listings.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/MarketplaceFreelancer"},{"type":"object","required":["listings"],"properties":{"listings":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"slug":{"type":"string"},"marketplace_key":{"type":"string"},"price_minor":{"type":"integer","format":"int64"},"currency":{"type":"string"}}}}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/marketplace/freelancers/{slug}/contact":{"post":{"operationId":"contactMarketplaceFreelancer","summary":"Hire directly — open a message thread with a freelancer.","description":"Creates a `direct` marketplace conversation between the caller's org and the freelancer's, with the first message in it. The marketplace contact policy applies.","tags":["marketplace"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","maxLength":4000},"subject":{"type":"string","maxLength":180}}}}}},"responses":{"201":{"description":"The thread.","content":{"application/json":{"schema":{"type":"object","required":["conversation_id"],"properties":{"conversation_id":{"type":"string","format":"uuid"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/marketplace/freelancer/profile":{"get":{"operationId":"getOwnFreelancerProfile","summary":"Your own freelancer profile (approved Zinner® only).","tags":["marketplace"],"responses":{"200":{"description":"Whether a profile exists, and it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceOwnFreelancerProfile"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"put":{"operationId":"saveOwnFreelancerProfile","summary":"Create or update your freelancer profile.","description":"Every key is optional; an absent key is left as it is. Publishing needs a headline and at least one skill. Skills are de-duplicated case-blind (up to 20, 40 characters each). `rate_minor` is integer minor units of `rate_currency` (§2.8), null for \"ask for a quote\".","tags":["marketplace"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"headline":{"type":"string","maxLength":120},"bio":{"type":"string","maxLength":4000},"skills":{"type":"array","items":{"type":"string","maxLength":40},"maxItems":20},"project_types":{"type":"array","items":{"type":"string","enum":["seo_services","link_building","guest_posts","ai_automation","web_development"]}},"languages":{"type":"array","items":{"type":"string","pattern":"^[a-z]{2}$"},"maxItems":10},"rate_minor":{"type":"integer","format":"int64","minimum":0,"nullable":true},"rate_currency":{"type":"string","minLength":3,"maxLength":3},"rate_unit":{"type":"string","enum":["hour","day","project"]},"published":{"type":"boolean"}}}}}},"responses":{"200":{"description":"The saved profile.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceOwnFreelancerProfile"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/marketplace/freelancer/portfolio":{"post":{"operationId":"addFreelancerPortfolioItem","summary":"Add a piece of past work to your profile (up to 12).","description":"Multipart. The optional picture is normalised and stored exactly like a listing picture (JPEG, PNG or WebP; served resized at the edge). A link must be https.","tags":["marketplace"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string","maxLength":120},"description":{"type":"string","maxLength":1000},"link_url":{"type":"string","format":"uri","maxLength":500},"file":{"type":"string","format":"binary"}}}}}},"responses":{"201":{"description":"The piece of work.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplacePortfolioItem"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/marketplace/freelancer/portfolio/{item_id}":{"delete":{"operationId":"deleteFreelancerPortfolioItem","summary":"Remove a piece of work from your profile.","tags":["marketplace"],"parameters":[{"name":"item_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/marketplace/projects":{"get":{"operationId":"listMarketplaceProjects","summary":"Your posted projects, or the board of open projects (approved Zinner® sellers).","description":"`scope=mine` (default): the caller's own orgs' projects with `quote_count`. `scope=board`: every OPEN project except the caller's own org's, for an approved Zinner® only, each with `quoted` (whether you have already quoted). Briefs are never served anonymously — they are a buyer's own words.","tags":["marketplace"],"parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["mine","board"],"default":"mine"}},{"name":"category","in":"query","schema":{"type":"string","enum":["seo_services","link_building","guest_posts","ai_automation","web_development"]}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"One page, newest first.","content":{"application/json":{"schema":{"type":"object","required":["data","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceProject"}},"next_cursor":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"post":{"operationId":"createMarketplaceProject","summary":"Post a project for freelancers to quote on.","tags":["marketplace"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","brief","category"],"properties":{"title":{"type":"string","minLength":5,"maxLength":140},"brief":{"type":"string","minLength":20,"maxLength":5000},"category":{"type":"string","enum":["seo_services","link_building","guest_posts","ai_automation","web_development"]},"skills":{"type":"array","items":{"type":"string","maxLength":40},"maxItems":20},"budget_min_minor":{"type":"integer","format":"int64","minimum":0,"nullable":true},"budget_max_minor":{"type":"integer","format":"int64","minimum":0,"nullable":true},"currency":{"type":"string","minLength":3,"maxLength":3},"deadline":{"type":"string","format":"date","nullable":true}}}}}},"responses":{"201":{"description":"The project, open for quotes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceProject"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/marketplace/projects/{project_id}":{"get":{"operationId":"getMarketplaceProject","summary":"One project — its owner sees every quote, a freelancer only their own.","tags":["marketplace"],"parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The project and the quotes the caller may see.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/MarketplaceProject"},{"type":"object","required":["quotes"],"properties":{"quotes":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceProjectQuote"}}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/marketplace/projects/{project_id}/close":{"post":{"operationId":"closeMarketplaceProject","summary":"Stop taking quotes on your project.","tags":["marketplace"],"parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The closed project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceProject"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/marketplace/projects/{project_id}/quotes":{"post":{"operationId":"quoteMarketplaceProject","summary":"Quote on an open project (approved Zinner®).","description":"The quote is sold under one of the freelancer's own LIVE listings in an SEO, link building, guest post, AI or development vertical, so commission, tax and the order rules come from that listing's type. The message opens (or continues) a `direct` thread with the buyer. One live quote per freelancer per project.","tags":["marketplace"],"parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["listing_id","price_minor","delivery_days","message"],"properties":{"listing_id":{"type":"string","format":"uuid"},"price_minor":{"type":"integer","format":"int64","minimum":1},"delivery_days":{"type":"integer","minimum":1,"maximum":365},"message":{"type":"string","minLength":10,"maxLength":3000}}}}}},"responses":{"201":{"description":"The quote.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceProjectQuote"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/marketplace/projects/{project_id}/quotes/{quote_id}/{action}":{"post":{"operationId":"actOnMarketplaceProjectQuote","summary":"Accept or decline a quote (buyer), or withdraw it (freelancer).","description":"`accept` creates a package on the freelancer's listing RESERVED for the buyer's org — inactive, so no storefront shows it, buyable once and only by that org — marks the project awarded and declines the other open quotes. Put `listing_package_id` in the basket to pay: payment, the held payout (escrow), delivery, acceptance and disputes are the ordinary marketplace order flow.","tags":["marketplace"],"parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"quote_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"action","in":"path","required":true,"schema":{"type":"string","enum":["accept","decline","withdraw"]}}],"responses":{"200":{"description":"The quote after the action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceProjectQuote"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/marketplace/aged-domains":{"get":{"operationId":"listAgedDomains","summary":"Search the aged domains on sale (signed in).","description":"s1006 (owner D44) — V1's aged-domain shop, mirrored HOURLY since s1014 (a conditional read of V1's export; a sold domain leaves within the hour). Every filter V1 has: `q` (domain or description), `tld`, `language`, `category`, `min_`/`max_` for `dr`, `da`, `tf`, `cf`, `rd`, `uniques`, `added_year` and `price` (USD), flags `indexed`, `wiki`, `gnews` (`1`), `sort` (`dr`, `da`, `tf`, `cf`, `rd`, `uniques`, `price`, `added_year`, `domain`; prefix `-` for descending; unmeasured values sort last), `page`, `per_page` (25, 50 or 100). Prices are the supplier list price with no markup (owner D55). Requires authentication — any signed-in user.","tags":["marketplace"],"parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"tld","in":"query","schema":{"type":"string"}},{"name":"language","in":"query","schema":{"type":"string"}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"min_dr","in":"query","schema":{"type":"integer"}},{"name":"max_dr","in":"query","schema":{"type":"integer"}},{"name":"min_price","in":"query","schema":{"type":"string"},"description":"USD, e.g. 49.99"},{"name":"max_price","in":"query","schema":{"type":"string"}},{"name":"sort","in":"query","schema":{"type":"string","default":"-dr"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","enum":[25,50,100],"default":50}}],"responses":{"200":{"description":"One page of matching domains, the total, and the facet values on sale.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgedDomainPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/public/aged-domains":{"get":{"operationId":"listPublicAgedDomains","summary":"The aged domains on sale, filtered, sorted and paged, every row masked (public).","description":"MKTDOMAINS (owner 2026-11-02) — what zinndigital.com/marketplace/domains renders: the same stock, filters and sort as `listAgedDomains`, for a visitor who is not signed in. ⛔ No domain is NAMED — each row carries `masked_domain` and the `id` the app's detail page (`getAgedDomain`, signed in) opens; that page runs the live check and the checkout (docs/1107 §3, §5). `q` matches the description only and `sort=domain` falls back to `-dr`, so the name cannot be recovered a letter at a time. Filters: `q`, `tld`, `language`, `category`, `min_`/`max_` for `dr`, `da`, `tf`, `cf`, `rd`, `uniques`, `added_year` and `price` (USD), flags `indexed`, `wiki`, `gnews` (`1`); `sort` as `listAgedDomains` except `domain`; `per_page` 24, 48 or 96. Prices are the supplier list price with no markup (owner D55), integer USD minor units. Cached 5 minutes per query, facets 15 minutes; no authentication.","tags":["marketplace"],"security":[],"parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"tld","in":"query","schema":{"type":"string"}},{"name":"language","in":"query","schema":{"type":"string"}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"min_dr","in":"query","schema":{"type":"integer"}},{"name":"max_dr","in":"query","schema":{"type":"integer"}},{"name":"min_tf","in":"query","schema":{"type":"integer"}},{"name":"min_rd","in":"query","schema":{"type":"integer"}},{"name":"max_added_year","in":"query","schema":{"type":"integer"}},{"name":"min_price","in":"query","schema":{"type":"string"},"description":"USD, e.g. 49.99"},{"name":"max_price","in":"query","schema":{"type":"string"}},{"name":"indexed","in":"query","schema":{"type":"string","enum":["1"]}},{"name":"wiki","in":"query","schema":{"type":"string","enum":["1"]}},{"name":"sort","in":"query","schema":{"type":"string","default":"-dr"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","enum":[24,48,96],"default":24}}],"responses":{"200":{"description":"One masked page of matching domains, the total, and the public facet counts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgedDomainPublicPage"}}}}}}},"/v1/public/aged-domains/summary":{"get":{"operationId":"getPublicAgedDomainSummary","summary":"The aged domains on sale, counted, with a masked sample (public).","description":"AGED1 (owner 2026-10-20) — what zinndigital.com/aged-domains renders: how many aged domains are on sale now, the lowest price, DR bands, the top TLDs and languages, and the ten highest-DR domains priced at or under USD 1,000. ⛔ No domain is NAMED — each sample row carries `masked_domain` (first and last letter, extension) — because the full list is signed-in only (`listAgedDomains`). Prices are the supplier list price with no markup (owner D55), integer USD minor units. Cached 15 minutes; no authentication.","tags":["marketplace"],"security":[],"responses":{"200":{"description":"The live stock summary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgedDomainPublicSummary"}}}}}}},"/v1/marketplace/aged-domains/{domain_id}/order":{"post":{"operationId":"orderAgedDomain","summary":"Order an aged domain — opens a support ticket in the caller's org.","description":"s1006 (owner D44): no payment is taken here; the ticket carries the domain, price and metrics and staff complete the purchase. Requires `tickets.reply` in the org (the org comes from the caller's scope or `X-Zinn-Org`). An unavailable domain is 404.","tags":["marketplace"],"parameters":[{"name":"domain_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","maxLength":2000},"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"201":{"description":"The ticket that was opened.","content":{"application/json":{"schema":{"type":"object","required":["ticket_id","domain","price_minor"],"properties":{"ticket_id":{"type":"string","format":"uuid"},"domain":{"type":"string"},"price_minor":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/marketplace/aged-domains/{domain_id}":{"get":{"operationId":"getAgedDomain","summary":"One aged domain — every figure we hold, its live check, similar domains (signed in).","description":"s1014 DOMAINS (owner: \"Full detail page\"). Everything V1's `/domains/domain/<pk>` shows — DR/DA/TF/CF/RD, monthly traffic, indexed / Wikipedia / Google News, language, categories, description, possible use, history from (`date_added_on`) — plus the last LIVE availability answer (`live`), the price in the visitor's currency as an approximation (`price_local`, plain conversion — the charge is USD), a Wayback Machine link and up to six similar domains on sale (same first category, nearest DR). A sold domain still answers, with `available: false`, so an old link says so and offers others. `enquire_only` is true when the source marks it or its price is above the shop settings' self-serve ceiling.","tags":["marketplace"],"parameters":[{"name":"domain_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The domain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgedDomainDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/public/guest-post-sites":{"get":{"operationId":"listPublicGuestPostSites","summary":"Guest-post sites on sale, filtered, sorted and paged, every row blurred (public).","description":"GUESTFEED1114 (ZinnHub ZH-5491, owner 2026-11-14) — the guest-post sites from ZinnHub's site-listings feed (synced hourly), for a visitor who is not signed in. ⛔ No site is NAMED: every row is `label` \"Site 12\" (its number) with `domain`, `domain_ascii`, `name` and `sample_url` null and `revealed: false`, even when a bearer token is sent (this endpoint reads no credentials at all). No filter or sort reads the real domain, so it cannot be probed. Filters: `language`, `country`, `min_dr`, `max_price_minor`, `link_type`; `sort` `dr` (default), `price` or `newest`; `per_page` 24, 48 or 96. Prices are integer minor units of `currency`, before VAT. Cached 5 minutes; no authentication (docs/1309).","tags":["marketplace"],"security":[],"parameters":[{"name":"language","in":"query","schema":{"type":"string"}},{"name":"country","in":"query","schema":{"type":"string"},"description":"ISO 3166-1 alpha-2"},{"name":"min_dr","in":"query","schema":{"type":"integer"}},{"name":"max_price_minor","in":"query","schema":{"type":"integer"}},{"name":"link_type","in":"query","schema":{"type":"string"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["dr","price","newest"],"default":"dr"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","enum":[24,48,96],"default":24}}],"responses":{"200":{"description":"One blurred page of guest-post sites.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GuestPostSitePage"}}}}}}},"/v1/marketplace/guest-post-sites":{"get":{"operationId":"listGuestPostSites","summary":"Guest-post sites on sale, for a signed-in buyer, every row with its real domain.","description":"GUESTFEED1114 — the same filters as `listPublicGuestPostSites`. Real site names are shown once you sign in (owner 2026-11-15): every row carries its real `domain` and `domain_ascii` with `revealed: true`, and `name` and `sample_url` where the site has them (otherwise null). A row the feed sent without a real domain is left out of this list (and is 404 on `getGuestPostSite` and `orderGuestPostSite`), and the sync raises an ops alert naming the count; a blurred ZinnHub feed (consumer `v2-catalogue`) raises a critical alert. Responses are `Cache-Control: private, no-store`. Requires authentication — any signed-in user (docs/1309 §1 rule 1a).","tags":["marketplace"],"parameters":[{"name":"language","in":"query","schema":{"type":"string"}},{"name":"country","in":"query","schema":{"type":"string"},"description":"ISO 3166-1 alpha-2"},{"name":"min_dr","in":"query","schema":{"type":"integer"}},{"name":"max_price_minor","in":"query","schema":{"type":"integer"}},{"name":"link_type","in":"query","schema":{"type":"string"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["dr","price","newest"],"default":"dr"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","enum":[24,48,96],"default":24}}],"responses":{"200":{"description":"One page of guest-post sites.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GuestPostSitePage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/marketplace/guest-post-sites/{site_uid}":{"get":{"operationId":"getGuestPostSite","summary":"One guest-post site, every offer and metric (signed in).","description":"GUESTFEED1114 — one site by its stable feed id (`s<digits>`), with its real domain, its name and, where the site has one, its sample link. A site with no real domain is 404, as in `listGuestPostSites`. `Cache-Control: private, no-store`.","tags":["marketplace"],"parameters":[{"name":"site_uid","in":"path","required":true,"schema":{"type":"string","pattern":"^s[0-9]{1,18}$"}}],"responses":{"200":{"description":"The site.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GuestPostSite"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/marketplace/guest-post-sites/{site_uid}/order":{"post":{"operationId":"orderGuestPostSite","summary":"Order a guest post on one site — opens a support ticket in the caller's org.","description":"GUESTFEED1114: no payment is taken here; the ticket (origin `guest_post_site_order`) carries the site, the chosen offer and its price, and staff fulfil it with the seller. Requires `tickets.reply` in the org (the caller's scope or `X-Zinn-Org`). An unknown site or offer index is 404.","tags":["marketplace"],"parameters":[{"name":"site_uid","in":"path","required":true,"schema":{"type":"string","pattern":"^s[0-9]{1,18}$"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"offer_index":{"type":"integer","minimum":0,"default":0},"note":{"type":"string","maxLength":2000},"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"201":{"description":"The ticket that was opened.","content":{"application/json":{"schema":{"type":"object","required":["ticket_id","site_uid","currency"],"properties":{"ticket_id":{"type":"string","format":"uuid"},"site_uid":{"type":"string"},"price_minor":{"type":["integer","null"]},"currency":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/marketplace/aged-domains/{domain_id}/check":{"post":{"operationId":"checkAgedDomain","summary":"Ask the supplier now whether this domain is still for sale — in the background.","description":"s1014 DOMAINS. Answers at once with 202 and the `live` block; the check itself runs as a Temporal workflow (one per domain at a time — a second ask joins it) because the supplier can take ~35 s cold. Poll `getAgedDomain` until `live.checking` is false. An answer younger than the shop settings' `check_fresh_seconds` (default 120, V1's) is reused without a new call. `sold` takes the domain off sale at once; `unknown` (the supplier did not answer) never does. Our own stock answers `available` without a supplier call.","tags":["marketplace"],"parameters":[{"name":"domain_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"The check is running, or a fresh answer is returned.","content":{"application/json":{"schema":{"type":"object","required":["live","available"],"properties":{"live":{"$ref":"#/components/schemas/AgedDomainLiveCheck"},"available":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/marketplace/aged-domain-orders":{"get":{"operationId":"listAgedDomainOrders","summary":"Your aged-domain orders, newest first (signed in).","description":"s1014 DOMAINS (V1's `/domains/orders`). Each order's state — `holding` (placed, held for payment until `hold_expires_at`), `paid`, `ordered` (checked again after payment and being bought for you), `delivered`, `refunded` (gone at the supplier after payment — refunded in full), `expired`, `cancelled` — with the price paid, where it is going, the commerce order and the ticket staff update. Only the caller's organisations.","tags":["marketplace"],"responses":{"200":{"description":"The orders.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgedDomainOrder"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/marketplace/listing-types":{"get":{"operationId":"listSellableMarketplaceListingTypes","summary":"The kinds of Zinn® this account may sell.","description":"What populates the chooser on the seller's \"start a listing\" form. Requires an **approved** Zinner® — the same gate `createMarketplaceListing` applies, so the chooser and the create call can never disagree about who may sell.\n\n⛔ Excludes archived types, types with no vertical, and `first_party_only` types (docs/78 §6 ruling 7 — those skip review and carry no commission row, so offering one to a third party would publish straight to the storefront with no queue). `createMarketplaceListing` already refuses them with `FIRST_PARTY_ONLY`, and a chooser that offers a choice the next call rejects is the #2872 defect in another costume.\n\n⭐ This endpoint existed nowhere until #2606. The only list of listing types was `/v1/admin/marketplace/listing-types`, which a vendor cannot call — so the seller form had no way to populate a picker, and the create control was simply never built. Measured in a browser on 2026-08-19 as an approved vendor: `/sell` rendered its heading and \"You have not listed anything yet.\" with **no button, link or input** on the page.","tags":["marketplace"],"responses":{"200":{"description":"The sellable listing types, grouped by vertical in name order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellableListingTypeList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"This account is not a Zinner®.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"This account is a Zinner® but is not approved yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/marketplace/listings":{"get":{"operationId":"listMyMarketplaceListings","summary":"The Zinn®s this account sells.","description":"Org-scoped. A Zinner® sees their own listings and nobody else's — Postgres RLS plus an explicit `org_id` filter, because RLS is a no-op on SQLite and the ORM filter is what holds on every backend.","tags":["marketplace"],"responses":{"200":{"description":"This account's listings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceListingList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"operationId":"createMarketplaceListing","summary":"Start a Zinn®.","description":"Creates a draft. The listing type's CURRENT schema version is stamped onto it here, once, and never moved — tightening the type's schema later must not retroactively invalidate what was authored under the old one (docs/78 §4.2 trap 2).\n\n⛔ The Zinner® must be `approved`. docs/78 §3.2 makes `under_review` the anti-fraud gate rather than a formality, and an account that can author listings while under review has walked straight through it.","tags":["marketplace"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceListingCreate"}}}},"responses":{"201":{"description":"The draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceListing"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"description":"That web address is already taken in this marketplace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"No such listing type, a type sold by Zinn Digital® only, a category from another vertical, a missing title, or a Zinner® that is not approved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/marketplace/listings/bulk":{"post":{"operationId":"bulkUpsertListings","summary":"Create or update up to 200 per-site guest-post listings in one call.","description":"s1006 (owner D41). Guest posts are listed one per SITE. The dashboard parses the seller's CSV (template at `/v1/marketplace/listings/bulk/template.csv`) and sends it in batches of at most 200 rows. Each row is created — or UPDATED when this seller already lists that site under that type (never duplicated) — and published through the ordinary path (measured metrics, content scan, review queue / automatic publish). A bad row is reported with its line and reason and never stops the batch. Requires an approved seller account. Translation of each live listing's copy starts in a background workflow after the call returns (ANTHSPEND1114), so the response never waits on language detection.","tags":["marketplace"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rows"],"properties":{"listing_type":{"type":"string","enum":["guest_post","niche_edit"],"default":"guest_post"},"first_line":{"type":"integer","minimum":1,"description":"The CSV line of the first row, so reported lines match the file."},"rows":{"type":"array","minItems":1,"maxItems":200,"items":{"type":"object","description":"`site_domain`*, `price_usd`*, `link_type`* (dofollow|nofollow), `link_duration`* (permanent|twelve_months|monthly), `traffic_bracket`, `niche`, `category`, `delivery_days`, `title`, `summary`, `sample_url`.","additionalProperties":{"type":"string"}}}}}}}},"responses":{"200":{"description":"One result per row, in order.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["line","status"],"properties":{"line":{"type":"integer"},"status":{"type":"string","enum":["created","updated","error"]},"listing_id":{"type":"string"},"state":{"type":"string"},"error":{"type":"string"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/marketplace/listings/bulk/template.csv":{"get":{"operationId":"getBulkListingTemplate","summary":"The example CSV for bulk per-site guest posts (public).","description":"s1006 (owner D41) — a header row and two filled examples. No sign-in.","tags":["marketplace"],"security":[],"responses":{"200":{"description":"The CSV file.","content":{"text/csv":{"schema":{"type":"string"}}}}}}},"/v1/marketplace/listings/from-site":{"post":{"operationId":"listListingFromSite","summary":"Sell a site hosted with Zinn® — a draft listing, filled in from the site.","description":"docs/714 §3. Creates (or returns the open) draft `website` listing pointed at the site, with the domain filled in, our own server-log traffic and uptime measured onto it, and the platform's checklist rows added. When it sells, the site, its files, database, DNS, mail, remaining paid term and registered domain move into the buyer's account automatically.\n\nNeeds `sites.transfer` on the site's organization AND an approved Zinner® account. Refused at listing time for anything that would make the sale undeliverable — a site that is not active or has no paid term of its own.","tags":["marketplace"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["site_id"],"properties":{"site_id":{"type":"string","format":"uuid"},"title":{"type":"string","maxLength":180}}}}}},"responses":{"201":{"description":"The draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceListing"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"The site cannot be sold as it stands, or the account is not an approved Zinner®.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/marketplace/listings/from-domain":{"post":{"operationId":"listListingFromDomain","summary":"Sell a domain held with Zinn® — a draft listing, filled in from the domain.","description":"docs/57 §3.1, docs/714 §3. Creates (or returns the open) draft `domain` listing. When it sells, the domain, its DNS zone and any mail on it move into the buyer's account with no transfer code; the seller's registrant record is NOT carried, and the buyer cannot confirm receipt until they have entered their own. While the listing is in review, live or paused the domain's transfer code, transfer lock, auto-renew and removal are held.\n\nNeeds `domains.dns.manage` AND an approved Zinner® account. Refused for a domain that is not active, is the address of a site (sell the site), or expires within 30 days without auto-renew.","tags":["marketplace"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain_id"],"properties":{"domain_id":{"type":"string","format":"uuid"},"title":{"type":"string","maxLength":180}}}}}},"responses":{"201":{"description":"The draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceListing"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"The domain cannot be sold as it stands, or the account is not an approved Zinner®.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/marketplace/listings/{listing_id}":{"get":{"operationId":"getMarketplaceListing","summary":"One of this account's Zinn®s, with the schema it is authored against.","description":"`field_schema` is the version stamped on THIS listing, not the type's current head — so a form built from it edits the listing as it actually is.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The listing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceListing"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"operationId":"updateMarketplaceListing","summary":"Edit a Zinn®, or publish it.","description":"`publish: true` validates every value against the stamped schema version, requires at least one package, recomputes the price cache and takes the listing live — in one transaction, because a listing that went live with a stale price sorts wrongly on every storefront page and quotes a price nobody agreed to, and nothing raises.\n\n⛔ A live Zinn®'s `slug` is permanent: it is the public URL, and changing it breaks every link to it and loses the ranking that link earned.\n\n⛔ A `domain` value is stored in the reveal table, never in `field_values` — the storefront's read path cannot leak what it cannot see (docs/83 §3).","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceListingUpdate"}}}},"responses":{"200":{"description":"The updated listing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceListing"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"A value the schema refuses, an unknown field key, a rename of a live slug, or a publish with no package.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/marketplace/listings/{listing_id}/images":{"get":{"operationId":"listMarketplaceListingImages","summary":"A listing's images, and the limits an upload must satisfy.","description":"⭐ The **policy travels with the list** so an upload control can state the real limits before a seller picks a file. A limit discovered only by having an upload rejected is a limit that wastes the seller's time.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The images, cover first, plus the effective image policy.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceImageList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"uploadMarketplaceListingImage","summary":"Upload one image to a listing.","description":"The bytes are decoded to decide the format — the declared `Content-Type` and the filename are both caller-chosen — checked against the listing type's policy, stripped of EXIF and re-encoded with orientation applied, and only then stored. A rejected upload leaves nothing behind: no object, no row.\n\n⛔⛔ **EXIF is removed before storage, not on the way out.** A phone photo of a house for sale carries the GPS coordinates of the house.\n\n⛔ **An image is content**, so adding one to a live third-party listing takes it off sale and back into the review queue (`docs/78` §5).\n\nA 422 carries `code` and `params` in `details` — `TOO_SMALL` with the actual and required dimensions, for example — so the surface renders the sentence in the seller's own language rather than the engine hardcoding English (CLAUDE.md §2.19).","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"JPEG, PNG or WebP. Decided by decoding, not by this declaration."},"alt":{"type":"string","maxLength":300,"description":"Alt text — an accessibility requirement and a localised SEO surface (CLAUDE.md §2.19), not an afterthought."}}}}}},"responses":{"201":{"description":"The stored image.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceImage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/marketplace/listings/{listing_id}/images/{image_id}":{"patch":{"operationId":"updateMarketplaceListingImage","summary":"Set the alt text, the gallery position, or make this the cover.","description":"Promoting a cover demotes the incumbent in the same write — there is a partial unique constraint allowing exactly one cover per listing, so doing it in two steps would fail.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"image_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceImageUpdate"}}}},"responses":{"200":{"description":"The updated image.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceImage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"operationId":"deleteMarketplaceListingImage","summary":"Remove an image, and its stored object.","description":"The object is deleted too — an orphan is a bill that never stops and, for an image a seller removed precisely because they did not want it public, a URL that still works. Deleting the cover promotes the next image rather than leaving the listing coverless.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"image_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/marketplace/listings/{listing_id}/revenue-verification":{"get":{"operationId":"getMarketplaceListingRevenueVerification","summary":"Your listing's Stripe revenue verification, and whether the key is kept.","description":"s1014 L69 (Q6), docs/83 §1e. The seller's own view: `status` is `not_connected`, `one_off` (read once, key not kept), `active` (key kept in Vault, re-read weekly) or `lapsed` (two refreshes failed and the kept key was deleted). Figures are in the Stripe account's own `currency`, integer minor units. Never the key, never where it is kept.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The connection status.","content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["not_connected","one_off","active","lapsed"]},"kept":{"type":"boolean"},"currency":{"type":"string"},"payouts_12m_minor":{"type":["integer","null"]},"payouts":{"type":["integer","null"]},"mrr_minor":{"type":["integer","null"],"description":"Monthly recurring revenue of active subscriptions; null when unknown."},"active_subscriptions":{"type":["integer","null"]},"measured_at":{"type":["string","null"],"format":"date-time"},"failed_refreshes":{"type":"integer"},"last_error":{"type":"string","description":"A `refusal.marketplaceRevenue.<code>` code, or empty."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"verifyMarketplaceListingRevenue","summary":"Verify a site or store's revenue from the seller's Stripe payouts and subscriptions.","description":"s1006 (slice 3, owner D41) and s1014 L69 (Q6), docs/83 §1e. The seller of a website or store listing sends a Stripe RESTRICTED live key (`rk_live_…`) with Payouts set to Read (and Subscriptions set to Read for monthly recurring revenue). The engine reads the account's paid payouts of the last 12 months and its active subscriptions (normalised to a month), keeps the figures in the account's own currency and stores two measured values stamped `by: stripe` in whole US dollars, converted at the marketplace's exchange rate (`stripe_payouts_12m`, `stripe_payouts_monthly_avg`), shown to buyers as verified with their date. ⛔ By default the key is used in this request only and is never stored, logged or echoed. ONLY with `keep_verified: true` (the seller's explicit opt-in) is it kept in Vault and re-read weekly; it is deleted on disconnect, when the listing is sold or closed, after two failed refreshes, or when the seller re-verifies without the opt-in. A secret key (`sk_`), a test key or a publishable key is refused before any call to Stripe.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["stripe_restricted_key"],"properties":{"stripe_restricted_key":{"type":"string","writeOnly":true,"pattern":"^rk_live_"},"keep_verified":{"type":"boolean","default":false,"description":"Keep the key in Vault and re-read Stripe weekly. Off unless the seller ticks it."}}}}}},"responses":{"200":{"description":"What was verified and stored.","content":{"application/json":{"schema":{"type":"object","required":["payouts_12m","monthly_average","currency","payouts","verified_at","kept"],"properties":{"payouts_12m":{"type":"integer","description":"Whole units of `currency` (US dollars)."},"monthly_average":{"type":"integer"},"currency":{"type":"string","description":"Always USD","the display currency.":null},"payouts":{"type":"integer","description":"How many payouts were counted."},"account_currency":{"type":"string"},"account_payouts_12m_minor":{"type":"integer","description":"Minor units of `account_currency`."},"mrr_minor":{"type":["integer","null"],"description":"Minor units of `account_currency`; null when unknown."},"active_subscriptions":{"type":["integer","null"]},"mrr_note":{"type":"string","description":"Why MRR is unknown (`needsSubscriptionsRead`, `tooManySubscriptions`), or empty."},"kept":{"type":"boolean"},"verified_at":{"type":"string","format":"date-time"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"removeMarketplaceListingRevenueVerification","summary":"Disconnect Stripe and remove the verified figures from your listing.","description":"The kept key (if any) is deleted from Vault, then the connection and both figures.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/marketplace/listings/{listing_id}/valuation":{"get":{"operationId":"getMarketplaceListingValuation","summary":"The seller's estimate for their own listing, with every figure's basis (an estimate, not advice).","description":"s1014 L69 (docs/1068 Q9/Q17). The seller's own listing only (404 otherwise). Profit is the listing's monthly profit; a figure Zinn® read itself (Stripe payouts, GA4 visitors, fresh within the Verified badge's maximum age) is `verified` and raises verification coverage; typed figures are `declared`. `trend` and `top_source_share` are optional refinements the seller picks on the page. Also returns the listing `multiple`. 404 `refusal.marketplaceValuation.off` while the deal-room switch is OFF (unless the seller's organisation is a valuation pilot).","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"trend","in":"query","required":false,"schema":{"type":"string","enum":["growing","flat","declining"]}},{"name":"top_source_share","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":100}}],"responses":{"200":{"description":"The estimate.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceValuationEstimate"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/marketplace/listings/{listing_id}/managed-sale":{"get":{"operationId":"getMarketplaceListingManagedSale","summary":"The managed-sale add-on for your own listing — offered, its price, whether this listing qualifies.","description":"s1014 L69 (docs/1068 §9e, owner 2026-10-20). Our deal desk runs the sale for a flat fee per sale (the catalogue row `marketplace_managed_sale`, USD 499 converted to the caller's currency like every add-on). Only for a business listing (website, Shopify store, Amazon FBA business, Etsy shop) whose asking price (its dearest package) is UNDER `deal_desk_from_usd_minor` (default USD 100,000); at or above it the free deal desk helps instead (`reason: dealDeskInstead`). The seller's own listing only (404 otherwise).","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"currency","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The add-on for this listing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceManagedSaleState"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"buyMarketplaceListingManagedSale","summary":"Buy the managed sale for your own listing (a flat fee; our deal desk takes it from there).","description":"s1014 L69 (docs/1068 §9e). Needs `billing.payment.manage` on the seller organisation. Wallet credit or a stored mandate settles it at once (201); with neither, 422 `refusal.marketplaceManagedSale.payment` carries the order's payment step to pay in place (Q225) and the purchase waits — buying again for the same listing resumes it. Paid, it reaches the deal desk queue as a `managed_sale` case. Refunds follow the add-on refund rules (docs/26); a refund closes the case. 422 codes: `unavailable` (not launched for this organisation), `notBusiness`, `listingClosed`, `noPrice`, `fxUnavailable`, `dealDeskInstead`, `alreadyBought`, `declined`.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string","description":"The currency the price was quoted in."},"gateway":{"type":"string","description":"The payment rail the customer chose."}}}}}},"responses":{"201":{"description":"Bought; the managed sale is with our deal desk.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/MarketplaceManagedSaleState"},{"type":"object","required":["purchase_id","status"],"properties":{"purchase_id":{"type":"string","format":"uuid"},"status":{"type":"string"}}}]}}}},"400":{"description":"Invalid body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Refused before any charge, waiting for payment, or declined.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/marketplace/listings/{listing_id}/amazon-report":{"get":{"operationId":"getMarketplaceListingAmazonReport","summary":"Whether your Amazon FBA listing can take an Amazon report, and what is stamped now.","description":"s1014 L69 (docs/1068 §4, owner Q7). `available` is false while the feature switch is off or the listing is not an Amazon FBA business. `current` is the stamped figures (or null). `supported_languages` lists the Seller Central languages the reader understands.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The upload status.","content":{"application/json":{"schema":{"type":"object","required":["available","current","supported_languages","max_bytes"],"properties":{"available":{"type":"boolean"},"current":{"type":["object","null"],"properties":{"net_proceeds":{"type":"integer","description":"Whole units of `currency`."},"net_proceeds_minor":{"type":"integer","description":"Minor units of `currency`."},"currency":{"type":"string"},"months":{"type":"integer"},"period_from":{"type":"string","description":"YYYY-MM"},"period_to":{"type":"string","description":"YYYY-MM"},"verified_at":{"type":"string","format":"date-time"}}},"supported_languages":{"type":"array","items":{"type":"string","enum":["en","de","fr","es","it","ja"]}},"max_bytes":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"uploadMarketplaceListingAmazonReport","summary":"Add Amazon sales to your FBA listing from a Seller Central Date Range report.","description":"s1014 L69 (docs/1068 §4). Multipart field `file`: the Date Range (transaction) report CSV exactly as Seller Central downloads it, in English (US, UK, Canada, Australia), German, French, Spanish, Italian or Japanese. Amounts and dates are parsed by the report's own conventions and never translated. The engine sums net proceeds (excluding transfers to the bank) and product sales per month in integer minor units over the last up to 12 consecutive months, and stamps four measured values (`amazon_net_proceeds`, `amazon_net_proceeds_monthly_avg`, `amazon_product_sales`, `amazon_report_months`) with `by: amazon_report`, the report's currency and its SHA-256. ⛔ The file is never stored (it holds buyers' postcodes). Refusals name the problem: `unknownLayout`, `numberFormat`, `dateFormat`, `monthGap`, `tooFewMonths`, `futureDates`, `mixedCurrencies`, `currencyUnknown`, `noOrders`, `notAReport`, `emptyFile`, `fileTooLarge`, `notThisKind`. 409 `switchOff` while the feature switch is off.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"}}}}}},"responses":{"200":{"description":"What was read and stamped.","content":{"application/json":{"schema":{"type":"object","required":["net_proceeds","net_proceeds_monthly_avg","product_sales","net_proceeds_minor","product_sales_minor","currency","months","period_from","period_to","orders","refunds","variant","verified_at"],"properties":{"net_proceeds":{"type":"integer","description":"Whole units of `currency`."},"net_proceeds_monthly_avg":{"type":"integer"},"product_sales":{"type":"integer"},"net_proceeds_minor":{"type":"integer","description":"Minor units of `currency`."},"product_sales_minor":{"type":"integer"},"currency":{"type":"string"},"months":{"type":"integer"},"period_from":{"type":"string"},"period_to":{"type":"string"},"orders":{"type":"integer"},"refunds":{"type":"integer"},"variant":{"type":"string","enum":["en","de","fr","es","it","ja"]},"verified_at":{"type":"string","format":"date-time"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"removeMarketplaceListingAmazonReport","summary":"Remove the Amazon report figures from your listing.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/marketplace/listings/{listing_id}/deal-room":{"get":{"operationId":"getMarketplaceListingDealRoom","summary":"Your business listing's deal-room choice (NDA, hidden identity) and who has signed.","description":"s1014 L69 (docs/1068 §6, owner Q10 + Q19). `available` is false while the switch is off or the listing is not a business for sale (websites, Shopify stores, Amazon FBA, Etsy shops, domains). `signatures` lists the buyer organisations that signed this listing's NDA. Your own listing only.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The deal room.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceListingDealRoom"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"operationId":"setMarketplaceListingDealRoom","summary":"Ask buyers to sign an NDA, and optionally hide the name and URL until they do.","description":"`hide_identity` implies `nda_required`. 409 `refusal.marketplaceDealRoom.switchOff` while the switch is off; 422 `notBusinessListing` for a listing that is not a business for sale.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["nda_required","hide_identity"],"properties":{"nda_required":{"type":"boolean"},"hide_identity":{"type":"boolean"}}}}}},"responses":{"200":{"description":"The deal room as it now stands.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceListingDealRoom"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/marketplace/listings/{listing_id}/nda":{"get":{"operationId":"getMarketplaceListingNda","summary":"A live listing's NDA in your language, and whether your organisation has signed.","description":"s1014 L69 (docs/1068 §6). `nda` is null when the listing asks for no NDA. The text is shown whole in `locale` or, until every paragraph is translated, whole in English (never mixed) — `nda.locale` is the language actually shown. `shown_sha256` is what you send back to sign.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"locale","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The NDA status.","content":{"application/json":{"schema":{"type":"object","required":["required","hide_identity","signed","own_listing","nda"],"properties":{"required":{"type":"boolean"},"hide_identity":{"type":"boolean"},"signed":{"type":"boolean"},"own_listing":{"type":"boolean"},"nda":{"type":["object","null"],"required":["version","locale","paragraphs","source_sha256","shown_sha256"],"properties":{"version":{"type":"integer"},"locale":{"type":"string"},"paragraphs":{"type":"array","items":{"type":"string"}},"source_sha256":{"type":"string","description":"SHA-256 of the English text."},"shown_sha256":{"type":"string","description":"SHA-256 of the text shown."}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"signMarketplaceListingNda","summary":"Sign a listing's NDA for your organisation.","description":"Send the `locale` and `shown_sha256` you were shown; the engine recomputes the text and refuses a mismatch (409 `textChanged`). Records the signer, organisation, time, IP address, browser and both hashes. A member of several organisations names one with `org_id` (or `X-Zinn-Org`). Audited as `marketplace.deal_room.nda_signed`. Signing again returns the existing signature.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["shown_sha256"],"properties":{"locale":{"type":"string"},"shown_sha256":{"type":"string","minLength":64,"maxLength":64},"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"201":{"description":"Signed.","content":{"application/json":{"schema":{"type":"object","required":["signed","signed_at","template_version","locale"],"properties":{"signed":{"type":"boolean"},"signed_at":{"type":"string","format":"date-time"},"template_version":{"type":"integer"},"locale":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/marketplace/listings/{listing_id}/data-room":{"get":{"operationId":"getMarketplaceListingDataRoom","summary":"A live listing's data room as your organisation sees it (buyer).","description":"s1014 L69 (docs/1068 §7, Q11). Re-checked on every read: the switch, the seller's NDA policy, your organisation's signature, at or above the threshold your approved KYC and a staff proof-of-funds check covering the asking price, and the seller's approval. `missing` names every unmet condition (`ndaRequired`, `kycRequired`, `proofOfFundsRequired`, `sellerApprovalRequired`; or `switchOff` / `noDataRoom`); `documents` lists the approved documents only when `open`. A member of several organisations names one with `X-Zinn-Org`.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The data room for your organisation.","content":{"application/json":{"schema":{"type":"object","required":["org_id","open","missing","access_state","checks_required","documents"],"properties":{"org_id":{"type":"string","format":"uuid"},"open":{"type":"boolean"},"missing":{"type":"array","items":{"type":"string"}},"access_state":{"type":["string","null"],"enum":["requested","approved","declined","revoked",null]},"checks_required":{"type":"boolean"},"documents":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceDataRoomDocument"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/marketplace/listings/{listing_id}/data-room/access-request":{"post":{"operationId":"requestMarketplaceListingDataRoomAccess","summary":"Ask the seller to open the data room to your organisation (buyer).","description":"Needs the NDA signed first (403 `ndaRequired`). Asking again after a decline or a revocation puts the request back to the seller. Audited as `marketplace.data_room.access_requested`. Nothing is sent: the seller sees the request in Marketplace → Sell.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","maxLength":1000},"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"201":{"description":"The request as it now stands.","content":{"application/json":{"schema":{"type":"object","required":["id","state"],"properties":{"id":{"type":"string","format":"uuid"},"state":{"type":"string","enum":["requested","approved","declined","revoked"]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/marketplace/listings/{listing_id}/data-room/documents":{"get":{"operationId":"listMarketplaceListingDataRoomDocuments","summary":"Your listing's data-room documents and their review state (seller).","description":"s1014 L69 (docs/1068 §7, Q12). Your own listing only. `storage_ready` false means uploads refuse until the private bucket is configured.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The documents.","content":{"application/json":{"schema":{"type":"object","required":["storage_ready","max_bytes","allowed_types","documents"],"properties":{"storage_ready":{"type":"boolean"},"max_bytes":{"type":"integer"},"allowed_types":{"type":"array","items":{"type":"string"}},"documents":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceDataRoomDocument"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"uploadMarketplaceListingDataRoomDocument","summary":"Add a document to your listing's data room (seller).","description":"multipart/form-data with `file` (PDF, PNG, JPEG or CSV, at most 25 MB, checked against its bytes) and `title`. Scanned for malware BEFORE it is stored — anything but clean is refused. Needs the listing's NDA policy on (409 `ndaPolicyRequired`). Waits for staff review before any buyer sees it. 503 `storageUnavailable` when the private bucket is not configured — nothing is stored. Audited as `marketplace.data_room.document_uploaded`.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file","title"],"properties":{"file":{"type":"string","format":"binary"},"title":{"type":"string","maxLength":200}}}}}},"responses":{"201":{"description":"Stored, waiting for review.","content":{"application/json":{"schema":{"type":"object","required":["document"],"properties":{"document":{"$ref":"#/components/schemas/MarketplaceDataRoomDocument"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/marketplace/listings/{listing_id}/data-room/documents/{document_id}":{"delete":{"operationId":"deleteMarketplaceListingDataRoomDocument","summary":"Take a document out of your listing's data room (seller).","description":"The stored object and its row go. Audited as `marketplace.data_room.document_removed`.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/marketplace/listings/{listing_id}/data-room/documents/{document_id}/download":{"get":{"operationId":"downloadMarketplaceListingDataRoomDocument","summary":"Your organisation's watermarked copy of a data-room document (buyer).","description":"Q12 — every copy carries your organisation, your name and the date (PDF pages, images, or a CSV first line) and is logged per buyer; a file that cannot be stamped is never served (422 `watermarkFailed`). Served as an attachment, `nosniff`, sandboxed. 403 names the first unmet condition of the data-room gate. Audited as `marketplace.data_room.download`.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The stamped file.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}},"image/png":{"schema":{"type":"string","format":"binary"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}},"text/csv":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/marketplace/listings/{listing_id}/data-room/access":{"get":{"operationId":"listMarketplaceListingDataRoomAccess","summary":"Buyer organisations asking to see your listing's data room (seller).","description":"`buyer_missing` is what each buyer still lacks besides your approval (NDA, KYC, proof of funds) — an approval opens nothing until those are met.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The requests, newest first.","content":{"application/json":{"schema":{"type":"object","required":["requests"],"properties":{"requests":{"type":"array","items":{"type":"object","required":["id","buyer_org_id","buyer_org_name","state","message","requested_by","created_at","decided_at","buyer_missing"],"properties":{"id":{"type":"string","format":"uuid"},"buyer_org_id":{"type":"string","format":"uuid"},"buyer_org_name":{"type":"string"},"state":{"type":"string","enum":["requested","approved","declined","revoked"]},"message":{"type":"string"},"requested_by":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"decided_at":{"type":["string","null"],"format":"date-time"},"buyer_missing":{"type":"array","items":{"type":"string"}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/marketplace/listings/{listing_id}/data-room/access/{access_id}":{"put":{"operationId":"decideMarketplaceListingDataRoomAccess","summary":"Approve, decline or revoke a buyer's data-room access (seller).","description":"approve from requested/declined, decline from requested, revoke from approved (409 `decisionNotAllowed` otherwise). Audited as `marketplace.data_room.access_decided`.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"access_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["decision"],"properties":{"decision":{"type":"string","enum":["approve","decline","revoke"]}}}}}},"responses":{"200":{"description":"The request as it now stands.","content":{"application/json":{"schema":{"type":"object","required":["id","state"],"properties":{"id":{"type":"string","format":"uuid"},"state":{"type":"string","enum":["requested","approved","declined","revoked"]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/marketplace/listings/{listing_id}/data-room/downloads":{"get":{"operationId":"listMarketplaceListingDataRoomDownloads","summary":"Who downloaded what from your listing's data room (seller).","description":"s1014 L69 (docs/1068 §7, Q12). Your own listing only. `watermark` is the exact text stamped on that copy, so a leaked copy names the row that made it.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Every download, newest first, with the exact watermark stamped.","content":{"application/json":{"schema":{"type":"object","required":["downloads"],"properties":{"downloads":{"type":"array","items":{"type":"object","required":["document_id","document_title","buyer_org_id","user_name","watermark","at"],"properties":{"document_id":{"type":["string","null"],"format":"uuid","description":"null once the seller removed the document; the download record is kept."},"document_title":{"type":"string"},"buyer_org_id":{"type":"string","format":"uuid"},"user_name":{"type":"string"},"watermark":{"type":"string"},"at":{"type":"string","format":"date-time"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/marketplace/listings/{listing_id}/offers":{"get":{"operationId":"listMarketplaceListingOffers","summary":"Your organisation's offers on a listing, and whether you may make one (buyer).","description":"s1014 L69 (docs/1068 §8, Q13). A live listing. `available` is false while the deal-room switch is off or the seller does not ask for an NDA; `nda_signed` says whether your organisation signed it (an offer needs it). Amounts are integer minor units of `currency`.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The negotiation as it stands.","content":{"application/json":{"schema":{"type":"object","required":["available","nda_signed","currency","asking_minor","default_valid_days","max_valid_days","offers","deal_desk"],"properties":{"available":{"type":"boolean"},"nda_signed":{"type":"boolean"},"currency":{"type":"string"},"asking_minor":{"type":"integer"},"default_valid_days":{"type":"integer"},"max_valid_days":{"type":"integer"},"offers":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceDealOffer"}},"deal_desk":{"$ref":"#/components/schemas/MarketplaceDealDeskNotice"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"makeMarketplaceListingOffer","summary":"Make an offer on a business listing (buyer).","description":"Needs the listing's NDA signed by your organisation (403 `ndaRequired`). One open offer per organisation per listing (409 `offerAlreadyOpen`). `amount_minor` is a positive integer in the listing's currency — a float is refused. `valid_days` 1-30, default 7; an expiry timer marks the offer expired when it lapses. Audited as `marketplace.offer.made`. No money moves.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount_minor"],"properties":{"amount_minor":{"type":"integer","minimum":1},"terms":{"type":"string","maxLength":4000},"valid_days":{"type":"integer","minimum":1,"maximum":30},"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"201":{"description":"The offer.","content":{"application/json":{"schema":{"type":"object","required":["offer"],"properties":{"offer":{"$ref":"#/components/schemas/MarketplaceDealOffer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/marketplace/listings/{listing_id}/offers/received":{"get":{"operationId":"listMarketplaceListingOffersReceived","summary":"Every negotiation on your listing (seller).","description":"s1014 L69 (docs/1068 §8). Your own listing only; each offer carries the buyer organisation's name. Empty while the deal-room switch is off.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The offers.","content":{"application/json":{"schema":{"type":"object","required":["available","offers","deal_desk"],"properties":{"available":{"type":"boolean"},"offers":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceDealOffer"}},"deal_desk":{"$ref":"#/components/schemas/MarketplaceDealDeskNotice"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/marketplace/listings/{listing_id}/offers/{offer_id}/actions":{"post":{"operationId":"actOnMarketplaceListingOffer","summary":"Counter, accept, decline or withdraw an open offer (buyer or seller).","description":"The side that did not make the offer counters (`amount_minor`, optional `terms`, `valid_days`), accepts or declines it; the side that made it may withdraw it (409 `actionNotAllowed` otherwise). A countered offer closes and the counter becomes the open offer. A lapsed offer refuses 409 `offerExpired`; an answered one 409 `offerClosed`. Accepting records an agreed price and makes the letter of intent available — no money moves. Audited as `marketplace.offer.<action>`.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"offer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["counter","accept","decline","withdraw"]},"amount_minor":{"type":"integer","minimum":1},"terms":{"type":"string","maxLength":4000},"valid_days":{"type":"integer","minimum":1,"maximum":30},"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"The new counter-offer, or the answered offer.","content":{"application/json":{"schema":{"type":"object","required":["offer"],"properties":{"offer":{"$ref":"#/components/schemas/MarketplaceDealOffer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/marketplace/listings/{listing_id}/offers/{offer_id}/loi":{"get":{"operationId":"getMarketplaceListingOfferLoi","summary":"The letter of intent of an accepted offer, as a PDF (buyer or seller).","description":"Rendered from the accepted offer in the reader's language (`locale` or Accept-Language), or wholly in English while any paragraph is untranslated. Non-binding except the NDA. 409 `loiNotAvailable` before acceptance. Audited as `marketplace.offer.loi_downloaded`.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"offer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"locale","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The PDF.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/marketplace/listings/{listing_id}/traffic-verification":{"get":{"operationId":"getMarketplaceListingTrafficVerification","summary":"The GA4 verified-traffic connection on your listing.","description":"Q287 (s1006, owner D41), docs/83 §1f. `not_connected`, `awaiting_property` (Google said yes, pick the property), `active` (figures on the listing) or `needs_reconnect` (Google no longer accepts the grant). Never the token: it lives in Vault.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The connection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceTrafficVerification"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"operationId":"chooseMarketplaceListingTrafficProperty","summary":"Pick the GA4 property that measures this listing's site, and read its traffic.","description":"Accepted only when one of the property's web streams measures the listing's own host (`www.` aside) — otherwise `422 hostMismatch`. Reads sessions and total users for the last 30 and 90 whole days (ending yesterday) and shows them on the public listing as GA4 verified traffic. Bounded: two Google calls plus one report.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["property_id"],"properties":{"property_id":{"type":"string","example":"properties/123456789"}}}}}},"responses":{"200":{"description":"The connection, now active, with its figures.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceTrafficVerification"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"disconnectMarketplaceListingTraffic","summary":"Disconnect Google Analytics from your listing.","description":"Forgets the stored token (Vault) and deletes the figures, and takes the badge off the public listing. It does NOT revoke at Google, because Google's revoke withdraws the whole account's grant to Zinn®'s one Google app (every other listing, Zinn® SEO site and report sink connected with that account would stop). Remove Zinn®'s access at Google, if wanted, at myaccount.google.com/permissions.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Disconnected."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/marketplace/listings/{listing_id}/traffic-verification/connect":{"post":{"operationId":"startMarketplaceListingTrafficConnect","summary":"Start connecting Google Analytics (GA4) to your listing.","description":"Returns Google's consent URL (scope `analytics.readonly`, offline access) with a signed state naming the listing, your organisation and you; it expires in ten minutes. The listing must be for a site (it has a domain to match). ⚠️ Google allows 100 users of an unverified app's sensitive scope until its consent screen is verified (docs/83 §1f).","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Where to send the browser.","content":{"application/json":{"schema":{"type":"object","required":["authorize_url"],"properties":{"authorize_url":{"type":"string","format":"uri"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/marketplace/listings/{listing_id}/traffic-verification/properties":{"get":{"operationId":"listMarketplaceListingTrafficProperties","summary":"The GA4 properties the connected Google account can read.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Every property the account can see (every Admin API page is read).","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","name","account"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"account":{"type":"string"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/marketplace/ga4/oauth/callback":{"get":{"operationId":"completeMarketplaceTrafficConnect","summary":"Where Google returns the seller after they authorize GA4 access.","description":"⛔ **Not called by a client** — Google redirects the seller's browser here, so it is unauthenticated by necessity and all of its authority comes from the signed `state` minted by `startMarketplaceListingTrafficConnect`. Always a 302 back to the dashboard (`/sell?listing=<id>&ga4=connected|cancelled|failed|scope`).","tags":["marketplace"],"security":[],"parameters":[{"name":"code","in":"query","required":false,"description":"Google's authorization code.","schema":{"type":"string"}},{"name":"state","in":"query","required":false,"description":"The signed state.","schema":{"type":"string"}},{"name":"error","in":"query","required":false,"description":"Present when the seller declined.","schema":{"type":"string"}}],"responses":{"302":{"description":"Redirect back to the dashboard with the outcome.","headers":{"Location":{"description":"The dashboard URL, carrying the outcome.","schema":{"type":"string"}}}}}}},"/v1/marketplace/listings/{listing_id}/packages":{"get":{"operationId":"listMarketplaceListingPackages","summary":"What a buyer can actually buy on this Zinn®.","description":"⭐ There is no listing without a package. A single-price Zinn® is a one-package Zinn®, which deletes the \"is the price on the listing or on the package\" fork entirely.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The packages, in position order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplacePackageList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"operationId":"putMarketplaceListingPackages","summary":"Replace the whole package list.","description":"Whole-list, like the field schema and for the same reason: per-package create/delete reopens the read-then-write race defect **D824** recorded, and position ordering only means anything as a set.\n\nThe cap is `Marketplace.max_packages` — a ROW an operator can change, not a database constraint that would need a migration (CLAUDE.md §2.35).","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplacePackagesUpdate"}}}},"responses":{"200":{"description":"The stored packages.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplacePackageList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"No packages, too many, a missing name, or a price that is not whole minor units.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/marketplace/listings/{listing_id}/reveal":{"get":{"operationId":"revealMarketplaceListing","summary":"The identifying value behind the mask (authenticated).","description":"docs/83 §3. The masking rule is \"not signed in\", and a crawler is never signed in — so this is a SEPARATE authenticated endpoint rather than a richer variant of the public page. A user-agent branch would be cloaking, and the penalty lands on the whole storefront.\n\n⚠️ Today the gate is \"signed in\". M4 tightens it to \"has bought\" when orders exist; that is the honest state rather than the final one.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The revealed value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceReveal"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"`refusal.marketplaceDealRoom.ndaRequired` — the seller hides the name and URL until your organisation signs this listing's NDA (s1014 L69, docs/1068 §6).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/marketplace/listing-types/{key}/schema":{"get":{"operationId":"getPublicListingTypeSchema","summary":"The public field schema for a kind of Zinn®.","description":"⭐ This is what makes \"add a field, no deploy\" true on the client side: the vendor form and the public renderer are generated from this response rather than compiled against a copy, so a bundle pinned to an older build still renders the fields the running engine has.\n\n⛔ Public fields only. A private field's label is harmless on its own, but its presence tells a scraper exactly which listings to ask about, and this endpoint is anonymous.","tags":["marketplace"],"parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"}},{"name":"locale","in":"query","required":false,"description":"Render every operator-authored string — field labels, help text, enum option labels — in this locale, falling back to the source language per string.\n\n⛔ A query parameter rather than `Accept-Language`, deliberately. A response that varies on a request header needs `Vary: Accept-Language`, at which point the edge caches one entry per header value and a crawler can be served a different page from a visitor — which is cloaking, and docs/83 §3 forbids it. The storefront already knows the locale: it is the first segment of every public URL.\n\nAn unknown locale falls back to the platform default rather than 4xx-ing: a stale link is a visitor, not an error.","schema":{"type":"string"}}],"responses":{"200":{"description":"The published public schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplacePublicSchema"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/marketplace/purchases":{"get":{"operationId":"listMarketplacePurchases","summary":"Everything this org has bought on the marketplace.","description":"The buyer's side of a sale. A `Sale` is a genuinely two-party record — one row, two audiences — so this and `listMarketplaceVendorSales` read the same table and return deliberately different payloads. Mirroring the money into a second table is how two copies of one balance come to disagree.\n\nDeclared before `/v1/marketplace/{vertical}/{slug}` in the router: that route is two free segments and would otherwise swallow the vendor routes below.","tags":["marketplace"],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"Purchases, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplacePurchaseList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/marketplace/purchases/{sale_id}/accept":{"post":{"operationId":"acceptMarketplacePurchase","summary":"Accept delivery — the act that releases the seller's money.","description":"docs/82 §3. The buyer's **explicit act**, and it is FINAL: it ends the refund window and releases the vendor's payout. The warning belongs on the client, before the button is pressed — an endpoint cannot warn anybody.\n\nAnswers **200** on a replay as well as on the first call. The buyer's click and the auto-accept timer genuinely race, so acceptance converges rather than raising: a retried request from a client that already succeeded is not an error to that client, and the payable is released exactly once regardless.\n\nScoped to the BUYER's org. A seller reaching for their own sale here gets a 404 — acceptance is the buyer's act alone, and a vendor who could press it would be paying themselves.","tags":["marketplace"],"parameters":[{"name":"sale_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The accepted purchase.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplacePurchase"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"This purchase is in a state that cannot be accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/marketplace/purchases/{sale_id}/revision":{"post":{"operationId":"requestMarketplaceRevision","summary":"Send the delivery back, and say what is wrong.","description":"docs/82 §3. Not accepting is a **first-class path**, not an error state, and it **pauses the acceptance clock** — so a seller cannot run the timer out by stalling, and a buyer who did engage is never auto-accepted for a delivery they rejected.\n\nThe reason is required and becomes part of the order record, visible to the seller: a rejection they cannot read is an instruction to change something unnamed, which produces a second rejection.\n\nBounded by the package's `revisions_included`, which is a term the buyer paid for rather than an unlimited entitlement — exceeding it points at a dispute, which has staff in it. A package promising **zero** revisions still allows the first request, because the alternative to it is a chargeback.","tags":["marketplace"],"parameters":[{"name":"sale_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceRevisionRequest"}}}},"responses":{"200":{"description":"The paused purchase.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplacePurchase"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"No reason given, nothing delivered to revise, or revisions exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/marketplace/orders/{sale_id}":{"get":{"operationId":"getMarketplaceOrder","summary":"The order workspace — one order, from your side of it.","description":"docs/147 §3. The screen where the work actually happens, for whichever party is asking. Before this there was a buyer's list and a seller's money screen, and nowhere the work happened.\n\nThe payload leads with `turn` and `waiting_on` because the screen does. The anti-jumble device is one question at the top — **whose turn is it, and what is it waiting for** — and it is computed in the engine so every client answers it identically rather than each deriving it from six columns.\n\n`paused` is the revision clock, made visible. Requesting a revision pauses the acceptance window by clearing its deadline, which is correct and completely unrenderable: a null deadline looks identical to a sale that never had one.\n\nThe commission split is present for the SELLER and null for the buyer. To a buyer the price is the price.","tags":["marketplace"],"parameters":[{"name":"sale_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/ReaderLocale"}],"responses":{"200":{"description":"The order, from the caller's side.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceOrderWorkspace"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/marketplace/orders/{sale_id}/dispute":{"get":{"operationId":"getMarketplaceOrderDispute","summary":"The dispute on an order, and whether the buyer may raise one.","description":"W43-74 (D25235). Either party reads it — the seller must see the buyer's reason to answer it in the order chat. `can_raise` uses the same rule the POST enforces: an order is disputable once delivered, while a revision is requested, once its delivery date has passed, or when an asset-transfer handover item is flagged. Staff identities are never included.","tags":["marketplace"],"parameters":[{"name":"sale_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The order's dispute state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceOrderDispute"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"raiseMarketplaceOrderDispute","summary":"The buyer disputes an order — stops the acceptance clock and holds the payout.","description":"Buyer only (a seller receives 404). A reason is required. The sale moves to `disputed`, the auto-accept deadline is cleared, no path can release the seller's payable until staff decide, and the seller, the buyer and marketplace staff are notified.","tags":["marketplace"],"parameters":[{"name":"sale_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","maxLength":2000}}}}}},"responses":{"200":{"description":"The order's dispute state after raising.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceOrderDispute"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/marketplace/orders/{sale_id}/requirements":{"post":{"operationId":"submitMarketplaceOrderRequirements","summary":"The buyer's brief — and the thing that starts the delivery clock.","description":"docs/147 §2. A paid order used to arrive carrying a package name and nothing else: the seller could not start, the clock was running, and there was no channel to ask.\n\n**Submitting is what starts the delivery clock.** Until this call the seller's deadline does not exist, so the days a buyer spends writing their brief are never billed against the seller's deadline and a seller is never late for work they could not begin.\n\nThe questions come from the order's own frozen `requirements_schema` — a snapshot taken at purchase, so a seller who rewrites their questions tomorrow cannot change what this buyer was asked.\n\nBuyer only. A seller gets a 404, the same way acceptance is the buyer's act alone.","tags":["marketplace"],"parameters":[{"name":"sale_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceRequirementsSubmission"}}}},"responses":{"200":{"description":"The order, with its clock now running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceOrderWorkspace"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"A required answer is missing, or the brief was already submitted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/marketplace/orders/{sale_id}/messages":{"get":{"operationId":"listMarketplaceOrderMessages","summary":"The order chat.","description":"docs/82 §4. A per-order conversation between buyer and seller, and staff on a dispute. Messages are part of the order record and are evidence in a dispute.\n\nA held message is excluded from **both** parties, not just the recipient: showing a sender their own held message as if it had been delivered is how someone concludes they are being ignored and leaves for email — the outcome the whole feature exists to avoid.\n\nReading clears the caller's unread count.","tags":["marketplace"],"parameters":[{"name":"sale_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/ReaderLocale"},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"The conversation, oldest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceMessageList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"sendMarketplaceOrderMessage","summary":"Send a message on an order.","description":"docs/133 D26. The on-platform contact policy applies and is **proportionate**: a message may be sent as written, sent and flagged quietly, sent with contact details masked, or held for review. There is no rung that refuses to send — a hard block is what generates the false positives honest sellers leave over, and they do not complain first.\n\nAfter an order exists, exchanging details is often the work itself — a guest post needs the target URL and the anchor, an asset transfer needs the registrar and the DNS — so the policy leans far less here than on a pre-sales enquiry, and least of all on an asset transfer.\n\n`held` is reported to the sender. It is the one case where \"sent\" would be a lie.","tags":["marketplace"],"parameters":[{"name":"sale_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceMessageCreate"}}}},"responses":{"201":{"description":"The message as it landed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceMessage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Empty, too long, too many files, or a file on a pre-sales thread.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/marketplace/orders/{sale_id}/messages/preview":{"post":{"operationId":"previewMarketplaceOrderMessage","summary":"Assess a draft before it is sent — the inline nudge.","description":"docs/133 D26, the top rung of the ladder and the one that does most of the work: most circumvention is naive, and telling someone once, before they send, that the platform holds the money and the guarantee stops most of it.\n\nWrites nothing and counts nothing, so it is safe to call on blur. Storing a policy event for a draft somebody then edits would also poison the false-positive rate with messages that were never sent.\n\n`nudge` is a message KEY, not a sentence — it is rendered in every locale by the client.","tags":["marketplace"],"parameters":[{"name":"sale_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceMessageCreate"}}}},"responses":{"200":{"description":"What the policy would do with this draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceContactDecision"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/marketplace/orders/{sale_id}/zinn-asset":{"post":{"operationId":"moveMarketplaceOrderZinnAsset","summary":"Move the sold site or domain into the buyer's account again, after a refusal.","description":"docs/714 §3. The move runs by itself when the sale is created; this runs it again once whatever it named has been fixed. Either party may call it; it only ever moves the asset towards the buyer. A refusal is a `200` with `outcome: refused` and the reason — the reason is also written onto the order's checklist row, and an error status would roll that record back.","tags":["marketplace"],"parameters":[{"name":"sale_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"What happened.","content":{"application/json":{"schema":{"type":"object","required":["outcome","message"],"properties":{"outcome":{"type":"string","enum":["moved","already_moved","refused","failed"]},"message":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The order was refunded or cancelled, so the site or domain stays with the seller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/marketplace/orders/{sale_id}/handover/{item_id}":{"post":{"operationId":"updateMarketplaceHandoverItem","summary":"Tick one handover item — from your side of the order.","description":"docs/83 §4.4. Each item carries **two** confirmations: the seller marks it transferred, and the buyer marks it received. Funds release only when every required item is buyer-confirmed — a seller-only tick is not delivery.\n\nWhich action a caller may take is decided server-side by which side of the order they are on. A seller marking an item received on the buyer's behalf would be a seller releasing their own money.\n\nA buyer can flag a single item as missing or wrong **without rejecting the whole sale**; that flag is what opens a dispute, with the checklist and the order chat as evidence.\n\n`order_accepted` is true when this tick was the last required one and the money has been released.","tags":["marketplace"],"parameters":[{"name":"sale_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceHandoverAction"}}}},"responses":{"200":{"description":"The item, and where the checklist now stands.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceHandoverResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Not an action that can be taken on this item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/marketplace/conversations":{"get":{"operationId":"listMarketplaceConversations","summary":"Every thread this org is in, on either side.","description":"docs/133 D26. Pre-sales, direct and order chat are one system, so they are one list. `is_buyer` says which side of each thread the caller is on, and `unread` is that side's count.","tags":["marketplace"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"The organization whose threads to list, and whose side `is_buyer` describes. Omitted, every organization you belong to is listed. Naming one you do not belong to is 403.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"Threads, most recently active first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceConversationList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/marketplace/conversations/{conversation_id}/messages":{"get":{"operationId":"listMarketplaceConversationMessages","summary":"One thread's messages, for whichever side of it you are on.","description":"docs/147 §5. The door both parties share — above all the SELLER's way to read a pre-sales question, which the buyer-keyed enquiry route cannot serve. Reading clears your side's unread count. Held messages are hidden from both parties.","tags":["marketplace"],"parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"description":"Which of your organizations is reading. Naming one you do not belong to is 403.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/ReaderLocale"},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"The thread, oldest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceMessageList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"sendMarketplaceConversationMessage","summary":"Reply in a thread, as whichever side of it you are on.","description":"docs/147 §5. The same contact policy as every other marketplace message; on a pre-sales thread attachments are refused.","tags":["marketplace"],"parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"description":"Which of your organizations is replying. Naming one you do not belong to is 403.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceMessageCreate"}}}},"responses":{"201":{"description":"The message as it landed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceMessage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Empty, too long, or a file on a pre-sales thread.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/marketplace/listings/{listing_id}/enquiries":{"get":{"operationId":"listMarketplaceListingEnquiries","summary":"The pre-sales conversation about one listing.","description":"docs/133 D26. The highest-risk surface on the platform, because nothing is paid and there is therefore nothing to lose by taking the conversation elsewhere. The contact policy leans hardest here.\n\nKeyed on the listing and the enquirer, not on the seller: a buyer asking about two of a seller's listings is having two conversations, and merging them produces a thread where neither party can tell which asset a question was about.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"description":"Which of your organizations the enquiry is from. Optional when you belong to exactly one; **required (422) when you belong to more than one**, because the platform will not guess. Naming an organization you do not belong to is 403.\n\nA reseller scoped to a parent organization and its clients has to say which one is asking: the thread is keyed on (listing, organization), so a guess would file the enquiry where the buyer will never look for the reply.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/ReaderLocale"},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"The enquiry thread, oldest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceMessageList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"sendMarketplaceListingEnquiry","summary":"Ask a seller a question before buying.","description":"docs/133 D26. **Attachments are refused here entirely**: an attachment bypasses text scanning, we have no OCR, and on the one surface where nobody has paid there are therefore no files. Saying so is honest; scanning an image we cannot read would not be.","tags":["marketplace"],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"description":"Which of your organizations the enquiry is from. Optional when you belong to exactly one; **required (422) when you belong to more than one**, because the platform will not guess. Naming an organization you do not belong to is 403.\n\nA reseller scoped to a parent organization and its clients has to say which one is asking: the thread is keyed on (listing, organization), so a guess would file the enquiry where the buyer will never look for the reply.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceMessageCreate"}}}},"responses":{"201":{"description":"The message as it landed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceMessage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Empty, too long, your own listing, or a file on a pre-sales thread.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/marketplace/vendor/sales/{sale_id}/deliver":{"post":{"operationId":"deliverMarketplaceSale","summary":"Mark the work delivered — starts the buyer's acceptance window.","description":"Delivery is the **seller's claim**, never the end of the sale, and it moves no money: it starts the buyer's acceptance window and nothing else.\n\nRedelivery after a revision **restarts** the clock, measured from the redelivery rather than from the original — the buyer's window is a window on the delivery in front of them. Without that, a seller redelivering on day four of a five-day window would hand the buyer one day to check a whole revision.\n\nScoped to the SELLER's org. A buyer marking their own purchase delivered would be starting the clock that releases the seller's money before anything was sent.","tags":["marketplace"],"parameters":[{"name":"sale_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The delivered sale, with its new acceptance deadline.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceVendorSale"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"This sale is in a state that cannot be delivered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/marketplace/purchases/{sale_id}":{"get":{"operationId":"getMarketplacePurchase","summary":"One purchase, as the buyer sees it.","description":"Scoped to the BUYER's org. A seller asking for their own sale through this route gets a 404 — the two views of a sale are different payloads, not one payload with a permission check.","tags":["marketplace"],"parameters":[{"name":"sale_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The purchase.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplacePurchase"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/marketplace/vendor/sales":{"get":{"operationId":"listMarketplaceVendorSales","summary":"Everything this org has sold on the marketplace.","description":"The seller's side, including the commission split — it is their deal. Filtered on the sale's `vendor_org_id`: the plain `org_id` on a sale is the BUYER's, so filtering on it would return this org's purchases labelled as its sales, with a split attached and no error anywhere.","tags":["marketplace"],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"Sales, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceVendorSaleList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/marketplace/vendor/ledger":{"get":{"operationId":"getMarketplaceVendorLedger","summary":"What the seller is owed, and what is still being held.","description":"\"Funds are held securely by Zinn® until the buyer accepts delivery\" (docs/82 §1) is a promise to two people, and the seller is the one who needs to watch it — a balance they cannot see is indistinguishable from not being paid.\n\nThe three balance figures are computed over every entry by the database, not summed from `data`. They are kept separate rather than netted because they answer different questions: `pending` is what no buyer has accepted yet, `released` is what the next weekly payout run will pay, `paid` is history.","tags":["marketplace"],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"The balance and its entries, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceLedger"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/marketplace/vendor/payouts":{"get":{"operationId":"listMarketplaceVendorPayouts","summary":"What has been paid out, and what is being held.","description":"⭐ This is what makes a HELD payout something a seller can act on rather than money that silently did not arrive. docs/82 §7a is explicit that an unverified vendor is told exactly why and what to do, and a hold with no surface is the same as no hold at all from where they are standing — they simply were not paid.\n\n`hold_reason` is a NAMED code rather than prose, so a console can render an instruction per reason: \"finish your verification\" is a different action from \"your balance is below this rail's minimum and is rolling over to next week\".\n\n`external_ref` is empty for account credit, which never leaves the platform — a real distinction rather than a missing value.","tags":["marketplace"],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"Payouts, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplacePayoutList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/marketplace/vendor/payouts/{payout_id}/statement":{"get":{"operationId":"getMarketplaceVendorPayoutStatement","summary":"One paid payout's statement — also the self-billed invoice.","description":"docs/78 §11.4 + §13.2. Every paid payout has a statement listing each sale (gross, commission, net), the at-cost provider fee, what reached the seller, the method and the provider's reference. Under self-billing it doubles as the seller's invoice to us, numbered from the gapless `SBI` series. ⛔ A payout that is not paid has no statement (404), and another seller's payout is a 404, never a 403.","tags":["marketplace"],"parameters":[{"name":"payout_id","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The statement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplacePayoutStatement"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/marketplace/vendor/payout-schedule":{"get":{"operationId":"getMarketplaceVendorPayoutSchedule","summary":"When the next payout run is, the minimum, and the instant tier.","description":"Payouts run automatically on Fridays at 10:00 UTC with a US$50 minimum (owner ruling 2026-10-25). A seller in the instant tier — 20+ completed orders and no refund, dispute or chargeback in the last 90 days — is paid when each sale completes. Evaluated live.","tags":["marketplace"],"responses":{"200":{"description":"The schedule.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplacePayoutSchedule"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/marketplace/vendor/profile":{"get":{"operationId":"getMarketplaceVendorProfile","summary":"Whether this account sells on the marketplace, and where its file is.","description":"The one call a dashboard makes to decide what to render. `registered: false` is a normal answer, not an error — most customers are not sellers.\n\n⛔ D51530: when `X-Zinn-Org` (or `org_id`) names an organisation, the answer is for THAT organisation only — `registered: false` if it has no seller row, never another org's row. A named organisation outside the caller's scope is `403`.","tags":["marketplace"],"parameters":[{"$ref":"#/components/parameters/ActiveOrg"}],"responses":{"200":{"description":"The seller profile, or a plain `registered: false`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceVendorProfile"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"operationId":"registerMarketplaceVendor","summary":"Become a Zinner®.","description":"docs/82 §7a. Self-service registration — until M1 a vendor row could only be created by staff in admin, which is a marketplace whose seller half is reachable only by asking us.\n\n⭐ **Idempotent.** An org that is already registered gets `200` and its existing row, never a `409`: two members of one org pressing the button is an ordinary event.\n\n⛔⛔ **The organisation registered is the one the request targets** (D51530): body `org_id`, else `X-Zinn-Org`, validated against the caller's scope — a named organisation the caller cannot act in is `403 ORG_OUT_OF_SCOPE`, never re-routed. With none named it is the API key's org, else the caller's one direct membership, else the one org in scope; anything else is `422 ORG_REQUIRED` rather than a guess (it used to take the first org by sorted id). ⛔ The row is always created `registered` and never first-party: registering is not approval, and approval is not verification.","tags":["marketplace"],"parameters":[{"$ref":"#/components/parameters/ActiveOrg"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceVendorRegistration"}}}},"responses":{"200":{"description":"Already registered; this is the existing seller profile.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceVendorProfile"}}}},"201":{"description":"Registered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceVendorProfile"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/marketplace/vendor/payout-methods":{"get":{"operationId":"listMarketplaceVendorPayoutMethods","summary":"Where this seller can be paid, and the rails they may choose (PayPal, bank, crypto).","description":"docs/82 §7c. ⛔ The destination is **masked** — enough for the seller to recognise which of their accounts it is, never enough to reproduce it. A wallet address on a screen is a wallet address in a screenshot.\n\nThe `rails` block carries each rail's **minimum and fee note**, because docs/82 §7 requires the seller to see them *where they choose the rail*: \"the rail they pick changes what they actually receive\", and a fee discovered on the statement is a support ticket.","tags":["marketplace"],"responses":{"200":{"description":"The seller's destinations and the rails on offer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplacePayoutMethodList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"addMarketplaceVendorPayoutMethod","summary":"Propose a destination to be paid at.","description":"docs/82 §7c. The row is created **unverified** and can receive nothing: only staff verification makes it payable, and then only after the 48-hour cooling-off.\n\n⛔⛔ **A change of destination is a new row, never an edit** — there is deliberately no endpoint that changes `destination` on an existing one. §7c: *\"Change of payout details is the account-takeover cash-out route, and must be treated as one.\"* Editing a verified row would keep its verified state and its long-expired hold while pointing the money somewhere nobody looked at.\n\n⭐ Re-adding a destination the seller already has returns the existing row rather than minting a second one — otherwise \"change it and change it back\" resets the cooling-off clock in two requests.\n\n⛔ The **network** is its own field, not part of the address. Sending USDT TRC20 to a BEP20 address loses the money irrecoverably, so the same address on two networks is two destinations, each earning its own proof and its own hold.","tags":["marketplace"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplacePayoutMethodCreate"}}}},"responses":{"201":{"description":"The destination, awaiting proof.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplacePayoutMethod"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"`STEP_UP_REQUIRED` — setting or changing the CRYPTO payout e-mail needs a sign-in from the last 5 minutes (the token's `auth_time`; owner ruling 2026-10-25). Re-authenticate with `prompt=login&max_age=0` and retry. API keys and impersonation sessions cannot step up.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/marketplace/vendor/payout-methods/confirm":{"post":{"operationId":"confirmMarketplaceVendorPayoutMethod","summary":"Confirm a PayPal or crypto payout e-mail from the link we sent to it.","description":"The seller page calls this with the `payout_confirm` token from the e-mailed link. Verifies the destination and starts its cooling-off (48 hours; 72 for crypto). Scoped to the signed-in seller — a forwarded link confirms nothing on another account. The link expires after 48 hours (`LINK_EXPIRED`).","tags":["marketplace"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","maxLength":200}}}}}},"responses":{"200":{"description":"The destination, now verified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplacePayoutMethod"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/marketplace/vendor/payout-methods/bank-onboarding":{"post":{"operationId":"startMarketplaceVendorBankOnboarding","summary":"Start (or resume) bank payouts set-up with Stripe.","description":"Bank payouts are Stripe Connect Express, payouts only (owner, 2026-10-25, mirrored from Zinn Hub®): the seller completes Stripe's hosted onboarding once, and we transfer to that account on payout day. Returns the Stripe-hosted URL to send the seller to. Countries: US, UK, EEA, Canada, Switzerland (`BANK_COUNTRY_UNSUPPORTED` otherwise). The destination becomes `verified` only when Stripe reports transfers active and payouts enabled — read on `listMarketplaceVendorPayoutMethods`.","tags":["marketplace"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["country"],"properties":{"country":{"type":"string","minLength":2,"maxLength":2,"example":"GB"}}}}}},"responses":{"200":{"description":"Where to send the seller, and the destination row.","content":{"application/json":{"schema":{"type":"object","required":["url","method"],"properties":{"url":{"type":"string","format":"uri"},"method":{"$ref":"#/components/schemas/MarketplacePayoutMethod"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/marketplace/vendor/payout-methods/{method_id}/send-link":{"post":{"operationId":"resendMarketplaceVendorPayoutLink","summary":"E-mail the confirmation link for a PayPal or crypto destination again.","tags":["marketplace"],"parameters":[{"name":"method_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The destination, still awaiting its link.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplacePayoutMethod"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/marketplace/vendor/payout-methods/{method_id}":{"post":{"operationId":"proveMarketplaceVendorPayoutMethod","summary":"Show that the destination belongs to you.","description":"docs/82 §7c's proof table, as data. Since 2026-10-25 the methods are PayPal, bank (Stripe) and crypto (NOWPayments): PayPal and crypto are proved by the e-mailed link (`confirmMarketplaceVendorPayoutMethod`) and bank by Stripe's onboarding, so this endpoint now only serves a PayPal destination already in the staff queue under the older `account_email` proof; anything else is refused (`PROOF_IS_AUTOMATIC`).","tags":["marketplace"],"parameters":[{"name":"method_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplacePayoutMethodProof"}}}},"responses":{"200":{"description":"The destination, now awaiting review.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplacePayoutMethod"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"retireMarketplaceVendorPayoutMethod","summary":"Stop using a destination.","description":"Retires the row; it is never deleted. A payout that went there is explained by it, and *\"where did we send March's money\"* must stay answerable after the seller changes bank.","tags":["marketplace"],"parameters":[{"name":"method_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Retired."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/marketplace/vendor/payout-readiness":{"get":{"operationId":"getMarketplaceVendorPayoutReadiness","summary":"Whether money may leave the platform to this seller, and why not.","description":"docs/82 §7a: *\"the vendor is told exactly why and what to do.\"*\n\n⭐ The same computation the payout runner performs, rendered for the seller. One producer, two audiences — a screen that re-derived the reasons would drift from the gate, and the drift would show as a seller told they are ready while the runner refuses.\n\n⛔ Verification is optional until the first payout and then mandatory. An unverified seller may list, sell and be accepted; it is the **payout** that is held, never the sale.","tags":["marketplace"],"responses":{"200":{"description":"The verdict and every reason behind it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplacePayoutReadiness"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/marketplace/vendor/verification":{"get":{"operationId":"getMarketplaceVendorVerification","summary":"The seller's identity file and what it still needs.","description":"Seller verification is fully automatic. When you apply, you tell us the country you live in and the country of your payout bank, and we check names against the official UK, EU and US sanctions lists. If everything passes, you are approved straight away, with no manual review, and you can start selling. When your first payout is due, you verify your identity once with a photo of a government-issued ID and a selfie, through Stripe Identity. Your documents stay with Stripe; we keep only the result. If the ID check fails, we tell you why and you can try again yourself.\n\n⭐ That paragraph is `engine.marketplace.kyc_copy.PROCESS`, verbatim (KYCCOPY1115, `test_kyc_copy_parity.py`).\n\n⛔ The sanctions/PEP screening result is **not** in this payload. Telling someone they are a possible match is tipping-off; only the decision reaches the seller, through `state`.","tags":["marketplace"],"responses":{"200":{"description":"The file (or `null`) plus the machine-readable requirement set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceVerificationEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"operationId":"startMarketplaceVendorVerification","summary":"Open the identity file on a track, or edit it.","description":"docs/82 §7a. **Two tracks, chosen here: individual and company.** They are not the same shape with extra fields — the required documents differ, the number of natural persons differs (one, versus every beneficial owner over 25%), and the approval rule differs, because a company is not verified until every required owner is.\n\n⛔ `PUT`, not `POST`: there is exactly one file per seller and sending the form twice must not make two. ⛔ Refused once the file is in review or approved — the reviewer approves what they saw.","tags":["marketplace"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceVerificationStart"}}}},"responses":{"200":{"description":"The file as it now stands.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceVerificationEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/marketplace/vendor/verification/subjects":{"post":{"operationId":"addMarketplaceVerificationSubject","summary":"Add a natural person to the identity file.","description":"One person on the individual track. On the company track, the person authorised to act plus **each beneficial owner over 25%** — a holding below that threshold is refused rather than recorded, because a person on a file whose presence nobody can later explain is worse than an absent one.","tags":["marketplace"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceVerificationSubjectCreate"}}}},"responses":{"201":{"description":"The person, as recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceVerificationSubject"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/marketplace/vendor/verification/subjects/{subject_id}":{"patch":{"operationId":"updateMarketplaceVerificationSubject","summary":"Correct a person already on a file that is still editable.","description":"Sets the person's name parts and date of birth (DAC7, docs/298 §2a) without removing them, so documents already uploaded against the person are kept. Only the keys sent are changed. Refused once the file is in review or approved. ⛔ Exists because an individual seller saved without first name, last name and date of birth had no way to add them — one person per individual file, and no edit path — and the payout gate demanded all three.","tags":["marketplace"],"parameters":[{"name":"subject_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceVerificationSubjectUpdate"}}}},"responses":{"200":{"description":"The person, as now recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceVerificationSubject"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"removeMarketplaceVerificationSubject","summary":"Remove a person from a file that is still editable.","description":"Refused once the file is in review or approved — the reviewer decided on the set of people they saw, and removing one afterwards would leave an approval attached to a file that no longer describes the company.","tags":["marketplace"],"parameters":[{"name":"subject_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/marketplace/vendor/verification/subjects/{subject_id}/identity-check":{"post":{"operationId":"startMarketplaceVendorIdentityCheck","summary":"Start (or resume) this person's Stripe Identity check.","description":"The identity check is the payout gate (owner, 2026-11-13): a seller approved to sell verifies the identity of each person on the file once their first payout is due. Returns the provider's hosted page to send the seller to; `url` is null when the check is already with the provider and nothing is left for the seller to do. The return URL is built by the server, never taken from the request. Refusals (422, `details[].code`): `NOT_SUBMITTED` (no submitted or automatically approved file), `PAYOUT_NOT_DUE`, `NOT_IN_GOOD_STANDING`, `ALREADY_VERIFIED`; none of them opens a paid session. An open session is resumed, never paid for twice.","tags":["marketplace"],"parameters":[{"name":"subject_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Where to send the seller, and the check's state.","content":{"application/json":{"schema":{"type":"object","required":["url","state"],"properties":{"url":{"type":"string","format":"uri","nullable":true},"state":{"type":"string","enum":["created","requires_input","processing","verified","canceled"]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/marketplace/vendor/verification/documents":{"post":{"operationId":"createMarketplaceVerificationDocument","summary":"Reserve a document slot and get a short-lived upload URL.","description":"docs/82 §7a. **The bytes never pass through the engine.** The response carries a presigned `PUT` the browser uploads straight to object storage with; a 10 MB scan routed through an API worker is 10 MB of a request thread and a request that outlives its timeout on a poor connection.\n\n⛔ The stored object key is deliberately absent from the response — the seller needs the signed URL, never the address of an object in a bucket of identity documents.\n\n⛔ **We ask for \"a government-issued photo ID\"** — passport, national identity card, driving licence or residence permit — and there is no country list. A student, workplace or library card is not government-issued and is not accepted.","tags":["marketplace"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceDocumentUploadRequest"}}}},"responses":{"201":{"description":"The document row and the grant to upload its bytes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceDocumentUpload"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/marketplace/vendor/verification/documents/{document_id}/url":{"get":{"operationId":"getMarketplaceVerificationDocumentUrl","summary":"A short-lived URL that downloads one identity document.","description":"⛔⛔ **Every view is audit-logged**, including the seller's own view of their own passport. docs/82 §7a asks *\"who looked at this document\"*, and the honest answer includes the account holder — a support agent investigating an account takeover needs to know the documents were pulled, and from which session.\n\nThe URL carries its own signature and is therefore a credential for its lifetime. Never log it, never store it.","tags":["marketplace"],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The signed URL and when it expires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceDocumentUrl"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/marketplace/vendor/verification/submit":{"post":{"operationId":"submitMarketplaceVendorVerification","summary":"Send the seller file; the checks then run automatically, with no manual review.","description":"Completeness is checked **here**, so a seller finds out at once, and a refusal names every missing requirement together. There is no manual review and nothing to upload (owner order 1112#SELLERKYC): the file is decided automatically, by `engine.marketplace.auto_kyc`, once each person's Stripe Identity check at the first payout and the sanctions-list check have passed.\n\nSubmitting also requires the self-billing agreement: we buy from the seller net and self-bill, so the payout statement doubles as their invoice to us (docs/82 §8).","tags":["marketplace"],"responses":{"200":{"description":"Submitted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceVerificationEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/marketplace/verticals":{"get":{"operationId":"listPublicMarketplaceVerticals","summary":"The marketplace verticals a buyer can browse.","description":"⛔ **The storefront's front door, as data.** Both the per-vertical search and the listing endpoint take the vertical *from the URL*, so before this existed every caller had to already know one: a buyer landing anywhere but a deep link had no route in.\n\nAnonymous. A vertical is staff-authored platform configuration with no tenant scope — the same fields already returned in every search response's `marketplace` block. Archived verticals are omitted here while their URLs keep resolving (`docs/78` §4.5): hidden from the hub, never a broken link.\n\n`locale` returns each vertical's name and tagline in that language (per field, falling back to the source text), as `/v1/marketplace/overview` does — s1014 L32: the app's browse screen showed \"Shopify stores for sale\" in English to an Arabic buyer.","tags":["marketplace"],"security":[],"parameters":[{"name":"locale","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The live verticals, in display order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceVerticalPublicList"}}}}}}},"/v1/marketplace/{vertical}/search":{"get":{"operationId":"searchPublicMarketplace","summary":"Filter, sort and page one vertical's live Zinn®s.","description":"docs/83 §2 step 4. Anonymous, single-variant, and answered entirely from the derived publication projection — never from the org-scoped authoring tables.\n\n⛔ **The facet parameters are generic on purpose.** Fields are defined by staff in admin, so a typed parameter per filter would mean a spec change, an SDK regeneration and a deploy every time somebody added one — which is the exact property this milestone exists to remove. A filter is `facet=key:op:value`, repeated; values of the same key are OR-ed, different keys are AND-ed.\n\n⛔ **A numeric filter requires `type`.** The promoted slot behind `da` holds a different field for every listing type, so asking `da:gte:50` across a whole vertical would compare a domain authority against whatever the next kind of listing stores in the same column — wrong, plausible, and impossible to notice. It is refused with 422.\n\n⛔ **`declared`/`of` on every facet are not decoration.** A field added in schema v2 does not exist on v1 listings, so filtering on it silently excludes them and \"DA ≥ 50\" quietly becomes \"and authored after the day DA was added\". The two numbers are what let the page say \"482 of 1,930 Zinn®s declare DA\" instead of implying the other 1,448 failed the filter.\n\n⛔ `total` is probed to 10,000 and `total_is_capped` says so. An exact count of a large filtered set costs as much as returning it.","tags":["marketplace"],"parameters":[{"name":"vertical","in":"path","required":true,"schema":{"type":"string"}},{"name":"locale","in":"query","required":false,"description":"Render every operator-authored string — field labels, help text, enum option labels — in this locale, falling back to the source language per string.\n\n⛔ A query parameter rather than `Accept-Language`, deliberately. A response that varies on a request header needs `Vary: Accept-Language`, at which point the edge caches one entry per header value and a crawler can be served a different page from a visitor — which is cloaking, and docs/83 §3 forbids it. The storefront already knows the locale: it is the first segment of every public URL.\n\nAn unknown locale falls back to the platform default rather than 4xx-ing: a stale link is a visitor, not an error.","schema":{"type":"string"}},{"name":"type","in":"query","required":false,"description":"A listing type key. Defaults to the vertical's only live type when it has exactly one; required before any facet filter on a vertical that sells several types.","schema":{"type":"string"}},{"name":"category","in":"query","required":false,"description":"A category path. Matches that category AND everything beneath it.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"What the buyer typed. Truncated at 120 characters rather than refused — pasting an essay into a search box is not an attack.\n\n⭐ Answered by **hybrid retrieval** (docs/83 §2a, owner ruling D-W15-9): a Postgres full-text index, a trigram index and a pgvector nearest-neighbour search, merged by Reciprocal Rank Fusion. The response's `retrieval` field names the paths that actually ran.\n\n⭐ A **numeric range typed into this box** — `DR 40-50`, `DA 50+`, `price under $200`, `traffic 10k` — is read as a facet filter against the named `type`'s own (translated) field labels, and reported back in `interpreted` so the storefront can render it as a removable chip. The words left over are what is searched for, and they come back as `query`. An explicitly ticked `facet` always beats an inferred one.\n\n⛔ **A domain is not searchable and that is deliberate.** docs/83 §3 masks it to a constant for anyone not signed in, so indexing the real value would turn this anonymous endpoint into a machine for confirming guesses one at a time.","schema":{"type":"string"}},{"name":"facet","in":"query","required":false,"description":"`key:op:value`, repeatable. `op` is `gte`/`lte` for numbers and `eq` for choices and yes/no fields.","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true},{"name":"price_min","in":"query","required":false,"description":"s1006 (Q59). The lowest \"from\" price (`price_minor`, the cheapest package), in integer minor units of `currency` — `5000` is 50.00. Inclusive.","schema":{"type":"integer","minimum":0,"format":"int64"}},{"name":"price_max","in":"query","required":false,"description":"The highest \"from\" price, in integer minor units of `currency`. Inclusive. ⛔ A price bound with no `currency` is refused (`CURRENCY_REQUIRED`): comparing one listing's dollars with another's yen would answer wrongly and confidently. Only listings priced in `currency` match.","schema":{"type":"integer","minimum":0,"format":"int64"}},{"name":"currency","in":"query","required":false,"description":"ISO 4217 code the price band is in. Required with `price_min`/`price_max`.","schema":{"type":"string","minLength":3,"maxLength":3,"example":"USD"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["newest","price","-price","rating","sales"]}},{"name":"cursor","in":"query","required":false,"description":"Keyset page marker from a previous response. Never an offset.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":60}}],"responses":{"200":{"description":"The matching Zinn®s, the filter rail and the paging marker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceSearchResult"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"An unknown filter or sort, a malformed `key:op:value`, a range filter with no `type`, or a page marker this catalogue did not issue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/marketplace/{vertical}/categories":{"get":{"operationId":"listPublicMarketplaceCategories","summary":"A storefront's category tree, with live listing counts.","description":"Anonymous and single-variant (s1014 J08). Every category of this vertical that holds at least one live listing — its own or a descendant's — with its translated name, its `path` (pass it to `searchPublicMarketplace` as `category`), its depth and parent, and the live count. Read from the taxonomy and the storefront projection only; two queries whatever the tree's size.","tags":["marketplace"],"security":[],"parameters":[{"name":"vertical","in":"path","required":true,"schema":{"type":"string"}},{"name":"locale","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The category tree, parents before children.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplaceCategoryTree"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/marketplace/{vertical}/{slug}":{"get":{"operationId":"getPublicMarketplaceListing","summary":"One live Zinn®, as anyone sees it.","description":"Anonymous and SINGLE-VARIANT. No user-agent branch, no `Vary: Cookie`, no signed-in mode — docs/83 §3's rule is that Googlebot must see exactly what an anonymous visitor sees.\n\nA `domain` renders as `site****.com`; a `url` or `file` does not render at all. The full value is not in the tables this reads.\n\n⛔ An unknown field kind is SKIPPED, never degraded to text: a page served by a newer engine than the deployed bundle must not print `12000` for a money field whose truth is `$120.00`, because a visitor has no way to tell a wrong number from a right one.\n\n⛔ A listing whose stamped schema version has no history row is a **404**, not a render against the type's current head. Quietly showing different facts is worse than showing nothing.\n\nA listing that MOVED vertical (s1014 J40: the V1 import moved V1's guest posts from Link building to Guest posts) is still answered at its OLD address, with its new `marketplace_key`; a caller that sees a key other than the vertical it asked for should treat the old URL as permanently moved (the public site 301s).","tags":["marketplace"],"parameters":[{"name":"vertical","in":"path","required":true,"schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"locale","in":"query","required":false,"description":"Render every operator-authored string — field labels, help text, enum option labels — in this locale, falling back to the source language per string.\n\n⛔ A query parameter rather than `Accept-Language`, deliberately. A response that varies on a request header needs `Vary: Accept-Language`, at which point the edge caches one entry per header value and a crawler can be served a different page from a visitor — which is cloaking, and docs/83 §3 forbids it. The storefront already knows the locale: it is the first segment of every public URL.\n\nAn unknown locale falls back to the platform default rather than 4xx-ing: a stale link is a visitor, not an error.","schema":{"type":"string"}}],"responses":{"200":{"description":"The public listing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketplacePublicListing"}}}},"404":{"$ref":"#/components/responses/NotFound"},"410":{"description":"The listing was removed for good — archived or rejected — or it is our own test content (a lane walk, a checkout probe, a verify seller), which never reaches the storefront. Answered instead of 404 so a crawler drops the URL at once (D41601). A paused, draft or not-yet-projected listing is still a 404.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/compute/servers/{serverId}/overage":{"parameters":[{"$ref":"#/components/parameters/ComputeServerId"}],"get":{"operationId":"getComputeServerOverage","summary":"What this machine owes for bandwidth over its allowance this month.","description":"The traffic this machine has carried beyond its included allowance in the current metering period, what it has cost, what has already been paid, and the next threshold at which a charge is raised. Requires `sites.view`.\n\nOverage is charged **automatically at each threshold** rather than as one bill at the end of the month, so this is the screen that answers \"why was my card charged\". `charges` lists every threshold already raised for the period with what happened to it, including a decline — a decline is why a machine gets stopped, so it must be visible here rather than only in an email.\n\n`period` is the **provider's** metering month (`YYYY-MM`, UTC), not the subscription's billing period. The provider resets the counter it meters on at their month boundary, and the two disagree for anyone who bought mid-month; keying on the subscription's period would double-charge or free-ride on the first of every month.\n\n`last_known_at` is when a reading was last actually obtained. `null` beside a zero accrual means we have never had a number for this machine this period — **not** that it owes nothing — and a client must render that difference for the same reason it must not render an unknown usage gauge as `0%`.","tags":["compute"],"responses":{"200":{"description":"The machine's overage position for the current period.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeServerOverage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/pay/invoices/{token}":{"get":{"operationId":"getDirectInvoiceForPayer","summary":"An invoice, for the person paying it. Unauthenticated.","description":"**No authentication and no session.** The payer may have no account here at all; the capability token in the path is the whole authorisation and it reaches exactly one invoice.\n\nEvery string in the response is already translated into the recipient's locale — the one stored on the document, not the one of whoever's browser opened the link. The page that renders this holds no copy of its own.\n\nEvery refusal answers with the same sentence whatever the cause — a wrong token, a draft, a withdrawn or an unknown one. Distinguishing them would confirm to a stranger that a token is real, which is the oracle that makes a capability URL worth sweeping.","tags":["public"],"security":[],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","maxLength":64}}],"responses":{"200":{"description":"The invoice as the payer reads it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectInvoicePortal"}}}},"404":{"description":"This payment link is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/pay/invoices/{token}/checkout":{"post":{"operationId":"startDirectInvoicePayment","summary":"Start paying an invoice on our checkout. Unauthenticated.","description":"Joins the platform's ordinary money path at the front. It creates the recipient's lightweight account **here and not before** — an order is org-scoped and so is the invoice document its payment produces — mints one order for the document (idempotent, so a double tap reaches the same order and the same payment intent), and starts the charge on our own gateway.\n\nThe response carries whichever credential the chosen rail needs: `client_token` is a card intent's client secret for the browser SDK, `redirect_url` is an approval page for PayPal or a crypto invoice. `settled: true` means the total was zero and the order completed with no gateway at all.\n\n⛔ Nothing here captures money and nothing here decides an order is paid. The gateway's webhook does both, exactly as it does for every other order on the platform.","tags":["public"],"security":[],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","maxLength":64}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"gateway":{"type":"string","maxLength":32,"description":"The rail to settle on. Omit to follow the platform default."}}}}}},"responses":{"200":{"description":"The payment was started. Finish it with the credential returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectInvoicePaymentStart"}}}},"404":{"description":"This payment link is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The payment cannot be started. Either this invoice is not open for payment, or the address already has a Zinn Digital® account and the invoice is waiting on their billing page, or the payment method chosen is not one this invoice can be paid with (`rail_not_available` — never quietly swapped for a card).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"description":"Ours, retryable, and never blamed on the payer. Nothing has been charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/pay/invoices/{token}/confirm":{"post":{"operationId":"confirmDirectInvoicePayment","summary":"The payer entered a card — record it and take the money. Unauthenticated.","description":"The second half of a two-step that cannot be collapsed into one. A payer with no card on file gets a **SetupIntent** from `/checkout`, confirms it in the browser, and lands here; this records the mandate and then charges the order.\n\nCharging on the first call instead would put a failed payment on the order — this platform classifies a mandate-less charge as *nothing was presented* — and the capture webhook refuses to settle one of those, so the money would be taken and never recorded.\n\n`setup_intent_id` is an id and not a credential. The mandate behind it is re-read from the gateway and refused unless the gateway itself says it belongs to this invoice's payer, so holding one pay link cannot attach a stranger's saved card.","tags":["public"],"security":[],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","maxLength":64}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["setup_intent_id"],"properties":{"setup_intent_id":{"type":"string","minLength":8,"maxLength":128}}}}}},"responses":{"200":{"description":"The card was recorded and the charge attempted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectInvoicePaymentStart"}}}},"404":{"description":"This payment link is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The payment could not be completed. Nothing has been charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/pay/partner/{token}":{"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","maxLength":64}}],"get":{"operationId":"getPartnerPayment","summary":"A partner's domain order, for the customer paying it. Unauthenticated.","description":"**No authentication and no session.** The token in the path is the whole authorisation and it reaches exactly one order that a partner placed. Returns the lines, subtotal, tax, total, currency, the payment rails on offer, the partner's display name and the two exits (`cancel_url` while payable, `return_url` once paid) — nothing about the tenancy. Labels arrive translated for `locale`. An unknown, malformed, expired, cancelled or used link answers the same `404` sentence; a paid link can still be read for 30 minutes.","tags":["public"],"security":[],"parameters":[{"name":"locale","in":"query","required":false,"schema":{"type":"string","maxLength":12}}],"responses":{"200":{"description":"The order as the payer reads it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerPayment"}}}},"404":{"description":"This payment link is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"startPartnerPayment","summary":"Pay a partner's domain order on our checkout. Unauthenticated.","description":"With an empty body or `{\"rail\": …}`: the chosen rail is opened. Card gives a card-setup `client_token` (`status: setup_required`, nothing charged); PayPal gives a `paypal_order_id` for the wallet overlay (`status: paypal_approval_required`, nothing charged); crypto gives a `redirect_url` to the vendor invoice. With `setup_intent_id`, after the card form is confirmed: the card is re-read from the gateway, refused unless it belongs to this order's organization, recorded, and charged. With `paypal_order_id`, after the buyer approved: PayPal is asked to capture — the browser is never believed. When the order is paid, `return_url` is the partner's URL to send the browser to. ⛔ Nothing here decides an order is paid — the capture and the gateway webhook do, as for every order. A refusal the payer can act on is a `409` carrying its sentence.","tags":["public"],"security":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"rail":{"type":"string","maxLength":32,"description":"The rail the payer chose, from the `rails` the GET offered. Omitted means the default. A rail this order cannot settle on is refused with a sentence — it is never silently replaced by a card form."},"setup_intent_id":{"type":"string","maxLength":255},"paypal_order_id":{"type":"string","maxLength":255}}}}}},"responses":{"200":{"description":"The next step, or the settled payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerPaymentStep"}}}},"404":{"description":"This payment link is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/billing/adhoc-charges":{"get":{"operationId":"listMyAdhocCharges","summary":"The manual charges on your account, and what you have been billed.","description":"Ad-hoc items on your own account — anything a member of our team added by hand — plus the history of what has actually been billed. Requires `billing.view`.\n\nTwo questions, two halves: `data` answers *\"is this going to happen again\"* and `occurrences` answers *\"which invoice was that line on\"*. The staff notes that sit beside these items are never returned here.\n\n`occurrences[].paid` is tri-state: `true`, `false`, or `null` when the order could not be read — \"we do not know\" and \"you have not paid\" are different things to say to somebody about their own money.","tags":["billing"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"Required when you belong to more than one organisation. Omitted, it means your own — which is ambiguous for a reseller or an agency, so that answers 422 rather than guessing.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Your ad-hoc items and their billing history.","content":{"application/json":{"schema":{"type":"object","required":["data","occurrences"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdhocCharge"}},"occurrences":{"type":"array","items":{"$ref":"#/components/schemas/AdhocChargeOccurrence"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/wp-credentials":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteWpCredentials","summary":"The WordPress admin login for a site.","description":"Requires `sites.view` and `sites.panel_access` — the key that already means \"a customer reaching their own site\". Every read is audit-logged: a password revealed by session alone is only safe if looking at it is attributable.\n\nRe-reads the site's own `wp_users` row before answering, so the screen a human is looking at is never stale. A site that cannot be reached is not an error: the stored record is returned unchanged and `checked_at` says when the platform last managed to look.","tags":["hosting"],"responses":{"200":{"description":"The credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WpCredentials"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"rotateSiteWpPassword","summary":"Generate a new WordPress admin password for a site.","description":"Sets a new password on the server first and records it only once WordPress has it, so a failure can never leave the customer holding a password that does not open their site. Requires `sites.view` and `sites.panel_access`, and is audit-logged.\n\nRe-reads the site's admin row before resolving which user to act on. Without that step this call fails with \"no such user\" for exactly the customers who need it — the ones who renamed their WordPress admin outside the app — so the one action that repairs a drifted credential was the one that stopped working once there was drift to repair.","tags":["hosting"],"responses":{"200":{"description":"The new credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WpCredentials"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/plugin-clicks":{"post":{"operationId":"recordPublicPluginClick","summary":"A visitor on one of our sites clicked a plugin-store checkout or a free download.","description":"docs/1002 §4 — the beacon our product sites send (`navigator.sendBeacon`, so the body may arrive as `text/plain`; it is read as JSON either way, at most 8 KiB). The engine records the click so the store's sale, which happens on a checkout we cannot tag, can be joined back to the advert and site that produced it. Kept: the store product and plan named by `href` (a store checkout, a free download on wordpress.org, GitHub or our own `api.zinndigital.com/v1/plugins/<slug>/download`), the site (from `Origin`), the ad networks' click ids (Google's, `msclkid`, `twclid` and ChatGPT Ads' `oppref`), UTM source/medium/campaign, the landing page (host + path, never a query) and GA4's own client/session id. ⛔ The visitor's IP is kept ONLY as a keyed hash, and only when the engine can establish the real client address. Always answers `204` with no body, whether or not anything was recorded. Anonymous; throttled per source address (`plugin_click`).","tags":["public"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginClick"}},"text/plain":{"schema":{"type":"string","maxLength":8192}}}},"responses":{"204":{"description":"Received."},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/pricing/tax-quote":{"post":{"operationId":"quotePublicTaxDisplay","summary":"What these net prices look like to a signed-out visitor, after VAT.","description":"The anonymous half of `quoteTaxDisplay` (#1482). Same answer, one difference that matters: there is no organisation, so there is no validated VAT number and **every visitor is treated as a consumer**.\n\n⛔ **This route accepts no buyer-validation flag, deliberately.** Reverse charge turns on a VIES-validated number and the seller carries the liability for granting it wrongly (`docs/34` §2.3), so a client-supplied validation claim would be a request to zero-rate a sale on the buyer's own say-so. Treating everyone as a consumer is also the safe direction: it over-states rather than under-states the tax due.\n\nCountry comes from the request body or Cloudflare's `CF-IPCountry`. The answer is always `estimated: true` — a pricing page runs on a geo hint, and the charge is rated again at checkout against real place-of-supply evidence.","tags":["public"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxQuoteRequest"}}}},"responses":{"200":{"description":"The same figures the signed-in route returns.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxQuote"}}}},"422":{"description":"A malformed item list, a repeated `ref`, or an unknown currency.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/payment-config":{"get":{"operationId":"getPublicPaymentConfig","summary":"The publishable key and enabled gateways, for a browser.","description":"Unauthenticated: the guest checkout funnel has no principal, and everything here is public by construction — a Stripe **publishable** key is designed to be embedded in a page, and \"which gateways are switched on\" is visible at checkout anyway.\n\nThis exists so the key is **rotatable from admin**. The dashboard used to read it from `VITE_STRIPE_PUBLISHABLE_KEY`, a build-time constant that was set in no build — so every deployed dashboard shipped an empty key and could only tell customers card payments were unavailable. A build-time value also could not be changed by editing a row, which is what the owner asked for.","tags":["public"],"security":[],"responses":{"200":{"description":"What a browser needs to render a payment step.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentConfig"}}}}}}},"/.well-known/openai-apps-challenge":{"get":{"operationId":"getOpenAIAppsChallenge","summary":"ChatGPT app-directory domain-verification token (plain text).","description":"The token OpenAI's plugin portal asks the MCP host to serve before it connects the server for review (docs/925 §6): exactly the token as `text/plain`, never JSON. Public by design; set in Vault without a deploy. `404` while no token is set. Unauthenticated.","tags":["mcp"],"security":[],"responses":{"200":{"description":"The token, and nothing else.","content":{"text/plain":{"schema":{"type":"string","example":"oai-apps-challenge-0123456789abcdef"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/.well-known/openai-apps-challenge/ads":{"get":{"operationId":"getOpenAIAppsChallengeAds","summary":"The Zinn® Ads ChatGPT plugin's domain-verification token (plain text).","description":"The Zinn® Ads plugin (`/v1/mcp/ads`) cannot use the token above, which belongs to the Zinn Digital® plugin on this host, so it verifies on the parent origin `zinndigital.com`, whose Worker serves this value at `https://zinndigital.com/.well-known/openai-apps-challenge` (docs/925 §1b). Vault `secret/platform/openai-apps-challenge-ads#token`; `404` while unset. Unauthenticated.","tags":["mcp"],"security":[],"responses":{"200":{"description":"The token, and nothing else.","content":{"text/plain":{"schema":{"type":"string","example":"oai-apps-challenge-0123456789abcdef"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/.well-known/oauth-protected-resource":{"get":{"operationId":"getMcpProtectedResourceMetadata","summary":"OAuth 2.1 protected-resource metadata for the MCP server (RFC 9728).","description":"The discovery document a compliant MCP client fetches (after a `401` from the MCP endpoint) to learn which authorization server issues tokens for this resource. Unauthenticated.","tags":["mcp"],"security":[],"responses":{"200":{"description":"The protected-resource metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthProtectedResourceMetadata"}}}}}}},"/.well-known/oauth-protected-resource/v1/mcp":{"get":{"operationId":"getMcpProtectedResourceMetadataForPath","summary":"The MCP server's protected-resource metadata at its path-qualified URL (RFC 9728 §3.1).","description":"The same document as `/.well-known/oauth-protected-resource`, at the path-qualified URL a compliant client asks for first for the resource `…/v1/mcp`. Unauthenticated.","tags":["mcp"],"security":[],"responses":{"200":{"description":"The protected-resource metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthProtectedResourceMetadata"}}}}}}},"/.well-known/oauth-protected-resource/v1/mcp/ads":{"get":{"operationId":"getMcpAdsProtectedResourceMetadata","summary":"The Zinn® Ads MCP endpoint's protected-resource metadata (RFC 9728 §3.1).","description":"The document a `401` from `/v1/mcp/ads` points at. Its `resource` is `…/v1/mcp/ads` and `scopes_supported` lists only the permissions a Zinn® Ads tool needs (docs/925 §1b). Unauthenticated.","tags":["mcp"],"security":[],"responses":{"200":{"description":"The protected-resource metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthProtectedResourceMetadata"}}}}}}},"/.well-known/oauth-authorization-server":{"get":{"operationId":"getMcpOAuthServerMetadata","summary":"OAuth 2.1 authorization-server metadata for AI apps (RFC 8414).","description":"The engine's own authorization server for MCP clients (Claude, ChatGPT, Cursor…): dynamic client registration (RFC 7591), Client ID Metadata Documents, PKCE S256 only, rotating refresh tokens and RFC 7009 revocation. The person signs in through Keycloak on the dashboard consent page and picks the organization and permissions the app gets (docs/27 §3a). `404` while the OAuth kill switch is off. Unauthenticated.","tags":["mcp"],"security":[],"responses":{"200":{"description":"The authorization-server metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthAuthorizationServerMetadata"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/.well-known/openid-configuration":{"get":{"operationId":"getMcpOAuthServerMetadataOidc","summary":"The authorization-server metadata at the OpenID discovery path.","description":"Identical to `/.well-known/oauth-authorization-server` (RFC 8414). Served because some AI-app clients (OpenAI's) try OpenID Connect discovery as well; no ID tokens are issued. `404` while the OAuth kill switch is off. Unauthenticated.","tags":["mcp"],"security":[],"responses":{"200":{"description":"The authorization-server metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthAuthorizationServerMetadata"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/.well-known/oauth-authorization-server/v1/mcp":{"get":{"operationId":"getMcpOAuthServerMetadataForPath","summary":"The authorization-server metadata, for clients that append the resource path.","description":"Identical to `/.well-known/oauth-authorization-server`. Unauthenticated.","tags":["mcp"],"security":[],"responses":{"200":{"description":"The authorization-server metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthAuthorizationServerMetadata"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/oauth/register":{"post":{"operationId":"registerMcpOAuthClient","summary":"Register an AI app as an OAuth client (RFC 7591 dynamic client registration).","description":"Open registration, as both connector directories require. `redirect_uris` must be https, loopback http or an app scheme; a public client (`none`) uses PKCE only, a confidential one receives a `client_secret` once (stored only as a hash). Bounded per source address per hour. Registering grants nothing: a person still has to approve the app on the consent page. Unauthenticated.","tags":["mcp"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthClientRegistrationRequest"}}}},"responses":{"201":{"description":"The registered client.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthClientRegistrationResponse"}}}},"400":{"description":"The metadata was refused (`invalid_redirect_uri`, `invalid_client_metadata`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthErrorResponse"}}}},"429":{"description":"Too many registrations from this address this hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthErrorResponse"}}}},"503":{"description":"The OAuth kill switch is off (`temporarily_unavailable`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthErrorResponse"}}}}}}},"/v1/oauth/authorize":{"get":{"operationId":"authorizeMcpOAuth","summary":"Start an AI app's sign-in (OAuth 2.1 authorization endpoint).","description":"Validates the client (a registered `zoc_…` id, or a Client ID Metadata Document URL), the exact redirect URI and the PKCE S256 challenge, then redirects the browser to the dashboard consent page. A bad client or redirect URI is answered here with `400` and is never redirected (no open redirector); every other error goes back to the client's redirect URI with `error`, `state` and `iss`. Unauthenticated (the consent page signs the person in).","tags":["mcp"],"security":[],"parameters":[{"name":"response_type","in":"query","required":true,"schema":{"type":"string","enum":["code"]}},{"name":"client_id","in":"query","required":true,"schema":{"type":"string"}},{"name":"redirect_uri","in":"query","required":true,"schema":{"type":"string"}},{"name":"code_challenge","in":"query","required":true,"schema":{"type":"string"}},{"name":"code_challenge_method","in":"query","required":true,"schema":{"type":"string","enum":["S256"]}},{"name":"state","in":"query","required":false,"schema":{"type":"string"}},{"name":"scope","in":"query","required":false,"description":"Space-separated permission keys to pre-select on the consent page.","schema":{"type":"string"}},{"name":"resource","in":"query","required":false,"description":"RFC 8707 — must be this server's MCP endpoint.","schema":{"type":"string"}}],"responses":{"302":{"description":"To the consent page, or back to the client's redirect URI with an error."},"400":{"description":"Unknown client or unregistered redirect URI.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthErrorResponse"}}}},"503":{"description":"The OAuth kill switch is off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthErrorResponse"}}}}}}},"/v1/oauth/token":{"post":{"operationId":"exchangeMcpOAuthToken","summary":"Exchange a code or refresh token for MCP access tokens (OAuth 2.1 token endpoint).","description":"`authorization_code` (with the PKCE `code_verifier`; a code is single-use and lives two minutes) or `refresh_token` (rotating: each refresh returns a new pair, and presenting a used refresh token again revokes the whole connection). Access tokens (`zoat_…`) last one hour and are accepted only on `/v1/mcp`. Confidential clients authenticate with HTTP Basic or `client_secret_post`. Unauthenticated otherwise.","tags":["mcp"],"security":[],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/OAuthTokenRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/OAuthTokenRequest"}}}},"responses":{"200":{"description":"A new token pair.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthTokenResponse"}}}},"400":{"description":"`invalid_grant`, `invalid_client`, `unsupported_grant_type`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthErrorResponse"}}}},"401":{"description":"Client authentication failed (`invalid_client`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthErrorResponse"}}}},"503":{"description":"The OAuth kill switch is off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthErrorResponse"}}}}}}},"/v1/oauth/revoke":{"post":{"operationId":"revokeMcpOAuthToken","summary":"Revoke an AI app's access (RFC 7009).","description":"Revoking either token ends the connection it belongs to (the same as revoking it on the dashboard's AI tools screen). An unknown token is not an error. Unauthenticated (client credentials for a confidential client).","tags":["mcp"],"security":[],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/OAuthRevokeRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/OAuthRevokeRequest"}}}},"responses":{"200":{"description":"Revoked (or there was nothing to revoke).","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Client authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthErrorResponse"}}}},"503":{"description":"The OAuth kill switch is off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthErrorResponse"}}}}}}},"/v1/mcp/oauth/requests/{requestId}":{"parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"operationId":"getMcpOAuthRequest","summary":"What an AI app asking to connect wants (the consent screen's data).","description":"The parked authorization request: the app's name, logo, how it identified itself (a metadata-document client shows its verified domain), where it will send the person back to, and the permissions it asked for. Expires ten minutes after the app started the sign-in. Requires `mcp.manage`.","tags":["mcp"],"responses":{"200":{"description":"The request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpOAuthConsentRequest"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/mcp/oauth/requests/{requestId}/approve":{"parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"operationId":"approveMcpOAuthRequest","summary":"Approve an AI app — creates the connection and returns the app's redirect.","description":"Creates an MCP connection (`kind: oauth`) in the chosen organization with the chosen permissions and returns the URL to send the browser back to, carrying a one-time code. The person must manage MCP connections in that organization and may grant only permissions they hold there (`403` otherwise); a request is approved once (`404` after). Audited as `mcp.connection.created`. Requires `mcp.manage`.","tags":["mcp"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpOAuthApproveRequest"}}}},"responses":{"200":{"description":"Approved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpOAuthRedirect"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/mcp/oauth/requests/{requestId}/deny":{"parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"operationId":"denyMcpOAuthRequest","summary":"Decline an AI app — returns the app's redirect carrying `access_denied`.","description":"Ends the request; nothing is created. Requires a signed-in person.","tags":["mcp"],"responses":{"200":{"description":"Declined.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpOAuthRedirect"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/mcp":{"post":{"operationId":"mcpRpc","summary":"The MCP JSON-RPC 2.0 protocol endpoint.","description":"The Model Context Protocol endpoint (`initialize`, `tools/list`, `tools/call`, `resources/list`, `resources/read`, `ping`). Authenticated **only** by a `zmcp_…` connection token (`Authorization: Bearer zmcp_…`); a missing/invalid token returns `401` with a `WWW-Authenticate` challenge pointing at the resource-metadata document. Each call runs under the connecting org's RLS scope and is gated by the connection's RBAC scopes; a batch (JSON array) is accepted. The tool catalogue is additionally filtered by the connecting org's **role** (customer, reseller's client, agency, reseller, staff), in `tools/list` and `tools/call` alike — a role-hidden tool answers *unknown tool*, never *forbidden*. An entitlement refusal (a full plan, a feature not on the tier) is returned as a tool result carrying a structured upgrade offer, never as a JSON-RPC error. An OAuth token issued for another MCP endpoint (`/v1/mcp/ads`) is refused with `401`.","tags":["mcp"],"security":[{"mcpTokenAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/JsonRpcRequest"},{"type":"array","items":{"$ref":"#/components/schemas/JsonRpcRequest"}}]}}}},"responses":{"200":{"description":"The JSON-RPC response (object, or array for a batch).","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/JsonRpcResponse"},{"type":"array","items":{"$ref":"#/components/schemas/JsonRpcResponse"}}]}}}},"202":{"description":"Accepted — the message(s) were notifications with no response."},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/mcp/ads":{"post":{"operationId":"mcpAdsRpc","summary":"The Zinn® Ads MCP endpoint — the same protocol, serving only the Zinn® Ads tools.","description":"The \"Zinn® Ads\" listing in the Claude and ChatGPT directories (docs/925 §1b). Same JSON-RPC 2.0 protocol as `/v1/mcp`, but `tools/list` and `tools/call` cover only the `ads_*` tools (any other tool answers *unknown tool*), and `resources/list` and `prompts/list` are empty. Authenticated **only** by an OAuth access token issued for this URL (RFC 8707 `resource`): a token issued for `/v1/mcp`, or a pasted `zmcp_…` token, is refused with `401`, and a token issued here is refused at `/v1/mcp`. The consent screen for this resource offers only the Zinn® Ads permissions.","tags":["mcp"],"security":[{"mcpTokenAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/JsonRpcRequest"},{"type":"array","items":{"$ref":"#/components/schemas/JsonRpcRequest"}}]}}}},"responses":{"200":{"description":"The JSON-RPC response (object, or array for a batch).","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/JsonRpcResponse"},{"type":"array","items":{"$ref":"#/components/schemas/JsonRpcResponse"}}]}}}},"202":{"description":"Accepted — the message(s) were notifications with no response."},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/mcp/scopes":{"get":{"operationId":"listMcpGrantableScopes","summary":"The permissions worth granting an AI tool.","description":"The RBAC permissions an MCP connection can usefully be granted, **derived from the registered tool set** rather than listed by hand, with the number of tools each one unlocks and how many of those are destructive. `held` says whether the caller can actually grant it — a connection can never out-scope its creator, so an unheld scope would be refused with a `403` at create time. Read-only scopes are returned first. Requires `mcp.manage`.","tags":["mcp"],"responses":{"200":{"description":"The grantable scopes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpGrantableScopePage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/mcp/connections":{"get":{"operationId":"listMcpConnections","summary":"List the organization's MCP connections.","description":"Lists the non-revoked MCP connections the caller can manage. Only metadata is returned — never the token or its hash (CLAUDE.md §2.4). Requires `mcp.manage`.","tags":["mcp"],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"A page of MCP connections.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpConnectionPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createMcpConnection","summary":"Create an MCP connection (Connect AI tool).","description":"Mints a per-tool MCP connection and returns the full `zmcp_…` token **once** (only its hash is stored) plus a paste-ready client config snippet. The requested `scopes` must be permissions the caller already holds in the target org — an unheld scope is a `403` (a connection can never out-scope its creator), an unknown one a `422`. A scope that `GET /v1/mcp/scopes` does not offer to AI connections is also a `422`: holding a permission is not enough to hand it to an assistant. An optional spend cap bounds AI-triggered paid actions. Requires `mcp.manage`.","tags":["mcp"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpConnectionCreate"}}}},"responses":{"201":{"description":"The created connection, including its one-time token + client config.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpConnectionCreated"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/mcp/connections/{connectionId}":{"parameters":[{"$ref":"#/components/parameters/ConnectionId"}],"get":{"operationId":"getMcpConnection","summary":"Get an MCP connection.","description":"Returns one non-revoked connection's metadata (never the token). RBAC + RLS scoped.","tags":["mcp"],"responses":{"200":{"description":"The MCP connection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpConnection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"revokeMcpConnection","summary":"Revoke an MCP connection.","description":"Revokes the connection — its token stops authenticating immediately. The revocation is audit-logged. Requires `mcp.manage`.","tags":["mcp"],"responses":{"204":{"description":"The connection was revoked."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/domains/{domainId}/cache/purge":{"parameters":[{"$ref":"#/components/parameters/DomainId"}],"post":{"operationId":"purgeDomainCache","summary":"Purge a domain's CDN cache.","description":"Purge the CDN cache for a domain now. Omit `urls` to purge everything, or pass a bounded list of absolute URLs to purge only those. Exposed on the dashboard and the MCP server through the same service, so the two cannot diverge (docs/19 §5.4). A domain not served through our CDN is a `404`. Requires `sites.cache.purge`.","tags":["domains"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CachePurgeRequest"}}}},"responses":{"200":{"description":"The cache was purged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CachePurgeResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/domains/{domainId}/dns/sync":{"parameters":[{"$ref":"#/components/parameters/DomainId"}],"post":{"operationId":"syncDomainDns","summary":"Trigger immediate DNS propagation.","description":"Publish a `domain.dns_changed` event so dependent systems (CDN origin, certificate SANs, indexing) reconcile the domain's DNS **at once** rather than waiting for a periodic sweep (register #93). A domain whose authoritative DNS we do not host is a `404`. Requires `domains.dns.manage`.","tags":["domains"],"responses":{"202":{"description":"The change was published for immediate propagation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DnsSyncResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/crawler-policy":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getCrawlerPolicy","summary":"Get a site's SEO-crawler-blocking (PBN footprint) policy.","description":"The effective crawler-block policy for a site — the stored override or the line default (the PBN/footprint-free line blocks every SEO crawler by default; other lines block none). Returns the blocked crawler keys, the catalog of blockable crawlers, and the rendered `robots.txt` + server rules. Search engines (Googlebot/Bingbot) are never blockable. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The effective crawler-block policy + rendered rules.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrawlerPolicyResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setCrawlerPolicy","summary":"Set a site's SEO-crawler-blocking policy.","description":"Set which SEO crawlers to block (`blocked` is a list of crawler keys from the catalog). An unknown key is a `422`; a search engine has no key, so it can never be blocked. Publishes `site.crawler_policy_changed` so the server-level rules are re-written. The response answers at once with `enforcement.reason: pending` on a platform that can carry the rules; a background workflow writes the server and records the outcome, which the GET then returns (D30500). Requires `sites.crawler.manage`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrawlerPolicyWrite"}}}},"responses":{"200":{"description":"The updated effective policy + rendered rules.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrawlerPolicyResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/crawler-block":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteCrawlerBlock","tags":["hosting"],"summary":"Get a site's blocked-crawler selection.","description":"A second representation of the same policy as `crawler-policy`, not a second setting: this one carries just the customer-facing selection, while `crawler-policy` additionally returns the rendered server rules that MCP and the hosting worker consume. `available_bots` is the catalog of blockable SEO crawlers, which by construction contains no search engine — so a customer cannot de-index themselves here, because Googlebot and Bingbot are not in the list to choose from. Requires `sites.view`.","responses":{"200":{"description":"The site's crawler-block selection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrawlerBlock"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setSiteCrawlerBlock","tags":["hosting"],"summary":"Replace a site's blocked-crawler selection.","description":"Replaces the blocked set. Only keys from `available_bots` are accepted; an unknown key is rejected rather than ignored. Settings this surface does not expose (`robots_txt`, `ip_deny`) are preserved, never reset. Answers at once with `enforcement.reason: pending` on a platform that can carry the rules; a background workflow writes the server and records the outcome, which the GET then returns (D30500). Requires `sites.crawler.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrawlerBlockUpdate"}}}},"responses":{"200":{"description":"The updated crawler-block selection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrawlerBlock"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/performance":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSitePerformance","tags":["hosting"],"summary":"Get a site's caching and acceleration settings.","description":"The free server-side cache layers (LiteSpeed LSCache, Redis object cache) plus the AccelerateWP premium upsell and its trial state. The row is created on first read, so a site that has never been configured returns defaults rather than 404. Requires `sites.view`.","responses":{"200":{"description":"The site's performance settings.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePerformance"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setSitePerformance","tags":["hosting"],"summary":"Update a site's caching and acceleration settings.","description":"Merge semantics: every field is optional and only the fields present are applied, so toggling one setting never resets the others. Selecting the `premium` AccelerateWP tier starts the trial and requires a payment method on file, returning `PAYMENT_METHOD_REQUIRED` otherwise. While Premium is not on sale (`accelerate_wp.premium_available: false`) it answers `409 ACCELERATE_WP_PREMIUM_UNAVAILABLE` before any billing check. Returns the complete updated resource. Requires `hosting.performance.manage`, and additionally `billing.payment.manage` when changing the AccelerateWP tier.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePerformanceUpdate"}}}},"responses":{"200":{"description":"The complete updated performance settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePerformance"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/cdn":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteCdn","tags":["hosting"],"summary":"Get a site's CDN configuration.","description":"On the footprint-free line the CDN is platform-managed footprint machinery: `managed` is true and `provider` is always null, because naming the CDN in front of a PBN site would leak the footprint the line exists to hide (register #93). On other lines the customer picks a tier or brings their own connected account. Requires `sites.view`.","responses":{"200":{"description":"The site's CDN configuration.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CdnConfig"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setSiteCdn","tags":["hosting"],"summary":"Choose a site's CDN tier.","description":"Mainstream lines only — a managed (footprint-free) site returns `FOOTPRINT_MANAGED`. Selecting `byo` requires an already-connected Cloudflare account, else `NO_CLOUDFLARE_CONNECTION`. The zone is created or torn down asynchronously; the response reflects the requested desired state. Requires `hosting.cdn.manage`.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CdnUpdate"}}}},"responses":{"200":{"description":"The complete updated CDN configuration.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CdnConfig"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/cdn/offers":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"listSiteCdnOffers","tags":["hosting"],"summary":"The CDNs this site's product line can actually buy.","description":"Keyed on the **pair** `(product line, vendor)`, never on the vendor alone. The same network is a different product on different lines: Bunny on Footprint-Free is platform-managed footprint machinery and is included, while Bunny on mainstream is a speed upgrade the customer pays for. A catalogue keyed on the vendor has one answer for both, and whichever answer it gives is wrong for one line — either a mainstream customer gets a paid upgrade free, or a Footprint-Free customer is asked to buy the CDN their product already is.\n\nOn a **managed line the `vendor` and `label` fields are omitted entirely**, not blanked. Naming which of the pool accounts fronts a site is one query away from linking a customer's PBN domains to each other, which is the single fact that product exists to hide; an empty string would still reach the client and render as a gap rather than as nothing.\n\n`region_weights` is how a flat allowance stays honest across geography. A gigabyte served to Africa costs us six times one served to Frankfurt, so allowance is denominated in base-region-equivalent gigabytes and dearer regions spend it faster. That makes `allowance_gb x base_rate` the exact worst case whatever traffic mix the customer serves. Requires `sites.view`.","responses":{"200":{"description":"What is on offer for this site's line.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCdnOffers"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/cdn/origin-host":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteOriginHost","tags":["hosting"],"summary":"The origin hostname a hostname-only CDN pulls from, and the record to add.","description":"Some CDNs (KeyCDN) refuse an IP address as a pull origin, so the site is given an origin HOSTNAME: `o-<hash>.<site domain>`, written by us where we run the site's DNS, or added by the customer where they run it; otherwise a neutral fallback name. `record` is the one `A` record a customer who runs their own DNS adds, and `answering` says whether public DNS returns it with the origin address right now. Read-only. Requires `sites.view`.","responses":{"200":{"description":"The site's origin hostname state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteOriginHost"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/cdn/origin-host/check":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"checkSiteOriginHost","tags":["hosting"],"summary":"Re-read public DNS for the customer's origin record and use it when it answers.","description":"The dashboard's *Check* button. Reads public DNS for `record.name`; when it answers with the origin address the name becomes the site's origin hostname (mode `customer_dns`), unless the platform already holds one on DNS it runs. Writes no DNS record and calls no CDN. Requires `hosting.cdn.manage`.","responses":{"200":{"description":"The site's origin hostname state after the check.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteOriginHost"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/dns-publish":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteDnsPublish","tags":["hosting"],"summary":"Where this site's DNS is published, on Zinn®'s servers or your own DNS account.","description":"Read-only. Requires `sites.view`.","responses":{"200":{"description":"The site's DNS-publish choice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteDnsPublish"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setSiteDnsPublish","tags":["hosting"],"summary":"Change where this site's DNS is published.","description":"`own` runs the same read-only pre-flight as `preflightOwnDns` first; when it fails the answer is 422 naming the fix and nothing changes. `zinn` always succeeds. The choice decides where the NEXT DNS publish goes; records already published are not moved. Audit-logged. Requires `hosting.deploy.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["publish_on"],"properties":{"publish_on":{"type":"string","enum":["zinn","own"]}}}}}},"responses":{"200":{"description":"The site's DNS-publish choice after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteDnsPublish"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/cdn/canonical-host":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteCanonicalHost","tags":["hosting"],"summary":"Which hostname serves, which redirects, and whether HTTPS is forced.","description":"Returns the whole serving plan rather than the two stored flags: the host that serves, the host that `301`s to it, and **every hostname the edge certificate must cover**. A client given only `canonical_host` would have to work out the alias itself, and two implementations of \"what is the other hostname\" is exactly the drift the engine-owns-policy rule exists to prevent.\n\n`certificate_hosts` always contains **both** names, and that is the half that is invisible when testing in a browser. TLS is negotiated on the name being redirected *from*, so a certificate covering only the canonical host puts a full-page security interstitial in front of the alias and the visitor never reaches the redirect at all. Requires `sites.view`.","responses":{"200":{"description":"The site's canonical-host plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCanonicalHost"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateSiteCanonicalHost","tags":["hosting"],"summary":"Choose www or non-www, and whether to force HTTPS.","description":"A **merge**: only the fields present in the body change. An absent field is left alone rather than reset, so a client written before one of these existed cannot switch it off on every save.\n\n`force_https` defaults to `true` on every new site. The insecure choice has to be made explicitly; it is never reached by omitting a field.\n\nA site whose primary domain is a **deeper subdomain** (`shop.blog.example.com`) has no `www` counterpart, and the request is a `422` rather than a stored preference whose plan can never be built. Refusing at write time is deliberate: the alternative saves cleanly and then fails later inside provisioning, where the customer sees a stuck deploy instead of the bad input. An empty body is a `422`, not a no-op success. Requires `hosting.cdn.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCanonicalHostUpdate"}}}},"responses":{"200":{"description":"The plan after applying the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCanonicalHost"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/cdn/usage":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteCdnUsage","tags":["hosting"],"summary":"This month's CDN allowance on a pool CDN, and how much of it the site has used.","description":"Every site served by one of our pooled CDNs includes a monthly CDN allowance (the provider's cost of serving it, `cap_micros`, $0.25 by default, plus any top-ups bought this month). The customer is warned at `warn_low_pct` and `warn_high_pct`; at 100% the site's CDN is paused (`status: paused`) until the month ends or a top-up is added. A site on an unmetered CDN reads `metered: false` and `status: unmetered` (included, no cap). `tiers` are the one-off top-ups on sale, priced in integer minor units with their ISO currency. Requires `sites.view`.","responses":{"200":{"description":"The site's CDN usage this month.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCdnUsage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/cdn/usage/top-ups":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"createSiteCdnUsageTopUp","tags":["hosting"],"summary":"Add a one-off CDN top-up to this site for the rest of the month.","description":"Paid from the organization's Zinn® credit — never a card charge, and nothing renews. Idempotent on `request_id`: a retry with the same id returns the same top-up and debits nothing more. A paused site whose new allowance covers its spend is switched back on in the same call. Refused (422) for a site with no allowance, an unknown tier, an account not in good standing, a tier too small to lift the site back under its allowance (`enough: false`), or credit that does not cover the price. Requires `hosting.cdn.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCdnUsageTopUpRequest"}}}},"responses":{"201":{"description":"The top-up was added (or had already been added for this request id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCdnUsageTopUp"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/cdn/budget":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteCdnBudget","tags":["hosting"],"summary":"This site's slice of the account's metered CDN spend.","description":"A **per-site** ceiling, which exists so that one site cannot take the rest of an account down with it. With only an account-level cap, a single crawled domain spends the whole balance and every other site in the account stops serving — a denial of service on a customer's entire estate, triggered by a stranger with a scraper.\n\n`serving` is the honest answer to \"is the CDN working right now?\" and reads **both** this site's state and its account's, because either can pause it. Requires `sites.view`.","responses":{"200":{"description":"The site's budget and whether it is currently serving.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCdnBudget"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateSiteCdnBudget","tags":["hosting"],"summary":"Set this site's metered CDN spend ceiling.","description":"`cap_minor: 0` means **no per-site ceiling** — the account cap alone applies — and is the default. Any other value must be at least the platform minimum; a cap of a few cents is a site that pauses on its first visitor and reads as broken hosting rather than as a budget working.\n\nRaising the cap above what the site has already spent **resumes** it. Leaving it paused would require a second, undiscoverable action and would read as the setting not working. A site paused by staff is not resumed by this — that pause is not the customer's to lift. Requires `hosting.cdn.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCdnBudgetUpdate"}}}},"responses":{"200":{"description":"The budget after applying the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCdnBudget"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/cdn/credit":{"get":{"operationId":"getCdnCredit","tags":["billing"],"summary":"The account's prepaid metered-CDN balance, spend cap and top-up settings.","description":"The metered Enterprise-edge tier is prepaid. This is the balance, the customer's own spend ceiling, what has been spent this period, and whether auto-top-up is on.\n\n`worst_case_overshoot_minor` is reported to the customer rather than hidden, and it is the honest part of this endpoint. A spend cap cannot be exact: between one usage sample and the cut-off, traffic keeps flowing, so the cap is overshot by `peak_bandwidth x poll_interval x rate`. That is bounded by a hard egress rate limit at the vendor, not by how often we poll — but it is not zero, and a product that promises an exact ceiling it cannot hold is worse than one that states the tolerance. Requires `billing.view`.","parameters":[{"$ref":"#/components/parameters/ActiveOrg"}],"responses":{"200":{"description":"The account's CDN credit state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CdnCredit"}}}},"204":{"description":"This organization buys no metered CDN (the common case) — an empty state, not an error. Before 2026-10-16 this was a 404, logged by every browser on every Billing page load (s1014 L58)."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateCdnCredit","tags":["billing"],"summary":"Set the spend cap, or turn auto-top-up on or off.","description":"The spend cap is the customer's and it is enforced, not advisory: reaching it pauses metered serving. It has a platform minimum, below which a cap would pause an account before it could do anything useful.\n\nAuto-top-up refills the **balance** so serving continues below the ceiling. It never raises the ceiling — a top-up that moved the cap would make the cap unreachable and turn a spending limit into a delay.\n\nRaising the cap above current spend resumes an account paused by that cap. It does **not** resume one paused by staff, or one paused because the account is not in good standing; those need the thing that actually caused them. Reading the balance is `billing.view`; changing a ceiling is a money change and requires `billing.payment.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CdnCreditUpdate"}}}},"parameters":[{"$ref":"#/components/parameters/ActiveOrg"}],"responses":{"200":{"description":"The credit state after applying the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CdnCredit"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/cdn/switch":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"switchSiteCdn","deprecated":true,"x-sunset":"2027-03-11","tags":["hosting"],"summary":"Deprecated: start a move of this site's CDN (use startSiteCdnSwap).","description":"⛔ **Deprecated since 2026-09-11; stops answering on 2027-03-11.** Use `startSiteCdnSwap` (`POST /v1/sites/{siteId}/cdn/swap`), which names the destination account. Every response carries `Deprecation`, `Sunset` and a `Link` to the successor.\n\n⛔⛔ **This operation no longer moves the site inside the request, and that is the fix, not a regression (D23680).** It used to create the zone on the destination, repoint the site and delete the old zone in one call. On a zone-owning CDN the nameservers belong to the ACCOUNT, so your registrar still pointed at the old zone when it was deleted — the site went dark and the response said `200` with `old_zone_removed: true`. It now starts the same durable move as `startSiteCdnSwap`: the old zone is removed **only once your domain is observed answering from the new nameservers**, and every failure leaves the site serving where it was.\n\n**The response shape is unchanged** — `CdnConfig`, `200` — and says only what is true the moment the move starts: the configuration is still the source's, `old_zone_removed` is `false` and `nameservers` is empty (the destination zone does not exist yet). `swap` is the move itself; poll `getSiteCdnSwap` for its progress and for the nameservers to set at your registrar.\n\n`{\"to_own\": true}` means your one usable CDN account. With more than one connected it is refused with a sentence naming `startSiteCdnSwap`, rather than guessed. A request for where the site already is answers `200` with `swap: null` and starts nothing.\n\n⛔ There is no origin, zone or account field: every one is derived server-side from what the site is placed on. A Footprint-Free site needs `footprint_acknowledged` to move **onto** its own account (owner ruling G-3) and needs nothing to move back. Requires `hosting.cdn.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CdnSwitch"}}}},"responses":{"200":{"description":"The move has started (`swap`), or the site is already where the request asked (`swap: null`). The configuration is the site's CURRENT one.","headers":{"Deprecation":{"description":"RFC 9745 — when this operation was deprecated (`@<unix-seconds>`).","schema":{"type":"string"}},"Sunset":{"description":"RFC 8594 — the HTTP-date after which this operation stops answering.","schema":{"type":"string"}},"Link":{"description":"The successor operation (`rel=\"successor-version\"`).","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CdnConfig"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/cdn/targets":{"get":{"operationId":"listCdnTargetsForCreate","tags":["hosting"],"summary":"Where a NEW site's CDN could be served from.","description":"The CDN destinations a site you are about to create could be placed on: Zinn®'s own pool, and **one row per CDN account you have connected**.\n\n⛔⛤ **This exists because the create wizard asked a boolean.** *\"Use my own CDN\"* is a checkbox, and a checkbox cannot name one of two accounts — so a customer with two Cloudflare accounts said *\"mine\"* and the platform chose which. The wizard also showed that checkbox only when a connected provider was literally `cloudflare`, so an account on Bunny or CDN77 had no control at all and no explanation for its absence.\n\n⛔ Pass `product_line`. It is the one input that changes the answer: on a platform-managed line (Footprint-Free) creating straight onto your own account is refused — every site on one account can be linked to every other on it, which is what that line is sold to prevent — so each account comes back listed, unavailable, with `reason: line_is_platform_managed`. Listing it and saying why is the point: a customer who cannot find their account concludes the connection failed.\n\n⭐ `changes_nameservers` is the field to render before the customer commits. A zone-owning CDN assigns nameservers **per account**, so choosing your own account means your registrar must be pointed at that account's pair.\n\nAdvisory and read-only; the create itself re-checks everything. Requires `sites.create`.","parameters":[{"name":"product_line","in":"query","required":false,"schema":{"type":"string"},"description":"The line the site will be created on, as the engine spells it (`footprint_free`, `mainstream`). Omitted means unmanaged, which is the permissive answer — the create re-checks, so a wrong guess here costs a refusal and never a bad placement."}],"responses":{"200":{"description":"The destinations available to a new site.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CdnTarget"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/cdn/targets":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"listSiteCdnTargets","tags":["hosting"],"summary":"Where this site's CDN could be served from.","description":"Every destination this site's CDN could move to: Zinn®'s own pool, **one row per CDN account you have connected**, and passthrough (an edge you run yourself).\n\n⛔⛔ **This operation exists because a customer could not see their own accounts at all.** A connected CDN account is a provider-account row scoped to your organisation, and until this endpoint the only route that read that table was a staff one — so a customer who connected two Cloudflare accounts could see neither, and the (now deprecated) `switchSiteCdn`'s body was a boolean that cannot name one of two. The account you connect on the Connections page is listed too, as one `own` row.\n\n⛔ **An unusable target is LISTED, with its reason, never hidden.** *\"My account is not in the list\"* and *\"my account is in the list and says the token was revoked\"* send you to two different places, and only the second is true. `reason` is a machine key so the client renders the sentence in your language.\n\n⭐ `changes_nameservers` is the field to render before the customer clicks. A zone-owning CDN assigns nameservers **per account**, so a move between two accounts on the *same vendor* still changes the delegation your registrar must point at.\n\nAdvisory and read-only: a target listed as available may still fail at swap time because a credential was revoked in between, and the swap says so. Requires `hosting.cdn.manage`.","responses":{"200":{"description":"The destinations available to this site.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CdnTarget"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/cdn/swap":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteCdnSwap","tags":["hosting"],"summary":"The site's most recent CDN move, and what it is waiting for.","description":"The latest CDN move for this site, or `null` if there has never been one — **not a 404**, because \"this site has never been moved\" is a normal state and a 404 could not be told apart from \"no such site\".\n\n⭐ The field to render is `nameservers`. While `status` is `awaiting_delegation` the move is complete on our side and waiting on **your registrar**: both edges serve the site throughout, and nothing is removed until the new nameservers are observed answering. Requires `hosting.cdn.manage`.","responses":{"200":{"description":"The latest swap, or `null`.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"oneOf":[{"$ref":"#/components/schemas/CdnSwap"},{"type":"null"}]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"startSiteCdnSwap","tags":["hosting"],"summary":"Move this site's CDN to a named destination.","description":"Starts a **durable** move of this site's CDN to the destination you name, and answers `202` with a row to poll.\n\n⭐ **The one way a site's CDN moves.** The deprecated `switchSiteCdn` and the staff `rotateSiteCdn` start this same workflow; they differ only in how the destination is named. `switchSiteCdn` takes `{to_own: boolean}`, which cannot name one of several accounts; this takes `{to_kind, to_account_id}`.\n\n⭐⭐ **Asynchronous because of a step no request can hold.** The move only finishes once your registrar points at the destination's nameservers — minutes if the domain is registered with us, days if it is not. The source zone is removed **only after the new nameservers are observed answering**, so there is no moment at which your domain names an edge that is not there. Poll `getSiteCdnSwap`.\n\nEvery step can be undone and every failure leaves the site serving: if the destination refuses the zone, or the credential has been revoked since you connected it, the site carries on being served exactly where it was.\n\nA Footprint-Free site needs `footprint_acknowledged` to move onto one account of your own (owner ruling G-3) — every site on one account can be linked to every other on it, which is the connection that line exists to prevent. Requires `hosting.cdn.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CdnSwapRequest"}}}},"responses":{"202":{"description":"The move has started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CdnSwap"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"delete":{"operationId":"cancelSiteCdnSwap","tags":["hosting"],"summary":"Abandon a CDN move and put the site back.","description":"Rolls a move back and returns the site to the account it came from.\n\n⭐ Exists because a move can wait on your registrar indefinitely, and that is the correct state rather than a failure — both edges serve the site throughout. Nothing rolls it back on a timer, because doing so would move a site that has been served happily from the destination for days. **You** say when.\n\n⛔ Refused once the move has completed: the source zone has gone by then, so there is nothing to put the site back onto. ⛔ Also refused once the domain's nameservers have been changed or the new delegation has been seen (`cancellable` is false): the registry already points at the new zone, and undoing the move would take the site offline. Requires `hosting.cdn.manage`.","responses":{"200":{"description":"The swap after the rollback.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CdnSwap"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/cdn/move-offer":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteCdnMoveOffer","tags":["hosting"],"summary":"The open \"Move it now\" offer for a site suspended on your own CDN account.","description":"When a site is suspended on a CDN account of your own and you have connected another one, we offer to move it there and move nothing until you say so (\"Ask first\", owner ruling 2026-11-09). This answers the open offer, or `null` when there is none.\n\n`available` is re-asked on every read: it turns false (with `reason`) once the offered account has also been suspended or can no longer be used. The offer closes after seven days and once it has been accepted. Requires `hosting.cdn.manage`.","responses":{"200":{"description":"The open offer, or `null`.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"oneOf":[{"$ref":"#/components/schemas/CdnMoveOffer"},{"type":"null"}]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"acceptSiteCdnMoveOffer","tags":["hosting"],"summary":"Move it now — accept the offer and start the move onto your other account.","description":"The click. Opening the e-mailed link moves nothing; this call does, and only for a signed-in member with `hosting.cdn.manage`. `token` is the one from the e-mailed link (`?move_offer=`); the banner's own button sends none.\n\nThe offer is single-use and expires after seven days. A `422` names why in `details[0].code`: `offer_closed` (used, expired or never made), `link_invalid` (a forged token, or one for another site), `target_suspended` (the account we offered is suspended too) or `move_refused` (the move itself would not start). `503` with `unavailable` when the move could not be started right now. Accepted and refused clicks are both audit-logged. Poll `getSiteCdnSwap` for the move.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CdnMoveOfferAccept"}}}},"responses":{"202":{"description":"The move has started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CdnSwap"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/cdn/swap/check":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"checkSiteCdnSwapNameservers","tags":["hosting"],"summary":"Check now whether the domain uses the nameservers a CDN move is waiting for.","description":"\"Check now\" for a move in `awaiting_delegation`. Reads the domain's nameservers as the public internet sees them RIGHT NOW (`live_nameservers`; `null` when the public resolver did not answer, which is \"we could not see\", never \"nothing is set\") against the ones the move needs (`nameservers`). When they match, `delegated` is true and the move carries on at once instead of at its next ten-minute check.\n\nWhen the site has no move waiting on its nameservers (it finished, or never waited), the answer is `waiting: false` and the screen should re-read the move. Requires `hosting.cdn.manage`.","responses":{"200":{"description":"The live delegation against the nameservers the move needs.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CdnSwapCheck"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/cdn/purge":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"post":{"operationId":"purgeSiteCdn","tags":["hosting"],"summary":"Purge a site's CDN cache.","description":"Purges the whole zone for this site. The engine verifies the site owns the domain before purging, because on a pooled CDN account a zone resolves by name alone and an unchecked purge could clear a different tenant's cache — so the hostname is read off the site row and **the request body must be empty**. A body carrying a `domain`, `zone` or `urls` key is a `422`, not a silently ignored field.\n\nA site that is not served through our CDN is a `404`, answered before any vendor call. `Idempotency-Key` is accepted and requires no de-duplication here: purging a zone twice has the same effect as purging it once. Requires `sites.cache.purge`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false}}}},"responses":{"202":{"description":"The purge was accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCachePurgeResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/sites/{siteId}/cdn/settings":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteCdnSettings","tags":["hosting"],"summary":"Read a site's CDN zone settings.","description":"The edge behaviour a customer controls for their own zone: cache level, development mode, Always Online, the CDN-to-origin TLS mode, and Brotli compression. Read live from the provider on every call rather than mirrored, so the answer reflects what is actually in force — development mode in particular expires on the provider's own three-hour timer, and only the provider knows how much of it is left.\n\nA provider with no equivalent vocabulary (a pull-zone CDN such as Bunny or CDN77) answers `200` with `supported: false` and default values, **not** a `404` — the tier and cache-purge controls on the same screen are real on those providers and a `404` would take them down with it.\n\nA site that is not served through our CDN is a `404`, answered before any vendor call. A provider failure is a `503` that says the answer is unknown — never a `404`, which would tell a customer their site is not CDN-fronted because the vendor returned a 500. Requires `sites.view`.","responses":{"200":{"description":"The site's current zone settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCdnSettings"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"},"502":{"$ref":"#/components/responses/CdnZoneNotOnAccount"}}},"put":{"operationId":"updateSiteCdnSettings","tags":["hosting"],"summary":"Change a site's CDN zone settings.","description":"A **merge**: only the fields present in the body are changed and an absent field is left alone — never reset to a default. A client written before a setting existed must not switch it off on every save.\n\nThe body carries settings and nothing else. `additionalProperties: false` is load-bearing rather than tidy: these are pooled CDN accounts holding other customers' zones and a Cloudflare zone resolves **by name alone**, so a body key named `domain` or `zone_id` must be refused rather than silently discarded. The hostname is always read off the site row.\n\n`ssl_mode` deliberately does not accept Cloudflare's `flexible`, which leaves the edge-to-origin leg in plaintext. An empty body is a `422`, not a no-op success. A provider without these controls is a `422` with code `UNSUPPORTED_BY_PROVIDER` — a save that reported success having changed nothing would be worse than a refusal. Requires `hosting.cdn.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCdnSettingsUpdate"}}}},"responses":{"200":{"description":"The settings as read back from the provider after applying them.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCdnSettings"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"},"502":{"$ref":"#/components/responses/CdnZoneNotOnAccount"}}}},"/v1/sites/{siteId}/cdn/security":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteCdnSecurity","tags":["hosting"],"summary":"Read a site's CDN security and bot settings.","description":"How hard the edge is on suspicious traffic, and how it treats AI crawlers: security level, bot fight mode, Cloudflare's AI-bot and crawler controls, Always Use HTTPS, automatic HTTPS rewrites, opportunistic encryption and the minimum TLS version.\n\nSeparate from `/cdn/settings`, which is about caching and the origin TLS leg, because these are a different question with a different blast radius — turning the cache off makes a site slow, while `under_attack` puts an interstitial in front of every visitor and `crawler_protection` can remove a site from search results. They are also different provider APIs behind different token scopes, so a customer's own credential may carry one and not the other.\n\nA provider with no equivalent vocabulary answers `200` with `supported: false` and defaults, never a `404`. Requires `sites.view`.","responses":{"200":{"description":"The zone's current security posture.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCdnSecurity"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"},"502":{"$ref":"#/components/responses/CdnZoneNotOnAccount"}}},"put":{"operationId":"updateSiteCdnSecurity","tags":["hosting"],"summary":"Change a site's CDN security and bot settings.","description":"A **merge**: only the fields present are changed. A full-object write would turn a customer's AI-crawler policy off every time they changed their security level.\n\nThe body carries settings and nothing else — `additionalProperties: false`, for the reason `PUT /v1/sites/{siteId}/cdn/settings` gives: these are pooled CDN accounts and a Cloudflare zone resolves by name alone, so a body key named `domain` or `zone_id` must be refused rather than discarded.\n\nThe result is read back from the provider rather than echoed, because the provider silently ignores a bot control a zone's plan does not include — \"we asked\" and \"it changed\" are different facts. Requires `hosting.cdn.manage`.\n\n**Bot management is a sold entitlement (`protection_tier`).** Turning `bot_fight_mode` on, or setting `ai_bots_protection`/`crawler_protection` to `block` or `managed_challenge`, needs a plan that includes it and otherwise answers a plan refusal naming the tier held and the tier needed.\n\nThree things are deliberately NOT gated. Turning any control **off** is free on every plan — a customer whose plan changed must always be able to reach the floor rather than be stranded with a setting they cannot undo. `allow` is an explicit relaxation, not protection, so it is free too. And `security_level: under_attack` is free on every plan, for ever: it is the emergency DDoS response, and refusing it to a customer under active attack because of their plan is not a product decision this platform will make.\n\n**Bot Fight Mode is opt-in.** The platform never switches it on, and it can challenge automated traffic a site depends on — uptime monitors, payment callbacks and some crawlers. Switching it on for a site the platform itself runs answers `422` before anything reaches the provider.\n\n**Every field is zone-wide.** A site on a shared preview address is served by a zone every other preview site uses, so a write for it answers `422` before anything reaches the provider.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCdnSecurityUpdate"}}}},"responses":{"200":{"description":"The security posture as read back after applying the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCdnSecurity"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"s1014 L04 — `security_level` would be lowered from `under_attack` while the flood guard holds this site under attack (see `flood_hold_until` on the read). Refusal key `refusal.edge.underAttackHeldByFloodGuard`; audited as `site.cdn.security_refused_flood_hold`. Raising the level and every other field still work; the guard restores the zone's own level when it lifts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"},"502":{"$ref":"#/components/responses/CdnZoneNotOnAccount"}}}},"/v1/sites/{siteId}/geo-restriction":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteGeoRestriction","tags":["hosting"],"summary":"Which countries may reach this site.","description":"The site's country rule and what each enforcement layer is doing about it.\n\n**Not under `/cdn/`, deliberately.** A country rule is a *site* control with up to two enforcement points — the CDN edge and the origin server — and a site with no CDN still gets it at the origin. It applies on every product line.\n\n**The edge state is read from the provider, not from our record.** \"We asked for it\" and \"it is set\" are different claims: they diverge when a customer edits the rule in their own CDN dashboard, after a CDN switch, or after a failed apply. Read `edge` and `origin` separately — a rule live at one layer only is a real, partial state, and `enforcing: false` with a `detail` means the layer is not protecting the site whatever `mode` says. Requires `sites.view`.","responses":{"200":{"description":"The country rule, per layer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteGeoRestriction"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"replaceSiteGeoRestriction","tags":["hosting"],"summary":"Restrict this site to chosen countries, or refuse named ones.","description":"**Convergent, and `mode` plus `countries` must be sent together.** The same list means \"only these may enter\" under `allow` and \"only these are refused\" under `block`, so a partial update that changed one field would invert who can reach the site without naming a country.\n\n**The rule is pushed to every layer that can carry it** — the CDN edge where the provider supports it, and the origin. A provider that cannot express the requested direction is reported in `edge.detail` and the rule is never quietly narrowed to fit it. When *no* layer can carry it the call is refused with `422` rather than storing an intent nothing enforces.\n\n**`exempt_search_engines` defaults to `true`, and you usually want it.** A single-country allow-list otherwise blocks Googlebot, which crawls from US addresses, and removes the site from search. It is honoured only where the provider verifies the crawler by forward/reverse DNS; `search_engines_exempt_at_edge` reports whether it is actually in force, which is not the same as whether it was requested.\n\n**This is a customer-visible, revenue-affecting switch** — a wrong country refuses every real visitor to a live site. Clients must confirm before sending, and every call is audit-logged with the acting principal. Requires **both** `hosting.cdn.manage` and `sites.panel_access`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteGeoRestrictionUpdate"}}}},"responses":{"200":{"description":"The rule as read back from every layer after applying it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteGeoRestriction"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/cdn/firewall-rules":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"listSiteCdnFirewallRules","tags":["hosting"],"summary":"List a site's custom edge firewall rules.","description":"The zone's custom block/challenge rules, **in evaluation order**. Rules written in the customer's own provider dashboard are included and flagged `foreign: true`; they are editable here, because it is their account.\n\n`expression` is the provider's own matching syntax, passed through unchanged. A neutral matching language that every adapter half-implemented would be a rule that silently matches nothing. Requires `sites.view`.","responses":{"200":{"description":"The rules currently in force.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCdnFirewallRules"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"},"502":{"$ref":"#/components/responses/CdnZoneNotOnAccount"}}},"put":{"operationId":"replaceSiteCdnFirewallRules","tags":["hosting"],"summary":"Replace a site's custom edge firewall rules.","description":"**Convergent and whole-list.** The body is the complete ordered rule set and the provider is made to match it exactly, including removing what is gone. A client must send back every rule it was shown — `foreign` ones included — because sending a subset deletes the rest.\n\n**Order is the security property, not presentation.** Cloudflare's custom-rules phase is terminating: the first matching rule decides and no later rule runs, so reordering the list changes which rule wins.\n\nRequires `hosting.cdn.manage`. A provider without custom rules is a `422` with code `UNSUPPORTED_BY_PROVIDER`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCdnFirewallRulesUpdate"}}}},"responses":{"200":{"description":"The rules as read back from the provider after applying them.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCdnFirewallRules"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"},"502":{"$ref":"#/components/responses/CdnZoneNotOnAccount"}}}},"/v1/sites/{siteId}/cdn/page-rules":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"listSiteCdnPageRules","tags":["hosting"],"summary":"List the legacy page rules on a site's zone.","description":"Legacy URL-pattern page rules, in priority order. There is deliberately **no create** endpoint: page rules are a retiring provider product and the modern answer to almost everything they did is a cache rule or a redirect rule. A customer must be able to see and retire what they already have, and must not be led into building more of it. Requires `sites.view`.","responses":{"200":{"description":"The zone's page rules.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCdnPageRules"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"},"502":{"$ref":"#/components/responses/CdnZoneNotOnAccount"}}}},"/v1/sites/{siteId}/cdn/page-rules/{ruleId}":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"$ref":"#/components/parameters/CdnRuleId"}],"patch":{"operationId":"setSiteCdnPageRuleEnabled","tags":["hosting"],"summary":"Turn one page rule on or off.","description":"Requires `hosting.cdn.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCdnPageRuleUpdate"}}}},"responses":{"200":{"description":"The rule's new state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCdnPageRuleState"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"},"502":{"$ref":"#/components/responses/CdnZoneNotOnAccount"}}},"delete":{"operationId":"deleteSiteCdnPageRule","tags":["hosting"],"summary":"Remove one page rule.","description":"Requires `hosting.cdn.manage`.","responses":{"204":{"description":"The page rule was removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"},"502":{"$ref":"#/components/responses/CdnZoneNotOnAccount"}}}},"/v1/sites/{siteId}/cdn/analytics":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"days","in":"query","required":false,"description":"How many days to report, clamped to 1–30. Clamped rather than trusted: this is reachable from a screen a customer can refresh, against a provider API whose request budget is shared by every zone on the account.","schema":{"type":"integer","minimum":1,"maximum":30,"default":7}}],"get":{"operationId":"getSiteCdnAnalytics","tags":["hosting"],"summary":"Read edge traffic for a site's CDN zone.","description":"Daily requests, bytes, threats and unique visitors as counted **at the CDN edge**.\n\nThis is not the same measurement as `/v1/sites/{siteId}/cdn/statistics`, and the two will not agree. That endpoint reports the hosting platform's own edge cache for a site on a managed hosting plan; this one reports the Cloudflare zone's. A site may have one, the other, both or neither, and they are counted at different edges — collapsing them into one number would invent a figure that is true of neither. Requires `sites.view`.","responses":{"200":{"description":"Edge traffic for the requested window.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCdnAnalytics"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"},"502":{"$ref":"#/components/responses/CdnZoneNotOnAccount"}}}},"/v1/sites/{siteId}/cdn/tiered-cache":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteCdnTieredCache","tags":["hosting"],"summary":"Read tiered caching and smart routing for a site's zone.","description":"`supported` is a fact about the **driver**; `tiered_cache_editable` is a fact about the **zone's plan**, and they are reported separately because a driver that can write the setting in general still cannot write it for a customer on a free plan — measured, the provider answers `editable: false` there.\n\n`smart_routing` is `null`, never `false`, when the provider refuses to report it at all. `false` would tell a customer that a paid feature they are not buying is simply switched off. Requires `sites.view`.","responses":{"200":{"description":"The zone's tiered-cache state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCdnTieredCache"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"},"502":{"$ref":"#/components/responses/CdnZoneNotOnAccount"}}},"put":{"operationId":"updateSiteCdnTieredCache","tags":["hosting"],"summary":"Turn tiered caching on or off.","description":"Refused **before** the provider is called when the zone's plan does not include it, because the provider's own refusal is a 4xx we cannot phrase usefully and a save button that produced it would look like our bug rather than their plan. Requires `hosting.cdn.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCdnTieredCacheUpdate"}}}},"responses":{"200":{"description":"The state as read back after applying the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCdnTieredCache"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"},"502":{"$ref":"#/components/responses/CdnZoneNotOnAccount"}}}},"/v1/sites/{siteId}/cdn/profile":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteCdnProfile","tags":["hosting"],"summary":"Read a site's recommended CDN profile and where the zone has drifted from it.","description":"Every site is given a recommended edge configuration at provision time — settings plus ordered cache rules — chosen by product line and built entirely from **free** provider features. This reads what the provider currently has and names the difference.\n\n`drifted` lists the knobs whose live value differs from the recommendation, and includes `cache_rules` when a recommended rule is missing at the provider. A read **never** re-applies anything: a setting a customer or operator deliberately changed in the provider's own dashboard is shown as drift rather than silently overwritten, and putting it back is an explicit `POST`.\n\n`settings_supported` and `cache_rules_supported` are separate booleans because a provider may express one and not the other. A site that is not served through our CDN is a `404`. Requires `sites.view`.","responses":{"200":{"description":"The recommended profile, the live values, and the drift between them.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCdnProfile"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"},"502":{"$ref":"#/components/responses/CdnZoneNotOnAccount"}}},"post":{"operationId":"applySiteCdnProfile","tags":["hosting"],"summary":"Re-apply the recommended CDN profile to a site's zone.","description":"Puts the zone back to our recommended settings and cache rules — the \"reset to recommended defaults\" action. Idempotent: applying a profile that is already in force changes nothing at the provider.\n\nThere is **no request body**. These are pooled provider accounts carrying other customers' zones and a zone resolves by name alone, so the hostname is read from the site row and there is no field through which a neighbouring zone could be named.\n\nSettings are applied before cache rules, never the other way round: the rules include a cache-everything rule and the settings include the edge-to-origin TLS mode, so the reverse order would briefly cache pages fetched over a leg whose TLS mode had not yet been corrected. A provider that cannot express part of the profile is reported per capability in the response rather than failing the call. Requires `hosting.cdn.manage`.","responses":{"200":{"description":"The profile state as read back from the provider after applying it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCdnProfile"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"},"502":{"$ref":"#/components/responses/CdnZoneNotOnAccount"}}},"patch":{"operationId":"setSiteCdnProfileManaged","tags":["hosting"],"summary":"Choose whether we keep the recommended CDN profile applied automatically.","description":"Turns the *keep this applied* toggle on or off for one site. With it **off** — the default, and what every existing site has — a setting changed at the provider is reported as drift and only a human puts it back. With it **on**, the `zinn-managed-cdn-profile` sweep re-applies the recommendation on a cadence.\n\nThe default is off on purpose and it matters most for a customer on their **own** provider account: silently correcting a value they changed deliberately, inside an account they pay for, is not something to opt anybody into.\n\nSetting the toggle **does not apply anything**. Arming an automation and writing to a zone are different acts, so a customer switching it on to see what it does has not thereby had their edge rewritten — the sweep picks it up on its next pass, and anyone who wants it now uses the `POST` above. A site that is not served through our CDN is a `404`. Requires `hosting.cdn.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["managed"],"properties":{"managed":{"type":"boolean","description":"`true` to have us keep the recommended profile applied; `false` to go back to reporting drift and changing nothing."}}}}}},"responses":{"200":{"description":"The profile state, including the new value of `managed`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCdnProfile"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"},"502":{"$ref":"#/components/responses/CdnZoneNotOnAccount"}}}},"/v1/sites/{siteId}/content":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteContentState","tags":["hosting"],"summary":"Whether anything has been published to a site yet.","description":"`empty` when the site has nothing to serve — on our own servers, no `index.php`, `index.html` or `index.htm` in its document root; on an edge host, no deployment that went live. `present` when it has content, and `unknown` when the server could not be asked, which a client must never render as empty. Content uploaded by FTP, SSH or an import counts, because the server is asked rather than the deploy history. An empty site's own domain serves a holding page to visitors until something is published. Not polled: the answer is reused for two minutes. Requires `sites.view`.","responses":{"200":{"description":"The site's content state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteContentState"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/deploy":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteDeploy","tags":["hosting"],"summary":"Get a site's deploy target and status.","description":"A site that has never been deployed reports status `idle` with null details — null means \"nothing to show\", never zero or an epoch. This is polled while a deploy is in flight, so it is a cheap database read and never calls a build provider. Requires `sites.view`.","responses":{"200":{"description":"The site's deploy state.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteDeploy"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"deploySite","tags":["hosting"],"summary":"Deploy or redeploy a site.","description":"Starts a durable deploy workflow and returns immediately with the new in-flight state. The target is derived from the site's stack and its connected accounts; there is no target to choose. A site with a deploy already running returns `DEPLOY_IN_PROGRESS`, and one with no usable target returns `DEPLOY_TARGET_UNAVAILABLE`. Requires `hosting.deploy.manage`.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false}}}},"responses":{"202":{"description":"The deploy was accepted; the complete new deploy state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteDeploy"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/domain-pointing":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteDomainPointing","tags":["hosting"],"summary":"Does this site's domain actually reach us?","description":"The measured answer, composed from the domain's public NS and A/AAAA records, a docroot nonce fetched through the public name, and whether we host a site on that name at all — never from a flag anybody set. Carries the exact next step for the customer and what to set where. A site we have not measured yet answers `unknown` with a null `measured_at` rather than a 404: \"we have not looked\" is a real answer and must not read as \"fine\". Requires `sites.view`.","responses":{"200":{"description":"The measured pointing state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteDomainPointing"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/domain-pointing/check":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"checkSiteDomainPointing","tags":["hosting"],"summary":"Check the site's own domain now (DNS, nameservers, SSL).","description":"The live DNS/nameserver check behind the site page's \"Check now\", the MCP tool `site_domain_check`, the dashboard assistant and the support-ticket AI — one implementation. Reads the public DNS now (at most one live reading per 30 seconds per domain; inside that window it answers from the last reading), restarts the fast check ladder, marks the site live on its own domain the moment DNS reaches us, and looks up the registrar and the nameservers the registry holds. Changes nothing the customer owns. Requires `sites.view`.","responses":{"200":{"description":"The pointing state, progress and diagnosis after the check.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteDomainPointing"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/edge-domains":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"listSiteEdgeDomains","tags":["hosting"],"summary":"The custom domains bound to this site's deploy target.","description":"Every hostname the site serves at its edge host, with the exact DNS records it needs, which of the three DNS tiers it landed on, and when we last saw those records actually resolve from a public resolver. A site with no edge-host project returns an empty list rather than a 404 — that is an ordinary state (every fleet site is in it) and the dashboard renders it as the add-a-domain form. Requires `sites.view`.","responses":{"200":{"description":"The bound custom domains.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SiteCustomDomain"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"bindSiteEdgeDomain","tags":["hosting"],"summary":"Point a domain at this site's deploy target.","description":"Attaches the hostname at the provider and, unless `write_dns` is false, publishes its DNS records in the same call — on the customer's own connected DNS account where they have one, otherwise on ours. A DNS failure does not fail the bind: the binding at the provider has already happened, and reporting failure would leave the customer retrying into an \"already bound\" error. The DNS outcome is on the returned row instead. Requires `hosting.deploy.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCustomDomainWrite"}}}},"responses":{"201":{"description":"The bound domain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCustomDomain"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/edge-domains/{hostname}":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"hostname","in":"path","required":true,"description":"The bound hostname, lower-cased and without a trailing dot.","schema":{"type":"string","maxLength":253}}],"delete":{"operationId":"unbindSiteEdgeDomain","tags":["hosting"],"summary":"Stop serving this hostname from the deploy target.","description":"Detaches the hostname at the provider and forgets it here. The DNS records are deliberately left in place: they are in the customer's zone, and a name that has stopped serving is a fixable state while a record we silently deleted is not. Requires `hosting.deploy.manage`.","responses":{"204":{"description":"Unbound."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/edge-domains/{hostname}/dns":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"hostname","in":"path","required":true,"description":"The bound hostname, lower-cased and without a trailing dot.","schema":{"type":"string","maxLength":253}}],"get":{"operationId":"checkSiteEdgeDomainDns","tags":["hosting"],"summary":"What this domain actually resolves to right now.","description":"Resolves every wanted record from a public resolver and reports what came back. Writes no DNS. `resolves` and each check's `observed` are three-valued on purpose — `null` means the resolver did not answer, which is *unknown* and not *no*; rendering it as a failure puts a red mark on a working domain during a resolver hiccup. Requires `sites.view`.","responses":{"200":{"description":"The wanted records and what resolves.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCustomDomainDns"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"publishSiteEdgeDomainDns","tags":["hosting"],"summary":"Publish this domain's DNS records for the customer.","description":"Writes the records and then resolves them, so the answer is what the internet says rather than what we did. Three tiers in order — the customer's own connected DNS provider, then our nameservers with the zone pre-built, then the records to publish by hand — and the tier that was actually used comes back as `mode`. In `nameservers` mode the `nameservers` array is the one thing left for the customer to do. Requires `hosting.deploy.manage`.","responses":{"200":{"description":"What was published, and what resolves.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCustomDomainDns"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/repo":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteRepo","tags":["hosting"],"summary":"Get the repository a site deploys from.","description":"A 404 means no repository is connected, which is an ordinary state the dashboard renders as the connect form — deliberately not an empty object, because a payload of blanks cannot be told apart from a failed load. The response carries no secret: the webhook secret is derived from the connection id, never stored. Requires `sites.view`.","responses":{"200":{"description":"The connected repository.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteRepo"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setSiteRepo","tags":["hosting"],"summary":"Connect (or re-connect) a repository to a site.","description":"Confirms the repository exists on the connected account, stores the connection, and creates or updates the provider-side push webhook — and, when `build_mode` is `ci`, commits the Zinn® build workflow to the repository. The provider work happens before the row is reported as connected, so a hook that could not be created never leaves a row claiming it was. Requires `hosting.deploy.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteRepoWrite"}}}},"responses":{"200":{"description":"The connected repository.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteRepo"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"deleteSiteRepo","tags":["hosting"],"summary":"Disconnect the repository and remove its webhook.","description":"Removes the provider-side hook first, then the connection. A provider that cannot be reached does not block the disconnect — the failure is logged rather than trapping the customer during the outage that made them want to disconnect. Requires `hosting.deploy.manage`.","responses":{"204":{"description":"Disconnected."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/repo/sync":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteRepoSync","tags":["hosting"],"summary":"Two-way sync settings, state and recent runs for a site.","description":"Whether this site's own files are committed back to its repository, where the sync currently stands, and the last runs. `available` is false when the customer has not connected their own account — two-way sync is free but only ever writes to a repository on an account the customer owns, so a pooled account of ours is never enough. `state` of `conflict` or `adopt` means the sync is HELD, waiting for the customer to choose; it is not an error and it will not clear itself. Requires `sites.view`.","responses":{"200":{"description":"The site's two-way sync.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteRepoSync"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setSiteRepoSync","tags":["hosting"],"summary":"Turn two-way sync on or off for a site.","description":"Free, and refused with 422 unless the customer has connected their own GitHub account. Turning it on does not push anything by itself — the first run is either the scheduled sweep or an explicit run. Requires `hosting.deploy.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteRepoSyncWrite"}}}},"responses":{"200":{"description":"The updated two-way sync.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteRepoSync"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/repo/sync/run":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"runSiteRepoSync","tags":["hosting"],"summary":"Sync this site with its repository now.","description":"Commits whatever has changed in the site's files and pushes it to the connected branch. A 200 whose `state` is `conflict` or `adopt` is a successful call reporting a HELD sync — the repository moved since we last agreed with it, so nothing was pushed and nothing was overwritten on either side. Never force-pushes and never merges. Requires `hosting.deploy.manage`.","responses":{"200":{"description":"What the run did — including a run that held.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteRepoSync"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/repo/sync/resolve":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"resolveSiteRepoSync","tags":["hosting"],"summary":"Clear a held sync by choosing which side wins.","description":"`keep: site` commits this site's files on top of the repository's current tip, so the other commits stay in the history rather than being erased. `keep: repository` applies the repository to the site, discarding the unsynced changes on our side — which is destructive, and is the only path that may overwrite them. There is deliberately no merge option: a platform neither party asked to arbitrate should not produce a file that neither of them wrote. Requires `hosting.deploy.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteRepoSyncResolve"}}}},"responses":{"200":{"description":"The sync after the choice was applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteRepoSync"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/repo/branches":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"listSiteRepoBranches","tags":["hosting"],"summary":"List the connected repository's branches.","description":"The only read on this surface that calls the provider, which is why it is its own route rather than a field on the repository: the panel loads that one on every visit, and an un-cached vendor round-trip does not belong on a screen-open path. Requires `hosting.deploy.manage`.","responses":{"200":{"description":"The repository's branches.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RepoBranch"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/deployments":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"listSiteDeployments","tags":["hosting"],"summary":"A site's deploy history, most recent first.","description":"Bounded to the 50 most recent. The build log is deliberately absent here and present on the single-deployment read — a history of twenty deploys carrying twenty build logs is a response nobody asked for on a screen that polls. Requires `sites.view`.","responses":{"200":{"description":"The deploy history.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SiteDeployment"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/deployments/{deploymentId}":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"$ref":"#/components/parameters/DeploymentId"}],"get":{"operationId":"getSiteDeployment","tags":["hosting"],"summary":"One deploy, with its build log.","description":"The log is written line by line as the build runs rather than at the end, so it is readable while a deploy is in flight and present on one that hangs. Requires `sites.view`.","responses":{"200":{"description":"The deployment and its log.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteDeploymentDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/deployments/{deploymentId}/redeploy":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"$ref":"#/components/parameters/DeploymentId"}],"post":{"operationId":"redeploySiteDeployment","tags":["hosting"],"summary":"Roll back by re-publishing an earlier deploy's commit.","description":"Rollback is a forward deploy of the recorded commit, not a provider-side pointer move — a provider rollback promotes a deployment that provider still holds, so it silently does nothing once that has expired, behaves differently on each backend, and leaves our history naming a commit the site is not on. A deployment with no recorded commit returns `UNPROCESSABLE_ENTITY`. Requires `hosting.deploy.manage`.","responses":{"202":{"description":"The new deployment, queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteDeploymentDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/build-env":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteBuildEnv","tags":["hosting"],"summary":"The build variable NAMES a site holds — never their values.","description":"A build variable is routinely an API key, so there is deliberately no endpoint anywhere in this API that reads one back. This returns the names, which is what a customer needs to see what is set and replace or remove it. The values live in Vault, per site. Requires `sites.view`.\n\nA site that has never had variables answers `200` with an empty list — that is not an error. A secret store that cannot be READ answers `503`: the two are deliberately distinguishable, because a store we cannot reach reported as \"no variables\" is a build that silently ships without its keys.","responses":{"200":{"description":"The variable names.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBuildEnv"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"put":{"operationId":"setSiteBuildEnv","tags":["hosting"],"summary":"Replace a site's whole build environment.","description":"Replaces rather than merges, because that is the only shape in which DELETING a variable is expressible — merge semantics would make a rotated-out key undeletable, and it would keep reaching the customer's builds from a screen that no longer lists it. An empty `variables` object clears them all. Names must be POSIX environment-variable syntax and may not start with a prefix the build platform owns (`CF_PAGES`, `GITHUB_`). Requires `hosting.deploy.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBuildEnvWrite"}}}},"responses":{"200":{"description":"The variable names now stored, read back from the store.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBuildEnv"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/deployments/{deploymentId}/build-log":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"$ref":"#/components/parameters/DeploymentId"}],"get":{"operationId":"getSiteDeploymentBuildLog","tags":["hosting"],"summary":"The hosting provider's own build log for one deploy.","description":"Distinct from the `log` on `GET /deployments/{deploymentId}`, which is the platform's own five steps and is the same five whether a build succeeded or failed. When a build fails this is the only text that says WHY. Tail it with `after` while `complete` is false; `after` is a line offset so a live tail is incremental rather than re-fetching a growing log. A provider that publishes no build log, or a deploy that rebuilt nothing, returns `UNPROCESSABLE_ENTITY` with the reason — never an empty log, which would read as \"your build printed nothing\". Requires `sites.view`.","parameters":[{"name":"after","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0},"description":"Skip this many lines — the count already rendered."}],"responses":{"200":{"description":"A page of the provider's build log.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuildLog"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/previews":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"createSitePreview","tags":["hosting"],"summary":"Build a branch as a preview, without touching the live site.","description":"A preview NEVER binds the site's hostname: it is reachable at the provider's own per-deployment URL and nowhere else, which is the whole promise of a preview. Previewing the branch the site already serves is refused rather than quietly promoted to a production deploy. Requires `hosting.deploy.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePreviewWrite"}}}},"responses":{"202":{"description":"The preview deployment, queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteDeploymentDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/app/releases":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"listSiteAppReleases","tags":["hosting"],"summary":"The application releases on the server, newest first, with the live one marked.","description":"A Node.js, Python or Ruby site on our own servers deploys from Git as immutable releases: each deploy installs the commit into its own directory, installs its dependencies and runs the build there, and only then switches the live release. The last five are kept for instant rollback. Read from the server that runs the site, so a release pruned there is never offered. A release serving a branch preview carries `preview_id` and the branch it came from. Requires `sites.view`.","responses":{"200":{"description":"The releases.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppReleaseList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/app/releases/{release}/activate":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"release","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-z][0-9a-z-]{5,63}$"}}],"post":{"operationId":"activateSiteAppRelease","tags":["hosting"],"summary":"Switch the live application to a release already on the server — an instant rollback.","description":"No fetch, no dependency install and no build: the release's directory is already complete, so this moves the live link and restarts the application. A release no longer on the server answers `503` with a sentence saying so; redeploy that commit instead. Requires `hosting.deploy.manage`.","responses":{"200":{"description":"What was switched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppReleaseAction"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/app/restart":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"restartSiteApp","tags":["hosting"],"summary":"Restart the site's application processes.","description":"The web server starts a fresh process on the next request, reading the current release and environment. Scoped to this site's own account, so no other site on the server is affected. Requires `hosting.deploy.manage`.","responses":{"204":{"description":"Restarted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/app/previews/{previewId}":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"previewId","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{8}$"}}],"delete":{"operationId":"deleteSiteAppPreview","tags":["hosting"],"summary":"Take a branch preview down and withdraw its address.","description":"Removes the preview's virtual host and its address record. The release it served is pruned with the site's other old releases. Requires `hosting.deploy.manage`.","responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/backups":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteBackups","tags":["hosting"],"summary":"List a site's backups and what its plan grants.","description":"A cheap database read, polled while a backup is in flight, so it never calls the hosting adapter or object storage. `offsite_enabled` is reported deliberately: when it is false every backup lives on the same host as the site, so a host loss takes both — the customer is entitled to know that before they need a restore. Requires `sites.view`.","responses":{"200":{"description":"The site's backups and its plan's backup grants.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBackupState"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createSiteBackup","tags":["hosting"],"summary":"Take an on-demand backup of a site.","description":"Starts a durable backup workflow and returns immediately with the new in-flight state, never a bare acknowledgement. Gated on the `on_demand_backups` **entitlement** as well as the permission: a plan that does not include it gets `PLAN_REQUIRED` (422, an upgrade prompt), not a 403. A site with a backup already running returns 409. Requires `hosting.backup.manage`.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false}}}},"responses":{"202":{"description":"The backup was accepted; the complete new backup state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBackupState"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/backups/{backupId}/download":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"$ref":"#/components/parameters/BackupId"}],"post":{"operationId":"downloadSiteBackup","tags":["hosting"],"summary":"Mint a time-limited download URL for one of a site's backups.","description":"Returns a presigned URL the customer's browser fetches **directly from object storage**; the archive never passes through the control plane. A site archive is measured in gigabytes, so proxying it would make the customer's site size our memory ceiling and hold a request thread for the length of the transfer. ⛔ **`POST`, despite reading nothing.** The response body is a bearer credential for the whole site — database included — so a `GET` would invite it into browser history, proxy logs and shared caches, and the audit row this writes would be created by every prefetch. The grant expires; take a new one rather than storing it. A backup that never produced a stored archive is `422` (`backup_not_downloadable`) rather than a signature over a key that is not there, which object storage would reject seconds later as an opaque `404`. Requires `hosting.backup.export` — or `hosting.backup.manage`, which every holder of the old gate still has — and never `sites.view`: reading a tenant's database out is never a viewer's. A per-site *editor* holds `hosting.backup.export`, which is how `zinnector pull` brings the site down for local development — files **and** database — without being able to restore. The `site.backup.exported` audit row records `has_database` (three states; `null` is *not recorded*, never *no*) and whether the caller holds the site through a per-site grant, so a site's owner can answer *\"did the developer I shared this with take my database?\"* from their own audit log rather than by asking.","responses":{"200":{"description":"A presigned grant for the backup archive.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BackupDownloadGrant"}}}},"202":{"description":"The backup is an incremental and its complete archive is being assembled from the chain (docs/349 §8) — an incremental's own object holds only that night's changes, so it is never handed out. Ask again after `retry_after_seconds`; the answer becomes `200` with a grant over the complete archive. Nothing is charged and the request is safe to repeat: a second call joins the build already running.","headers":{"Retry-After":{"description":"Seconds to wait before asking again.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BackupDownloadPreparing"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/backups/restore":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"restoreSiteBackup","tags":["hosting"],"summary":"Restore a site from one of its backups.","description":"⛔ **Destructive.** This overwrites the site's live database and files with the contents of the named backup. Its own path rather than a verb on the collection, so it can never be reached by varying the body of the endpoint that *takes* backups. The backup must belong to this site and must have completed successfully; anything else is 422. Requires `hosting.backup.manage`.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteRestoreRequest"}}}},"responses":{"202":{"description":"The restore was accepted; the complete new backup state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBackupState"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/backups/transfer-in":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"transferSiteBackupIn","tags":["hosting"],"summary":"Move an externally hosted site onto Zinn® hosting from a backup we hold.","description":"⛔ **Destructive.** Restores a backup taken from a site hosted somewhere else onto `siteId`, overwriting that site's live database and files. This is what makes an external-site backup subscription a migration path: because we already hold the archive, moving onto our hosting is a restore rather than a migration.\n\nBoth sites must belong to the same organisation, `source_site_id` must be a site we do **not** host, `siteId` must be an active site we do, and the backup must be a completed full backup. Anything else is 422. Requires `hosting.backup.manage` on the destination.\n\n⭐ Nothing is sent to the origin host: it is not contacted, nothing there is deleted, and its backup connection keeps running. Disconnecting it is a separate, customer-initiated act, so the original stays a working fallback until the customer is happy with the copy.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteTransferInRequest"}}}},"responses":{"202":{"description":"The transfer was accepted; the destination's backup state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBackupState"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/offsite-destinations":{"get":{"operationId":"listOffsiteDestinations","tags":["hosting"],"summary":"Places this organisation lets us send backups to.","description":"S3-compatible buckets and SFTP servers the customer owns. Never returns a credential or an encryption key. `sites_using` counts the sites whose offsite copies go here. Gated on `sites.view`.","parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The destinations.","content":{"application/json":{"schema":{"type":"object","required":["items","total"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/OffsiteDestination"}},"total":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createOffsiteDestination","tags":["hosting"],"summary":"Add a place to send backups to, after proving we can write, read and delete there.","description":"The destination is saved only after a real round trip: a small test file is written, read back byte for byte and deleted. For SFTP the server's host key is read without authenticating and pinned; every later connection must present it. Addresses must be on the public internet and S3 endpoints must be `https://`. Credentials are write-only and go straight to our secret store with a fresh encryption key; every archive is encrypted (AES-256-CTR with HMAC-SHA256) before it leaves us. Refusals are `422` with a machine code in `details[0].code`. Requires `hosting.backup.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OffsiteDestinationWrite"}}}},"responses":{"201":{"description":"The destination, proven working.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OffsiteDestination"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/offsite-destinations/{destinationId}":{"parameters":[{"name":"destinationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"delete":{"operationId":"removeOffsiteDestination","tags":["hosting"],"summary":"Remove a destination and forget its credentials and encryption key.","description":"Refused with `IN_USE` while a site still sends backups there. Copies already written stay in the customer's storage; without the key they saved from `POST …/key` they cannot be opened. Requires `hosting.backup.manage`.","responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/offsite-destinations/{destinationId}/test":{"parameters":[{"name":"destinationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"testOffsiteDestination","tags":["hosting"],"summary":"Prove the round trip again and record the answer.","description":"Writes, reads back and deletes a test file. Always `200`; the verdict is in `status` and `last_check_code`. Requires `hosting.backup.manage`.","responses":{"200":{"description":"The destination with its fresh verdict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OffsiteDestination"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/offsite-destinations/{destinationId}/key":{"parameters":[{"name":"destinationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"revealOffsiteDestinationKey","tags":["hosting"],"summary":"Show the encryption key, so a copy can be opened without us.","description":"`POST` so the key never sits in a browser history or a proxy log; audited every time. With the IV from the `.json` sidecar beside each archive: `openssl enc -d -aes-256-ctr -K <key_hex> -iv <iv> -in site.tar.gz.enc -out site.tar.gz`. Requires `hosting.backup.manage`.","responses":{"200":{"description":"The key.","content":{"application/json":{"schema":{"type":"object","required":["algorithm","key_hex"],"properties":{"algorithm":{"type":"string","enum":["aes-256-ctr"]},"key_hex":{"type":"string","pattern":"^[0-9a-f]{64}$"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/sites/{siteId}/offsite":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteOffsite","tags":["hosting"],"summary":"Where this site's backups are copied offsite, and every copy made.","description":"`entitled` says whether the paid add-on (`extra_code`) is active for this site. Copies reach the destination within about ten minutes of a backup finishing. Gated on `sites.view`.","responses":{"200":{"description":"The site's offsite state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteOffsite"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"operationId":"setSiteOffsite","tags":["hosting"],"summary":"Send this site's backups to a destination.","description":"Requires the add-on for this site and an account in good standing. Switching on copies the newest restorable backup (and any archives it depends on) at once, then every later backup. Changing destination drops copies still waiting for the old one; stored copies stay. Requires `hosting.backup.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["destination_id","retention_days"],"properties":{"destination_id":{"type":"string","format":"uuid"},"retention_days":{"type":"integer","enum":[7,30,90,180,365]},"enabled":{"type":"boolean","default":true}}}}}},"responses":{"200":{"description":"The site's offsite state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteOffsite"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"removeSiteOffsite","tags":["hosting"],"summary":"Stop copying this site's backups offsite.","description":"Copies already written stay in the customer's storage and remain listed. Requires `hosting.backup.manage`.","responses":{"200":{"description":"The site's offsite state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteOffsite"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/sites/{siteId}/offsite/copies/{copyId}/retry":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"copyId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"retrySiteOffsiteCopy","tags":["hosting"],"summary":"Try a failed copy again.","description":"Resets a `failed` copy so the next sweep retries it. Requires `hosting.backup.manage`.","responses":{"202":{"description":"Queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteOffsite"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/sites/{siteId}/offsite/restore":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"restoreSiteFromOffsite","tags":["hosting"],"summary":"Overwrite the site from a copy held in the customer's own storage.","description":"Destructive: the site's current files and database are replaced. Each archive is decrypted and its HMAC verified before the restore can use a byte of it; a copy altered at the destination is refused. Incremental copies restore with every archive they depend on. Requires `hosting.backup.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["copy_id"],"properties":{"copy_id":{"type":"string","format":"uuid"}}}}}},"responses":{"202":{"description":"The restore has started.","content":{"application/json":{"schema":{"type":"object","required":["workflow_id","state"],"properties":{"workflow_id":{"type":"string"},"state":{"$ref":"#/components/schemas/SiteOffsite"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/external-backup":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteExternalBackupConnection","tags":["hosting"],"summary":"How we reach an externally hosted site to back it up.","description":"The configured backup channel for a site hosted somewhere else, or an object with `configured: false` when nobody has set one up yet. A cheap database read; it never touches the customer's server.\n\nNever returns a credential. `credential_present` says whether one is stored in our secret store; the key or password itself cannot be read back through any endpoint once it has been saved.\n\n`422` when the site is one we host — its backups are already managed and this surface would be a second, contradictory answer to *\"is this site backed up?\"*. Gated on `sites.view`.","responses":{"200":{"description":"The site's external-backup connection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalBackupConnection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"put":{"operationId":"connectSiteExternalBackup","tags":["hosting"],"summary":"Connect an externally hosted site so we can back it up.","description":"Configures one of two channels.\n\n`connector` — the customer installs the Zinn® Connector plugin and pairs it. Nothing else is needed and we never hold a server credential. The plugin makes outbound calls only; it opens no route on their site. Backup only: it cannot restore.\n\n`ssh` — the customer gives us a host, a username, the document root and a private key. This channel can also **push a site back**, including when the site itself will not load, which is the only way a one-click restore can be honest.\n\n`ssh_secret` is write-only. It goes straight to our secret store and only a pointer to it is kept; it is never returned by this or any other endpoint. Connecting a `connector` site mints a fresh plugin token and returns it **once** as `job_token`, for the customer to paste into the plugin; re-connecting invalidates whatever the previous install held.\n\nRequires `hosting.backup.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectExternalBackupRequest"}}}},"responses":{"200":{"description":"The connection as it now stands.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalBackupConnection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"disconnectSiteExternalBackup","tags":["hosting"],"summary":"Remove our access to an externally hosted site.","description":"Deletes the connection and forgets the stored credential.\n\nThe backups themselves are **not** deleted. A customer disconnecting us may be doing it precisely so they can restore elsewhere, and their existing restore points are theirs — they expire on the normal retention schedule and are all still downloadable.\n\nRequires `hosting.backup.manage`.","responses":{"200":{"description":"The now-unconfigured connection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalBackupConnection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/site-blueprints":{"get":{"operationId":"getSiteBlueprints","tags":["hosting"],"summary":"List your site blueprints.","description":"The management screen's data. A cheap database read, polled while a capture is in flight, so it never calls object storage — `has_screenshot` reports whether a picture exists and each tile asks for its own short-lived URL. Filter by `stack_type` to get exactly the blueprints that can be deployed onto a site of that stack; that is the same field the engine refuses a mismatch on, so a picker built on it cannot drift from the guard. Requires `sites.view`.","parameters":[{"name":"stack_type","in":"query","required":false,"description":"Only blueprints captured from a site of this stack. The compatibility axis — a WordPress blueprint can only be deployed onto WordPress.","schema":{"$ref":"#/components/schemas/StackType"}},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"ordering","in":"query","required":false,"description":"Sort key, optionally `-`-prefixed for descending. One of `created` or `name`; defaults to `-created` (newest first). An unrecognised key is a `422`, never a silent fall back to the default.","schema":{"type":"string","maxLength":32}}],"responses":{"200":{"description":"A page of site blueprints.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBlueprintPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createSiteBlueprint","tags":["hosting"],"summary":"Capture a built site as a reusable blueprint.","description":"Starts a durable capture — a backup of the named site, plus a screenshot of its home page — and answers `202` with the new row in `capturing`. Poll the list.\n\nTwo shapes. Omit `backup_id` and a **new backup is taken**, which spends one of the site's three per-rolling-day on-demand slots and is refused with a `429` naming when the next opens. Give `backup_id` and an **existing stored backup is adopted**: the blueprint is `ready` immediately and no allowance is spent, which is what a customer wants when this morning's site is broken and last night's is the template.\n\nThe site must be `active` — a template of a half-built or failed site is not a thing anybody means to make — and its hosting must be able to produce a backup at all. Requires `sites.blueprint.manage`.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBlueprintCreate"}}}},"responses":{"202":{"description":"The capture was accepted; the new blueprint row.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBlueprint"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/site-blueprints/{siteBlueprintId}":{"parameters":[{"$ref":"#/components/parameters/SiteBlueprintId"}],"get":{"operationId":"getSiteBlueprint","tags":["hosting"],"summary":"Read one site blueprint.","description":"Requires `sites.view`.","responses":{"200":{"description":"The blueprint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBlueprint"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateSiteBlueprint","tags":["hosting"],"summary":"Rename a blueprint, or edit its notes.","description":"Both fields are optional and **omitted is not the same as empty**: omitting `notes` leaves the existing note alone, sending `\"\"` clears it. Collapsing the two would make it impossible to clear a note, or would wipe one on every rename. Requires `sites.blueprint.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBlueprintUpdate"}}}},"responses":{"200":{"description":"The updated blueprint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBlueprint"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"deleteSiteBlueprint","tags":["hosting"],"summary":"Delete a site blueprint.","description":"Removes the template and its screenshot. ⛔ **The backup is not deleted** — it is one of the customer's restore points and always was; the blueprint only held it open past the org's ordinary retention, and deleting the blueprint releases that pin. A blueprint that sites have been built from is refused with a `422`: the deployment rows are the record of what a live site was made from. Requires `sites.blueprint.manage`.","responses":{"204":{"description":"The blueprint was deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/site-blueprints/{siteBlueprintId}/title-suggestion":{"parameters":[{"$ref":"#/components/parameters/SiteBlueprintId"}],"get":{"operationId":"getSiteBlueprintTitleSuggestion","tags":["hosting"],"summary":"A fresh site title and tagline for a copy of this blueprint.","description":"⛔⛔ A copy never keeps the original site's title or tagline: on a footprint-free network one title across many sites links them. The deploy form and the create-site wizard pre-fill from this, and the customer can change both before deploying. The title is one no copy in the blueprint's account already has. A read; nothing is reserved, so send the values back in the deploy (`site_title`, `tagline`). Leaving them out of the deploy has the same effect: the copy is given a fresh pair. Requires `sites.view`.","responses":{"200":{"description":"A suggested title and tagline.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBlueprintTitleSuggestion"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/site-blueprints/{siteBlueprintId}/screenshot":{"parameters":[{"$ref":"#/components/parameters/SiteBlueprintId"}],"post":{"operationId":"getSiteBlueprintScreenshot","tags":["hosting"],"summary":"Mint a time-limited URL for a blueprint's screenshot.","description":"Returns a presigned URL the browser fetches directly from object storage. ⛔ **`POST`, despite reading nothing** — the same rule `downloadSiteBackup` follows: the response body is a signed credential for customer content (a picture of their site, which can show unlaunched branding or a page behind a login), so a `GET` would invite it into browser history, proxy logs and shared caches. The grant expires in ten minutes; take a new one rather than storing it. A blueprint with no screenshot is a `422`, not a `404` — the blueprint exists, the picture does not. Requires `sites.view`.","responses":{"200":{"description":"A presigned grant for the screenshot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBlueprintScreenshotGrant"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/clone":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"cloneSite","tags":["hosting"],"summary":"Copy this site onto a new domain, as a new site.","description":"Creates a new site on the same plan, product line, stack and region as this one, takes a copy of this site's files and database, and restores that copy onto the new site once it has finished being built — then points the copy's stored web addresses (a WordPress database names its own URLs) at the new domain. This site is only read, never changed.\n\n⭐ A clone is a **site blueprint** capture and a blueprint deploy in one call, so it is durable end to end and every guard those enforce applies here. The copy is kept as a blueprint named after both domains, and progress is read from `GET /v1/sites/{siteId}/clones`.\n\nThe copy's backup does **not** spend the on-demand backup allowance: a clone is paid for with a site slot, which is checked exactly as `POST /v1/sites` checks it. A refusal from that check (no slot left, the domain taken) creates nothing.\n\nRefusals carry a machine code in `error.details[0].code`: `site_not_active`, `app_copy_unavailable` (a stack other than WordPress/WooCommerce, temporarily: its config would still name this site's database on the copy) and `clone_not_supported` (422), `backup_in_flight` (409).\n\n⛔ *\"As staging\"* is a different product — a private copy on the SAME site that publishes back — and lives at `/v1/sites/{siteId}/wordpress/staging`.\n\nRequires **both** `sites.create` and `sites.blueprint.manage`: it spends a site slot and it reads this site's whole content into a copy.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCloneRequest"}}}},"responses":{"202":{"description":"The new site was created and the copy is under way.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCloneAccepted"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/clones":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"listSiteClones","tags":["hosting"],"summary":"Every copy made from this site, newest first.","description":"One row per copy: the new site, the step it is on, and why it failed if it did. Polled while a copy is in flight. A copy is any site built from a blueprint of this site, so a blueprint deployed by hand appears here too. Requires `sites.view`.","responses":{"200":{"description":"The copies made from this site (at most 50).","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SiteClone"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/clones/{cloneId}/retry":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"cloneId","in":"path","required":true,"description":"The `id` of a row from `listSiteClones`.","schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"retrySiteClone","tags":["hosting"],"summary":"Finish a copy that failed, onto the same new site.","description":"Recovery goes to the step that failed: when the copy of this site was never made a new one is taken, and when it was it is reused. Either way it is restored onto the SAME new site, so a half-built site never has to be deleted to try again. `409` when the copy has not failed; `422` when its new site has been deleted. Requires `hosting.backup.manage`, because it overwrites the new site's content.","responses":{"202":{"description":"The retry is under way; its row.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteClone"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/site-blueprint-deploy":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteBlueprintDeployments","tags":["hosting"],"summary":"What has been deployed onto this site from a blueprint.","description":"The site panel's history, newest first, capped at twenty. A cheap database read, polled while one is in flight. Requires `sites.view`.","responses":{"200":{"description":"The site's blueprint deployments.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SiteBlueprintDeployment"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"deployFromSiteBlueprint","tags":["hosting"],"summary":"Replace a site's content with a blueprint's.","description":"⛔ **Destructive.** This overwrites the site's live database and files with the contents of the named blueprint, then rewrites the restored content's stored web addresses to this site's domain (a WordPress database names its own URLs, so without that step the new site would redirect its visitors to the old one).\n\nIts own path on the **site**, beside `backups/restore`, rather than a verb on the blueprint — the destruction happens here, so it is gated on `hosting.backup.manage` and cannot be reached by varying the body of anything gentler.\n\n⛔ A blueprint captured from a different **stack** is refused with a `422` (`stack_mismatch`) — WordPress can only be deployed onto WordPress. So is one from a different **hosting platform** (`platform_mismatch`), whose archive our adapter cannot restore here. A blueprint belonging to a **different account** is refused with `org_mismatch`, even when your token can reach both: hierarchical tenancy means a reseller's key spans every client organisation, and a blueprint is that site's whole database — it never crosses between accounts. A blueprint that is still being captured is `blueprint_not_ready`. A deploy already in flight on this site is a `409`. ⛔ A blueprint of any stack other than WordPress or WooCommerce deployed onto a site OTHER than the one it was captured from is refused with `app_copy_unavailable` (temporarily): those apps keep their database settings in a config file the archive carries, and the copy would land naming the source site's database. A redeploy onto the source site itself is unaffected.\n\nThe refusal is a **machine code**, carried in `error.details[0].code`, so a client can render it in the customer's own language; `error.message` is the English equivalent for a caller with no catalogue. ⛔ Read the code from `details`, not from `error.code` — that is the generic `UNPROCESSABLE_ENTITY` for every 422 this API produces.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBlueprintDeployRequest"}}}},"responses":{"202":{"description":"The deploy was accepted; the new deployment row.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBlueprintDeployment"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/site-imports/snapshots":{"get":{"operationId":"getArchiveSnapshots","tags":["hosting"],"summary":"What a web archive holds for a domain, by day.","description":"The date picker's data for a Wayback restore. ⛔ **A cached database read, never a live archive call.** The Internet Archive's CDX index answered a two-row query in 41.9 seconds when measured on 2026-08-06, so an endpoint that blocked on it would hold a worker per customer and read as broken. When the cache is absent or stale this starts a durable refresh workflow and answers `202` with `state: \"pending\"`; poll it. `state` has four values and they are not interchangeable — `pending` (never fetched), `ready` (fresh), `stale` (usable but past its TTL, a refresh is running) and `error` (the archive refused, and the reason is in `error`). Requires `sites.view`.","parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string","maxLength":253},"description":"The domain to look up, e.g. `example.com`. `www.` is ignored."}],"responses":{"200":{"description":"The cached snapshot index (`ready` or `stale`).","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArchiveSnapshotIndex"}}}},"202":{"description":"Nothing cached yet; a refresh has been started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArchiveSnapshotIndex"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/site-imports/platform":{"get":{"operationId":"getArchivePlatform","tags":["hosting"],"summary":"What the archived site was built on, and what a restore can recover.","description":"⚖️ **Owner ruling 2026-09-08.** A web-archive capture holds rendered HTML and nothing else — no database, no PHP, no administrator — so a Joomla, Drupal or Magento site cannot be restored *as* that application. This endpoint says what the archive was, so the restore form can state plainly, **before the customer commits**, what they get back (`gains`) and what is gone (`losses`). Every value is a machine code the client localises; the engine composes no sentences (they could only ever be English). ⛔ A cached read, like `/v1/site-imports/snapshots`, and for a related but different reason: one home-page fetch measured 1.13 s live on 2026-09-08, which is affordable once and not affordable per viewer of a shared aged-domain list. A miss starts a durable probe and answers `202` with `state: \"pending\"`; poll it. `state` has the same four values as the snapshot index and they are not interchangeable. Requires `sites.view`.","parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string","maxLength":253},"description":"The archived domain, e.g. `example.com`. `www.` is ignored."},{"name":"day","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"description":"The snapshot day being considered, `YYYY-MM-DD`. Required, because a domain's platform changes over its life — a 2009 capture and a 2019 capture of one domain routinely answer differently."}],"responses":{"200":{"description":"The cached verdict (`ready`, `stale` or `error`).","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArchivePlatform"}}}},"202":{"description":"Nothing probed yet; a probe has been started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArchivePlatform"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/site-moves":{"get":{"operationId":"listSiteMoves","tags":["hosting"],"summary":"Sites moving onto your hosting from PBN hosting, and your free site slots.","description":"The moves a connected partner (PBN hosting) started for this organization, newest first, and one row per hosting plan with its site slots — the same numbers a site create is refused on. Read-only: a move is started from the partner's own panel. Requires `sites.view`.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"responses":{"200":{"description":"Slots and moves.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMoveOverview"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/site-moves/{moveId}/retry":{"parameters":[{"$ref":"#/components/parameters/PartnerSiteMoveId"}],"post":{"operationId":"retrySiteMove","tags":["hosting"],"summary":"Try a failed move-in again from your own panel.","description":"The customer's own retry of a site being moved in from PBN hosting, with the same rule as the partner's (`retryable: true` only). Requires `sites.create` in the site's organisation.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerSiteMoveRetry"}}}},"responses":{"202":{"description":"The move, queued again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerSiteMove"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/site-imports":{"get":{"operationId":"listSiteImports","tags":["hosting"],"summary":"List the org's Wayback restores and migrations.","description":"A pure database read, polled by the progress screen. Requires `sites.view`.","responses":{"200":{"description":"The org's most recent import jobs, newest first.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteImportList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createSiteImport","tags":["hosting"],"summary":"Restore a site from a web archive, or migrate one in.","description":"Starts a durable, resumable import workflow and returns the new job state, never a bare acknowledgement. A Wayback restore **must** name `snapshot_day`: the most recent capture of an expired domain is usually a parking page, so there is no safe default (422 without it). The output is either a static HTML document root or a WordPress import — both are supported and neither is a default. A site with an import already running returns 409. ⚠️ `ownership_attested` is recorded, not enforced: the platform's obligation here is to know who requested what. Requires `hosting.import.manage`.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteImportCreate"}}}},"responses":{"202":{"description":"The import was accepted; the new job state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteImport"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/site-imports/{importId}":{"parameters":[{"$ref":"#/components/parameters/ImportId"}],"get":{"operationId":"getSiteImport","tags":["hosting"],"summary":"One import job's state and progress.","description":"A pure database read — everything reported comes from rows the workflow writes, so polling costs no archive call. Progress is per-URL counters rather than only a percentage, because \"which step\" is the useful answer when a customer asks why a restore is slow. `budget_exhausted` is surfaced deliberately: a job that stopped because it ran out of requests otherwise looks exactly like one that finished. Requires `sites.view`.","responses":{"200":{"description":"The import job.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteImport"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/site-imports/{importId}/cancel":{"parameters":[{"$ref":"#/components/parameters/ImportId"}],"post":{"operationId":"cancelSiteImport","tags":["hosting"],"summary":"Cancel a running import.","description":"Marks the job cancelled. The running workflow notices at the top of its next fetch batch and stops cleanly, which leaves the job's rows consistent — cancelling the workflow itself would abort mid-batch with items half-written. An already-finished job returns 422. Requires `hosting.import.manage`.","responses":{"200":{"description":"The cancelled job.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteImport"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/migrations/discover":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"discoverMigrationSource","tags":["hosting"],"summary":"Work out which control panel a host runs, from the hostname alone.","description":"Takes a hostname and **no credential**, and answers which control panel the host is running, on which port, and what we would expect to be able to take off it. It exists because the step before it used to be a dropdown asking a prospect to choose \"cPanel / WHM\" or \"DirectAdmin\" and to know their own control-panel port — which the customer who is leaving a host they are unhappy with frequently cannot answer, and a form that cannot be filled in is a migration that is postponed for ever.\n\nIt runs unauthenticated TCP connects and reads public sign-in pages. Five protocol fingerprints decide first (`cpsrvd` in a `Server:` header, `PLESKSESSID`, and so on — facts about software, not a list of hosting brands that would rot); a language model is asked to read the page **only** when that table is not confident, and its answer is weighted evidence that cannot outrank a protocol banner. `agent_used` says whether it was asked.\n\n`outcome` is three-valued and never a boolean: `identified`, `unidentified` (something answered and we cannot place it — a candidate for the managed migration) and `unreachable` (nothing answered at all — usually a typo or a firewall). Those have opposite remedies, so folding them would hand both populations the same wrong advice.\n\n`routes` lists every way in that was tried and whether it answered, with `checked` distinguishing \"closed\" from \"we never got to try\". Read it when a panel is firewalled: a host with 2083 closed and 22 open can still have its files, databases and mail moved. **Nothing we do installs anything on the source** — no migration plugin, no backup plugin, no agent — so a host that forbids those blocks none of it.\n\n⛔ `POST` although it creates nothing and carries no secret: it knocks on a third party's administrative ports, which is an act rather than a lookup, and must not be repeated by a prefetch or a back button. A bad hostname or a dead host is an `outcome`, not an error. Requires `hosting.import.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MigrationDiscoveryRequest"}}}},"responses":{"202":{"description":"The discovery has been started; `outcome` is `pending` and `discovery_id` is the row to poll with `getMigrationDiscovery`. ⛔ 202 and not 200 since D19865: the probe fan-out plus an optional model call ran to gunicorn's 30 s worker timeout inside this request on production, so it now runs as a Temporal workflow and the screen polls the row.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MigrationDiscoveryResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/migrations/discoveries/{discoveryId}":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"discoveryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The `discovery_id` a `discoverMigrationSource` call answered with."}],"get":{"operationId":"getMigrationDiscovery","tags":["hosting"],"summary":"Poll a discovery until it has an answer.","description":"The row `discoverMigrationSource` created, as the workflow completes it. `outcome` is `pending` until the probe has run — a few seconds, up to about two minutes when the fingerprint table is not confident and a model is asked to read the sign-in page — and then `identified`, `unidentified` or `unreachable`. A workflow that could not finish leaves `unreachable` with the reason recorded; a row never stays `pending` for ever. Reads the row, never Temporal, so polling is cheap. Scoped to the site: another tenant's discovery id is a 404. Requires `hosting.import.manage`.","responses":{"200":{"description":"The discovery as recorded so far.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MigrationDiscoveryResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/migrations/probe":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"probeMigrationSource","tags":["hosting"],"summary":"Sign in to the old host and show what is there.","description":"The migration form's preview: authenticates against the source and enumerates the estate **without creating a job**. Run while the customer is still on the screen, which is the whole design — a wrong password becomes a form error instead of a job that fails an hour later, and the customer confirms what is about to move before anything is committed. It is also where the mail precondition is discovered early enough to be fixable.\n\nRead `unavailable` before believing an empty list: it names what we could not look at, and \"there is no mail here\" and \"this login cannot see mail\" are opposite answers. Refusals arrive as 422 with a machine `code` per detail row (`source_credentials_rejected`, `source_unreachable`, `source_port_unreachable`, `source_host_not_public`, `plesk_needs_admin_credentials`, `credential_required`), so the dashboard localises them rather than showing engine English. `source_port_unreachable` is returned within ~8 s when nothing accepts a TCP connection on the source's port, and carries two more rows with the same code: `field: port` and `field: addresses` (our outbound IPv4 addresses, read live from the cluster, for the customer's host to allow). `source_admin_login_needs_subscription_login` (a Plesk administrator login: the copy needs the subscription's own FTP/SSH login, named in `field: logins`) and `source_login_attempts_paused` (after 2 refused logins to one host inside 10 minutes no further login is tried, so the source's brute-force guard never bans us; `field: minutes`) are refusals too. `source_file_access_refused`: the control panel accepted the login but SSH and FTP both refused it (the password is right; SSH or FTP access is off for the account). When only SSH refuses, files move over FTP and databases are listed in `unavailable` as `ftp_login_cannot_reach_mysql`. An `ftp` source itself reads the database through a one-time PHP helper (docs/1296), deleted straight after and verified gone over FTP.\n\n⛔ `POST` although it creates nothing: the body carries a live credential for somebody else's server, and a `GET` would put it in a query string — browser history, proxy logs, access logs. Requires `hosting.import.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MigrationCredentials"}}}},"responses":{"200":{"description":"What the source holds, and what could not be read.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MigrationSourceInventory"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/migrations/managed-request":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"requestManagedMigration","tags":["hosting"],"summary":"Ask our team to migrate this site for you — free, no limit.","description":"Books a **free** manual migration: our staff move the site for the customer. Owner ruling 2026-10-14 — migrations are free for every customer with no limits, and self-service (`createSiteMigration`, the zinn-migrate plugin archive import, cPanel, Plesk, DirectAdmin, FTP/SFTP and SSH sources) is the main, fastest route; this is the route when the customer would rather we did it, or a source cannot be automated.\n\nIt records an **`ExtraPurchase`** of the `managed_migration` service at a price of 0 (waived for every organization, whatever the catalogue row says), not a migration job: the fulfilment workflow raises it to the staff Extras queue, staff are alerted by e-mail and Telegram, and the 72-hour SLA clock starts. Returns the purchase, so the client can show its status and SLA due time. There is no per-site or per-account limit — a second request is a second job. An environment whose catalogue has never been seeded answers 503 rather than 404, because the service exists and is advertised. The staff note travels on the purchase.\n\n⛔ Send **no credentials** here — the body has nowhere to put them, and staff collect them out of band from a human they can verify. Requires `hosting.import.manage`, the same authority as a self-service migration: nothing is charged.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedMigrationRequest"}}}},"responses":{"201":{"description":"The free purchase, handed to fulfilment and the staff queue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtraPurchase"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/migrations":{"get":{"operationId":"listMigrations","tags":["hosting"],"summary":"Every migration across the organisation, newest first.","description":"The estate-wide view. The per-site list exists too and answers a different question: this one is *\"what is moving in, anywhere\"*, which is the question a customer has when they are moving a hosting account rather than a site. Each row carries the site's name, domain and status so the screen renders without one request per row.\n\nA pure database read — nothing here costs a Temporal describe or a connection to anybody's old host. Requires `sites.view`.","parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"A page of migrations.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OrgMigration"}},"page":{"$ref":"#/components/schemas/PageMeta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createMigrationWithSite","tags":["hosting"],"summary":"Create the site and start migrating onto it, in one call.","description":"The *\"deploy it and start the migration straight away\"* path, and the only one that works from an account with **no sites yet**.\n\n⛔⛔ One endpoint rather than \"call `POST /v1/sites` then `POST /v1/sites/{id}/migrations`\", because the two-call version fails badly: a browser closed between them, or a migration refused for a bad password, leaves an **orphan site** the customer never asked for, holding one of their plan's site slots, with a hostname they must now delete. Each endpoint did exactly what it was asked and the customer is left holding it.\n\nSo the ordering here is load-bearing: the source is probed **first**, and the site is created only once the credentials have been proven against the customer's old host and the estate enumerated. The two failures a customer will actually hit both happen while nothing has been created — and so do the attestation and mail refusals (`ownership_not_attested`, `mailbox_passwords_required`, `source_cannot_migrate_mail`), which until 2026-09-13 were asked only after the site existed. Send `mailbox_passwords` for the addresses `POST /v1/migrations/probe` lists.\n\n⛔ Not idempotent, and it does not pretend to be — a retry is refused by the hostname uniqueness constraint, which is a clean conflict rather than a second site.\n\nRequires **both** `sites.create` and `hosting.import.manage`: it spends a site slot *and* connects to a third party's production server, and a principal holding one of those powers must not acquire the other by coming through this door.\n\n⚖️ **A full plan does not refuse a migration** (row 1107#13, owner 2026-11-07: *\"better that than refusing the migration in\"*). With no free site slot the site is still created and migrated, then **frozen** (served, but read-only, no cron, no mail) with the `site_slots_frozen` notice; an upgrade or a deleted site unfreezes it within about ten minutes. The oldest such sites get any free room first. The slot refusal stands only past the hard cap of `max(10 × the plan's sites, sites + 9)`, and an organization with no plan on the line is still refused.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeployAndMigrate"}}}},"responses":{"202":{"description":"The site was created and the migration accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgMigration"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/migrations/discover":{"post":{"operationId":"discoverMigrationSourceForOrg","tags":["hosting"],"summary":"Identify a host from its hostname, with no site yet.","description":"The org-scoped twin of `POST /v1/sites/{siteId}/migrations/discover`. Same workflow, same 202-plus-poll shape, and the same owner ruling behind it: **signed-in customers only, never a prospect** — the hostname is attacker-supplied by construction and *\"probe this for me\"* is the classic shape of a request to reach something the caller cannot.\n\nIt exists because the customer it serves has **no sites at all**, which is exactly the customer being asked *\"which control panel do you log in to?\"* by a form they cannot answer. `hosting.import.manage` is an org permission, so every run still has a named actor and an org to rate-limit; only the site-level anchor is dropped, and nothing about the ruling rested on it.\n\nPOST rather than GET, and not because of a secret — there is none in the body. It knocks on a third party's administrative ports, which is an act rather than a lookup, and must not be repeated by a browser prefetch, a CDN revalidation or a back button. Name the organisation with `X-Zinn-Org` when you belong to more than one; a caller in exactly one org may omit it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MigrationDiscoveryRequest"}}}},"responses":{"202":{"description":"The discovery was started; the pending row to poll.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MigrationDiscoveryResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/migrations/discoveries/{discoveryId}":{"parameters":[{"name":"discoveryId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"get":{"operationId":"getMigrationDiscoveryForOrg","tags":["hosting"],"summary":"Poll a discovery started without a site.","description":"Answers from the row the workflow completes. `outcome` is `pending` until then and one of the three answers afterwards; a workflow that could not finish leaves `unreachable` with its reason, never `pending` for ever. Scoped to the caller's own organisations — another tenant's discovery id is a 404, not their row. Requires `hosting.import.manage`.","responses":{"200":{"description":"The discovery row.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MigrationDiscoveryResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/migrations/ai-move/eligibility":{"get":{"operationId":"getAiMoveEligibility","tags":["hosting"],"summary":"May this organisation have a free AI Move, and if not, why not.","description":"AI Move is free and unlimited on paid plans (owner ruling 2026-10-21). A trial gets self-service plus an upgrade prompt: `reason` is `trial`. Other reasons: `not_offered` (not launched to this account yet), `no_plan`, `not_in_good_standing`. Name the organisation with `X-Zinn-Org` when you belong to more than one. Requires `sites.view`.","responses":{"200":{"description":"The answer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiMoveEligibility"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/migrations/ai-moves":{"get":{"operationId":"listAiMoves","tags":["hosting"],"summary":"The organisation's AI Moves, newest first.","description":"Requires `sites.view`. Never returns a credential.","responses":{"200":{"description":"The AI Moves (at most 200).","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AiMove"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"post":{"operationId":"requestAiMove","tags":["hosting"],"summary":"Ask our AI to move a site here — free, overseen by our team.","description":"The intake. The access given (`access`) is written straight to Vault and never stored, logged or returned; the request keeps only which kinds of access were given and the host each points at. A $0 `managed_migration` purchase keeps the SLA, and a support ticket is opened for the customer and linked both ways — every step the AI takes is posted there. **Refused with 403 unless eligible** (`getAiMoveEligibility`): a trial is refused with `ai_move_trial`. With no `site_id` the move creates the site, which needs `sites.create`. With `site_id` the move goes OVER that site: when it has ever served anything, `replace_confirmation` (its domain, typed) is required and checked here (`422` `replace_not_confirmed` / `replace_confirmation_mismatch`), the site is backed up before the copy writes, and it can be restored for 30 days. Requires `hosting.import.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiMoveIntake"}}}},"responses":{"201":{"description":"The request, as recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiMove"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/migrations/ai-moves/{moveId}":{"parameters":[{"name":"moveId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAiMove","tags":["hosting"],"summary":"One AI Move and where it is.","description":"Requires `sites.view`.","responses":{"200":{"description":"The AI Move.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiMove"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/migrations/ai-moves/{moveId}/access":{"parameters":[{"name":"moveId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"put":{"operationId":"updateAiMoveAccess","tags":["hosting"],"summary":"Send fresh access for an AI Move (the secure form).","description":"The answer to the ticket's \"please send fresh access\": written straight to Vault, merged with what was given before, and the move carries on by itself. Never send a password on the ticket. Requires `hosting.import.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"access":{"$ref":"#/components/schemas/AiMoveAccess"},"mailbox_passwords":{"type":"object","maxProperties":500,"description":"Mailbox address -> password. Straight to Vault; never stored or returned.","additionalProperties":{"type":"string","maxLength":1024,"writeOnly":true}},"replace_confirmation":{"type":"string","maxLength":253,"description":"The site's domain typed back, to confirm replacing a site that has content."},"replace_site_id":{"type":["string","null"],"format":"uuid","description":"When `needs` is `replace_existing`: the `existing_site.id` the move named — the site in the SAME organisation that already holds the domain — whose content the customer chooses to replace with the move. Sent with `replace_confirmation` (the domain, typed). A backup of that site is taken before anything is replaced and the switch-over can be rolled back for 30 days. The consent is audited (`site.migration.ai_move_replace_existing_consented`). A site that is not the one named, or a domain that does not match, is refused with 422 `replace_not_confirmed`. A site in another organisation is never offered."}}}}}},"responses":{"200":{"description":"The AI Move.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiMove"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/migrations/ai-moves/{moveId}/continue":{"parameters":[{"name":"moveId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"continueAiMove","tags":["hosting"],"summary":"Tell a waiting AI Move to look again (after an upgrade or an answer).","description":"Requires `hosting.import.manage`.","responses":{"202":{"description":"The AI Move will look again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiMove"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/migrations/ai-moves/{moveId}/go":{"parameters":[{"name":"moveId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"goAiMove","tags":["hosting"],"summary":"Switch an AI Move over now (the GO).","description":"The same consent as replying GO on the move's ticket. Refused with 409 unless the copy has passed its preview and app checks (`stage` is `awaiting_cutover`), and refused with 409 once the customer put the replaced site back (the copy was restored over); the live check follows the switch-over and the move is `done` only when the customer's own domain reaches our server. Requires `hosting.import.manage`.","responses":{"202":{"description":"The switch-over will start.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiMove"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/migrations/ai-moves/{moveId}/cancel":{"parameters":[{"name":"moveId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"cancelAiMove","tags":["hosting"],"summary":"Cancel an AI Move; the access given is deleted at once.","description":"Nothing at the old host is changed. Requires `hosting.import.manage`.","responses":{"200":{"description":"The cancelled AI Move.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiMove"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/migrations/ai-moves/{moveId}/restart":{"parameters":[{"name":"moveId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"restartAiMove","tags":["hosting"],"summary":"Start this AI Move again from the beginning, as a fresh move.","description":"Owner row 1107#24. The fresh move keeps the same site, the access already given and the same ticket; this one is cancelled (its unfinished copy is stopped) and points to the new one in `restarted_as`. Nothing at the old host is changed. Refused with 409 once the move is done or cancelled (`refusal.aiMove.finished`), once its switch-over has started (`refusal.aiMove.switchStarted`), or when its access was already deleted (`refusal.aiMove.accessGone` — start a new move instead). Requires `hosting.import.manage`.","responses":{"201":{"description":"The fresh AI Move.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiMove"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/migrations/agent":{"post":{"operationId":"askMigrationAgent","tags":["hosting"],"summary":"Ask the AI migration agent to move a site, in words.","description":"The conversational door onto the migration toolchain. Say what you want — *\"move my site from oldhost.example.com\"* — and the agent finds the site, works out which control panel the old host runs, plans the move, starts it when you say yes, watches it, and tells you what the comparison of the two sites found.\n\nRequires `sites.view` to ask. What the agent can actually **do** is decided per tool against your own permissions: a read-only member gets an assistant that explains a migration and cannot start one, and only a member with `hosting.backup.manage` is offered a rollback. The agent holds no identity of its own.\n\n`confirm` is the list of actions you have approved **for this message** — `migration_start`, `migration_start_new_site` (create the site here and move yours onto it, when you have none yet), `migration_cancel` or `migration_rollback`. The platform checks it against what you actually sent, so the assistant cannot start, stop or undo anything by claiming you agreed. `credentials` carries the login for your old host; it is used for this request and is never stored on the conversation, never returned, and never shown to the model.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MigrationAgentMessage"}}}},"responses":{"200":{"description":"The agent's reply, with both turns of the exchange.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MigrationAgentReply"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/migrations/agent/conversations":{"get":{"operationId":"listMigrationAgentConversations","tags":["hosting"],"summary":"Your migration assistant conversations, most recently used first.","description":"Each thread carries who opened it. A thread whose `opened_by` is `staff` was started by Zinn® on your behalf — so a migration you did not ask for always has a record of where it came from. Requires `sites.view`.","responses":{"200":{"description":"The conversations.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MigrationAgentConversationList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/migrations/agent/conversations/{conversationId}":{"parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getMigrationAgentConversation","tags":["hosting"],"summary":"One conversation, every turn, with what the agent did on each.","description":"Every agent turn lists the actions it ran and whether each succeeded, beside what it said. That is deliberate: an assistant that says it has started moving your site either called the action or did not, and the record lets you see which. Requires `sites.view`.","responses":{"200":{"description":"The conversation.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MigrationAgentConversationDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/migrations/probe":{"post":{"operationId":"probeMigrationSourceForOrg","tags":["hosting"],"summary":"Sign in to the old host and show what is there, with no site yet.","description":"The org-scoped twin of `POST /v1/sites/{siteId}/migrations/probe`, for the site-less `/migrations/new` form: authenticates against the source and enumerates it **without creating a site or a job**, and returns the same inventory.\n\nIt exists because mail cannot move without a password per mailbox, no panel can read one out, and the customer can only be asked for the mailboxes the source actually holds once somebody has looked. `mailboxes_without_passwords` lists them; when a source cannot list mailboxes at all (Plesk to a subscription login) `unavailable` carries `site_migration:mailboxes: mailbox_passwords_required`, meaning *name each mailbox with its password*, not *mail cannot move*.\n\n⛔ `POST` although it creates nothing: the body carries a live credential for somebody else's server. Name the organisation with `X-Zinn-Org` when you belong to more than one. Requires `hosting.import.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MigrationCredentials"}}}},"responses":{"200":{"description":"What the source holds, and what could not be read.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MigrationSourceInventory"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/migrations":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"listSiteMigrations","tags":["hosting"],"summary":"The site's migrations, newest first.","description":"A pure database read — everything reported comes from rows the workflow writes, so the progress screen can poll it without costing a Temporal describe or a single connection to the customer's old host. Requires `sites.view`.","responses":{"200":{"description":"The site's migration jobs.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMigrationList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createSiteMigration","tags":["hosting"],"summary":"Migrate a site in from another host.","description":"Probes the source, records the job and its per-item rows, then starts a durable workflow that resumes rather than restarts — a 5,000-file or 40-mailbox job survives a worker being replaced, which matters because a restart would mean a second full read of a stranger's live server. Returns `202` with the **new job state**, never a bare acknowledgement.\n\nRefused up front, while the customer still has their old account, if the source cannot give us the mail they asked for (`source_cannot_migrate_mail`) or if any mailbox has no password (`mailbox_passwords_required`, with the count in the detail rows) — a migration that moves a website and silently loses the mailboxes is worse for the customer than no migration at all. Other refusals are 422 with a machine `code`; a site that already has a migration running is 409; a site mid-move between our own fleet workers is also 409. If the workflow service or the secret store is unavailable the answer is 503 and **no job is written** — an acceptance we cannot honour would leave the customer watching a progress bar for ever.\n\nRequires `hosting.import.manage`.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMigrationCreate"}}}},"responses":{"202":{"description":"The migration was accepted; the new job state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMigration"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/migrations/{migrationId}":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"$ref":"#/components/parameters/MigrationId"}],"get":{"operationId":"getSiteMigration","tags":["hosting"],"summary":"One migration's state and progress.","description":"A pure database read, polled by the progress screen. Progress is per-kind counters rather than only a percentage, because \"which step\" is the useful answer when a customer asks why a migration is slow, and `items_failed` is reported separately from the `*_done` counts so a job that could not fetch part of the estate cannot report itself complete. Requires `sites.view`.","responses":{"200":{"description":"The migration job.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMigrationDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/migrations/{migrationId}/cancel":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"$ref":"#/components/parameters/MigrationId"}],"post":{"operationId":"cancelSiteMigration","tags":["hosting"],"summary":"Stop a running migration.","description":"Marks the job cancelled. The running workflow notices at the top of its next round and stops cleanly, which leaves the item rows consistent and closes the session on the source host — cancelling the workflow itself would abort mid-item, with a half-written file on the new site and an open connection to somebody else's production server. An already-finished job returns 422 with `migration_not_cancellable`. Requires `hosting.import.manage`.","responses":{"200":{"description":"The cancelled job.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMigration"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/migrations/{migrationId}/rollback":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"$ref":"#/components/parameters/MigrationId"}],"post":{"operationId":"rollbackSiteMigration","tags":["hosting"],"summary":"Put the site back to how it was before this migration.","description":"Restores the backup taken in the seconds before the migration replaced the site. ⛔ **This overwrites the site's live files and database** — with the version from before the migration, which is the point, but overwriting all the same: anything the customer has done since is inside the window the restore covers.\n\nIts own route rather than a flag on the detail endpoint, and it does not re-implement the restore — it starts the same `SiteRestoreWorkflow` the Backups screen uses, which the weekly restore drill already exercises.\n\nRefused with 422 and a machine `code` when the migration replaced nothing (`nothing_was_replaced`), has already been rolled back (`already_rolled_back`), is still running (`migration_not_finished` — the answer there is to cancel it), has no usable archive (`no_safety_backup:<state>`, `safety_backup_gone`) or is past its 30 days (`window_expired`).\n\nRequires `hosting.backup.manage` — **not** `hosting.import.manage`. Starting a migration and destroying what is on a site now are different powers, and this is the same permission `POST /v1/sites/{siteId}/backups/restore` requires for the identical act.","responses":{"202":{"description":"The restore was started; the migration row, now stamped.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMigration"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/sites/{siteId}/migrations/{migrationId}/cutover":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"$ref":"#/components/parameters/MigrationId"}],"post":{"operationId":"cutoverSiteMigration","tags":["hosting"],"summary":"Re-sync the mail that arrived during the move.","description":"Runs the **mail delta**, and it is the control that makes mail survive a migration. Mail keeps arriving at the old host while we copy, so the sequence is: full sync → the customer moves their MX → this. The delta asks the source only for messages above each mailbox's high-water UID, which is what stops a second pass duplicating an inbox.\n\nOnly a job in `awaiting_cutover` may be cut over (422 `migration_not_awaiting_cutover` otherwise): running it earlier would re-read the whole estate, and running it on a finished job would reopen a session on a server the customer may already have cancelled. A website-only migration is **refused** rather than accepted as a no-op (422 `migration_has_no_mail`) — a control that reports success and does nothing is how a customer concludes their mail moved when it did not. Requires `hosting.import.manage`.","responses":{"202":{"description":"The delta was started; the job's state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMigration"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/mail/routing":{"get":{"operationId":"listMailRouting","summary":"How every domain in this organization has its mail routed.","description":"One row per domain: which mechanism serves its mail, where its catch-all delivers, and whether the world agrees yet. Requires `mail.view`.\n\n⛔ **A different question from `/v1/mail/services`, and the reason this endpoint had to exist.** A forwarding domain — the whole Footprint-Free line — deliberately has **no mail service**: it gets an alias that receives rather than a mailbox that stores, so it appears in no service list at any depth. Before this route, that customer could not see that their site forwards, could not see where to, and could not change it.\n\n`mechanism` is **derived, never chosen**: it is a function of the customer's own mail connection, the plan's mailbox allowance, and the domain's live DNS delegation — and a zone on Cloudflare is routed through Cloudflare Email Routing automatically, because it is free there and keeps the traffic off our relay. `mechanism_label` is the sentence explaining that choice, and it is the same one the operator log carries.","tags":["mail"],"responses":{"200":{"description":"Every domain's mail routing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailRoutingList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/mail/routing/{fqdn}":{"parameters":[{"name":"fqdn","in":"path","required":true,"description":"The hostname whose mail routing is being read or changed.","schema":{"type":"string","maxLength":253}}],"get":{"operationId":"getMailRouting","summary":"How one domain's mail is routed.","description":"Requires `mail.view`.","tags":["mail"],"responses":{"200":{"description":"The domain's mail routing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailRouting"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateMailCatchAll","summary":"Re-point a forwarding domain's catch-all.","description":"Sets where everything addressed to this domain is delivered. Requires `mail.manage`.\n\n⛔ **Taking ownership is part of the write.** The alias stops being system-managed, so the convergence sweep will never reassert our computed destination over the customer's choice — silently, which is the only way that failure would ever be noticed.\n\n⛔ **Refused with 422 on a domain that stores its mail in mailboxes**, rather than accepted and ignored: a forwarding address on a mailbox domain is a control that appears to work while mail keeps arriving in the mailbox.","tags":["mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["destination"],"properties":{"destination":{"type":"string","format":"email","maxLength":254,"description":"Where mail to any address on this domain is delivered."}}}}}},"responses":{"200":{"description":"The updated routing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailRouting"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/mail/free-tier":{"get":{"operationId":"getMailFreeTier","summary":"What a free mailbox is, and what it costs to provide.","description":"The free mailbox tier's quota, per-organization ceiling and derived capacity. Requires `mail.view`.\n\n⭐ **Published rather than written down.** Every figure is computed from the measured relay capacity and the configured quota, so raising the quota lowers the mailbox count and raises the stated per-mailbox cost with no second edit. A screen or a pricing page that restated these numbers would be a second expression of the same arithmetic, and would go stale the first time the quota moved.","tags":["mail"],"responses":{"200":{"description":"The free tier's derived figures.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailFreeTier"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/mail/reseller-brand":{"get":{"operationId":"getResellerMailBrand","summary":"The mail hostnames this reseller's mail is published and served under.","description":"Requires `mail.view`. An organization with no brand configured gets an empty one with `configured: false` rather than a 404 — the form is the same either way.","tags":["mail"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"The organization to read for; defaults to the caller's own when unambiguous.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The reseller's mail brand.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerMailBrand"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setResellerMailBrand","summary":"Set the mail hostnames this reseller's mail carries.","description":"Requires `mail.manage`. Every field is a public hostname — there is no credential here, because the relay authenticates the mailbox rather than the brand.\n\n⭐ **This is what makes hosted mail sellable by a white-label reseller.** With their own `mx1.` / `imap.` / `smtp.` / `webmail.` names in front of the relay, nothing published on a client's zone and nothing handed to a client's mail app carries the platform's name — so the product can be offered without the leak that previously required withholding it.\n\n⛔ **A partially-filled brand is saved and does not enable anything.** `configured` is all-or-nothing: a brand with an MX and no webmail host would publish the reseller's MX and then send their client to somebody else's webmail, which is the leak arriving through the mechanism built to close it.","tags":["mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerMailBrandInput"}}}},"responses":{"200":{"description":"The saved brand.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerMailBrand"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/mail/allowance":{"get":{"operationId":"getMailAllowance","summary":"What the caller's plan grants for mailboxes.","description":"The preflight the \"set up email\" screen reads: whether the governing plan includes mailboxes, how large each one is, and how many a domain may have. **Reports rather than refuses** — an organization with no plan gets `included: false` and an upgrade prompt, not an error, because this is a read screen.\n\nResolution walks **up** the `parent_org` chain, so a reseller's client organization inherits the reseller's plan (CLAUDE.md §2.3). `source` names where the answer came from. `mailbox_limit` is the **smaller of the plan's `mailboxes` grant and the platform abuse ceiling**, so it does vary by plan; `-1` means both are uncapped. Requires `mail.view`.\n\n⭐ **Pass `fqdn` whenever the question is about one domain, which is nearly always.** Since the owner's ruling of 2026-08-16 a domain registered with us — or transferred in — grants free mailboxes **on itself**, whatever the organization's hosting plan says, and that grant is only reachable when the hostname is supplied. Without `fqdn` this endpoint answers the narrower question \"does anything the organization owns include mail at all\", and a customer whose only product is a domain gets `included: false` followed by a successful mailbox creation — a screen disagreeing with its own API.","tags":["mail"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"The organization to resolve for; defaults to the caller's own when unambiguous.","schema":{"$ref":"#/components/schemas/Uuid"}},{"name":"fqdn","in":"query","required":false,"description":"Resolve for this hostname. Adds the `domain` source — free mailboxes on a domain we hold the registration for.","schema":{"type":"string","maxLength":253}}],"responses":{"200":{"description":"The resolved mailbox allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailAllowance"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/mail/services/{mailServiceId}/forwarders":{"parameters":[{"$ref":"#/components/parameters/MailServiceId"}],"get":{"operationId":"listMailForwarders","summary":"The forwarders on this domain.","description":"Read through to the mail backend (#662). **Filtered to this service's own domain** — the backend lists forwarders per *account*, and one account can hold several domains, so returning its whole set would show a customer another domain's routing. Requires `mail.view`.","tags":["mail"],"responses":{"200":{"description":"Every forwarder on the domain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailForwarderList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"post":{"operationId":"createMailForwarder","summary":"Forward an address, a catch-all, or a whole domain.","description":"`source` is required for `mailbox` and **ignored** for `catchall`/`wildcard`, where the whole domain is the source — so it may be omitted for those rather than sending a value the backend discards. Requires `mail.manage`.","tags":["mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailForwarderCreate"}}}},"responses":{"201":{"description":"The forwarder.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailForwarder"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/mail/services/{mailServiceId}/forwarders/{forwarderId}":{"parameters":[{"$ref":"#/components/parameters/MailServiceId"},{"name":"forwarderId","in":"path","required":true,"description":"The mail backend's identifier, as returned by the list - not a UUID of ours.","schema":{"type":"string"}}],"delete":{"operationId":"deleteMailForwarder","summary":"Remove a forwarder.","description":"Idempotent - removing one already gone succeeds. Requires `mail.manage`.","tags":["mail"],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/mail/services/{mailServiceId}/responders":{"parameters":[{"$ref":"#/components/parameters/MailServiceId"}],"get":{"operationId":"listMailResponders","summary":"The auto-responders on this domain.","description":"Out-of-office replies (#664). **Read through to the mail backend** — a responder has no count entitlement, no billing consequence and no lifecycle of its own, so there is no model of ours behind this and nothing to paginate: the backend's list for one domain is the whole answer. Requires `mail.view`.","tags":["mail"],"responses":{"200":{"description":"Every auto-responder on the domain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailResponderList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"post":{"operationId":"createMailResponder","summary":"Set an auto-reply on a mailbox.","description":"Idempotent on `local`: re-posting for the same mailbox reconciles to the existing responder rather than creating a second one, which is the backend's own natural key. Requires `mail.manage`.","tags":["mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailResponderCreate"}}}},"responses":{"201":{"description":"The auto-responder.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailResponder"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/mail/services/{mailServiceId}/responders/{responderId}":{"parameters":[{"$ref":"#/components/parameters/MailServiceId"},{"name":"responderId","in":"path","required":true,"description":"The **mail backend's** identifier for the responder, as returned by the list — not a UUID of ours. A responder has no model here, so there is no id of ours to use.","schema":{"type":"string"}}],"patch":{"operationId":"updateMailResponder","summary":"Edit an auto-reply.","description":"Changes the message and its schedule. **The address is not part of this body** — an auto-reply belongs to a mailbox, and the address is *which mailbox you are editing* rather than a property of the reply.\n\n⭐ This used to say *\"the mail backend has no rename verb\"*. That was **false** and was the stated premise of a decision to offer no rename at all; measured against the live upstream hosting API on 2026-08-16, a mailbox renames **in place**, same id, contents intact. Use `renameMailbox` to change an address, or a forwarder to give a mailbox a second one.\n\nThe responder is returned **as the backend reports it back after the write**, not as it was sent: the mail backend answers an applied update and an ignored one with the same empty body, so echoing the request would be a fabricated success (D9256). Requires `mail.manage`.","tags":["mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailResponderUpdate"}}}},"responses":{"200":{"description":"The auto-responder as it now stands.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailResponder"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"delete":{"operationId":"deleteMailResponder","summary":"Remove an auto-reply.","description":"Idempotent - removing one that is already gone succeeds. Requires `mail.manage`.","tags":["mail"],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/mail/domains":{"get":{"operationId":"listMailDomains","summary":"Every domain the organization could have email on, searchable.","description":"The mail domain directory behind the `/mail` screen's domain picker (MAILUX, owner 2026-10-27: *\"we should have emails tied to domains on here … and no search option at all to find the one you're looking for\"*). One row per hostname, the union of: domains registered with us, connected to us or transferring in; every live site's primary domain; and every domain that already has an email service. Each row carries the service on it (or `null`) and whether email can be set up there at all, with the reason when it cannot (a hostname on our own platform domain — a preview or staging address — never takes mail).\n\n**Searched and paged on the server** (`q`, `cursor`, `limit`): an account with thousands of domains never loads them all. Ordered by hostname; the cursor is the last hostname returned. A site's extra alias hostnames are not listed (set mail up on the domain itself). Requires `mail.view`; RLS-scoped.","tags":["mail"],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"org_id","in":"query","required":false,"description":"Restrict to one organization in scope. **Narrowing only**, as on `GET /v1/mail/services`: an organization outside the caller's subtree filters to nothing rather than `403`-ing.","schema":{"$ref":"#/components/schemas/Uuid"}},{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":253},"description":"Case-insensitive substring of the hostname. Empty lists everything."}],"responses":{"200":{"description":"One page of the organization's mail domains, by hostname.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailDomainList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/mail/preflight":{"get":{"operationId":"getMailPreflight","summary":"What setting email up on a domain would do to its DNS.","description":"Read-only. Answers **before the customer commits** whether this domain can take our mail records, and exactly what publishing them would remove (#662).\n\nSetting mail up rewrites the domain's apex `MX`. If the domain already receives email somewhere else, that stops inbound mail reaching the mailboxes it is addressed to — an outage the customer usually learns about from the people who could not reach them. Without this endpoint the only way to discover the refusal was to create a service and watch it fail asynchronously, which is a refusal arriving *after* the decision.\n\n`safe: false` means `POST /v1/mail/services` will refuse unless it is called with the override flag. `foreign_mx` and `would_delete` are listed **verbatim**, not counted, because a customer must be able to see what they are about to destroy before confirming it.\n\n`zone_unreadable: true` is **never** `safe`: there is no DNS resolver in the platform, so \"we could not read the zone\" is the normal answer for a domain whose DNS is hosted elsewhere, and treating that as safe would disable the guard exactly where it matters most.\n\n⚠️ A safe answer is not a promise — the zone can change between this call and the apply, so provisioning repeats the check inside its workflow. Requires `mail.view`.","tags":["mail"],"parameters":[{"name":"fqdn","in":"query","required":true,"description":"The domain to check.","schema":{"type":"string","maxLength":253}},{"name":"provider","in":"query","required":false,"description":"Which provider's records to test against; defaults to our own mail. The answer differs per provider, because each preset publishes a different record set.","schema":{"$ref":"#/components/schemas/MailProvider"}},{"name":"mx_hosts","in":"query","required":false,"description":"`custom` only: the MX targets the reseller has typed so far, comma-separated. The preflight compares the zone with the records the preset **would** publish, and for a provider we cannot name that set is whatever is being declared — so a domain already on that provider reads as safe, and one on somebody else's does not.","schema":{"type":"string","maxLength":2048}},{"name":"org_id","in":"query","required":false,"description":"The organization to act in; defaults to the caller's own when unambiguous.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"What an apply would find and remove.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailPreflight"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/mail/services":{"get":{"operationId":"listMailServices","summary":"List the organization's email services.","description":"Every domain the organization has email on, cursor-paginated and RLS-scoped. Requires `mail.view`.\n\n⚖️ **A `deleted` service is not listed** (W43-99, D26270 — owner ruling 2026-09-15: no row that can never be actioned). It has no control left, and the row records no deletion date to window on, so it is left out rather than shown for a period. `GET /v1/mail/services/{mailServiceId}` still answers for it.","tags":["mail"],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"org_id","in":"query","required":false,"description":"Restrict to one organization in scope. **Narrowing only** — the value is intersected with what the caller may already read, so an organization outside their subtree filters to nothing rather than `403`-ing (a `403` would confirm it exists). The default is the caller's **entire readable subtree**, which for a reseller is every client's mail at once — so the org switcher must send this.","schema":{"$ref":"#/components/schemas/Uuid"}},{"name":"fqdn","in":"query","required":false,"schema":{"type":"string","maxLength":253},"description":"Return only the service on this exact hostname (normalised: lowercased, trailing dot stripped). ⛔ **A site surface must use this rather than searching the list.** The list is paginated newest-first at 50, so \"does this domain have email\" cannot be answered from the first page - and getting it wrong tells a customer their plan excludes mailboxes for a domain that has a live, MX-published service."},{"name":"site_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Return only the mail services on the hostnames this **site** serves. Resolved through the site's domains, not through a stored column — mail attaches to a domain and a domain outlives the site on it, so there is deliberately no `site_id` on a mail service. An id that matches nothing returns an **empty** list, never an unfiltered one."},{"name":"worker_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Return only the mail services belonging to the sites on this **fleet worker**. Mail has no server of its own — it runs at the mail backend, not on the box serving the website — so this is \"the mail estates of the sites on this machine\", resolved server → sites → domains → mail."},{"name":"compute_server_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"As `worker_id`, for a cloud `ComputeServer` rather than a fleet worker. The two are different machine kinds and are not interchangeable."}],"responses":{"200":{"description":"The organization's email services.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailServiceList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createMailService","summary":"Set email up on a domain.","description":"Registers the email service and requests its provisioning. Returns `201` with the service `pending`: creating the backend account and publishing the mail DNS is a durable Temporal workflow (CLAUDE.md §2.9), so poll `status` or subscribe to `mail.provisioned` / `mail.provisioning_failed`.\n\n⛔ **Provisioning refuses to overwrite existing mail.** If the domain's apex already carries a foreign `MX`, or its zone cannot be read at all, the service ends `failed` rather than replacing records that are delivering someone's live email. That refusal is not retried — it is a decision about the customer's own domain.\n\nRequires `mail.manage`. Fails `409` when the domain already has an email service, and `422` when the plan does not include mailboxes.","tags":["mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailServiceCreate"}}}},"responses":{"201":{"description":"The registered email service, provisioning under way.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailService"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/mail/services/{mailServiceId}":{"parameters":[{"$ref":"#/components/parameters/MailServiceId"}],"get":{"operationId":"getMailService","summary":"Get one email service.","description":"One email service in the caller's scope. Requires `mail.view`.","tags":["mail"],"responses":{"200":{"description":"The email service.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailService"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"deleteMailService","summary":"Remove a domain's email service.","description":"Moves the service to `deleting`; teardown then runs asynchronously. Idempotent — a service already removed returns `204`. Requires `mail.manage`. When we published the domain's mail DNS records, removing the service also removes them in the background: every record we recorded publishing, including a DKIM key an earlier setup wrote, but only while it still holds the value we published, only in the zone the domain is delegated to, and each removal confirmed at the domain's own nameservers. A foreign MX and any record someone changed are left alone, and an SPF record another sender was added to keeps everything except our own include.","tags":["mail"],"responses":{"204":{"description":"Removal accepted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/mail/services/{mailServiceId}/deliverability":{"get":{"operationId":"getMailDeliverability","summary":"SPF, DKIM and DMARC state for a domain that already has email.","description":"Whether this domain's mail is set up to be **delivered** - the question a customer asks when their messages land in spam. ⛔ A different question from `/preflight`, which asks what setting mail up here would destroy; both read the same underlying report so a preview and the fix cannot disagree. `fixable` is false when the apex MX belongs to somebody else or the zone cannot be read, because a one-click apply would then either destroy working mail or write blind. Requires `mail.view`.","tags":["mail"],"parameters":[{"$ref":"#/components/parameters/MailServiceId"}],"responses":{"200":{"description":"The domain's deliverability state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailDeliverability"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"applyMailDeliverability","summary":"Publish this domain's mail records.","description":"Write the correct SPF, DKIM and DMARC records into the domain's zone. ⛔ Refuses with `422` when the apex MX is somebody else's - that is not a state to confirm past from this screen, because the customer's mail is being delivered today and this button must never be how that stops. When records would be **replaced**, answers `409` until `confirm: true` is sent, so a destructive apply is always a deliberate second act (the confirm-gated shape #622 forced on DNS). Also `422`, writing nothing, when the domain's DNS is managed by an external app (`dns_managed_externally` on the platform domain, docs/845 §9). Requires `mail.manage`.","tags":["mail"],"parameters":[{"$ref":"#/components/parameters/MailServiceId"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailDeliverabilityApply"}}}},"responses":{"200":{"description":"Applied. The re-read state, so the caller sees what is now published.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailDeliverability"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/mail/services/{mailServiceId}/dns-records":{"get":{"operationId":"getMailDnsRecords","summary":"Every DNS record this domain needs for email, each checked live.","description":"The exact records (type, host, value, priority) the domain needs for its email provider - MX, SPF, DKIM, DMARC and the mail-app discovery records - from the same preset the provisioning publishes, so what is shown is what would be written. Each record carries a live `status` asked of the domain's OWN nameservers: `ok`, `missing`, `different` (with what was `found` instead) or `unknown` when the nameservers could not be asked (never shown as ok or missing). `dns_hosted` says whether we publish them (`ours`) or the customer adds them at their DNS provider (`external`). The support AI reads the same list. `422` for our own mail under a white label, as the connection settings are. Requires `mail.view`.","tags":["mail"],"parameters":[{"$ref":"#/components/parameters/MailServiceId"}],"responses":{"200":{"description":"The domain's mail records and their live state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailDnsRecords"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/mail/services/{mailServiceId}/retry":{"parameters":[{"$ref":"#/components/parameters/MailServiceId"}],"post":{"operationId":"retryMailService","summary":"Retry a mail service whose setup failed.","description":"Re-enters the provisioning workflow for a service in `failed`. Setting email up is a multi-step operation against two backends — the mail account and the domain's DNS zone — and a failure part-way leaves a service that is real, may already hold a paid mailbox package, and is not usable. The automatic sweep cannot recover it: that re-drives services still `pending`, never one that failed after that point, so before this endpoint the only options were to look at the failure or delete the service.\n\nSafe to call twice. The provisioning workflow id is derived from the service id so a duplicate start converges on the run already going, the mail-account step is an ensure, and the DNS step is a convergent write. Calling it on a service that is already `pending` or `provisioning` is answered with its current state rather than an error — the caller asked for the state it is already in. Any other status is `409`. Requires `mail.manage`.\n\nA `zinn` service under a white-label entitlement with no reseller mail hostnames is `422` with the same sentence the records list gives: setting it up again would hand out our hostnames, so the refusal is identically true on every call and the caller shows the reason rather than offering another retry.","tags":["mail"],"responses":{"200":{"description":"The service, now provisioning."},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/mail/services/{mailServiceId}/provider":{"parameters":[{"$ref":"#/components/parameters/MailServiceId"}],"post":{"operationId":"switchMailServiceProvider","tags":["mail"],"summary":"Move a domain's email to a different provider.","description":"Repoints this domain at another mail provider — our own email, Google Workspace or Microsoft 365 — and, when moving **away from ours**, destroys the mailboxes we were hosting for it.\n\n⛔ **Not the same as `DELETE`, and the difference is the post-condition.** A delete ends with no mail service at all; a switch ends with a **live** one on the new provider, publishing that provider's records. Using the delete for this would leave the domain with no email a moment after the customer chose some.\n\n**The order is the safety property:** the DNS records are repointed FIRST, and the mailboxes destroyed second. The reverse loses mail — between a destroy and a repoint the MX still names mailboxes that no longer exist, and everything sent in that window bounces. Doing it this way costs a brief period in which both could receive, which is the harmless failure.\n\n`confirm_fqdn` — the domain typed back — is **required when the switch destroys mailboxes we run**, and ignored otherwise. Owner ruling 2026-08-14: type the domain, no grace period. The mailboxes and their contents are gone at the vendor the moment this runs.\n\n⛔ `422`, writing nothing and changing nothing, when the domain's DNS is managed by an external app (`dns_managed_externally` on the platform domain, docs/845 §9).\n\nSwitching to the provider a domain is already on is a no-op that returns the service, so a retry is idempotent. Requires `mail.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailProviderSwitch"}}}},"responses":{"200":{"description":"The email service, now on the new provider.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailService"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/mail/services/{mailServiceId}/connection-settings":{"parameters":[{"$ref":"#/components/parameters/MailServiceId"}],"get":{"operationId":"getMailConnectionSettings","summary":"IMAP and SMTP settings for a mail client.","description":"The hostnames and ports a customer types into Apple Mail, Outlook or a phone. For Zinn®'s own email these are **our** hostnames — an environment that has not been given them returns `503` rather than inventing names or naming the backend. For a `custom` provider they are the declared ones, and a declaration with no client hostnames is a `422` that says to ask the provider rather than an invented name. A `zinn` service under a white-label account is also `422`: our hostnames must not reach a reseller's client (W40-MAIL). Requires `mail.view`.","tags":["mail"],"responses":{"200":{"description":"The connection settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailConnectionSettings"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/mail/services/{mailServiceId}/mailboxes":{"parameters":[{"$ref":"#/components/parameters/MailServiceId"}],"get":{"operationId":"listMailboxes","summary":"List a domain's mailboxes.","description":"The mailboxes on this email service, cursor-paginated. Served from our own records rather than from the backend, so a listing never puts an external call in a hot path (CLAUDE.md §2.16). Requires `mail.view`.","tags":["mail"],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":64},"description":"Case-insensitive substring of the mailbox's local part (the bit before the `@`). Empty lists every mailbox."}],"responses":{"200":{"description":"The mailboxes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createMailbox","summary":"Create a mailbox.","description":"Creates `local@domain`. Send `password` to choose it (checked first; never echoed back), or omit it to get a generated one **returned once**. A password is never stored by us and cannot be read back — a lost one is replaced by `resetMailboxPassword`, not recovered. `password` is `null` when the backend reconciled to a mailbox that already existed and refused to rotate a live password; show that as \"we could not display a password\", never as a blank one.\n\nRequires `mail.manage`. Fails `409` on a duplicate address, and `422` when the service is not live yet or the domain is at its mailbox ceiling.","tags":["mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxCreate"}}}},"responses":{"201":{"description":"The mailbox and its one-time password.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxCreated"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/mail/mailboxes/{mailboxId}":{"parameters":[{"$ref":"#/components/parameters/MailboxId"}],"put":{"operationId":"updateMailbox","summary":"Change a mailbox's size, or its send/receive switches.","description":"Every field is optional; a request that sets only `receive` leaves the size alone.\n\n**The size half is what makes the quota warning honest.** `mail.mailbox_quota_warning` tells a customer their mailbox is filling up, and until this existed the only truthful advice it could give was \"delete things\" — the mail backend could always resize a mailbox, but nothing exposed it (#932, #662).\n\n`quota_mb` is bounded by the **plan allowance captured on the service at purchase**, so a later plan change cannot retroactively shrink what a customer was sold. Above that sits the backend package's own ceiling; both refusals answer **422** with the same customer-facing sentence, because the customer's next action is identical either way. Requires `mail.manage`.","tags":["mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxUpdate"}}}},"responses":{"200":{"description":"The updated mailbox.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Mailbox"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"delete":{"operationId":"deleteMailbox","summary":"Delete a mailbox.","description":"Deletes the mailbox at the backend and then locally, in that order — a local row removed first would leave a mailbox still receiving mail that nothing knows about. Requires `mail.manage`.\n\n⛔ Refused with **422** for a mailbox carrying `system_managed: true` — the address we created with the site, which the site's own outbound mail and contact form are configured against. Every other mailbox on every product line is the customer's to remove (owner ruling 2026-08-16).","tags":["mail"],"responses":{"204":{"description":"The mailbox was deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/mail/mailboxes/{mailboxId}/rename":{"parameters":[{"$ref":"#/components/parameters/MailboxId"}],"post":{"operationId":"renameMailbox","summary":"Change a mailbox's address, keeping the mail in it.","description":"Changes the local part — `sales@example.com` becomes `hello@example.com` — with every message already in the mailbox intact.\n\n⚖️ Part of the owner's 2026-08-16 ruling that a domain owner must be able to *\"create the mailboxes easily and manage them in full\"*.\n\n**A POST to a sub-resource rather than a field on `updateMailbox`, deliberately.** A rename moves where mail is delivered; a quota edit does not. Sharing a body would let a mistyped field change a customer's address as a side effect of resizing their mailbox, and would make the two indistinguishable in the audit log.\n\n⛔ **The engine reads the mailbox back from the backend and refuses if the address did not actually change**, rather than trusting the backend's success response. It never falls back to create-then-delete: that would \"work\" on screen and silently destroy every stored message.\n\n`409` when the target address already exists on the domain; `422` for a mailbox that has not finished provisioning, and for the `system_managed` address the site sends from. Requires `mail.manage`.","tags":["mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxRename"}}}},"responses":{"200":{"description":"The renamed mailbox.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Mailbox"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/mail/mailboxes/{mailboxId}/password":{"parameters":[{"$ref":"#/components/parameters/MailboxId"}],"post":{"operationId":"resetMailboxPassword","summary":"Set or reset a mailbox password.","description":"Sets the password the person **chose** (`{\"password\": \"…\"}`), or, with an empty body, generates a strong one and returns it once. A chosen password must be 12–128 characters, must not contain the address or its domain name, and must not appear in a known data breach (checked with k-anonymity: only five characters of its hash leave our systems); a refused one is a `422` and changes nothing. A chosen password is never echoed back (`password: null`, `chosen: true`). Always a reset, never a read: there is no column holding the old one. Audited (how it was set, never what to); at most 10 per mailbox per hour (`429`). Requires `mail.manage`.","tags":["mail"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxPasswordSet"}}}},"responses":{"200":{"description":"The mailbox and its new one-time password.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxCreated"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/mail/mailboxes/{mailboxId}/recovery":{"parameters":[{"$ref":"#/components/parameters/MailboxId"}],"put":{"operationId":"setMailboxRecovery","summary":"Set a mailbox's recovery address.","description":"Stores an opt-in recovery address for the mailbox and e-mails it a verification link. Once verified, the mailbox's user can reset a forgotten password from the webmail sign-in page: a single-use link (30 minutes) is sent to this address — never a password. The mailbox's own address is refused (`422`), and so is any address while self-reset is switched off. Audited. At most 10 changes per mailbox per hour. Requires `mail.manage`.","tags":["mail"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxRecovery"}}}},"responses":{"200":{"description":"The mailbox, with its (unverified) recovery address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Mailbox"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"removeMailboxRecovery","summary":"Remove a mailbox's recovery address.","description":"Removes the recovery address and voids every outstanding link sent to it. Audited. Requires `mail.manage`.","tags":["mail"],"responses":{"200":{"description":"The mailbox, with no recovery address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Mailbox"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/mail/mailboxes/{mailboxId}/webmail":{"parameters":[{"$ref":"#/components/parameters/MailboxId"}],"post":{"operationId":"createMailboxWebmailLink","summary":"Open webmail for a mailbox.","description":"Mints a single-use webmail sign-in URL for this mailbox, so the customer reaches their inbox without re-entering the password. Requires `mail.manage`.","tags":["mail"],"responses":{"200":{"description":"The webmail sign-in URL.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebmailLink"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/mail/mailboxes/{mailboxId}/client-setup":{"parameters":[{"$ref":"#/components/parameters/MailboxId"}],"get":{"operationId":"getMailboxClientSetup","summary":"Everything needed to add this mailbox to a mail app.","description":"The hostnames, ports, socket security and username for **this mailbox**, so a customer can set it up on a phone, in Outlook, in Apple Mail or in Thunderbird without asking us. One payload for every client — the per-client wording is translated copy on the surfaces that render it, not part of this contract.\n\nThe `username` is the **full address** on both servers, stated rather than left to be derived: it is the single most common thing a person types wrongly. `apple_profile_available` and `autodiscover_available` say whether the two self-configuring routes exist for this mailbox — they do for Zinn®'s own email, and not for Google Workspace or Microsoft 365, whose own clients already know their provider. A `zinn` service under a white-label account is a `422`: our hostnames must not reach a reseller's client (W40-MAIL). Requires `mail.view`.","tags":["mail"],"responses":{"200":{"description":"The client setup for this mailbox.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxClientSetup"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/mail/mailboxes/{mailboxId}/apple-profile":{"parameters":[{"$ref":"#/components/parameters/MailboxId"}],"get":{"operationId":"getMailboxAppleProfile","summary":"An Apple configuration profile for this mailbox.","description":"A `.mobileconfig` that sets the mailbox up on iOS or macOS in one tap. It carries the hostnames, ports and username; **no password is in it** — the person types their own when the profile installs, so the file is safe to download, e-mail to yourself or keep. `404` when the mailbox is on Google Workspace or Microsoft 365, whose own profiles configure calendars and contacts as well and are the better answer. Requires `mail.view`.","tags":["mail"],"responses":{"200":{"description":"The configuration profile.","content":{"application/x-apple-aspen-config":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/autodiscover/autodiscover.xml":{"get":{"operationId":"getAutodiscoverDocument","summary":"Outlook auto-setup (discovery).","description":"The POX Autodiscover response for an address, so Outlook configures itself from the e-mail address alone. Unauthenticated by protocol. Answers only for domains whose mailboxes are ours and active; everything else is `404`, including a domain we do not host and one whose mail is with Google or Microsoft — one answer for every reason, so this cannot be walked as a list of our customers' domains. Everything in the response is already published in that domain's own DNS.","tags":["mail"],"security":[],"parameters":[{"name":"emailaddress","in":"query","required":false,"schema":{"type":"string"},"description":"The address being set up. Outlook itself POSTs this in an XML body instead; the query parameter is what a browser, a `curl` or a monitoring probe sends."}],"responses":{"200":{"description":"The Autodiscover document.","content":{"text/xml":{"schema":{"type":"string"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"postAutodiscoverDocument","summary":"Outlook auto-setup (discovery), as Outlook actually asks.","description":"The same document, for the POST Outlook really sends — an XML body carrying `<EMailAddress>`. Unauthenticated by protocol; see the `GET` for what is and is not disclosed.","tags":["mail"],"security":[],"requestBody":{"required":false,"content":{"text/xml":{"schema":{"type":"string"}}}},"responses":{"200":{"description":"The Autodiscover document.","content":{"text/xml":{"schema":{"type":"string"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/Autodiscover/Autodiscover.xml":{"get":{"operationId":"getAutodiscoverDocumentTitleCase","summary":"Outlook auto-setup (discovery), capitalised path.","description":"Byte-for-byte the same document as `/autodiscover/autodiscover.xml`, under the spelling several Outlook builds send. Unauthenticated by protocol; see that path for what is and is not disclosed.","tags":["mail"],"security":[],"parameters":[{"name":"emailaddress","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The Autodiscover document.","content":{"text/xml":{"schema":{"type":"string"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"postAutodiscoverDocumentTitleCase","summary":"Outlook auto-setup (discovery), capitalised path, as Outlook actually asks.","description":"The same document for the POST Outlook really sends, under the capitalised spelling.","tags":["mail"],"security":[],"requestBody":{"required":false,"content":{"text/xml":{"schema":{"type":"string"}}}},"responses":{"200":{"description":"The Autodiscover document.","content":{"text/xml":{"schema":{"type":"string"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/mail/config-v1.1.xml":{"get":{"operationId":"getMailAutoconfigDocument","summary":"Thunderbird auto-setup (discovery).","description":"The Mozilla `clientConfig` document for a domain, so Thunderbird configures itself from the address alone. Unauthenticated by protocol. It is about the **provider**, not the mailbox, and contains no address at all — which is what makes it safe to serve to an anonymous caller. `?domain=` is accepted as well as `?emailaddress=`, because Thunderbird's MX-derived lookup arrives with no address and that is the route needing no record in the customer's own zone.","tags":["mail"],"security":[],"parameters":[{"name":"emailaddress","in":"query","required":false,"schema":{"type":"string"}},{"name":"domain","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The autoconfig document.","content":{"text/xml":{"schema":{"type":"string"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/.well-known/autoconfig/mail/config-v1.1.xml":{"get":{"operationId":"getMailAutoconfigDocumentWellKnown","summary":"Thunderbird auto-setup (discovery, well-known path).","description":"Identical to `/mail/config-v1.1.xml`. Thunderbird tries the `.well-known` spelling at the customer's own domain and the bare one at an `autoconfig.` host, so both exist or one family of clients is not served.","tags":["mail"],"security":[],"parameters":[{"name":"emailaddress","in":"query","required":false,"schema":{"type":"string"}},{"name":"domain","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The autoconfig document.","content":{"text/xml":{"schema":{"type":"string"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/streaming/streams":{"get":{"operationId":"listLiveStreams","tags":["connections"],"summary":"The organisation's live streaming channels.","description":"Live channels on the **customer's own** streaming account (owner ruling 2026-08-28: Gcore is sold BYO only). Connect one at `/v1/connections/streaming_gcore` first.\n\n⛔⛔ **The RTMP/SRT push URL is deliberately absent from this response and must never be added to it.** It is a credential, not an address: anyone holding that string can broadcast as the customer. The provider's own API treats it as a secret — it offers a \"reset push token\" call — and the driver strips it on every list read.\n\n`state` is `idle` (channel enabled, nothing arriving), `processing`, `ready` (bytes are arriving now) or `failed`. ⛔ *Enabled* and *live* are different questions: rendering an enabled-but-silent channel as live sends a customer to publish a player against a manifest with nothing behind it.","responses":{"200":{"description":"The organisation's live channels.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiveStreamList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/streaming/videos":{"get":{"operationId":"listStoredVideos","tags":["connections"],"summary":"The organisation's stored, transcoded video.","description":"Video assets on the customer's own streaming account.\n\n⛔ `duration_seconds` is `null`, never `0`, while the provider has not finished measuring it. A UI that renders a missing duration as `0:00` tells the customer their upload is broken when it is merely still transcoding.\n\n`state` is `ready` once at least one quality is playable.","responses":{"200":{"description":"The organisation's stored videos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoredVideoList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/waap/domains":{"get":{"operationId":"listWaapDomains","tags":["connections"],"summary":"Domains protected by the organisation's WAAP account, and what the policy did.","description":"Web application and API protection on the customer's own account.\n\n⛔⛔ **`mode` is mandatory reading and no client may render a domain as \"protected\" without it.** `monitor` evaluates every rule, logs every match and **delivers the traffic anyway** — it produces analytics, shows threats detected, and blocks nothing. On a dashboard it is indistinguishable from `block` unless the mode is shown.\n\n`locked` is a fourth state the **provider** assigns (usually for billing) and the customer cannot change; it is not a mode they chose and a toggle will not clear it.\n\n⛔ `total_requests` and `blocked_requests` are `null` when the provider does not report them — never `0`. \"Nothing was blocked\" and \"we cannot see what was blocked\" are opposite answers.","responses":{"200":{"description":"The protected domains.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WaapDomainList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/waap/domains/{domainId}/mode":{"parameters":[{"name":"domainId","in":"path","required":true,"schema":{"type":"string"},"description":"The provider's id for the protected domain."}],"post":{"operationId":"setWaapDomainMode","tags":["connections"],"summary":"Switch a protected domain between monitor, block and off.","description":"The one call here that changes whether traffic is refused. Requires `connections.manage`: it writes to the customer's connected account, so the read key the list call takes is not enough.\n\n⛔ The response reports the mode the provider says is **now in force**, which is not necessarily the one that was requested: providers apply some transitions asynchronously and refuse others outright. Echoing the request back would leave every screen showing a protection state that was never applied.\n\n⛔ `locked` is rejected with `422`: it is a state the provider assigns, never one that can be requested, and accepting it would build a control that always fails.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WaapModeRequest"}}}},"responses":{"200":{"description":"The domain, with the mode now in force.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WaapDomain"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/inference/deployments":{"get":{"operationId":"listInferenceDeployments","tags":["connections"],"summary":"The organisation's model deployments and what is actually serving.","description":"Model endpoints on the customer's own inference account.\n\n⛔ `replicas` is what was **asked for** and `ready_replicas` is what is **serving**. A screen showing only the first reports a healthy deployment that is answering nothing. `ready_replicas` is `null` when the provider did not report readiness at all — which is not the same as zero.\n\n`state` includes `degraded` (some replicas up, some not) and `deleting` (being torn down, and possibly still holding GPUs). Neither is rounded onto a neighbour: a `degraded` deployment reported as `running` hides missing capacity, and a `deleting` one reported as `stopped` implies it has stopped costing money.","responses":{"200":{"description":"The organisation's deployments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InferenceDeploymentList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/inference/flavours":{"get":{"operationId":"listInferenceFlavours","tags":["connections"],"summary":"The GPU shapes the organisation's inference account may deploy on.","description":"The provider's own catalogue of GPU shapes.\n\n⛔⛔ **`price_per_hour_minor` is `null` for every row today, and that is correct rather than a gap.** The provider's flavour catalogue carries no price at all — its prices are quoted per prospective deployment, against the customer's own account and commitments. Filling this from a public rate card would be a *list* price for a *different* account, rendered to a customer as though we had measured it. A client must show \"price on request\" and **must not draw a zero**.","responses":{"200":{"description":"The available GPU shapes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GpuFlavourList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/registrar-domains":{"get":{"operationId":"listRegistrarDomains","tags":["connections"],"summary":"The domains in the organization's linked registrar accounts.","description":"Everything we can see in the registrar accounts (GoDaddy, Namecheap, Porkbun, Name.com, Gandi, Spaceship, NameSilo, Hostinger or OVHcloud) the customer has connected, with what we last observed about each name and what — if anything — they need to do about it.\n\n⛔ **These are not `Domain` resources and the two must not be conflated.** A `Domain` is a name the platform is responsible for: we sell it, we renew it, a workflow drives every transition. A row here is a name registered somewhere we did not sell it, whose renewal and ownership are entirely the customer's — we may read it and we may point it at a site, and that is the whole surface. `matched_domain_id` is the one place they meet, set when a `Domain` for the same name exists in the same organization.\n\n⛔ `nameservers` is `null` when we have never read the delegation — **never** `[]`, which would say the domain is delegated nowhere. Two of the three registrars' account listings do not carry nameservers at all, so `null` is the ordinary state of a freshly imported row.\n\n⛔ `state` is **our** verdict (*is there anything to tell you?*) and `registrar_status` is the **vendor's** own word, carried through verbatim and unmapped. They answer different questions and a client must not render one as the other: three registrars use three vocabularies, and deciding what `AWAITING_VERIFICATION` \"really\" means is not a decision this API takes on a screen whose job is to show the customer what their registrar says.\n\n`accounts` is served beside the domains because a connected account holding **zero** domains is a state the screen must render — a Porkbun key scoped to no domain, or an account genuinely empty — and a domain list alone cannot express it.\n\n⛔ `total` is the count **before** the page limit and is not decoration: a list that silently stops is the same shape as a complete one, and the customer's conclusion from it (\"these are all my domains\") is exactly the wrong one. Requires `sites.view` — seeing which domains you hold is not managing a credential.","parameters":[{"name":"provider","in":"query","required":false,"description":"Show only one linked provider's domains, e.g. `registrar_godaddy`.","schema":{"$ref":"#/components/schemas/ConnectionProvider"}},{"name":"state","in":"query","required":false,"description":"Show only domains in one state.","schema":{"$ref":"#/components/schemas/RegistrarDomainState"}}],"responses":{"200":{"description":"The linked domains, the total, and the accounts they came from.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistrarDomainList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/registrar-accounts/{connectionId}/refresh":{"parameters":[{"$ref":"#/components/parameters/ConnectionId"}],"post":{"operationId":"refreshRegistrarAccount","tags":["connections"],"summary":"Re-read one linked registrar account now.","description":"Asks the registrar for the account's current domain list and reconciles it: new domains appear, changed ones are updated, and domains the account **no longer lists** are retired.\n\n⛔ `retired` is reported rather than swallowed. A refresh that retires forty domains is either a transfer the customer made or a key that has lost access, and both need saying out loud.\n\n⛔ A registrar that refuses answers **200 with `refused` set**, not a 5xx. The customer's own key or their registrar declined — that is an answer they can act on, and an error status makes the client render an anonymous failure where a specific, fixable sentence belongs. When `refused` is set every count is `0` and **nothing was retired**: a vendor outage is not a portfolio change.\n\nSpends the customer's own vendor quota, so it requires `connections.manage`.","responses":{"200":{"description":"What the refresh reconciled, or why it could not.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistrarAccountRefresh"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/connections/providers":{"get":{"operationId":"listConnectionProviders","tags":["connections"],"summary":"Every provider a customer can connect, with its form and its checklist.","description":"The **catalogue**: for each connectable provider, which credential fields it takes (and which of them are secret), and which permissions we will test it for.\n\nServed as an endpoint rather than baked into each client because the six BYO DNS vendors take credentials of one, two and five fields — ClouDNS needs `auth_id` and `auth_password`, Azure needs five — and hardcoding those in a client duplicates the driver's own `required_settings` across the wire, where the two copies are free to drift apart. Every field name here is read off the driver class itself, so a vendor that gains a required setting changes this response and cannot be connected with a bundle it will refuse.\n\n`shapes` is a list of **alternative** credential forms; a client renders the first and offers the rest. Cloudflare is the live case: a scoped API token, or the account email plus its Global API Key.\n\n`permissions` is empty when we have no permission model for that provider. ⛔ Render that as \"we cannot test this provider's permissions\" — **never** as a satisfied (empty) checklist, which is a different and wrong claim. Requires authentication only; it describes what *can* be connected, not what anyone has connected.","responses":{"200":{"description":"The connectable providers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionProviderList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/connections/{provider}":{"parameters":[{"$ref":"#/components/parameters/ConnectionProviderPath"}],"get":{"operationId":"listConnections","tags":["connections"],"summary":"List the org's connected accounts for one provider.","description":"Returns an empty list rather than 404 when nothing is connected — \"not connected yet\" is the normal state, not an error. Requires `connections.manage`.","responses":{"200":{"description":"The connected accounts for this provider.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"connectProvider","tags":["connections"],"summary":"Validate or store a provider access token.","description":"With `validate_only` the token is checked and nothing is stored, and the result is returned with 200 **even when the token is invalid** — an invalid token is an answer the caller renders, not a request error. Without it the token is re-validated and then stored in Vault, returning 201; a token that fails validation is rejected with `TOKEN_INVALID` and never persisted. The token itself is never logged or echoed. Requires `connections.manage`.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which organization this connected account belongs to. Required when the caller manages connections for more than one — a reseller or an agency by construction — because a credential silently stored against the wrong org reads on the site side as \"no account connected\", with nothing on either screen explaining why. It can only narrow **within** the organizations the caller already manages, so it can never widen scope; one outside that set is refused with the same wording as \"you did not choose\", because distinguishing \"not yours\" from \"does not exist\" would confirm the organization exists.","schema":{"$ref":"#/components/schemas/Uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectTokenRequest"}}}},"responses":{"200":{"description":"The validation result (validate-only; nothing was stored).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenValidation"}}}},"201":{"description":"The stored connection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Connection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/connections/{provider}/{connectionId}":{"parameters":[{"$ref":"#/components/parameters/ConnectionProviderPath"},{"$ref":"#/components/parameters/ConnectionId"}],"delete":{"operationId":"disconnectProvider","tags":["connections"],"summary":"Disconnect a provider account.","description":"Removes the connection and its Vault secret. Any site whose CDN runs on this account is reset to off in the same transaction, so a site is never left pointing at a credential that no longer exists. Requires `connections.manage`.","responses":{"204":{"description":"Disconnected."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/connections/{provider}/{connectionId}/probe":{"parameters":[{"$ref":"#/components/parameters/ConnectionProviderPath"},{"$ref":"#/components/parameters/ConnectionId"}],"post":{"operationId":"probeConnectionPermissions","tags":["connections"],"summary":"Re-test a stored credential, one row per permission.","description":"Exercises every permission we need **against the provider** using the credential already stored for this connection, and returns one row per permission.\n\nThis is the \"retest\" half of add-and-test: the customer's fix happens in their vendor's console — they tick the missing permission at Cloudflare — so there is nothing to re-paste and the stored credential is used.\n\n⛔ It does not ask the credential to describe itself. A least-privilege token cannot enumerate its own permissions, which is how a token missing DNS edit entirely came to be displayed as \"works, we will check on first use\". Every check here is a real, well-formed call, and a write permission is proved by writing — a throwaway DNS record created and immediately deleted, or a zone setting written back to the value just read.\n\nEach row is `pass`, `fail` or **`unknown`**, and the third is not a nicety: `unknown` is the honest answer when we could not reach the question — no zone on the account yet, the vendor rate-limiting us, or a well-formed request refused on its content. ⛔ A client that renders `unknown` as a tick has reintroduced the defect this endpoint exists to remove.\n\nThe result is stored against the connection with the time it was taken, and returned with `checked_at`. It is a **measurement, not a state** — the customer can revoke a permission at their vendor a second later and nothing here will know — so any surface showing it must show its age. Requires `connections.manage`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionProbeRequest"}}}},"responses":{"200":{"description":"The per-permission report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionReport"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/client-reports/overview":{"get":{"operationId":"getClientReportsOverview","tags":["client-reports"],"summary":"What your Client Reports plan allows, and which report sections have data.","description":"The allowance (clients, reports this month, looks, share-link life, own sender) read from the SAME helper the point of spend asks, so the screen and the refusal cannot disagree. `sections_with_data` names the sections that would print something today. Requires `sites.view`.","responses":{"200":{"description":"The allowance and the section picker.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReportsOverview"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/client-reports/brands":{"get":{"operationId":"listClientReportBrands","tags":["client-reports"],"summary":"Your report looks (white-label brands).","description":"Default first. Requires `sites.view`.","responses":{"200":{"description":"The looks.","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ClientReportBrand"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createClientReportBrand","tags":["client-reports"],"summary":"Add a report look — your name, colours, intro and footer.","description":"⛔ Refused past the looks your tier includes (1 / 3 / 10). The first look becomes the default. The intro and footer are plain text, printed verbatim and never translated. Requires `sites.create`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReportBrandInput"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReportBrand"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/client-reports/brands/{brand_id}":{"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"operationId":"updateClientReportBrand","tags":["client-reports"],"summary":"Change a report look.","description":"Changes future reports only — a report already made keeps the look it was made with. ⛔ Changing the reply-to address makes it unconfirmed again. Requires `sites.create`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReportBrandInput"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReportBrand"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"deleteClientReportBrand","tags":["client-reports"],"summary":"Remove a report look.","description":"Clients using it fall back to no look (your organisation's name). Requires `sites.create`.","responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/client-reports/brands/{brand_id}/logo":{"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"uploadClientReportBrandLogo","tags":["client-reports"],"summary":"Upload the logo a report look carries.","description":"Vetted and stored content-addressed (the same store as the agency invoice logo); the PDF inlines the bytes as a `data:` URI and fetches nothing at render time. Requires `sites.create`.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["logo"],"properties":{"logo":{"type":"string","format":"binary","description":"The image."}}}}}},"responses":{"201":{"description":"Stored and set on the look.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReportBrand"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"clearClientReportBrandLogo","tags":["client-reports"],"summary":"Take the logo off future reports.","description":"The bytes are kept — reports already made still show it. Requires `sites.create`.","responses":{"200":{"description":"Cleared.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReportBrand"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/client-reports/brands/{brand_id}/reply-to/code":{"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"sendClientReportReplyToCode","tags":["client-reports"],"summary":"E-mail a confirmation code to the look's reply-to address.","description":"⛔ Pro and Agency only (`own_sender`). Replies to a report reach the reply-to address only once it is confirmed, so a report can never tell a client to reply to an address nobody proved they read. Requires `sites.create`.","responses":{"202":{"description":"Sent.","content":{"application/json":{"schema":{"type":"object","required":["sent_to"],"properties":{"sent_to":{"type":"string","format":"email"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/client-reports/brands/{brand_id}/reply-to/confirm":{"parameters":[{"name":"brand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"confirmClientReportReplyTo","tags":["client-reports"],"summary":"Confirm the reply-to address with the code it received.","description":"A wrong or expired (24 h) code changes nothing. Requires `sites.create`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","example":"123456"}}}}}},"responses":{"200":{"description":"Confirmed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReportBrand"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/client-reports/clients":{"get":{"operationId":"listClientReportClients","tags":["client-reports"],"summary":"The clients you make reports for, with their schedules.","description":"Requires `sites.view`.","responses":{"200":{"description":"The clients.","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ClientReportClient"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createClientReportClient","tags":["client-reports"],"summary":"Add a client, the domains a report covers, who receives it and how often.","description":"⛔ Refused past the clients your plan covers (5 / 25 / 100, plus packs). Empty `domains` means the report covers everything this account tracks. `locale` is the CLIENT's language — the report and its e-mail are written in it. Requires `sites.create`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReportClientInput"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReportClient"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/client-reports/clients/{client_id}":{"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"operationId":"updateClientReportClient","tags":["client-reports"],"summary":"Change a client or its schedule.","description":"Requires `sites.create`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReportClientInput"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReportClient"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"deleteClientReportClient","tags":["client-reports"],"summary":"Remove a client and its reports.","description":"⛔ Its reports go too, and every share link to them stops working. Requires `sites.create`.","responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/client-reports/clients/{client_id}/reports":{"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"makeClientReport","tags":["client-reports"],"summary":"Make a report for this client now.","description":"Counted against this month's reports at once; built in the background from data already collected (no supplier is called) and ready in seconds — poll `GET /v1/client-reports/reports/{report_id}` until `state` is `ready`. A report that fails is not counted. Requires `sites.create`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"send_email":{"type":"boolean","default":false,"description":"E-mail it to the client's recipients when ready."},"period_start":{"type":"string","format":"date"},"period_end":{"type":"string","format":"date"}}}}}},"responses":{"202":{"description":"Opened; building.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReport"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/client-reports/reports":{"get":{"operationId":"listClientReports","tags":["client-reports"],"summary":"Reports made, newest first (100 at most).","description":"Requires `sites.view`.","parameters":[{"name":"client_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The reports.","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ClientReport"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/client-reports/reports/{report_id}":{"parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getClientReport","tags":["client-reports"],"summary":"One report's state, headline figures and share link.","description":"Requires `sites.view`.","responses":{"200":{"description":"The report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReport"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/client-reports/reports/{report_id}/preview":{"parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"locale","in":"query","required":false,"schema":{"type":"string"},"description":"Any enabled language; the report's own by default."}],"get":{"operationId":"previewClientReport","tags":["client-reports"],"summary":"The report as the HTML page its PDF is made from.","description":"Self-contained (styles inline, logo as a `data:` URI, no script). Requires `sites.view`.","responses":{"200":{"description":"The page.","content":{"text/html":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/client-reports/reports/{report_id}/pdf":{"parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"locale","in":"query","required":false,"schema":{"type":"string"},"description":"Any enabled language; the report's own by default."}],"get":{"operationId":"downloadClientReportPdf","tags":["client-reports"],"summary":"Download the report as a PDF.","description":"White-label: the document names your agency and never the platform. Requires `sites.view`.","responses":{"200":{"description":"The PDF.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/client-reports/reports/{report_id}/revoke":{"parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"revokeClientReportShare","tags":["client-reports"],"summary":"Stop the report's share link working, now.","description":"Requires `sites.create`.","responses":{"200":{"description":"Revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReport"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/client-reports/{token}":{"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}},{"name":"locale","in":"query","required":false,"schema":{"type":"string"}}],"get":{"operationId":"viewSharedClientReport","tags":["client-reports"],"summary":"A shared report, as a web page. Unauthenticated.","description":"⛔ **No authentication.** The reader is the agency's client and has no account; the token is the whole authorisation and reaches one report. Revoked, expired and unknown tokens all answer `404`, so the endpoint confirms nothing about which tokens exist. `noindex`, no script, nothing fetched.","security":[],"responses":{"200":{"description":"The report page.","content":{"text/html":{"schema":{"type":"string"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/client-reports/{token}/pdf":{"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}},{"name":"locale","in":"query","required":false,"schema":{"type":"string"}}],"get":{"operationId":"downloadSharedClientReportPdf","tags":["client-reports"],"summary":"A shared report as a PDF. Unauthenticated.","description":"The same rules as the page.","security":[],"responses":{"200":{"description":"The PDF.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/client-reports/clients/{client_id}/logo":{"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"uploadClientReportClientLogo","tags":["client-reports"],"summary":"Upload the client's own logo, printed beside \"Prepared for\" on its reports.","description":"Zinn® SEO stage E5. The same vetting and store as a brand logo (PNG, JPEG or WebP, size and dimension limits). Frozen onto every report made afterwards, so an old report keeps the mark it was sent with. Requires `sites.create`.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["logo"],"properties":{"logo":{"type":"string","format":"binary"}}}}}},"responses":{"201":{"description":"Stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReportClient"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"deleteClientReportClientLogo","tags":["client-reports"],"summary":"Remove the client's logo from future reports.","description":"Requires `sites.create`.","responses":{"200":{"description":"Removed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReportClient"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/client-reports/clients/{client_id}/portal-links":{"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listClientPortalLinks","tags":["client-reports"],"summary":"The client's own page links, newest first.","description":"Zinn® SEO stage E5 (zs-421). Requires `sites.view`.","parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"A page of links.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientPortalLinkPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createClientPortalLink","tags":["client-reports"],"summary":"Make a link to the client's own page of reports, under the agency's brand.","description":"One address the client bookmarks once: every ready report made for them appears there, newest first, with its PDF. Read-only, white label, `noindex`. Optionally expiring (1 to 3650 days); at most 20 live links per client. Requires `sites.create`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","maxLength":120,"description":"The agency's own note. Never shown to the client."},"expires_in_days":{"type":["integer","null"],"minimum":1,"maximum":3650}}}}}},"responses":{"201":{"description":"Made.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientPortalLink"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/client-reports/clients/{client_id}/portal-links/{link_id}":{"parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"link_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"delete":{"operationId":"revokeClientPortalLink","tags":["client-reports"],"summary":"End a client page link now.","description":"The page then answers `404`. Requires `sites.create`.","responses":{"200":{"description":"Revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientPortalLink"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/client-reports/sinks":{"get":{"operationId":"listSeoReportSinks","tags":["client-reports"],"summary":"Google Sheets and Drive connections that receive clients' reports.","description":"Zinn® SEO stage E5. Disconnected ones are left out. Requires `sites.view`.","parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"client_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"A page of sinks.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReportSinkPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"connectSeoReportSink","tags":["client-reports"],"summary":"Start connecting a Google account to receive one client's reports.","description":"Returns Google's consent URL (open it in the same tab). Google asks only for `drive.file` — access to the files this app creates, nothing else in the account — plus the account's e-mail. On return the client's spreadsheet (one tab per figure set plus a history tab, rewritten with every new report) or folder (one PDF per report) is created in that account and the latest report is copied at once. Connecting again replaces the previous connection of the same kind for that client. Requires `sites.create`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["client_id","kind"],"properties":{"client_id":{"type":"string","format":"uuid"},"kind":{"$ref":"#/components/schemas/ClientReportSinkKind"}}}}}},"responses":{"201":{"description":"Pending until Google returns.","content":{"application/json":{"schema":{"type":"object","required":["sink","authorize_url"],"properties":{"sink":{"$ref":"#/components/schemas/ClientReportSink"},"authorize_url":{"type":"string","format":"uri"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/client-reports/sinks/google/callback":{"get":{"operationId":"completeSeoReportSinkGoogle","tags":["client-reports"],"summary":"Where Google returns the browser after consent. Unauthenticated.","description":"⛔ **No authentication** — Google redirects an anonymous browser. Authorised by the signed `state` alone (ten minutes, one sink). Always answers `302` to the app's `/seo/reports?sink=connected|cancelled|scope|failed&client=<id>`; it names nothing else on failure.","security":[],"parameters":[{"name":"state","in":"query","required":true,"schema":{"type":"string"}},{"name":"code","in":"query","required":false,"schema":{"type":"string"}},{"name":"error","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"302":{"description":"Back to the app.","headers":{"Location":{"schema":{"type":"string","format":"uri"}}}}}}},"/v1/client-reports/sinks/{sink_id}":{"parameters":[{"name":"sink_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"delete":{"operationId":"deleteSeoReportSink","tags":["client-reports"],"summary":"Stop copying reports there and forget the Google access.","description":"The spreadsheet or folder stays in the Google account — it is the customer's. ⭐ We delete our copy of the access rather than revoking it at Google, because revoking withdraws the whole account's grant (other clients' connections made with the same account included); the person can remove the app's access in their Google account at any time. Requires `sites.create`.","responses":{"200":{"description":"Disconnected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReportSink"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/client-reports/sinks/{sink_id}/sync":{"parameters":[{"name":"sink_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"syncSeoReportSink","tags":["client-reports"],"summary":"Copy the client's latest report there now.","description":"In the background (a workflow, retried while Google is busy); read the sink again for `last_synced_at` or `failure`. Requires `sites.create`.","responses":{"202":{"description":"Started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReportSink"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/client-portal/{token}":{"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}},{"name":"locale","in":"query","required":false,"schema":{"type":"string"}}],"get":{"operationId":"viewClientPortal","tags":["client-reports"],"summary":"The client's own page of reports. Unauthenticated.","description":"⛔ **No authentication.** The token is the whole authorisation and reaches one client's ready reports. Revoked, expired and unknown tokens all answer `404`. White label, `noindex`, no script, nothing fetched.","security":[],"responses":{"200":{"description":"The page.","content":{"text/html":{"schema":{"type":"string"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/client-portal/{token}/reports/{report_id}":{"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}},{"name":"report_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"locale","in":"query","required":false,"schema":{"type":"string"}}],"get":{"operationId":"viewClientPortalReport","tags":["client-reports"],"summary":"One of the client's reports, as a web page. Unauthenticated.","description":"Only a ready, unrevoked report of THIS link's client; anything else is `404`.","security":[],"responses":{"200":{"description":"The report page.","content":{"text/html":{"schema":{"type":"string"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/client-portal/{token}/reports/{report_id}/pdf":{"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}},{"name":"report_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"locale","in":"query","required":false,"schema":{"type":"string"}}],"get":{"operationId":"downloadClientPortalReportPdf","tags":["client-reports"],"summary":"One of the client's reports as a PDF. Unauthenticated.","description":"The same rules as the page.","security":[],"responses":{"200":{"description":"The PDF.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/seo/agency-overview":{"get":{"operationId":"getAgencySeoOverview","tags":["seo-connect"],"summary":"Every connected Zinn® SEO site of the organization, with scores, alerts and spend.","description":"Zinn® SEO stage E5 (zs-422). One row per connected site (cursor-paginated, newest first): latest rank, site-health, AI-visibility and backlink figures, the newest index-check batch, open SEO Guard incidents, work held for credit, this month's credit spend against the site's cap, and the report client whose domains cover it. `summary` covers the whole organization: balance, 30-day forecast, hold, totals. ⛔ Spend is read from the credit ledger (debits less refunds), never from an audit's `charged_micros`, which is 0 for credit-funded runs. Needs `billing.view` (`org_id` or `X-Zinn-Org`).","parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"org_id","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Uuid"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["active","revoked"]}}],"responses":{"200":{"description":"The sites and the organization summary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencySeoOverview"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/seo-connection/work-log":{"post":{"operationId":"pushSeoWorkLog","tags":["seo-connect"],"summary":"The plugin reports what it did on the site, for the client's report.","description":"Zinn® SEO stage E5. Counts per day and kind (never page titles or content), idempotent on each entry's `id`: a night sent twice is the same rows. At most 500 entries per call; the whole call is refused on the first bad entry, with its index. Feeds the \"Work done on the site\" section of white-label client reports. Needs the `seo.run` scope.","security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["entries"],"properties":{"entries":{"type":"array","minItems":1,"maxItems":500,"items":{"$ref":"#/components/schemas/SeoWorkEntryInput"}}}}}}},"responses":{"200":{"description":"Stored.","content":{"application/json":{"schema":{"type":"object","required":["accepted"],"properties":{"accepted":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/seo-connection/reports":{"get":{"operationId":"getSiteReports","tags":["seo-connect"],"summary":"This site's white-label client report: client, look, schedule, reports, deliveries and client pages.","description":"Zinn® SEO stage P12. Only the client whose domains name THIS site; `client` is `null` until one is set up. Needs the `seo.read` scope.","security":[{"seoSiteConnection":[]}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteReports"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"saveSiteReportClient","tags":["seo-connect"],"summary":"Set up or change this site's client and its report schedule.","description":"Zinn® SEO stage P12. The client's one domain is always the site's own host (a site never reports on another). Same rules and caps as `createClientReportClient`; refused past the plan's clients (`refusal.clientReports.notHeld` without Client Reports). Needs `seo.run`.","security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteReportClientInput"}}}},"responses":{"200":{"description":"Updated (201 when the client was created).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteReports"}}}},"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteReports"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/seo-connection/reports/brand":{"put":{"operationId":"saveSiteReportBrand","tags":["seo-connect"],"summary":"The agency's look on this site's report and e-mail, and the client's own logo.","description":"Zinn® SEO stage P12 — the plugin's white label carried onto the report. Needs a client first (`refusal.clientReportSinks.clientNotFound`). ⛔ A default brand shared with other clients is never edited from one site: the site gets a brand of its own. Logos are vetted like `uploadClientReportBrandLogo`. Needs `seo.run`.","security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteReportBrandInput"}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteReports"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/seo-connection/reports/run":{"post":{"operationId":"makeSiteReport","tags":["seo-connect"],"summary":"Make this site's report now.","description":"Zinn® SEO stage P12. Same as `makeClientReport` for this site's client: counted at once, built in the background, poll `getSiteReport`. Needs `seo.run`.","security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"send_email":{"type":"boolean","default":false},"period_start":{"type":"string","format":"date"},"period_end":{"type":"string","format":"date"}}}}}},"responses":{"202":{"description":"Opened; building.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReport"}}}},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/seo-connection/reports/{report_id}":{"parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getSiteReport","tags":["seo-connect"],"summary":"One of this site's reports (poll until `ready`).","description":"Zinn® SEO stage P12. 404 for a report of any other client. Needs `seo.read`.","security":[{"seoSiteConnection":[]}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReport"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/seo-connection/reports/sinks":{"post":{"operationId":"connectSiteReportSink","tags":["seo-connect"],"summary":"Deliver this site's reports into a Google Sheet or Drive folder.","description":"Zinn® SEO stage P12. Answers Google's consent address. `return_url` (https, on THIS site only; anything else is ignored) is where Google's answer sends the browser, with `zseo_sink=connected|cancelled|scope|failed` added. Needs `seo.run`.","security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kind"],"properties":{"kind":{"$ref":"#/components/schemas/ClientReportSinkKind"},"return_url":{"type":"string","format":"uri","maxLength":500}}}}}},"responses":{"201":{"description":"Pending until Google answers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReportSinkStart"}}}},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/seo-connection/reports/sinks/{sink_id}":{"parameters":[{"name":"sink_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"delete":{"operationId":"disconnectSiteReportSink","tags":["seo-connect"],"summary":"Stop delivering into that Sheet or folder and forget the grant.","description":"Zinn® SEO stage P12. Never revokes at Google (the account's other grants stay). Needs `seo.run`.","security":[{"seoSiteConnection":[]}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReportSink"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/seo-connection/reports/sinks/{sink_id}/sync":{"parameters":[{"name":"sink_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"syncSiteReportSink","tags":["seo-connect"],"summary":"Deliver the latest report into that Sheet or folder now.","description":"Zinn® SEO stage P12. Refused unless the delivery is active (`refusal.clientReportSinks.notActive`). Needs `seo.run`.","security":[{"seoSiteConnection":[]}],"responses":{"202":{"description":"Started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientReportSink"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/seo-connection/reports/portal-links":{"post":{"operationId":"createSitePortalLink","tags":["seo-connect"],"summary":"A read-only page for the client, no login (zs-421).","description":"Zinn® SEO stage P12. Same as `createClientPortalLink` for this site's client. Needs `seo.run`.","security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","maxLength":120},"expires_in_days":{"type":["integer","null"],"minimum":1}}}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientPortalLink"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/seo-connection/reports/portal-links/{link_id}":{"parameters":[{"name":"link_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"delete":{"operationId":"revokeSitePortalLink","tags":["seo-connect"],"summary":"Turn a client page off now.","description":"Zinn® SEO stage P12. Needs `seo.run`.","security":[{"seoSiteConnection":[]}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientPortalLink"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/plugin-affiliates":{"get":{"operationId":"listResellerPluginAffiliates","tags":["reseller"],"summary":"The Pro-plugin affiliate programmes a reseller can earn commission from.","description":"Every active, visible Freemius affiliation programme across our Pro plugins, with the commission Freemius holds today (never a typed figure) and where to apply. Licences sold through these programmes are sold under the Zinn® brand; the reseller earns the commission (owner ruling 2026-11-13, \"A: affiliate link\"). `complete` is false only when Freemius was asked and could not answer, so a short list is never read as \"none\". A product Freemius says has no programme is in `without_programme`; one that cannot be checked (no key pair, e.g. a bundle) is in `skipped` with its reason. Neither makes the list incomplete. Cached for an hour. 404 when the org has no reseller programme. Requires `reseller.view`.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The programmes.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerPluginAffiliates"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/program":{"get":{"operationId":"getResellerProgram","tags":["reseller"],"summary":"The org's wholesale reseller agreement.","description":"Returns 404 when the org is not enrolled — \"not a reseller\" is a state the screen renders, and the same 404 is what an out-of-scope org gets, so this is not an existence oracle. Requires `reseller.view`.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The wholesale programme.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerProgram"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"applyForResellerProgram","tags":["reseller"],"summary":"Apply to resell Zinn® hosting to your own clients.","description":"Creates the programme in `pending`; a human at Zinn® activates it. Idempotent — applying twice returns the existing programme with 200 rather than a second row. Requires `reseller.manage`.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The programme that already existed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerProgram"}}}},"201":{"description":"The new, pending programme.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerProgram"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateResellerProgram","tags":["reseller"],"summary":"Change your own wholesale settings.","description":"Billing anchor day and the default markup applied to plans you have not priced explicitly. ⛔ `status` is not settable here — approving yourself as a reseller is not a self-service act. Requires `reseller.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerProgramUpdate"}}}},"parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The updated programme.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerProgram"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/overview":{"get":{"operationId":"getResellerOverview","tags":["reseller"],"summary":"Everything you have — every URL, credential and setting, in one read.","description":"The reseller reference card: the address your clients sign in at, the nameservers you hand them, your sending domain, your API base and key counts, where your clients' support goes, which product lines you sell, how many languages their panel offers, and how many client accounts you run. Every block carries the route that changes it, and the gaps (`gateway_gap`, `invoicing_gap`, `support.gap`) are reported as booleans so a screen can say what is missing rather than render a blank field. Requires `reseller.view`.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"Your reseller reference card.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerOverview"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/lines":{"get":{"operationId":"listResellerLines","tags":["reseller"],"summary":"Which product lines you sell.","description":"Every sellable product line, not only the ones you have decided about — a line you have never touched is on, so the list is what you offer today. `plan_count` is how many plans sit in the line and `active_client_count` how many of your clients hold a live subscription in it. Requires `reseller.view`.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"Your product lines.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerLineList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setResellerLines","tags":["reseller"],"summary":"Turn product lines on or off for your clients.","description":"Send the complete set of line codes you are turning **off**; anything not listed is on. A line that is off cannot be bought by your clients through any route — it is hidden from their catalogue and refused at the basket, not merely unadvertised. Clients already on a plan in that line keep it and keep renewing; only new orders are refused. You cannot turn off every line at once — ask us to pause your programme instead. Requires `reseller.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerLineWrite"}}}},"parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"Your product lines, as stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerLineList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/languages":{"get":{"operationId":"getResellerLanguages","tags":["reseller"],"summary":"The languages your clients' panel offers.","description":"Every language the panel ships in, with `offered` saying whether your clients see it. All of them are included in your programme at no extra cost; narrowing the list is a presentation choice for a reseller selling into one market. `offers_all: true` means you have made no choice and your clients get the full set. Requires `reseller.view`.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"Your client language policy.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerLanguagePolicy"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"setResellerLanguages","tags":["reseller"],"summary":"Choose the languages and the default your clients start in.","description":"`locales` replaces the list your clients may choose from; send an empty array to go back to offering every language. `default_locale` is what a new client account starts in and must be one you offer — your clients can still change their own language afterwards. A code we do not ship is refused rather than dropped. Requires `reseller.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerLanguageWrite"}}}},"parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"Your client language policy, as stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerLanguagePolicy"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/currencies":{"get":{"operationId":"getResellerCurrencies","tags":["reseller"],"summary":"The currencies your clients are quoted in.","description":"Every currency we can charge in, with `offered` saying whether your clients may be quoted in it. `offers_all: true` means you have made no choice and your clients get the full set — which is the state every programme starts in. `sell_in_currency` is what **you** are priced and settled in, which is a different question from what your customers browse in, and it is served only here and never to your clients. `switcher: false` removes the currency control from their panel entirely, so every one of your clients is quoted in `default_currency`. Requires `reseller.view`.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"Your client currency policy.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerCurrencyPolicy"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"setResellerCurrencies","tags":["reseller"],"summary":"Choose the currencies, the default, and what you sell in.","description":"`currencies` replaces the list your clients may be quoted in; send an empty array to go back to offering every currency we can charge. `default_currency` is what a client is quoted in before they choose and must be one you offer. `sell_in_currency` is what you are settled in and is deliberately **not** required to be one of them — a reseller may be paid in one currency and sell in others. `switcher: false` hides the control from your clients. A currency no payment gateway can capture is refused rather than dropped, because a currency we can display and cannot charge is a checkout that fails at the last step. Requires `reseller.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerCurrencyWrite"}}}},"parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"Your client currency policy, as stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerCurrencyPolicy"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/session/offering":{"get":{"operationId":"getSessionOffering","tags":["localization"],"summary":"The currencies and languages this viewer may be shown.","description":"What a storefront, checkout or panel shell may offer the person looking at it, already resolved through their provider's policy. The viewer is identified two ways, in this order: **who they are**, when they are signed in; otherwise **where they are standing**, from the reseller panel hostname in the browser's `Origin`. So an anonymous visitor on a reseller's branded panel gets that reseller's offering, and everybody else — an anonymous visitor to Zinn®, an unrecognised origin, a hostname we no longer serve — gets the platform answer: every currency we can charge and every language we ship. Signing in always wins over the origin, because pricing follows the organisation the rest of the API scopes your reads by. `restricted` says a reseller stands between this viewer and Zinn®; read it rather than inferring one from list lengths, because a reseller who has narrowed nothing returns exactly the same lists as no reseller at all. `currency_switcher: false` means render no control, not a disabled one. Never cached.","responses":{"200":{"description":"What this viewer may be offered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionOffering"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/vendor-policy":{"get":{"operationId":"getResellerVendorPolicy","tags":["reseller"],"summary":"Whose SEO data accounts your clients' checks run on.","description":"Your choice of running client SEO and indexing data on your **own** Majestic / DataForSEO keys — which costs you nothing with us — or on Zinn®'s accounts as a metered monthly add-on. `client_overrides` lists every one of your clients with the cap you have set for them; a client you have never touched appears with `daily_lookup_cap: null`, meaning they get whatever their plan grants. `monthly_pool_micros` is read-only: it is a commercial term of your programme, and `null` means no pool has been set at all — which is **unbounded**, not zero. Requires `reseller.view`.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"Your vendor data policy.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerVendorPolicy"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"setResellerVendorPolicy","tags":["reseller"],"summary":"Switch between your own vendor keys and Zinn®'s metered pool.","description":"`own_keys` runs your clients' SEO and indexing lookups on credentials you connect yourself, and nothing is metered against you here. `platform_pool` runs them on Zinn®'s accounts against the monthly allowance in your programme; when that allowance is spent, further **paid** checks pause for your clients until the month rolls or the pool is raised — nothing is cancelled, no history is lost, and your clients keep seeing the last reading already paid for. Requires `reseller.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerVendorPolicyWrite"}}}},"parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"Your vendor data policy, as stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerVendorPolicy"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/vendor-policy/clients/{orgId}":{"put":{"operationId":"setResellerClientVendorPolicy","tags":["reseller"],"summary":"Cap or pause one client's paid data checks.","description":"Per-client control inside your own pool. `daily_lookup_cap` can only ever **reduce** what that client's plan already grants — a number above their plan allowance has no effect, because the smaller of the two is what is applied. `billed_data_enabled: false` stops that client drawing on your pool at all; their plan, their sites and their history are untouched and they still see readings already paid for. An org id that is not one of your clients is a 404. Requires `reseller.manage`.","parameters":[{"name":"orgId","in":"path","required":true,"description":"The client organization to cap. Must be one of your own clients.","schema":{"$ref":"#/components/schemas/Uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerClientVendorWrite"}}}},"responses":{"200":{"description":"Your vendor data policy, including the updated client row.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerVendorPolicy"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/edge-policy":{"get":{"operationId":"getResellerEdgePolicy","tags":["reseller"],"summary":"Which CDN and DNS networks your clients can be placed on.","description":"Every network your clients could use, each with whether you currently offer it. The list is what **your** pool serves: if you have connected your own CDN or DNS accounts, your clients are placed on those and this lists them; otherwise it lists Zinn®'s pool. A network you have never touched comes back `enabled: true` — the switches record your exceptions, so a new reseller offers everything and a network Zinn® adds later is live for you with nothing to do. Requires `reseller.view`.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"Every network you could offer, with whether you do.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerEdgePolicy"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setResellerEdgePolicy","tags":["reseller"],"summary":"Turn CDN or DNS networks on and off for your clients.","description":"Send the **complete** set of networks you are turning off; anything absent is on. This is a placement rule, not a display preference: a network you turn off disappears from your clients' site-creation picker, is refused if they name it directly, and is not used when Zinn® places a new site. **Sites already running are never moved** — a live site keeps the network it is on, so nothing goes down when you change what you offer. You can only narrow what your pool serves, never add a network, and turning off every network in a category is refused because your clients could then create no sites at all. Requires `reseller.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerEdgePolicyWrite"}}}},"parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"Your edge policy, as stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerEdgePolicy"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/edge-policy/clients/{orgId}":{"get":{"operationId":"getResellerClientEdgePolicy","tags":["reseller"],"summary":"Which networks one client of yours can be placed on.","description":"The same list as your own policy, narrowed to one client. A network you have turned off for everybody reports `enabled: false` with `inherited_off: true`, so you can see that the switch is being decided above this screen rather than appearing broken. An org id that is not one of your clients is a 404. Requires `reseller.view`.","parameters":[{"name":"orgId","in":"path","required":true,"description":"The client organization. Must be one of your own clients.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"That client's networks.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerEdgePolicy"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setResellerClientEdgePolicy","tags":["reseller"],"summary":"Turn networks on and off for one client.","description":"Per-client control inside what you already offer. This can only narrow **further**: a network you have turned off for everybody stays off for this client whatever you send here. Unlike your own policy, turning off every network for one client is allowed — that client simply creates no new sites — and their running sites are untouched. An org id that is not one of your clients is a 404. Requires `reseller.manage`.","parameters":[{"name":"orgId","in":"path","required":true,"description":"The client organization. Must be one of your own clients.","schema":{"$ref":"#/components/schemas/Uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerEdgePolicyWrite"}}}},"responses":{"200":{"description":"That client's networks, as stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerEdgePolicy"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/vendor-usage":{"get":{"operationId":"getResellerVendorUsage","tags":["reseller"],"summary":"What your clients drew from Zinn®'s vendor accounts this month.","description":"Spend for your whole client base this calendar month, against your pool, broken down by vendor. Always read `month_is_floor` and `ceiling_is_floor` before showing a total: some vendors bill prepaid units whose per-unit cost is not priced here, so when a flag is `true` the money figure is a **minimum** and `month_unpriced_calls` counts what it excludes. `ceiling_micros` is the most your client base could draw in a month if every client used every allowance their plan includes — it does not depend on how busy this month happened to be. Available even when your pool is spent. Requires `reseller.view`.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"This month's vendor draw for your client base.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerVendorUsage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/ai/credits":{"get":{"operationId":"getResellerAiCredits","tags":["reseller"],"summary":"Your AI credit pool, your prices, and what your clients hold.","description":"One request for the whole screen: the pool you buy from Zinn® and sell on, every pack priced three ways (Zinn®'s list, your wholesale cost, what your clients pay), and each client's own AI balance.\n\nYour pool is a balance on the same AI credit ledger your clients use — there is no separate pool store, so `balance_micros` here and a client's balance are the same kind of number and reconcile against one statement.\n\n`retail_source` says whether a price is yours (`price_list`) or Zinn®'s default (`default`). Requires `reseller.view`.","parameters":[{"name":"currency","in":"query","required":false,"description":"ISO-4217 code to price in. Defaults to USD.","schema":{"type":"string","minLength":3,"maxLength":3}},{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The pool, the price ladder and the clients.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerAiCredits"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/ai/credits/settings":{"put":{"operationId":"setResellerAiCreditSettings","tags":["reseller"],"summary":"When to warn you your pool is low, and whether to refill it automatically.","description":"`low_pool_threshold_micros` of `0` means \"work it out from what I actually allocate\" — two allocations' worth of head-room, which means the same thing to a reseller moving thousands and to one with three clients.\n\n`auto_buy_enabled` is **off** unless you switch it on: it charges your card without anybody clicking, so it is never a default. `auto_buy_monthly_cap_micros` of `0` means four packs' worth of the pack you chose — a cooldown is not a ceiling.\n\nSaving clears any standing low-pool notice, so a new threshold warns you again at the new line. Requires `reseller.manage`.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to.","schema":{"$ref":"#/components/schemas/Uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerAiCreditSettings"}}}},"responses":{"200":{"description":"The saved settings, with the resolved threshold.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerAiCreditSettingsResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/ai/credits/prices":{"put":{"operationId":"setResellerAiCreditPrices","tags":["reseller"],"summary":"What YOUR clients pay for AI credit.","description":"Accepts the whole ladder in one request, so re-pricing four rungs is one change rather than four.\n\nA `price_minor` of `null` **resets that pack to Zinn®'s price** and deletes your override — which is not the same as copying our number: an override stops tracking our list the moment we re-price, and an absent row cannot go stale. A zero or a negative price is refused rather than treated as a reset, because a magic value in a money API deletes a price by fat-finger. Requires `reseller.manage`.","parameters":[{"name":"currency","in":"query","required":false,"description":"ISO-4217 code the returned ladder is priced in. Defaults to USD.","schema":{"type":"string","minLength":3,"maxLength":3}},{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to.","schema":{"$ref":"#/components/schemas/Uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ResellerAiPriceWrite"}}}}},"responses":{"200":{"description":"The ladder after the change.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["packs"],"properties":{"packs":{"type":"array","items":{"$ref":"#/components/schemas/ResellerAiPack"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/ai/credits/clients/{org_id}":{"post":{"operationId":"adjustClientAiCredit","tags":["reseller"],"summary":"Give one of your clients AI credit, or take unspent credit back.","description":"Moves credit between your pool and one client's balance in one transaction: a positive `delta_micros` gives, a negative one takes back.\n\nA client who has already **spent** the credit cannot be taken below zero — the request is refused and names what is left. A client that is not yours is refused with the same code and message as one that does not exist, so this cannot be used to discover whether an organization id is real.\n\nThis is the manual route, for a trial, a goodwill gesture, or a bundle sold offline. The self-serve route is your client buying a pack from you, which draws on the same pool. Requires `reseller.manage`.","parameters":[{"name":"org_id","in":"path","required":true,"description":"The client organization whose balance moves. Must be one of yours.","schema":{"$ref":"#/components/schemas/Uuid"}},{"name":"org_id","in":"query","required":false,"description":"Which of YOUR organizations is acting. Not the client.","schema":{"$ref":"#/components/schemas/Uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerAiClientAdjustment"}}}},"responses":{"200":{"description":"Both balances afterwards.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerAiClientAdjustmentResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/prices":{"get":{"operationId":"listResellerPrices","tags":["reseller"],"summary":"Your price list — what YOUR clients pay.","description":"Every sellable plan, not only the rows you have authored, with Zinn®'s list price and your wholesale cost alongside so the margin is visible without a second request. `price_source` says whether a number is yours (`price_list`) or derived from list by your default markup (`markup`). Requires `reseller.view`.","parameters":[{"name":"currency","in":"query","required":false,"description":"ISO-4217 code to price in. Defaults to USD.","schema":{"type":"string","minLength":3,"maxLength":3}},{"name":"interval","in":"query","required":false,"description":"Billing interval. Defaults to monthly.","schema":{"type":"string"}},{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The price list.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerPriceList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setResellerPrice","tags":["reseller"],"summary":"Set your own price for one plan.","description":"Upserts one row of your price list, keyed on (plan, interval, currency). Editing it never re-prices a client already sold — their subscription captured the price at purchase. Requires `reseller.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerPriceWrite"}}}},"parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The stored price.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerPrice"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/statements":{"get":{"operationId":"listWholesaleStatements","tags":["reseller"],"summary":"What you owe Zinn®, per period.","description":"One statement per period **per currency** — there is no FX conversion on this path, because inventing a rate for a bill turns every month's rounding difference into a dispute. Requires `reseller.view`.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The statements.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WholesaleStatementList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/statements/{statementId}":{"parameters":[{"name":"statementId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"get":{"operationId":"getWholesaleStatement","tags":["reseller"],"summary":"One statement, with the line for every client.","description":"Each line snapshots the client, the plan, Zinn®'s list price, the discount that was applied and the result — so the charge stays explainable after the rate changes. Requires `reseller.view`.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The statement and its lines.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WholesaleStatement"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/tax-registrations":{"get":{"operationId":"listResellerTaxRegistrations","tags":["reseller"],"summary":"Your own VAT registrations.","description":"The dated VAT/tax registrations held against **your** company — the ones that decide what your clients are charged and which number appears on the invoices we raise in your name. Until you add one, your supplies are treated as `not_registered` and no VAT is charged, which is the correct treatment for a business under its country's registration threshold. `meta.company_required` is `true` when you have not given us your company details yet, because a registration belongs to a company. Requires `reseller.view`.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"Your VAT registrations, newest first within each jurisdiction.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerTaxRegistrationListEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"addResellerTaxRegistration","tags":["reseller"],"summary":"Add one of your VAT registrations.","description":"**This starts charging VAT immediately.** There is no \"record the number but do not charge yet\" state: the registration row *is* the switch, so from `effective_from` your clients are charged at the rate for the supply and your number is printed on their invoices. The number is yours and the liability is yours — we do not hold it for approval. We check only that the value could be a VAT number at all; we do not verify it exists. Two registrations in force for one jurisdiction at once is a 422, because the rate charged would then depend on row order rather than on a decision — end the old one first. Requires `reseller.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerTaxRegistration"}}}},"parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"201":{"description":"Added, and in force from its effective date.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerTaxRegistrationEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"You have not saved your company details yet, so there is nothing to register against.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/tax-registrations/{registration_id}":{"delete":{"operationId":"removeResellerTaxRegistration","tags":["reseller"],"summary":"End or remove one of your VAT registrations.","description":"A registration that has not started yet is **deleted**; one that is or has been in force is **ended** today, and `outcome` says which happened. Ending rather than deleting is not a nicety: invoices already issued froze your number and their tax treatment at the moment of issue, and a VAT return for that period is computed from rows that reference this one. Requires `reseller.manage`.","parameters":[{"name":"registration_id","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}},{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"Ended or deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerTaxRegistrationRemovalEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/legal-entity":{"get":{"operationId":"getResellerLegalEntity","tags":["reseller"],"summary":"The company details your clients' invoices are issued under.","description":"Your OWN legal identity — the name, address and VAT number that appear on a document your client files with their accountant. `data` is `null` when you have not given them to us yet, which is the state the screen is built to render; until then no invoice can be raised to a client of yours, because falling back to Zinn®'s entity would tell them exactly who their supplier buys from. Requires `reseller.view`.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"Your company details, or `null` if none are held.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerLegalEntityEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"saveResellerLegalEntity","tags":["reseller"],"summary":"Save the company details your clients' invoices are issued under.","description":"Creates the entity the first time and updates it afterwards — never a second row. `number_prefix` is **globally unique across every company on the platform** because it is what keeps two issuers' invoice numbers apart, so a value already in use is a 409; and it **freezes once an invoice has been issued** under this company, because releasing it would let the next taker mint numbers you have already issued. Everything else stays editable — a company that moves office must be able to say so. Requires `reseller.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerLegalEntity"}}}},"parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerLegalEntityEnvelope"}}}},"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerLegalEntityEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The invoice number prefix is already used by another company, or it is frozen because invoices have been issued under this one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/gateways":{"get":{"operationId":"listResellerGateways","tags":["reseller"],"summary":"The payment gateways you can connect, and which you have.","description":"Your OWN Stripe / PayPal / NOWPayments account — not Stripe Connect, not a sub-account of Zinn®'s. The response carries the whole connect form: every input, what it is, where in that provider's own console to find it, and the webhook URL to paste back. ⛔ It never carries a credential. Requires `reseller.view`.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The connectable gateways.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerGatewayList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/gateways/{code}":{"parameters":[{"name":"code","in":"path","required":true,"description":"The gateway code — `stripe`, `paypal` or `nowpayments`.","schema":{"type":"string"}}],"post":{"operationId":"connectResellerGateway","tags":["reseller"],"summary":"Connect or re-key your own payment gateway.","description":"The credentials are checked against the provider with a real authenticated call before anything is stored, then written to Vault — never to a database row, a log line, an audit entry or an error message. With `validate_only` the check runs and nothing is stored, returning 200 **even when the credentials are rejected**, because that is the answer being asked for. Requires `reseller.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerGatewayConnect"}}}},"parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The check result (validate-only; nothing was stored).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayProbe"}}}},"201":{"description":"Connected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayProbe"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"delete":{"operationId":"disconnectResellerGateway","tags":["reseller"],"summary":"Disconnect your payment gateway.","description":"Refused with 409 when it is your only gateway and a statement is outstanding: charging then fails closed rather than falling back to Zinn®'s merchant account, so disconnecting would silently stop you billing anyone. Requires `reseller.manage`.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"204":{"description":"Disconnected."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/wallet":{"get":{"operationId":"getClientWallet","tags":["reseller"],"summary":"Your credit balance with your provider.","description":"The float your provider holds for you, and your statement of account. ⛔ This is **your provider's** money, not Zinn®'s: a top-up settles into their payment account and the balance is a debt they owe you. Two balances are returned and they can differ — `balance_minor` is what you are **owed**, `spendable_minor` is what you can spend today. They come apart when your provider's reseller programme is suspended: the deposit is still yours, but nothing is being delivered against it.\n\n⭐ **Answers for both providers.** If your account is not managed by a reseller, this returns the credit you hold with **Zinn®** instead, and `provider` says which — a reseller float can be sent back to the card it came from, Zinn® credit never can. This used to be a 404, which the dashboard rendered as *\"This account does not use credit\"*; that was true only because there was no way to buy any. Requires `billing.view`.","parameters":[{"name":"currency","in":"query","required":false,"description":"ISO-4217 code. A wallet is per-currency — a EUR float does not pay a USD invoice — so an unknown code is a 422 rather than a silent fallback.","schema":{"type":"string","minLength":3,"maxLength":3}},{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The balance and recent movements.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientWallet"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/wallet/top-ups":{"get":{"operationId":"listClientWalletTopUps","tags":["reseller"],"summary":"Your credit top-ups.","description":"Requires `billing.view`.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The top-ups.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientWalletTopUpList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createClientWalletTopUp","tags":["reseller"],"summary":"Add credit to your balance.","description":"Charged on **your provider's own** payment account when you are a reseller's client, and on Zinn®'s when you buy directly. The credit is written when the payment **captures**: a crypto invoice awaiting confirmation (`pending`), a card awaiting 3-D Secure or a PayPal payment awaiting your approval at `action_url` (`requires_action`) returns 201 with that status and **no** balance change, because the money has not arrived. An approved PayPal top-up is captured and credited when PayPal reports the approval. 422 when your provider has not finished connecting a payment account — the charge is refused rather than settled somewhere else. 422 `PAYMENT_METHOD_REQUIRED` (refusal `refusal.wallet.topUpPaymentStep`) when a card top-up is bought from Zinn® with no saved card: nothing is written and no gateway is asked. Show the customer a choice of card, PayPal or crypto for the same amount, then repeat the request on the chosen `gateway` (1108#13).\n\n⚖️ **Credit bought from Zinn® is never refundable, including on account closure, and never expires** (owner ruling 2026-08-22). Call `GET /v1/wallet/top-ups/estimate` first and show the customer what they will actually receive — on a crypto rail that can be less than the amount quoted, because we credit what settles rather than what was asked for. Requires `billing.payment.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientWalletTopUpCreate"}}}},"parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"201":{"description":"The top-up, with the status the gateway gave it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientWalletTopUp"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/wallet/top-ups/estimate":{"get":{"operationId":"estimateWalletTopUp","tags":["reseller"],"summary":"What a top-up will actually credit, before you pay.","description":"The **pre-purchase disclosure**. Returns what we expect to put in your balance for a given amount and rail, and whether that figure can still move.\n\n⚖️ Zinn® credits **what actually settles**, net of fees, at the real settlement rate (owner ruling 2026-08-22). On a card that is exactly the amount you asked for. On a crypto rail it can be less, because the value of the coin moves between the quote and the confirmation and the network takes a fee — so `is_estimate` is `true` and the figure is indicative.\n\n⛔ A screen that renders `expected_credit_minor` without also reading `is_estimate` turns a disclosure into a promise. `refundable` and `expires` are both always `false` and are returned here, at the point of sale, because that is where a non-refundable purchase has to be disclosed. Requires `billing.view`.","parameters":[{"name":"amount_minor","in":"query","required":true,"description":"The amount you want to add, in integer minor units.","schema":{"type":"integer","format":"int64","minimum":1}},{"name":"currency","in":"query","required":false,"description":"ISO-4217 code. A wallet is per-currency; an unknown code is a 422.","schema":{"type":"string","minLength":3,"maxLength":3}},{"name":"gateway","in":"query","required":false,"description":"Which rail — `stripe`, `paypal` or `nowpayments`. Determines whether the estimate is exact or indicative; it is the crypto rail that settles at a moving rate.","schema":{"type":"string","maxLength":32}},{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"What this top-up would credit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletTopUpEstimate"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/wallet/upcoming-charges":{"get":{"operationId":"getWalletUpcomingCharges","tags":["reseller"],"summary":"Charges already committed against your Zinn® credit and Credit balance.","description":"⚖️ Owner, 2026-11-13: *\"show the TOTAL currently committed or recurring against the wallet (upcoming charges, with due dates)\"*. Lists every recurring charge due within `horizon_days`: US SMS registration months and Zinn® Ads tracking-number months (paid from **Zinn® credit**, no card fallback: when short at the due date they are held and then stop), and engine-billed subscription renewals (paid from the **Credit balance** first, the saved card for the rest; their amount is the list price before tax and coupons, so `estimate` is true). The two balances are totalled separately and never added together; `shortfall_minor` is what each balance lacks to cover what is due. Read-only, no vendor call. Requires `billing.view`.","parameters":[{"name":"currency","in":"query","required":false,"description":"ISO-4217 code of the Credit balance to compare against.","schema":{"type":"string","minLength":3,"maxLength":3}},{"name":"horizon_days","in":"query","required":false,"description":"How many days ahead to look (1-366, default 35).","schema":{"type":"integer","minimum":1,"maximum":366,"default":35}},{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The committed charges and the per-balance totals.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletUpcomingCharges"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/wallet/settings":{"get":{"operationId":"getWalletSettings","tags":["reseller"],"summary":"Your low-balance warning and automatic top-up.","description":"⭐ Answers `200` with defaults for an account that has never saved any, rather than `404`: a settings screen that 404s before first save forces the client to treat \"absent\" and \"off\" as two states and then render them identically anyway.\n\n`low_balance_threshold_minor` of `0` means the warning is **off**, not \"warn me at zero\" — a customer who never chose a threshold holds `0`, and treating that as a threshold would warn every account with an empty wallet. Requires `billing.view`.","parameters":[{"name":"currency","in":"query","required":false,"description":"ISO-4217 code. Settings are per-currency because balances are: an account quoted in EUR and USD holds two balances that are never mixed, so one threshold would be a threshold against a number that does not exist.","schema":{"type":"string","minLength":3,"maxLength":3}},{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The current settings, or their defaults.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletSettings"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"updateWalletSettings","tags":["reseller"],"summary":"Set your low-balance warning and automatic top-up.","description":"⚖️ Both settings are the customer's to choose — *\"notificaitons when low they can set\"* and *\"can they set the wallet to auto topup before payments are due so they can be taken from the waller (fallback to card/paypal or whateer they have setup)\"* (owner, 2026-08-22).\n\nThe fallback in that sentence is already how checkout works: credit is spent first and the remainder goes to the card, so an automatic top-up that has not fired yet never blocks a payment. Switching automatic top-up on without an amount is a 422.\n\n⭐ Saving **clears the disarm counter**. A standing instruction switches itself off after three consecutive failures, and a customer arriving at this screen after being told so has just fixed something — leaving them disarmed would mean their fix silently did nothing. Requires `billing.payment.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletSettingsUpdate"}}}},"parameters":[{"name":"currency","in":"query","required":false,"description":"ISO-4217 code these settings apply to.","schema":{"type":"string","minLength":3,"maxLength":3}},{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The saved settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletSettings"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/dunning":{"get":{"operationId":"getResellerDunning","tags":["reseller"],"summary":"Your own dunning ladder, and its history.","description":"The schedule your clients are chased on when a payment fails - your retry timings, your grace period, your suspension threshold and your own reminder copy. If you have not published one, this answers `using_platform_default: true` with the rungs your clients actually climb today, because the platform ladder is the fallback. It never returns an empty ladder: that would describe a system in which nobody is chased at all. Requires `reseller.view`.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here - otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The active ladder and every version of it.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerDunning"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"publishResellerDunning","tags":["reseller"],"summary":"Publish the next version of your ladder.","description":"Publishing, never editing. A ladder changed while customers are halfway up it must not change what those customers were already told, so every save is a new immutable version and runs already climbing keep the one they started on. A 422 carries the validator's own sentence, naming which rung is wrong and why - a `warn` whose grace disagrees with the next rung would tell a customer a deadline that is not the deadline. Requires `reseller.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerDunningPublish"}}}},"parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here - otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"201":{"description":"The published version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerDunning"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/dunning/reset":{"delete":{"operationId":"resetResellerDunning","tags":["reseller"],"summary":"Go back to the platform's default ladder.","description":"Deactivates your ladder. The version history is kept, never deleted - it is the answer to \"why was I suspended on the 14th\" months later, and destroying it would remove the evidence for a decision the platform actually made. Runs already in flight are unaffected: a run pins its version, so turning yours off stops the next client being put on it and does not re-time anyone mid-ladder. Requires `reseller.manage`.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here - otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"204":{"description":"Reverted to the platform ladder."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/client-wallets":{"get":{"operationId":"listResellerClientWallets","tags":["reseller"],"summary":"Every client float you are holding.","description":"A **liability register**: the sum of these balances is money your clients have paid you and you have not yet delivered service for. It is on your books, not Zinn®'s. ⛔ Totals are **per currency** and never summed across them. Requires `reseller.view`.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The client floats and what is held per currency.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientWalletSummary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"openResellerClientWallet","tags":["reseller"],"summary":"Open a client's float, or add credit to it.","description":"Records a deposit you took **outside** our gateway — a bank transfer, cash, an invoice settled directly — or a goodwill credit, or a balance migrated in from whatever you used before. It lands as an adjustment on the client's ledger with your reason on the line they read. Requires `reseller.manage`.\n\n⛔ This is the only way to bring a client's float into existence. Every other write on this surface needs a `wallet_id`, and until this endpoint a wallet only appeared once the client had paid by card — so a reseller could see an empty liability register with no control on it, which is what was measured on production on 2026-08-16 (`ClientWallet` held zero rows estate-wide).\n\n⛔ It is deliberately **not** a card charge. `POST /v1/wallet/top-ups` is that, it is the client's own action, and it settles into your gateway. Money that never moved through a gateway must not be recorded as though it had.\n\nA client that does not bill back to you is a **404**, never a 403 — this endpoint must not become a way to discover who else resells to whom.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred.","schema":{"$ref":"#/components/schemas/Uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerClientWalletOpen"}}}},"responses":{"201":{"description":"The client's float after the credit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientWallet"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/client-wallets/{walletId}/top-ups":{"parameters":[{"name":"walletId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"get":{"operationId":"listResellerClientWalletTopUps","tags":["reseller"],"summary":"The deposits on one client's balance.","description":"What a refund is chosen from. A wallet belonging to another reseller answers 404, never 403, so this is not an existence oracle. Requires `reseller.view`.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The deposits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientWalletTopUpList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/client-wallets/{walletId}/adjustments":{"parameters":[{"name":"walletId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"adjustClientWallet","tags":["reseller"],"summary":"Correct a client's balance.","description":"Signed — positive credits, negative takes back. ⛔ A negative adjustment that would put the client below zero is refused with 422 naming what is available: you may correct your own mistake, you may not push a customer into debt. `reason` is required and the client sees it on their statement. A wallet belonging to another reseller answers 404, never 403, so this is not an existence oracle. Requires `reseller.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientWalletAdjustment"}}}},"parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"201":{"description":"The wallet after the adjustment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientWallet"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/client-wallets/top-ups/{topUpId}/refunds":{"parameters":[{"name":"topUpId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"refundClientWalletTopUp","tags":["reseller"],"summary":"Send a deposit back to the card it came from.","description":"⛔ **Back the way it came.** There is deliberately no \"refund to wallet\" option: a top-up already *is* wallet credit, so crediting it again would be a no-op wearing the name of a remedy, and wallet credit is an opt-in under consumer law rather than something silence can agree to. The balance is debited first and the gateway refund taken second; if the client has already spent the deposit the refund is refused with 422, and if the gateway declines it the balance is put back. Requires `reseller.manage`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientWalletRefund"}}}},"parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The top-up, with what has now been refunded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientWalletTopUp"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/support/tickets":{"get":{"operationId":"listResellerSupportTickets","tags":["reseller"],"summary":"Your clients' support tickets — your own support desk.","description":"Every ticket one of your clients opened (from their dashboard, by e-mail to your support address, or through their AI assistant). These tickets reach YOU, not us: you answer them here, in your brand, and you may escalate one to us when you need platform support. Tickets about a service only we run for your client (a held invoice, an AI Move, Code Care) stay with us and are not listed here. Newest first, cursor-paginated. Requires `reseller.view`.","parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here.","schema":{"$ref":"#/components/schemas/Uuid"}},{"name":"status","in":"query","required":false,"description":"Narrow to one status; `active` means open or pending.","schema":{"type":"string","enum":["active","open","pending","solved","closed"]}}],"responses":{"200":{"description":"A page of your clients' tickets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerSupportTicketPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/support/tickets/{ticketId}":{"parameters":[{"name":"ticketId","in":"path","required":true,"description":"The client ticket's id.","schema":{"$ref":"#/components/schemas/Uuid"}}],"get":{"operationId":"getResellerSupportTicket","tags":["reseller"],"summary":"One client ticket on your desk, with its thread.","description":"The ticket and every message on it, including your team's internal notes (the client never sees those). A ticket that is not on your desk is a 404, never a 403. Requires `reseller.view`.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The ticket and its thread.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerSupportTicketDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/support/tickets/{ticketId}/messages":{"parameters":[{"name":"ticketId","in":"path","required":true,"description":"The client ticket's id.","schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"replyResellerSupportTicket","tags":["reseller"],"summary":"Reply to your client, or add an internal note.","description":"A public reply is e-mailed to your client from your brand and moves the ticket to `pending`; an internal note is seen only by your team. Requires `reseller.manage`.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to.","schema":{"$ref":"#/components/schemas/Uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerSupportReply"}}}},"responses":{"201":{"description":"The ticket and its thread, with your message added.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerSupportTicketDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/support/tickets/{ticketId}/close":{"parameters":[{"name":"ticketId","in":"path","required":true,"description":"The client ticket's id.","schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"closeResellerSupportTicket","tags":["reseller"],"summary":"Close a client ticket.","description":"Closes the ticket. Closing a closed ticket changes nothing. Requires `reseller.manage`.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The closed ticket.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerSupportTicketDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/support/tickets/{ticketId}/escalate":{"parameters":[{"name":"ticketId","in":"path","required":true,"description":"The client ticket's id.","schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"escalateResellerSupportTicket","tags":["reseller"],"summary":"Escalate a client ticket to platform support.","description":"Opens a ticket in YOUR organization, on behalf of the client, with your note first and the client's thread quoted under it. Platform support answers you there and you relay the answer; the client's ticket stays on your desk with an internal note linking the two. Escalating the same ticket twice returns the first escalation. Requires `reseller.manage`.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to.","schema":{"$ref":"#/components/schemas/Uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerSupportEscalation"}}}},"responses":{"201":{"description":"The client ticket, now carrying `escalated_ticket_id`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerSupportTicketDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/support/desk":{"get":{"operationId":"getResellerSupportDesk","tags":["reseller"],"summary":"Your support desk's settings, including your own AI support agent.","description":"Whether your own AI support agent answers your clients' tickets, which of your own AI keys it uses, and the website, instructions and knowledge it answers from. It runs ONLY on your own key — never on ours and never on credits — and speaks in your brand with your prices and packages. Requires `reseller.view`.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The desk settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerSupportDesk"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"updateResellerSupportDesk","tags":["reseller"],"summary":"Change your support desk's settings.","description":"Switching the AI agent on needs a live key of your own for the chosen provider (or any provider when none is chosen); without one it is refused with a 422. Requires `reseller.manage`.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to.","schema":{"$ref":"#/components/schemas/Uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerSupportDeskInput"}}}},"responses":{"200":{"description":"The saved settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerSupportDesk"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/services":{"get":{"operationId":"listResellerServices","tags":["reseller"],"summary":"Everything you have provisioned for your clients.","description":"One row per site across your client subtree — the client organization it belongs to, its plan, its lifecycle status, its disk and bandwidth usage, and the price *you* charge for it. This is the endpoint a billing panel polls to keep its own records in step with ours, and it is the answer to \"what have I actually sold\". Cursor-paginated. Requires `reseller.view`.\n\nSites in your OWN organization are excluded: this surface is about what you resell, and mixing your own estate into it would make a billing panel invoice you for your own sites.","parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}},{"name":"client_org_id","in":"query","required":false,"description":"Narrow to one client organization.","schema":{"$ref":"#/components/schemas/Uuid"}},{"name":"status","in":"query","required":false,"description":"Narrow to one site status.","schema":{"$ref":"#/components/schemas/SiteStatus"}}],"responses":{"200":{"description":"A page of provisioned services.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerServicePage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/services/{siteId}":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getResellerService","tags":["reseller"],"summary":"One provisioned service.","description":"The same row `listResellerServices` returns, for one site. A site outside your client subtree is a 404, never a 403 — so this is not an existence oracle. Requires `reseller.view`.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The service, with its current usage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerServiceDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/services/{siteId}/suspend":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"suspendResellerService","tags":["reseller"],"summary":"Put a client's site on a non-payment hold.","description":"Suspends a site you resell — the lever a billing panel pulls when your client has not paid you. The site stops serving and its content is retained; nothing is deleted. Requires `reseller.provision`.\n\nThe hold is attributed to YOU, and that attribution is load-bearing: a site the malware ladder suspended cannot be released by `unsuspendResellerService`, and a site you suspended cannot be released from the abuse queue. Two different people hold two different keys to the same door, and neither may open the other's lock.\n\nAnswers `202` at once (D50801): the site's server is changed by a durable workflow, not inside this request. The hold is recorded when the server confirms it; `serving_change` on the service shows the change until then (and a failure after it).","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerServiceHold"}}}},"responses":{"202":{"description":"The service; the hold is being applied (`serving_change`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerService"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/reseller/services/{siteId}/unsuspend":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"unsuspendResellerService","tags":["reseller"],"summary":"Release a non-payment hold you placed.","description":"Brings a site you suspended back into service. Refused with a `409` for a site this surface did not suspend — releasing a malware or abuse hold from a billing panel would hand out hosting the abuse desk had deliberately taken offline. Requires `reseller.provision`. Answers `202` at once; the release is applied on the server by a durable workflow (D50801) and `serving_change` shows it until then.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"202":{"description":"The service; the release is being applied (`serving_change`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerService"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/reseller/services/{siteId}/sso":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"createResellerServiceSso","tags":["reseller"],"summary":"A one-time sign-in link into the panel for this client.","description":"Mints a single-use, short-lived URL that drops your client straight into their own account in the panel, already signed in, with no password to remember. This is what the \"Log in to your hosting\" button in your billing panel or on your WordPress site opens. Requires `reseller.provision`.\n\nThe ticket travels in the URL **fragment**, so it is never sent to a server, never appears in a `Referer` and never reaches an access log. It is good for a few minutes and can be redeemed once. The session it opens is confined to that one client organization and is audit-logged against you, not against them.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"201":{"description":"The sign-in link.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerServiceSso"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/clients/{orgId}/plan":{"parameters":[{"name":"orgId","in":"path","required":true,"description":"One of your client organizations.","schema":{"$ref":"#/components/schemas/Uuid"}}],"get":{"operationId":"getResellerClientPlan","tags":["reseller"],"summary":"Which plan this client is on, and what it costs you.","description":"The client's live plan, or nulls when they are not on one yet. `wholesale_amount_minor` is what Zinn® charges **you** per period for it — integer minor units, `null` and never `0` when the catalogue does not price it in the currency asked for. Requires `reseller.view`. An organization that is not one of your clients is a `404`, not a `403`, so this cannot be used to discover that an organization exists.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of YOUR organizations is asking. Required only when you belong to more than one. Not to be confused with the path parameter, which is your client.","schema":{"$ref":"#/components/schemas/Uuid"}},{"name":"currency","in":"query","required":false,"description":"ISO 4217 code the wholesale figure is quoted in. Defaults to `USD`.","schema":{"type":"string","minLength":3,"maxLength":3}}],"responses":{"200":{"description":"The client's plan, or nulls if they have none.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerClientPlan"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"setResellerClientPlan","tags":["reseller"],"summary":"Put a client on a plan — call this before provisioning their first service.","description":"Grants the client organization the plan your product sells, and returns the `subscription_id` to pass to `createSite`. Requires `reseller.provision`.\n\n⛔⛔ **A provisioning module MUST call this before `createSite`, and omitting it is a silent, total loss of the invoice.** A newly created organization has no subscription, and `createSite` has no plan field — so a site provisioned without one lands with no plan at all. Your wholesale statement is built from your clients' live subscriptions, so there is no line for that service and Zinn® bills you nothing while the hosting runs; the client inherits no entitlements, so no quota is applied to their box; and `changeResellerServicePackage` has nothing to change, so an upgrade you sell cannot be performed. Nothing anywhere reports this — the site provisions and serves perfectly.\n\n**Your client is never invoiced by Zinn®.** The subscription is granted comped: it exists to carry entitlements and to put a line on *your* wholesale statement, and our renewal billing skips it. You bill your client; we bill you.\n\n**A second service for the same client.** On the **same** plan this is a no-op and returns `200` with `created: false` — the plan's own site allowance covers the extra site, so nothing further is granted and a retried provision cannot disturb the subscription it is re-establishing. On a **different** plan it is refused `422`, because replacing the live plan would leave one of the two services unbilled. Either sell both on the same plan, or set the client up as a separate client record. To move a client to a different plan, use `changeResellerServicePackage` on the service.\n\n`422` for an unknown plan code and for a plan that is not for sale. `409` when the client's existing usage does not fit the plan being granted, with the real numbers.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of YOUR organizations is asking. Required only when you belong to more than one.","schema":{"$ref":"#/components/schemas/Uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerClientPlanSet"}}}},"responses":{"200":{"description":"The client was already on this plan. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerClientPlan"}}}},"201":{"description":"The plan was granted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerClientPlan"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/reseller/services/{siteId}/package":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"listResellerServicePackages","tags":["reseller"],"summary":"Which packages this client's service could move onto, and what each costs you.","description":"The upgrade/downgrade picker your billing panel renders. Every plan this service could move to, each already scored against what the client is actually using, with the refusals applied — so a downgrade that would strand them over their own disk or database allowance is reported as ineligible here rather than failing when your customer presses the button. Requires `reseller.view`.\n\nTwo prices per option, and they answer different questions. `wholesale_amount_minor` is what **Zinn® charges you** for a period of that plan, after your programme's discount. `sell_amount_minor` is what **you charge your client** — your own price-list row where you have authored one, otherwise our list price plus your default markup. Both are integer minor units with an ISO currency code, and both are `null` — never `0` — when the catalogue holds no price in the currency asked for: a zero is a number a billing panel will invoice.\n\n`blocked_reason` is a **stable code, never prose**: `usage_exceeds` · `account_over_limit` · `platform_mismatch` · `no_price` · `unknown_package_type` · `different_target` · `no_package_type`. Your panel renders it in your own language. `blocked_detail` carries the numbers behind `usage_exceeds` so a screen can say which limit and by how much.\n\n`changeable: false` means the **surface** is shut whatever plan is chosen, and `reason` says which: `no_subscription`, `not_billable`, `no_package_type`, `subscription_not_live`, or `renewal_unpaid` (pay first: a renewal is unpaid, so a plan change is refused until it is paid).\n\n⛔ `shared_subscription` is **retired** (2026-09-08) and this surface no longer returns it. It shut the screen whenever one subscription covered several of a client's sites — which is what a multi-site plan is — so a reseller's panel could not offer an upgrade to exactly the clients most likely to want one. A plan covering several sites is now moved for all of them together.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred, and an id outside your direct memberships is a 404 rather than a 403, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}},{"name":"currency","in":"query","required":false,"description":"ISO 4217 code the two prices are quoted in. Defaults to `USD`.","schema":{"type":"string","minLength":3,"maxLength":3}},{"name":"interval","in":"query","required":false,"description":"Billing interval the prices are quoted for. Defaults to `monthly`.","schema":{"type":"string","maxLength":32}}],"responses":{"200":{"description":"The current package and everywhere this service could move to.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerServicePackageChoices"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"post":{"operationId":"changeResellerServicePackage","tags":["reseller"],"summary":"Move this client's service onto another package.","description":"Performs the upgrade or downgrade your panel just sold. The vendor package is moved, the client's entitlements follow it, and on our own fleet the box is given the new plan's quota. Requires `reseller.provision`.\n\n⛔ **Your client is not charged by us, and cannot be.** Under a reseller programme Zinn® bills *you* — the new plan appears on your next wholesale statement, because that statement is built from your clients' live subscriptions — and you bill your client through your own panel, which has already taken their money for this upgrade. There is no second charge and no card is touched. That is why this operation exists beside `changeSitePlan` rather than instead of it: the customer-facing one mints an order against the client organization, which under a reseller holds no payment instrument at all.\n\nTakes a plan **code**, not a version id. A code is what your admin typed into the product's module settings and it stays valid for years; the engine always resolves the newest active version of it, so a plan we have since re-priced cannot be bought at its old price by a panel nobody has updated.\n\nEvery refusal `listResellerServicePackages` reports is applied again here on fresh numbers, so a downgrade that has become unsafe since the picker was rendered is still refused. Repeating an identical request is safe and is the documented recovery: each step is idempotent, and a service already on the target plan is a `422` saying so rather than a second move.\n\n`422` for an unknown plan code, for a plan on a different product line or infrastructure, and for a downgrade the client's usage does not fit. `503` when the hosting platform behind the service cannot change a package type at all. `404` for a service that is not one of your clients'.","parameters":[{"name":"org_id","in":"query","required":false,"description":"Which of your organizations this applies to. Required only when you belong to more than one here — otherwise it is inferred.","schema":{"$ref":"#/components/schemas/Uuid"}},{"name":"currency","in":"query","required":false,"description":"ISO 4217 code the returned wholesale figure is quoted in. Defaults to `USD`.","schema":{"type":"string","minLength":3,"maxLength":3}},{"name":"interval","in":"query","required":false,"description":"Billing interval the returned wholesale figure is quoted for. Defaults to `monthly`.","schema":{"type":"string","maxLength":32}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerServicePackageChange"}}}},"responses":{"200":{"description":"The service's new package, read back from the rows.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerServicePackage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/plugins":{"get":{"operationId":"listPlugins","tags":["public"],"summary":"Everything Zinn® publishes for you to install, at its current version.","description":"Public and unauthenticated. A reseller evaluating us should be able to see what they get before they sign up, and an AI answer engine should be able to quote it. Each row carries the archive's SHA-256 and its size so a download can be checked; the archive itself is at `downloadPlugin`.\n\nCovers both the WordPress plugins and the billing-panel provisioning modules — `kind` says which, and filters the list. An unrecognised `kind` returns an empty list rather than everything: a page asking for modules must never silently render the WordPress catalogue instead.","parameters":[{"name":"kind","in":"query","required":false,"description":"Narrow to one kind of artefact. Omit for everything.","schema":{"type":"string","enum":["wordpress_plugin","whmcs_module","hostbill_module","generic_client"]}}],"responses":{"200":{"description":"The catalogue.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginReleaseList"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai-model-catalogue":{"get":{"operationId":"getAiModelCatalogue","tags":["public"],"security":[],"summary":"The signed catalogue of AI models the Zinn® plugins offer.","description":"The list of AI providers' models, prices and per-task recommendations that the shared AI core in the Zinn® WordPress plugins shows under Settings → AI providers. A plugin fetches it (only when its owner opts in) so model lists and prices stay current between plugin releases.\n\nPublic and unauthenticated, takes no parameters and records nothing about the caller. The body is a signed envelope returned byte for byte as published: `payload` is the base64 of the exact catalogue JSON bytes and `signature` is an Ed25519 (libsodium `crypto_sign_detached`) signature over those bytes by the key named in `key_id`. A plugin verifies the signature against the public key built into it before decoding anything, and refuses a bad signature, an unknown `key_id`, another `format`, or a catalogue older than the one it already has. Cacheable for an hour.\n\nThe catalogue keeps itself current (owner decision 2026-10-13): a daily workflow reads every provider's model list, adds new models, keeps the newest two of each family `current` and marks older ones `retiring` with the `successor` a saved choice should move to, then re-signs and stores a new release — which this endpoint serves within the hour, with no deploy. Each model carries `family`, `released`, `status`, `capabilities`, `max_output_tokens` and its price; image models are listed under `image_models`, and `recommended` includes an `image` task.","responses":{"200":{"description":"The signed catalogue envelope.","headers":{"Cache-Control":{"description":"`public, max-age=3600`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiModelCatalogueEnvelope"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/plugin-versions":{"get":{"operationId":"listPluginVersions","tags":["public"],"summary":"Every plugin you may download, with its current and older versions.","description":"For each plugin: its current release, then the newest release of each of the two previous **major** versions — for a site that cannot run the current one yet (an older WordPress or PHP), or to roll back an update that caused a problem. Download any of them with `downloadPlugin` and `version`.\n\n⛔ \"Major\" is WordPress's own meaning — `x.y`. When `1.2.3` is current the older versions are the newest `1.1.x` and the newest `1.0.x`; a superseded patch inside a line (`1.1.0` once `1.1.2` exists) is not offered, because the newest release of a line carries every fix that line received.\n\nEntitlement is the current release's, unchanged: an anonymous caller sees public plugins; a signed-in customer also sees `app-only` ones; a `licensed` (paid) plugin is never listed — Freemius sells, licenses and updates those. Computed from the published releases on every request — there is no hand-maintained list of versions.","responses":{"200":{"description":"The plugins, each with its downloadable versions, newest first.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginVersionList"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/plugins/{slug}":{"parameters":[{"$ref":"#/components/parameters/PluginSlug"}],"get":{"operationId":"getPlugin","tags":["public"],"summary":"One plugin's current release.","description":"Public and unauthenticated. A plugin we publish no release of is a `404`.","responses":{"200":{"description":"The current release.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginRelease"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/plugins/{slug}/download":{"parameters":[{"$ref":"#/components/parameters/PluginSlug"}],"get":{"operationId":"downloadPlugin","tags":["public"],"summary":"The installable plugin zip.","description":"The archive itself, over TLS on our own hostname, with its SHA-256 in `X-Zinn-Package-SHA256` so a download is checkable without a second request.\n\n⛔ The bytes are served rather than redirected, and that is a constraint the CLIENT imposes: the self-hosted updater shipped inside these plugins accepts a package only on our own host, so a redirect to a release asset or an object store is refused on every site.\n\nAn `app-only` plugin is invisible here to an anonymous caller. A site we host reaches it with the **package ticket** (`site`, `exp`, `sig`) that `POST /v1/wp/plugin-update/{siteId}` puts in the `package` URL it returns — WordPress fetches that URL with no headers, so the proof has to travel in the query string. The ticket is bound to one plugin at one version and expires; an invalid one is the same `404` as an unknown plugin.\n\nA plugin held for launch (`launch_pending` in `wp/plugins.json`, e.g. Zinn® SEO until release R1) is a `404` to every caller, signed in or not, and is absent from `listPlugins` and `getPlugin`; only a hosted site's package ticket opens it, so a site already running it keeps its updates.\n\n`version` downloads one of the older releases `listPluginVersions` offers, under the same entitlement as the current one. A version that exists but is not offered — a superseded patch, a line older than the two previous majors, or a newer release that has not been made current — is a `404`, exactly like a version that never existed. Every credential stays bound to the version it names: a ticket for `1.2.3` does not open `1.1.2`.","parameters":[{"name":"version","in":"query","required":false,"description":"One of the versions `listPluginVersions` lists for this plugin. Omit for the current release.","schema":{"type":"string","maxLength":32,"pattern":"^[0-9]+(\\.[0-9]+)*$"}},{"name":"site","in":"query","required":false,"description":"The site id a package ticket was minted for. Ignored for public plugins.","schema":{"type":"string","format":"uuid"}},{"name":"exp","in":"query","required":false,"description":"Unix time the package ticket stops being accepted.","schema":{"type":"integer","format":"int64"}},{"name":"sig","in":"query","required":false,"description":"Hex HMAC-SHA256 over `slug:version:exp` with the site's own secret.","schema":{"type":"string","minLength":64,"maxLength":64}}],"responses":{"200":{"description":"The zip.","headers":{"X-Zinn-Package-SHA256":{"description":"Lowercase hex SHA-256 of the body. The same value `getPlugin` reports.","schema":{"type":"string","minLength":64,"maxLength":64}}},"content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/plugins/{slug}/language-packs/{version}/{locale}":{"parameters":[{"$ref":"#/components/parameters/PluginSlug"},{"name":"version","in":"path","required":true,"description":"The plugin version the pack was built for.","schema":{"type":"string","maxLength":32,"pattern":"^[0-9][0-9A-Za-z.+-]{0,31}$"}},{"name":"locale","in":"path","required":true,"description":"A WordPress locale, e.g. `de_DE`, `ja`, `ar`.","schema":{"type":"string","maxLength":32,"pattern":"^[a-z]{2,3}(_[A-Z]{2})?(_[a-z0-9]+)?$"}}],"get":{"operationId":"getPluginLanguagePack","tags":["public"],"summary":"One plugin version's translations for one language (a language pack).","description":"A zip of the plugin's catalogues for one locale: `<slug>-<locale>.mo` and the script catalogues `<slug>-<locale>-<md5>.json`, nothing else. A plugin built with `language_packs` (Zinn® SEO, Tranzly, Page Builder Sandwich) ships its source strings only, and its admin kit fetches the packs for the languages the site uses — the site's language and its users' — and installs them into `wp-content/languages/plugins/`.\n\n⭐ Authenticated by the plugin, not by this channel: the zip carries `languages/language-packs.json` with the name, size and SHA-256 of every file of every pack, and a site installs a pack only when its files match exactly. `slug` is the plugin's text domain (its free slug; the Pro build uses the same packs).\n\nPublic and unauthenticated: the caller is a WordPress site with no account of ours. A pack never changes once published, so it is cacheable for a day (`immutable`).","responses":{"200":{"description":"The pack.","headers":{"X-Zinn-Package-SHA256":{"description":"Lowercase hex SHA-256 of the body.","schema":{"type":"string","minLength":64,"maxLength":64}}},"content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/wp/plugin-update/{siteId}":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"checkPluginUpdate","tags":["public"],"summary":"What an installed Zinn® plugin polls for updates.","description":"The WordPress self-hosted update endpoint. It is called by the plugin, not by a person: `wp/plugins/*/includes/class-updater.php` posts here on WordPress's own update schedule and turns the answer into the ordinary \"update available\" notice.\n\nAuthenticated by the site's own secret, never by a bearer token — the caller is a WordPress site, not a principal. The request carries `X-Zinn-Cache-Signature: sha256=HMAC(timestamp + \"\\n\" + body)` keyed with that site's `ZINN_UPDATE_SECRET`, and the response is signed the same way in `X-Zinn-Signature` so a site can prove the answer came from us before installing anything.\n\n⛔ A version staff HALTED (`POST /v1/admin/plugin-updates/halts`) is never offered here: the answer is the newest offered release that is not halted, or `204` when none is (PF-445).\n⛔ A site already on the current version gets `204`, not a `200` describing the version it has: the updater re-fetches and re-verifies a package whenever it is offered one. Anything unauthenticated, stale or unknown is a `404` — never a `401`, so this cannot become an oracle for which site ids exist.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginUpdateCheck"}}}},"responses":{"200":{"description":"A newer release is available.","headers":{"X-Zinn-Signature":{"description":"`sha256=<hex>` HMAC over the exact response body, keyed with the site's update secret. The plugin refuses a package unless this verifies.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginUpdateDescriptor"}}}},"204":{"description":"The site is already on the current version. Nothing to do."},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/wp/site-panel/{siteId}":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"getSitePanel","tags":["public"],"summary":"What the must-use plugin renders on a hosted site's WordPress dashboard.","description":"Called by the Zinn® Platform **must-use** plugin on a site we host, not by a person. It returns that site's plan, its allowances and current usage, and the cards, plan links and admin-bar items the platform is currently showing — so changing what every hosted site displays is an edit on one admin screen rather than a plugin release.\n\nAuthenticated by the site's own secret, never by a bearer token: the caller is a WordPress site, not a principal. The request carries `X-Zinn-Cache-Signature: sha256=HMAC(timestamp + \"\\n\" + body)` keyed with that site's `ZINN_UPDATE_SECRET`, and the response is signed the same way in `X-Zinn-Signature` so a site can prove the answer came from us before rendering any of it.\n\n⛔ Every unknown quantity is `null`, never `0`. A resource this kind of hosting cannot measure — a database on a static host, for instance — is permanently `null`, and the plugin renders that as *\"not measured yet\"*. A `0` would tell the customer their database is empty.\n\n⛔ Anything unauthenticated, stale, unknown or deleted is a `404`, never a `401`, so this cannot become an oracle for which site ids exist.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePanelRequest"}}}},"responses":{"200":{"description":"The site's panel.","headers":{"X-Zinn-Signature":{"description":"`sha256=<hex>` HMAC over `timestamp + \"\\n\" + <response body>`, keyed with the site's update secret, where `timestamp` is the one the request sent. The plugin refuses a manifest unless this verifies, which also stops an old answer being replayed at the site later.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePanel"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/pro-discounts":{"get":{"operationId":"listProDiscounts","tags":["billing"],"summary":"Your hosting-customer discount on every Pro plugin, and your code for each.","description":"Hosting customers get **50% off the first payment** of any Zinn® Pro plugin, through one personal code per plugin. This lists every Pro plugin the discount covers (read from the plugin registry, so a newly released Pro appears here with no change), whether your account qualifies — a paid hosting plan, active, in good standing; trials do not qualify — and the code you already hold for each, if any.\n\nRequires `billing.view`. Never calls the store: a code redeemed a minute ago may still read `active` until you ask for it again or the daily upkeep reads the store.","parameters":[{"name":"org_id","in":"query","required":false,"description":"The account to read. Required when you belong to more than one.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The offers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProDiscountList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/pro-discounts/{product}/code":{"parameters":[{"$ref":"#/components/parameters/ProDiscountProduct"}],"post":{"operationId":"getProDiscountCode","tags":["billing"],"summary":"Your personal code for one Pro plugin — created on first ask, the same one after.","description":"Returns your personal, single-use code for `product` and a checkout link with it already applied. The first call creates it (`201`); asking again while it is valid and unused returns the same code (`200`). A code lasts 30 days; after an unused expiry a new one is issued. Once a code has been used, no other is ever issued for that plugin — the discount is on the first payment only, and renewals are at the normal price.\n\nRequires `billing.view`. `403` when the account does not qualify, `404` when the plugin has no discount, `409` when it has already been used, `503` when the store could not be reached (nothing is created). Rate-limited.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProDiscountCodeRequest"}}}},"responses":{"200":{"description":"The code you already hold.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProDiscountIssued"}}}},"201":{"description":"A new code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProDiscountIssued"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/wp/pro-discount/{siteId}":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"getSiteProDiscount","tags":["public"],"summary":"The hosting-customer Pro discount, asked for from a hosted site's wp-admin.","description":"Called by a Zinn® free plugin's upgrade card on a WordPress site we host, not by a person. `action: status` says whether the site's owner qualifies and returns a live code if one exists, without creating anything; `action: issue` returns the owner's code, creating it if needed. It is the SAME code the owner sees in the dashboard — one per customer per Pro plugin, whichever door they use.\n\nAuthenticated by the site's own secret, exactly as `getSitePanel`: `X-Zinn-Cache-Signature: sha256=HMAC(timestamp + \"\\n\" + body)` keyed with the site's `ZINN_UPDATE_SECRET`, and the response is signed back in `X-Zinn-Signature` over the request's timestamp and the response body. Anything unauthenticated, stale, unknown or deleted is a `404`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteProDiscountRequest"}}}},"responses":{"200":{"description":"The owner's standing and code.","headers":{"X-Zinn-Signature":{"description":"`sha256=<hex>` HMAC over `timestamp + \"\\n\" + <response body>`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteProDiscount"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/hosting-code":{"get":{"operationId":"getHostingCode","tags":["billing"],"summary":"Your personal plugin-licence hosting code — 50% off the first year, if you hold one.","description":"Everyone who holds a paid licence for one of our WordPress plugins (Page Builder Sandwich, Tranzly, Zinn® SEO and the other Zinn® Pro plugins) gets ONE personal code for 50% off the first year of the Start or Grow WordPress hosting plan, billed yearly. Renewals are at the normal price. This returns the code held by the e-mail address of your account's owner, admin or billing member, or `offer: null`.\n\nThe code works only for an account signed in with that same address, once, on a new yearly Start or Grow plan, and never together with any other discount on the same line. Requires `billing.view`.","parameters":[{"name":"org_id","in":"query","required":false,"description":"The account to read. Required when you belong to more than one.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Your code, or none.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HostingCodeAnswer"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/wp/hosting-code":{"post":{"operationId":"getPluginHostingCode","tags":["public"],"summary":"A plugin licence holder's hosting code, asked for from the plugin's wp-admin card.","description":"Called by a Zinn® plugin's wp-admin card (Page Builder Sandwich, Tranzly, Zinn® SEO), from inside the site, with the licence id and the licence holder's e-mail address that the plugin's licensing SDK holds. The code is returned only when that licence belongs to a buyer with that address; otherwise `offer` is `null`. Nothing is created here: codes are issued in the background for every paid licence holder.\n\nNo credentials are needed because the code is useless to anyone else: checkout accepts it only for an account signed in with the same e-mail address. Rate limited per IP.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginHostingCodeRequest"}}}},"responses":{"200":{"description":"The holder's code, or none.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginHostingCodeAnswer"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/pro-discount-offers":{"get":{"operationId":"listPartnerProDiscountOffers","tags":["partner"],"summary":"The Pro plugins your hosting customers get 50% off, and one customer's codes.","description":"For a partner platform (V1) building its own panel: the discount terms and every Pro plugin it covers, read from the plugin registry — render from this, never from a copy. With `external_id`, each offer also carries that customer's code and its state, so one call renders the whole section. Requires a partner key holding `partner.domains`.","parameters":[{"name":"external_id","in":"query","required":false,"description":"Your id for the customer, as you send it to `createPartnerProDiscountCode`.","schema":{"type":"string","maxLength":128}}],"responses":{"200":{"description":"The terms and offers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerProDiscountOffers"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/partner/pro-discount-codes":{"post":{"operationId":"createPartnerProDiscountCode","tags":["partner"],"summary":"One of your hosting customers' personal code for a Pro plugin.","description":"Returns the customer's personal, single-use code for `product` and a checkout link with it applied — created on the first call (`201`), the same code on later calls while it is valid and unused (`200`). Codes last 30 days; after an unused expiry a new one is issued; after a redemption none ever is (`409`). The discount is on the first payment only.\n\n⛔ `hosting_in_good_standing` is YOUR assertion, made on every call, that this customer holds a paid hosting plan in good standing with you right now. V2 cannot see your billing, so it relies on it; `false` is refused (`403`) and an omitted field is a `422`, never a yes. Requires `partner.domains`. Rate-limited.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerProDiscountCodeRequest"}}}},"responses":{"200":{"description":"The code the customer already holds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerProDiscountIssued"}}}},"201":{"description":"A new code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerProDiscountIssued"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/partner/proven-plugin-releases":{"get":{"operationId":"listPartnerProvenPluginReleases","tags":["partner"],"summary":"The newest version of each of our free plugins that V2 has proven safe.","description":"For a partner platform (V1) that rolls our WordPress plugins out through its own checked updater: the newest version of each free plugin (`tranzly`, `page-builder-sandwich`, `zinn-chat`, `zinn-footprint`) that passed V2's checked update on the staff canary ring — at least one staff or test site KEPT it — and is not halted. A halted version is never listed; a plugin with no proven version is absent. `proven_at` is the time the first canary site kept it.\n\n`zip_url` is a download on our own API host that needs no credentials: it carries a signed, expiring grant (`exp`, `sig`) valid for at least seven days, and changes at most once a day. `sha256` is the SHA-256 of exactly the bytes at `zip_url` — check it before installing. Requires a partner key holding `partner.plugins`. Rate-limited.\n\nFree editions only, except for a FIRST-PARTY partner (our own V1 platform, programme `pbn-v1`): it also gets `tranzly-premium` and `page-builder-sandwich-premium` (`edition: licensed`), the licensed build of the same Freemius release at the same version as the proven free build. Those rows exist for our own staff product sites, which run the licensed builds. Their `zip_url` is NOT a bearer grant: it is `downloadPartnerLicensedPluginPackage`, which needs the same partner key. Halting the free version withdraws the licensed one too.","responses":{"200":{"description":"The proven releases.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerProvenPluginReleases"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/own-plugin-builds":{"get":{"operationId":"listPartnerOwnPluginBuilds","tags":["partner"],"summary":"Every published build of our WordPress plugins, by tree digest.","description":"For a partner platform (V1) that exempts our own plugins from its customers' file and disk allowances (owner ruling 2026-10-01): a plugin folder is exempt only when its tree digest equals the digest of a build we published (our release channel, Freemius free and premium builds, WordPress.org). The digest is SHA-256 over every directory, every file's path and size, and the content of each top-level `.php` file, prefixed with `digest_version`.\n\n`want` names folder versions the partner saw on its own sites that this list lacks (`dir@version`, comma-separated, at most 200). They are queued and looked up at our sources by our hourly sweep, never during this request; `queued` counts the new ones. Requires a partner key holding `partner.plugins`. Rate-limited.","parameters":[{"name":"want","in":"query","required":false,"schema":{"type":"string","maxLength":20000},"description":"Comma-separated `dir@version` pairs to look up."}],"responses":{"200":{"description":"The known builds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerOwnPluginBuilds"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/partner/plugin-packages/{plugin}/{version}":{"get":{"operationId":"downloadPartnerPluginPackage","tags":["partner"],"security":[],"summary":"The zip of a proven plugin version, as `zip_url` names it.","description":"The installable free zip of one version `listPartnerProvenPluginReleases` lists, served from our own host with its SHA-256 in `X-Zinn-Package-SHA256`. No credentials: the grant is the `exp` and `sig` in the URL, bound to this plugin and version. A version that is not proven (or is halted), an expired or forged grant, and an unknown plugin are all the same `404`. A proven version whose bytes cannot be fetched from upstream right now is `503` with `Retry-After`: retry later, it is not a verdict on the version.","parameters":[{"name":"plugin","in":"path","required":true,"schema":{"type":"string","enum":["tranzly","page-builder-sandwich","zinn-chat","zinn-footprint"]}},{"name":"version","in":"path","required":true,"schema":{"type":"string","maxLength":32,"pattern":"^[0-9]+(\\.[0-9]+)*$"}},{"name":"exp","in":"query","required":true,"description":"Unix time the grant stops being accepted.","schema":{"type":"integer","format":"int64"}},{"name":"sig","in":"query","required":true,"description":"The grant's signature, as `zip_url` carries it.","schema":{"type":"string","minLength":64,"maxLength":64}}],"responses":{"200":{"description":"The zip.","headers":{"X-Zinn-Package-SHA256":{"description":"Lowercase hex SHA-256 of the body — the `sha256` the manifest lists.","schema":{"type":"string","minLength":64,"maxLength":64}}},"content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/partner/licensed-plugin-packages/{plugin}/{version}":{"get":{"operationId":"downloadPartnerLicensedPluginPackage","tags":["partner"],"summary":"The licensed build of a proven plugin version (first-party partner only).","description":"The licensed (Freemius premium) zip of the plugin version that `listPartnerProvenPluginReleases` lists as `edition: licensed`, served with its SHA-256 in `X-Zinn-Package-SHA256`. It is for our own staff product sites on V1, which run the licensed builds. It needs a partner key holding `partner.plugins` on a first-party programme, and is never a bearer URL. A plugin that is not a licensed edition, a partner that is not first-party, and a version whose free build is not the newest proven, unhalted one all get the same `404`. A proven version whose bytes cannot be fetched from upstream right now is `503` with `Retry-After`: retry later, it is not a verdict on the version. Rate-limited.","parameters":[{"name":"plugin","in":"path","required":true,"schema":{"type":"string","enum":["tranzly-premium","page-builder-sandwich-premium"]}},{"name":"version","in":"path","required":true,"schema":{"type":"string","maxLength":32,"pattern":"^[0-9]+(\\.[0-9]+)*$"}}],"responses":{"200":{"description":"The zip.","headers":{"X-Zinn-Package-SHA256":{"description":"Lowercase hex SHA-256 of the body, the `sha256` the manifest lists.","schema":{"type":"string","minLength":64,"maxLength":64}}},"content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/tickets":{"get":{"operationId":"listTickets","summary":"List the organization's support tickets.","description":"The org's support tickets in creation order (the cursor keysets over the time-ordered id). Cursor-paginated and RLS-scoped to the caller's org subtree; requires `tickets.view`.","tags":["support"],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"status","in":"query","required":false,"description":"Only tickets in this lifecycle state.","schema":{"$ref":"#/components/schemas/TicketStatus"}},{"name":"site_id","in":"query","required":false,"description":"Only tickets raised about this site.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"A page of tickets.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createTicket","summary":"Open a support ticket.","description":"Opens a ticket in `open` with the supplied `body` as its first message, and publishes `ticket.created` (which sends the customer a localized acknowledgement via the notification consumer). `channel` is server-decided — it is not accepted from the client. A supplied `site_id` or `invoice_id` must belong to the same org or the request is a `404`. Requires `tickets.reply`.\n\n⭐ Spam guard (s1014 TICKETSPAM, V1's ticket limits): a request identical to one already on an open ticket, or a new one while the org (per client org) already has the open-ticket limit of customer tickets open, is **not** opened as another ticket — it is answered `200` with the existing ticket and a `merged` block (`duplicate`: nothing is written; `open_limit`: the request is appended to the newest open ticket as the customer's message). Never refused, never lost.\n\n⭐ The support AI goes first (s1014 TICKETAI, owner 2026-10-27): a new ticket opens only after an AI attempt — `POST /v1/tickets/deflect` with `ask_ai: true` — in the same org within the last 24 hours that has not already become a ticket; send its `deflection_id` (without one, the org's most recent unused attempt from the last 30 minutes stands in). Otherwise the request is a `422` whose `details` carry `{\"code\": \"ai_attempt_required\"}`. An attempt that FAILED (provider outage, refused, an answer request that never completed) still counts — the rule is that the AI goes first, never that it succeeds. One attempt opens one ticket. What the AI said and what its live checks found are put on the ticket as a staff-only note. Exceptions: `category` `abuse` or `legal` goes straight to the team (owner ruling *\"Abuse and legal only\"* — billing goes through the AI, which can check invoices), chosen by the customer, not detected from the text. A spam-guard merge (above) needs no attempt.","tags":["support"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketCreate"}}}},"responses":{"200":{"description":"Merged into an open ticket instead of opening another (see `merged`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketDetail"}}}},"201":{"description":"The newly opened ticket with its first message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/tickets/{ticketId}":{"parameters":[{"name":"ticketId","in":"path","required":true,"description":"The ticket's id.","schema":{"$ref":"#/components/schemas/Uuid"}}],"get":{"operationId":"getTicket","summary":"Get a support ticket and its thread.","description":"One ticket in scope with its full message thread in chronological order. Staff-internal notes are **not** included — they are excluded by the query and never reach this surface. Requires `tickets.view`.","tags":["support"],"responses":{"200":{"description":"The ticket and its customer-visible thread.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/tickets/{ticketId}/messages":{"parameters":[{"name":"ticketId","in":"path","required":true,"description":"The ticket's id.","schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"replyToTicket","summary":"Reply to a support ticket.","description":"Appends a customer message and returns the thread to `open`. Replying to a `solved` ticket reopens it. A **closed** ticket is rejected with a `422` whose error code is the stable `TICKET_CLOSED`, so a client can offer \"reopen\" without string-matching a translated message. Requires `tickets.reply`.\n\n⭐ Spam guard (s1014 TICKETSPAM): the same message as the customer's previous, still-unanswered one is kept once (`200`, nothing written). After the unanswered-reply limit the customer waits for an answer — `429` with `details[0].code` = `replies_waiting` (V1's follow-up limit), which the dashboard renders translated.","tags":["support"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketReplyCreate"}}}},"responses":{"200":{"description":"A repeat of the customer's previous message; kept once, nothing written.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketDetail"}}}},"201":{"description":"The ticket with the new message appended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/tickets/{ticketId}/close":{"parameters":[{"name":"ticketId","in":"path","required":true,"description":"The ticket's id.","schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"closeTicket","summary":"Close a support ticket.","description":"Closes the ticket. Idempotent — closing an already-closed ticket returns it unchanged rather than erroring. Requires `tickets.reply`.","tags":["support"],"responses":{"200":{"description":"The closed ticket.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/tickets/{ticketId}/access/{grantId}/revoke":{"parameters":[{"name":"ticketId","in":"path","required":true,"description":"The ticket's id.","schema":{"$ref":"#/components/schemas/Uuid"}},{"name":"grantId","in":"path","required":true,"description":"The `id` of an entry in the ticket's `access` list.","schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"revokeTicketAccess","summary":"Withdraw the site access given to support on this ticket.","description":"The customer takes back the \"give support access\" consent (s1014 L39). Staff can no longer open the site from this ticket. Idempotent — withdrawing twice is `204` both times. Closing the ticket withdraws it too. Requires `tickets.reply`; a grant on another ticket is a `404`.","tags":["support"],"responses":{"204":{"description":"Withdrawn."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/tickets/deflect/{deflectionId}/solved":{"parameters":[{"name":"deflectionId","in":"path","required":true,"description":"The `deflection_id` from `POST /v1/tickets/deflect`.","schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"markTicketDeflectionSolved","summary":"\"That solved it\" — the AI answer resolved the problem without a ticket.","description":"Records a ticket PREVENTED by the support AI (s1014 L39), counted in the admin support stats. Scoped to the caller's own organizations; another org's id is a `404`.","tags":["support"],"responses":{"204":{"description":"Recorded."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/tickets/deflect":{"post":{"operationId":"deflectTicket","summary":"Knowledge-base articles and a live diagnosis, before a ticket is opened.","description":"The KB + AI in front of the ticket form (#2661). Given what the customer has typed so far, returns matching published KB articles and — when a site is named — findings from live checks against it, including whether its nameservers still point at us.\n\n⛔ This never refuses to open a ticket and must never be made to. Everything it returns is offered; the form's submit button is unaffected. Requires `tickets.reply`.\n\n⛔ `checks_incomplete` is `true` when a check could not run. \"We found nothing wrong\" and \"we could not look\" are different answers and the client must render them differently.","tags":["support"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketDeflectionRequest"}}}},"responses":{"200":{"description":"What to show the customer before they open a ticket.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketDeflection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/status/affecting":{"get":{"operationId":"listAffectingStatusIncidents","summary":"Open status incidents that affect the caller's own services.","description":"⚖️ Owner, 2026-08-24: *\"when the ai things check sites and people submit tickets and things, does it count for outages and like tell them this is caused by x outage and we are working on it already no need to submit a ticket type of thing and link them to status to follow for updates when it's resolved.\"*\n\n⭐ Deliberately CHEAP and separate from `POST /v1/tickets/deflect`, which runs live DNS-backed probes and is therefore behind a button. The requirement is that an open incident is surfaced BEFORE the customer writes anything, so this must be able to load with the page: it reads two indexed tables and makes no network call.\n\n⭐ The same read backs the AI assistant's refusal panel and the MCP server, so all three surfaces answer from one implementation rather than three that drift.\n\n⛔ Relevance is a real test. A maintenance window is returned only while it is OPEN and only when it touches a region this organisation actually has a site in. Telling a customer a known outage explains them when it does not is worse than saying nothing.\n\n⛔ The organisation comes from the caller's own scope; there is no `org_id` parameter. An attacker-chosen one would be a cross-tenant read of another tenant's placement footprint.","tags":["support"],"responses":{"200":{"description":"Open incidents affecting this caller, and where to follow them.","content":{"application/json":{"schema":{"type":"object","required":["incidents","status_url"],"properties":{"incidents":{"type":"array","items":{"$ref":"#/components/schemas/TicketDeflectionIncident"}},"status_url":{"type":"string","description":"The public status page in the caller's language."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/diagnose":{"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site to check.","schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"diagnoseSite","summary":"Run the support AI against one site — check it, fix what is fixable, record the rest.","description":"Runs every diagnostic probe against the named site: whether it is being throttled by its plan's LVE limits (the cause of `508 Resource Limit Is Reached`), whether a `php.ini` value is below what the plan already allows, whether it runs a retired PHP version, and how much of its disk allowance is used.\n\nRemedies on the platform's named safe list are then applied — audit-logged and reversible — and everything that cannot be fixed becomes a **recommendation** the customer and staff can both see.\n\n⛔⛔ **A remedy can never grant a limit the plan does not include.** Every one runs through the same customer-band service a person would use, and an application that moved what the site is entitled to is refused rather than reported as applied.\n\n⛔ `complete` is `false` and `blind_probes` names what could not be read. \"We found nothing wrong\" and \"we could not look\" are different answers and the client must render them differently. Requires `hosting.php.manage`.","tags":["support"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"apply_fixes":{"type":"boolean","default":true,"description":"Set `false` to diagnose without applying anything. The default applies the safe list, which is the platform's ruled behaviour."}}}}}},"responses":{"200":{"description":"What was found, what was fixed and what was recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteDiagnosis"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/sites/{siteId}/support-recommendations":{"parameters":[{"name":"siteId","in":"path","required":true,"description":"The site whose advice history to read.","schema":{"$ref":"#/components/schemas/Uuid"}}],"get":{"operationId":"listSiteSupportRecommendations","summary":"What the support AI has advised about this site, and whether it was acted on.","description":"Every recommendation raised about this site, newest first, in every state — including ones marked `ignored`. Showing the customer their own record is deliberate: it is what makes an automatic reply quoting earlier advice fair rather than an ambush. Requires `sites.view`.","tags":["support"],"responses":{"200":{"description":"This site's advice history.","content":{"application/json":{"schema":{"type":"object","required":["items","live"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SupportRecommendation"}},"live":{"type":"integer","description":"How many are still open — the number the panel badges."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/tickets/{ticketId}/messages/{messageId}/attachments":{"parameters":[{"name":"ticketId","in":"path","required":true,"description":"The ticket's id.","schema":{"$ref":"#/components/schemas/Uuid"}},{"name":"messageId","in":"path","required":true,"description":"The message the file belongs to.","schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"uploadTicketAttachment","summary":"Attach a file to a ticket message.","description":"Uploads one file and records it against the message. The file is accepted immediately and is **not downloadable by anyone — including staff — until a malware scan has passed** (`scan_state: clean`).\n\n⛔ Only the types on the allow-list are accepted, and the declared content type is verified against the file's own leading bytes: a `.png` beginning `MZ` is refused whatever the header says. Maximum 25 MB. Requires `tickets.reply`.","tags":["support"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"The file. Maximum 25 MB."}}}}}},"responses":{"201":{"description":"The stored attachment, awaiting its scan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketAttachment"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/tickets/{ticketId}/attachments/{attachmentId}":{"parameters":[{"name":"ticketId","in":"path","required":true,"description":"The ticket's id.","schema":{"$ref":"#/components/schemas/Uuid"}},{"name":"attachmentId","in":"path","required":true,"description":"The attachment's id.","schema":{"$ref":"#/components/schemas/Uuid"}}],"get":{"operationId":"downloadTicketAttachment","summary":"Download a ticket attachment.","description":"The file's bytes, served `Content-Disposition: attachment` with `nosniff` and a sandboxing CSP so it cannot execute in the caller's origin.\n\n⛔ Answers **422**, not 404, when the file exists but has not passed its malware scan — a customer whose upload is quarantined must not be told their file vanished. The error code distinguishes `pending` (wait) from `infected`/`error` (never served). Requires `tickets.view`.","tags":["support"],"responses":{"200":{"description":"The file.","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/assistant/conversations":{"get":{"operationId":"listAssistantConversations","summary":"List your own assistant conversations.","description":"⛔ **Your own**, not your organization's. RLS scopes rows to a tenant and has no opinion about which colleague wrote them; an agency thread that starts \"my card keeps getting declined\" is not something every member should read back, so this filters on the calling user as well. An API-key principal has no user and cannot use this surface at all. Requires `tickets.reply`.","tags":["assistant"],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"org_id","in":"query","required":false,"description":"Narrow to one organization. ⛔ Narrows, never widens: the base set is always what you may act in, and an `org_id` you cannot act in intersects to nothing rather than raising — a `403` would confirm the organization exists.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"A page of your conversations, newest activity first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantConversationPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createAssistantConversation","summary":"Start a new assistant conversation.","description":"Creates an empty thread. Nothing is sent to a model until you post a message. Requires `tickets.reply`.","tags":["assistant"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantConversationCreate"}}}},"responses":{"201":{"description":"The new conversation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantConversation"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/assistant/conversations/{conversationId}":{"parameters":[{"name":"conversationId","in":"path","required":true,"description":"The conversation's id.","schema":{"$ref":"#/components/schemas/Uuid"}}],"get":{"operationId":"getAssistantConversation","summary":"Read one conversation with its full thread.","description":"⛔ A colleague's conversation is a `404`, never a `403` — a `403` confirms the id exists, which is itself information about what a colleague has asked.","tags":["assistant"],"responses":{"200":{"description":"The conversation and its turns.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantConversationDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"deleteAssistantConversation","summary":"Delete a conversation and everything in it.","description":"⭐ A real delete, cascading to the turns — not an archive flag. A customer asking us to forget a conversation about their own account is entitled to have it gone.","tags":["assistant"],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/assistant/conversations/{conversationId}/messages":{"parameters":[{"name":"conversationId","in":"path","required":true,"description":"The conversation's id.","schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"askAssistant","summary":"Ask the assistant a question and get its answer.","description":"Synchronous: one request, two persisted turns, and the answer in the response. ⛔ Not `202` with a poll — §2.16 forbids an interactive path behind a job queue, and a chat that answers on the next poll is not a chat. Expect several seconds.\n\nThe answer is grounded in **published knowledge-base articles** and, when `site_id` names one of your own sites, that site's health as read from our monitoring database. It cannot see another tenant's data, an unpublished draft, or a staff internal note — those are excluded by what the engine fetches, not by asking the model. It **cannot act**: no tool on this path changes anything.\n\nA `503` is a refusal fit to show the customer, and its `error_code` distinguishes the reasons — `ASSISTANT_DAILY_LIMIT`, `ASSISTANT_DISABLED`, `ASSISTANT_FAILED`, `ASSISTANT_UNAVAILABLE`. ⭐ Four, not six: an empty or over-long question is refused by validation as a `422` before anything is spent, so its code never reaches this response. Requires `tickets.reply`.","tags":["assistant"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantAsk"}}}},"responses":{"201":{"description":"The assistant's turn.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantMessage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"description":"The assistant cannot answer right now. The message is customer-safe; the `error_code` says which reason.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/assistant/conversations/{conversationId}/escalate":{"parameters":[{"name":"conversationId","in":"path","required":true,"description":"The conversation's id.","schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"escalateAssistantConversation","summary":"Turn a conversation into a support ticket.","description":"⭐ The point of `needs_human`. Opens a ticket carrying the whole transcript, so the customer does not start again somewhere else and the agent opens something that already contains the question and what the assistant could not do. **Idempotent** — a second call returns the same ticket with `200` rather than opening a duplicate. Requires `tickets.reply`. ⭐ Spam guard (s1014 TICKETSPAM): the support restriction and rate limit apply here as on `createTicket`, and past the open-ticket limit the hand-off joins the newest open ticket (`200` with `merged`).","tags":["assistant"],"responses":{"200":{"description":"This conversation had already been escalated; the existing ticket.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantEscalation"}}}},"201":{"description":"The new ticket.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantEscalation"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/staff-app/zinn-live-chat.apk":{"get":{"operationId":"downloadStaffApp","summary":"The staff phone app, newest build — a stable link to open on a phone.","description":"**Anonymous**, by design: the app holds no credential and opens the admin's own sign-in. The link never changes; the build behind it does. Rate-limited per client and globally. `404` until a build is published.","tags":["public"],"security":[],"responses":{"200":{"description":"The signed APK.","headers":{"X-Zinn-App-Version":{"schema":{"type":"string"},"description":"The build's version name."}},"content":{"application/vnd.android.package-archive":{"schema":{"type":"string","format":"binary"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/staff-app/zinn-live-chat-setup.exe":{"get":{"operationId":"downloadStaffDesktopApp","summary":"The Windows desktop app's installer, newest build — a stable link.","description":"**Anonymous**, by design, like the APK: the app holds no credential and opens the admin's own sign-in. `404` until a Windows build is published (`manage.py publish_staff_app --platform windows`). While no code-signing certificate exists the installer is unsigned (`signed_by` empty on `getAdminStaffApp`).","tags":["public"],"security":[],"responses":{"200":{"description":"The NSIS installer.","headers":{"X-Zinn-App-Version":{"schema":{"type":"string"},"description":"The build's version name."}},"content":{"application/vnd.microsoft.portable-executable":{"schema":{"type":"string","format":"binary"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/domains/tld-pricing":{"get":{"operationId":"listTldPricingTable","summary":"The TLD price table, flat, in the caller's currency.","description":"The **canonical** TLD price table (docs/43 §3.1) and the one the dashboard's \"Register a domain\" reference table consumes. Flat integer minor units converted into the caller's display currency (`X-Zinn-Currency`, falling back to USD). `GET /v1/public/domains/tld-pricing` serves the same rows anonymously in a nullable `MoneyAmount` shape, cursor-paged; `GET /v1/domains/pricing` served them publicly and uncursored and was **retired in wave 8** (#845).\n\nAuthenticated, because it prices in the caller's currency. Cacheable per caller — strong `ETag` + `Cache-Control: private, max-age=60` + `Vary: X-Zinn-Currency`, so a shared cache can never hand one customer's currency to another.\n\nA TLD whose register, renew and transfer are not all priced is **omitted** rather than zero-filled: the flat shape has no null, and `$0.00` on a pricing screen is a false quote, not a missing value.\n\n**Cursor-paged and server-searched (#846).** This was the last unbounded projection of the catalogue — the public reader has been paged since #571 and `/v1/domains/pricing` was retired for exactly this (#845), which left the authenticated table returning every row in one body. `q` is a substring match on the label and tolerates a leading dot (`.shop` and `shop` find the same row).\n\nOrdered **most popular first** by default, matching the public table: the two show the same catalogue to the same person before and after they sign up, and opening one with `.com` and the other with `.ai` is the split `docs/48` §6 warns about. `order=tld` gives the alphabetical reference view.\n\n⚠️ **A page can be short.** The omit-if-unpriced rule above is applied *after* the window, so a page of 50 offers may carry 48 rows. Pagination is still correct — the cursor is taken from the last **offer** in the window, not the last row emitted — so follow `page.next_cursor` until `page.has_more` is false rather than stopping when a page looks short.","tags":["domains"],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"q","in":"query","required":false,"description":"Substring match on the TLD label, applied server-side. A leading dot is tolerated and ignored.","schema":{"type":"string","maxLength":63}},{"name":"order","in":"query","required":false,"description":"`popularity` (default) is most-popular-first with an alphabetical tiebreak; `tld` is the alphabetical reference view.","schema":{"type":"string","enum":["popularity","tld"],"default":"popularity"}},{"name":"If-None-Match","in":"header","required":false,"description":"A previously returned `ETag`; a match responds `304`.","schema":{"type":"string","maxLength":256}}],"responses":{"200":{"description":"The TLD price table in the caller's currency.","headers":{"ETag":{"description":"Strong validator over the table as priced for this caller.","schema":{"type":"string"}},"Cache-Control":{"description":"Always `private, max-age=60`.","schema":{"type":"string"}},"Vary":{"description":"Always `X-Zinn-Currency` — the body is currency-dependent.","schema":{"type":"string"}},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TldPricingTable"}}}},"304":{"description":"Unchanged since the supplied `If-None-Match`.","headers":{"ETag":{"description":"The unchanged validator.","schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/domains/{domainId}/settings":{"parameters":[{"$ref":"#/components/parameters/DomainId"}],"get":{"operationId":"getDomainSettings","summary":"Get a domain's registrar settings.","description":"Auto-renew, registrar transfer lock, DNSSEC and WHOIS privacy for an owned domain. Served from our mirror of the registrar's state rather than a live vendor round-trip, so a detail screen never waits on a third party. Requires `sites.view`.\n\n**422 also covers a refusal that will never succeed.** A domain registered through the Cloudflare route has no API-writable transfer lock or WHOIS privacy — Cloudflare exposes neither for a registration made through its registrations endpoint — so the answer names the Cloudflare dashboard and offers support rather than `503 try again`, which is a sentence a customer would act on for ever.","tags":["domains"],"responses":{"200":{"description":"The domain's settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainSettings"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"updateDomainSettings","summary":"Change a domain's registrar settings.","description":"A **partial** update: an omitted field is left alone, never reset. Each changed flag is applied at the **registrar first** and mirrored onto our record only once it succeeds — so this endpoint never reports a protection (a transfer lock, WHOIS privacy) that the registrar has not actually applied. `auto_renew` is decided here and a registrar that keeps its own auto-renew flag is made to agree with it, registrar first and read back (#7175) — so switching it off can never leave the registrar renewing and charging on its own. (On the Cloudflare route switching it **on** is applied by the renewal sweep once the renewal is paid.) A registrar that refuses or ignores the change is a `503`. Requires `domains.dns.manage`.","tags":["domains"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainSettingsUpdate"}}}},"responses":{"200":{"description":"The settings after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainSettings"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"description":"Nothing was mirrored. **Branch on `error.code`** — the two causes need opposite responses:\n\n* `SERVICE_UNAVAILABLE` — the registrar was reached and could not apply the\n  change. Retrying shortly is correct.\n\n* `PROVIDER_NOT_CONFIGURED` — the refusal happened **before any registrar call**:\n  this account has no registrar provider configured, so the platform declined to\n  act rather than apply the change to a fake (issue #1039). Retrying can never\n  succeed; only staff adding a provider account can clear it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/domains/{domainId}/contacts":{"parameters":[{"$ref":"#/components/parameters/DomainId"}],"get":{"operationId":"getDomainContact","summary":"The registrant contact on public WHOIS for this domain.","description":"Who the registry believes owns this domain. `contact` is `null` where we hold none — deliberately, because \"we have no contact\" and \"the contact is blank\" are different facts and an empty object asserts the second.\n\n`editable` says whether this domain's registrar publishes a way to change it. It is `false` on the Cloudflare route, which accepts contacts only when the domain is first registered, so the console renders the panel read-only rather than offering a control that would answer 422.","tags":["domains"],"responses":{"200":{"description":"The registrant contact, or `null`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainContactEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"updateDomainContact","summary":"Change the registrant contact (drives the registrar first).","description":"**This is not a preference.** The registrant address is the ICANN record of who owns the domain and is what the registry emails to verify the registration — an unverified or bouncing one gets the domain **suspended**, so a customer who moves house or changes email needs to be able to correct it.\n\nThe registrar is driven **first** and our mirror is written only once it accepted. The reverse order would show a customer their new address over a registry that still holds the old one.\n\n**Every field is required.** ICANN treats a registrant change as one record, several registries re-verify the whole contact on any change, and the drivers replace the set rather than patching a field — so a partial body would merge into whatever our mirror happened to hold.\n\n`422` where the registrar cannot change contacts at all (the Cloudflare route), naming support rather than telling the customer to retry something that will never work. `503` where it could not, which is worth retrying.","tags":["domains"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainContact"}}}},"responses":{"200":{"description":"The saved contact.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainContactEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/domains/default-registrant":{"get":{"operationId":"getDefaultRegistrant","summary":"The owner the organization's new domains are registered to.","description":"The organization's **default registrant** — the ICANN owner every domain bought through a basket (`domain_register` or `domain_transfer`) is registered to, unless the checkout names another. `registrant` is `null` when none is set; `complete` says whether a registrar would accept it, and `missing` lists the fields a checkout would still need. Requires `sites.view`.","tags":["domains"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"The organization to read; defaults to the caller's own.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The default registrant, or `null`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultRegistrantEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setDefaultRegistrant","summary":"Set the owner the organization's new domains are registered to.","description":"Replaces the organization's default registrant. Checkout refuses a basket that registers or transfers a domain with `422 REGISTRANT_REQUIRED` while the organization has no complete default and the request names no `registrant`, so this is how an integration sets it ahead of buying.\n\n**Never rewrites an existing domain.** A default already recorded as the owner of a domain is kept as it is and a new record becomes the default; change an existing domain's owner with `updateDomainContact`, which drives the registrar. The phone is stored in the EPP `+CC.NUMBER` form and must carry its country code. Requires `billing.payment.manage` — the permission that places an order.","tags":["domains"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"The organization to change; defaults to the caller's own.","schema":{"$ref":"#/components/schemas/Uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Registrant"}}}},"responses":{"200":{"description":"The saved default registrant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultRegistrantEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/domains/registrant-email-verifications":{"get":{"operationId":"listRegistrantEmailVerifications","summary":"The caller's domains whose registrant email address is not yet confirmed.","description":"ICANN requires the registrar to confirm a generic-TLD registrant's email address: it mails the registrant a link, and a name whose address is not confirmed by the deadline is suspended by the registry. Each item is one of your domains still waiting, with the address the link went to and the deadline. Read from what the registrar reported at its last check (every 6 hours, `checked_at`), soonest deadline first, at most 200 items. A confirmed address leaves the list at the next check. Requires `sites.view`. Scoped to the caller's OWN orgs (direct memberships, or the API key's org), or to the one org the request names in `X-Zinn-Org`: a parent or reseller org is never shown a client org's notice unless it acts in that client org.","tags":["domains"],"parameters":[{"name":"domain_id","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Uuid"}},{"name":"org_id","in":"query","required":false,"description":"The one org whose notices to list (the same as `X-Zinn-Org`; this parameter wins when both are sent). Narrowed to the orgs the caller may view with `sites.view`: an org outside that set, or a value that is not a UUID, lists nothing. Omitted, the list reads the caller's own orgs only.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The pending verifications.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistrantEmailVerificationList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/domains/{domainId}/registrant-email-verification/resend":{"parameters":[{"$ref":"#/components/parameters/DomainId"}],"post":{"operationId":"resendRegistrantEmailVerification","summary":"Ask the registrar to send the registrant verification email again.","description":"Sends the registrar's confirmation email again to the address shown in `listRegistrantEmailVerifications`. The registrar restarts the check for that ADDRESS, so every pending domain on it is covered, and the registrar may move the deadline (the new one shows at its next check). Rate limited per domain and per address: one resend per 15 minutes and at most 3 per 24 hours (`429` with `Retry-After`). Audit-logged. `409` when the domain has no pending verification; `422` when the registrar declines to resend for this address (contact support); `503` when the registrar could not be reached (try again later). Requires `domains.dns.manage`.","tags":["domains"],"responses":{"200":{"description":"The resend was accepted; the verification as it now stands.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistrantEmailVerification"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/domains/holder-verifications":{"get":{"operationId":"listHolderVerifications","summary":"The caller's nic.at holder verifications, soonest deadline first.","description":"nic.at (the `.at` registry) can ask the holder of a `.at` domain to prove who they are under the EU NIS2 directive: an ID card or passport plus proof of address for a person, or a company-register extract for an organisation, within **21 days**. After that the registry suspends the domain (`serverHold`) and may cancel it. Each item is one such request on one of your domains. `state=open` (the default) returns only cases still running; `state=all` includes closed ones. Requires `sites.view`.","tags":["domains"],"parameters":[{"name":"state","in":"query","required":false,"schema":{"type":"string","enum":["open","all"],"default":"open"}},{"name":"domain_id","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The verifications.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HolderVerificationList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/domains/holder-verifications/{caseId}":{"parameters":[{"$ref":"#/components/parameters/HolderVerificationCaseId"}],"get":{"operationId":"getHolderVerification","summary":"One nic.at holder verification.","description":"The deadline, the documents asked for, which are still missing, and anything our verification team asked you to change. Documents are listed by name and type only; once uploaded they are never served back to the customer. Requires `sites.view`.","tags":["domains"],"responses":{"200":{"description":"The verification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HolderVerification"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/domains/holder-verifications/{caseId}/documents":{"parameters":[{"$ref":"#/components/parameters/HolderVerificationCaseId"}],"post":{"operationId":"uploadHolderVerificationDocument","summary":"Upload one holder document (PDF, JPEG or PNG, 10 MB at most).","description":"The file is checked against its declared type by its first bytes, scanned for malware, encrypted (AES-256-GCM) and stored privately. It is read only by our verification team and, after their approval, by the registry through a signed link that expires after 7 days. Documents are deleted 30 days after the verification closes. `kind` must be one the case asks for (`required_documents`). Allowed while the case is `awaiting_documents` or `changes_requested`. Requires `billing.payment.manage`.","tags":["domains"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["kind","file"],"properties":{"kind":{"$ref":"#/components/schemas/HolderDocumentKind"},"file":{"type":"string","format":"binary","description":"The document. PDF, JPEG or PNG; 10 MB maximum."}}}}}},"responses":{"201":{"description":"Stored; the verification as it now stands.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HolderVerification"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/domains/holder-verifications/{caseId}/documents/{documentId}":{"parameters":[{"$ref":"#/components/parameters/HolderVerificationCaseId"},{"name":"documentId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"delete":{"operationId":"removeHolderVerificationDocument","summary":"Take back a document before submitting.","description":"The encrypted copy is destroyed immediately. Allowed while the case is `awaiting_documents` or `changes_requested`. Requires `billing.payment.manage`.","tags":["domains"],"responses":{"200":{"description":"The verification as it now stands.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HolderVerification"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/domains/holder-verifications/{caseId}/submit":{"parameters":[{"$ref":"#/components/parameters/HolderVerificationCaseId"}],"post":{"operationId":"submitHolderVerification","summary":"Hand the documents to our verification team.","description":"Refused with `422` until every kind in `required_documents` is uploaded. The case moves to `under_review`; reminders stop. Requires `billing.payment.manage`.","tags":["domains"],"responses":{"200":{"description":"Submitted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HolderVerification"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/registry-documents/{token}":{"get":{"operationId":"getRegistryDocument","summary":"One holder document, for the registry. Unauthenticated; the token is the key.","description":"The link our verification team hands the registrar after approving a case. The token is 256 random bits, stored only as a hash, valid for 7 days, and dead as soon as the case closes or staff re-issue links. Every fetch is audit-logged. Any invalid, expired or revoked token answers the same `404`. Served as a download (`Content-Disposition: attachment`, `nosniff`, a sandboxing CSP).","tags":["domains"],"security":[],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","maxLength":128}}],"responses":{"200":{"description":"The document.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/png":{"schema":{"type":"string","format":"binary"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/domains/{domainId}/auth-code":{"parameters":[{"$ref":"#/components/parameters/DomainId"}],"post":{"operationId":"revealDomainAuthCode","summary":"Reveal a domain's EPP transfer code.","description":"Returns the domain's EPP/auth code, which **authorizes transferring the domain to another registrar**. It is fetched from the registrar on demand, returned once, and never stored or logged by us; the response is `no-store`.\n\nA `POST` deliberately, despite reading: revealing a credential must not be something a page load, a prefetch, a browser-history entry or a cache can trigger. The reveal is audit-logged (the code itself never is). Requires `domains.dns.manage`.\n\n**422 where the registrar publishes no auth-code endpoint at all** (the Cloudflare route). The refusal names the way out rather than simply declining — a customer is entitled to leave, so support fetches the code rather than the transfer being delayed.","tags":["domains"],"responses":{"200":{"description":"The transfer code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthCode"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"description":"No transfer code was returned. **Branch on `error.code`:** `SERVICE_UNAVAILABLE` means the registrar was asked and did not supply one (retry shortly); `PROVIDER_NOT_CONFIGURED` means this account has no registrar provider configured, so nothing was asked at all — permanent until staff add one (issue #1039).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/domains/transfer/preflight":{"post":{"operationId":"preflightDomainTransfer","summary":"Check and price a bulk transfer-in.","description":"Takes a list of domain names and answers, per name, whether it can be transferred to us and what that costs — the check half of the bulk transfer-in wizard (`docs/31` §5.3(e)). A `POST` because the list would not survive a query string at this size, not because it changes anything: it is idempotent and writes nothing.\n\nBounded to 50 names per request, so one paste cannot fan an unbounded burst at the registrar; a longer list is a `422` asking the customer to split it rather than a silent truncation. Every price resolves through the TLD catalogue — a client never invents one. Requires `sites.view`.","tags":["domains"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferPreflightRequest"}}}},"responses":{"200":{"description":"One row per distinct name, in the order they were given.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferPreflightResults"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/domains/{domainId}/restore-quote":{"parameters":[{"$ref":"#/components/parameters/DomainId"}],"get":{"operationId":"getDomainRestoreQuote","summary":"What it costs to restore a lapsed domain.","description":"The registry redemption fee for a domain that has fallen into `redemption`, and whether it can be restored at all. Priced in the caller's display currency (`X-Zinn-Currency`, falling back to USD) from the TLD catalogue.\n\nA domain that has not lapsed that far needs a **renewal**, not a restore, and is answered `restorable: false` rather than quoted — a redemption fee is many times a renewal, so quoting one in the wrong state would overcharge for a renewal. Requires `sites.view`.","tags":["domains"],"responses":{"200":{"description":"The quote, or the reason there is none.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestoreQuote"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/site-forms/submit":{"post":{"operationId":"submitSiteForm","summary":"Send a static site's form to a mailbox on that site's own domain.","description":"**Anonymous** — the house form backend for a STATIC site we host (docs/1185). A plain HTML `<form method=\"post\">` on the site posts here; the engine e-mails the answers to `<_to>@<the site's domain>` with the visitor as `Reply-To`, sends the visitor a short confirmation, and **stores nothing**.\n\n⛔ The site is the one serving the request's `Origin` (else `Referer`) host, and the recipient must be an ACTIVE, receiving mailbox on that site's own domain in the SAME org — never any other address. A Cloudflare Turnstile token (`cf-turnstile-response`) is verified against the site's OWN widget; no widget, no form. A filled honeypot (`_website`) is accepted silently and sends nothing. Charged against a fail-closed per-IP and global budget before the body is parsed.\n\nA browser form gets a `303` back to the same site: `_next?sent=1` on success, `_back?sent=0&reason=<code>` on refusal. A caller sending `Accept: application/json` gets JSON and a status code instead. Every body field not starting with `_` is a question and its answer, mailed in the order sent.","tags":["public"],"security":[],"parameters":[{"in":"header","name":"Origin","required":false,"schema":{"type":"string"},"description":"Set by the browser; names the site. `Referer` is the fallback."}],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/SiteFormSubmission"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/SiteFormParts"}},"application/json":{"schema":{"$ref":"#/components/schemas/SiteFormSubmission"}}}},"responses":{"200":{"description":"Sent (JSON callers).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteFormResult"}}}},"303":{"description":"Back to the site — `?sent=1`, or `?sent=0&reason=<code>`.","headers":{"Location":{"schema":{"type":"string","format":"uri"}}}},"400":{"description":"Unknown site (`origin`), not a mailbox of the site (`recipient`), a bad e-mail (`email`) or an oversized body (`invalid`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteFormResult"}}}},"403":{"description":"The site has no form widget (`not_enabled`) or Turnstile refused (`verification`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteFormResult"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"description":"The mail could not be sent, or the site's account is not in good standing (`unavailable`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteFormResult"}}}}}}},"/v1/public/assistant/ask":{"post":{"operationId":"askZinnPresales","summary":"Ask Zinn® a pre-sales question — no account, one grounded answer.","description":"**Anonymous** — no credential, no tenant, nothing stored. The public half of Ask Zinn®: a visitor deciding whether to buy asks a question, and the answer is built from PUBLISHED knowledge-base articles plus the LIVE catalogue read at request time, so a price it quotes is the price the engine will charge.\n\n⛔ It answers only from that material. `grounded: false` is the assistant saying it could not — a **successful** response whose correct rendering is a route to a human, never an error banner. A client that renders it as a failure has inverted the one property this surface exists to give (§2.44, §2.57).\n\n⛔ It cannot read a site, a ticket, an invoice or an org: no identifier for one is accepted anywhere on this path. Anything about an existing account comes back `grounded: false`.\n\n⛔ `history` is supplied by the CALLER because nothing is persisted — there is no account to hang a conversation on. It is bounded here and again in the engine.\n\nCharged against a fail-closed per-IP and global budget before the body is parsed, because every call is a paid model call.","tags":["public"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PresalesAskRequest"}}}},"responses":{"200":{"description":"The answer, grounded or honestly not.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PresalesAnswer"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"description":"Ask Zinn® is switched off, or could not answer at all. ⛔ Distinct from a `200` carrying `grounded: false`: that is the assistant working and being honest; this is the assistant unavailable. `error_code` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/public/quotes/form":{"get":{"operationId":"getPublicQuoteForm","summary":"What the free-quote form needs to render itself.","description":"**Anonymous** — no credential, no tenant. Reports the Cloudflare Turnstile **site key** (public by construction; it ships in the page's HTML) and the enum choices the form's dropdowns are built from.\n\n⛔ The choices come from here rather than being hand-copied into the client for the reason a hand-maintained copy of anything always goes wrong: it goes stale silently and then submits a value the engine refuses, which the visitor sees as an error on a field they filled in correctly.\n\n⛔ `turnstile_site_key` is `null` — never `\"\"` — when no challenge is configured. The client branches on it, and \"not configured\" and \"configured as an empty string\" must be distinguishable on the wire.","tags":["public"],"security":[],"responses":{"200":{"description":"The form's configuration.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteFormConfig"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/support/deflect":{"post":{"operationId":"deflectPublicSupportQuestion","summary":"The AI answer in front of a public support form (plugin support, chat, public).","description":"**Anonymous** (s1014 L39). The same grounded answer as the dashboard's \"Ask for help\" (published KB + live catalogue), for a visitor with no account, recorded in the admin support stats in the platform organization. Returns a `deflection_id` the ticket then carries (`POST /v1/plugin-support/tickets`, the chat's ticket form), or that `POST /v1/public/support/deflect/{deflectionId}/solved` marks as solved.\n\n⛔ Never blocks the ticket: a failed answer comes back with `answer.failure` set (the §2.57 classes) and the form keeps its submit button. Spends the presales budget per client and globally before the body is read (`429`).","tags":["public"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicSupportDeflectRequest"}}}},"responses":{"200":{"description":"The answer, its record id and the matching help articles.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicSupportAnswer"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/support/deflect/{deflectionId}/solved":{"parameters":[{"name":"deflectionId","in":"path","required":true,"description":"The `deflection_id` from `POST /v1/public/support/deflect`.","schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"markPublicSupportAnswerSolved","summary":"\"That solved it\" on a public support form — a ticket the AI prevented.","description":"**Anonymous** (s1014 L39). Moves only a PUBLIC answer (platform organization, surface `public`/`plugin`/`chat`) shown in the last 24 hours. Always `204`, so whether an id exists is not disclosed to an anonymous caller.","tags":["public"],"security":[],"responses":{"204":{"description":"Recorded (or nothing to record)."},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/news/subscribe":{"post":{"operationId":"subscribeZinnNews","summary":"Ask for Zinn® news by e-mail (double opt-in; sends one confirmation e-mail).","description":"s1014 DOUBLEOPTIN, docs/1052 §7j. Records the consent request (time, IP, user agent, page, the wording version shown, language) and e-mails ONE confirmation link that works for 7 days. ⛔ No oracle: `202` with the same body for a new, pending, confirmed, throttled or suppressed address. Human check (`newsletter` surface), a per-client budget, a honeypot (`website_confirm`) and a per-address resend limit. `422` for an unknown source or wording.","tags":["public"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicNewsSubscribe"}}}},"responses":{"202":{"description":"Check your inbox.","content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["check_your_inbox"]}}}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/news/confirm":{"post":{"operationId":"confirmZinnNews","summary":"Confirm a Zinn® news subscription with the e-mailed token (double opt-in).","description":"The page the e-mail's link opens POSTs the token here (a link's GET never confirms, so a mail scanner cannot). Only the NEWEST link confirms. `422` with refusal `refusal.news.linkExpired` (older than 7 days) or `refusal.news.linkInvalid`.","tags":["public"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","maxLength":1024}}}}}},"responses":{"200":{"description":"Confirmed (or already confirmed).","content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["confirmed","already"]}}}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/news/preferences/{token}":{"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"get":{"operationId":"getZinnNewsPreferences","summary":"A subscriber's Zinn® news settings (masked address, status, language).","tags":["public"],"security":[],"responses":{"200":{"description":"The settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicNewsPreferencesEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateZinnNewsPreferences","summary":"Change the language Zinn® news is written in.","tags":["public"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["locale"],"properties":{"locale":{"type":"string","maxLength":16}}}}}},"responses":{"200":{"description":"The settings after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicNewsPreferencesEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"unsubscribeZinnNewsPreferences","summary":"Unsubscribe from Zinn® news (and every other Zinn® marketing e-mail to the address).","tags":["public"],"security":[],"responses":{"200":{"description":"Unsubscribed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicNewsPreferencesEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/news/u/{token}":{"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"get":{"operationId":"unsubscribeZinnNewsByLink","summary":"The List-Unsubscribe URL opened in a browser - unsubscribes, then lands on the site.","tags":["public"],"security":[],"responses":{"302":{"description":"Redirect to the site's news page (`#unsubscribed`)."},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"oneClickUnsubscribeZinnNews","summary":"RFC 8058 one-click unsubscribe (the List-Unsubscribe URL on every Zinn® news e-mail).","description":"`200` with no body whatever the token (no oracle). Stops the news AND every other Zinn® marketing e-mail to that address (the lifecycle e-mails' suppression too).","tags":["public"],"security":[],"responses":{"200":{"description":"Unsubscribed (or nothing to do)."},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/quotes":{"post":{"operationId":"submitQuoteRequest","summary":"Ask us to price a project, or send us a message — no account.","description":"One endpoint for every public form (W43-83): `kind: quote` (the default) asks us to price a project and requires `project_type`; `kind: contact` is the contact form and requires `topic`. Both land in the one staff log (`listQuoteRequests`), are copied to the office inbox, and confirm to the sender in their own language.\n\n**Anonymous** — no credential, no tenant, and the only route into paid development work (development services are quote-only, owner ruling 2026-09-11).\n\nThree spam controls fire in order: a fail-closed per-IP and global budget charged **before the body is parsed**, a honeypot field, then Cloudflare Turnstile. The cheapest first, and the one that makes a vendor call last — so a flood cannot turn our anti-abuse check into an outbound traffic amplifier.\n\nAn unsolicited sales pitch (link selling, guest posts, outsourced development, lead generation, an offer to acquire our business or partner with us, or a sender already held as one) is refused with `422` and the refusal key `refusal.publicQuote.salesPitchNotWelcome` (owner, 2026-11-04). The row is kept under the staff Spam view with its Release button (`POST /v1/admin/quotes/{id}/not-spam`); no one is mailed and its attachments are not stored. A message that reads like a customer asking about our service (hosting their own sites, a price, a migration) is never refused. A message in any language is judged: one that is not English is read in English first by the support translator (failing open when no translator answers).\n\n⛔ `multipart/form-data` accepts attachments (a brief, a spec, a screenshot of the error). They are magic-byte verified against an allow-list and are **not servable to anybody** until a malware scan returns clean.\n\n⛔⛔ An attachment refused after the enquiry is written does **not** fail the request. The reply is still `201` with `attachments_refused` set: throwing away a description somebody spent ten minutes on because a file was the wrong type loses the customer and reads, to them, as the form being broken.","tags":["public"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequestInput"}},"multipart/form-data":{"schema":{"allOf":[{"$ref":"#/components/schemas/QuoteRequestInput"},{"type":"object","properties":{"attachments":{"type":"array","description":"Up to five files, 25 MB across the whole request.","items":{"type":"string","format":"binary"}}}}]}}}},"responses":{"201":{"description":"Filed. The reference is what a human quotes back at us.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequestAccepted"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/presales-tickets":{"post":{"operationId":"createPresalesTicket","summary":"Ask a question before you buy — no account.","description":"The \"Ask before you buy\" form on the public site (owner ruling 2026-11-02). Files a GUEST ticket on the sales desk with category `presales`; the presales AI answers it and the reply reaches the asker by e-mail, and staff are notified with a subject that starts `Pre-sales ticket:`.\n\n**Anonymous** — no credential, no tenant. Controls fire cheapest first: a fail-closed per-IP (3/hour) and global (300/hour) budget, a honeypot field (`website`, answered `202` silently), the per-address ticket budget, a blocked sender (`202` silently), then Cloudflare Turnstile. A question the content filter flags is still filed and answered, as `presales_spam` at low priority — only a Turnstile failure or a rate limit refuses one.","tags":["public"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PresalesTicketInput"}}}},"responses":{"201":{"description":"Filed. The reference is what the asker quotes back at us.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PresalesTicketAccepted"}}}},"202":{"description":"Accepted and dropped without a ticket (the honeypot was filled, or the sender is blocked). Deliberately indistinguishable from success to the sender.","content":{"application/json":{"schema":{"type":"object","required":["accepted"],"properties":{"accepted":{"type":"boolean"}}}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/pbs-library/kits":{"get":{"operationId":"listPbsKits","summary":"List the Page Builder Sandwich website kits.","description":"Every kit with its pages (titles only), palette and preview. Public: with no token every Pro kit is listed with `locked: true` (the free plugin shows it greyed out with a Go Pro upsell, feature pbs-r2); with a Pro licence session `pro_unlocked` is true and nothing is locked. Budget 600/hour per IP.","tags":["pbs-library"],"security":[{},{"pbsLibraryToken":[]}],"parameters":[{"name":"tier","in":"query","required":false,"schema":{"type":"string","enum":["free","pro"]}},{"name":"locale","in":"query","required":false,"description":"WordPress or platform locale (fr_FR, pt-BR); names, descriptions and page titles are served in it, English per string where no translation exists yet.","schema":{"type":"string","maxLength":16}}],"responses":{"200":{"description":"The catalogue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PbsKitCatalogue"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/pbs-library/kits/{slug}":{"get":{"operationId":"getPbsKit","summary":"One website kit with its page content (pbs-kit/1).","description":"A free kit is public. A Pro kit needs a Pro licence session; without one it answers `403` `pro_required`.","tags":["pbs-library"],"security":[{},{"pbsLibraryToken":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,60}$"}},{"name":"locale","in":"query","required":false,"description":"The site's locale; page text is served translated, English per string where no translation exists yet.","schema":{"type":"string","maxLength":16}}],"responses":{"200":{"description":"The kit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PbsKit"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/pbs-library/sessions":{"post":{"operationId":"createPbsLibrarySession","summary":"Start a cloud-library session for a licensed site.","description":"Called server-side by Page Builder Sandwich. The request is signed with the site's licensing install secret key: `signature = hex(HMAC-SHA256(install_secret_key, \"zinn-pbs-library/v1\\n{product}\\n{install_id}\\n{license_id}\\n{site_url}\\n{timestamp}\\n{nonce}\"))`. The engine reads the install from the licensing vendor with the product's keys, recomputes the signature, and checks the licence (active, this product, a paid plan). A proof older than 5 minutes (`proof_expired`) or seen before (`proof_replayed`) is `401`; a wrong signature or a lapsed licence `403` `licence_refused`; a free plan `403` `pro_required`; a vendor that cannot be reached `503` `licence_unverifiable`. The token is returned once and lives 30 days. Budget 30/hour per IP.","tags":["pbs-library"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PbsLibrarySessionInput"}}}},"responses":{"201":{"description":"The session. The token is shown only in this response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PbsLibrarySession"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/pbs-library/session":{"delete":{"operationId":"revokePbsLibrarySession","summary":"Disconnect this site from the cloud library.","tags":["pbs-library"],"security":[{"pbsLibraryToken":[]}],"responses":{"204":{"description":"Revoked."},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/pbs-library/account":{"get":{"operationId":"getPbsLibraryAccount","summary":"This site's library plan, quota and usage.","description":"What the plugin shows as the quota meter. `can_save` is false when the licence has lapsed (reads keep working; saving resumes automatically after renewal, §2.46).","tags":["pbs-library"],"security":[{"pbsLibraryToken":[]}],"responses":{"200":{"description":"The account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PbsLibraryAccount"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/pbs-library/items":{"get":{"operationId":"listPbsLibraryItems","summary":"List saved designs (the private library, or a team's with `team`).","tags":["pbs-library"],"security":[{"pbsLibraryToken":[]}],"parameters":[{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["section","page","style"]}},{"name":"team","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Up to 500 items, newest first.","content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PbsLibraryItem"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createPbsLibraryItem","summary":"Save a section, page or style.","description":"The content (block markup and styles, at most 2 MB) goes to object storage; images are uploaded first with `createPbsLibraryImage` and referenced by SHA-256. Refused with `409` `quota_exceeded` / `item_limit_reached` when the plan's ceiling would be passed (nothing is stored), `413` `item_too_large`, `403` `licence_inactive` (lapsed licence) or `read_only` (a read-only team member). Budget 600 writes/hour per session.","tags":["pbs-library"],"security":[{"pbsLibraryToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PbsLibraryItemInput"}}}},"responses":{"201":{"description":"Saved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PbsLibraryItemCreated"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/pbs-library/items/{itemId}":{"parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"team","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getPbsLibraryItem","summary":"Load one saved design with its content.","tags":["pbs-library"],"security":[{"pbsLibraryToken":[]}],"responses":{"200":{"description":"The item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PbsLibraryItemDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"patch":{"operationId":"updatePbsLibraryItem","summary":"Rename, re-tag or replace a saved design.","tags":["pbs-library"],"security":[{"pbsLibraryToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PbsLibraryItemInput"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PbsLibraryItem"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"delete":{"operationId":"deletePbsLibraryItem","summary":"Delete a saved design (its images are freed when nothing else uses them).","tags":["pbs-library"],"security":[{"pbsLibraryToken":[]}],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/pbs-library/images":{"post":{"operationId":"createPbsLibraryImage","summary":"Upload one image for a saved design (raw body, deduplicated by content).","description":"The body is the image itself (`Content-Type` image/webp, image/jpeg, image/png, image/gif or image/avif; no SVG). At most 2 MB and 2560 px on the longest edge — the plugin resizes and re-encodes before upload, and the engine re-checks the bytes. The same bytes twice answer `200` with `created: false` and charge nothing.","tags":["pbs-library"],"security":[{"pbsLibraryToken":[]}],"parameters":[{"name":"team","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"image/*":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"Already stored for this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PbsLibraryImage"}}}},"201":{"description":"Stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PbsLibraryImage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"description":"Not an accepted image type (`image_type`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/pbs-library/images/{sha256}":{"get":{"operationId":"getPbsLibraryImage","summary":"Download one image (or, with `meta=1`, check that it is already stored).","tags":["pbs-library"],"security":[{"pbsLibraryToken":[]}],"parameters":[{"name":"sha256","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}},{"name":"meta","in":"query","required":false,"schema":{"type":"string"}},{"name":"team","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The image bytes, or `{sha256, size_bytes}` with `meta`.","content":{"image/*":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"type":"object","required":["sha256","size_bytes"],"properties":{"sha256":{"type":"string"},"size_bytes":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/pbs-library/teams":{"get":{"operationId":"listPbsLibraryTeams","summary":"The Agency's team libraries (a team session sees its own team).","tags":["pbs-library"],"security":[{"pbsLibraryToken":[]}],"responses":{"200":{"description":"Teams.","content":{"application/json":{"schema":{"type":"object","required":["teams"],"properties":{"teams":{"type":"array","items":{"$ref":"#/components/schemas/PbsLibraryTeam"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createPbsLibraryTeam","summary":"Create a team library (Agency plan, feature pbs-c4).","tags":["pbs-library"],"security":[{"pbsLibraryToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":120}}}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PbsLibraryTeam"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/pbs-library/teams/{teamId}":{"delete":{"operationId":"deletePbsLibraryTeam","summary":"Delete a team library and every design in it.","tags":["pbs-library"],"security":[{"pbsLibraryToken":[]}],"parameters":[{"name":"teamId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/pbs-library/teams/{teamId}/invites":{"post":{"operationId":"createPbsLibraryTeamInvite","summary":"Create a single-use invite code for a team member or client site.","description":"The code is returned once and stored only as a SHA-256 hash.","tags":["pbs-library"],"security":[{"pbsLibraryToken":[]}],"parameters":[{"name":"teamId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","enum":["read","write"],"default":"read"},"days":{"type":"integer","minimum":1,"maximum":30,"default":7},"label":{"type":"string","maxLength":120}}}}}},"responses":{"201":{"description":"The invite.","content":{"application/json":{"schema":{"type":"object","required":["code","role","expires_at"],"properties":{"code":{"type":"string","description":"`zpi_…`, shown once."},"role":{"type":"string","enum":["read","write"]},"expires_at":{"type":"string","format":"date-time"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/pbs-library/teams/{teamId}/members":{"get":{"operationId":"listPbsLibraryTeamMembers","summary":"The sites that joined a team.","tags":["pbs-library"],"security":[{"pbsLibraryToken":[]}],"parameters":[{"name":"teamId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Members.","content":{"application/json":{"schema":{"type":"object","required":["members"],"properties":{"members":{"type":"array","items":{"$ref":"#/components/schemas/PbsLibraryTeamMember"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/pbs-library/teams/{teamId}/members/{memberId}":{"delete":{"operationId":"removePbsLibraryTeamMember","summary":"Remove a site from a team (its session stops at once).","tags":["pbs-library"],"security":[{"pbsLibraryToken":[]}],"parameters":[{"name":"teamId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"memberId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/pbs-library/team-sessions":{"post":{"operationId":"joinPbsLibraryTeam","summary":"Redeem a team invite code for a team session (no licence needed on this site).","tags":["pbs-library"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code","site_url"],"properties":{"code":{"type":"string","maxLength":100},"site_url":{"type":"string","format":"uri","maxLength":500}}}}}},"responses":{"201":{"description":"The team session. The token is shown only in this response.","content":{"application/json":{"schema":{"type":"object","required":["token","expires_at","team","role"],"properties":{"token":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"team":{"$ref":"#/components/schemas/PbsLibraryTeam"},"role":{"type":"string","enum":["read","write"]}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/seo-connect/start":{"post":{"operationId":"startSeoConnect","summary":"Start connecting a Zinn® SEO site to a Zinn® account (device code).","description":"Called server-side by the Zinn® SEO WordPress plugin after the site owner agreed on its opt-in screen (WordPress.org guideline 7). Returns a secret `device_code` the site keeps and a short `user_code` (`BCDF-GHJK`) with the page the plugin opens in a NEW TAB, where a signed-in member approves the site for one organization (`approveSeoConnect`). The site then polls `exchangeSeoConnect`. Requests last ten minutes. No password ever enters wp-admin. ADR 0038.\n\n**Anonymous**, server-to-server (no CORS). Budget: 120/hour per IP, sized for shared hosting where many sites share one address; `429` with `Retry-After`.","tags":["seo-connect"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoConnectStartInput"}}}},"responses":{"201":{"description":"A pending request. `device_code` appears only in this response.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoConnectDeviceCode"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/seo-connect/signup":{"post":{"operationId":"seoConnectSignup","summary":"Create a Zinn® account from inside the plugin, and start connecting the site.","description":"The \"I have no account\" door (owner, round 2). For a NEW address it creates the account the way every other door does (Keycloak identity with no password, organization, owner membership, audit row) and e-mails a set-password-and-verify link in the person's language; the pending request is bound to the new organization and `exchangeSeoConnect` releases the token once the person has signed in with the verified address — they can also approve it explicitly on the verification page.\n\n⛔ For an address that already has an account nothing is created or bound: `account` is `exists` and the person approves the request signed in. That answer reveals that an account exists, exactly as guest checkout's `next: \"login\"` does, and is budgeted for the same reason: 10/hour per IP and 3/hour per address (fail-closed). A filled `website` honeypot answers `202` and creates nothing. Requests from this door last 24 hours (the e-mailed link's lifetime).","tags":["seo-connect"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoConnectSignupInput"}}}},"responses":{"201":{"description":"A pending request, and whether an account was created.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoConnectSignupResult"}}}},"202":{"description":"The honeypot was filled. Nothing was stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginSupportDiscarded"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/seo-connect/token":{"post":{"operationId":"exchangeSeoConnect","summary":"Exchange an approved device code for the site's connection token.","description":"The plugin polls this every `interval` seconds (RFC 8628 §3.4). Until the request is approved it answers `400` with `error.code` `authorization_pending`; polling faster is `slow_down`; a refused request is `access_denied`; an unknown, expired or already used code is `expired_token`. Once approved it answers `200` with the `zsc_` token — exactly once (`Cache-Control: no-store`); the engine stores only its SHA-256. A site that connects again to the same organization retires its previous token.","tags":["seo-connect"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["device_code"],"properties":{"device_code":{"type":"string","maxLength":200}}}}}},"responses":{"200":{"description":"Connected. The token appears only in this response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoConnectToken"}}}},"400":{"description":"Not (yet) exchangeable: `authorization_pending`, `slow_down`, `access_denied` or `expired_token` in `error.code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/seo-connect/requests/{userCode}":{"parameters":[{"name":"userCode","in":"path","required":true,"description":"The code the plugin showed (`BCDF-GHJK`; case, spaces and the dash are ignored).","schema":{"type":"string","maxLength":20}}],"get":{"operationId":"getSeoConnectRequest","summary":"Read a pending site connection request (the approval page).","description":"The dashboard's approval page (`/connect/seo?code=`) reads this after Keycloak signed the person in. `approvable_org_ids` are the organizations where they hold `billing.payment.manage`, the permission a site that spends the org's credits needs. An unknown, used or expired code is `404`. 60 look-ups or answers per person per hour.","tags":["seo-connect"],"responses":{"200":{"description":"The pending request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoConnectRequest"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/seo-connect/approve":{"post":{"operationId":"approveSeoConnect","summary":"Approve a site connection for one organization.","description":"The caller must hold `billing.payment.manage` in `org_id` (or `X-Zinn-Org`; omitted, the one org they hold it in). Single use: a second answer from another tab is `404`. Writes an audit event `seo_connect.approved`; the connection itself, and its audit event `seo_connection.created`, are written when the site exchanges its device code.","tags":["seo-connect"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoConnectAnswer"}}}},"responses":{"200":{"description":"Approved.","content":{"application/json":{"schema":{"type":"object","required":["status","site_url","org"],"properties":{"status":{"type":"string","enum":["approved"]},"site_url":{"type":"string"},"org":{"$ref":"#/components/schemas/SeoConnectionOrg"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/seo-connect/deny":{"post":{"operationId":"denySeoConnect","summary":"Refuse a site connection request.","description":"Any signed-in person holding the code may refuse it; the site's next poll is `access_denied`. Single use, like `approveSeoConnect`.","tags":["seo-connect"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoConnectAnswer"}}}},"responses":{"200":{"description":"Refused.","content":{"application/json":{"schema":{"type":"object","required":["status","site_url"],"properties":{"status":{"type":"string","enum":["denied"]},"site_url":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/seo-connection":{"get":{"operationId":"getSeoConnection","summary":"Read this site's own Zinn® SEO connection.","description":"The plugin's Account screen reads this. A revoked token answers `401` with `error.code = \"connection_revoked\"`, an unknown one `\"invalid_token\"`, so the plugin can show the right reconnect screen.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"responses":{"200":{"description":"The connection, with the organization it spends from.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoSiteConnectionSelf"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"revokeSeoConnection","summary":"Disconnect this site (revoke from the site side).","description":"Revokes the connection the token names and writes an audit event in the organization. Every later call with that token is `401` `connection_revoked`.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"responses":{"204":{"description":"Revoked."},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/seo-connection/target":{"get":{"operationId":"getSeoSiteTarget","summary":"The connected site's own watch-list row, created on first use.","description":"Every Zinn® SEO tool works on this row: read and change it with the `/v1/visibility/targets/{targetId}/*` operations using the same `zsc_` token. The first call creates it for the site's own domain (or adopts the organization's existing row for that domain, without changing who pays for it), with no products switched on. Switch products on with `updateVisibilityTarget` — `funding: credits` makes the ones the plan does not hold pay-per-use.\n\nA connected site reaches this row only: another target of its organization answers `404`, and it cannot add a domain (`403`, `refusal.seoConnect.ownSiteOnly`).","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"responses":{"200":{"description":"The site's target.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisibilityTarget"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/seo-connection/account":{"get":{"operationId":"getSeoAccount","summary":"The site's credit position — balance, 30-day forecast, holds, prices.","description":"What the plugin's Account screen shows: the organization's Zinn® credit balance, what the site's scheduled pay-per-use work will cost over the next 30 days (and the day the balance runs out at that rate), the products held for want of credit, the price of each unit, the packs on sale, the auto top-up settings, this site's monthly limit and what it has spent this month, and the page to buy credits on (open it in a new tab). Answers for an account in bad standing too, so the site can say why its tools stopped.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"responses":{"200":{"description":"The account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoAccount"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/seo-connection/index-checks":{"post":{"operationId":"checkSeoIndex","summary":"Check whether pages of the site are in Google's index. Spends credits.","description":"Up to 1,000 addresses on the connected site per call (more is more calls), duplicates checked once. Needs the `seo.spend` scope. The price of every page is debited up front (`index_check` in `getSeoAccount`) and the check runs in the background: read the outcome with `getSeoIndexCheck`. A page Google's index could not be asked about is `indexed: null` — unknown, never \"not indexed\" — and is refunded, so the site pays only for answers.\n\nRefused before anything is spent: an address on another host (`422`), no or too many addresses (`422`), not enough credit, the site's monthly limit or an account not in good standing (`403`).","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoIndexCheckInput"}}}},"responses":{"202":{"description":"Debited and started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoIndexCheck"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/seo-connection/index-checks/{runId}":{"parameters":[{"name":"runId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"get":{"operationId":"getSeoIndexCheck","summary":"One batch of index checks, with every page's answer.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"responses":{"200":{"description":"The batch.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoIndexCheck"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/seo-connection/research/{tool}":{"parameters":[{"name":"tool","in":"path","required":true,"schema":{"type":"string","enum":["keywords","domain","gap"]},"description":"`keywords` — keyword research (around `seed`, for `page_url`, or for the whole site); `domain` — what the site's domain is worth in search; `gap` — who else ranks for the site's phrases and what they win that it does not."}],"post":{"operationId":"runSeoResearch","summary":"Run one research report on the site. Spends credits when the plan lacks it.","description":"The same run as `runVisibilityAudit` (`keyword_research`, `domain_score`, `competitors`) on the site's own target, with the same refusals, workflow id and audit row; read the result from `listVisibilityAudits`. When the organization's plan does not include the product it is pay-per-use (one `keyword_list` or `domain_report` unit), needs `seo.spend`, and does NOT add the product to the site's schedule — one question is not a subscription.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoResearchInput"}}}},"responses":{"202":{"description":"Started.","content":{"application/json":{"schema":{"type":"object","required":["workflow_id","kind","target_id"],"properties":{"workflow_id":{"type":"string"},"kind":{"$ref":"#/components/schemas/VisibilityAuditKind"},"target_id":{"type":"string","format":"uuid"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/seo-connection/notices":{"get":{"operationId":"listSeoNotices","summary":"The connected site's notices feed — credits, alerts and SEO Guard.","description":"What the Zinn® SEO plugin shows in wp-admin and may send from the site's own mailer: low balance, the 30-day run-out forecast, scheduled checks paused for credit, their resume, ranks that fell, backlinks lost, pages dropped from Google, AI answers that stopped or started quoting the site, new brand mentions, and every SEO Guard problem and its fix. Organization-wide notices (credits) and this site's own domain only, newest first, the last 90 days. Needs the `seo.notices` scope.\n\nEach item is rendered from the SAME template as the Zinn Digital® e-mail, in `locale` (a WordPress locale such as `de_DE` or a registry code; unknown falls back to English): `title` and `message` for the notice, `site_email` for the site's own mailer, with `default_on` saying whether the plugin sends it unless the site owner switched it off. Send `If-None-Match` with the last `ETag`; an unchanged feed answers `304` with no body. Cache for 15 minutes.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"parameters":[{"name":"locale","in":"query","required":false,"schema":{"type":"string","maxLength":16}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"If-None-Match","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The feed.","headers":{"ETag":{"description":"Validator for `If-None-Match`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoNoticeFeed"}}}},"304":{"description":"Unchanged since the supplied `If-None-Match`.","headers":{"ETag":{"description":"The unchanged validator.","schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"ackSeoNotice","summary":"Dismiss notices for this site.","description":"Dismisses for THIS site only — another site of the same organization still sees them. Send `ids`, or `all: true` for every notice in the feed. Needs `seo.notices`.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoNoticeAckInput"}}}},"responses":{"200":{"description":"How many were newly dismissed.","content":{"application/json":{"schema":{"type":"object","required":["acked"],"properties":{"acked":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/seo-connection/guard":{"get":{"operationId":"getSeoGuard","summary":"SEO Guard for this site — settings, open problems and recent fixes.","description":"SEO Guard checks the site from outside: the home page and up to 20 key pages for noindex (including WordPress's \"Discourage search engines\"), robots.txt blocking Google, the sitemap, canonical addresses changing together, the home title, the certificate's expiry and whether the site answers at all. Daily on Free, every 15 minutes on a Zinn® SEO Pro licence Freemius confirms. Created switched on at first use. Needs `seo.read`.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"responses":{"200":{"description":"The site's Guard.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoGuard"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"put":{"operationId":"setSeoGuard","summary":"Change SEO Guard for this site.","description":"Any of: switch it on or off, set the key pages (on this site only, at most 20), send the Pro licence (checked with Freemius — the plan is never taken from the site; a confirmed licence holds the 15-minute cadence for 8 days and is re-sent by the plugin), accept the current canonical addresses as the new normal (`rebaseline`), or ask for a check at the next sweep (`check_now`). Audited. Needs `seo.run`.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoGuardInput"}}}},"responses":{"200":{"description":"The site's Guard after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoGuard"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/seo-connection/cloak-checks":{"post":{"operationId":"fetchAsBot","summary":"Fetch a page as a visitor and as Googlebot, and compare. Free.","description":"The hacked-site detector's cloak check: one page of this site fetched with a browser user agent and with Google's crawler user agent, and the two compared — status, redirect, title, text, spam words and outbound links only Googlebot sees, and the Japanese-keyword hack. Runs in the background: read it with `getSeoSiteCheck`. It sees cloaking keyed on the user agent, not on Google's own addresses (`limits`). Free, at most 200 a day per site. Needs `seo.run`.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoSiteCheckInput"}}}},"responses":{"202":{"description":"Started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoSiteCheck"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/seo-connection/lab-tests":{"post":{"operationId":"runSeoLabTest","summary":"Lighthouse lab test of one page on our own runner. Free on Zinn Digital® hosting.","description":"Performance, accessibility, best practices and SEO scores with the Core Web Vitals and the biggest opportunities. Free when the page is on a site this organization hosts with Zinn Digital®; otherwise one `audit_page` unit of Zinn® credits (`getSeoAccount`), debited up front and refunded in full when no reading comes back, and needing `seo.spend`. Refused before anything is spent: another host (`422`), not enough credit, the site's monthly limit or an account not in good standing (`403`). Runs in the background: read it with `getSeoSiteCheck`.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoSiteCheckInput"}}}},"responses":{"202":{"description":"Started (and paid, unless free).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoSiteCheck"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/seo-connection/site-checks/{checkId}":{"parameters":[{"name":"checkId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"get":{"operationId":"getSeoSiteCheck","summary":"One cloak check or lab test, with its result.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"responses":{"200":{"description":"The check.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoSiteCheck"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/plugin-ai/complete":{"post":{"operationId":"pluginAiComplete","summary":"Run the Zinn® SEO plugin's AI on Zinn® credits. Spends credits.","description":"The alternative to the site owner's own AI key in the plugin (zs-197): up to 20 independent requests in one call, run concurrently, each metered on the one Zinn® AI meter (surface `plugin_ai`) and debited from the connected site's org — filed against the site, so its monthly limit and the agency overview count it. A request that fails is reported in place (`ok: false` with a `failure`) and charged nothing; the others still return. A `schema` (a JSON object schema) asks for a structured answer, returned as `data`. The model is the cheapest one we have verified and can price. Needs the `seo.spend` scope.\n\nRefused before anything is sent or spent (`403`, with a `failure` of class `refused`): no Zinn® credit (the app's free daily allowance is never used by the plugin), the site's monthly limit, or an account not in good standing. When EVERY request failed, `503` with the `failure` of the first: `provider_outage` names the AI vendor and its status page; `our_fault` names nobody.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginAiCompleteInput"}}}},"responses":{"200":{"description":"Every request answered or reported in place.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginAiCompleteResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/seo-connection/data-sources":{"get":{"operationId":"getSeoDataSources","summary":"The SEO data sources this site can connect, its keys, what it tracks and the latest values.","description":"Zinn® SEO stage C2 (zs-500…zs-509). Every source the site owner can bring their OWN account for — Ahrefs (the free Domain Rating key, or a Site Explorer API key), Majestic, Moz, Semrush, SE Ranking, Open PageRank — plus Zinn® Authority (our DataForSEO backlink data on Zinn® credits): their metrics, attribution, where to get a key and the unit each vendor counts in. Then the organization's connected keys (never the key itself — its last four characters, status and the allowance the vendor last reported, with the time it was read), this site's feeds (shown and tracked metrics, alert rules, cadence, state), its domains (itself and competitors) and the two most recent values of every metric. Free. Needs `seo.read`.","tags":["seo-data"],"security":[{"seoSiteConnection":[]}],"responses":{"200":{"description":"Sources, keys, feeds, targets and latest values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoDataSources"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/seo-connection/data-sources/{source}/key":{"parameters":[{"$ref":"#/components/parameters/SeoDataSource"}],"put":{"operationId":"connectSeoDataKey","summary":"Connect the site owner's own key for one SEO data source (stored in Vault).","description":"Checks the key with the vendor using a call the vendor does not charge for, then stores it in Vault (`secret/orgs/<org>/seo-connections/<id>`) — never in a column, a log or the WordPress database — and keeps only its last four characters. Replaces an earlier key for the same source in the organization (the old one is deleted from Vault), and every feed that used it moves to the new key and runs again. A key the vendor refuses is not stored (`422 refusal.seoData.keyRefused`); a real key with no units left is stored and its feeds wait. A refusal that came from the vendor carries `failure` (§57): `credential_problem` with the vendor's `keys_url` for a wrong or revoked key, or its `billing_url` when the account's plan or subscription does not include the API; `provider_outage` (with the vendor's `status_url` where it publishes one) when the vendor is down or asked us to slow down (`503 refusal.seoData.vendorUnavailable`). Zinn®'s own vendor keys are never used for this. Moz takes an API token, or an Access ID with a Secret Key. Each vendor's requests and answers are checked against its published API reference (Semrush, SE Ranking and Moz read 2026-10-13). Needs `seo.run`.","tags":["seo-data"],"security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoDataKeyInput"}}}},"responses":{"200":{"description":"The connected key (without the key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoDataAccount"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"delete":{"operationId":"removeSeoDataKey","summary":"Forget the organization's key for one source (deleted from Vault).","description":"Deletes the key from Vault and pauses every feed that used it (`paused_key`); the history stays. Removing a key that is not there is not an error. Needs `seo.run`.","tags":["seo-data"],"security":[{"seoSiteConnection":[]}],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/seo-connection/data-sources/{source}/feed":{"parameters":[{"$ref":"#/components/parameters/SeoDataSource"}],"put":{"operationId":"saveSeoDataFeed","summary":"Choose which metrics this site shows and tracks from a source, the alerts and the cadence.","description":"`show` are dashboard cards; `track` are kept as history and judged by `alerts` (`drops` / `rises` by at least `by`, or goes `above` / `below` `by` — the crossing, not every check it stays there). `cadence_days` is 1, 7 or 30. `enabled: false` pauses scheduled checks (`paused_user`). A keyed source needs its key connected first (`422 refusal.seoData.keyRequired`). Zinn® Authority spends Zinn® credit on every check, so it also needs `seo.spend`. Needs `seo.run`.","tags":["seo-data"],"security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoDataFeedInput"}}}},"responses":{"200":{"description":"The saved feed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoDataFeed"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/seo-connection/data-sources/{source}/estimate":{"parameters":[{"$ref":"#/components/parameters/SeoDataSource"}],"post":{"operationId":"estimateSeoDataFeed","summary":"What a schedule will spend, before it is saved.","description":"Units per check and per month in the vendor's own unit (API units, rows, credits, domains), for this site and its competitors, beside the units the vendor last reported left; for Zinn® Authority, the Zinn® credit per check and per month at the price row. Free; spends nothing. Needs `seo.read`.","tags":["seo-data"],"security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"metrics":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":40}},"cadence_days":{"type":"integer","enum":[1,7,30],"default":30}}}}}},"responses":{"200":{"description":"The estimate.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoDataEstimate"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/seo-connection/data-sources/{source}/run":{"parameters":[{"$ref":"#/components/parameters/SeoDataSource"}],"post":{"operationId":"runSeoDataFeed","summary":"Check this source for the site now.","description":"Starts one check (a Temporal workflow) and answers `202` at once; read the result with `getSeoDataSources`. Spends the site owner's own units at the vendor — or, for Zinn® Authority, Zinn® credit (paid up front, refunded for domains with no answer; needs `seo.spend`). Needs `seo.run`.","tags":["seo-data"],"security":[{"seoSiteConnection":[]}],"responses":{"202":{"description":"Started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoDataFeed"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/seo-connection/data-targets":{"put":{"operationId":"setSeoDataTargets","summary":"The competitors this site measures beside itself.","description":"Replaces the competitor list (up to 10; the site itself is always measured and cannot be removed). Every source the site tracks measures them on its next check. Needs `seo.run`.","tags":["seo-data"],"security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["competitors"],"properties":{"competitors":{"type":"array","maxItems":50,"items":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","maxLength":253},"label":{"type":"string","maxLength":80}}}}}}}}},"responses":{"200":{"description":"The site's domains.","content":{"application/json":{"schema":{"type":"object","required":["targets"],"properties":{"targets":{"type":"array","items":{"$ref":"#/components/schemas/SeoDataTarget"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/seo-connection/data-history":{"get":{"operationId":"getSeoDataHistory","summary":"One metric's history for the site and its competitors.","description":"Day by day, oldest first, per domain, over the last `days` (up to 1,095). A `null` value is a day the vendor gave no figure — never zero. Carries the vendor's attribution, which every chart prints. Free. Needs `seo.read`.","tags":["seo-data"],"security":[{"seoSiteConnection":[]}],"parameters":[{"name":"source","in":"query","required":true,"schema":{"type":"string","maxLength":32}},{"name":"metric","in":"query","required":true,"schema":{"type":"string","maxLength":40}},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1095,"default":365}}],"responses":{"200":{"description":"The series.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoDataHistory"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/seo/data-overview":{"get":{"operationId":"getSeoDataOverview","summary":"Every connected site's tracked SEO metrics in one table (agencies).","description":"For each active Zinn® SEO site in the organization: the latest and previous value of every metric it tracks for its own domain, with the vendor's attribution, and which sources are paused; plus the organization's connected keys (last four characters only). Needs `billing.view` in the organization (`org_id` or `X-Zinn-Org`; omitted, the one org the caller holds it in).","tags":["seo-data"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"The organization.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The table.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoDataOverview"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/seo-connection/crux":{"get":{"operationId":"getSeoCrux","summary":"Real-visitor Core Web Vitals (Chrome UX Report) for the site. Free.","description":"What real Chrome users experienced on the connected site's origin (or one of its pages) over Google's rolling 28 days: p75 and the good / needs-improvement / poor split for LCP, INP, CLS, FCP and TTFB, and Google's Core Web Vitals assessment. Read from the CrUX API, or from the same record inside PageSpeed Insights; cached a day per origin or page and form factor (`cached`). A site below CrUX's traffic threshold is `has_data: false` — an answer, not an error; a page never borrows its origin's numbers. Free. Needs `seo.read`.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"parameters":[{"name":"url","in":"query","required":false,"schema":{"type":"string","maxLength":2000},"description":"A page or the home page of the connected site; defaults to the home page."},{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["origin","url"],"default":"origin"}},{"name":"form_factor","in":"query","required":false,"schema":{"type":"string","enum":["phone","desktop"],"default":"phone"}}],"responses":{"200":{"description":"The record, or `has_data` false.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoCrux"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/seo-connection/edge":{"get":{"operationId":"getSeoEdge","summary":"Whether the site is on Zinn® hosting, and what the engine does at its edge.","description":"On Zinn® hosting the plugin needs no Cloudflare connection: the engine purges the site's pages at its edge and makes the zone's AI-crawler setting follow the plugin's robots choice, on the account that serves the site. `ai_bots.why_not` says why the crawler switch is unavailable (`shared_zone`, `held`, `no_zone_control`, `unreadable`). Needs `seo.read`.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"responses":{"200":{"description":"The site's edge.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoEdge"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"updateSeoEdge","summary":"Purge the site's pages at the edge and set its AI-crawler rule. Free.","description":"Called by the plugin when an SEO change makes pages stale (`purge_urls`, up to 30, on this site only) or changes many at once (`purge_everything`: server and edge cache, like the dashboard's Clear cache), and when its AI-crawler setting changes (`ai_bots`: `block` blocks AI crawlers at the edge, `allow` lets them through). The crawler rule is zone-wide, so it is refused on a zone shared by several sites (`422`), on a site our team holds back from automatic edge changes (`409`) and where we hold no credential for the CDN (`409`). A site not on Zinn® hosting is `409`. Audited. Needs `seo.run`.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoEdgeUpdateInput"}}}},"responses":{"200":{"description":"What was done.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoEdgeUpdateResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/seo-connection/cdn":{"get":{"operationId":"getSeoCdn","summary":"The Zinn® CDN for this site — offered here or not, its zone, this month, its price.","description":"Zinn® SEO stage CDN1 (zs-658, owner decision Q182). A WordPress site hosted ELSEWHERE can serve its images, CSS, JavaScript and fonts from the Zinn® CDN (a Bunny pull zone pulling from the site's own https origin; the plugin rewrites static asset URLs to `zone.hostname`). `offered` is false for a site hosted with us (it keeps the Premium CDN tier) and for a site not on `https://`. `price` is derived from the vendor's cost at the 2x markup: USD micros per decimal GB per billing band, and the monthly minimum. Free. Needs `seo.read`.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"responses":{"200":{"description":"The site's CDN.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoCdn"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"enableSeoCdn","summary":"Switch the Zinn® CDN on for this site, in one click. Idempotent.","description":"Creates (or finds) the site's pull zone and answers with its hostname (`201` when created, `200` when it already existed or was switched back on). ⛔ Nothing is charged at the click: each UTC day's traffic is charged afterwards from Zinn® credit at the 2x markup, and each month is topped up to a pro-rated minimum. Refused with nothing created: a site hosted with us (`409`, it keeps the Premium CDN), a site not on https (`422`), credit below one month's minimum (`422`, `refusal.zinnCdn.noCredit`), an account not in good standing (`403`). Audited. Needs `seo.spend`.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"responses":{"200":{"description":"Already on (or switched back on).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoCdn"}}}},"201":{"description":"Switched on; the zone was created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoCdn"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"delete":{"operationId":"disableSeoCdn","summary":"Switch the Zinn® CDN off for this site.","description":"The plugin stops rewriting at once; the zone's last days are still billed, then the zone is removed by the metering pass. Switching on again before that reuses it. Audited. Needs `seo.run`.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"responses":{"200":{"description":"Switched off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoCdn"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/seo-connection/cdn/purge":{"post":{"operationId":"purgeSeoCdn","summary":"Drop everything the site's Zinn® CDN has cached. Free.","description":"The next request for each file is read from the site again. Called by the plugin's purge button and when the site's media, theme or plugins change. `404` when the CDN is not on. Audited. Needs `seo.run`.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"responses":{"200":{"description":"Purged.","content":{"application/json":{"schema":{"type":"object","required":["purged","hostname"],"properties":{"purged":{"type":"boolean"},"hostname":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/zinn-cdn/zones":{"get":{"operationId":"listZinnCdnZones","tags":["seo-connect"],"summary":"Every Zinn® CDN of the organization, with this month's traffic and cost.","description":"Zinn® SEO stage CDN1. One row per site whose Zinn® CDN is on, paused or switched off, or was billed this month: its state, hostname, and this calendar month's bytes, charges and anything still owed (USD micros, paid from Zinn® credit). Needs `billing.view` (`org_id` or `X-Zinn-Org`).","parameters":[{"name":"org_id","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The organization's CDN zones and the price.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ZinnCdnZoneList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/seo-connection/google":{"get":{"operationId":"getSeoGoogle","summary":"Whether the site's own Google account is connected, and what it reads. Free.","description":"The connected site's link to its owner's own Google account (Zinn® SEO stage P11): which account, which features Google granted (`search_console`, `analytics`, `business`, `indexing`) and which Search Console property, GA4 property and Business Profile location the site reads. With `choices=1` it also lists the Search Console properties that cover this site's address and the GA4 properties whose web streams measure it (a few Google calls — for the settings screen); when exactly one of each covers the site it is chosen. Needs `seo.read`.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"parameters":[{"name":"choices","in":"query","required":false,"schema":{"type":"string","enum":["0","1","true","false"]}}],"responses":{"200":{"description":"The link.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoGoogleLink"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"post":{"operationId":"startSeoGoogle","summary":"Start \"Connect Google\" — Google's consent page for this site.","description":"Answers Google's consent URL for the one Zinn® Google app; the plugin opens it in a new tab. Search Console is always asked for; `features` adds `analytics`, `business` and `indexing`. Earlier grants are kept (incremental consent). Google returns the browser to `completeSeoGoogle`, which sends it back to `return_url` — an address on the connected site only — with `zseo_google=connected|cancelled|scope|failed`. Needs `seo.run`.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["return_url"],"properties":{"features":{"type":"array","maxItems":8,"items":{"type":"string","enum":["search_console","analytics","business","indexing"]}},"return_url":{"type":"string","maxLength":2000}}}}}},"responses":{"201":{"description":"Google's consent URL.","content":{"application/json":{"schema":{"type":"object","required":["consent_url","status"],"properties":{"consent_url":{"type":"string"},"status":{"type":"string","enum":["pending","active","needs_reconnect"]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"patch":{"operationId":"updateSeoGoogle","summary":"Choose the Search Console property, GA4 property and Business Profile location.","description":"Each choice is checked against what Google says the connected account can see, and a Search Console or GA4 property must cover this site's address. An empty string clears a choice; an absent field is left as it is. Audited (`seo_google.updated`). Needs `seo.run`.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"search_console_property":{"type":["string","null"],"maxLength":300},"analytics_property":{"type":["string","null"],"maxLength":40},"business_location":{"type":["string","null"],"maxLength":120}}}}}},"responses":{"200":{"description":"The link after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoGoogleLink"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"delete":{"operationId":"disconnectSeoGoogle","summary":"Disconnect the site's Google account.","description":"Forgets the stored grant (Vault) and the site's link; it does NOT revoke at Google, because that withdraws the whole grant of the Google account to the Zinn® app (every other site, GA4 listing and report sink using it). Revoking the site's Zinn® connection does the same. Audited (`seo_google.disconnected`). Needs `seo.run`.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"responses":{"204":{"description":"Disconnected (or was not connected)."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/seo-connection/google/callback":{"get":{"operationId":"completeSeoGoogle","summary":"Google's return after consent (a browser redirect).","description":"Anonymous: Google redirects the person's browser here. Authorised by the signed `state` alone (15 minutes). Stores the grant in Vault and redirects to the WordPress page the consent started from, with `zseo_google=connected|cancelled|scope|failed`. An unreadable state goes to the help page, never to an address taken from the request.","tags":["seo-connect"],"security":[],"parameters":[{"name":"state","in":"query","required":true,"schema":{"type":"string","maxLength":2000}},{"name":"code","in":"query","required":false,"schema":{"type":"string","maxLength":2000}},{"name":"error","in":"query","required":false,"schema":{"type":"string","maxLength":200}}],"responses":{"302":{"description":"Back to the WordPress site (or the help page)."}}}},"/v1/seo-connection/google/search-analytics":{"post":{"operationId":"querySeoSearchAnalytics","summary":"Search Console clicks, impressions, CTR and position for the chosen property. Free.","description":"Google's `searchAnalytics.query` for the property this site chose, with Google's own fields only: dates (at most 16 months), up to four of `date`, `hour`, `query`, `page`, `country`, `device`, `searchAppearance`, filter groups, `type`, `aggregationType`, `dataState`, `rowLimit` (at most 25,000) and `startRow`. `more` is true when the page is full: ask again with the next `startRow` — the plugin pages through every row of a large site. Needs `seo.read`.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoSearchAnalyticsQuery"}}}},"responses":{"200":{"description":"Rows.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoSearchAnalytics"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/seo-connection/google/url-inspection":{"post":{"operationId":"inspectSeoUrl","summary":"Google's own index verdict for one page of this site (URL Inspection). Free.","description":"Search Console's URL Inspection for a page on the connected site: verdict, coverage, last crawl, Google's chosen canonical and yours, robots and fetch state, mobile and rich result verdicts. Google allows 2,000 a day per property; the plugin spends them on the pages that matter. Needs `seo.read`.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","maxLength":2000},"language":{"type":"string","maxLength":16,"default":"en-US"}}}}}},"responses":{"200":{"description":"The verdict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoUrlInspection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/seo-connection/google/sitemaps":{"get":{"operationId":"listSeoSitemaps","summary":"The sitemaps Search Console knows for the chosen property, with errors and counts.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"responses":{"200":{"description":"Sitemaps.","content":{"application/json":{"schema":{"type":"object","required":["sitemaps"],"properties":{"sitemaps":{"type":"array","items":{"$ref":"#/components/schemas/SeoSitemapStatus"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"post":{"operationId":"submitSeoSitemap","summary":"Submit one of this site's sitemaps to Search Console.","description":"The plugin calls it on connect and whenever the sitemap's address changes (no-trace on or off). The address must be on the connected site. Audited (`seo_google.sitemap_submitted`). Needs `seo.run`.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sitemap_url"],"properties":{"sitemap_url":{"type":"string","maxLength":2000}}}}}},"responses":{"200":{"description":"Submitted.","content":{"application/json":{"schema":{"type":"object","required":["submitted"],"properties":{"submitted":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/seo-connection/google/indexing":{"post":{"operationId":"notifySeoIndexing","summary":"Tell Google's Indexing API a job posting or livestream page changed or went.","description":"Google allows the Indexing API only for pages with JobPosting or BroadcastEvent structured data; the plugin calls it for those pages alone. Needs the `indexing` grant and `seo.run`. Audited (`seo_google.indexing_notified`).","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","maxLength":2000},"type":{"type":"string","enum":["URL_UPDATED","URL_DELETED"],"default":"URL_UPDATED"}}}}}},"responses":{"200":{"description":"Google's acknowledgement.","content":{"application/json":{"schema":{"type":"object","required":["url","type","notified_at"],"properties":{"url":{"type":"string"},"type":{"type":"string","enum":["URL_UPDATED","URL_DELETED"]},"notified_at":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/seo-connection/google/analytics":{"post":{"operationId":"runSeoAnalyticsReport","summary":"GA4 landing-page sessions, key events and revenue for the chosen property. Free.","description":"A GA4 `runReport` with dimensions and metrics from fixed lists (landing page, date, channel, source, medium, country, device; sessions, engaged sessions, users, key events, revenue, purchases, page views, engagement), up to four date ranges, and an optional channel filter (`Organic Search`). Reads only: no tracking script is added to the site. Needs the `analytics` grant and `seo.read`.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoAnalyticsReportRequest"}}}},"responses":{"200":{"description":"Rows.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoAnalyticsReport"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/seo-connection/google/business/reviews":{"get":{"operationId":"listSeoBusinessReviews","summary":"Google reviews of the chosen Business Profile location, newest first.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"parameters":[{"name":"page_token","in":"query","required":false,"schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"One page of reviews.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoBusinessReviews"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/seo-connection/google/business/reviews/{reviewId}/reply":{"post":{"operationId":"replySeoBusinessReview","summary":"Reply to (or change the reply to) one Google review.","description":"Audited (`seo_google.review_replied`). Needs the `business` grant and `seo.run`.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"parameters":[{"name":"reviewId","in":"path","required":true,"schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","maxLength":4096}}}}}},"responses":{"200":{"description":"The reply as Google holds it.","content":{"application/json":{"schema":{"type":"object","required":["id","reply","replied"],"properties":{"id":{"type":"string"},"reply":{"type":"string"},"replied":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/seo-connection/google/business/posts":{"post":{"operationId":"createSeoBusinessPost","summary":"Publish a post on the chosen Business Profile location.","description":"A standard local post with an optional \"Learn more\" button to a page on this site and an optional photo (an https address Google fetches). Audited (`seo_google.post_created`). Needs the `business` grant and `seo.run`.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["summary"],"properties":{"summary":{"type":"string","maxLength":1500},"url":{"type":"string","maxLength":2000},"image_url":{"type":"string","maxLength":2000}}}}}},"responses":{"201":{"description":"Published.","content":{"application/json":{"schema":{"type":"object","required":["name","url","state"],"properties":{"name":{"type":"string"},"url":{"type":"string"},"state":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/seo-connection/catalogue":{"get":{"operationId":"listSeoCatalogue","summary":"Every live SEO product V2 sells, its price, and what this site's account holds.","description":"The live catalogue rows (code, name, price, currency, monthly or one-off) of every product category the Zinn® SEO plugin offers, each with the plugin screen and context that offers it, read through the storefront's own active / public / deliverable filters and price conversion — so a new product or price appears in the plugin with no release. `owned` lists the account's held purchases of them. Spends nothing.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"parameters":[{"name":"currency","in":"query","required":false,"schema":{"type":"string","pattern":"^[A-Za-z]{3}$"},"description":"Show prices in this currency (the storefront's conversion; USD when it has no rate)."}],"responses":{"200":{"description":"The products and holdings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoV2Catalogue"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/seo-connection/products":{"get":{"operationId":"listSeoProducts","summary":"The site's credit tools and what one unit of each costs.","description":"Every tool a connected site can run from Zinn® credits — local rank grid, reviews, Google Shopping and Amazon shelves, YouTube rankings, competitor traffic, results-page snapshots, brand sentiment, technology lookup, \"People also ask\" questions and content briefs — with the unit each is billed in and that unit's price, read from the price rows (V1's own prices). Spends nothing.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"responses":{"200":{"description":"The tools.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoProductCatalogue"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/seo-connection/products/{product}/quote":{"parameters":[{"$ref":"#/components/parameters/SeoProductCode"}],"post":{"operationId":"quoteSeoProduct","summary":"What one run would cost, before it is asked for. Spends nothing.","description":"Validates the parameters exactly as `runSeoProduct` will and answers the units, the unit price, the total and the current balance — the price the screen shows before the person presses Run.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoProductInput"}}}},"responses":{"200":{"description":"The quote.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoProductQuote"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/seo-connection/originality/quote":{"get":{"operationId":"quoteSeoOriginalityCheck","summary":"What an originality check of this many sentences would cost. Free.","description":"The price of one sentence (the unit `originality_phrase`, read from its price row) times the sentences asked for, before anything is spent (stage X1C, zs-722).","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"parameters":[{"name":"units","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":10}}],"responses":{"200":{"description":"The price.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoOriginalityQuote"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/seo-connection/originality":{"post":{"operationId":"startSeoOriginalityCheck","summary":"Search the web for a draft's sentences word for word. Spends credits.","description":"Needs the `seo.spend` scope. Up to 20 sentences of at least 8 words (only these leave the site, never the whole draft) are each searched as an exact quotation, in the background; read the answer with `getSeoOriginalityCheck`. Every sentence is debited up front (under the site's own spend, so its monthly limit counts it) and every sentence the search did not answer is refunded. A check that could not be started is refunded in full (`503`).\n\nRefused before anything is spent: no usable sentence or too many (`422`), not enough credit, the site's monthly limit or an account not in good standing (`403`).","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoOriginalityInput"}}}},"responses":{"202":{"description":"Debited and started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoContentRun"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/seo-connection/originality/{runId}":{"parameters":[{"name":"runId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"get":{"operationId":"getSeoOriginalityCheck","summary":"One originality check, and where each sentence was found.","description":"`result.phrases` lists each sentence with the pages of OTHER sites that hold it (the site's own pages are counted apart), `answered` is false for a sentence the search did not answer (it was refunded), and `original_percent` is the share of answered sentences found nowhere else. Reading costs nothing.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"responses":{"200":{"description":"The check.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoContentRun"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/seo-connection/images":{"post":{"operationId":"startSeoImage","summary":"Draw one image from a description on Zinn® credits. Spends credits.","description":"Needs the `seo.spend` scope (stage X1C, zs-720). The image is drawn in the background by the cheapest image model Zinn® has measured and is metered on the one meter only when it arrived; read it with `getSeoImage`. Refused before anything is spent: no description (`422`), not enough credit for one image, the site's monthly limit or an account not in good standing (`403`). A run that could not be started costs nothing (`503`).","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoImageInput"}}}},"responses":{"202":{"description":"Started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoContentRun"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/seo-connection/images/{runId}":{"parameters":[{"name":"runId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"get":{"operationId":"getSeoImage","summary":"One image run; when complete, the picture itself.","description":"A complete run carries `images` — the picture as base64 with its type — for the plugin to save to the site's media library. A failed run says why in `error` and charged nothing. Reading costs nothing.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"responses":{"200":{"description":"The run.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoContentRun"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/seo-connection/products/{product}/runs":{"parameters":[{"$ref":"#/components/parameters/SeoProductCode"}],"post":{"operationId":"runSeoProduct","summary":"Run one credit tool now. Spends credits.","description":"Needs the `seo.spend` scope. Every unit is debited up front (units x the unit price, under the site's own spend so its monthly limit counts it) and the run happens in the background: read it with `getSeoProductRun`. Every unit the data supplier did not answer is refunded — the site pays only for answers. A run that could not be started is refunded in full before the answer (`503`).\n\nRefused before anything is spent: unusable parameters (`422`, a refusal naming the field), not enough credit, the site's monthly limit or an account not in good standing (`403`).","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoProductInput"}}}},"responses":{"202":{"description":"Debited and started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoProductRun"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/seo-connection/products/runs":{"get":{"operationId":"listSeoProductRuns","summary":"This site's recent credit-tool runs, newest first.","description":"Up to 50 runs of this site, optionally of one tool or one scheduled tool, each with its answer, alerts and money line. Reading costs nothing.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"parameters":[{"name":"product","in":"query","required":false,"schema":{"$ref":"#/components/schemas/SeoProductCode"}},{"name":"watch","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Uuid"},"description":"Only the runs one scheduled tool made."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"The runs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoProductRunList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/seo-connection/products/runs/{runId}":{"parameters":[{"name":"runId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"get":{"operationId":"getSeoProductRun","summary":"One credit-tool run, with its answer, its alerts and what it cost.","description":"`queued` while the background run is going; then `complete`, `partial` (some units refunded) or `failed` (refunded in full). Reading costs nothing.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"responses":{"200":{"description":"The run.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoProductRun"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/seo-connection/products/runs/{runId}/screenshot":{"parameters":[{"name":"runId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}},{"name":"phrase","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0},"description":"Which phrase of a snapshot run (its index in `result.phrases`)."}],"get":{"operationId":"getSeoProductScreenshot","summary":"The picture of a results page a snapshot run took (PNG).","description":"Served through Zinn®, never linked: the site keeps its own copy. `404` once the picture is no longer available — take a new snapshot.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"responses":{"200":{"description":"The picture.","content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/seo-connection/products/places":{"post":{"operationId":"findSeoProductPlaces","summary":"Find a business on Google Maps, to pick \"this is my business\". Free to the site.","description":"Candidates only — a shared trading name must be confirmed by the person. Used by the local rank grid (its centre and its Google id) and by Google reviews (its place id). Limited per site as a runaway guard.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoProductPlacesInput"}}}},"responses":{"200":{"description":"The candidates.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoProductPlaces"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/seo-connection/products/watches":{"get":{"operationId":"listSeoProductWatches","summary":"The credit tools this site runs on a schedule, with each one's cost.","description":"Each scheduled tool with its next run, whether it is paused for want of credit (`held_since`), what one run costs and about what a month costs.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"responses":{"200":{"description":"The schedule.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoProductWatchList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createSeoProductWatch","summary":"Put a credit tool on a schedule. Spends credits on each run.","description":"Needs `seo.spend`. The first run is taken by the next hourly sweep (it is the baseline the alerts compare with), then one every `cadence_days`. Each run is paid like `runSeoProduct`; when the balance cannot pay, the tool is PAUSED (nothing spent, nothing dropped, one notice) and carries on by itself after a top-up.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoProductWatchInput"}}}},"responses":{"201":{"description":"Scheduled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoProductWatch"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/seo-connection/products/watches/{watchId}":{"parameters":[{"name":"watchId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"patch":{"operationId":"updateSeoProductWatch","summary":"Change, pause or restart a scheduled credit tool.","description":"Changing the parameters or switching it back on needs `seo.spend`; switching it on makes it due at the next hourly sweep.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoProductWatchPatch"}}}},"responses":{"200":{"description":"Changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoProductWatch"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"deleteSeoProductWatch","summary":"Take a credit tool off the schedule. Its past runs are kept.","description":"Nothing further is run or charged for it.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/seo-connection/offers":{"get":{"operationId":"listSeoOffers","summary":"What Zinn® sells inside the plugin, each product priced from its live row.","description":"Every offer the plugin can show beside a finding (stage C3, zs-601 … zs-616): link placements, articles, domains, Wayback restore hosting, domain vetting, reputation monitoring, local citations, uptime monitoring, hosting and migration, the footprint check, security clean-up and backups, the indexing boost, expert services (the audit, monthly SEO and the done-for-you move from another SEO plugin, `experts` → `migration`, Q348), the referral programme and the SEO tool bundle. Each product carries the price read from its catalogue row now; a product whose row is missing, switched off or cannot be fulfilled comes back `available: false` with no price, and an offer with no available product is not shown. Spends nothing.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"responses":{"200":{"description":"The offers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoOfferCatalogue"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/seo-connection/offers/orders":{"get":{"operationId":"listSeoOfferOrders","summary":"The orders this site placed, with where each one is now.","description":"Newest first, at most 50. The status is read from the basket the order opened, the order the basket became and any marketplace sale behind it — `basket`, `awaiting_payment`, `payment_failed`, `paid`, `brief_needed`, `in_progress`, `delivered`, `done`, `disputed`, `cancelled`, `refunded`, `expired`, or `opened` for an offer that continues on a dashboard page instead of a basket.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"responses":{"200":{"description":"The orders.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoOfferOrderList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"placeSeoOfferOrder","summary":"Open the basket an offer's order needs. Charges nothing.","description":"Needs the `seo.run` scope. Puts the product in a NEW basket for the site's organization, priced by the basket from the live row (the request carries no amount), and answers the dashboard address where the person pays it, signed in, in a new tab. Nothing is charged, captured or authorised here. A marketplace product takes the chosen `package_id` (one of `listSeoOfferListings`); a domain takes the full `domain`; `context` carries the finding, the page, the anchor, a brief and the A/B `variant` the site showed. A service a person delivers (the done-for-you SEO-plugin migration) carries the site and its context to the staff task, and is refused with `refusal.seoOffers.notInGoodStanding` when the account is suspended or closed (§2.46).","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoOfferOrderInput"}}}},"responses":{"201":{"description":"The order, with the address to pay it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoOfferOrder"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/seo-connection/offers/orders/{orderId}/placement":{"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"setSeoOfferPlacement","summary":"Where a bought link went live; watched by link watch from now on.","description":"Needs the `seo.run` scope, and a paid link or citation order. The page must be on another website. The link (page, the order's target address and anchor) joins the site's watched links, checked like every other watched link.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","maxLength":2000}}}}}},"responses":{"200":{"description":"Recorded and watched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoOfferOrder"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/seo-connection/offers/domains/search":{"post":{"operationId":"searchSeoOfferDomains","summary":"Is a domain free, and what does it cost to register for a year?","description":"The dashboard's own availability check and price rows, on a short list of extensions (at most 12 names). Spends nothing.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","maxLength":63}}}}}},"responses":{"200":{"description":"The names.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoOfferDomainResults"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/seo-connection/offers/{offer}/{product}/listings":{"parameters":[{"name":"offer","in":"path","required":true,"schema":{"$ref":"#/components/schemas/SeoOfferKey"}},{"name":"product","in":"path","required":true,"schema":{"type":"string","maxLength":24}},{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":100},"description":"Words the listing's title or summary must contain (a niche, \"DR 50\", a language)."},{"name":"max_price_minor","in":"query","required":false,"schema":{"type":"integer","minimum":0}}],"get":{"operationId":"listSeoOfferListings","summary":"The live marketplace listings a link, article, citation or expert offer sells.","description":"At most 24, cheapest package first, each with up to four packages on sale. Spends nothing.","tags":["seo-connect"],"security":[{"seoSiteConnection":[]}],"responses":{"200":{"description":"The listings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoOfferListings"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/seo-connections":{"get":{"operationId":"listSeoConnections","summary":"The organization's connected Zinn® SEO sites.","description":"Newest first, cursor-paginated. Needs `billing.view` in the organization (`org_id` or `X-Zinn-Org`; omitted, the one org the caller holds it in).","tags":["seo-connect"],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"org_id","in":"query","required":false,"description":"The organization.","schema":{"$ref":"#/components/schemas/Uuid"}},{"name":"status","in":"query","required":false,"description":"Only connections in this state.","schema":{"type":"string","enum":["active","revoked"]}}],"responses":{"200":{"description":"A page of connections.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoSiteConnectionPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/seo-connections/{connectionId}":{"parameters":[{"name":"connectionId","in":"path","required":true,"description":"The connection's id.","schema":{"$ref":"#/components/schemas/Uuid"}}],"patch":{"operationId":"updateOrgSeoConnection","summary":"Change what a connected site may do, and its monthly credit limit.","description":"Needs `billing.payment.manage` in the connection's organization; writes the audit event `seo_connection.updated`. `scopes` narrows (or widens back, never beyond) the four the connection was minted with and must keep `seo.read`: without `seo.spend` the site reads its results and spends nothing; without `seo.run` it changes nothing. A site calling an operation its scopes do not cover gets `403` with `error.code = \"insufficient_scope\"`.\n\n`monthly_spend_cap_micros` is the most Zinn® credit the site's tools may spend per calendar month (USD micros; `null` removes the limit). A run on demand that would pass it is refused `403` before anything is spent; a scheduled run waits for the 1st of next month.","tags":["seo-connect"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoConnectionUpdate"}}}},"responses":{"200":{"description":"The connection as it now is.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoSiteConnection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"revokeOrgSeoConnection","summary":"Disconnect a site from the app.","description":"Needs `billing.payment.manage` in the connection's organization. Idempotent; the first revoke writes an audit event. The site's token is then `401` `connection_revoked`.","tags":["seo-connect"],"responses":{"200":{"description":"The connection, now revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeoSiteConnection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/plugin-support/connections":{"post":{"operationId":"connectPluginSite","summary":"Connect a WordPress site to Zinn® plugin support.","description":"Called server-side by a Zinn® WordPress plugin (Tranzly, Page Builder Sandwich) after the site owner agreed on the plugin's consent screen (WordPress.org Guideline 7). Creates — or reuses — a **support contact** for the e-mail address and returns a scoped, revocable connection token **once**. ADR 0035; contract `docs/plugins-overhaul/x1-x7-contract.md` §2.1.\n\n⛔ **A contact is never an organization.** Nothing here creates an org, a user or a membership; a contact whose address matches a platform user is linked for staff to see and nothing more (owner, D33).\n\n⛔ The engine stores only `sha256(token)`. The token's scopes are `support.tickets` and `support.diagnostics` and nothing else — no scope administers or logs into the site.\n\n**Anonymous**: no session, CSRF-exempt. Budgets: 10/hour per IP (charged before the body is parsed) and 5/hour per e-mail, `429` with `Retry-After`. A filled `website` honeypot answers `202` and stores nothing.","tags":["plugin-support"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginSiteConnectInput"}}}},"responses":{"201":{"description":"Connected. The token is shown only in this response.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginSiteConnected"}}}},"202":{"description":"The honeypot was filled. Nothing was stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginSupportDiscarded"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/plugin-support/connection":{"get":{"operationId":"getPluginSiteConnection","summary":"Read this site's own connection.","description":"The plugin's settings screen reads this to show the connection card. Authenticated by the connection token (`pluginConnectionToken`). A revoked token answers `401` with `error.code = \"connection_revoked\"`, an unknown one `\"invalid_token\"` — the plugin shows the disconnected state with its reason and a reconnect button.","tags":["plugin-support"],"security":[{"pluginConnectionToken":[]}],"responses":{"200":{"description":"The connection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginSiteConnection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"revokePluginSiteConnection","summary":"Disconnect this site (revoke from the site side).","description":"Revokes the connection the token names. Every later call with that token is `401` `connection_revoked` — including a second `DELETE`, so it is idempotent in effect.","tags":["plugin-support"],"security":[{"pluginConnectionToken":[]}],"responses":{"204":{"description":"Revoked."},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/plugin-support/tickets":{"post":{"operationId":"createPluginSupportTicket","summary":"Open a plugin support ticket — from a plugin or a product website's form.","description":"One intake for every plugin support request (X1, ADR 0035). Either a connection token (a connected plugin) or no credential and an `email` (the product websites' forms, `zinndigital.com/support/plugins`, and a plugin that has not connected). The ticket lands in the one Zinn-owned \"Zinn® plugin support\" organization, tagged with its product; staff see it in the ordinary ticket queue.\n\n`diagnostics` is stored ONLY when `consent_diagnostics` is `true`. Each `credentials[].secret` is written to Vault — never to the database, never logged, never returned by a list or read — and purged **30 days after the ticket closes** (owner, D32). Staff read one with `revealPluginSupportCredential`, which is audited.\n\n`licence` is a **claim**. Pro licences no longer buy priority (owner, 2026-11-12): priority is `high` only when the engine has VERIFIED the install and its licence with Freemius AND that licence was live at the 2026-11-12 cut, until the renewal that was due at the cut (a lifetime licence held at the cut keeps it forever). Every other ticket, including an unverifiable claim, files at `normal` and the staff screen says why.\n\nThe contact gets the standard confirmation e-mail in their own language; staff replies reach them by e-mail with the reply in the message, and a reply from their address files onto the ticket as theirs.\n\nCORS is answered on this path for exactly `https://tranzly.io`, `https://www.tranzly.io`, `https://pagebuildersandwich.com`, `https://www.pagebuildersandwich.com` and `https://zinndigital.com`. Budgets: 10/hour per IP, 5/hour per e-mail, 30/day per connection (`429` with `Retry-After`). A filled `website` honeypot answers `202` and stores nothing.","tags":["plugin-support"],"security":[{},{"pluginConnectionToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginSupportTicketInput"}}}},"responses":{"201":{"description":"Filed.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginSupportTicketCreated"}}}},"202":{"description":"The honeypot was filled. Nothing was stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginSupportDiscarded"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"description":"The request carried a login and the secret store would not take it, so NOTHING was filed (`error.code` = `credential_store_unavailable`). Retry, or send it without the login.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/plugin-support/showcase":{"post":{"operationId":"createShowcaseRequest","summary":"Ask for a site to be shown on a product website's showcase page.","description":"The \"Get featured\" form on `pagebuildersandwich.com/showcase/` (owner, 2026-10-05: *\"Yes, opt-in and reviewed\"*). Anonymous, from the visitor's browser. `consent` must be literally `true`: the visitor ticked the box agreeing that the site, its name, the description and a screenshot may be shown publicly.\n\nFiles a `showcase` ticket in the plugin-support inbox (the sender gets the standard confirmation e-mail in their language) and a `pending` entry. The filing (the ticket's language detection and translation take seconds) runs on the platform worker (`ShowcaseIntakeWorkflow`), so the `201` answers at once with the ticket handle the worker files under; when Temporal cannot take it the request files it itself. ⛔ Nothing is public until a member of staff approves it (`adminApproveShowcaseEntry`) and its screenshot has been taken.\n\nSpam controls, the same as the product websites' support form: a fail-closed per-IP budget (5/hour) charged before the body is parsed, the `website` honeypot (`202`, nothing stored), then the per-e-mail ticket budget (5/hour). CORS: the product-website origins listed on `createPluginSupportTicket`.","tags":["plugin-support"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShowcaseRequestInput"}}}},"responses":{"201":{"description":"Filed for review.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShowcaseRequestCreated"}}}},"202":{"description":"The honeypot was filled. Nothing was stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginSupportDiscarded"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/plugin-support/showcase/{product}":{"parameters":[{"name":"product","in":"path","required":true,"description":"The product website asking.","schema":{"$ref":"#/components/schemas/PluginSupportProduct"}}],"get":{"operationId":"listShowcaseEntries","summary":"The sites shown on a product website's showcase page.","description":"Anonymous. ONLY entries a member of staff approved, whose sender consented, and whose screenshot exists — newest approval first. Cached for 60 seconds, and the cache is cleared by every approval, removal and new screenshot, so a removed site disappears at once. Budget: 600/hour per IP, fail-open.","tags":["plugin-support"],"security":[],"responses":{"200":{"description":"The public entries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShowcaseEntryPublicList"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/plugin-support/showcase/{product}/{entryId}/screenshot":{"parameters":[{"name":"product","in":"path","required":true,"description":"The product website.","schema":{"$ref":"#/components/schemas/PluginSupportProduct"}},{"name":"entryId","in":"path","required":true,"description":"The entry's id.","schema":{"$ref":"#/components/schemas/Uuid"}}],"get":{"operationId":"getShowcaseScreenshot","summary":"An approved entry's screenshot (JPEG).","description":"Anonymous. `404` for anything not public (pending, removed, no picture yet). The URL in `ShowcaseEntryPublic.screenshot_url` carries the capture time (`?v=`), so a new picture is a new address and the response is cacheable for an hour.","tags":["plugin-support"],"security":[],"responses":{"200":{"description":"The picture.","content":{"image/jpeg":{"schema":{"type":"string","format":"binary"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/proposals":{"get":{"operationId":"listProposals","summary":"The proposals this organisation has written — draft, sent, accepted and running.","description":"A reseller's or agency's priced offers to its own clients (`docs/720`). Requires `agency.invoicing.view` — a proposal is the front half of an agency invoice, so whoever reads the invoices reads the offers. Newest first, capped at 500.","tags":["proposals"],"parameters":[{"$ref":"#/components/parameters/AgencyInvoicingOrgId"},{"name":"status","in":"query","required":false,"schema":{"$ref":"#/components/schemas/ProposalStatus"}},{"name":"source_request_id","in":"query","required":false,"description":"Only proposals written in answer to this free-quote request.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The proposals.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProposalList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"post":{"operationId":"createProposal","summary":"Draft a proposal. Nothing is sent until `send`.","description":"Requires `agency.invoicing.manage`. The recipient may be ANY e-mail address — they need no account. Every price is integer minor units (§2.8); a decimal is a `422`.","tags":["proposals"],"parameters":[{"$ref":"#/components/parameters/AgencyInvoicingOrgId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProposalInput"}}}},"responses":{"201":{"description":"The draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Proposal"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/proposals/{proposalId}":{"parameters":[{"$ref":"#/components/parameters/ProposalId"},{"$ref":"#/components/parameters/AgencyInvoicingOrgId"}],"get":{"operationId":"getProposal","summary":"One proposal, with its lines, live invoice and full audit trail.","tags":["proposals"],"responses":{"200":{"description":"The proposal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Proposal"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"operationId":"updateProposal","summary":"Edit a proposal before it is accepted.","description":"⛔ Refused (`422`) once accepted — the accepted revision is the agreement. Editing a SENT proposal does not change what the recipient reads until it is sent again, which issues a new revision and replaces their link.","tags":["proposals"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProposalInput"}}}},"responses":{"200":{"description":"The edited proposal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Proposal"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/proposals/{proposalId}/send":{"parameters":[{"$ref":"#/components/parameters/ProposalId"},{"$ref":"#/components/parameters/AgencyInvoicingOrgId"}],"post":{"operationId":"sendProposal","summary":"Issue the current edits as a new revision and e-mail the recipient a fresh link.","description":"The link is returned ONCE as `public_url` and is never readable again (only its digest is stored). The previous link stops working. If the mail provider refuses, nothing is marked sent (`503`).","tags":["proposals"],"responses":{"200":{"description":"The sent proposal, with `public_url`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Proposal"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/proposals/{proposalId}/withdraw":{"parameters":[{"$ref":"#/components/parameters/ProposalId"},{"$ref":"#/components/parameters/AgencyInvoicingOrgId"}],"post":{"operationId":"withdrawProposal","summary":"Take back a proposal that has not been accepted.","tags":["proposals"],"responses":{"200":{"description":"The withdrawn proposal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Proposal"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/proposals/{proposalId}/complete":{"parameters":[{"$ref":"#/components/parameters/ProposalId"},{"$ref":"#/components/parameters/AgencyInvoicingOrgId"}],"post":{"operationId":"completeProposal","summary":"Mark the project finished. The room stays readable.","tags":["proposals"],"responses":{"200":{"description":"The completed proposal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Proposal"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/proposals/{proposalId}/resend-link":{"parameters":[{"$ref":"#/components/parameters/ProposalId"},{"$ref":"#/components/parameters/AgencyInvoicingOrgId"}],"post":{"operationId":"resendProposalLink","summary":"Replace the recipient's link and e-mail the new one.","tags":["proposals"],"responses":{"200":{"description":"The proposal. The old link no longer works.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Proposal"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/public/proposal-labels":{"get":{"operationId":"getPublicProposalLabels","summary":"The proposal page's labels in one language, with no proposal. Unauthenticated.","description":"For the \"this link is not valid\" page, which has no proposal to read labels from. Keyed on the URL's locale, never on a token, so it confirms nothing about any link.","tags":["proposals"],"security":[],"parameters":[{"name":"locale","in":"query","required":false,"schema":{"type":"string","default":"en"}}],"responses":{"200":{"description":"The labels.","content":{"application/json":{"schema":{"type":"object","required":["locale","direction","labels"],"properties":{"locale":{"type":"string"},"direction":{"type":"string","enum":["ltr","rtl"]},"labels":{"type":"object","additionalProperties":{"type":"string"}}}}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/proposals/{token}":{"parameters":[{"$ref":"#/components/parameters/ProposalToken"}],"get":{"operationId":"getPublicProposal","summary":"The recipient's page — the document, its invoice and the project room. Unauthenticated.","description":"⛔ **No authentication.** The token is the whole authorisation and reaches one proposal. Unknown, malformed, replaced and draft links all answer the same `404`. Labels come back in the RECIPIENT's language. Reading a paid proposal whose board is missing creates it.","tags":["proposals"],"security":[],"responses":{"200":{"description":"The proposal as the recipient sees it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicProposal"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/proposals/{token}/accept":{"parameters":[{"$ref":"#/components/parameters/ProposalToken"}],"post":{"operationId":"acceptPublicProposal","summary":"Accept the newest revision. Raises its invoice in the same transaction.","description":"`agree` must be `true` and `name` is the typed acceptance. If the invoice cannot be raised the proposal is NOT accepted (`409`). A zero total raises no invoice and opens the project immediately.","tags":["proposals"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","agree"],"properties":{"name":{"type":"string","minLength":2,"maxLength":200},"agree":{"type":"boolean"}}}}}},"responses":{"200":{"description":"The accepted proposal, with the invoice to pay.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicProposal"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/proposals/{token}/changes":{"parameters":[{"$ref":"#/components/parameters/ProposalToken"}],"post":{"operationId":"requestPublicProposalChanges","summary":"Ask the sender for an amended proposal.","tags":["proposals"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","minLength":3,"maxLength":8000}}}}}},"responses":{"200":{"description":"The proposal, now `changes_requested`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicProposal"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/proposals/{token}/decline":{"parameters":[{"$ref":"#/components/parameters/ProposalToken"}],"post":{"operationId":"declinePublicProposal","summary":"Decline the proposal, optionally saying why.","tags":["proposals"],"security":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":8000}}}}}},"responses":{"200":{"description":"The declined proposal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicProposal"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/proposals/{token}/messages":{"parameters":[{"$ref":"#/components/parameters/ProposalToken"}],"post":{"operationId":"postPublicProposalMessage","summary":"Post a message into the project thread. Visible to both parties.","tags":["proposals"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["body"],"properties":{"body":{"type":"string","minLength":1,"maxLength":8000}}}}}},"responses":{"201":{"description":"The project room, with the message in it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicProposal"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/proposals/{token}/files":{"parameters":[{"$ref":"#/components/parameters/ProposalToken"}],"post":{"operationId":"sharePublicProposalFile","summary":"Share a file into the project. Scanned before anyone can download it.","tags":["proposals"],"security":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"}}}}}},"responses":{"201":{"description":"The project room, with the file listed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicProposal"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/proposals/{token}/files/{attachmentId}":{"parameters":[{"$ref":"#/components/parameters/ProposalToken"},{"name":"attachmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"downloadPublicProposalFile","summary":"Download a shared file — only once its virus scan has passed.","tags":["proposals"],"security":[],"responses":{"200":{"description":"The file.","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/kb":{"get":{"operationId":"listPublicKbArticles","summary":"Browse or search the knowledge base.","description":"**Anonymous** — no credential, no tenant. This is what the marketing site server-renders and what an AI answer engine crawls (§2.18), so it must work with no authentication at all. Published articles only, and that filter lives in every queryset rather than in a serializer so a new field or endpoint cannot leak a draft. `locale` names what the reader wants; the payload's `locale` reports what they actually got, field by field, with English as the floor.","tags":["public"],"security":[],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"locale","in":"query","required":false,"description":"The language to render in. An unknown value falls back to English rather than returning nothing, so a visitor whose browser sends a locale we do not serve reads the English article — and a caller cannot use this to probe which locales exist.","schema":{"type":"string"}},{"name":"category","in":"query","required":false,"description":"Only articles in this category slug.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Free text, minimum two characters.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of published articles.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbArticlePage"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/kb/categories":{"get":{"operationId":"listPublicKbCategories","summary":"List the knowledge-base sections.","description":"Anonymous. ⭐ Only categories that contain something published — an empty section on a public index is a dead end that says \"we have nothing here\" in the place a visitor went looking for help.","tags":["public"],"security":[],"responses":{"200":{"description":"The sections.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbCategoryList"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/kb/slugs":{"get":{"operationId":"listPublicKbSlugs","summary":"Every published article's URL segment, in every locale.","description":"Anonymous. ⛔ Written for the public site's SITEMAP builder, which has to emit 58 localized sitemaps and until 2026-08-22 emitted the English article slug in all of them — so `/de/wissensdatenbank/why-a-listing-hides-…` and `/de/wissensdatenbank/warum-ein-inserat-…` both answered `200`, each claiming to be canonical, at 57 locales × every article. ⛔ ONE request for all locales, never one per locale: a per-locale read gave `/sitemaps/so.xml` an 18.64 s TTFB and made every edge purge a 58-way herd against the engine (#3059, #3111, #3154). ⭐ English is included explicitly in `locales` so a caller never rewrites the fallback.","tags":["public"],"security":[],"responses":{"200":{"description":"One entry per published article.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbSlugMapList"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/kb/entries":{"get":{"operationId":"listPublicKbEntryMap","summary":"Named articles' title and summary, in every locale.","description":"Anonymous. ⛔ Written for the public site's CONTENT MAP builder, the sibling of `/v1/public/kb/slugs`. `/llms.txt` lists every published article by reading this engine live, and took each article's localized title and summary from a committed snapshot refreshed every 3h — so an article published inside that window was advertised to every AI answer engine, in 57 languages, in **English**, while its own page served the translation (§2.38; the public-site sweep calls it `TRANSLATED BUT NOT SERVED`).\n\n⛔ ONE request for all locales, never one per locale — the rule `/v1/public/kb/slugs` records, with the measurement behind it: a per-locale read gave `/sitemaps/so.xml` an 18.64 s TTFB and made every edge purge a 58-way herd against the engine.\n\n⛔ `slugs` is REQUIRED and capped. Unlike the slug map, copy does not stay small: a whole-corpus grid is multiple megabytes in 58 languages and grows with the corpus, so an optional filter whose absence meant \"everything\" would be an unbounded anonymous read one forgotten parameter away. `body` is never served here for the same reason.\n\n⭐ An unknown or unpublished slug is omitted rather than failing the request — the caller is describing a register it read a moment ago, and an article retired in between is an ordinary race, not a reason to take a content map down.","tags":["public"],"security":[],"parameters":[{"name":"slugs","in":"query","required":true,"description":"Comma-separated English article slugs. Duplicates are collapsed before the cap is applied, so repeating a slug cannot spend the budget.","schema":{"type":"string"},"example":"my-site-is-slow,restore-a-backup"}],"responses":{"200":{"description":"One entry per article that is published and was named.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbEntryMapList"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/kb/{slug}":{"parameters":[{"name":"slug","in":"path","required":true,"description":"The article's URL segment. Accepts the English slug, this locale's translated slug, a **retired** slug, and — since 2026-08-24 — **any other locale's** slug. An AI citation carries whatever spelling the citing model saw, and a citation that 404s throws away everything the URL earned, so every spelling resolves. The response's own `slug` is always the REQUESTED locale's current segment, so a caller that arrived on any other form can 301 to it from the difference — which is what the public site does, keeping exactly one `200` URL per article per locale.","schema":{"type":"string"}}],"get":{"operationId":"getPublicKbArticle","summary":"Read one knowledge-base article.","description":"Anonymous. ⛔ A draft is a `404`, the same as a missing slug — distinguishing them would tell an anonymous caller which unpublished articles exist, which is a preview of unannounced work.","tags":["public"],"security":[],"parameters":[{"name":"locale","in":"query","required":false,"description":"The language to render in; unknown values fall back to English.","schema":{"type":"string"}}],"responses":{"200":{"description":"The article.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KbArticle"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/domain-holder/ask":{"get":{"operationId":"askDomainHolder","summary":"May the holder-page edge serve (and obtain a certificate for) this hostname?","description":"The `ask` endpoint of the domain holder-page edge's on-demand TLS (docs/845). Answers `200` only for a domain we hold a DNS zone for, with no site attached and not deleted, at its apex or `www`; `404` for every other hostname. This is what stops the edge requesting certificates for arbitrary names that point at it. Deliberately not a delegation check: a parked domain pointed away and back shows its page again with no action. Unauthenticated and answered from our own rows only.","tags":["public"],"security":[],"parameters":[{"name":"domain","in":"query","required":true,"description":"The hostname the edge is about to serve.","schema":{"type":"string","maxLength":260}}],"responses":{"200":{"description":"The hostname is a parked domain we hold.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["allowed"],"properties":{"allowed":{"type":"boolean","enum":[true]}}}}}},"404":{"description":"Not a hostname the edge may serve.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["allowed"],"properties":{"allowed":{"type":"boolean","enum":[false]}}}}}}}}},"/v1/public/domain-holder/page":{"get":{"operationId":"getDomainHolderPage","summary":"The page a parked domain shows, in the visitor's language.","description":"Served by the holder-page edge for every hostname it admits (docs/845): a tiny, self-contained HTML page saying the domain is registered with Zinn Digital®, with a link to zinndigital.com. Identical for every parked domain — it carries no customer data and echoes nothing the visitor sends. The language is negotiated from `Accept-Language` across every enabled locale (right-to-left languages get `dir=\"rtl\"`); each string falls back to English until its translation is up to date. `noindex`, cached per language.","tags":["public"],"security":[],"parameters":[{"name":"Accept-Language","in":"header","required":false,"schema":{"type":"string","maxLength":500}}],"responses":{"200":{"description":"The holder page.","headers":{"Content-Language":{"description":"The locale the page was rendered in.","schema":{"type":"string"}}},"content":{"text/html":{"schema":{"type":"string"}}}}}}},"/v1/public/domains/search":{"post":{"operationId":"searchPublicDomains","summary":"Search domain availability without an account.","description":"The guest half of `searchDomains`. Applies the **same selling rules** as the authenticated endpoint — a name is only tokenised when it is available, in a TLD we offer, registrable as a bare `SLD.TLD`, and priced (a premium name is priced from the registrar's live quote plus margin) — but checks at most **5** candidate extensions per request rather than 64, because every miss is a call to a paid registrar API made on behalf of an anonymous visitor. That limit bounds what the **caller asks for**; a bare name with no `tlds` expands to the curated default set (see `PublicDomainSearchRequest.tlds`) and is always inside it. Prices are returned in the currency requested by `X-Zinn-Currency` where one is available. The `token` on an available result is what `addPublicCartItem` requires. A `query` that cannot be a domain name is `422` (`refusal.domains.domainName`), exactly as on `searchDomains`.","tags":["public"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicDomainSearchRequest"}}}},"responses":{"200":{"description":"The candidate results.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainSearchResults"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/domains/suggest":{"post":{"operationId":"suggestDomains","summary":"Alternative domains worth offering alongside a search.","description":"The upsell grid (docs/31 §5.3). Ranked in tiers — **brand protection** (you are buying `acme.com`; somebody else buying `acme.net` can pass for you), then the **regional** extension for the visitor's country, then **same-intent** alternatives, then popular filler — and each row says which tier it came from, so a surface can make the argument rather than just list names.\n\nEvery suggestion is priced and tokenised by **exactly the same code path as `searchPublicDomains`**: a grid price that came from anywhere else is a price the basket then refuses, at the moment the customer has already decided to buy.\n\nIts own endpoint rather than a field on the search response, because each suggestion is a paid registrar availability call: the primary result must not wait for the upsell, and the upsell must be skippable. It shares the search abuse budget — the two together are what one visitor's session costs us at the registrar. The visitor's country comes from Cloudflare's `CF-IPCountry`, an edge-set header the browser never sends, so no CORS allow-list entry is involved.","tags":["public"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainSuggestRequest"}}}},"responses":{"200":{"description":"The ranked suggestions, priced and tokenised. May be empty.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainSearchResults"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/cart":{"post":{"operationId":"createPublicCart","summary":"Open an anonymous cart.","description":"Creates an empty cart with **no organization and no user** and returns its opaque bearer `token`. The token is returned **only here** — nothing can re-derive it from the cart afterwards, so a client that loses it has lost the cart. It is a credential: treat it like one. The cart expires at `expires_at` (24 hours).\n**Cross-origin callers.** Besides zinndigital.com, this route answers the browsers of the hosting sites' on-page free trial — zinnhosting.com, zinnhosting.co.uk and the zinndigital country sites (`engine.api.trial_cors`, list generated from the product-sites registry into `engine/engine/api/trial_origins.json`). Exact origins only, never credentials; the route's own budgets, Turnstile and trial guard apply unchanged (docs/749 §16).","tags":["public"],"security":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCartCreate"}}}},"responses":{"201":{"description":"The new, empty cart, including its `token`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCart"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/cart/{token}":{"parameters":[{"$ref":"#/components/parameters/PublicCartToken"}],"get":{"operationId":"getPublicCart","summary":"Get an anonymous cart.","description":"Returns the cart with every item re-priced from the live catalog and its pre-tax totals. Tax is not computed here — it depends on the billing country, which a guest cart does not have until checkout. A token that is unknown, malformed, expired or already checked out all return the same `404`.","tags":["public"],"security":[],"responses":{"200":{"description":"The cart.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCart"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/cart/{token}/items":{"parameters":[{"$ref":"#/components/parameters/PublicCartToken"}],"post":{"operationId":"addPublicCartItem","summary":"Add a domain to an anonymous cart.","description":"Adds one `domain_register` item and returns the updated cart. `availability_token` is the `token` from a search result for **this exact name** and is required: it is what proves the item came out of a real, rate-limited search rather than being invented, so a name that search would not sell cannot be added here either. A stale, forged or now-taken name is a `409`. A cart holds at most 20 items, and one name may appear only once. The price is computed by the server; anything sent by the client is ignored.","tags":["public"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCartItemCreate"}}}},"responses":{"201":{"description":"The updated cart, including the new item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCart"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The name is not available, or its availability token was stale or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/cart/{token}/plan":{"parameters":[{"$ref":"#/components/parameters/PublicCartToken"}],"post":{"operationId":"addPublicCartPlan","summary":"Add a hosting plan, or a free trial of one, to an anonymous cart.","description":"Owner ruling D-W15-2: hosting, free trials and domains go through ONE public checkout, so a visitor never has to sign up in the app before they can buy. The price is computed by the server from the pinned plan VERSION in the cart's own currency; anything sent by the client is ignored. A basket holds one plan at a time, because a subscription governs the org rather than a line. `trial: true` prices the line at **zero** and is refused (`422`) on a plan that does not offer a trial — eligibility is read from the catalogue, never taken on trust.\n**Cross-origin callers.** Besides zinndigital.com, this route answers the browsers of the hosting sites' on-page free trial — zinnhosting.com, zinnhosting.co.uk and the zinndigital country sites (`engine.api.trial_cors`, list generated from the product-sites registry into `engine/engine/api/trial_origins.json`). Exact origins only, never credentials; the route's own budgets, Turnstile and trial guard apply unchanged (docs/749 §16).","tags":["public"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCartPlanCreate"}}}},"responses":{"201":{"description":"The updated cart, including the new plan line.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCart"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/order/config/{planCode}":{"parameters":[{"name":"planCode","in":"path","required":true,"description":"The catalogue `code` of the plan being configured.","schema":{"type":"string","maxLength":64}}],"get":{"operationId":"getOrderConfig","summary":"Everything a signed-in customer configures for one plan.","description":"The in-app twin of `getPublicOrderConfig`, and it reads the **same** function: two computations of \"what can I configure on this plan\" is how the public funnel and the console come to disagree about whether a plan includes a free domain.\n\nThe one real difference is why this route exists: it includes the product lines the owner ruled sellable **only inside the app** (email for an external domain, 2026-08-16), which are absent from every anonymous surface. It is a separate authenticated route rather than a query parameter, because a parameter an anonymous caller can set is not a visibility control.\n\nAuthenticated but not tenant-scoped: the answer is a statement about what the platform sells, not about the caller's estate. Requires `billing.view`.","tags":["commerce"],"responses":{"200":{"description":"The plan's configurable options, priced in the caller's currency.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderConfig"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/public/cart/{token}/extra":{"parameters":[{"$ref":"#/components/parameters/PublicCartToken"}],"post":{"operationId":"addPublicCartExtra","summary":"Add one purchasable service (an addon) to an anonymous cart.","description":"Owner ruling 2026-09-09: the order configuration page upsells addons *\"suitable for the hosting type\"*, and its running total has to match what checkout charges to the minor unit. That second half is what makes an addon a basket LINE rather than a second purchase path — a total including something the basket cannot hold would be a second place that adds money up.\n\nThe price is computed by the server from the catalogue in the cart's own currency; anything sent by the client is ignored. Which addons this basket may buy is read from **its own plan line**, never from the request: this endpoint is anonymous, so a caller-supplied product line would put every PBN-only addon one request away from any basket. A basket with no plan in it can buy only the addons sold on every line.\n\n`422` covers all three refusals — withdrawn (no fulfilment handler is registered, so we could take the money and run nothing), not sold on this product line, or already in the basket. One of each service per basket.","tags":["public"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCartExtraCreate"}}}},"responses":{"201":{"description":"The updated cart, including the new service line.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCart"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/order/config/{planCode}":{"parameters":[{"name":"planCode","in":"path","required":true,"description":"The catalogue `code` of the plan being configured (`pbn_5`, …).","schema":{"type":"string","maxLength":64}}],"get":{"operationId":"getPublicOrderConfig","summary":"Everything a buyer configures for one plan, in one call.","description":"Owner ruling 2026-09-09, on a competitor's order flow: *\"when you buy something it has a clear config page for that hosting where all the options reside nice and neatly including the domain and things … we should have these config pages in full too inside our app, so you select the hosting type then they config for it both public and in the app\"*.\n\n**One call by design, not as an optimisation.** A configuration page assembled from five endpoints renders in five stages, and the two that matter most — the free-domain allowance and the eligible addons — would arrive last, after the visitor has already decided.\n\nEverything here is derived from live rows: the terms and their saving are the plan's own two prices subtracted, `default_interval` is the cheapest per month rather than a literal, the free-domain allowance and its TLDs are the `included_domains` entitlement, the regions come from the activated data centres for this product line (empty on Footprint-Free by owner ruling), and the addons are the extras `Extra.is_eligible_for` admits on this line.\n\nA choice the platform cannot **apply** is deliberately absent. There is no PHP-version option: measured on the live catalogue, no plan carries a PHP entitlement — PHP is chosen per site after provisioning — so a picker here would be a control that changes nothing.\n\nLines the owner ruled sellable only inside the app are **not** served here; the signed-in console reads the same shape from `getOrderConfig`.","tags":["public"],"security":[],"parameters":[{"name":"currency","in":"query","required":false,"description":"ISO-4217 code to price this response in — the same assertion `X-Zinn-Currency` makes, in a form a caller that cannot send custom headers can use. The public funnel is exactly that caller: its transport forbids them outright, because `X-Zinn-Currency` once shipped on an SPA without its engine CORS entry and took production down with every deploy green. An unknown or unoffered code falls back silently rather than raising — a bad value must never break a pricing page.","schema":{"type":"string","minLength":3,"maxLength":3}},{"name":"locale","in":"query","required":false,"description":"The interface language the page renders in (`de`, `pt-BR`, …). The add-ons' names and descriptions come back in it, the seeded English where a string has no translation yet. Missing or unsupported keeps the English. Never read from `Accept-Language`: the value comes from the page the copy sits in (1108#14).","schema":{"type":"string","maxLength":35}}],"responses":{"200":{"description":"The plan's configurable options, priced in the caller's display currency (`?currency=`, then `X-Zinn-Currency`, then the visitor's country, then USD). A currency with no derived price row yet falls back to USD and says so in `currency` — an honest USD figure beats a converted-looking number under the wrong code, and an empty term list would render a configuration page with no price at all, which reads as \"free\".","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderConfig"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/order/finder":{"get":{"operationId":"getPublicHostingFinderOptions","summary":"The questions the hosting finder may ask, enumerated from the estate.","description":"The form's own options come from here rather than from the component, and that is the whole reason this endpoint exists: a hardcoded CMS list survives the day we stop offering that CMS, and the failure is silent in the worst direction — a visitor answers a question we cannot honour and is recommended a plan that cannot run their site. `cms` is the union of what our own fleet can install and what any active line's application policy allows, plus `static` and `none`, which are about the absence of a CMS and so cannot come from an installer inventory.","tags":["public"],"security":[],"responses":{"200":{"description":"The answerable options, per question.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/HostingFinderOptions"}}}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/order/recommend":{"post":{"operationId":"recommendHosting","summary":"Recommend hosting from the guided form's answers, with the reasoning.","description":"Owner, 2026-09-09: *\"maybe we also need some smart hosting finder, where they can complete a form type thing to choose what they need like cms, if for pbn, and some other questions and then we recommend them the hosting they need with options on it etc\"*.\n\n**Computed from entitlements, never from a mapping.** A hardcoded `{\"wordpress\": \"some_plan\"}` table is right on the day it is written and wrong the first time a plan is renamed, repriced or retired — and it fails silently, recommending a plan the visitor then cannot buy. Every rule reads a number off the plan they would actually receive.\n\nA plan that cannot meet a **stated hard requirement** — fewer sites than asked for, no SSH when SSH was asked for, no footprint promise when the answer was PBN — is dropped rather than ranked lower. So is a plan of the wrong KIND for the answer: a plan built for one application never answers another, a WordPress-only plan (Zinn® Managed WordPress) answers only a WordPress or WooCommerce answer, and a database plan is never hosting for a site. Everything else that does not fit comes back as a `caveat` on a plan that is still offered: a finder that returns nothing because every plan is a pound over budget has answered nobody's question.\n\n`reasons` and `caveats` are **machine codes**, never sentences: we serve 58 languages and every surface renders its own copy, so an English string minted here would reach an Arabic page inside an RTL document.\n\nA POST that writes nothing. It is a POST because the answers are a structured body, and because a visitor's traffic, budget and site count do not belong in a URL that proxies, logs and `Referer` headers all carry.","tags":["public"],"security":[],"parameters":[{"name":"currency","in":"query","required":false,"description":"ISO-4217 code to price this response in, and the currency `budget_max_minor` is read in. Same contract as on `getPublicOrderConfig`.","schema":{"type":"string","minLength":3,"maxLength":3}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HostingFinderRequest"}}}},"responses":{"200":{"description":"The recommended plans, best match first. Priced in the caller's display currency (`X-Zinn-Currency`), and `budget_max_minor` is read in that same currency's minor units.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/HostingRecommendation"}}}}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/cart/{token}/server":{"parameters":[{"$ref":"#/components/parameters/PublicCartToken"}],"post":{"operationId":"addPublicCartServer","summary":"Add one cloud machine to an anonymous cart.","description":"The anonymous half of `POST /v1/carts/{cartId}/lines` with `kind=compute_server` (#1741). Before it existed a machine could not be bought without an account at all, so `/hosting/cloud` — ten published, priced Zinn® Cloud tiers — sent every visitor to `/auth/register` first.\n\nThe price is computed by the server from the catalogue in the cart's own currency; anything sent by the client is ignored. Everything answerable **without an org** is answered now: the size is one we sell, it is a compute size, it has a vendor spec token, the cadence has a price, the machine's name is free within this basket. A refusal here is a `422` the visitor can act on while they are still looking at the configurator.\n\n⛔ A machine on an account we hold (every size on sale today) or one priced per data centre answers `422` here: its data centre, operating system and SSH key cannot be carried by this basket, so the public site sends the visitor to register and on to the signed-in builder. The basket logic stands for a resold size only.\n\nEverything that **needs** an org — the provider, the data centre and the vendor account's funding — is validated at `createPublicCheckout` instead, which is the first instant an org exists and is still **before any card is taken**. So a vendor refusal arrives as a sentence, never as a charge with no machine behind it.\n\nThere is deliberately no `zone`, `provider`, `disk` or `bandwidth` field: each is answered by an org-scoped live vendor read the anonymous funnel cannot make, and a guessed value is one only the vendor would disagree with, after the charge.","tags":["public"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCartServerCreate"}}}},"responses":{"201":{"description":"The updated cart, including the new server line.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCart"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/cart/{token}/marketplace":{"parameters":[{"$ref":"#/components/parameters/PublicCartToken"}],"post":{"operationId":"addPublicCartMarketplacePackage","summary":"Add one marketplace package to an anonymous cart.","description":"Guest checkout for the marketplace (s1014 J08, owner 2026-10-14: no account and no card needed before buying; the account is created at checkout). The anonymous half of `POST /v1/carts/{cartId}/lines` with `kind=marketplace_package`.\n\nOnly `listing_package_id` is read. The price, currency and listing come from the package on a **live** listing; the basket must be in the package's currency (the marketplace is USD-native, docs/82 §2), and one package may appear once. A package that is off sale, a test listing, or a currency mismatch is a `422` the visitor can act on. At checkout the line is re-validated with the buyer's new org, which is also where a seller buying their own listing is refused.","tags":["public"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCartMarketplaceCreate"}}}},"responses":{"201":{"description":"The updated cart, including the new marketplace line.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCart"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/cart/{token}/items/{itemId}":{"parameters":[{"$ref":"#/components/parameters/PublicCartToken"},{"$ref":"#/components/parameters/PublicCartItemId"}],"patch":{"operationId":"updatePublicCartItem","summary":"Change a line in an anonymous cart — a plan's data centre or a domain's term.","description":"⚖️ s1014 R37 (owner, 2026-10-18): the data centre is chosen on the buy button AND on the checkout page. `region` is a public city slug (or a placement code), checked against the plan's OWN product line exactly as `addPublicCartPlan` checks it; `\"\"` clears the choice (\"choose for me\"). Returns the updated cart. A line that is not a hosting plan, or an item id from another cart, is `404`; a city that line cannot use today is `422` and the stored choice is left as it was.","tags":["public"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCartItemUpdate"}}}},"responses":{"200":{"description":"The updated cart.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCart"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"removePublicCartItem","summary":"Remove an item from an anonymous cart.","description":"An item id from another cart is a `404`, never a cross-cart delete.","tags":["public"],"security":[],"responses":{"204":{"description":"Removed."},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/promo-codes/quote":{"post":{"operationId":"publicQuotePromoCode","summary":"Preview what a discount code takes off a guest basket.","description":"The guest checkout's coupon preview (docs/1311). Unauthenticated and budgeted per visitor (a few dozen checks an hour, fail-closed). A DISPLAY only: the code is re-checked by `publicCheckout` before any account exists and the placed order is priced from the cart. Once-per-customer is judged at placement, against the new organization.","tags":["public"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CouponQuoteRequest"}}}},"responses":{"200":{"description":"The preview.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CouponQuote"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/checkout":{"post":{"operationId":"publicCheckout","summary":"Check out as a guest — create the account and place the order.","description":"Converts an anonymous cart into a real tenant: it **creates the organization and the user at this point**, captures the billing details, and places an immutable order. Availability is **re-verified live** against the registrar first, so a name taken while the customer was typing aborts the whole call (`409`) with nothing created. Tax is computed against `billing.country` (§2.8).\n\n**It never takes a card, and what it does next depends entirely on the total.** The response is `{order_id, org_id, next}` plus the order's own `currency`, `subtotal_minor`, `tax_minor` and `total_minor`:\n\n- `\"payment\"` — the order has something to pay and is left `pending_payment`.\n  Taking payment is the authenticated step that follows, because a brand-new\n  organization has no payment mandate on file.\n\n- `\"done\"` — the total is **zero** (a free trial, a zero-priced plan, a 100%\n  discount), so the order is **settled and provisioned inside this call**: a zero\n  `Payment` is recorded, the order becomes `paid`, and the fulfilment workflow\n  starts. No gateway is contacted — a brand-new organization has none to resolve,\n  and there is nothing to charge. Owner ruling 2026-08-09: *a free trial takes no\n  card and starts immediately.*\n\n\n⛔ Between that ruling and 2026-08-12 this endpoint answered `\"done\"` and performed **none** of it — the order stayed `pending_payment` with no payment, no fulfilment and no workflow, so the customer was told their trial had started and no site was ever built. Anything that keys off `next` should key off it alone; the order state now follows it.\n\n**Idempotent on the cart.** A double-submit — concurrent or an hour later — produces one organization, one user and one order; the repeat returns the same ids. There is no `Idempotency-Key` header to send: the cart token *is* the key.\n\nIf the email already has an account the call is refused with `409` and nothing is created: the purchase must be completed signed in, so that an unauthenticated request can never attach an order to somebody else's tenant. The cart stays open.\n**Cross-origin callers.** Besides zinndigital.com, this route answers the browsers of the hosting sites' on-page free trial — zinnhosting.com, zinnhosting.co.uk and the zinndigital country sites (`engine.api.trial_cors`, list generated from the product-sites registry into `engine/engine/api/trial_origins.json`). Exact origins only, never credentials; the route's own budgets, Turnstile and trial guard apply unchanged (docs/749 §16).","tags":["public"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCheckoutRequest"}}}},"responses":{"201":{"description":"The created tenant and the placed order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCheckoutResult"}}}},"404":{"$ref":"#/components/responses/NotFound"},"403":{"description":"The buyer's e-mail address is refused (`SIGNUP_EMAIL_REFUSED`, docs/1174): a disposable, invalid or spam-trap address. Nothing was created and the basket stays. For a likely typo in the domain, `details[0]` is `{field: email, code: EMAIL_POSSIBLE_TYPO, suggestion}`: `suggestion` is the same address on the domain the validator suggested (\"ann@gmail.com\" for \"ann@gamil.com\"), which the page offers as a one-click fix before the buyer submits again (EMAILTYPO).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The email already has an account (sign in to complete the purchase), or a domain in the cart is no longer available. Nothing was created either way.\n\nThe two are told apart by `error.code`, and a client MUST branch on it rather than on the status: the remedies are opposite. `ACCOUNT_EXISTS` means sign in and the basket follows you; the generic `CONFLICT` means a name went while it sat in the basket and the customer must search again. Until W42-N both returned `CONFLICT`, and the public funnel showed every returning customer the \"your domain was taken\" copy on the last click of a purchase.\n\nOr (`error.details[0].code` `COUPON_WITHDRAWN`, `field: promo_code`, docs/1311) a replayed checkout resumed an order whose coupon claim had lapsed and could not be re-taken: the code was removed and the order repriced to the full total before any gateway call, so nothing was charged. The keyed message (`refusal.commerce.couponWithdrawn`) states the new total; the public checkout shows its own localized sentence and re-quotes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body failed validation, or (`error.code` `REGISTRY_DATA_REQUIRED`, Q10) a domain's registry demands fields `registry_data` did not carry — checked before any account exists — or (`error.code` `REGISTRANT_REQUIRED`) the basket holds a domain and no `registrant` was sent. The registrant refusal happens before any account, organization or order exists, so the visitor adds the owner and submits again with nothing to unwind. Or (`error.code` `REFUND_TERMS_REQUIRED`) `accept_refund_terms` was not `true`: the visitor ticks \"refunds are issued as Zinn® credit\" and submits again; nothing was created. Or (`details[0].code` `TOTAL_CHANGED`) the total the order will be placed or RESUMED at is not `expected_total_minor`: nothing is placed or charged, and `details[0].fresh_total_minor` carries that total, which the page shows and sends back as `expected_total_minor` on the next press (docs/1311). Or (`details[0].code` `EMAIL_MAILBOX_FULL`, `field: email`, MAILQUOTA) the address is a real mailbox whose inbox is full: `details[0].provider` names the provider (\"Gmail\") or is empty. It is NOT a refusal of the sale and nothing was created; the page keeps the basket and the form, and the buyer either changes the address or sends the same request again with `email_warning_accepted: true` (\"Continue anyway\").","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"description":"Account provisioning is unavailable, so no account could be created. Refused deliberately rather than creating an account that could never be signed into.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/public/domains/tld-requirements":{"get":{"operationId":"getTldRequirements","summary":"What each extension's registry demands before it will register a name.","description":"Q10. For each named extension: whether it can be ordered online, which registrant countries and entity types the registry accepts, and every extra field it demands (`registry_data` on checkout and on a partner order) — identity, tax, company or VAT numbers on the owner, extension data such as the `.us` nexus, domain fields such as the `.ca` legal type, and registry acceptances. Read from the registrar's own per-extension API specification and documentation, with the source and its date on every row. No account, no registrar call; cacheable for an hour.","tags":["public","domains"],"security":[],"parameters":[{"name":"tlds","in":"query","required":true,"description":"Comma-separated extensions without the dot (`es,it,com.au`), at most 50.","schema":{"type":"string","maxLength":1000}},{"name":"op","in":"query","required":false,"schema":{"type":"string","enum":["register","transfer"],"default":"register"}},{"name":"currency","in":"query","required":false,"description":"ISO 4217 code the `local_presence_addon.per_year` price is quoted in; USD when absent or malformed.","schema":{"type":"string","minLength":3,"maxLength":3,"default":"USD"}}],"responses":{"200":{"description":"One row per named extension, in the order named.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TldRequirementsResponse"}}}},"422":{"description":"No extension named, more than 50, or an unknown `op`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/domains/tld-pricing":{"get":{"operationId":"listPublicTldPricing","summary":"The public, searchable TLD price table.","description":"The crawlable price surface `docs/31` §5.1 specifies and nothing served: what every extension we sell costs to **register, renew and transfer**, plus the registry policy a buyer needs (min/max years, WHOIS privacy, IDN, restore, whether a transfer grants a year, and any residency restriction). No account, no cart, no registrar call — a cached read of platform-global reference data.\n\n**Cursor-paged and searched server-side**, which is now the only public shape: the older `listTldPricing` (`GET /v1/domains/pricing`) returned the whole catalogue in one uncursored body and was **retired in wave 8** (issue #845). That was fine at fifteen TLDs and was issue #466 all over again at the ~1,500 the registrar sync imports — on an unauthenticated endpoint, which is the worst place to have one. `q` is a substring match on the label and tolerates a leading dot (`.shop` and `shop` find the same row). Ordered **most popular first** by default, because a visitor who has decided nothing wants `.com` before `.zuerich`; `order=tld` gives the alphabetical reference view. Inactive offers are never returned.\n\n`summary` appears on the **first page only** and carries `active` — how many extensions we sell, *counted*. Any surface stating \"search across N extensions\" must read it: a hardcoded number is a public claim that goes stale the first time the sync deactivates a registry. `matched` is the same count under the current filter, so a page can say both without either being wrong.\n\n`related` appears when `q` names an extension we actually sell, and carries the neighbours worth offering beside it — `.shop` returns `.store` and `.online` with their real prices — each row stamped with `related_kind` so the surface can make the *argument* rather than list names. Ranked by the same code as the domain-search upsell grid, and unlike that grid it costs **no registrar call**: a price table is a browse, not an availability check.\n\nPrices are USD, the catalogue's authored currency (`docs/29`); a public surface converts for display. Cacheable — strong `ETag` + `Cache-Control: public, max-age=60`.","tags":["public","domains"],"security":[],"parameters":[{"name":"q","in":"query","required":false,"description":"Substring match on the TLD label. A leading dot is ignored.","schema":{"type":"string","maxLength":63}},{"name":"category","in":"query","required":false,"description":"Restrict to one registry family.","schema":{"type":"string","enum":["gtld","new_gtld","cctld","sponsored"]}},{"name":"order","in":"query","required":false,"description":"`popularity` (default) ranks the extensions a visitor is most likely to want first; `tld` is the alphabetical reference order.","schema":{"type":"string","enum":["popularity","tld"],"default":"popularity"}},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"If-None-Match","in":"header","required":false,"description":"A previously returned `ETag`; a match responds `304`.","schema":{"type":"string","maxLength":256}}],"responses":{"200":{"description":"A page of the public price table.","headers":{"ETag":{"description":"Strong validator over the response body.","schema":{"type":"string"}},"Cache-Control":{"description":"Always `public, max-age=60`.","schema":{"type":"string"}},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicTldPricingPage"}}}},"304":{"description":"Unchanged since the supplied `If-None-Match`.","headers":{"ETag":{"description":"The unchanged validator.","schema":{"type":"string"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/security":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteSecurity","summary":"A site's malware state and live findings.","description":"The per-site Tools tab's *Malware and security* card — the scan verdict, when it last completed, and every live finding. RLS-scoped to a site the caller can view (`sites.view`); an out-of-scope or unknown id is a `404`, exactly like `getSite`.\n\n**This reads a stored projection and never calls the scanner.** The card mounts with the Tools tab for every site and polls while a scan is in flight, so a vendor round-trip here would be an un-cached external call in a hot path (CLAUDE.md §2.16). A scan is a durable Temporal workflow (§2.9) that writes the row this returns.\n\n`status: clean` with `last_scan_at: null` means **not scanned yet** — one nullable timestamp rather than a fourth status. \"We could not look\" is deliberately distinguishable from \"we looked and it is fine\", because neither a failed nor an un-attempted scan stamps `last_scan_at`.\n\n⛔ **\"We tried and could not\" and \"we have never tried\" are different facts and arrive in different fields.** `last_scan_error` carries the first (an attempt ran and broke — an unreachable host, a vendor error, a scan abandoned after timing out); `unavailable_reason` carries the second as a machine identifier (nothing is attached to scan this site, or its platform cannot be scanned at all). They are never both non-empty. Render the first as a warning and the second as a neutral notice: showing *\"we couldn't scan this site\"* over a scan that was never attempted tells a customer their site might be infected when nothing of the sort is known.\n\n`detections[].path` is always **relative to the document root** — an absolute path would disclose the host account handle and the fleet's filesystem layout (§2.4).","tags":["hosting"],"responses":{"200":{"description":"The site's malware state.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteSecurity"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/security/scan":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"startSiteSecurityScan","summary":"Scan a site for malware now.","description":"Queues an on-demand scan and answers `202` with the site's state, which will read `scanning` once the workflow starts. Gated on `sites.view`, not on a write key: asking for a fresh scan of your own site changes nothing about it, and it is the first thing a worried customer does.\n\n**Concurrency is bounded by the workflow id, which is per site.** A second request while a scan is running is still a `202` — a scan of this site *is* in progress, which is what was asked for — and no second scan of the same document root starts.\n\n`422` when the site is not running (a suspended or still-provisioning site has no document root to scan). `503` when the durable-execution service is unreachable: answering `202` there would flip the card to *scanning…* for a scan that was never started, and the customer would watch a spinner for hours.","tags":["hosting"],"responses":{"202":{"description":"The scan was queued (or one was already running).","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteSecurity"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"description":"The scanner service is unavailable, so nothing was queued. Refused deliberately rather than reporting a scan that is not running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sites/{siteId}/security/clean":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"startSiteSecurityClean","summary":"Scan and clean a site's malware now.","description":"*Clean now* — the same durable scan as `startSiteSecurityScan`, which then cleans what the scanner can, moves what it cannot out of the document root into the hosting account's `zinn-quarantine` folder (kept, never deleted, restorable) and **always** records a row in `listSiteSecurityHistory`. Works for every site type (static, PHP, WordPress, Node): each step is per file. Files a site cannot open without (`wp-config.php`, `index.php`, `index.html`, `.htaccess`, …) are never moved aside; if one is infected the clean is *failed* and a person decides.\n\nRequires `sites.restart` — it changes files on the site. `202` with the site's state; one per site at a time (a second request joins the running one). `422` when the site cannot be scanned or is not running; `503` when the durable-execution service is unreachable.","tags":["hosting"],"responses":{"202":{"description":"The clean was queued (or a scan of this site was already running).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteSecurity"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"description":"The scanner service is unavailable, so nothing was queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sites/{siteId}/security/history":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"listSiteSecurityHistory","summary":"What the platform cleaned on a site, newest first.","description":"The site's malware clean runs (newest 50): automatic cleans after a scan, *Clean now* runs and restores. An automatic run is recorded only when something new happened (a file cleaned or quarantined, or the first failure), so a site re-scanned daily does not grow a row per scan. `sites.view`; paths are relative to the document root.","tags":["hosting"],"responses":{"200":{"description":"The clean runs.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MalwareCleanRun"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/security/detections/{detectionId}/restore":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"detectionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"restoreSiteSecurityDetection","summary":"Put a cleaned or quarantined file back.","description":"The one-click undo for a false positive: puts the original file back where it was (from `zinn-quarantine`, or the scanner's kept original for a file cleaned in place), then re-scans. The file stays reported but automatic cleaning leaves it alone from then on. Durable workflow; `202` with the site's state, and the result lands in `listSiteSecurityHistory` as `restored` (or `failed`). Requires `sites.restart`. `422` when the finding is not restorable (`can_restore: false`).","tags":["hosting"],"responses":{"202":{"description":"The restore was queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteSecurity"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"description":"The scanner service is unavailable, so nothing was queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/ai/summary":{"get":{"operationId":"getAiSummary","summary":"The organization's AI position — balance, funding route, usage.","description":"Everything the AI page needs in one request: the Zinn® AI credit balance, which funding route the **next** call would take, the org's own provider keys, 30 days of metered usage and how many agent proposals are waiting.\n\n`funding_route` is derived from the same function the next call will use, never re-implemented — a screen that computes its own answer eventually tells a customer they are on their own key while we bill them. Requires `sites.view`.","tags":["ai"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"Which organization this is about. Required when the caller belongs to more than one; a caller in exactly one may omit it. Omitting it in a multi-org account is a `422` that says so, never a silent pick.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The AI summary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiSummary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/site-agent/preferences":{"get":{"operationId":"getAiSiteAgentPreferences","summary":"What this customer lets the AI do to their sites without asking.","description":"One row per fix the AI knows how to apply, carrying **three** values and not one: what the customer asked for (`requested`), what will actually happen (`effective`), and the highest mode the platform currently permits (`ceiling`).\n\nThey differ when a customer has chosen more autonomy than a fix has earned. A response carrying only `effective` would misreport the customer's own setting back to them — they chose \"just fix it\", the page shows \"ask me first\", and it looks as though their click did not register. `clamped` is true in exactly that case and `reason` says why in words a customer can read.\n\nThe ceiling is the platform's, not the customer's: a brand-new fix nobody has watched work cannot be set to unattended by anybody. Requires `sites.view`.","tags":["ai"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"Which organization this is about. Required when the caller belongs to more than one; a caller in exactly one may omit it.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"Every fix, with the customer's choice and the platform's ceiling.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiSiteAgentPreferences"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"put":{"operationId":"setAiSiteAgentPreference","summary":"Choose what the AI may do for one kind of fix.","description":"Records the customer's wish. The **requested** value is stored, never the clamped one: a customer who asks for \"just fix it\" on a fix still earning its rung keeps that setting, and it takes effect on its own the day the fix is promoted. Storing the clamp instead would quietly downgrade them for ever with no way to see it had happened.\n\nAn unknown action or remedy key is a `422` naming it, never a silently ignored write. Requires `sites.view`.","tags":["ai"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiSiteAgentPreferenceWrite"}}}},"responses":{"200":{"description":"The stored choice and what it resolves to.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiSiteAgentPreference"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/site-agent/allowance":{"get":{"operationId":"getAiSiteAgentAllowance","summary":"How many self-serve site checks are left this month.","description":"One allowance per organization per calendar month, sized by how many sites the organization has — not per site. Free grants from staff are added to it.\n\nChecks run from the **support ticket form are free and unmetered** and never appear in `used`: a customer who has exhausted their allowance can still open a ticket and still gets a full check on their site. `in_good_standing` is false while an account is suspended or unpaid, which pauses metered checks only — the ticket path and previously-purchased results are unaffected. Requires `sites.view`.","tags":["ai"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"Which organization this is about. Required when the caller belongs to more than one; a caller in exactly one may omit it.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The allowance, what has been used, and what is left.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiSiteAgentAllowance"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/site-agent/sites/{site_id}/check":{"post":{"operationId":"runAiSiteAgentCheck","summary":"Read this site's server, diagnose it, and fix what the customer allows.","description":"Reads the site's live server — error log, PHP faults, slow queries, disk and memory — diagnoses what is wrong, and applies the fixes this customer has allowed to run unattended. Fixes they have asked to be asked about come back in `offered` with the finding that triggered them, so the screen can show the button.\n\nLog text is **redacted before it leaves the server**: visitor IP addresses, email addresses, tokens, keys and passwords are masked, and `logs.sources[].masked` reports how many runs of each kind were removed. On our own fleet the server-wide error log is filtered to this account on the host, so another tenant's lines are never transferred at all.\n\nA source that could not be read is returned with `state: unavailable` and a reason, **never omitted** — \"we found nothing wrong\" and \"we could not look\" are different answers and only one of them is reassuring. `incomplete` is true whenever any source is in that state.\n\nCounts against the monthly allowance. A `402` means the allowance is exhausted or the account is not in good standing; the body carries the allowance and a message. Requires `sites.view`.","tags":["ai"],"parameters":[{"name":"site_id","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"What was read, what was found, and what was fixed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiSiteAgentCheck"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"Out of allowance, or the account is not in good standing. The body carries the allowance and a message the customer can act on.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiSiteAgentCheck"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/credits":{"get":{"operationId":"getAiCredits","summary":"Zinn® credit balance, whether to offer more, and the packs for sale.","description":"Everything the three credit surfaces need, in **one** request: the balance, whether this customer is genuinely short, and the packs they can buy.\n\nThe AI page, the header chip and the upsell banner all read this endpoint rather than each deciding \"is this customer low?\" for itself. Two behaviours reading one fact is how a header comes to nag somebody the banner has decided is fine, so `state.is_low` is computed server-side and every surface renders it.\n\n`state.on_byo` is `true` only when a live customer key exists for **every** provider we route to, so credits genuinely cannot be spent. The banner must stay silent in that case: selling credit to somebody whose every call runs on their own key sells them something that will never be spent. It is **not** \"this org has a key\" — a customer holding one Anthropic key still pays us for Google, OpenAI and xAI.\n\nAmounts are USD **micros** (1 minor unit = 10,000 micros; 1 USD = 1,000,000), because one model call costs a fraction of a cent and rounding each one up to a penny over-bills by two orders of magnitude. `packs[].price_minor` is ordinary integer minor units, because that is what the customer is charged. Requires `sites.view`.\n\nThe AI credits an active plan includes (`inference_credits_monthly`, Zinn® AI Hosting) are granted before the balance is read, once per monthly slot of the subscription's period: one credit is 1,000 micros (USD 0.001) of usage at the price charged, so 5,000 credits are USD 5. Only an `active` subscription of an org in good standing earns a grant. The grant appears in `history` as a `grant` row whose `note` is the token `plan_credit:<credits>`, which the dashboard renders as a translated sentence.","tags":["ai"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"Which organization this is about. Required when the caller belongs to more than one; a caller in exactly one may omit it.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The credit position, the packs and the customer's preferences.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiCreditOverview"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/inference/models":{"get":{"operationId":"listAiInferenceModels","summary":"The open models serverless AI inference offers, with the customer price.","description":"The models `POST /v1/ai/inference/chat` accepts (Zinn® AI Hosting, AIHOSTING slice 2), each with what one million input and output tokens CHARGE the customer in USD micros (the meter's price, so the number shown is the number the ledger debits). `default_model` is the cheapest priced model, derived from measured prices. Requires `sites.view`.","tags":["ai"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"Which organization this is about. Required when the caller belongs to more than one; a caller in exactly one may omit it.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The offered models and their prices.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiInferenceModels"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/inference/chat":{"post":{"operationId":"createAiInferenceChat","summary":"Run one chat completion on an open model, paid from Zinn® AI credits.","description":"Serverless AI inference for Zinn® AI Hosting plans (every AI Hosting plan grants `serverless_inference`). Runs in the request, on actual tokens, billed from the org's Zinn® AI credits: plan-included credits first spend here (this is an AI Hosting surface), then bought top-up credit. The platform's small daily included allowance never funds it, and a customer's own provider key is not used.\n\nGates, each before anything is sent or charged: the plan grants `serverless_inference` (else `422 FEATURE_NOT_INCLUDED`); the model is offered and priced (else `422`, `refusal.aiInference.unknownModel`); the org is in good standing (else `422 AI_NOT_IN_GOOD_STANDING`); credit is left (else `422 AI_CREDIT_REQUIRED`, `details[].can_buy`). An answer that stops at the caller's own `max_output_tokens` before it finishes (a reasoning model can spend a small cap thinking) answers `422` with `details[]` `{field: max_output_tokens, maximum}` and a `failure` of class `refused`, code `output_cap_reached` (`aiError.outputCapReached`): raise the cap and send it again. Any other failed model call answers `503` with a `failure` whose class is `our_fault` and names no supplier. Neither charges anything. At most 64 messages of 32,000 characters; `max_output_tokens` 1 to 4,096 (default 2,048). A reasoning model's thinking is off unless `reasoning` is `true`; opted in, the thinking counts against `max_output_tokens` and every token is billed. Requires `sites.create`.","tags":["ai"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiInferenceChatRequest"}}}},"responses":{"200":{"description":"The reply, the tokens used, what was charged and the balance after.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiInferenceReply"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/ai/credits/settings":{"put":{"operationId":"setAiCreditSettings","summary":"Turn automatic top-up on or off.","description":"Automatic top-up is **off by default** and only the customer can turn it on. When it is on, running below the threshold buys the chosen pack once, with an hour between attempts so a declining card cannot be retried in a loop.\n\nRequires `billing.payment.manage` — turning this on is a decision to let us charge a saved card, which is the same audience as managing a provider key.","tags":["ai"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiCreditSettingsWrite"}}}},"responses":{"200":{"description":"The updated credit position.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiCreditOverview"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/site-builds":{"get":{"operationId":"listSiteBuilds","summary":"The organization's AI-built sites, its trial state and its builder spend.","description":"Every draft this organization has built, newest first, capped at 50.\n\n`files` is deliberately **omitted** from each row here and present on `getSiteBuild` — a generated tree can be a hundred kilobytes and thirty of them inlined is a response no client can render. Read `file_count` for a list, and fetch one build for its contents.\n\n`trial` answers whether the one-time free allowance has been used. Requires `sites.view`.","tags":["ai"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"Which organization this is about. Required when the caller belongs to more than one; a caller in exactly one may omit it.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The drafts, the trial state, the balance and the total spend.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBuildList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createSiteBuild","summary":"Describe a site and the AI builds it.","description":"Accepts a brief and returns the new draft **at once, in `generating`, with no files yet**. A durable workflow writes the site — a real multi-page site takes one to three minutes, which no request can hold (D20191) — and the row settles to `drafted`, or to `failed` with a reason in `error`. Poll `listSiteBuilds` or `getSiteBuild` to watch it. Nothing is public until `publishSiteBuild` is called.\n\nThe model is the **cheapest priced one the catalogue has verified** for the funding provider unless `model` names another (§2.45); the choice is recorded on the row.\n\n**The first build on an organization posts its one-time free allowance before the spend is authorised**, so a brand-new customer's first build succeeds rather than being refused and then handed credit they cannot retroactively use. The grant is made one-time by a database constraint, not by application code.\n\nBilled on **actual** token usage against the ordinary AI credit balance, or against the customer's own provider key when they have one — the same one meter every other AI surface uses.\n\nRefuses rather than truncating: a site that overran the size cap, that named an unusable file path, or that came back without a home page is reported as a `422` with a reason, because a half-written site that renders is worse than none — the customer would publish it.\n\nRequires `sites.create`, which is a stronger authority than reading a draft needs: this call spends the organization's money.","tags":["ai"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBuildCreate"}}}},"responses":{"201":{"description":"The finished draft, with its files.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBuildEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/site-builds/{siteBuildId}":{"parameters":[{"name":"siteBuildId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"get":{"operationId":"getSiteBuild","summary":"One AI-built site, with every generated file.","description":"The draft and its complete `files` map. A build belonging to another organization is a `404` rather than a `403`, because a `403` would confirm the identifier exists. Requires `sites.view`.","tags":["ai"],"responses":{"200":{"description":"The build.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBuildEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/site-builds/{siteBuildId}/publish":{"parameters":[{"name":"siteBuildId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"publishSiteBuild","summary":"Put an AI-built site live on one of the organization's sites.","description":"Deploys the draft's files to the named site's edge host — Cloudflare Pages, Netlify, GitHub Pages, GitLab Pages, Vercel or AWS Amplify — and optionally pushes them to the organization's git provider as well.\n\nIdempotent on the build: a retried publish republishes the same draft rather than stacking a second deployment, and produces neither a duplicate repository nor an empty commit.\n\n**A site on our own fleet is published through its own repository instead**, because a fleet document root accepts bytes from exactly one place: a git checkout over SSH. The customer's connected GitHub or GitLab repository is therefore a *prerequisite* there rather than the optional extra it is on an edge host — a site without one is refused with `fleet_needs_repo`, naming the missing connection.\n\nThat path can also finish `held` rather than `published`, which no edge publish does. A fleet document root holding files we did not put there is left **untouched** and `hold_reason` says so: overwriting it would destroy the customer's own work silently. The generated files are safe in the repository and the customer chooses which version wins on the site's sync screen. A `held` response is a successful refusal — do not retry it automatically.\n\nA site that is neither on our fleet nor on a managed edge host is refused with that provider's own reason. A site on a resold package is refused because its vendor publishes it, not us.\n\nRequires `hosting.deploy.manage` — a separate and stronger authority than reading a draft, so somebody who may look at one cannot put it in front of the public. The target site is scoped by that same authority, so naming a site the caller may only view is a `404`.","tags":["ai"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBuildPublish"}}}},"responses":{"200":{"description":"The published build, with its live URL.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBuildEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/site-builds/{siteBuildId}/rebuild":{"parameters":[{"name":"siteBuildId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"rebuildSiteBuild","summary":"Build the site again from its brief, optionally tweaked.","description":"Runs the builder again on this draft's stored brief. Send `brief` to change it first; omit it to rebuild from exactly what was asked for before. Like `createSiteBuild`, the new draft is returned in `generating` and settles through the same workflow.\n\n**A rebuild creates a NEW draft and never edits this one.** The original keeps its files, its cost and — if it was published — its live URL, because the customer paid for it and may be about to decide they preferred it. The new draft records `rebuilt_from` so a screen can show the lineage.\n\nIt costs exactly what a first build costs and is metered identically; there is no discount for reusing the brief, because the model does the same work.\n\nRequires `sites.create` — the same authority as building the first one, and a stronger one than reading a draft, because this spends money.","tags":["ai"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBuildRebuild"}}}},"responses":{"201":{"description":"The new draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBuildEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/site-builds/{siteBuildId}/files":{"parameters":[{"name":"siteBuildId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"put":{"operationId":"putSiteBuildFile","summary":"Replace one generated file's contents.","description":"Writes `content` to `path` in this draft, creating the file if it does not exist. Adding `robots.txt` to a generated site is the same act as correcting `index.html`, so both are allowed; the size and file-count caps are what bound it.\n\nThe path goes through the same validator the builder's own output does — relative, no traversal, and a suffix a static host will serve and that cannot execute on our side. Images cannot be edited here because they are not text.\n\n**Refused on a published build** (`published`). A published draft's files are what visitors are seeing; editing them here would make the record disagree with the live site silently, until somebody republished for an unrelated reason.\n\nRequires `sites.create`.","tags":["ai"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBuildFile"}}}},"responses":{"200":{"description":"The draft, with the edited file.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBuildEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/site-builds/{siteBuildId}/images":{"parameters":[{"name":"siteBuildId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"get":{"operationId":"quoteSiteBuildImages","summary":"What generating this draft's images would cost. Spends nothing.","description":"Lists every image the generated markup asks for and prices them, **without generating anything and without charging anything**. Images already generated for this draft are listed separately and are not quoted again.\n\nThe list comes from the `<img>` tags in the generated HTML rather than from a number anybody types, so the count shown is the number of images the site actually uses.\n\n`unit_price_usd_micros` is `0` when the organization is on its own provider key — that is the true answer to \"what will we charge you\", not a missing value; their own provider bills them directly.\n\nRequires `sites.create`.","tags":["ai"],"responses":{"200":{"description":"The quote.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBuildImageQuoteEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"generateSiteBuildImages","summary":"Draw the draft's images. Charges the content-images meter.","description":"Generates every image the markup asks for and stores it against the draft, so a publish carries the pictures as well as the markup.\n\n**Send back the total you were quoted.** If the price has moved since — the catalogue changed, a model was withdrawn, another tab generated some of the same images — this is refused with `price_moved` and nothing is charged. A confirm that charged a different number from the one on the screen is the one thing a money confirm must never do.\n\nImages already generated are skipped and not re-charged, so pressing the button twice costs nothing the second time.\n\nTwo meters bill for a draft with images: the build's own generation, and this. Both are visible on the organization's AI usage screen.\n\nRequires `sites.create`.","tags":["ai"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBuildImagesConfirm"}}}},"responses":{"201":{"description":"The images drawn, and the draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBuildImagesEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/site-builds/targets":{"get":{"operationId":"listSiteBuildTargets","summary":"Where a draft can be published, and what is already on each destination.","description":"Lists every site the caller may deploy to, and — the part that did not exist before — **what is already there**. Publishing used to take a site id with no way to discover which ids were valid, and no way to learn that a destination had a live business on it.\n\n`occupancy` is the field to read, never `known_files`:\n\n* `empty` — nothing is deployed. Publishing here destroys nothing.\n* `ours` — we published the current contents ourselves, from an earlier draft.\n* `occupied` — something is there and we can read it, because the site has a connected repository.\n* `unknown` — something may be there and we **cannot** read it. This is deliberately not reported as `empty`: an empty destination is precisely the one where overwriting is safe, so the two must never collapse. A destination we cannot read offers `replace` only, and the customer is told to connect a repository if they want to add to it instead.\n\n`allowed_dispositions` is advisory — the screen uses it to decide which buttons to show, and the engine re-derives it when a publication is started. A client that offers a disposition this list omits is refused with `disposition_not_available`.\n\n`publishable` (s1014 L57): a **static** site on our own fleet needs no repository — the publication workflow places the draft in its document root itself, through the same host-pull seam the web archive restore uses. A static site that is still being set up is `publishable: false` with a `refusal` saying so, until it is active. A WordPress or PHP site on our fleet still needs a connected repository. Starting a publication on a destination this list marks unpublishable is refused up front with `not_publishable` (no row, no backup).\n\nRequires `hosting.deploy.manage`, even though this only reads: the list is \"places you may publish to\", and offering a destination the caller cannot use both answers the wrong question and discloses sites they may only view.","tags":["ai"],"parameters":[{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Match against the destination's primary domain."}],"responses":{"200":{"description":"The destinations and the disposition catalogue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMakerTargetList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/site-builds/{siteBuildId}/preview":{"parameters":[{"name":"siteBuildId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"previewSiteBuildPublication","summary":"What publishing this draft would do to that site. Changes nothing.","description":"Answers \"what happens if the site is already there\" before anything happens: which existing files are kept, which are added, which would be **overwritten**, and which generated files would be renamed to avoid a collision.\n\nThis runs the same guard the publication itself runs, not a second description of it. A preview computed by different code is a promise the real path never made, and it would be wrong in exactly the cases that matter.\n\nThe preview does **not** require the typed confirmation that a `replace` needs. A customer has to be able to see what would be destroyed before deciding to confirm it; demanding the confirmation in order to show the consequence is the wrong way round.\n\nRequires `hosting.deploy.manage`.","tags":["ai"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMakerPreviewRequest"}}}},"responses":{"200":{"description":"What would change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMakerPreviewEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/site-builds/{siteBuildId}/plugin-plan":{"parameters":[{"name":"siteBuildId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"planSiteBuildPlugins","summary":"Which plugins this generated site needs, and a custom one if it needs that.","description":"Chooses plugins for the generated site from a curated set, and writes one small WordPress plugin when the site needs behaviour no listed plugin provides.\n\nGenerated PHP is **scanned before it is packaged**, not before it is installed: dynamic execution, shell access, remote includes, direct filesystem writes, unescaped request data and hand-built SQL are refused outright, and a plugin that fails never becomes an archive at all. When that happens the reason appears in `notes` — a scan that silently dropped its subject would be indistinguishable from a scan that found nothing.\n\nSlugs the model proposes that are not in the curated set are dropped and **counted** in `rejected` rather than passed through.\n\nThe generated plugin's source is deliberately not returned. It is real PHP that has passed the scan; handing it to a client invites an edited copy to be posted back on a path that believes it was scanned. Ask for it at publish time with `include_generated_plugin`, and it is regenerated and re-scanned there.\n\nSpends AI credit and is metered under the `site_builder` surface, on the one AI meter. Requires `sites.create`.","tags":["ai"],"responses":{"200":{"description":"The plan, and the curated catalogue it was chosen from.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMakerPluginPlanEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/site-builds/{siteBuildId}/publications":{"parameters":[{"name":"siteBuildId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"get":{"operationId":"listSiteBuildPublications","summary":"Every attempt to publish this draft, newest first.","description":"One draft can be published to several destinations, or to the same one twice with different dispositions, and each attempt keeps its own record — including which backup was taken before it. A backup nobody can find is a backup that does not exist.\n\nRequires `sites.view`.","tags":["ai"],"responses":{"200":{"description":"The publications.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMakerPublicationList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"startSiteBuildPublication","summary":"Publish a draft to a destination, taking a backup first when it destroys.","description":"Starts a durable publication and returns **202**, not 201: the work has been accepted and is running. A 201 would say the site is published when the backup has not started, and a customer reads \"created\" as \"done\".\n\nA destination `listSiteBuildTargets` marks `publishable: false` (no repository on a WordPress or PHP fleet site, or a static site still being set up) is refused with `not_publishable` before any row or backup is created (s1014 L57).\n\n`disposition` decides what happens to whatever is already on the destination:\n\n* `add_to` — every existing file is kept byte-for-byte and only new paths are written. A collision is **renamed** (`about.html` becomes `about-new.html`), never merged and never overwritten.\n* `revamp` — markup, stylesheets and scripts are replaced; content, data files and `robots.txt`, `sitemap.xml`, `.htaccess` and `ads.txt` are kept. A file type we have never seen defaults to kept.\n* `replace` — the whole tree becomes the draft. **Destructive.**\n* `wordpress` — a WordPress or WooCommerce site on our own hosting only, and its default: the draft is built inside WordPress as a block theme plus one real page per built page, with the home page as the front page. Idempotent (a retry updates the same pages), never deletes a post, page, plugin or theme, needs no typed confirmation, and takes a full backup first. Undo is restoring that backup.\n\nA `replace` requires `confirm_hostname` to equal the site's own primary domain, typed. A boolean flag would be satisfied by any client that set it — including a retry and every future caller that copied the previous request body — so it would confirm that a field exists rather than that a human read the domain.\n\nAnything that would overwrite live files takes a **full backup first** and waits for it to finish. That includes a `revamp` that happens to overwrite real pages: the requirement is keyed on what the publication does, not on which word was chosen. A site whose hosting cannot produce a backup is refused rather than published, because we cannot make the change reversible there.\n\nOne live publication per destination at a time; a second is refused with `409`.\n\nRequires `hosting.deploy.manage`, and the target site is scoped by that same authority.","tags":["ai"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMakerPublishRequest"}}}},"responses":{"202":{"description":"The publication was accepted and is running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMakerPublicationEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/site-publications/{publicationId}":{"parameters":[{"name":"publicationId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"get":{"operationId":"getSiteMakerPublication","summary":"How far a publication has got.","description":"`step` is the stage currently running and `steps` is the full ordered list, so a client renders progress without hardcoding the workflow's shape.\n\n`status` `held` is neither success nor failure: the generated files are safe in the repository and nothing on the site was overwritten, because the destination held files we did not put there. The customer chooses which version wins on the site's sync screen. Do not retry a `held` publication automatically.\n\nRequires `sites.view`.","tags":["ai"],"responses":{"200":{"description":"The publication.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMakerPublicationEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"cancelSiteMakerPublication","summary":"Stop a publication that has not finished.","description":"Cancels the running work. The response reports the publication's state **after** the cancellation was requested, which may still be `published`: by the time a cancel arrives the bytes may already have landed, and reporting `cancelled` for a site that is live would send the customer looking for something they would then find.\n\nA publication that has already finished is refused with `already_finished`.\n\nRequires `hosting.deploy.manage`.","tags":["ai"],"responses":{"200":{"description":"The publication, as it stands after the cancellation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteMakerPublicationEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/credentials":{"get":{"operationId":"listAiCredentials","summary":"The organization's own AI provider keys.","description":"The BYO keys this org has stored (D4). **The secret is never returned** — not masked, not last-four: there is no field on the response that could carry it. The key itself lives in Vault and its only consumer is the driver call. Requires `sites.view`.","tags":["ai"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The org's live provider keys.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiCredentialList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"addAiCredential","summary":"Store an AI provider key for this organization.","description":"Puts the key in Vault and records a pointer. Any existing live key for the same provider is revoked in the same transaction — one live key per provider, because two is not a richer model, it is an ambiguity about which key we are about to spend the customer's money through.\n\n⚖️ **The key is TESTED before this responds** — owner instruction 2026-08-20: *\"we need to test the api keys when they add them.\"* A **real** completion with our own prompts and tool format, not the free authentication probe: the narrower question is one a screen would render as a green tick while a recipe fails on its first run. The response carries `state`, `last_error` and `tested_on_save`.\n\n⛔⛔ **A FAILED TEST DOES NOT FAIL THE SAVE.** The key is already in Vault by then. Refusing would leave a customer who pasted a valid key with an empty screen and no way to tell \"we could not reach the provider\" from \"you typed it wrong\", while the secret sat stored. They get it saved, the state set honestly, and the provider's own reason to act on. A `422` still means nothing was stored anywhere.\n\n⭐ The provider's model catalogue is also filled from this key in the same call — a free authenticated read that costs the customer nothing, and the only opportunity we get for a vendor we hold no platform key for.\n\n⛔ Vault is written **before** the row, and the row is created only if that succeeded. A `422` means nothing was stored anywhere: an unreachable secret store is a refusal, never a silent skip that leaves the customer believing their key was saved. Requires `billing.payment.manage`.","tags":["ai"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiCredentialCreate"}}}},"responses":{"201":{"description":"The stored key's pointer. The secret is not in this response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiCredential"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/credentials/{credentialId}":{"parameters":[{"name":"credentialId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"delete":{"operationId":"revokeAiCredential","summary":"Stop using an AI provider key.","description":"Deletes the secret from Vault and marks the row revoked. **The row is kept**, because metered usage points at it: deleting it would orphan every record saying \"this call ran on your own key\", which is what answers \"why was I not charged for that\". Requires `billing.payment.manage`.","tags":["ai"],"responses":{"204":{"description":"Revoked."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/credentials/{credentialId}/test":{"parameters":[{"name":"credentialId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"testAiCredential","summary":"Test a stored AI provider key now.","description":"Runs a **real, tiny completion with our own prompts and tool format** on the key — not the free authentication probe. ⚖️ The owner's requirement, verbatim: *\"it must test it works with our system and prompts.\"* Authenticating and *working with our prompts* are different claims, and a screen showing only the first as a green tick is a control that cannot see the failure it exists to catch.\n\nCosts a fraction of a cent on the customer's own key, which is why it is only ever run on save, weekly, or when a person presses the button. Requires `billing.payment.manage`.","tags":["ai"],"responses":{"200":{"description":"What the test found, and the credential's new state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiCredentialCheck"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/providers":{"get":{"operationId":"listAiProviders","summary":"Which AI vendors are available, and whether this organization can use each.","description":"⚖️ The owner's *\"it should first only be available if they have ai keys set and tell them which ones\"* as data. Each entry says whether **our credits** cover that vendor, what state **this org's** key for it is in, and how many of its models we have proven against our own prompts.\n\n⚖️ Note the funding order the owner settled on 2026-08-20: credit packs are the **default** route and BYO keys the alternative, so a provider with `covered_by_credits: true` is usable with no key at all. Requires `links.view`.","tags":["ai"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"Every supported vendor, with this org's key state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiProviderOptionList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/model-notices":{"get":{"operationId":"listAiModelNotices","summary":"Saved AI model choices that were moved to the newest model.","description":"When a provider releases a newer model and the oldest of its family retires, every recipe or board that had saved the retiring model is moved to the newest model of the same family, and one notice is left here so the customer knows what changed and why. Undismissed notices only, newest first, at most 50. Requires `links.view`.","tags":["ai"],"responses":{"200":{"description":"The notices.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiModelNoticeList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/model-notices/{noticeId}/dismiss":{"parameters":[{"name":"noticeId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"dismissAiModelNotice","summary":"Dismiss one model notice.","description":"Hides the notice for everyone in the organization. Requires `links.view`.","tags":["ai"],"responses":{"204":{"description":"Dismissed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/models":{"get":{"operationId":"listAiModels","summary":"The live model catalogue.","description":"Models read from each provider's own endpoint and **proven against our prompts** before being offered. ⚖️ Owner instruction 2026-08-20: *\"auto update of the latest models they release so it stays up to date … and it must test it works with our system and prompts.\"*\n\n⛔ Returns `verified` models only unless `status=all` is passed. A `discovered` row has been listed by the provider and never called by us; offering one is how a customer's scheduled run fails on a model nobody has ever tried. Requires `links.view`.","tags":["ai"],"parameters":[{"name":"provider","in":"query","required":false,"schema":{"$ref":"#/components/schemas/AiProviderCode"}},{"name":"modality","in":"query","required":false,"schema":{"type":"string","enum":["text","image"]}},{"name":"status","in":"query","required":false,"description":"`all` includes discovered and failed models. Omit for verified only.","schema":{"type":"string","enum":["all"]}}],"responses":{"200":{"description":"The catalogue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiModelList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/recipes":{"get":{"operationId":"listAiRecipes","summary":"This organization's AI posting recipes.","description":"A recipe is a reusable posting configuration — brief, tone, length, language, anchors, cadence, targets, images, and how far it goes on its own. Requires `links.view`.","tags":["ai"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The org's recipes, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiRecipeList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createAiRecipe","summary":"Create an AI posting recipe.","description":"⛔ Bounds are enforced at **authoring** time, not at run time: more than five anchors or more than ten posts per run would be refused on every run, so a recipe saved with them would look fine, sit on a schedule, and fail silently every night. Requires `links.edit` — the same key as writing a post by hand, because that is what this is.","tags":["ai"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiRecipeWrite"}}}},"responses":{"201":{"description":"The created recipe.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiRecipe"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/recipes/{recipeId}":{"parameters":[{"name":"recipeId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"get":{"operationId":"getAiRecipe","summary":"One AI posting recipe.","description":"Requires `links.view`.","tags":["ai"],"responses":{"200":{"description":"The recipe.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiRecipe"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"patch":{"operationId":"updateAiRecipe","summary":"Edit an AI posting recipe.","description":"Partial update. The schedule is recomputed on every write rather than by a nightly job — a recipe saved with a cadence and no next run is a recipe that never runs and shows no error anywhere. Requires `links.edit`.","tags":["ai"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiRecipeWrite"}}}},"responses":{"200":{"description":"The updated recipe.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiRecipe"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"deleteAiRecipe","summary":"Delete an AI posting recipe.","description":"Archived rather than removed, and its schedule cleared in the same write. Runs it already produced stay readable — they point at content that exists. Requires `links.edit`.","tags":["ai"],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/recipes/{recipeId}/run":{"parameters":[{"name":"recipeId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"runAiRecipe","summary":"Queue an AI posting recipe to run now.","description":"**Returns as soon as the run is recorded — it does not wait for the article.** Writing takes longer than an HTTP request may live: the dashboard aborts at 20s and the engine's own worker timeout is 30s, so a synchronous run was killed mid-call every time. The response carries a run whose `state` is `queued`; poll `GET /v1/ai/recipes/{recipeId}/runs` until it reaches `succeeded`, `partial` or `failed`. A queued run normally starts within two minutes.\n\nThe work then happens on the customer's own key when they have one, on Zinn® AI credits otherwise — **one meter either way** (owner directive D4). What happens after the drafts exist is the recipe's `publish_mode`, which defaults to `draft`: nothing is scheduled or published unless the customer turned that on for that recipe.\n\nA `422` means nothing was queued and nothing was charged — funding is checked before the run is recorded, so an unaffordable run is refused here rather than failing later. Requires `links.edit`.","tags":["ai"],"responses":{"202":{"description":"The queued run. `funding` and `model` are empty until it executes — nothing has been decided or charged yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiRecipeRun"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/recipes/{recipeId}/runs":{"parameters":[{"name":"recipeId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"get":{"operationId":"listAiRecipeRuns","summary":"What an AI posting recipe has produced.","description":"Newest first. ⭐ The screen that answers *\"is my schedule actually running?\"* — the question a silent stop makes unanswerable. A recipe with a cadence, an empty list here and a `next_run_at` in the past is a state a customer can act on. Requires `links.view`.","tags":["ai"],"responses":{"200":{"description":"The recipe's runs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiRecipeRunList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/reports":{"get":{"operationId":"listAiReports","summary":"The AI reports this organization has bought.","description":"Every AI product's written report, with the fixes it raised — AI Webmaster site reviews and AI Update Guard pre-flight checks alike, newest first, distinguished by `kind`. An empty `report` while `status` is `fulfilling` means the run is still going — it does **not** mean nothing was found, and a client must render the difference. A `failure_reason` means the run was refused and the charge refunded. Requires `sites.view`.","tags":["ai"],"responses":{"200":{"description":"The org's AI reports, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiReportList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/subscriptions":{"get":{"operationId":"listAiProductSubscriptions","summary":"Which sites hold a recurring AI product, and when it next runs.","description":"The live AI Webmaster and AI Update Guard subscriptions for this organization. Each row carries the site, the product, and `cadence_days` — how many days the customer was sold between automatic runs — plus `next_due_at`, when the next one falls. `cadence_days` is a NUMBER rather than a rendered phrase so a client can say \"every 30 days\" in the customer's own language. `last_run_at` is null when the product has never run, which is not the same as having run and found nothing. Stopped subscriptions are omitted. Requires `sites.view`.","tags":["ai"],"responses":{"200":{"description":"The org's live AI product subscriptions, soonest due first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiProductSubscriptionList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/proposals":{"get":{"operationId":"listAgentProposals","summary":"What the AI agent wants done to this organization's resources.","description":"Cursor-paginated, RLS-scoped. **Nothing in this list has happened.** A proposal is a diagnosis plus a prepared action; the change is made when somebody approves it. Requires `sites.view`.","tags":["ai"],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"state","in":"query","required":false,"schema":{"$ref":"#/components/schemas/AgentProposalState"}}],"responses":{"200":{"description":"A page of proposals.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentProposalPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/proposals/{proposalId}/decision":{"parameters":[{"name":"proposalId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"decideAgentProposal","summary":"Approve or reject one proposal.","description":"Approving APPLIES the action, **under the approver's own permissions**. The caller must hold the permission the action itself requires, in the proposal's own organization — so approving can never reach further than the approver could reach by hand. A caller without it gets a `404`, never a `403`: answering \"forbidden\" would confirm the proposal exists.\n\n⛔ Not idempotent and not retryable. A second approval of an already-decided proposal is a `422`, which is the correct answer — a retry that applied the change twice would be a second cache purge or a second policy write nobody asked for.","tags":["ai"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentProposalDecision"}}}},"responses":{"200":{"description":"The proposal after the decision, including what happened.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentProposal"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/proposals/{proposalId}/revert":{"parameters":[{"name":"proposalId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"revertAgentProposal","summary":"Put an applied change back.","description":"Undoes a proposal that has been applied, restoring the values captured before it ran. Gated exactly as approving is — the caller must hold the action's own permission in the proposal's organization — because undoing a change is not a lesser act than making it.\n\n⛔ An action whose effect clears on its own (a cache purge) is a `422` saying so, not a silent success: there is nothing to put back, and reporting one would be a claim that something happened.\n\n⭐ This is also what earns a capability its rung 2. `revert_verified_at` is stamped by a revert that actually RAN, never by a form — the authority ladder wants an event rather than an intention.","tags":["ai"],"responses":{"200":{"description":"The proposal after the revert.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentProposal"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/fleet/register":{"post":{"operationId":"registerFleetWorker","summary":"Attach a booting agent to its declared fleet host.","description":"Called once when a worker-host agent starts. **Idempotent**, and structurally incapable of creating a fleet row: the host is the credential's foreign-key target, so re-registering converges the same row, and a re-register after the host was deleted cannot resurrect it (the delete cascaded the credential away, so the request no longer authenticates).\n**Registration does not make the box placeable.** It writes no status, no `acceptsDeploys` and no heartbeat stamp — a box that registers and then dies is still `provisioning` with a null heartbeat, and its declared capacity still counts zero toward placeable capacity. Promotion happens on the first *heartbeat*.\nThe request carries only what a box can honestly observe about itself. There is deliberately no capacity/region/pool/driver/`acceptsDeploys` field: those are operator facts set with `manage.py register_worker_host`, and a box that could declare `capacity=100000, pool=pbn` would pull every new PBN site onto itself.","tags":["fleet"],"security":[{"workerTokenAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkerRegisterRequest"}}}},"responses":{"200":{"description":"The host's placement identity, as the engine knows it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkerIdentity"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/fleet/heartbeat":{"post":{"operationId":"heartbeatFleetWorker","summary":"Stamp fleet liveness, ship the host report, collect queued commands.","description":"Sent every `heartbeatIntervalSeconds`. Carries the host health report — the same document the console has always shown — because the heartbeat and the report answer the same question, and one call means the report can never be fresher than the heartbeat it is judged against.\n**This is where a declared box becomes real capacity.** A host that has never heartbeated is promoted to `active` **and** starts accepting deploys on its first successful beat; every beat after that leaves `acceptsDeploys` untouched, so an operator's drain sticks across an agent restart. A `down` host that heartbeats again is revived to `active` or `draining` according to the operator's existing intent. A `decommissioned` host gets `continue: false` and nothing is written.\nThe response carries any commands the engine claimed for this host (bounded per tick). The claim is still `SELECT … FOR UPDATE SKIP LOCKED`, so exactly-once semantics are unchanged; only *who runs the query* moved, because a worker box has no database connection.","tags":["fleet"],"security":[{"workerTokenAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkerHeartbeatRequest"}}}},"responses":{"200":{"description":"The host's identity, whether to keep running, and claimed commands.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkerHeartbeatResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/fleet/commands/{commandId}/result":{"parameters":[{"name":"commandId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"A command claimed for this host in a heartbeat response."}],"post":{"operationId":"reportFleetCommandResult","summary":"Report how a claimed host command ended.","description":"A command belonging to a **different** host answers `404`, byte-identical to the answer for a command that does not exist — distinguishing them would make this an enumeration oracle for other hosts' command ids.\n`result` is one redacted line, never raw command output.","tags":["fleet"],"security":[{"workerTokenAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkerCommandResultRequest"}}}},"responses":{"200":{"description":"The command's recorded final status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkerCommandResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/fleet/drain":{"post":{"operationId":"drainFleetWorker","summary":"Take this host out of placement on graceful shutdown.","description":"The only availability change a box may make for itself, and safe in the direction it moves: a host can take itself **out** of service and never back **in**. Returning requires either the once-only first-heartbeat promotion or a staff undrain (`setWorkerDrain`). Idempotent; a `decommissioned` host is left alone.","tags":["fleet"],"security":[{"workerTokenAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkerDrainAgentRequest"}}}},"responses":{"200":{"description":"The host's identity after draining.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkerIdentity"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/fleet/phish-watch":{"post":{"operationId":"reportFleetPhishWatch","summary":"The box's upload watch graded freshly written site files as suspicious.","description":"A worker box's on-box upload watch (docs/1093 §8) scores a site's document root with the phishing detector the moment files in it are written, and the agent posts every MEDIUM/HIGH grade here. A **trigger, never a verdict**: the engine starts its own scan of THIS box's sites at the reported document roots and acts only on that scan, exactly as the hourly sweep would. Unknown document roots and other boxes' sites are ignored. Answers at once (`202`); one scan per box and document-root set per two minutes.","tags":["fleet"],"security":[{"workerTokenAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkerPhishWatchRequest"}}}},"responses":{"202":{"description":"The scan was started (or one for the same sites is already running).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkerPhishWatchResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/trials":{"get":{"operationId":"getTrial","summary":"This organization's free trial, if it has one.","description":"Returns `{\"data\": null}` when there is no trial. ⛔ Not a `404`: \"you have no trial\" is an ordinary answer to this question and the dashboard renders an offer from it — a 404 would make the ordinary case look like an error.","tags":["billing"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The live trial, or null.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrialEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"startTrial","summary":"Start a free trial on a plan.","description":"docs/20. **The endpoint the \"Start trial\" buttons had nowhere to point at.** Three admin trial endpoints existed — list templates, edit a template, staff-extend a trial — and no customer-facing one, so all 47 CTAs on the public pricing page linked to `?intent=register`: *register first*, which is the opposite of what the button says.\n\n⛔ `plan_code`, never a product line. Eligibility is a property of the **plan** (owner ruling 2026-07-29): cloud and VPS live in the same line as plans that do carry a trial, so a line-shaped request could not express \"never on billable per-instance compute\" at all.\n\nOne trial per organization **per product line** (owner ruling 2026-10-16, s1014 L58: an account may trial WordPress AND PBN, once each), enforced by a database constraint as well as a check — so a double-click races safely and the loser is refused rather than granted a second trial. Existing and paying customers may trial any line they never had; a plan on a line refuses only that line's trial (`refusal.trial.alreadySubscribedLine`). ⚖️ 2026-10-21 (ZEAB2): a card-required trial (Developer Hosting — 14 days, or 30 with `campaign: zeabur`) is refused with `refusal.trial.cardRequired` until a verified card is on file; the card is never charged.","tags":["billing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrialStart"}}}},"responses":{"201":{"description":"The started trial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Trial"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No such active plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The plan carries no trial, this organization has already used its one, or the caller bills for several organizations and named none.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/trials/eligibility":{"get":{"operationId":"getTrialEligibility","summary":"Can this organization start a trial on this plan, and on what terms?","description":"Lets a CTA be honest **before** it is clicked. Without it the only way to learn that a plan has no trial, or that this organization has already had one, is to press the button and read a 422 — which is how a \"Start free trial\" button that cannot start a free trial stays on a pricing page for months.\n\n`reason` distinguishes the cases deliberately: \"this plan has no trial\" and \"you have already had yours\" lead a customer to do completely different things, and a bare `eligible: false` would collapse them into one shrug.","tags":["billing"],"parameters":[{"name":"device_id","in":"query","required":false,"description":"docs/1000 §1 — the dashboard's per-browser id for the free-trial abuse guard.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{32}$"}},{"name":"plan_code","in":"query","required":true,"schema":{"type":"string","maxLength":64}},{"name":"campaign","in":"query","required":false,"description":"The campaign-only trial to ask about (`zeabur`); ignored when it names none on the plan.","schema":{"type":"string","maxLength":64}},{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Whether a trial can be started, and its terms.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrialEligibility"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/trials/lines":{"get":{"operationId":"listTrialLines","summary":"Every hosting line's free trial, and this organization's state on each.","description":"s1014 L58. ⚖️ Owner 2026-10-16: *\"make it CLEAR in the app: 'Try (product) free for 14 days' on every line the account has not trialled; trial status + switch option visible\"*. One answer for the dashboard's per-line cards, the assistants and the cross-sell sequence (`engine.billing.trials.trial_lines_for_org`). Lines whose trial has no plan on sale are not listed. ⛔ The cross-account abuse guard is NOT applied here — a person who trialled a line on another account learns it when they start.","tags":["billing"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"One row per hosting line with a card-free trial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LineTrialList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"description":"The caller bills for several organizations and named none.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/first-run":{"get":{"operationId":"getFirstRun","summary":"Every product this organization holds, with its one next step and whether it is done.","description":"s1014 FIRSTRUN (docs/1080). ⚖️ Owner 2026-10-18: *\"Nothing worse than someone taking a trial for x and then ending up lost in the app dashboard\"*. One row per held product — each live free trial, live plan subscription and add-on purchase — with what \"set up\" means for it (`kind`), the screen that does it (`next_path`, with the plan and line already chosen), an equal \"Build it with AI\" alternative where one exists, the guide, and whether the first success moment has happened, decided from account state on every call (`engine.billing.first_run`). Undone rows first, trials first. `product` (an app sign-up `?product=` key) adds the product the person signed up for when they hold nothing yet. `reminders` says whether the Overview home card and the trial banner may show for this organization (BRIEF 28: internal organizations only until switched on).","tags":["billing"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"product","in":"query","required":false,"description":"An app sign-up product key (`hosting`, `boards`, `seo-tools`, ...). Unknown keys are ignored.","schema":{"type":"string","maxLength":64}}],"responses":{"200":{"description":"The held products and their first steps.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FirstRunList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/trials/winback":{"get":{"operationId":"getTrialWinbackOffer","summary":"The one-time 7-day extension this account may take on its ended free trial, or null.","description":"s1014 L55 (docs/20 §5.6). ⚖️ Owner 2026-10-16: an ended free trial may take 7 more days, ONCE PER PERSON, EVER, across every product line. `offer` is `null` unless all hold: the `trial_winback` lifecycle sequence is switched on in admin; the account's latest trial ended (expired) within the last 30 days; nobody on the account has taken the extension before (the person is a keyed hash of their e-mail, so a second account does not get a second one); the account is in good standing for marketing; no plan or running trial on that line; and neither the abuse guard (an active ban, or any fingerprint matching one) nor the trial guard (a block or a flag for that line) objects — when either cannot answer, there is no offer.","tags":["billing"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The offer, or an `offer` of null.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrialWinbackOfferEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"description":"The caller bills for several organizations and named none, or named one it cannot act for.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"takeTrialWinbackExtension","summary":"Take the one-time 7-day extension — the ended trial runs again for 7 days.","description":"s1014 L55. The SAME trial row runs again until now + 7 days: same product line, same site limit, same plan; nothing is upgraded and nothing is charged. Sites the trial's end took offline come back, unless another enforcement (malware, abuse) holds them. Only a signed-in person may take it — not an API key and not a staff impersonation session (`refusal.trial.winback.personOnly`). Refusals: `refusal.trial.winback.alreadyUsed` (this person or this account already took it), `refusal.trial.winback.notOffered`. Audit-logged as `trial.winback_extended`.","tags":["billing"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrialWinbackTake"}}}},"responses":{"200":{"description":"The trial, running again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Trial"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"description":"No offer to take (already used, not offered, or no account named).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/trials/{trial_id}/switch":{"post":{"operationId":"switchTrial","summary":"Switch a running free trial to another product, keeping its end date.","description":"s1014 L58. ⚖️ Owner 2026-10-16: *\"within the first 3 days a trial can be switched to a different product keeping the remaining days\"*. Allowed once per trial, in its first three days, to a product this account never trialled and has no plan on. The product it leaves counts as trialled (it cannot be trialled again). Refused while the trial has a live site (`refusal.trial.switch.liveSite`) — remove the site, then switch. The new trial does not carry an auto-convert consent. Each refusal names its reason as `refusal.trial.switch.<code>`.","tags":["billing"],"parameters":[{"name":"trial_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrialSwitch"}}}},"responses":{"200":{"description":"The new, running trial on the chosen product.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Trial"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No such trial on this account, or no such active plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The switch is not allowed (window over, already switched, live site, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/alerts":{"get":{"operationId":"listAlerts","summary":"Every open alert for this customer, most urgent first.","description":"docs/87. What the bell in the dashboard header reads. ⚖️ Owner ask 2026-08-26: *\"maybe have an alerts bit somewhere like the other hosting platfroms do that has like an ! when something is open and then a list of them, like in other enterprise apps type of thing.\"*\n\nUnions seven sources: the customer's live **notices** (maintenance, DNS drift, a lost delegation, a paused posting run, a stranded card, a new PHP build, a certificate lapsing), an **expired or expiring stored card**, a **past-due subscription**, **domains** expiring without auto-renew or already lapsed, **suspended / restricted / quarantined** sites and orgs, any **supplier** we depend on reporting degraded or out, **our own** published open incidents and announced windows, and sites with **malware** on them.\n\n⛔ The last two are each deliberately distinct from the one before it. `incidents` is not `upstream` — that reports a *supplier* being unwell, this reports **Zinn®**, and a customer whose site is slow wants the second far more. `security` is not the suspended/restricted/quarantined family — those are *enforcement outcomes* and the site is already off, where an infected site inside its grace window is still serving and the customer can still act. A site that is both appears in both, and that is deliberate: the second alert is the reason for the first.\n\n⛔ No permission key — being told your card has expired is not a privilege. Gating it would mean a member whose role lacks `org.read` silently never learns their sites are suspended.\n\n⛔⛔ **This shipped in the same change that stopped platform notices bannering on every page.** Landing that alone would have made maintenance *unreachable* from `/sites` rather than merely quieter — a false all-clear with nothing red (§2.44). A banner policy without a bell is not a smaller feature, it is a worse one.\n\n⛔ The header calls this on every page, so it is seven bounded queries against indexed columns and reaches no vendor (§2.16). Every count that could be per-site is a grouped aggregate returning ONE row, so an estate with 40,000 suspended or infected sites produces one alert saying so rather than 40,000.","tags":["notices"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"Narrow to one organization. Omitted, the caller's whole accessible subtree is considered. An id outside that scope narrows to nothing rather than 403-ing.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The alerts, the badge count, and which checks could not run. ⛔ Read `degraded` before concluding anything from an empty `data`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/alerts/read":{"post":{"operationId":"markAlertsRead","summary":"The customer has seen these alerts.","description":"Clears the badge for these keys, for **this user only** — a colleague clearing the bell must not clear it for the rest of the team.\n\n⚠️ **Read is not dismissed and not resolved.** An expired card that has been read is still expired, still listed and still red. Conflating the three would let a customer make a real problem *look* solved by opening a dropdown.\n\nIdempotent: the panel marks on open, and customers open it repeatedly.","tags":["notices"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertReadRequest"}}}},"responses":{"204":{"description":"Recorded."},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/offers":{"get":{"operationId":"listOffers","summary":"The upsells this customer has earned, best first.","description":"⚖️ Owner, 2026-08-28: *\"on the app overview screen should we not upsell some things\"*, and — on how they are chosen — *\"we shuld have 3 there and they should roate ... we should be able to devide in admin which ones to incluide and which not with siple on off swithc\"*.\n\nEvery **active** offer whose audience reaches this customer and whose signal is true for them, ordered by the rank an operator set, with copy already translated into the reader's own language.\n\n⛔ **Every earned offer is returned, not the first `slots` of them.** The rotation that shows a different few on each visit is the client's, and it can only rotate over what it is given — truncating here would leave the dashboard cycling the same three cards for ever while appearing to work. The list is bounded by the size of a catalogue staff maintain by hand: tens, never thousands.\n\n⛔ A reseller's own client is served an **empty list**, whatever the catalogue says. Selling Zinn® products at Zinn® prices inside a reseller's white-labelled dashboard, to the reseller's customer, undercuts the reseller who is paying us (owner ruling, same day). An account that is not in good standing is likewise never sold to (§2.46).\n\n⛔ An offer whose link names a site the reader does not have is **dropped**, not rendered with a broken destination. Requires `sites.view`.","tags":["offers"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"Which organization this is about. Required when the caller holds more than one; a caller in exactly one may omit it. An id outside the caller's scope, or an omission by a multi-org caller, returns an **empty list** rather than an error — an offer panel is additive, and a 404 here would put an error block on the Overview of a customer whose dashboard is otherwise fine.","schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The offers to render, best first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfferList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/notices":{"get":{"operationId":"listNotices","summary":"The notices to show at the top of this screen.","description":"docs/87. What the platform is currently telling **this** customer, on **this** route, in **their** language — already sanitised, already localised.\n\n⛔ No permission key. Reading the notices aimed at you is not a privilege: gating it would mean a member whose role happens to lack `org.read` never learns their card needs re-adding. The audience is the scope — a notice reaches an organization only if it is explicitly `everyone` or that org is named in its audience. An untargeted notice reaches nobody, never everybody.\n\nExactly one of `body_html` and `body_i18n_key` is populated (a database constraint). `body_html` is operator-authored and safe to render as HTML; `body_i18n_key` + `body_params` are rendered from the SPA's own catalogue.","tags":["notices"],"parameters":[{"name":"route","in":"query","required":false,"description":"The dashboard path being rendered, e.g. `/billing/invoices`. Defaults to `/`. A query string is ignored, so a notice aimed at `/billing` does not vanish when the screen adds a tab.","schema":{"type":"string","default":"/"}},{"name":"org_id","in":"query","required":false,"description":"Narrow to one organization. Omitted, the caller's whole accessible subtree is considered, so a reseller admin sees a notice aimed at a client org they manage. An id outside that scope narrows to nothing rather than 403-ing.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The notices to render, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoticeList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/notices/{noticeId}/dismiss":{"post":{"operationId":"dismissNotice","summary":"The customer closed a notice.","description":"Per **user**, not per organization — a colleague dismissing a promotion must not remove it from everyone else's dashboard.\n\nIdempotent, and `204` whether or not the id resolved: \"I have closed this\" cannot fail from the customer's side, and answering differently for an id they are not in the audience for would confirm that a notice exists.","tags":["notices"],"parameters":[{"name":"noticeId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Recorded."},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/images/credentials":{"get":{"operationId":"listAiImageCredentials","summary":"The organization's own image-provider keys.","description":"The BYO **image** keys this org has stored. ⛔ A different set from `/v1/ai/credentials`: those are text keys. A customer may hold an OpenAI image key and an Anthropic text key, the provider sets do not overlap (Anthropic publishes no image model, xAI no text model we use), and one enum offering both would let them save a combination that can never work.\n\n⛔⛔ **These are OPTIONAL.** Image generation runs on platform credentials against the org's AI credits by default; a key here is the opt-in switch to their own provider account. No key does **not** mean no images. Requires `sites.view`.","tags":["ai"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The org's live image keys.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiImageCredentialList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"addAiImageCredential","summary":"Store an image-provider key for this organization.","description":"Puts the key in Vault and records a pointer. Any existing live key for the same provider is revoked in the same transaction.\n\n⭐ **The key is tested immediately, by generating a real image**, and the result is on the response. An auth probe is green against a model id that no longer exists, so the only check worth returning is one that actually draws something. A key that does not work is still stored and still a `201` — the row records `last_check_ok: false` and the provider's own words in `last_check_error`, because \"we saved it and it does not work\" is the successful outcome of this request and a `4xx` would leave the screen unable to say why. Requires `billing.payment.manage`.","tags":["ai"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiImageCredentialCreate"}}}},"responses":{"201":{"description":"The stored key's pointer, with the result of its first real test.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiImageCredential"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/images/credentials/{credentialId}":{"parameters":[{"name":"credentialId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"delete":{"operationId":"revokeAiImageCredential","summary":"Stop using an image-provider key.","description":"Deletes the secret from Vault and marks the row revoked. **The row is kept**, because metered usage points at it. ⛔ The row is revoked even if the Vault delete fails: every read path filters on the revocation, so a key we cannot delete is still a key we will never use again — whereas a failed revoke that left the row live would keep charging the customer's provider account after they asked us to stop. Requires `billing.payment.manage`.","tags":["ai"],"responses":{"204":{"description":"Revoked."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/images/credentials/{credentialId}/test":{"parameters":[{"name":"credentialId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"post":{"operationId":"testAiImageCredential","summary":"Check an image key now, by generating a real image with it.","description":"The customer's own \"check it now\". Same mechanism as the scheduled sweep, so the answer on screen and the answer in the sweep can never disagree.\n\n⛔ A `POST` and not a `GET` because it **costs money**: it draws an image on the customer's provider account. A GET that spends would be retried by every browser, proxy and prefetcher on the path. Requires `billing.payment.manage`.","tags":["ai"],"responses":{"200":{"description":"The key's state after the check.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiImageCredential"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/images/library":{"get":{"operationId":"listStandaloneImages","summary":"The images this organisation generated for its own use.","description":"The customer's own image library — every image they asked for directly, newest first, up to 200. Requires `sites.view`.\n\n⛔ Filtered on `purpose = standalone`, not on an absent `post_id`. Those are not the same set: the featured-image backfill writes rows for a post that already lives on the customer's WordPress and identifies it by `site_id`/`remote_post_id` with `post_id` left null, so a null-based filter would put live site images into a personal library where deleting one destroys the record of a media upload.\n\n⛔ No bytes and no URL on these rows, for the same reason the post rows carry none — the staged object is in a private bucket. Use the `file` endpoint.","tags":["ai"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"This organisation's standalone images.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeneratedImageList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"generateStandaloneImages","summary":"Generate images from a prompt, with no post involved.","description":"Draws up to four images from the customer's own prompt and keeps them in their library for 90 days. Requires `links.edit`.\n\n⭐ This is the door that makes image generation a product rather than a post decoration. Every other image operation needs a content post to exist first; a hosting customer who wants a hero picture for their homepage, a social card or a product shot has none and never will.\n\nBilling is the **one AI meter** — BYO key first, then Zinn® credits, then whatever the plan includes; there is no separate image SKU. ⛔ A suspended account or one with no active subscription is refused before anything is drawn (§2.46), with `AI_NOT_IN_GOOD_STANDING` rather than the top-up message: that one is fixed by settling the account, and offering a credit button there sends the customer to a screen that cannot help them.\n\nThe response carries `unmet` — anything the chosen provider could not honour, in words for the customer. Nothing is silently dropped.","tags":["ai"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateStandaloneImages"}}}},"responses":{"201":{"description":"The generated images and anything the provider could not honour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandaloneImageResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/images/library/{imageId}":{"parameters":[{"name":"imageId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"delete":{"operationId":"deleteStandaloneImage","summary":"Throw one of your own generated images away.","description":"Deletes the row **and the stored object**. Requires `links.edit`.\n\n⛔ Only a `standalone` row. A post image's row records the media id its upload was given, and losing that turns a re-publish into a duplicate in the customer's media library.\n\n⛔ Storage failure is not fatal: the customer's row goes either way, and the 90-day lifecycle rule reclaims the bytes.","tags":["ai"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/images/library/{imageId}/file":{"parameters":[{"name":"imageId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"get":{"operationId":"downloadStandaloneImage","summary":"Download the image bytes.","description":"The image itself, as an attachment. Requires `sites.view`.\n\n⛔⛔ **This is how the customer gets the thing they paid for.** A standalone image has no WordPress post to be written into, so without this endpoint it is a row in a table and a charge on a meter.\n\n⭐ Streamed through the engine rather than handed out as a presigned link: a signature that expires while the screen is open is a broken thumbnail with no explanation.\n\n⛔ `404` once the 90-day retention has taken the object, which is not an error on anybody's part.","tags":["ai"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The image bytes.","content":{"image/*":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/images/models":{"get":{"operationId":"listAiImageModels","summary":"The image models a recipe may be pointed at.","description":"The catalogue, filtered to what is actually sellable. ⛔ `untested` rows are excluded: a model the nightly self-test has *discovered* from a provider's listing is real but unproven, and offering it would be selling on the strength of a vendor's web page. `legacy` rows **are** included — a customer who pinned one deliberately keeps working.\n\n⭐ Model ids here are **rows, not constants**, refreshed nightly from each provider's own listing and proven by a real generation. That is not architecture for its own sake: on the day this shipped, two of the three models the owner named by nickname had already moved to different ids. `capabilities` says what each one will and will not honour, so the picker can warn **before** a choice is made rather than after a post goes out with the wrong-shaped picture. Requires `sites.view`.","tags":["ai"],"parameters":[{"name":"provider","in":"query","required":false,"schema":{"type":"string","enum":["openai","google","xai"]}}],"responses":{"200":{"description":"Selectable image models.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiImageModelList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/images/providers":{"get":{"operationId":"listAiImageProviders","summary":"Which image providers this organisation can actually generate with.","description":"Whether each provider can draw **right now, for this org**, and a machine-readable `reason` when it cannot. Requires `sites.view`.\n\n⚖️ Owner ruling 2026-08-20 — *\"declare capabilities; warn BEFORE they pick\"*. That was built for a model's capabilities and never for the provider itself, which is the coarser and far more expensive version of the same question. Measured on production 2026-08-21: the live picker offered **OpenAI** and **xAI Grok** as ordinary enabled choices and both answered `422` on every request, because the estate holds a key for neither and no customer key could promote a model on its own.\n\n⛔ `reason` is a **code**, never a sentence — `no_key`, `no_model`, `key_broken`, or empty when usable. Every string a customer reads is translated into 57 languages (§2.19), so a message assembled in the engine is an English message on a German screen.\n\n⛔ `usable` and `key_broken` are independent. With platform credits behind it, a provider whose customer key has failed its last check is still usable — and the customer still needs telling, which is why both fields travel.","tags":["ai"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"Availability of every image provider for this organisation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiImageProviderAvailabilityList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/images/posts/{postId}":{"parameters":[{"name":"postId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"get":{"operationId":"listPostImages","summary":"The images generated for one content post.","parameters":[{"name":"org_id","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Uuid"}}],"description":"Requires `sites.view`. ⛔ No bytes and no URL on these rows — the staged object lives in a private bucket behind a signature that expires in minutes, so a link here would die while the customer was looking at it. Use the preview endpoint.","tags":["ai"],"responses":{"200":{"description":"The post's generated images.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeneratedImageList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"generatePostImages","summary":"Generate a featured image and in-post images for a content post.","description":"Generates the images **and writes the `<img>` placeholders into the post body**, in one transaction. ⛔ Those are deliberately not two endpoints: one that generated images and left the body alone would produce rows in a table, nothing on a page, and a dashboard reporting success.\n\nAlt text is generated and stored in the source language and **localised to the destination site's language when the post is published** (§2.19) — one post goes to many sites, so the language is a property of the site, not of the draft.\n\nThe response carries `unmet`: anything the chosen provider could not honour, in words for the customer. Nothing is silently dropped. Requires `links.edit`.","tags":["ai"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeneratePostImages"}}}},"responses":{"201":{"description":"The generated images, the body with placeholders, and any unmet asks.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeneratedImageResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/ai/images/posts/{postId}/preview/{imageId}":{"parameters":[{"name":"postId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}},{"name":"imageId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"get":{"operationId":"previewPostImage","summary":"The staged bytes of one generated image.","parameters":[{"name":"org_id","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Uuid"}}],"description":"Streamed through the engine rather than handed out as a signed link, because the customer is looking at this **before** it reaches their site and a URL that expires while the screen is open is a broken thumbnail with no explanation.\n\n⛔ A `404` once the staged object has been pruned. Generated images are kept for **14 days after publication** and then deleted by an object-storage lifecycle rule — their permanent home is the site's own media library. That expiry is by design, so it is a `404` and not a `500`. Requires `sites.view`.","tags":["ai"],"responses":{"200":{"description":"The image bytes.","content":{"image/*":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/status/subscribe":{"post":{"operationId":"subscribeToStatusPage","summary":"Ask for email updates from the public status page.","description":"docs/121. Unauthenticated — a prospect subscribing has no account.\n\n⛔ **Double opt-in.** The address receives exactly one thing until it confirms: its own confirmation link. Anyone can type anyone's address into a public form, and single opt-in would make this endpoint a way to mail strangers from our domain.\n\n⛔ The response is identical whether or not the address is already known. Confirming that a given address is on the list would be an enumeration oracle, and this list contains prospects and journalists. Rate limited per client.","tags":["public"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusSubscribeRequest"}}}},"responses":{"202":{"description":"Accepted. A confirmation is on its way if the address can receive mail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusSubscribeResult"}}}},"422":{"description":"Not a usable email address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many attempts from this client.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/public/signup":{"post":{"operationId":"startSignup","summary":"Start an in-app sign-up by mailing a confirm link.","description":"docs/576 §9. Unauthenticated (no permission: the person has no account yet), so it is throttled per trusted client (`signup_start`, 10/hour) on top of a per-address mail budget (one mail per 60 s, five per hour).\n\n⛔ **No enumeration.** The answer is the same `202` whether or not the address already has an account. A known address with a password is mailed \"you already have an account, sign in or reset your password\"; any other address is mailed our branded link to `/signup/verify?token=…`, valid for 48 hours. No Keycloak user is created until the password is chosen (`completeSignup`).\n\nA disposable or invalid address is refused with `403 SIGNUP_EMAIL_REFUSED`, the same refusal the Keycloak form path gets at its first sign-in (docs/1174). When the address looks like a mistyped domain (\"gamil.com\") the refusal also carries `details[0] = {field: email, code: EMAIL_POSSIBLE_TYPO, suggestion}` (EMAILTYPO).","tags":["public"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupStartRequest"}}}},"responses":{"202":{"description":"Accepted. A mail is on its way if the address can receive one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupAccepted"}}}},"403":{"description":"The address is refused (`SIGNUP_EMAIL_REFUSED`). For a likely typo in the domain, `details[0].code` is `EMAIL_POSSIBLE_TYPO` and `details[0].suggestion` is the same address on the domain the validator suggested (\"ann@gmail.com\" for \"ann@gamil.com\"), which the page offers as a one-click fix (EMAILTYPO, docs/1174 §1b3).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/public/signup/verify":{"post":{"operationId":"inspectSignup","summary":"Read what state a sign-up link is in.","description":"docs/576 §9. Unauthenticated (no permission: the token is the credential), throttled per trusted client (`signup_token`, 60/hour). `POST`, not `GET ?token=`, so the token stays out of access logs and referrers. Reading never consumes the link.","tags":["public"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupTokenRequest"}}}},"responses":{"200":{"description":"The link's state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupLinkState"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/public/signup/resend":{"post":{"operationId":"resendSignup","summary":"Mail a fresh sign-up link, including from an expired one.","description":"docs/576 §9. Unauthenticated (no permission: the token is the credential), throttled per trusted client (`signup_token`) and by the same per-address mail budget as `startSignup`. ⭐ Works for an EXPIRED link: an expired link's page always offers \"Send me a new link\". A used or unknown token is a `409` whose `details[0].code` is `USED` or `INVALID`.","tags":["public"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupTokenRequest"}}}},"responses":{"202":{"description":"Accepted. A fresh link is on its way.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupAccepted"}}}},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/public/signup/complete":{"post":{"operationId":"completeSignup","summary":"Choose the password and finish the sign-up.","description":"docs/576 §9. Unauthenticated (no permission: the token is the credential), throttled per trusted client (`signup_token`). A valid, unused link is claimed atomically, the account is created with its address already verified, and a single-use sign-in URL (about two minutes) is returned that lands the person in the dashboard.\n\n`409` with `details[0].code` `EXPIRED`, `USED` or `INVALID` for a link that cannot be used; `409 ACCOUNT_EXISTS` when the address already has a password; `422` with `details[0].field = password` when the password policy refuses it (at least 12 characters, not the username, not the address).","tags":["public"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupCompleteRequest"}}}},"responses":{"200":{"description":"The account exists; follow `sign_in_url`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupCompleted"}}}},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/public/status/confirm":{"get":{"operationId":"confirmStatusSubscription","summary":"Confirm an email subscription to the status page.","description":"The target of the link in the confirmation email. The status page proxies this so the reader lands back on the page rather than on a JSON body.","tags":["public"],"security":[],"parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Confirmed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusSubscribeResult"}}}},"404":{"description":"No such token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/public/status/unsubscribe":{"get":{"operationId":"unsubscribeFromStatusPage","summary":"Stop receiving status emails.","description":"The target of the unsubscribe link carried by every status email.\n\n⛔ Always **200**, whether or not the token matched. An unsubscribe link clicked twice — or prefetched by a mail client — must never show somebody an error about their own withdrawal, and a 404 would confirm which tokens are real.","tags":["public"],"security":[],"parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Unsubscribed (or already were).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusSubscribeResult"}}}}}}},"/v1/wordpress/sites":{"get":{"operationId":"listWordPressSites","summary":"List every WordPress site the caller owns, across all product lines.","description":"The fleet manager's list: every `wordpress` or `woocommerce` site in the caller's tenancy subtree, on every product line and every deploy target (own fleet, managed shared, managed cloud, CloudLinux), with each one's stored WordPress posture.\n\n⛔ **This endpoint never calls a vendor**, however stale a row is. Collecting is `refreshWordPressSite`, an explicit act; a row that has never been collected reports `update_state: unknown` with a null `snapshot`, and the client renders that as *\"not checked yet\"* — **never** as \"up to date\". Those are different sentences and a customer acts differently on each.\n\n`update_state` and `needs_attention` are applied **after** pagination, because the state is derived from four snapshot columns with an explicit precedence and re-expressing that precedence in SQL would give this list and `getWordPressFleetOverview` two implementations of one rule. A filtered page can therefore be short; the totals come from the overview, which counts everything.\n\nRequires `sites.view`.","tags":["hosting"],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Narrow to one organisation in the caller's subtree. Equivalent to the `X-Zinn-Org` header, which is now read centrally for every org-scoped operation — this parameter wins where both are sent. An org outside the readable scope narrows to nothing rather than 403-ing, so it can only ever narrow."},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Substring match on the primary domain."},{"name":"product_line","in":"query","required":false,"schema":{"type":"string"}},{"name":"deploy_target","in":"query","required":false,"schema":{"type":"string"}},{"name":"update_state","in":"query","required":false,"schema":{"$ref":"#/components/schemas/WordPressUpdateState"},"description":"`422` on an unrecognised value rather than silently returning everything — a filter that quietly does nothing is how a customer concludes their estate is clean."},{"name":"needs_attention","in":"query","required":false,"schema":{"type":"boolean"},"description":"Only sites with a core or component update waiting, no WordPress installed, or a homepage that is not answering."},{"name":"health","in":"query","required":false,"schema":{"type":"string","enum":["","healthy","unhealthy"]},"description":"Filter by the stored health verdict. ⭐ Applied **in the database**, unlike `update_state` — `health_status` is one indexed column written by one function, so there is no precedence rule to re-express in SQL, and a filtered page comes back full rather than short.\n\n⛔ The empty string means **not yet checked**, and it matches a site with no snapshot row at all as well as one whose snapshot predates health assessment. A filter matching only the second would answer \"0 unchecked\" about an estate where nothing had ever been checked. `422` on any other value."}],"responses":{"200":{"description":"One page of the caller's WordPress estate.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"type":"object","required":["data","page"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WordPressFleetSite"}},"page":{"$ref":"#/components/schemas/PageMeta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/wordpress/overview":{"get":{"operationId":"getWordPressFleetOverview","summary":"Count the caller's whole WordPress estate by posture.","description":"The manager's tiles, counted over **every** site in scope rather than over the current page. ⛔ A tile derived from one page would read *\"3 sites need attention\"* and mean *\"3 on this page\"*, which is the reading a customer will not make.\n\n`never_collected` is reported separately from `unknown` on purpose: the first is *\"nobody has ever asked this site\"*, the second also covers *\"we asked and the platform declined to say\"*. Requires `sites.view`.","tags":["hosting"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Narrow to one organisation in the caller's subtree. Equivalent to the `X-Zinn-Org` header, which is now read centrally for every org-scoped operation — this parameter wins where both are sent. An org outside the readable scope narrows to nothing rather than 403-ing, so it can only ever narrow."}],"responses":{"200":{"description":"The estate's posture.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WordPressFleetOverview"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/wordpress/templates":{"get":{"operationId":"listWordPressTemplates","summary":"List the WordPress templates a customer may apply.","description":"The published `Blueprint` versions for the product lines the caller actually has WordPress sites on. ⛔ The **existing** blueprint, not a second \"template\" concept: a platform with two answers to *\"what is this site made of\"* has neither.\n\nDrafts are excluded — an unpublished blueprint's spec is still editable, so offering one would let the thing the customer applied change afterwards. Each row carries the plugin slugs the template declares, so a customer can see what applying it will put on their site **before** they apply it. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The templates available to this caller.","content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WordPressTemplate"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/wordpress/sets":{"get":{"operationId":"listWordPressSets","summary":"List the caller's saved WordPress plugin/theme sets.","description":"A set is a named list of WordPress.org plugin slugs plus an optional theme that a customer saves once and installs on any number of their sites (Softaculous / Plesk \"sets\" parity, docs/1135 §Sets). Applying a set is the existing bulk-job flow (`plugin_install`, `theme_install`), so a set is never a cheaper door than picking the same plugins by hand. Postgres only, no vendor call. Requires `sites.view`.","tags":["hosting"],"parameters":[{"name":"org_id","in":"query","required":false,"description":"Narrow to one org in the caller's scope (also the `X-Zinn-Org` header).","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The sets in scope, by name.","content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WordPressSet"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createWordPressSet","summary":"Save a new WordPress plugin/theme set.","description":"⛔ A slug is **refused, never sanitised**: letters, digits, hyphens and underscores, never a leading hyphen (a wp-cli flag). Slugs are lower-cased and de-duplicated in order. A set holds at most 50 plugins, an org at most 100 sets, names are unique per org, and a set must hold at least one plugin or a theme. The org is the one the request names (`org_id` body field or `X-Zinn-Org`), else the caller's only org. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WordPressSetWrite"}}}},"responses":{"201":{"description":"The saved set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WordPressSet"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/wordpress/sets/{setId}":{"parameters":[{"name":"setId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"operationId":"updateWordPressSet","summary":"Change a saved set. Only the fields sent change.","description":"Same validation as `createWordPressSet`. Another org's set is a `404`, never a `403`. Requires `sites.view` and `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WordPressSetWrite"}}}},"responses":{"200":{"description":"The changed set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WordPressSet"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"delete":{"operationId":"deleteWordPressSet","summary":"Delete a saved set. Sites it was applied to keep their plugins.","tags":["hosting"],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/wordpress/refresh":{"post":{"operationId":"refreshWordPressSites","summary":"Collect a named handful of sites in one call.","description":"Collects up to 25 sites' WordPress posture from their platforms. ⛔ Capped because each site is a real vendor conversation, and a customer with four hundred sites pressing *\"refresh everything\"* must not be able to turn their own screen into a rate-limit incident.\n\n⛔ **One site's failure never fails the call.** The response reports per site, because the interesting answer on an estate is usually *\"eleven collected and one refused, here is which\"* — and a 4xx for the whole batch would hide it. A site outside the caller's scope comes back `skipped`, never `404`, so this can never confirm whether a foreign site id exists.\n\nRequires `sites.view` **and** `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["site_ids"],"additionalProperties":false,"properties":{"site_ids":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"string","format":"uuid"}}}}}}},"responses":{"200":{"description":"One result per requested site.","content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WordPressRefreshResult"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/wordpress/sites/{siteId}":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getWordPressFleetSite","summary":"One WordPress site's stored posture, with its component listings.","description":"The same row `listWordPressSites` returns, plus the stored plugin, theme and administrator listings the manager's detail drawer shows. Still Postgres only — the listings are whatever the last collection stored, with `snapshot.collected_at` beside them so the age is visible.\n\n`404` for a site outside the caller's scope **and** for one that does not run WordPress — a 403 would confirm the id exists. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The site's stored WordPress posture.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WordPressFleetSiteDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/wordpress/sites/{siteId}/refresh":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"refreshWordPressSite","summary":"Ask this site's platform for its WordPress posture now.","description":"Collects core version, plugins, themes, administrators, enforced disk quota and a **cache-busted request to the site's own homepage**, then stores and returns them.\n\n⛔ **Every read is independent.** A platform that answers the install call and refuses the user list produces a snapshot with a core version and no administrators — not an empty row. And a failed collection **keeps the previous figures**, recording `snapshot.collect_error_code` beside them: *\"what we knew four hours ago, and why we could not refresh it\"* is a better answer than a blanked screen, provided the screen says which it is showing.\n\n⛔ `sites.panel_access`, not merely `sites.view`: this commissions real vendor work against a customer's site, and a read permission should not be able to spend somebody else's rate limit.","tags":["hosting"],"responses":{"200":{"description":"The freshly collected posture.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WordPressFleetSiteDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/wordpress/sites/{siteId}/credentials":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getWordPressSiteCredentials","summary":"Who can sign in to this site's WordPress, and where.","description":"The site's WordPress administrators — read **live** from the platform, not from the stored snapshot, because this list is what the rotate form acts on and offering a password reset for a user deleted an hour ago fails confusingly. A stale list is fine on a dashboard and wrong on a form.\n\n⛔⛔ **There is no `password` field and there cannot be one.** WordPress stores a hash; no plaintext exists on our side or theirs. A customer copies the *username* from here and, if they need a password, mints a new one with `rotateWordPressAdminPassword`. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The site's WordPress administrators and its wp-admin URL.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WordPressSiteCredentials"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/wordpress/sites/{siteId}/credentials/rotate":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"rotateWordPressAdminPassword","summary":"Set a new password on one WordPress administrator, shown once.","description":"Generates a 24-character password, applies it to the named WordPress administrator, and returns it in this response and **nowhere else** — it is not stored, not written to the snapshot, and not put in the audit record, which says a rotation happened and never what to.\n\n⛔ A user id that is not an administrator of this site is `422`. Without that check the endpoint would reset any WordPress account's password through a door labelled *administrators*.\n\nRequires `sites.view` **and** `sites.panel_access`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user_id"],"additionalProperties":false,"properties":{"user_id":{"type":"string","description":"The WordPress user id, from `getWordPressSiteCredentials`."}}}}}},"responses":{"200":{"description":"The new password. Shown once; it is stored nowhere.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WordPressRotatedPassword"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ProviderNotConfigured"}}}},"/v1/bulk-jobs/preview":{"post":{"operationId":"previewBulkJob","tags":["hosting"],"summary":"What a bulk job would do, per site, before you confirm it.","description":"Resolves a selection and answers **per site** whether the operation can run on it and, if not, why.\n\n⭐⭐ The counts come from the *same query the job will run*, so the number you confirm cannot drift from the number that executes. A count computed a different way would be decoration.\n\n⭐ A count alone would hide the thing that actually surprises people: six of your twelve sites may be on a platform with no shell and no `wp-cli`, so they physically cannot take an install. Learning that from the report afterwards is learning it too late, which is why `sites[]` carries a `reason` for every ineligible one.\n\n⛔ `POST` for a **read**. Nothing is written and nothing is started. The verb is a transport decision: an explicit selection of several hundred site ids does not fit in a query string that proxies, browsers and access logs will truncate or record. Do not \"correct\" it to `GET`.\n\nRequires `sites.view`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkJobRequest"}}}},"responses":{"200":{"description":"What the selection matches, and what would happen to each site.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkJobPreview"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/bulk-site-imports/template":{"get":{"operationId":"getBulkSiteImportTemplate","tags":["hosting"],"summary":"The columns, allowed values and example file for Add many sites.","description":"s1014 BULKUPLOAD. The single source of the upload format: the deploy form's \"Many sites\" mode renders its \"Download example CSV\" button and its instructions table from this, so the example file is by construction one the importer accepts. Requires `sites.create`.","responses":{"200":{"description":"The upload format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkSiteImportTemplate"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/bulk-site-imports/preview":{"post":{"operationId":"previewBulkSiteImport","tags":["hosting"],"summary":"Check every row of a site file before anything is created.","description":"Parses the rows (CSV; comma, semicolon or tab; a header row naming the columns, or no header and the columns in the template's order, so a pasted list of domains works) over the batch `defaults`, and answers per row what is wrong with it, by column: field validation by the one-site create path's own rules, an unknown site type, an unknown CDN, an own CDN account that is not connected (or not acknowledged on a platform-managed line), duplicates inside the file, a domain that is already one of the account's sites, and rows past the plan's remaining site slots. Nothing is written. A file that cannot be read at all comes back as `file_error` with a `200`, so the screen can say why. ⛔ `POST` for a read: a file does not fit in a query string. Requires `sites.create`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkSiteImportRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/BulkSiteImportUpload"}}}},"responses":{"200":{"description":"Every row and what is wrong with it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkSiteImportPreview"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/bulk-site-imports":{"post":{"operationId":"createBulkSiteImport","tags":["hosting"],"summary":"Add many sites — one per valid row of a file.","description":"Re-checks the file exactly as the preview does and enrols every VALID row as an item of a `site_create` bulk job; invalid rows are left out (the preview named them). Each row is then created through the same path as `POST /v1/sites`, so the site-slot quota, plan allowances and hostname rules apply per row. Refused with a `422` before anything is written when no row is valid or the file cannot be read; rows past the plan's room are flagged by the check and not enrolled. One durable job with bounded concurrency and no row cap: the bound is the quota. Follow progress with `GET /v1/bulk-jobs/{bulkJobId}`. Requires `sites.create`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkSiteImportRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/BulkSiteImportUpload"}}}},"responses":{"202":{"description":"The job was created and is running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkJob"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/bulk-jobs":{"get":{"operationId":"listBulkJobs","tags":["hosting"],"summary":"Your bulk jobs, newest first.","description":"Every bulk job for the organizations you can see, with its per-status counts. The counts are the summary; `getBulkJob` carries the per-site report that says *which* sites missed it and why. Requires `sites.view`.","parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"A page of bulk jobs with their per-status counts.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BulkJob"}},"page":{"$ref":"#/components/schemas/PageMeta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createBulkJob","tags":["hosting"],"summary":"Run one operation across many sites.","description":"Freezes the selection into a per-site work-list and starts a durable, idempotent workflow. **The submit is instant and the work is not** — this returns `202` as soon as the rows are written, and nothing a person is watching waits on the job itself.\n\nOnly **eligible** sites are enrolled; ineligible ones are not written as pre-failed rows, because a report padded with rows that never had a chance makes the failures that matter harder to find. `previewBulkJob` is where you see them.\n\nA selection that enrolls **nothing** is a `422`, not a job that completes instantly: \"completed, 0 of 0\" is indistinguishable from success on every screen that renders it.\n\n⛔ A typed `confirm` phrase is required when the selector is wider than an explicit list (`product_line`, `org`) **or** the operation is weighty (`plugin_remove`, `plugin_deactivate`, `blueprint_apply`) at any size. `previewBulkJob` returns the exact phrase in `confirmation_phrase`.\n\n⛔ All the selected sites must belong to **one** organization. A mixed selection is a `422` naming the problem rather than a job whose owner is a guess.\n\n⛔ Every operation here is a **WordPress** operation, so the selection must be WordPress. An explicit `sites` list holding even one non-WordPress site (static, Node, LLM) is a `422` with `refusal.bulk.selectionHasNonWordPress`; a wider selector (`product_line`, `org`, `group`) that resolves to no WordPress site at all is a `422` with `refusal.bulk.selectionNoWordPress`. A wider selector mixing both is accepted and only its WordPress sites are enrolled.\n\nRequires `sites.view` plus the operation's own key (see the tag description).","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkJobCreate"}}}},"responses":{"202":{"description":"The job was accepted and started; its rows are already written.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkJob"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/bulk-jobs/{bulkJobId}":{"parameters":[{"$ref":"#/components/parameters/BulkJobId"}],"get":{"operationId":"getBulkJob","tags":["hosting"],"summary":"One bulk job and its per-site report.","description":"⭐ The per-site rows are the feature. A job that reported only a count could not answer *\"which of my sites missed it, and why?\"*, and a bulk action whose failures are invisible is worse than none, because it is believed.\n\nA cheap database read, polled while a job is in flight, so it never describes a workflow and never calls a hosting adapter. Requires `sites.view`.","responses":{"200":{"description":"The job, its counts, and one row per site.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkJobDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/bulk-jobs/{bulkJobId}/retry-failed":{"parameters":[{"$ref":"#/components/parameters/BulkJobId"}],"post":{"operationId":"retryBulkJobFailures","tags":["hosting"],"summary":"Run a bulk job's failures again.","description":"Puts the `failed` and `skipped` items back to `pending` and restarts the job's workflow.\n\n⭐ `unsupported` items are **not** reopened, and that is deliberate: a platform with no shell will not grow one because somebody pressed a button, so a retry that provably does nothing is how a control stops being believed.\n\nA job that is still running is a `409` — the restart reuses the job's own workflow id, so this cannot start a second pass over the same rows. A job with nothing left to retry is a `422`. Requires `sites.view` plus the operation's own key.","responses":{"202":{"description":"The failures were reopened and the job restarted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkJob"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/bulk-jobs/installed-plugins":{"post":{"operationId":"surveyBulkInstalledPlugins","tags":["hosting"],"summary":"What is already installed across a bulk selection.","description":"The candidate list for `plugin_activate`, `plugin_deactivate`, `plugin_remove` and `plugin_update` — read from the **sites themselves**, not from the wordpress.org directory. Installing picks from what could go on; activating picks from what is already there, and those are different questions.\n\n**POST, and it writes nothing.** Same reason as `previewBulkJob` beside it: an explicit selection of 400 site ids does not survive a query string that proxies, browsers and access logs will truncate or record. No row is written and no job is started.\n\n⛔ **This is one network call per site, so it reads a bounded SAMPLE and says so.** `matched` counts the whole selection, `eligible` counts the ones that could take the operation, and `read` counts the ones actually listed — three separate numbers, because a blind version of this endpoint would return `read: 0`, which must never be readable as *\"nothing is installed\"*. Sites that could not be reached are named in `unreadable` rather than dropped into a shorter list that looks complete.\n\n`uniform` is `false` when the read sites do not all carry the same plugins, so the screen can say that plainly instead of silently acting on a subset.\n\nRequires `sites.view` plus the operation's own key — never a cheaper door than the single-site listing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkInstalledPluginsRequest"}}}},"responses":{"200":{"description":"The aggregated listing.","headers":{"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkInstalledPlugins"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/retry-provisioning":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"retrySiteProvisioning","tags":["hosting"],"summary":"Build a failed site again.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteProvisioningRetryRequest"}}}},"description":"Re-runs provisioning for a site whose build failed or never started. The transition `failed -> provisioning` has always been legal and the status enum's own comment says *\"retry or delete\"* — this is the door.\n\n**Idempotent, and pressing it twice is a success.** A site that is already `provisioning` answers `202` with `restarted: false` rather than a `409`: a customer pressing a button twice has not made an error. Three independent mechanisms make that safe — the workflow id is derived from the site id, the start policy is `ALLOW_DUPLICATE_FAILED_ONLY` so a completed provision can never be re-run, and the status transition locks and re-reads the row.\n\n**Another network, same click (R42).** When a DNS or CDN provider refused the domain (`Site.provider_refusal`), the body names the network to rebuild on; the site's provider placements are released so it is placed afresh on that vendor.\n\n⛔ Nothing here calls Temporal (§2.9). The status change and a `site.created` event commit in one transaction and the existing consumer starts the workflow, so a Temporal outage cannot leave the row half-moved.\n\nA site that is `active`, `deleting` or `deleted` is a `422` — a retry re-runs the build, and those are past it. Requires `sites.view` and `hosting.deploy.manage`. A site that publishes DNS on the customer's own account (`use_own_dns`) runs the same own-DNS pre-flight a create runs before it rebuilds: a failing verdict is a `422` with `refusal.ownDns.*` naming the fix (for example the token permission it lacks), and the site does not move.\n\n**Row 45 (s1014).** A `provisioning` site past its measured p90 is STALLED: Retry terminates the old run and starts afresh (row-locked, so a double press starts one workflow; the second answers `refusal: in_flight`). A `failed` site is refused with `422` (`refusal.sites.retryCoolingDown`) for 3 minutes after the failure, and (`refusal.sites.retryNotInGoodStanding`) when the account is not in good standing - exactly when `Site.install.retry.enabled` is `false`.","responses":{"202":{"description":"The build was queued, or was already running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteProvisioningRetry"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/application-reinstall":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteApplicationReinstall","tags":["hosting"],"summary":"Whether this site's PHP application can be reinstalled, and the latest run.","description":"MOODLEOPS-r26 (docs/557 §11). The card's one read: which modes are offered (`keep_database` only where the application can reconnect new files to its existing tables) and the latest reinstall with its outcome. Requires `sites.view`. `503` when the workflow engine cannot be asked — \"could not ask\" never reads as \"never ran\".","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The reinstall surface for this site.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteApplicationReinstall"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"post":{"operationId":"startSiteApplicationReinstall","tags":["hosting"],"summary":"Reinstall an active site's PHP application, after backing it up.","description":"Rebuilds an `active` PHP application site (any application, not only Moodle) — the door for a site whose files are gone, which `retrySiteProvisioning` (failed or pending sites only) cannot reach. The site's domain must be typed in `confirm_domain`.\n\n**The database and the files are ALWAYS backed up first** into a root-only store on the server, read back (every table in the dump, the archive passes `gzip -t`), and only then cleared. `keep_database` lays down fresh files and reconnects them to the existing tables; `fresh` also clears the application's data directory and tables and installs from nothing. The request is queued through the transactional outbox and a consumer starts the Temporal workflow (one per site, so a press while one is running is absorbed by it): a workflow-engine outage delays a reinstall and never fails this request. The moment it is queued this answers `202`; follow it on the `GET`. With `keep_database` Moodle's own non-interactive upgrade then brings the kept database up to the new release. Audit-logged (`site.application.reinstall_requested`, then `site.application.reinstalled` or `site.application.reinstall_failed`). Requires `sites.view` and `hosting.deploy.manage`.\n\n`422` with a refusal key: `refusal.sites.reinstallConfirmMismatch`, `reinstallNotActive`, `reinstallNotPhpApp`, `reinstallNoApplication`, `reinstallNotOnFleet`, `reinstallKeepDatabaseUnsupported`, `reinstallBadMode`.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteApplicationReinstallRequest"}}}},"responses":{"202":{"description":"The reinstall request is durably queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteApplicationReinstallStart"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{siteId}/install-progress":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteInstallProgress","tags":["hosting"],"summary":"The installing screen's live stage, measured timing and Retry validity.","description":"Row 45 (s1014, owner 2026-10-29). `install` is the same answer `retrySiteProvisioning` enforces; `step` is the running workflow's own progress answer, asked only while the site is installing and `null` when it cannot be asked (a Temporal fault degrades the field, never the response). Requires `sites.view`.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The site's install progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteInstallProgress"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/campaigns/segments":{"parameters":[{"name":"org_id","in":"query","required":false,"description":"Which organization's campaigns to work on. Required only when you hold campaign access on more than one; staff always work on the platform scope and may omit it.","schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listCampaignSegments","summary":"Your saved audience segments.","description":"The segment library. Active segments by default; pass `status=archived` for the rest.\n\nA segment is never deleted, only archived — a campaign that has already been sent references the segment it was sent to, and deleting the row would erase the answer to \"who did we mail?\", which is the one question a complaint or an audit asks.","tags":["campaigns"],"responses":{"200":{"description":"One row per segment.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CampaignSegment"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createCampaignSegment","summary":"Save a new audience segment.","description":"The `definition` is a filter tree over the fields `GET /v1/campaigns/segments/fields` lists, and is validated on write — a definition that cannot be compiled cannot be stored, so a saved segment never explodes at send time in front of an operator who has already scheduled it.\n\n⛔ An empty group (`{\"op\":\"and\",\"children\":[]}`) is refused rather than treated as \"everybody\": a half-built segment must not silently mean the entire estate.","tags":["campaigns"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignSegmentWrite"}}}},"responses":{"201":{"description":"The stored segment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignSegment"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/campaigns/segments/fields":{"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getCampaignSegmentFields","summary":"The filter vocabulary, its value lists and the magic tags.","description":"Everything a segment builder needs to render itself: the filterable fields with their operators and a hint each, the live value lists for the `choice` fields, and the merge tags a template may use.\n\nThe value lists are restricted to your own population — a reseller's country picker lists the countries their clients are actually in, not every country the platform sells into.","tags":["campaigns"],"responses":{"200":{"description":"The vocabulary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignSegmentFields"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/campaigns/segments/preview":{"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"previewCampaignSegment","summary":"How many people this reaches, who they are, and who it leaves out.","description":"Pass either a `definition` (to preview an unsaved segment as you build it) or a `segment_id` — exactly one.\n\n⛔ `total` is the TRUE recipient count and `sample` is a bounded illustration of it. They are different numbers and `truncated` says when: an operator who reads the sample size as the audience size sends thousands of emails believing they sent twenty.\n\nEvery response carries all five skip counters whether or not any is non-zero, because a counter that disappears when it is zero is indistinguishable from a fence that never ran. `skipped_no_marketing_consent` will be large today: marketing is soft opt-in for people who are or were customers, and anyone else needs an explicit opt-in.","tags":["campaigns"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignSegmentPreviewRequest"}}}},"responses":{"200":{"description":"The counts and a sample.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignSegmentPreview"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/campaigns/segments/{segmentId}":{"parameters":[{"name":"segmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getCampaignSegment","summary":"One saved segment.","description":"The segment as stored, including the filter tree. `scope` says who it may reach and cannot be changed after creation.","tags":["campaigns"],"responses":{"200":{"description":"The segment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignSegment"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"operationId":"updateCampaignSegment","summary":"Rename a segment or change its filters.","description":"`scope` is absent from the body and cannot be changed: a segment reviewed and approved as \"my clients\" must not silently become \"the estate\".","tags":["campaigns"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignSegmentWrite"}}}},"responses":{"200":{"description":"The segment as it now reads.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignSegment"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"archiveCampaignSegment","summary":"Archive a segment.","description":"Hidden from the picker and kept. See `GET` above for why nothing here is deleted.","tags":["campaigns"],"responses":{"200":{"description":"The archived segment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignSegment"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/campaigns/suppressions":{"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listCampaignSuppressions","summary":"Addresses that must not receive marketing.","description":"Your own list AND the platform-wide deliverability list, each row labelled with which.\n\nA hard bounce or a spam complaint is a fact about the ADDRESS and applies everywhere — continuing to mail one destroys the sending domain's reputation for everybody on it. An unsubscribe is the customer's own decision and applies only to the sender they left.","tags":["campaigns"],"responses":{"200":{"description":"One row per suppressed address.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CampaignSuppression"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createCampaignSuppression","summary":"Add an address to the suppression list.","description":"`unsubscribed` applies to your own campaigns. `bounced`, `complained` and `staff_blocked` are facts about the ADDRESS and are stored platform-wide whatever scope you send them under — continuing to mail a hard bounce damages delivery for every other customer sending from the same domain.\n\nIdempotent on `(scope, address, purpose)`.","tags":["campaigns"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["email","reason"],"properties":{"email":{"type":"string","format":"email"},"reason":{"type":"string","enum":["unsubscribed","bounced","complained","staff_blocked"]},"note":{"type":"string","maxLength":500}}}}}},"responses":{"201":{"description":"The stored suppression.","content":{"application/json":{"schema":{"type":"object","required":["id","email","reason"],"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"reason":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/campaigns/unsubscribe":{"post":{"operationId":"unsubscribeFromCampaigns","summary":"Leave a marketing list. No account needed.","description":"The link in the footer of every marketing message, and the target of the one-click `List-Unsubscribe-Post` header (RFC 8058).\n\n⛔ Deliberately unauthenticated: somebody leaving a marketing list has no reason to sign in first, and a one-click unsubscribe is submitted by the mail client itself with no session at all. The authorization is the SIGNATURE on the token, which names the address it may act on, so it cannot be replayed against anybody else. Nothing is read from the request beyond the token.\n\nThe token does not expire. A message read a year later must still unsubscribe.\n\nAlways `200` for a validly-signed token, including one naming an address we have never seen — distinguishing the two would make this an address-enumeration oracle, and the outcome is identical either way.","tags":["campaigns"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["token"],"properties":{"token":{"type":"string","maxLength":2048}}}}}},"responses":{"200":{"description":"Removed.","content":{"application/json":{"schema":{"type":"object","required":["unsubscribed","email","purpose","at"],"properties":{"unsubscribed":{"type":"boolean"},"email":{"type":"string"},"purpose":{"type":"string"},"at":{"type":"string","format":"date-time"}}}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/campaigns":{"get":{"operationId":"listCampaigns","summary":"The organisation's campaigns.","description":"Every campaign this organisation owns, newest first, with its status and its delivery counts. Counts are present even at zero, so a caller can tell 'none yet' from 'not reported'.","tags":["Campaigns"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"responses":{"200":{"description":"Campaigns, newest first.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["campaigns"],"properties":{"campaigns":{"type":"array","items":{"$ref":"#/components/schemas/Campaign"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createCampaign","summary":"Create a campaign from a template and an audience.","description":"Create a campaign from a template and an audience segment. It is created as a draft and sends nothing until the send endpoint is called.","tags":["Campaigns"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignInput"}}}},"responses":{"201":{"description":"The campaign, in draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/campaigns/esp":{"get":{"operationId":"getEspConnection","summary":"The organisation's own e-mail provider account.","description":"Never returns the API key or its Vault path — only the state of the connection and its lifetime delivery counters.\n","tags":["Campaigns"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"responses":{"200":{"description":"The connection, or a named \"not connected\" state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EspConnection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"connectEsp","summary":"Connect an e-mail provider account.","description":"The key is written to Vault and never to the database. Connecting resets the connection to unverified — a new key behind an old \"verified\" badge is a connection claiming a proof it does not have.\n","tags":["Campaigns"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EspConnectionInput"}}}},"responses":{"201":{"description":"The connection, unverified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EspConnection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"delete":{"operationId":"disconnectEsp","summary":"Disconnect the provider account and remove its stored key.","description":"Forget this organisation's e-mail provider. The stored key is removed from Vault, not merely hidden — and campaigns refuse to send until a provider is connected again.","tags":["Campaigns"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"responses":{"200":{"description":"The connection is gone.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EspConnection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/campaigns/esp/verify":{"post":{"operationId":"verifyEspConnection","summary":"Prove the provider account works and read its verified domains.","description":"A real call to the provider. Configured is not proved — a connection is unusable until this has succeeded, and the response distinguishes \"not connected\" from \"unverified\" from \"rejected\" so the operator knows which one they are in.\n","tags":["Campaigns"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"The connection as it now stands.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EspConnection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/campaigns/preview":{"post":{"operationId":"previewCampaignTemplate","summary":"Render a template with example values.","description":"Rendered by the engine, through the same renderer the send uses. A preview computed in the client is a second implementation of the substitution rules, and the first time it disagrees an author ships copy they never actually saw.\n","tags":["Campaigns"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignTemplateInput"}}}},"responses":{"200":{"description":"The rendered message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignPreview"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/campaigns/tags":{"get":{"operationId":"listCampaignTags","summary":"The magic-tag palette a campaign composer offers.","description":"Served by the engine rather than duplicated in the client: the per-tag fallback is the thing this feature is judged on (\"Hi ,\" is the failure), and two copies of the list would drift the first time somebody added one.\n","tags":["Campaigns"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"responses":{"200":{"description":"Every tag an author may type.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["tags"],"properties":{"tags":{"type":"array","items":{"$ref":"#/components/schemas/CampaignTag"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/campaigns/templates":{"get":{"operationId":"listCampaignTemplates","summary":"The organisation's campaign templates.","description":"Every reusable message template this organisation owns, newest first. A template carries the subject, the body with its magic tags, the purpose and the channels it may be sent on.","tags":["Campaigns"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"responses":{"200":{"description":"Templates, most recently edited first.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["templates"],"properties":{"templates":{"type":"array","items":{"$ref":"#/components/schemas/CampaignTemplate"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createCampaignTemplate","summary":"Author a campaign template.","description":"The copy enters the auto-translation lifecycle in the same call, so a template is never English-only even for an hour. An unknown magic tag is refused here rather than at send time, because a typo found while sending has no undo.\n","tags":["Campaigns"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignTemplateInput"}}}},"responses":{"201":{"description":"The template as stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignTemplate"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/campaigns/templates/{templateId}":{"parameters":[{"name":"templateId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getCampaignTemplate","summary":"One campaign template.","description":"One template, including its rendered magic-tag list so an editor can show which values a send will substitute and what each one falls back to.","tags":["Campaigns"],"responses":{"200":{"description":"The template.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignTemplate"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"operationId":"updateCampaignTemplate","summary":"Edit a campaign template.","description":"Editing the copy marks every locale stale and re-translates it, so a template and its 58 translations cannot drift.\n","tags":["Campaigns"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignTemplateInput"}}}},"responses":{"200":{"description":"The template as it now reads.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignTemplate"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"archiveCampaignTemplate","summary":"Archive a template and retire its translation sources.","description":"Archived rather than deleted, and its translation sources are retired in the same call — a dead source is not inert, it is `missing`, so the pipeline would go on paying to translate it into 57 languages for a template nobody will send.\n","tags":["Campaigns"],"responses":{"200":{"description":"What was archived and how many sources were retired.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["archived","sources_retired"],"properties":{"archived":{"type":"boolean"},"sources_retired":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/campaigns/{campaignId}":{"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getCampaign","summary":"One campaign and its delivery report.","description":"One campaign with its full delivery report: how many are queued, sent, delivered, bounced, opened, failed and skipped, and why each skip happened.","tags":["Campaigns"],"responses":{"200":{"description":"The campaign, with per-status delivery counts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"operationId":"deleteCampaign","summary":"Delete a campaign and retire its delivery rows.","description":"Delete a draft campaign. A campaign that has started sending cannot be deleted — cancel it instead, so its delivery history survives.","tags":["Campaigns"],"responses":{"200":{"description":"What was deleted.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["deleted","delivery_rows_purged"],"properties":{"deleted":{"type":"boolean"},"delivery_rows_purged":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/campaigns/{campaignId}/control":{"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"controlCampaign","summary":"Pause, resume or cancel a running send.","description":"The decision is written to the database first and signalled second, so a worker that restarted and never saw the signal still stops on its next batch.\n","tags":["Campaigns"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["action"],"properties":{"action":{"type":"string","enum":["pause","resume","cancel"]},"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"The campaign, plus whether the running workflow was reachable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignControlResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/campaigns/{campaignId}/send":{"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"sendCampaign","summary":"Start the durable send.","description":"Returns immediately; the send runs as a Temporal workflow that resumes rather than truncating. A send above the confirmation threshold requires `confirm` to equal the campaign's name exactly — enforced here, because a control that lives only in the client is one an API call walks past.\n","tags":["Campaigns"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"confirm":{"type":"string"},"org_id":{"type":"string","format":"uuid"},"scheduled_for":{"type":"string","format":"date-time","nullable":true,"description":"docs/1000 §3 — send later: a time zone-aware moment more than 2 minutes and at most 90 days ahead. The campaign reads `scheduled` until then (Temporal holds the delay); cancelling it before then stops it without sending."}}}}}},"responses":{"202":{"description":"The send has started (or is scheduled).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/campaigns/{campaignId}/test":{"parameters":[{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"testSendCampaign","summary":"Send one real message on the channel the campaign will actually use.","description":"A real send through the real provider, not a preview. The value of a test send is that it proves the account, the domain, the From header and the rendering all work together — which a preview cannot, because it touches none of them.\n\n⛔ It goes out on the channel the CAMPAIGN uses. A campaign whose channels are `[\"slack\"]` has no account, no domain and no From header to prove, so an e-mailed test would exercise nothing the send would do; it posts to a verified connected destination instead. `to` is therefore required only when the campaign sends by e-mail — for a connected channel the destination is the organisation's own verified connection and is never accepted from the caller.\n","tags":["Campaigns"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"to":{"type":"string","format":"email","description":"Required when the campaign sends by e-mail; ignored otherwise.\n"},"org_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"What was sent, and from where.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignTestSend"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/inbox/read-all":{"post":{"operationId":"markInboxAllRead","summary":"Mark every message in the inbox read.","description":"Mark every message in the signed-in person's inbox as read, and return the new unread count so a caller never has to guess it.","tags":["Inbox"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"responses":{"200":{"description":"How many were newly marked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboxUpdateResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/inbox/threads":{"get":{"operationId":"listInboxThreads","summary":"The inbox — one row per conversation, newest first.","description":"The signed-in person's message threads, newest activity first: campaign messages, support- ticket replies and account notifications in one stream.","tags":["Inbox"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["campaign","ticket","account"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"A page of conversations.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["threads"],"properties":{"threads":{"type":"array","items":{"$ref":"#/components/schemas/InboxThread"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/inbox/threads/{threadKey}":{"parameters":[{"name":"threadKey","in":"path","required":true,"schema":{"type":"string"}}],"get":{"operationId":"getInboxThread","summary":"One conversation, oldest message first.","description":"One thread with its messages in order. Reading a thread does not mark it read — that is a separate, explicit call.","tags":["Inbox"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"responses":{"200":{"description":"The conversation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboxThreadDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"updateInboxThread","summary":"Mark a conversation read, or archive it.","description":"A POST and not a GET, because a read receipt is a write — a GET that mutates is one a prefetcher, a crawler or the back button fires on the customer's behalf.\n","tags":["Inbox"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["action"],"properties":{"action":{"type":"string","enum":["read","archive"]}}}}}},"responses":{"200":{"description":"What changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboxUpdateResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/inbox/unread":{"get":{"operationId":"getInboxUnreadCount","summary":"The number the header badge renders.","description":"Its own endpoint because the header renders on every route: it must stay a bounded index scan. It caps, and it reports WHETHER it capped — a bare number that silently stops at the cap lies at exactly the moment it matters most.\n","tags":["Inbox"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"responses":{"200":{"description":"The unread count.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboxUnread"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/sites/{site_id}/translation":{"parameters":[{"name":"site_id","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"get":{"operationId":"getSiteTranslation","summary":"Whether this site is translated, and how far along it is.","description":"The state of Site Translation for one site: whether it is bought, which tier, how many words and documents we measured, when we last read the site, and per-locale progress.\n\n**A site with no subscription is a `200`, not a `404`.** The screen needs to render the offer, and \"not bought\" is an answer about a site that exists — returning `404` would make a site the customer owns look missing.\n\n`locales[]` reports every language with its own counts, and `served` says whether the customer has switched that language on for visitors. ⛔ `translated` and `served` are separate numbers on purpose: every tier translates every language, so a locale can be 100% translated and reach nobody because its owner has not enabled it. Merging them would report either a coverage figure nobody is served by, or a delivery figure that understates what is ready — the two mistakes `docs/28` was rewritten to stop making.\n\nReadable whether or not the account is in good standing: a customer behind on an invoice may still see what they have already paid for. Requires `sites.view`.","tags":["hosting"],"responses":{"200":{"description":"The site's translation state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteTranslation"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"operationId":"updateSiteTranslation","summary":"Choose which languages this site serves to visitors.","description":"Sets `served_locales` — the languages whose URLs the site publishes.\n\n**This does not buy or spend anything.** Every language is translated already: the tier includes all of them and the words were paid for at extraction, so switching one on is instant and switching one off costs nothing and destroys nothing. It is a publishing decision, not a purchase, which is why it needs `sites.translation.manage` and not a billing scope.\n\n**The site picks the change up on its next sync, not in this request.** The Zinn® Translate plugin reads this list from `getSiteTranslationServed` when it connects and then hourly, so a language switched on here gets its web addresses within the hour. ⛔ Until 2026-09-17 nothing read this column at all and the dashboard said *\"your site is serving those languages now\"* (D26430, D26950).\n\n⛔ An empty list means the site serves **no** translated URLs — it does not mean \"all\". Publishing 57 new indexed URL trees on someone's domain because a field was empty is an SEO event they did not ask for and cannot easily undo.\n\nA locale that is not in the platform's registry is a `422` naming it, never a silent drop: a typo that vanishes is how a customer waits a week for a language they believe they enabled. Requires `sites.translation.manage`.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteTranslationUpdate"}}}},"responses":{"200":{"description":"The updated state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteTranslation"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/sites/{site_id}/translation/refresh":{"post":{"operationId":"refreshSiteTranslation","summary":"Read the site again now, rather than waiting for the next pass.","description":"Re-reads the site's pages and posts and registers anything new or changed. The sweep does this on its own cadence; this is the button for a customer who has just published something and wants it translated now.\n\n**This is a point of spend**, so it asks good standing (`CLAUDE.md` §2.46) and the tier allowance before it reads anything. A `402` means the account is on hold — the body says so and says that it resumes automatically — or that the site now holds more words than the tier covers, with both numbers.\n\nIdempotent in the way that matters: content already registered at the same hash is a no-op that marks nothing stale and translates nothing again, so pressing the button twice costs nothing. Requires `sites.translation.manage`.","tags":["hosting"],"parameters":[{"name":"site_id","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"202":{"description":"The site was read and its content registered. Translation runs afterwards, so this means the words are queued, never that any language is finished.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteTranslationRefresh"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"The account is not in good standing, or the site is larger than its tier covers. The body says which, with the numbers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteTranslationRefresh"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{site_id}/translation/sources":{"post":{"operationId":"submitSiteTranslationSources","summary":"The site tells us every translatable string it has.","description":"The push counterpart of `refreshSiteTranslation`, and it exists because a REST read of a WordPress post returns four fields — title, body, excerpt, slug — and a site is made of far more than that. Product attributes, variation names, category descriptions, menu labels, image alt text and every SEO field Yoast or Rank Math keeps in post meta are invisible to that read, and between them they are most of the words a visitor actually looks at. The Zinn® Translate plugin runs inside WordPress, enumerates all of it, and submits it here.\n\n**This is a point of spend**, so it asks entitlement, good standing (`CLAUDE.md` §2.46) and the tier allowance before registering anything, exactly as the pull path does and through the same helper. A `402` means the account is on hold, or the site holds more words than the tier covers.\n\n**The submission is the complete inventory, not a delta**, and that is load-bearing: anything the site does NOT send is retired (`CLAUDE.md` §2.52), so a deleted page stops being translated instead of being paid for for ever. Sending a partial list therefore deletes the translations of everything you left out. Registration is idempotent at the same content hash, so re-submitting an unchanged site costs nothing. Requires `sites.translation.manage`.","tags":["hosting"],"parameters":[{"name":"site_id","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteTranslationSourceSubmission"}}}},"responses":{"202":{"description":"The inventory was registered. Translation runs afterwards, so this means the words are queued, never that any language is finished.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteTranslationRefresh"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"The account is not in good standing, or the site is larger than its tier covers. The body says which, with the numbers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteTranslationRefresh"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/sites/{site_id}/translation/served":{"get":{"operationId":"getSiteTranslationServed","summary":"The languages this site publishes, for the site itself to follow.","description":"The `served_locales` the customer chose on the site's Translation tab. **The Zinn® Translate plugin publishes exactly this list** when it is connected to a Zinn Digital® plan — it asks when it connects and then hourly, keeps the answer, and never asks during a page load.\n\nA separate read from `getSiteTranslation` on purpose: that payload counts every translation the site has to report per-language progress, and this one is asked hourly by every connected site, so it answers from one row.\n\n⛔ **An empty list means publish none** — never \"all\". A site with no Site Translation answers `200` with `state: disabled` and an empty list rather than a `403`, so the plugin can tell \"publish nothing\" apart from \"could not ask\"; nothing paid for is returned here. Requires `sites.view`, the same scope as the bundle.","tags":["hosting"],"parameters":[{"name":"site_id","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}}],"responses":{"200":{"description":"The languages the site publishes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteTranslationServed"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/sites/{site_id}/translation/bundle/{locale}":{"get":{"operationId":"getSiteTranslationBundle","summary":"One locale of a site's translated content, for the site itself to render.","description":"Every translated string this site has in `locale`, keyed by document. **This is the consumer end of the product**: the Zinn® Translate plugin on the customer's own WordPress site calls it, caches the payload, and swaps titles, bodies, excerpts and slugs at render time.\n\n**Last-good-while-stale, per string.** An entry is returned whenever its text is non-empty, whatever its status: a re-translation in flight must not blank a paragraph that is already live on someone's site. A string with no translation yet is **absent from the payload** rather than present and empty — the plugin then renders the customer's own words, and those two cases mean different things.\n\nReadable without good standing, deliberately: taking a live site's translated pages down over an unpaid invoice is a worse outcome than the invoice, and the customer never agreed to it. It does require a live subscription — a site that never bought this gets a `403`.","tags":["hosting"],"parameters":[{"name":"site_id","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}},{"name":"locale","in":"path","required":true,"description":"The locale to fetch (docs/28 registry code).","schema":{"$ref":"#/components/schemas/LocaleCode"}}],"responses":{"200":{"description":"The site's translated content in this locale.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteTranslationBundle"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/email-marketing":{"get":{"operationId":"getEmailMarketingOverview","tags":["zinn-campaigns"],"summary":"Zinn® Campaigns overview for one organisation.","description":"Gated on `email_marketing.view`. `open` is false while the product is switched off for this account. `contacts_by_status` counts the organisation's contacts per status; `max_import_rows` is the most contacts one import request may carry. Answers for ONE organisation (`org_id`, or `X-Zinn-Org`, or the caller's only organisation).","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"responses":{"200":{"description":"The overview.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingOverview"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/email-marketing/contacts":{"get":{"operationId":"listEmailMarketingContacts","tags":["zinn-campaigns"],"summary":"The organisation's contacts, one keyset page at a time.","description":"Gated on `email_marketing.view`. Ordered by id; pass the previous page's `next_after` as `after` to read the next page. Every contact is reachable this way — `limit` is a page size, not a cap.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"after","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"One page of contacts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingContactPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/email-marketing/imports":{"get":{"operationId":"listEmailMarketingImports","tags":["zinn-campaigns"],"summary":"Past contact imports, newest first, one keyset page at a time.","description":"Gated on `email_marketing.view`. Each import carries the consent attestation the customer gave and what happened to every row.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"after","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"One page of imports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingImportPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createEmailMarketingImport","tags":["zinn-campaigns"],"summary":"Import one chunk of contacts with its consent attestation.","description":"Gated on `email_marketing.manage`. At most `max_import_rows` (1,000) contacts per request; a larger list is sent as several requests. `attestation` (at least 20 characters) records how these people agreed to hear from the customer, and every imported contact gets a consent row pointing at this import. Invalid and role addresses (postmaster@, noreply@ …) are rejected per row; duplicates are merged; a contact who unsubscribed, bounced or complained is never re-subscribed (counted in `rows_suppressed`). Refused with `402 CONTACT_LIMIT` when the import would take the organisation over its contact allowance (the whole chunk is refused), `403 NOT_OPEN` while the product is off for the account, `413 TOO_MANY_ROWS` above 1,000 rows.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingImportCreate"}}}},"responses":{"201":{"description":"The import record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingImport"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"The import would exceed the organisation's contact allowance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"$ref":"#/components/responses/PayloadTooLarge"}}}},"/v1/email-marketing/senders":{"get":{"operationId":"listEmailMarketingSenders","tags":["zinn-campaigns"],"summary":"The organisation's sending connections.","description":"Gated on `email_marketing.view`. The password is never returned.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"responses":{"200":{"description":"The connections.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingSenderList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createEmailMarketingSender","tags":["zinn-campaigns"],"summary":"Connect a campaign sender (Zinn® sending, a sending service, a mailbox, or your own SMTP).","description":"Gated on `email_marketing.manage`. Pick a `provider` from `listEmailMarketingSenderProviders` (SendGrid, Postmark, SES, Gmail, Microsoft 365 …) and send the fields it lists; API keys are kept in the secret store, never returned. Otherwise `kind` is `pool` (Zinn® sending through our marketing pool: send `name` and `from_address` only; the response carries `dkim_record`, the TXT record the From domain publishes, and verifying checks that it is live) or `smtp` (Amazon SES, Resend and Mailgun work through their SMTP interfaces); other kinds are refused until their adapter ships. `pool` is refused (`refusal.campaigns.poolWhiteLabel`) for a white-labelled organisation, which sends through its own server only. An SMTP password goes to the secret store and is never returned. The connection starts `unverified`; call the verify endpoint to prove it. `409` when the organisation already has a connection with that name.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingSenderCreate"}}}},"responses":{"201":{"description":"The connection, unverified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingSender"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/email-marketing/senders/{sender_id}":{"delete":{"operationId":"deleteEmailMarketingSender","tags":["zinn-campaigns"],"summary":"Remove a sending connection and its stored password.","description":"Gated on `email_marketing.manage`. `404` for a connection outside the caller's organisation; `409` while a campaign that is sending or paused uses it (draft, refused and sent campaigns let go of it).","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"sender_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/email-marketing/senders/{sender_id}/verify":{"post":{"operationId":"verifyEmailMarketingSender","tags":["zinn-campaigns"],"summary":"Prove a sending connection works, without sending anything.","description":"Gated on `email_marketing.manage`. Starts a durable check (connect, TLS, log in, quit) and answers `202` with the connection in `verifying`; read the list for `verified` or `failing` with a sentence in `status_detail`. A host that resolves to a private or reserved address is refused without connecting.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"sender_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"The check has started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingSender"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/email-marketing/sender-providers":{"get":{"operationId":"listEmailMarketingSenderProviders","tags":["zinn-campaigns"],"summary":"The providers a campaign sender can connect (the connect picker).","description":"Gated on `email_marketing.view`. Every enabled catalogue row that sends newsletters, in display order: API sending services and SMTP mailboxes, with the fields each needs.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"responses":{"200":{"description":"The catalogue.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailMarketingSenderProvider"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/email-marketing/senders/{sender_id}/health":{"get":{"operationId":"listEmailMarketingSenderHealth","tags":["zinn-campaigns"],"summary":"The sending domain's DNS + reputation readings, newest first.","description":"Gated on `email_marketing.view`. The newest 30 readings of the connection's sending domain.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"sender_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The readings.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailMarketingSenderHealth"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"checkEmailMarketingSenderHealth","tags":["zinn-campaigns"],"summary":"Re-check the sending domain's DNS + reputation now.","description":"Gated on `email_marketing.manage`. Runs the check in the request (it is interactive) and answers the reading; a reading under a minute old is returned as it is instead of asking again. A pool connection is refused (`refusal.campaigns.healthPool`): its DNS is ours.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"sender_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The current reading.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingSenderHealth"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/email-marketing/senders/{sender_id}/dns":{"get":{"operationId":"previewEmailMarketingSenderDns","tags":["zinn-campaigns"],"summary":"Preview the sending records we would add to your DNS (when we host it).","description":"Gated on `email_marketing.view`. When the sending domain's DNS is served by us, lists exactly what `applyEmailMarketingSenderDns` would write: the provider's SPF `include:` merged into the SPF already there (your mechanisms and `all` are kept; two SPF records become one), a DMARC record only when none exists, and, for Zinn® sending, its DKIM key. An ESP's DKIM key lives at the ESP and is never written. A zone we do not serve (or one managed by an external app) answers `writable: false` with the reason in `refusal`.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"sender_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The preview.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingSenderDnsPlan"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"applyEmailMarketingSenderDns","tags":["zinn-campaigns"],"summary":"Add the previewed sending records to your DNS, with your consent.","description":"Gated on `email_marketing.manage`. `consent` must be `true` (`refusal.campaigns.dnsConsent` otherwise). The plan is computed again at this moment, never taken from an earlier preview, then written, audit-logged (`email_marketing.sender.dns_write`) and the domain checked again, so `health` is the reading the internet gives now. A zone we do not serve is refused (`refusal.campaigns.dnsNotOurs`) and nothing is written.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"sender_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["consent"],"properties":{"consent":{"type":"boolean","description":"The customer confirmed the preview."}}}}}},"responses":{"200":{"description":"Written.","content":{"application/json":{"schema":{"type":"object","required":["domain","zone","changes","written","health"],"properties":{"domain":{"type":"string"},"zone":{"type":"string"},"changes":{"type":"array","items":{"$ref":"#/components/schemas/EmailMarketingSenderDnsChange"}},"written":{"type":"integer"},"health":{"allOf":[{"$ref":"#/components/schemas/EmailMarketingSenderHealth"}],"nullable":true}}}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/email-marketing/cold":{"get":{"operationId":"getEmailMarketingCold","tags":["zinn-campaigns"],"summary":"Whether Cold Outreach is open to the organisation.","description":"Gated on `email_marketing.view`. Cold Outreach is a separate mode from opted-in marketing (`docs/1052` §11, ADR 0043): cold mail leaves only through mailboxes the customer connects, never through our sending pools. `open` is `false` until the mode is switched on for the organisation. `cap_ceiling` is the highest daily send cap a mailbox may be set to.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"responses":{"200":{"description":"The mode's state for the organisation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdOverview"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/email-marketing/cold/mailboxes":{"get":{"operationId":"listEmailMarketingColdMailboxes","tags":["zinn-campaigns"],"summary":"The organisation's Cold Outreach mailboxes.","description":"Gated on `email_marketing.view`. The password is never returned.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"responses":{"200":{"description":"The mailboxes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdMailboxList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createEmailMarketingColdMailbox","tags":["zinn-campaigns"],"summary":"Connect a mailbox (SMTP to send, IMAP to read replies) for Cold Outreach.","description":"Gated on `email_marketing.manage`. The mailbox must be the customer's own: a domain we host, a domain whose mail we receive, one of our own domains, or a domain the organisation already sends opted-in campaigns from is refused (`refusal.campaigns.cold*`), so cold mail never shares reputation with marketing or hosted mail. The password goes to the secret store and is never returned. The mailbox is checked in the background at once (`verifying`). `403` while the mode is not open to the organisation; `409` when the address is already connected. `404` (`refusal.campaigns.gone`) when the caller has no acting organisation.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdMailboxCreate"}}}},"responses":{"201":{"description":"The mailbox, being checked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdMailbox"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/email-marketing/cold/mailboxes/{mailbox_id}":{"get":{"operationId":"getEmailMarketingColdMailbox","tags":["zinn-campaigns"],"summary":"One Cold Outreach mailbox.","description":"Gated on `email_marketing.view`. `404` outside the caller's organisation.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"mailbox_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The mailbox.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdMailbox"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"operationId":"updateEmailMarketingColdMailbox","tags":["zinn-campaigns"],"summary":"Change a mailbox's name, daily cap, gap between sends, or pause it.","description":"Gated on `email_marketing.manage`. `daily_cap` is 1 to the cap ceiling; a cap above it is refused with `400`.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"mailbox_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdMailboxUpdate"}}}},"responses":{"200":{"description":"The mailbox.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdMailbox"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"operationId":"deleteEmailMarketingColdMailbox","tags":["zinn-campaigns"],"summary":"Remove a Cold Outreach mailbox and its stored password.","description":"Gated on `email_marketing.manage`. `404` outside the caller's organisation.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"mailbox_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/email-marketing/cold/mailboxes/{mailbox_id}/verify":{"post":{"operationId":"verifyEmailMarketingColdMailbox","tags":["zinn-campaigns"],"summary":"Check a mailbox again, without sending anything.","description":"Gated on `email_marketing.manage`. Starts a durable check (the separation guards, SMTP log in, IMAP log in) and answers `202` with the mailbox in `verifying`; read it again for `verified` or `failing` with a code in `status_code`.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"mailbox_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"The check has started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdMailbox"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/email-marketing/cold/leads":{"get":{"operationId":"listEmailMarketingColdLeads","tags":["zinn-campaigns"],"summary":"The organisation's Cold Outreach leads, one keyset page at a time.","description":"Gated on `email_marketing.view`. Every lead passed the import checks (`docs/1052` §11.4): a valid address whose domain receives mail, a country whose rule allows it, a business address where the rule is business-only, and not on the organisation's suppression list. Follow `next_after` to read every lead; `limit` is a page size, never a cap.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"after","in":"query","schema":{"type":"string","format":"uuid"},"description":"The last lead id of the previous page."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"import_id","in":"query","schema":{"type":"string","format":"uuid"},"description":"Only the leads last written by this import."}],"responses":{"200":{"description":"One page of leads.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdLeadPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/email-marketing/cold/imports":{"get":{"operationId":"listEmailMarketingColdImports","tags":["zinn-campaigns"],"summary":"The organisation's lead imports, newest first.","description":"Gated on `email_marketing.view`. Follow `next_after` for older imports.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"after","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"One page of imports.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdImportPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createEmailMarketingColdImport","tags":["zinn-campaigns"],"summary":"Import business leads for Cold Outreach (checked in the background).","description":"Gated on `email_marketing.manage`. `attested` must be `true`: the caller confirms the statement in `attestation` on `GET /v1/email-marketing/cold` (business contacts, a legitimate interest, published or provided business addresses); it is stored word for word with who confirmed it. Answers `202` at once; a durable workflow then checks every row (syntax, duplicates, the country rule from the `country` column or else the country-code domain, business addresses, the organisation's suppression list and the platform complaint list, then MX). Read `GET imports/{id}` for progress and the verdict of every refused row. At most `max_import_rows` rows per request: send a bigger file as several imports. `404` (`refusal.campaigns.gone`) when the caller has no acting organisation.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdImportCreate"}}}},"responses":{"202":{"description":"The import, waiting to be checked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdImport"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/email-marketing/cold/imports/{import_id}":{"get":{"operationId":"getEmailMarketingColdImport","tags":["zinn-campaigns"],"summary":"One lead import, its progress and the verdict of every refused row.","description":"Gated on `email_marketing.view`. A refused row carries one verdict: `countryRefused`, `notBusinessAddress`, `suppressed`, `invalid` or `duplicate`.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"import_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The import.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdImport"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/email-marketing/cold/sequences":{"get":{"operationId":"listEmailMarketingColdSequences","tags":["zinn-campaigns"],"summary":"The organisation's cold sequences.","description":"Gated on `email_marketing.view`. `404` outside the caller's organisation.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"responses":{"200":{"description":"The sequences, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdSequenceList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"createEmailMarketingColdSequence","tags":["zinn-campaigns"],"summary":"Create a cold sequence (draft).","description":"Gated on `email_marketing.manage`. The sequence starts in `draft`; add steps with `PUT .../steps`, enrol leads, then launch.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdSequenceInput"}}}},"responses":{"201":{"description":"The sequence.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdSequence"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/email-marketing/cold/sequences/{sequence_id}":{"get":{"operationId":"getEmailMarketingColdSequence","tags":["zinn-campaigns"],"summary":"One cold sequence, with its steps and A/B variants.","description":"Gated on `email_marketing.view`. `404` outside the caller's organisation.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"sequence_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The sequence.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdSequence"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"operationId":"updateEmailMarketingColdSequence","tags":["zinn-campaigns"],"summary":"Change a sequence's name, sending window, language, postal address or mailboxes.","description":"Gated on `email_marketing.manage`. Open and click tracking stay off for cold mail until the customer's own tracking domain exists (refused with `400`).","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"sequence_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdSequenceInput"}}}},"responses":{"200":{"description":"The sequence.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdSequence"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"operationId":"deleteEmailMarketingColdSequence","tags":["zinn-campaigns"],"summary":"Delete a sequence and its enrolments.","description":"Gated on `email_marketing.manage`. Messages already sent stay in the mailbox's Sent folder.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"sequence_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/email-marketing/cold/sequences/{sequence_id}/steps":{"put":{"operationId":"replaceEmailMarketingColdSequenceSteps","tags":["zinn-campaigns"],"summary":"Replace the whole step list (1-10 steps, 1-5 variants each).","description":"Gated on `email_marketing.manage`. Only while `draft` or `paused` (`409` otherwise). The first step needs a subject; later steps with no subject reply in the same thread. Merge fields: `{{first_name}}`, `{{last_name}}`, `{{company}}`, `{{title}}`, `{{domain}}` and any imported column.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"sequence_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdSteps"}}}},"responses":{"200":{"description":"The sequence.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdSequence"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"409":{"$ref":"#/components/responses/Conflict"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/email-marketing/cold/sequences/{sequence_id}/enrol":{"post":{"operationId":"enrolEmailMarketingColdSequence","tags":["zinn-campaigns"],"summary":"Enrol leads by id or by import (at most 10,000 per request).","description":"Gated on `email_marketing.manage`. Suppressed leads and leads already in the sequence are skipped and counted. Each new lead is given the sequence mailbox with the most room and keeps it for every step.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"sequence_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdEnrolRequest"}}}},"responses":{"200":{"description":"How many were added and skipped.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdEnrolResult"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/email-marketing/cold/sequences/{sequence_id}/launch":{"post":{"operationId":"launchEmailMarketingColdSequence","tags":["zinn-campaigns"],"summary":"Launch a sequence.","description":"Gated on `email_marketing.manage`. Refused with `400` until it has a postal address (`coldNoPostalAddress`), at least one complete step (`coldNoSteps`) and a verified mailbox (`coldNoMailbox`). Each mailbox then sends at most one message per tick, inside the window, within its daily cap, from the customer's own mail server.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"sequence_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The sequence.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdSequence"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"409":{"$ref":"#/components/responses/Conflict"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/email-marketing/cold/sequences/{sequence_id}/resume":{"post":{"operationId":"resumeEmailMarketingColdSequence","tags":["zinn-campaigns"],"summary":"Resume a paused sequence.","description":"Gated on `email_marketing.manage`. The same rules as launch; each lead continues from its own step.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"sequence_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The sequence.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdSequence"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"409":{"$ref":"#/components/responses/Conflict"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/email-marketing/cold/sequences/{sequence_id}/pause":{"post":{"operationId":"pauseEmailMarketingColdSequence","tags":["zinn-campaigns"],"summary":"Pause an active sequence.","description":"Gated on `email_marketing.manage`. Nothing more is sent until it is resumed (`409` when it is not active).","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"sequence_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The sequence.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdSequence"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"409":{"$ref":"#/components/responses/Conflict"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/email-marketing/cold/sequences/{sequence_id}/report":{"get":{"operationId":"getEmailMarketingColdSequenceReport","tags":["zinn-campaigns"],"summary":"Per step and A/B variant: sent, replies, reply rate, bounces, unsubscribes.","description":"Gated on `email_marketing.view`. `404` outside the caller's organisation.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"sequence_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdSequenceReport"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/email-marketing/cold/replies":{"get":{"operationId":"listEmailMarketingColdReplies","tags":["zinn-campaigns"],"summary":"The Unibox - every reply, automatic reply, bounce and unsubscribe to a cold thread.","description":"Gated on `email_marketing.view`. Newest first, 50 a page; pass `next_cursor` back as `cursor` for the next page. Only mail that answers a message we sent from one of the organisation's mailboxes is stored; everything else in the inbox is never read past its headers. `unread` counts unread real replies. A bad filter is refused with `400` naming the field. Rows are kept 13 months.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"kind","in":"query","schema":{"type":"string","enum":["reply","auto_reply","bounce","unsubscribe"]}},{"name":"unread","in":"query","schema":{"type":"string","enum":["1","true"]}},{"name":"mailbox_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"sequence_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"One page of the Unibox.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdReplyList"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/email-marketing/cold/replies/{reply_id}":{"patch":{"operationId":"updateEmailMarketingColdReply","tags":["zinn-campaigns"],"summary":"Mark a Unibox row read or unread, or label it.","description":"Gated on `email_marketing.manage`. `read` is a boolean; `label` is one of the fixed labels (an empty string clears it). Anything else is refused with `400`. `404` outside the caller's organisation.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"reply_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdReplyUpdate"}}}},"responses":{"200":{"description":"The row.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdReply"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/email-marketing/cold/replies/{reply_id}/answer":{"post":{"operationId":"answerEmailMarketingColdReply","tags":["zinn-campaigns"],"summary":"Answer a Unibox reply, in-thread, from the mailbox it reached.","description":"Gated on `email_marketing.manage`. Queues one plain-text answer to a reply from a person and starts its send on the Cold Outreach worker: it goes from the same mailbox, through that mailbox's own mail server, with `In-Reply-To` and `References` set so it files in the same conversation. One answer per reply: `409` while one is queued or once it was sent; a `failed` answer may be sent again. A bounce, automatic reply or unsubscribe request is refused with `400` (field `kind`); an empty or over-long body with `400` (field `body`). `503` when the send could not be started (nothing was sent; the reply is left `failed` so it can be retried). `404` outside the caller's organisation.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"reply_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdReplyAnswer"}}}},"responses":{"202":{"description":"The row, with `answer_status` `queued`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdReply"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/email-marketing/cold/countries":{"get":{"operationId":"listEmailMarketingColdCountries","tags":["zinn-campaigns"],"summary":"The Cold Outreach rule for each country, as this organisation sees it.","description":"Gated on `email_marketing.view`. Each row has the platform default (`default_rule`, with the law it rests on in `basis`), the organisation's own override if it set one, and the rule in force. `ZZ` answers for an unknown country and every country with no row.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"responses":{"200":{"description":"The country rules.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdCountryList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/email-marketing/cold/countries/{country}":{"put":{"operationId":"setEmailMarketingColdCountry","tags":["zinn-campaigns"],"summary":"Override the Cold Outreach rule for one country, after the warning.","description":"Gated on `email_marketing.manage`. Any rule other than the default needs `acknowledged: true`: the screen shows a warning that the default reflects the country's law and the organisation is responsible for sending there. The override is audited as `email_marketing.cold.country_override` (country, rule, default, who, when). Setting the default rule again removes the override. `404` (`refusal.campaigns.gone`) when the caller has no acting organisation.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"country","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":2},"description":"ISO 3166-1 alpha-2 code (`UK` is read as `GB`), or `ZZ` for unknown."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdCountrySet"}}}},"responses":{"200":{"description":"The country's rule now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingColdCountry"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/email-marketing/sms":{"get":{"operationId":"getEmailMarketingSms","tags":["zinn-campaigns"],"summary":"What the SMS screen needs — open?, paused?, credit balance and prices.","description":"Gated on `email_marketing.view`. `open` is true only when Zinn® Campaigns AND its SMS channel are open to this organisation (both ship off; pilot organisations first). `paused` is true while this organisation's SMS is paused by the spike guard (staff resume it). `prices` lists every country SMS can be sent to today with the price per message part in US dollar micros — the measured provider rate plus the margin row, the same figure the send charges. A country that needs a registered sender first (the US, India, the UAE, Saudi Arabia …) is not listed — unless this organisation's own approved registration opened it (US 10DLC, `/v1/email-marketing/sms/registrations/us`). Messages are paid from the Zinn® credit balance before they are sent. Texts go out under the organisation's OWN name: `sender_id` (set with `PUT /v1/email-marketing/sms/sender-id`) in `sender_id_countries`, else its own registered number; never Zinn®'s numbers or names.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"responses":{"200":{"description":"The SMS state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingSms"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/email-marketing/sms/sender-id":{"put":{"operationId":"setEmailMarketingSmsSenderId","tags":["zinn-campaigns"],"summary":"Set this organisation's own SMS sender name (alphanumeric sender ID).","description":"Gated on `email_marketing.manage`. Texts go out under the customer's OWN name, never Zinn®'s: where a country allows an alphanumeric sender ID (`sender_id_countries` on `GET /v1/email-marketing/sms`), this is the name the handset shows. 3 to 11 letters, digits or spaces, with at least one letter; Zinn®'s own names are refused. An empty `sender_id` clears it, and SMS to those countries is then refused with `own_sender_required` before any credit is taken. Refusal: `CAMPAIGNS_SENDER_ID_INVALID` (400, `details[].code` says why). Audited (`email_marketing.sms.sender_id.update`).","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sender_id"],"additionalProperties":false,"properties":{"sender_id":{"type":"string","maxLength":11}}}}}},"responses":{"200":{"description":"The organisation's own sending identities after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingOwnSenders"}}}},"400":{"description":"The sender ID is not allowed (`CAMPAIGNS_SENDER_ID_INVALID`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/email-marketing/sms/sender-requests":{"post":{"operationId":"createEmailMarketingSmsSenderRequest","tags":["zinn-campaigns"],"summary":"Ask to register this organisation's own SMS sender name in another country.","description":"Gated on `email_marketing.manage`. Countries in `sender_request_countries` (on `GET /v1/email-marketing/sms`) only deliver texts from a sender registered there first. This records the request with our team, who file it with the carrier; approvals can take a few days. When approved, that country opens for this organisation alone and its texts go out under this name, never Zinn®'s. Free: nothing is charged. One open request per country. Refusal: `CAMPAIGNS_SENDER_REQUEST_REFUSED` (400, or 409 when the country is already open or already has a request waiting; `details[].code` says why). Audited (`email_marketing.sms.sender_request.create`).","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["country","sender_id"],"additionalProperties":false,"properties":{"country":{"type":"string","pattern":"^[A-Z]{2}$"},"sender_id":{"type":"string","maxLength":11}}}}}},"responses":{"201":{"description":"The request, waiting for approval.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingSenderRequest"}}}},"400":{"description":"The country or sender name is not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"The country is already open, or a request for it is already waiting.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/email-marketing/whatsapp/connection":{"post":{"operationId":"connectEmailMarketingWhatsapp","tags":["zinn-campaigns"],"summary":"Connect this organisation's own WhatsApp Business Account (Meta Embedded Signup).","description":"Gated on `email_marketing.manage`. WhatsApp messages go out from the customer's OWN WhatsApp Business Account, never Zinn®'s. The dashboard opens Meta's Embedded Signup window with `whatsapp_signup.app_id` and `whatsapp_signup.config_id` from `GET /v1/email-marketing/sms`, and sends what it returns: the one-time `code`, the `waba_id` and the `phone_number_id`. The engine exchanges the code for the business token, checks the phone is on that account, subscribes our app to it and registers the phone; nothing is stored unless every step passes. The token is kept in Vault and never returned. Zinn®'s own accounts are refused. Refusal: `CAMPAIGNS_WHATSAPP_CONNECT_FAILED` (400, or 503 when signup is not set up or Meta did not answer; `details[].code` is one of `not_configured`, `ids_invalid`, `not_in_good_standing` (the account is suspended or closed), `house_account`, `code_invalid`, `waba_not_shared`, `phone_not_on_waba`, `subscribe_failed`, `register_failed`, `vendor_unavailable`). Audited (`email_marketing.whatsapp.connect`).","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code","waba_id","phone_number_id"],"additionalProperties":false,"properties":{"code":{"type":"string","maxLength":2048},"waba_id":{"type":"string","maxLength":32},"phone_number_id":{"type":"string","maxLength":32}}}}}},"responses":{"200":{"description":"The organisation's own sending identities, now with WhatsApp connected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingOwnSenders"}}}},"400":{"description":"The account could not be connected (`CAMPAIGNS_WHATSAPP_CONNECT_FAILED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"description":"Embedded Signup is not set up, or Meta did not answer. Nothing was stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"disconnectEmailMarketingWhatsapp","tags":["zinn-campaigns"],"summary":"Disconnect this organisation's WhatsApp Business Account.","description":"Gated on `email_marketing.manage`. Forgets the account's ids and deletes its token from Vault. WhatsApp messages are then refused with `own_sender_required` until it is connected again. Audited (`email_marketing.whatsapp.disconnect`).","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"responses":{"200":{"description":"The organisation's own sending identities after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingOwnSenders"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/email-marketing/whatsapp/health":{"get":{"operationId":"getEmailMarketingWhatsappHealth","tags":["zinn-campaigns"],"summary":"Can this organisation's own WhatsApp account send, and what to fix.","description":"Gated on `email_marketing.view`. The last reading of Meta's verdict on the organisation's own WhatsApp Business Account (no call to Meta): the state and each reason with where to fix it. Re-read hourly while it cannot send, six-hourly once it can, and on connect.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"responses":{"200":{"description":"The last reading.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingWhatsappHealth"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"checkEmailMarketingWhatsappHealth","tags":["zinn-campaigns"],"summary":"Read Meta again now (\"Check again\").","description":"Gated on `email_marketing.manage`. Reads Meta now and stores the verdict (at most once every 20 seconds per organisation; inside that window, and for an account not in good standing, the last reading is returned without calling Meta). A change between \"can send\" and \"can't send\" notifies the organisation. Audited (`email_marketing.whatsapp.health_check`).","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"responses":{"200":{"description":"The reading after the check.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingWhatsappHealth"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/email-marketing/whatsapp/templates":{"get":{"operationId":"listEmailMarketingWhatsappTemplates","tags":["zinn-campaigns"],"summary":"The message templates on this organisation's own WhatsApp account.","description":"Gated on `email_marketing.view`. Read from Meta (free). Meta sends no marketing WhatsApp message without an APPROVED template. Refusal `CAMPAIGNS_WHATSAPP_TEMPLATE_REFUSED` (409 `not_connected`, 503 `unavailable`, 400 `token_expired`).","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"responses":{"200":{"description":"Every template on the account.","content":{"application/json":{"schema":{"type":"object","required":["results"],"additionalProperties":false,"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/EmailMarketingWhatsappTemplate"}}}}}}},"400":{"description":"The connection's token no longer works (`token_expired`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"The account is not in good standing (`not_in_good_standing`), so no call is made to Meta for it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"No WhatsApp account is connected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Meta did not answer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createEmailMarketingWhatsappTemplate","tags":["zinn-campaigns"],"summary":"Submit a template for Meta's review.","description":"Gated on `email_marketing.manage`. Submits ONE template language to Meta for review (free; Meta usually decides within minutes to a day). The body may carry positional placeholders `{{1}}`, `{{2}}` and so on, numbered from 1 in order of appearance with no gap or repeat, and `examples` carries ONE example value per placeholder in the same order (sent to Meta as the body's `example.body_text`; a plain body sends none). Refusal `CAMPAIGNS_WHATSAPP_TEMPLATE_REFUSED` (`details[].code`: `name_invalid`, `language_invalid`, `category_invalid`, `body_invalid`, `placeholders_invalid` (a gap, a repeat, a wrong order, or a named or malformed placeholder), `examples_invalid` (not exactly one non-blank example per placeholder), `duplicate`, `refused`, `not_connected` 409, `unavailable` 503, `token_expired`); a refused body makes no Meta call. Audited (`email_marketing.whatsapp.template_create`).","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","language","body","category"],"additionalProperties":false,"properties":{"name":{"type":"string","pattern":"^[a-z0-9_]{1,512}$"},"language":{"type":"string","pattern":"^[a-z]{2,3}(_[A-Z]{2})?$"},"body":{"type":"string","maxLength":1024},"category":{"type":"string","enum":["MARKETING","UTILITY"]},"examples":{"type":"array","maxItems":204,"description":"One example value per `{{n}}` placeholder in `body`, in order.","items":{"type":"string","maxLength":1024}}}}}}},"responses":{"201":{"description":"Submitted; `status` is Meta's first answer (usually PENDING).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingWhatsappTemplate"}}}},"400":{"description":"The template was refused (`CAMPAIGNS_WHATSAPP_TEMPLATE_REFUSED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"The account is not in good standing (`not_in_good_standing`), so no call is made to Meta for it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"No WhatsApp account is connected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Meta did not answer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/email-marketing/sms/registrations/us":{"get":{"operationId":"getEmailMarketingUsRegistration","tags":["zinn-campaigns"],"summary":"This organisation's US 10DLC registration, and what one costs.","description":"Gated on `email_marketing.view`. Sending SMS to US numbers needs the sender's own brand and campaign registered with The Campaign Registry (10DLC). We register them through our provider on the customer's behalf. `quote` is the price charged when a registration is submitted (the provider's measured fees — brand, campaign review, the campaign's first `upfront_months` months and a US number for the same months — plus the margin row) and the monthly price after that. `registration` is the latest one (any status). `test_mode` true means a submission is made as a free test that never opens US.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"responses":{"200":{"description":"The US registration state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingUsRegistrationState"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"submitEmailMarketingUsRegistration","tags":["zinn-campaigns"],"summary":"Submit this organisation's brand and campaign for US 10DLC (charged on submit).","description":"Gated on `email_marketing.manage`, and only while SMS is open to the organisation. The quote's upfront price is taken from the Zinn® credit balance now (nothing in test mode); the brand and campaign go to the provider in the background (`202`), and the carriers' review takes days. If the provider refuses the details, or the carriers reject the campaign, the part of the price the provider did not bill is returned. Once approved, a US number is assigned and US opens for this organisation only; the monthly price is then taken each month (an unpaid month closes US again). Refusals: `CAMPAIGNS_ALREADY_REGISTERED` (409), `CAMPAIGNS_NO_CREDIT` (402), `CAMPAIGNS_NOT_OPEN` / `CAMPAIGNS_ACCOUNT_ON_HOLD` (403), `CAMPAIGNS_UNPRICED` (503). Audited (`email_marketing.registration.submit`). A live registration whose request was lost before its price was taken (left submitting for 15 minutes) is settled by the ledger on the next submit: removed if nothing was charged, sent on if it was; audited (`email_marketing.registration.recover`).","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["brand","campaign","fees_acknowledged"],"additionalProperties":false,"properties":{"fees_acknowledged":{"type":"boolean","enum":[true],"description":"The customer ticked that the quote's `nonrefundable_price_usd_micros` is not refunded once submitted."},"brand":{"type":"object","required":["entity_type","display_name","company_name","ein","vertical","email","phone","street","city","state","postal_code","website"],"additionalProperties":false,"properties":{"entity_type":{"type":"string","enum":["PRIVATE_PROFIT","PUBLIC_PROFIT","NON_PROFIT","GOVERNMENT"]},"display_name":{"type":"string","maxLength":100},"company_name":{"type":"string","maxLength":100,"description":"The legal name exactly as on the IRS record of the EIN (US), or as on the country's company register (any other country)."},"country":{"type":"string","pattern":"^[A-Z]{2}$","default":"US","description":"ISO 3166-1 alpha-2 country where the business is registered (a code outside the ISO list, such as `ZZ`, is a 400 on `country`). A business outside the US registers too. For `US` the EIN, phone, state and ZIP keep their US shapes (400 per field otherwise); elsewhere `ein` is the company registration or tax number, `phone` any E.164 number, and `state` and `postal_code` free text."},"ein":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9 -]{3,19}$","maxLength":20,"description":"US - the 9-digit EIN (`12-3456789` or `123456789`). Elsewhere - the company registration or tax number. Never blank."},"vertical":{"type":"string","maxLength":20},"email":{"type":"string","format":"email","maxLength":100},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$","description":"E.164. A US brand needs a US number (`+1` then 10 digits)."},"street":{"type":"string","maxLength":100},"city":{"type":"string","maxLength":100},"state":{"type":"string","maxLength":20,"description":"US - the 2-letter state. Elsewhere - the region or county."},"postal_code":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9 -]{1,9}$","maxLength":10,"description":"US - a ZIP code. Elsewhere - the postcode."},"website":{"type":"string","format":"uri","maxLength":100},"stock_symbol":{"type":"string","maxLength":10},"stock_exchange":{"type":"string","maxLength":10}}},"campaign":{"type":"object","required":["usecase","description","message_flow","sample1","sample2","help_message","optout_message","privacy_policy_link","terms_accepted"],"additionalProperties":false,"properties":{"usecase":{"type":"string","enum":["MARKETING"]},"description":{"type":"string","minLength":40,"maxLength":4096},"message_flow":{"type":"string","minLength":40,"maxLength":2048,"description":"How a person opts in to these texts (where, what they agree to)."},"sample1":{"type":"string","minLength":20,"maxLength":1024},"sample2":{"type":"string","minLength":20,"maxLength":1024},"help_message":{"type":"string","minLength":20,"maxLength":255},"optout_message":{"type":"string","minLength":20,"maxLength":255},"privacy_policy_link":{"type":"string","format":"uri","maxLength":255},"terms_link":{"type":"string","format":"uri","maxLength":255},"embedded_link":{"type":"boolean","default":false},"embedded_phone":{"type":"boolean","default":false},"age_gated":{"type":"boolean","default":false},"terms_accepted":{"type":"boolean","enum":[true]}}}}}}}},"responses":{"202":{"description":"Submitted; the provider steps follow in the background.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingUsRegistration"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"The Zinn® credit balance does not cover the registration (`CAMPAIGNS_NO_CREDIT`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/email-marketing/contacts/{contact_id}/messages":{"post":{"operationId":"sendEmailMarketingMessage","tags":["zinn-campaigns"],"summary":"Send one SMS or WhatsApp message to one contact.","description":"Gated on `email_marketing.manage`. `channel: whatsapp` sends a Meta-approved `template` (with `template_language` and up to 20 `template_params`) from the organisation's OWN WhatsApp Business account; it costs 0 Zinn® credit (Meta bills that account) and still checks good standing, WhatsApp consent and the WhatsApp spike pause. A missing or malformed template is refused with `CAMPAIGNS_TEMPLATE_REQUIRED` (400) before anything else; no own account is `CAMPAIGNS_OWN_SENDER_REQUIRED` (409). An SMS is paid from the Zinn® credit balance. Every guard runs before the provider is called: the line and SMS switches, the account's good standing, the contact's SMS consent, this organisation's spike pause, an open country, and the credit — the price (parts x the country's price per part) is debited BEFORE sending and returned if the network refuses the message. Refusals carry a `refusal.campaigns.channel*` key: `CAMPAIGNS_NO_CREDIT` (402), `CAMPAIGNS_NO_CONSENT` / `CAMPAIGNS_SUPPRESSED` / `CAMPAIGNS_NO_PHONE` / `CAMPAIGNS_PAUSED` (409), `CAMPAIGNS_UNPRICED` / `CAMPAIGNS_COUNTRY_NOT_OPEN` / `CAMPAIGNS_VENDOR_REFUSED` (422), `CAMPAIGNS_TOO_LONG` (400), `CAMPAIGNS_NOT_OPEN` / `CAMPAIGNS_CHANNEL_OFF` / `CAMPAIGNS_ACCOUNT_ON_HOLD` (403), and `CAMPAIGNS_VENDOR_UNAVAILABLE` / `CAMPAIGNS_NOT_CONFIGURED` (503). One message per call; audited (`email_marketing.message.send`).","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"contact_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"channel":{"type":"string","enum":["sms","whatsapp"],"default":"sms"},"text":{"type":"string","maxLength":2000,"description":"The SMS text (required for `sms`; ignored for `whatsapp`). At most 1,530 characters (10 parts) are sent."},"template":{"type":"string","maxLength":512,"description":"WhatsApp only (required): the name of a template Meta approved for this organisation's WhatsApp Business account (lower-case letters, digits, `_`)."},"template_language":{"type":"string","maxLength":16,"description":"WhatsApp only (required) — the template's language code, e.g. `en_GB`."},"template_params":{"type":"array","maxItems":20,"items":{"type":"string","minLength":1,"maxLength":1024},"description":"WhatsApp only — the values for the template body's `{{1}}`, `{{2}}`, … in order."}}}}}},"responses":{"201":{"description":"Sent (handed to the provider) and paid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingMessage"}}}},"400":{"description":"The text is missing or too long (`CAMPAIGNS_TOO_LONG`), or a WhatsApp send has no usable template (`CAMPAIGNS_TEMPLATE_REQUIRED`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"The Zinn® credit balance does not cover the message (`CAMPAIGNS_NO_CREDIT`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/email-marketing/messages":{"get":{"operationId":"listEmailMarketingMessages","tags":["zinn-campaigns"],"summary":"SMS and WhatsApp messages the organisation sent, newest first, one keyset page.","description":"Gated on `email_marketing.view`. Pass the previous page's `next_after` as `after`; `limit` is a page size, not a cap. `price_usd_micros` is what the organisation paid.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"after","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"One page of messages.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingMessagePage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/email-marketing/lists":{"get":{"operationId":"listEmailMarketingLists","tags":["zinn-campaigns"],"summary":"The organisation's mailing lists with subscribed / unsubscribed counts.","description":"Gated on `email_marketing.view`. One keyset page; pass `next_after` as `after`.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"after","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"One page of lists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingListPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createEmailMarketingList","tags":["zinn-campaigns"],"summary":"Create a mailing list (or return the one with that name).","description":"Gated on `email_marketing.manage`. Refused while the line is not open to the organisation.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":120}}}}}},"responses":{"200":{"description":"A list with that name already existed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingList"}}}},"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingList"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/email-marketing/lists/{list_id}/members":{"post":{"operationId":"addEmailMarketingListMembers","tags":["zinn-campaigns"],"summary":"Add contacts to a list by e-mail address (at most 1,000 a request).","description":"Gated on `email_marketing.manage`. Only existing contacts (imported with a consent record) are added; addresses that are not contacts come back in `not_contacts`. A contact who unsubscribed from this list stays unsubscribed.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"list_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["emails"],"properties":{"emails":{"type":"array","maxItems":1000,"items":{"type":"string"}}}}}}},"responses":{"200":{"description":"How many were added.","content":{"application/json":{"schema":{"type":"object","required":["added","not_contacts"],"properties":{"added":{"type":"integer"},"not_contacts":{"type":"array","items":{"type":"string"}}}}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/email-marketing/flows":{"get":{"operationId":"listEmailMarketingFlows","tags":["zinn-campaigns"],"summary":"E-mail flows (welcome, drip, a yearly date), one keyset page.","description":"Gated on `email_marketing.view`. A flow is a list, a trigger and a sequence of steps; it sends nothing itself: every 15 minutes each due step becomes an ordinary campaign run, which is checked like any campaign (line open, account in good standing, quota, a verified sender) and is listed under the flow, never among the campaigns.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"after","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"One page of flows.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingFlowPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createEmailMarketingFlow","tags":["zinn-campaigns"],"summary":"Create a flow (it starts as a draft).","description":"Gated on `email_marketing.manage`. `name` and `list_id` are required; `steps` (at most 20) each need a subject. A `date` flow names a contact attribute holding `YYYY-MM-DD`.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingFlowWrite"}}}},"responses":{"201":{"description":"The flow, with its steps and per-step report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingFlow"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/email-marketing/flows/{flow_id}":{"get":{"operationId":"getEmailMarketingFlow","tags":["zinn-campaigns"],"summary":"One flow with its steps and its report (enrolled, in progress, runs and recipients per step).","description":"Gated on `email_marketing.view`.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"flow_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The flow, with its steps and per-step report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingFlow"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"operationId":"updateEmailMarketingFlow","tags":["zinn-campaigns"],"summary":"Change a flow; `steps`, when given, replaces the whole sequence.","description":"Gated on `email_marketing.manage`. Contacts already in the flow continue at their next step number.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"flow_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingFlowWrite"}}}},"responses":{"200":{"description":"The flow, with its steps and per-step report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingFlow"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"operationId":"deleteEmailMarketingFlow","tags":["zinn-campaigns"],"summary":"Delete a flow and its enrolments (its sent runs stay, as campaigns).","description":"Gated on `email_marketing.manage`.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"flow_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/email-marketing/flows/{flow_id}/activate":{"post":{"operationId":"activateEmailMarketingFlow","tags":["zinn-campaigns"],"summary":"Switch a flow on; only people who join the list from now on are enrolled.","description":"Gated on `email_marketing.manage`. Refused (400) without at least one step, a postal address, or a body on every step. A paused flow resumes: its waiting steps are sent.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"flow_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The flow, with its steps and per-step report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingFlow"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/email-marketing/flows/{flow_id}/pause":{"post":{"operationId":"pauseEmailMarketingFlow","tags":["zinn-campaigns"],"summary":"Pause a flow; due steps wait and nobody new is mailed until it is switched back on.","description":"Gated on `email_marketing.manage`.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"flow_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The flow, with its steps and per-step report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingFlow"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/email-marketing/forms":{"get":{"operationId":"listEmailMarketingForms","tags":["zinn-campaigns"],"summary":"Sign-up forms (double opt-in), newest first, one keyset page.","description":"Gated on `email_marketing.view`. Each form carries its hosted page address, the embed snippet and how many sign-ups are pending and confirmed.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"after","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"One page of forms.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingFormPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createEmailMarketingForm","tags":["zinn-campaigns"],"summary":"Create a sign-up form that adds confirmed people to one list.","description":"Gated on `email_marketing.manage`. A person who submits the form is sent a confirmation e-mail; only a click on its link adds them to the list, with the form, page, time and consent wording recorded as their consent. `redirect_url` must be https.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingFormWrite"}}}},"responses":{"201":{"description":"The form.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingForm"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/email-marketing/forms/{form_id}":{"patch":{"operationId":"updateEmailMarketingForm","tags":["zinn-campaigns"],"summary":"Change a sign-up form (wording, list, redirect, on or off).","description":"Gated on `email_marketing.manage`.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"form_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingFormWrite"}}}},"responses":{"200":{"description":"The form.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingForm"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"operationId":"deleteEmailMarketingForm","tags":["zinn-campaigns"],"summary":"Delete a sign-up form (people already confirmed stay on the list).","description":"Gated on `email_marketing.manage`. Its hosted page then shows \"closed\".","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"form_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/email-marketing/campaigns":{"get":{"operationId":"listEmailMarketingCampaigns","tags":["zinn-campaigns"],"summary":"E-mail campaigns, newest first, one keyset page.","description":"Gated on `email_marketing.view`.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"after","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"One page of campaigns.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingCampaignPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createEmailMarketingCampaign","tags":["zinn-campaigns"],"summary":"Create a draft e-mail campaign.","description":"Gated on `email_marketing.manage`. Merge fields are `{{email}}` and any imported attribute (`{{first_name}}`…); an unknown field renders empty. `sender_id` is a verified connection of your own; with none the campaign would use Zinn® sending, which is refused while that pool warms up.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingCampaignWrite"}}}},"responses":{"201":{"description":"Created as a draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingCampaign"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/email-marketing/campaigns/{campaign_id}":{"get":{"operationId":"getEmailMarketingCampaign","tags":["zinn-campaigns"],"summary":"One e-mail campaign.","description":"Gated on `email_marketing.view`.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The campaign.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingCampaign"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"operationId":"updateEmailMarketingCampaign","tags":["zinn-campaigns"],"summary":"Edit a draft (or a refused campaign, which returns to draft).","description":"Gated on `email_marketing.manage`. A campaign that is sending, paused or sent cannot be edited (`409`).","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingCampaignWrite"}}}},"responses":{"200":{"description":"Saved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingCampaign"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/store-connect/authorize":{"post":{"operationId":"authorizeStoreConnect","tags":["zinn-campaigns"],"summary":"A member approves a store's Zinn® Order Updates connection (the consent screen's Allow).","description":"docs/1297 §5. Needs `email_marketing.manage` in `org_id` (or the only org the member manages). Keeps a single-use grant for ten minutes holding the SHA-256 of a one-time `code` and the plugin's PKCE `code_challenge` (S256 only). ⛔ `return_url` must be the SAME ORIGIN as `site_url`; the dashboard sends the browser to `redirect_to` with `code` and the plugin's `state`. Audit action `store_connect.authorized`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["site_url","return_url","code_challenge"],"properties":{"org_id":{"type":"string","format":"uuid"},"site_url":{"type":"string","format":"uri","maxLength":2048,"description":"The store's home_url()."},"return_url":{"type":"string","format":"uri","maxLength":2048,"description":"The plugin's admin page","same origin as site_url.":null},"code_challenge":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$"},"code_challenge_method":{"type":"string","enum":["S256"],"default":"S256"},"client":{"type":"string","enum":["zinn-order-updates","zinn-campaigns"],"default":"zinn-order-updates","description":"Which of our plugins connects. A store holds one active token per plugin; re-connecting one plugin revokes only its own earlier token."}}}}}},"responses":{"201":{"description":"Approved. The code is shown once; only its hash is kept.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreConnectAuthorized"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/store-connect/token":{"post":{"operationId":"exchangeStoreConnectCode","tags":["zinn-campaigns"],"summary":"The store plugin exchanges the one-time code and its PKCE verifier for a store token.","description":"⛔ **No session**: server to server from the store. The code is claimed with one conditional write before anything else is checked, so it works once; a wrong verifier or another site burns it. Unknown, used, expired and mismatched codes are one answer (422 `codeInvalid`). Re-connecting a store retires its old token in the same step. The `token` (`zou_…`) is returned ONCE; we keep its SHA-256. Audit action `store_connect.connected`.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code","code_verifier","site_url"],"properties":{"code":{"type":"string","maxLength":100},"code_verifier":{"type":"string","minLength":43,"maxLength":128},"site_url":{"type":"string","format":"uri","maxLength":2048},"site_uuid":{"type":"string","maxLength":64},"plugin_version":{"type":"string","maxLength":32},"wp_version":{"type":"string","maxLength":32},"integrations":{"type":"array","maxItems":64,"items":{"type":"string","pattern":"^[a-z0-9_-]{1,40}$"}},"platform":{"type":"object","additionalProperties":true,"description":"Reported facts such as the WooCommerce version; scalars only."},"client":{"type":"string","enum":["zinn-order-updates","zinn-campaigns"],"default":"zinn-order-updates","description":"Must match the client the code was approved for. A store holds one active token per plugin; re-connecting one plugin revokes only its own earlier token."}}}}}},"responses":{"201":{"description":"Connected.","content":{"application/json":{"schema":{"type":"object","required":["token","connection"],"properties":{"token":{"type":"string","description":"zou_… — store it; it is never shown again."},"connection":{"$ref":"#/components/schemas/StoreConnectStatus"}}}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/store-connect/status":{"get":{"operationId":"getStoreConnectStatus","tags":["zinn-campaigns"],"summary":"The store plugin reads its connection; doubles as the heartbeat.","description":"Store token only (`Authorization: Bearer zou_…`). Records `last_seen_at` and the reported versions and integrations. Missing, wrong and revoked tokens are one answer (401).","security":[],"parameters":[{"name":"plugin_version","in":"query","required":false,"schema":{"type":"string","maxLength":32}},{"name":"wp_version","in":"query","required":false,"schema":{"type":"string","maxLength":32}},{"name":"integrations","in":"query","required":false,"description":"Comma-separated integration keys.","schema":{"type":"string","maxLength":2700}},{"name":"languages","in":"query","required":false,"description":"Comma-separated language codes the store sells in, default first (Tranzly, else WPML, else Polylang, else the site language). Omitted = unchanged.","schema":{"type":"string","maxLength":400}}],"responses":{"200":{"description":"The connection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreConnectStatus"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/store-connect/connection":{"delete":{"operationId":"disconnectStore","tags":["zinn-campaigns"],"summary":"The store plugin's own Disconnect button revokes its token.","description":"Store token only. Audit action `store_connect.disconnected` (by `plugin`).","security":[],"responses":{"204":{"description":"Disconnected."},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/store-connect/campaigns":{"get":{"operationId":"getStoreCampaignsPlan","tags":["zinn-campaigns"],"summary":"The Zinn® Campaigns WordPress plugin reads whether its Pro add-on is unlocked.","description":"Store token only (`Authorization: Bearer zou_…`). The ENGINE decides Pro, never the plugin (docs/1052 §11.9b). `active` = the org is in good standing and holds a live, active, non-zero-priced plan on the Zinn® Campaigns line (any paid plan, no separate licence). `trial` = no paid plan, the org is active and fewer than 30 days have passed since the org first connected a store (disconnecting and reconnecting never restarts it). `lapsed` = anything else: the add-on keeps every setting and stops its Pro features until a paid plan is live again.","security":[],"responses":{"200":{"description":"The Pro state.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["pro","plan_paid","plan_code","trial_days","trial_ends_at"],"properties":{"pro":{"type":"string","enum":["active","trial","lapsed"]},"plan_paid":{"type":"boolean","description":"A paid Campaigns plan exists (it may be unusable while the account is not in good standing)."},"plan_code":{"type":"string","description":"The paid plan's code, or empty."},"trial_days":{"type":"integer","enum":[30]},"trial_ends_at":{"type":["string","null"],"format":"date-time"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/store-connect/forms":{"get":{"operationId":"listStoreForms","tags":["zinn-campaigns"],"summary":"The WordPress plugin lists the store org's enabled sign-up forms for its form picker.","description":"Store token only. At most 100, newest first. Only forms of the token's own org.","security":[],"responses":{"200":{"description":"The forms.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["forms"],"properties":{"forms":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":false,"required":["id","title","intro","button_label","consent_text","locale","list_name"],"properties":{"id":{"type":"string","maxLength":32,"description":"The form's public id."},"title":{"type":"string"},"intro":{"type":"string"},"button_label":{"type":"string"},"consent_text":{"type":"string","description":"The consent sentence the plugin must show beside the required tick box."},"locale":{"type":"string"},"list_name":{"type":"string"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"submitStoreForm","tags":["zinn-campaigns"],"summary":"The WordPress plugin posts one visitor's sign-up from the site's server (double opt-in).","description":"Store token only. The plugin sends it only when the visitor ticked the consent box. The same path as the hosted form (F20, docs/1052 §10f): ONE confirmation e-mail goes out and nobody is a contact until they click it. No oracle: a new, pending, confirmed, throttled, suppressed or over-allowance address all answer `ok`; `closed` is a fact about the form (off, Campaigns not open, or the account not in good standing). A form of another org is 404.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["form_id","email"],"properties":{"form_id":{"type":"string","maxLength":32},"email":{"type":"string","maxLength":254},"source_page":{"type":"string","maxLength":500,"description":"The page the form was on."},"client_ip":{"type":"string","maxLength":45,"description":"The visitor's IP as the site saw it, kept as consent evidence; ignored when not an IP address."},"user_agent":{"type":"string","maxLength":500}}}}}},"responses":{"202":{"description":"Recorded.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["result"],"properties":{"result":{"type":"string","enum":["ok","closed"]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/store-connect/events":{"post":{"operationId":"ingestStoreEvents","tags":["zinn-campaigns"],"summary":"The store plugin posts order events; each new one sends the shopper an update in their language.","description":"Store token only (`Authorization: Bearer zou_…`). A batch of 1-100 events (docs/1297 §4.4). `id` is the plugin's idempotency key (`<site_uuid>:<integration>:<order>:<kind>:<seq>`): a known key inserts nothing and never sends twice (`duplicates`). Each new event starts one durable send that picks the language (the shopper's `locale`, then the store's first language, then English), checks the shopper's order-updates consent and every Campaigns guard (line and channel switches, good standing, STOP opt-out, spike pause, own sender, prepaid credit), and records its outcome on the event. A kind with no template is stored and skipped. 503 when the workflow service is down: the rows are kept and a retry of the same batch starts them. Zinn® Campaigns flows (docs/1052 §11.9a): `cart_abandoned`, `product_viewed` and `payment_confirmed` enrol the org's active flows of trigger `cart_abandoned`, `product_viewed` and `post_purchase` when `marketing_consent` was ticked for e-mail at or before `occurred_at` (or the contact already holds an e-mail consent by then); `cart_recovered` ends an open cart flow; `order_placed` and `payment_confirmed` end open cart and browse flows. The shopper's `customer.email` finds the contact and is not kept on the event. A suppressed or unsubscribed shopper is never enrolled.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreEventBatch"}}}},"responses":{"202":{"description":"Accepted; new events are being sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreEventsAccepted"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/store-connect/consents":{"post":{"operationId":"recordStoreConsents","tags":["zinn-campaigns"],"summary":"The store plugin records the shopper's checkout opt-ins, per channel and purpose.","description":"Store token only. A batch of 1-100 ticks (docs/1297 §8, §9), one row per phone + channel + purpose, upserted. `updates` (order updates, transactional) never puts a shopper into a Campaigns list or marketing send; `marketing` is kept for the store to use by choice. `withdrawn: true` records an un-tick or a STOP. `evidence` keeps the wording the shopper saw (at most 10 keys).","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreConsentBatch"}}}},"responses":{"200":{"description":"Recorded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreConsentsRecorded"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/store-connect/people":{"post":{"operationId":"syncStorePeople","tags":["zinn-campaigns"],"summary":"The store plugin syncs its WordPress users and store customers into Zinn® Campaigns contacts.","description":"Store token only (docs/1297 §9.5, docs/1052 F30). A batch of 1-100 people from the plugin's resumable backfill, its live hooks or its daily reconcile, applied as one batched upsert keyed by organisation + e-mail hash. `op: upsert` creates or fills in the contact and records this store's source (`attributes.sources[]`); it never sets a contact's status, so an unsubscribed, bounced or complained person stays suppressed, and a new person whose address is on the organisation's suppression list arrives suppressed. A synced person gets NO consent and joins NO list, so no campaign can select them; the one exception is the e-mail soft opt-in, written only when `soft_opt_in` states the opt-out the store gave and only for a store customer with at least one paid order (never SMS or WhatsApp). `op: delete` removes this store's source and the contact with its last source unless it holds a consent of its own; `op: erase` (the WordPress privacy eraser) deletes the contact on its last source whatever it holds and keeps only the suppression hash and the number's opt-out. A person the engine cannot take is listed in `rejected` by index (an invalid or role address, or `contactLimit` when the plan's contact allowance is full, with `limit_reached: true`); the rest of the batch still applies.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorePeopleBatch"}}}},"responses":{"200":{"description":"Applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorePeopleSynced"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/store-connect/people/summary":{"get":{"operationId":"getStorePeopleSummary","tags":["zinn-campaigns"],"summary":"The store plugin reads how many people it has synced per source, for its daily reconcile.","description":"Store token only (docs/1297 §9.5 rule 1). Per source (`wp_user`, `woo_customer`, …): the number of people this store has synced and the XOR of each one's 64-bit id hash (the first 8 bytes of `sha256(\"<source>:<external_id>\")`, as 16 hex digits). The plugin compares both with its own and re-queues any gap; its health panel shows `synced N of M`.","security":[],"responses":{"200":{"description":"The per-source counts and hashes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorePeopleSummary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/store-connect/shopper":{"post":{"operationId":"readStoreShopper","tags":["zinn-campaigns"],"summary":"The store plugin reads one shopper's text preferences and the last 20 texts this store sent them.","description":"Store token only. Feeds the shopper's My Account \"Messages\" panel (docs/1297 §8.3). The plugin asks only for a number that is the billing phone on one of the signed-in shopper's OWN orders, and lists only the texts whose `ref` is one of those orders (an account phone is typed, so it proves nothing). Scoped to the token's ONE store: another store's consents or texts, even of the same organisation, are never returned. `consents` is every channel + purpose this number has at this store (`active: false` once withdrawn); `messages` holds only texts that were sent, newest first, at most 20. POST so the phone number never appears in a URL or a log. A preference change is posted back to `recordStoreConsents` (`withdrawn: true` to stop).","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreShopperQuery"}}}},"responses":{"200":{"description":"The shopper's preferences and recent texts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreShopper"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/store-connect/orders/{ref}/messages":{"get":{"operationId":"getStoreOrderMessages","tags":["zinn-campaigns"],"summary":"The store plugin reads one order's update history (sent, not sent and why, failed).","description":"Store token only. Feeds the plugin's `zinn-ou/get-order-messages` ability (docs/1297 §22.3, `edit_shop_orders` in WordPress). Every update the engine handled for this ONE order of the token's ONE store, newest first, at most 50: another store's events, even of the same organisation and with the same order ref, are never returned. `reason` is the refusal code of an update not sent (`noConsent`, `accountOnHold`, …) or the failure class of one that failed (`provider_outage` when the messaging vendor was at fault, `our_fault` when we were, `permanent`, …). The shopper's number is masked to its last three digits. `templates` lists the approved kinds `sendStoreOrderUpdate` takes.","security":[],"parameters":[{"name":"ref","in":"path","required":true,"description":"The store's order id.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,64}$"}}],"responses":{"200":{"description":"The order's updates.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreOrderMessages"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/store-connect/orders/{ref}/updates":{"post":{"operationId":"sendStoreOrderUpdate","tags":["zinn-campaigns"],"summary":"The store plugin sends one order's shopper an update from an approved template.","description":"Store token only. Feeds the plugin's `zinn-ou/send-order-update` ability (docs/1297 §22.3, `edit_shop_orders` in WordPress). `kind` is one of the approved, translated templates (never free text); the text goes to the order's own shopper, in their language, from the order's last event (a phone number is never taken from the request). The update is a new event sent by the same durable workflow as `ingestStoreEvents`, so every Campaigns guard applies: the shopper's order-updates consent, the line and channel switches, good standing, the STOP opt-out, the spike pause, the own sender and prepaid credit. Its outcome is read back with `getStoreOrderMessages`. `request_id` is the idempotency key for the order, whatever the `kind`: a repeat (even with another `kind`) books nothing and answers the FIRST update with `duplicate: true`. 403 when the account is on hold (nothing is booked), 404 when the engine has no event for the order, 429 after five staff-sent updates to one order in a day, 503 when the workflow service is down (the booking is kept; a retry with the same `request_id` starts it).","security":[],"parameters":[{"name":"ref","in":"path","required":true,"description":"The store's order id.","schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,64}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreOrderUpdateInput"}}}},"responses":{"202":{"description":"Booked; the update is being sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreOrderUpdateBooked"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/store-connect/connections":{"get":{"operationId":"listStoreConnections","tags":["zinn-campaigns"],"summary":"Connected stores, newest first (Campaigns, Stores).","description":"Needs `email_marketing.view`; only orgs where the member holds it. Keyset paged: follow `next_after` until it is null (a page size, never a cap).","parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"after","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"One page.","content":{"application/json":{"schema":{"type":"object","required":["items","next_after"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/StoreConnection"}},"next_after":{"type":["string","null"],"format":"uuid"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/store-connect/connections/{connection_id}":{"delete":{"operationId":"revokeStoreConnection","tags":["zinn-campaigns"],"summary":"Disconnect a store from the dashboard.","description":"Needs `email_marketing.manage` in the store's org; another org's store is a 404. The store's token stops at once; the plugin shows Reconnect. Audit action `store_connect.disconnected` (by `dashboard`).","parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Disconnected."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/store-connect/support/tickets":{"get":{"operationId":"listStoreSupportTickets","tags":["zinn-campaigns"],"summary":"This store's support tickets, newest first, with status and support's latest reply.","description":"Store token only. Never another store's ticket, even in the same organisation. A page of 50, never a cap: pass `before` = the last `reference` (`next_before`) for older ones. `answered` counts the tickets waiting on the store (the plugin's menu badge).","security":[],"parameters":[{"name":"before","in":"query","required":false,"schema":{"type":"string","maxLength":16}}],"responses":{"200":{"description":"The tickets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreSupportTicketList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createStoreSupportTicket","tags":["zinn-campaigns"],"summary":"Zinn® Order Updates files a support ticket with its store token (docs/1297 §16).","description":"Store token only (`Authorization: Bearer zou_…`). Files the ticket in the plugin-support desk tagged `product=zinn-order-updates`, exactly like `createPluginSupportTicket`; the reply address is `email` when given, else the member who approved the store. The ticket is tied to THIS store connection, so only this store lists it. `diagnostics` are kept only with `consent_diagnostics: true` (the plugin shows them in full first). A store that never connected uses `createPluginSupportTicket` with an e-mail address instead.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreSupportTicketInput"}}}},"responses":{"201":{"description":"Filed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PluginSupportTicketCreated"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/store-connect/support/tickets/{reference}/replies":{"post":{"operationId":"replyStoreSupportTicket","tags":["zinn-campaigns"],"summary":"The store owner replies to one of this store's tickets from the plugin.","description":"Store token only. Another store's ticket is a 404. The ticket returns to `open` (waiting on support); a closed ticket is a 422 with code `TICKET_CLOSED`.","security":[],"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","maxLength":16}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","maxLength":20000}}}}}},"responses":{"201":{"description":"The ticket after the reply.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreSupportTicket"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/email-marketing/deliverability-settings":{"get":{"operationId":"getEmailMarketingDeliverabilitySettings","tags":["zinn-campaigns"],"summary":"The bounce and spam-complaint thresholds this organisation sends under.","description":"Gated on `email_marketing.view`. `effective` is what the send path applies: the platform default for each field, or this organisation's override (`overridden`). By default bounces do NOT pause sending (owner 2026-11-08) and complaints pause above 0.3%. Rates are judged once a campaign has `min_sample` sends. Over a warn line staff are alerted and the send carries on.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"responses":{"200":{"description":"The thresholds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingDeliverabilitySettings"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"operationId":"updateEmailMarketingDeliverabilitySettings","tags":["zinn-campaigns"],"summary":"Set or clear this organisation's threshold overrides.","description":"Gated on `email_marketing.manage`. Only the fields sent change; `null` returns a field to the platform default. A rate is basis points 1..10000; anything else is refused with `400` (`refusal.campaigns.thresholdInvalid`). While staff have locked the thresholds the change is refused with `409` (`refusal.campaigns.thresholdsLocked`). Audited as `email_marketing.thresholds.update`.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingDeliverabilityWrite"}}}},"responses":{"200":{"description":"The thresholds after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingDeliverabilitySettings"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/email-marketing/zerobounce":{"get":{"operationId":"getEmailMarketingZeroBounce","tags":["zinn-campaigns"],"summary":"Whether this organisation's own ZeroBounce key is connected (F41).","description":"Gated on `email_marketing.view`. No network and no Vault read: the answer comes from the organisation's settings row. The key itself is never returned; `key_hint` is its last four characters. `modes` are the values a campaign's `zerobounce_mode` takes.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"responses":{"200":{"description":"The connection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingZeroBounce"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"operationId":"connectEmailMarketingZeroBounce","tags":["zinn-campaigns"],"summary":"Connect (or replace) this organisation's own ZeroBounce API key.","description":"Gated on `email_marketing.manage`. The key is checked first with ZeroBounce's free credit-balance call, then stored in Vault; nothing is stored when the check fails. A key ZeroBounce does not accept is refused with `400` (`refusal.campaigns.zerobounceKeyInvalid`); ZeroBounce not answering is `503` (`refusal.campaigns.zerobounceUnavailable`), and our secret store not answering is `503` (`refusal.campaigns.vaultUnavailable`). Campaigns that were paused waiting for a key (`zerobounce_key`) carry on by themselves. Audited as `email_marketing.zerobounce.connect` with the credit balance (never the key).","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingZeroBounceConnect"}}}},"responses":{"200":{"description":"The connection after the change, with the credit balance ZeroBounce reported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingZeroBounce"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"delete":{"operationId":"disconnectEmailMarketingZeroBounce","tags":["zinn-campaigns"],"summary":"Disconnect this organisation's ZeroBounce key.","description":"Gated on `email_marketing.manage`. The key is deleted from Vault. A campaign whose `zerobounce_mode` is not `off` is then refused at send (`zerobounce_key`) until a key is connected again or the check is turned off. Audited as `email_marketing.zerobounce.disconnect`.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"responses":{"200":{"description":"The connection after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingZeroBounce"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/email-marketing/brand-kit":{"get":{"operationId":"getEmailMarketingBrandKit","tags":["zinn-campaigns"],"summary":"The organisation's brand kit (name, logo, colours, font, voice).","description":"Gated on `email_marketing.view`. One kit per organisation; an organisation without one gets the empty kit (`status: manual`). `status` is `reading` while the website is being read, then `ready`, or `failed` with `status_code` (`siteUnreadable`: the address could not be read; the kit keeps its earlier values).","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"responses":{"200":{"description":"The kit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingBrandKit"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"put":{"operationId":"updateEmailMarketingBrandKit","tags":["zinn-campaigns"],"summary":"Edit the brand kit.","description":"Gated on `email_marketing.manage`. Only the fields sent change. A colour is `#rrggbb` (or `#rgb`), the logo an absolute `https://` address, the font a plain family name; anything else is refused with `400` (`refusal.campaigns.brandInvalid`, the field in `details`) and nothing is saved. With `apply_to_emails` on, every email on the `basic` template is dressed in the kit (the logo or the name on a band in the primary colour, the font, links in the accent colour); a `raw` email is sent as written. The name and voice are given to the AI writer. Audited as `email_marketing.brand_kit.update`.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingBrandKitWrite"}}}},"responses":{"200":{"description":"The saved kit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingBrandKit"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/email-marketing/brand-kit/read":{"post":{"operationId":"readEmailMarketingBrandKit","tags":["zinn-campaigns"],"summary":"Read the brand kit from the organisation's website.","description":"Gated on `email_marketing.manage`. Starts a durable workflow (`202`) that reads the home page and at most two of its stylesheets on the same host (every address checked to be public, bodies capped) and fills the name, logo, primary and accent colours and font it finds; a value the site does not show keeps the kit's earlier value, and the voice is never overwritten. Free: no AI and nothing billed. A plain address is read as `https://`; anything that is not a web address is refused with `400` (`refusal.campaigns.brandUrl`). Poll `GET /v1/email-marketing/brand-kit` for the result. Audited as `email_marketing.brand_kit.read`.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","maxLength":500,"description":"The website's address, e.g. https://example.com."}}}}}},"responses":{"202":{"description":"The read was started; the kit is `reading`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingBrandKit"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/email-marketing/ai/write":{"post":{"operationId":"writeEmailMarketingCampaignWithAi","tags":["zinn-campaigns"],"summary":"Write a draft campaign email from a short brief with Zinn® AI.","description":"Gated on `email_marketing.manage`. One model call during the request, paid by the organisation's own provider key, its credit balance or its included AI allowance, and listed on the AI spend page as \"Writing campaign emails\". Returns two subject lines (for an A/B test), a preheader and a sanitised HTML body in the requested language; nothing is saved, the editor fills the campaign and the customer saves it. Refused with `402` while the account is on hold or there is no AI allowance left, and `422` with a `failure` object (provider outage, a problem with the customer's own key, or ours) when the model call fails. Nothing is charged for a failed call.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingAiWriteRequest"}}}},"responses":{"200":{"description":"The draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingAiDraft"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"The account is on hold, or there is no AI allowance left to pay for the call.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/email-marketing/campaigns/{campaign_id}/test":{"post":{"operationId":"testEmailMarketingCampaign","tags":["zinn-campaigns"],"summary":"Send one test copy now to a member of the organisation.","description":"Gated on `email_marketing.manage`. Interactive: sent during the request through the campaign's own connection, subject prefixed `[TEST]`, links not tracked. Only an address that belongs to a member of the organisation is accepted.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["to"],"properties":{"to":{"type":"string","format":"email"}}}}}},"responses":{"200":{"description":"Accepted by the sending server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingTestResult"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"502":{"description":"The sending server refused or deferred the test.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingTestResult"}}}}}}},"/v1/email-marketing/campaigns/{campaign_id}/send":{"post":{"operationId":"sendEmailMarketingCampaign","tags":["zinn-campaigns"],"summary":"Start sending a campaign to its list.","description":"Gated on `email_marketing.manage`. The abuse gate runs first, in order: the line is open, the account is in good standing, the plan includes e-mail, the campaign is complete, the sending connection is verified (Zinn® sending is refused while it warms up), the From domain publishes SPF and DMARC, sending is not paused, someone on the list may be mailed, the plan's monthly e-mails cover the list, and staff have reviewed an account above the monthly review line. Each refusal is its own `409` code. On `202` a durable workflow sends in batches; a new sender's daily volume ramps up with clean sending days, and a bounce or complaint rate over the line pauses the account's sending.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Already sending or sent; nothing changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingCampaign"}}}},"202":{"description":"Sending has started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingCampaign"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/email-marketing/campaigns/{campaign_id}/lint":{"get":{"operationId":"lintEmailMarketingCampaign","tags":["zinn-campaigns"],"summary":"Check a campaign's copy for deliverability problems before it is sent.","description":"Gated on `email_marketing.view`. Rules only, run during the request, nothing billed: the subject (missing, too long, shouting, repeated punctuation, a fake `Re:`), the body (missing, tags mail clients strip, size over Gmail's clipping line, the image-to-text ratio, images without `alt`), every link (not http(s), an IP address, a public URL shortener, plain http, visible text naming a different domain than the link), the postal address the footer needs, and phrases spam filters score. Each finding is a stable `code` with a `severity` and `params`; the dashboard words it in the reader's language. The unsubscribe link and postal address are added to every message, so a body without them is not a finding.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The findings, errors first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingLint"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/email-marketing/campaigns/{campaign_id}/translations":{"get":{"operationId":"listEmailMarketingCampaignTranslations","tags":["zinn-campaigns"],"summary":"Each contact language of a campaign's list and whether its translation is current.","description":"Gated on `email_marketing.view`. The languages are the distinct languages of the list's subscribed contacts, mapped onto the 58 platform languages, minus the campaign's `source_locale`. `state` is `current` (made from the copy as it is now), `stale` (the copy changed since; the contact gets the source copy until it is translated again) or `missing`. A row with `wanted: false` is a translation kept for a language no contact uses any more.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The languages.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingCampaignTranslations"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/email-marketing/campaigns/{campaign_id}/translate":{"post":{"operationId":"translateEmailMarketingCampaign","tags":["zinn-campaigns"],"summary":"Translate a campaign into every contact language that is missing or stale.","description":"Gated on `email_marketing.manage`. Starts a durable workflow (`202`) that makes TWO batched calls on the house translation model for every missing or stale language at once: the short fields (subject, subject B, preheader, plain text) and the HTML body. Merge tags such as `{{first_name}}` are kept. It is the customer's AI use, metered on the organisation's AI meter (credits, then the included allowance; listed on the AI spend page as \"Translating campaign emails\"). Nothing to translate answers `200` with `started: false` and spends nothing. Refused with `402` before anything starts while the account is on hold (`refusal.campaigns.translateOnHold`) or when no credits or allowance are left (`refusal.campaigns.translateNoAllowance`). Each contact is sent the current translation for their language, else the source copy. Audited as `email_marketing.campaign.translate`.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Nothing was missing or stale; nothing was started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingCampaignTranslateResult"}}}},"202":{"description":"The translation was started; poll the translations list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingCampaignTranslateResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"The account is on hold, or no AI credits or allowance are left.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/email-marketing/campaigns/{campaign_id}/report":{"get":{"operationId":"getEmailMarketingCampaignReport","tags":["zinn-campaigns"],"summary":"A campaign's numbers.","description":"Gated on `email_marketing.view`. Events count distinct recipients (unique opens and clicks). Rates are basis points of `sent` (accepted by the sending server, including those that later bounced). `delivered` needs the provider's webhook.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailMarketingCampaignReport"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/email-marketing/senders/{sender_id}/webhook":{"put":{"operationId":"setEmailMarketingSenderWebhook","tags":["zinn-campaigns"],"summary":"Set up delivery events from your e-mail provider for this connection.","description":"Gated on `email_marketing.manage`. The connection's provider decides the `scheme`: `svix` (Resend, `whsec_…` signing secret) and `mailgun_hmac` (Mailgun HTTP webhook signing key) need `signing_secret`, kept in the secret store and never returned; `url_token` and `sns` (Amazon SES through SNS, which the endpoint confirms itself) need nothing: a token is minted and returned once, inside `webhook_url` as `?t=`, and calling this again replaces it. Point the provider's delivered, bounced and complained events at the returned `webhook_url`. A mailbox connection or a provider with no event webhook is refused (`refusal.campaigns.webhookNone`); a missing or malformed secret is `refusal.campaigns.webhookSecret` (`refusal.campaigns.webhookKey` for Mailgun).","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"sender_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"`signing_secret` is required for the `svix` and `mailgun_hmac` schemes and ignored for the others.","properties":{"signing_secret":{"type":"string","maxLength":200,"writeOnly":true}}}}}},"responses":{"200":{"description":"Stored.","content":{"application/json":{"schema":{"type":"object","required":["webhook_url","scheme"],"properties":{"webhook_url":{"type":"string","format":"uri","description":"For `url_token` and `sns` this carries the minted token (`?t=`); it is shown on this response only."},"scheme":{"type":"string","enum":["svix","mailgun_hmac","url_token","sns"]}}}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/public/email-marketing/f/{public_id}":{"get":{"operationId":"emailMarketingFormPage","tags":["zinn-campaigns"],"security":[],"summary":"A sign-up form's hosted page (no login).","description":"The form in its language, with the consent wording. A form that is off or gone shows a \"closed\" page.","parameters":[{"name":"public_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The form page.","content":{"text/html":{"schema":{"type":"string"}}}}}},"post":{"operationId":"emailMarketingFormSubmit","tags":["zinn-campaigns"],"security":[],"summary":"Submit a sign-up form (hosted page, embed or JSON).","description":"Records the request and e-mails a confirmation link (double opt-in). Every outcome but a closed form answers the same (no address oracle): a JSON caller gets `202`, a browser the form's redirect or a \"check your inbox\" page. Rate-limited per client; at most 3 confirmation mails per address a day.","parameters":[{"name":"public_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","maxLength":320},"website_confirm":{"type":"string","description":"Honeypot; leave empty."}}}},"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","maxLength":320}}}}}},"responses":{"200":{"description":"The \"check your inbox\" (or \"closed\") page.","content":{"text/html":{"schema":{"type":"string"}}}},"202":{"description":"Accepted (JSON callers).","content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["check_your_inbox"]}}}}}},"302":{"description":"To the form's redirect address."},"410":{"description":"The form is closed (JSON callers).","content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["closed"]}}}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/email-marketing/fc":{"get":{"operationId":"emailMarketingFormConfirmPage","tags":["zinn-campaigns"],"security":[],"summary":"The double opt-in confirmation page (no login).","description":"Shows a confirm button. The signed token travels in the URL fragment (`#t=`), so it never reaches a server log or a link scanner; only the button's POST confirms.","parameters":[{"name":"l","in":"query","required":false,"schema":{"type":"string","maxLength":16}}],"responses":{"200":{"description":"The confirmation page.","content":{"text/html":{"schema":{"type":"string"}}}}}},"post":{"operationId":"emailMarketingFormConfirm","tags":["zinn-campaigns"],"security":[],"summary":"Confirm a sign-up (adds the person to the list with a consent record).","parameters":[],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","maxLength":2048}}}}}},"responses":{"200":{"description":"Confirmed, already confirmed, closed or invalid, as a page.","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/v1/public/email-marketing/u/{token}":{"get":{"operationId":"emailMarketingUnsubscribePage","tags":["zinn-campaigns"],"security":[],"summary":"The footer unsubscribe link (no login).","description":"Unsubscribes the person from the campaign's LIST at once and answers a small page in their language that offers to stop every e-mail from that sender. A token that does not verify gets the same page and changes nothing (no address oracle).","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The confirmation page.","content":{"text/html":{"schema":{"type":"string"}}}}}},"post":{"operationId":"emailMarketingUnsubscribeOneClick","tags":["zinn-campaigns"],"security":[],"summary":"RFC 8058 one-click unsubscribe (and the page's \"stop everything\" button).","description":"A mail provider's one-click POST (body `List-Unsubscribe=One-Click`) unsubscribes from the list and answers `200` with no body. With `scope=all` (the page's button) the address is suppressed for every list of that sender and the page confirms it.","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}},{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["all"]}}],"responses":{"200":{"description":"Done (always, whatever the token).","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/v1/public/email-marketing/cold-u/{token}":{"get":{"operationId":"emailMarketingColdUnsubscribePage","tags":["zinn-campaigns"],"security":[],"summary":"The unsubscribe link every cold outreach message carries (no login).","description":"Adds the lead the signed token names to the sender's suppression list at once (no sequence of theirs writes to that address again) and answers a small confirmation page in the sequence's language. A token that does not verify gets the same page and changes nothing (no address oracle).","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The confirmation page.","content":{"text/html":{"schema":{"type":"string"}}}}}},"post":{"operationId":"emailMarketingColdUnsubscribeOneClick","tags":["zinn-campaigns"],"security":[],"summary":"RFC 8058 one-click unsubscribe from a cold outreach message.","description":"A mail provider's one-click POST (body `List-Unsubscribe=One-Click`) suppresses the lead and answers `200` with no body, whatever the token.","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Done (always, whatever the token)."}}}},"/v1/public/email-marketing/warmup-u/{token}":{"get":{"operationId":"emailMarketingWarmupUnsubscribePage","tags":["zinn-campaigns"],"security":[],"summary":"The marketing pool warm-up mail's unsubscribe link (no login).","description":"Takes the address the signed token names out of the Zinn® Campaigns marketing pool warm-up at once (it is never mailed by the warm-up again) and answers a small confirmation page. A token that does not verify gets the same page and changes nothing (no address oracle). The token carries a keyed digest of the address, never the address.","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The confirmation page.","content":{"text/html":{"schema":{"type":"string"}}}}}},"post":{"operationId":"emailMarketingWarmupUnsubscribeOneClick","tags":["zinn-campaigns"],"security":[],"summary":"RFC 8058 one-click unsubscribe from the warm-up mail.","description":"A mail provider's one-click POST (body `List-Unsubscribe=One-Click`) takes the address out of the warm-up and answers `200` with no body, whatever the token.","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Done (always, whatever the token)."}}}},"/v1/public/email-marketing/o/{token}":{"get":{"operationId":"emailMarketingOpenPixel","tags":["zinn-campaigns"],"security":[],"summary":"The open-tracking image (a 1x1 GIF). Counts one open per recipient.","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The image.","content":{"image/gif":{"schema":{"type":"string","format":"binary"}}}}}}},"/v1/public/email-marketing/c/{token}":{"get":{"operationId":"emailMarketingClick","tags":["zinn-campaigns"],"security":[],"summary":"The click counter. Records one click per recipient and redirects to the original link.","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"302":{"description":"To the link the campaign contained."},"404":{"description":"The token does not verify."}}}},"/v1/webhooks/email-marketing/{connection_id}":{"post":{"operationId":"receiveEmailMarketingProviderWebhook","tags":["zinn-campaigns"],"security":[],"summary":"A customer's own e-mail provider's delivery events for one sending connection.","description":"**Unauthenticated by design**: the connection's provider scheme is the authentication, checked with the secret stored for THIS connection: `svix` (signature over the raw body, at most five minutes old), `mailgun_hmac` (the signed timestamp + token, at most five minutes old), `url_token` and `sns` (the `t` query token minted by `setEmailMarketingSenderWebhook`; an SNS subscription confirmation is followed only to an Amazon SNS host and answers `subscribed`). `401` when it does not verify. Each of the catalogue's ESPs is parsed; only delivered, permanent bounce and complaint events count, matched to the latest send to that address through this connection in the last 14 days; a bounce or complaint suppresses the address at once. Anything else is acknowledged with `200` and ignored. Redelivery is a no-op.","parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"t","in":"query","required":false,"description":"The minted token, for the `url_token` and `sns` schemes.","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Accepted (recorded, a duplicate, or ignored).","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean"},"outcome":{"type":"string","enum":["recorded","duplicate","ignored","subscribed"]}}}}}},"400":{"description":"Not JSON."},"401":{"description":"The signature did not verify."},"404":{"description":"No such connection."},"503":{"description":"The secret store could not be read; the provider retries."}}}},"/v1/email-marketing/managed-delivery/price":{"get":{"operationId":"getEmailMarketingManagedDeliveryPrice","tags":["zinn-campaigns"],"summary":"The public price of Zinn® managed e-mail delivery.","description":"**Public** reference data (no auth, no tenant scope), for the server-rendered marketing pages. `price_usd_micros_per_1000` is the live row the send charges with (`CampaignsSettings.managed_delivery_price_usd_micros_per_1000`, metered from prepaid credit), never a typed copy. `data_locations` lists only the locations whose delivery provider is configured today (`global` = the Telnyx route, `eu` = Amazon SES eu-west-1), so a page never offers the EU location before it exists. `dedicated_ip_price_usd_minor_per_month` is the `campaigns_dedicated_ip` Extra. Cacheable exactly like `listCatalogPlans` (strong `ETag` + `max-age=60`). `docs/1052` §10 F47/F48.","security":[],"parameters":[{"name":"If-None-Match","in":"header","required":false,"description":"A previously returned `ETag`; a match responds `304`.","schema":{"type":"string","maxLength":256}}],"responses":{"200":{"description":"The managed-delivery price.","headers":{"ETag":{"description":"Strong validator over the response body.","schema":{"type":"string"}},"Cache-Control":{"description":"Always `public, max-age=60`.","schema":{"type":"string"}},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["price_usd_micros_per_1000","currency","data_locations","dedicated_ip_price_usd_minor_per_month"],"properties":{"price_usd_micros_per_1000":{"type":"integer","minimum":0,"description":"Price per 1,000 accepted recipients in USD micros (1200000 = $1.20)."},"currency":{"type":"string","enum":["USD"]},"data_locations":{"type":"array","items":{"type":"string","enum":["eu","global"]},"description":"The data locations offered today."},"dedicated_ip_price_usd_minor_per_month":{"type":"integer","minimum":0,"description":"The dedicated-IP add-on price, USD minor units per month (4900 = $49)."}}}}}},"304":{"description":"Unchanged since the supplied `If-None-Match`.","headers":{"ETag":{"description":"The unchanged validator.","schema":{"type":"string"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/email-marketing/sms/campaigns":{"get":{"operationId":"listSmsMarketingCampaigns","tags":["zinn-campaigns"],"summary":"Bulk SMS and WhatsApp campaigns, newest first, one keyset page.","description":"Gated on `email_marketing.view`. `channel` narrows the page to one channel.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"channel","in":"query","required":false,"schema":{"type":"string","enum":["sms","whatsapp"]}},{"name":"after","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"One page of SMS campaigns.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsMarketingCampaignPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createSmsMarketingCampaign","tags":["zinn-campaigns"],"summary":"Create a draft SMS or WhatsApp campaign to a list.","description":"Gated on `email_marketing.manage`. `channel: whatsapp` sends an approved template from the organisation's own WhatsApp Business account (named \"WhatsApp campaign\" by default).","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsMarketingCampaignWrite"}}}},"responses":{"201":{"description":"Created as a draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsMarketingCampaign"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/email-marketing/sms/campaigns/{campaign_id}":{"get":{"operationId":"getSmsMarketingCampaign","tags":["zinn-campaigns"],"summary":"One bulk SMS campaign.","description":"Gated on `email_marketing.view`.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The campaign.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsMarketingCampaign"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"operationId":"updateSmsMarketingCampaign","tags":["zinn-campaigns"],"summary":"Edit a draft (or a refused campaign, which returns to draft).","description":"Gated on `email_marketing.manage`. A campaign that is sending, paused or sent cannot be edited (`409`).","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsMarketingCampaignWrite"}}}},"responses":{"200":{"description":"Saved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsMarketingCampaign"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/email-marketing/sms/campaigns/{campaign_id}/send":{"post":{"operationId":"sendSmsMarketingCampaign","tags":["zinn-campaigns"],"summary":"Start sending an SMS to everyone on its list who agreed to SMS — or resume one paused for credit.","description":"Gated on `email_marketing.manage`. The gate runs first, in order: the line is open, SMS is open to the account, the account is in good standing, the campaign is complete and within the length limit, SMS is not paused, someone on the list may be texted (a member, subscribed, with a number, an SMS consent and no STOP), and staff have reviewed a send above the review size. Each refusal is its own `409` code (`CAMPAIGNS_SMS_<CODE>`). On `202` a durable workflow sends in batches; each message is priced and paid from the account's credit before it leaves. When the credit runs out the campaign pauses (`no_credit`) and this call resumes it after a top-up. STOP replies or carrier rejections over the line pause the account's SMS; staff resume it. A `whatsapp` campaign runs the same gate on WhatsApp's own switch, consent and pause, needs a complete template and the organisation's own connected WhatsApp Business account (`own_sender_required`), and costs 0 Zinn® credit (Meta bills that account). If Meta stops accepting that account's messages the campaign pauses as `whatsapp_not_ready`; the customer fixes the account and this call resumes it. A WhatsApp pause never pauses SMS campaigns, and the reverse.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Already sending or sent; nothing changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsMarketingCampaign"}}}},"202":{"description":"Sending has started (or resumed).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsMarketingCampaign"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/Conflict"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/email-marketing/sms/campaigns/{campaign_id}/report":{"get":{"operationId":"getSmsMarketingCampaignReport","tags":["zinn-campaigns"],"summary":"A bulk SMS campaign's numbers.","description":"Gated on `email_marketing.view`. `spent_usd_micros` is what the sent messages cost the account.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsMarketingCampaignReport"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/webhooks/campaigns/telnyx":{"post":{"operationId":"receiveCampaignsTelnyxInbound","tags":["zinn-campaigns"],"security":[],"summary":"Inbound SMS replies (STOP / START) and delivery receipts from our SMS vendor.","description":"**Unauthenticated by design**: the vendor's Ed25519 signature over `timestamp|raw body` (`telnyx-signature-ed25519`, `telnyx-timestamp`), checked with the public key held in the Campaigns settings, is the authentication — `401` when it does not verify or is older than five minutes, `503` while no key is configured (never accepted unverified). A `message.received` whose whole text is a STOP word opts the number out of SMS for every account holding it as a contact; START removes those reply opt-outs. A `message.finalized` records the delivery receipt (`delivered`, `failed` with the vendor's error code, or `unconfirmed`) on the paid message with that vendor id; an unknown status is left awaiting. Anything else is acknowledged and ignored. Redelivery is a no-op.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Accepted.","content":{"application/json":{"schema":{"type":"object","required":["ok","handled"],"properties":{"ok":{"type":"boolean"},"handled":{"type":"string","enum":["stop","start","no_keyword","ignored","receipt","unknown_message","unknown_status","no_message_id"]},"orgs":{"type":"integer"},"delivery":{"type":"string","enum":["delivered","failed","unconfirmed"]}}}}}},"400":{"description":"Not JSON."},"401":{"description":"The signature did not verify."},"503":{"description":"No signing key is configured."}}}},"/v1/webhooks/campaigns/whatsapp":{"get":{"operationId":"verifyCampaignsWhatsappWebhook","tags":["zinn-campaigns"],"security":[],"summary":"Meta's webhook verify-token handshake for WhatsApp.","description":"**Unauthenticated by design.** With `hub.mode=subscribe` and `hub.verify_token` equal to the token we gave Meta when the app was subscribed, answers `hub.challenge` as plain text; anything else is `403`, and `503` while no token is configured.","parameters":[{"name":"hub.mode","in":"query","required":false,"schema":{"type":"string"}},{"name":"hub.verify_token","in":"query","required":false,"schema":{"type":"string"}},{"name":"hub.challenge","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The challenge, echoed.","content":{"text/plain":{"schema":{"type":"string"}}}},"403":{"description":"Not our handshake."},"503":{"description":"No verify token is configured."}}},"post":{"operationId":"receiveCampaignsWhatsappWebhook","tags":["zinn-campaigns"],"security":[],"summary":"WhatsApp delivery receipts and STOP replies from Meta.","description":"**Unauthenticated by design**: `X-Hub-Signature-256` (`sha256=` + the HMAC-SHA256 of the raw body under the secret of one of our Meta apps) is the authentication — `401` when it is missing or does not verify, `503` while no app secret is configured (never accepted unverified). A verified body is queued for a background run and acknowledged at once; `503` when it cannot be queued (Meta retries). The run records each `statuses[]` entry on the paid WhatsApp message with that id (`delivered` or `read`, both recorded as delivered, or `failed` with Meta's error code; the first receipt stands, so a redelivery is a no-op); a `failed` with code `131050` (the person stopped marketing messages in WhatsApp) opts the number out. A `messages[]` entry whose whole text or quick-reply button is a STOP word (STOP, UNSUBSCRIBE, \"Stop promotions\", ...) opts the number out of WhatsApp for the account whose connected number it reached (for our own number, every account holding it as a contact); START removes a reply opt-out. Every later WhatsApp send to that number is refused as `suppressed`.","parameters":[{"name":"X-Hub-Signature-256","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Verified and queued.","content":{"application/json":{"schema":{"type":"object","required":["ok","queued"],"properties":{"ok":{"type":"boolean"},"queued":{"type":"string","description":"The background run handling this body."}}}}}},"400":{"description":"Not a JSON object."},"401":{"description":"The signature is missing or did not verify."},"503":{"description":"No app secret is configured, or the event could not be queued."}}}},"/v1/agents":{"get":{"operationId":"listAgents","tags":["zinn-agents"],"summary":"The organisation's agents, free plan slots, apps and plans.","description":"Gated on `agents.view`. `free_slots` are paid Zinn® Agents plans (or an active trial) with no agent deployed on them yet; `plans` carry the monthly price and, where the organisation has never held a Zinn® Agents plan, the first-month intro price, in the requested currency. `open` is false while the product is switched off for this account. Everything answers for ONE organisation: `org_id` (the dashboard sends its selected org as `X-Zinn-Org`, which stands in for it), or the caller's only organisation. A caller in several organisations that names none, or names one outside its scope, gets an empty answer rather than a guess.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"currency","in":"query","required":false,"schema":{"type":"string","minLength":3,"maxLength":3,"default":"USD"}}],"responses":{"200":{"description":"The agents and what can be deployed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createAgent","tags":["zinn-agents"],"summary":"Deploy one agent app on a free Zinn® Agents plan slot.","description":"Gated on `agents.manage`. Binds the app to one free slot (the named `slot_id`, or the oldest free one) and starts the durable provisioning workflow; the agent answers `provisioning` until its pod is ready, then `running`. Refused with `402 NO_PLAN` when there is no free slot, `409 PLAN_TOO_SMALL` when the plan's memory is below the app's minimum, `409 TOO_MANY` at the per-organisation ceiling, `403 NOT_OPEN` while the product is off for the account, and `400 UNKNOWN_APP` (n8n is never offered here — its licence allows it only on the customer's own Private Cloud server). The agent is created in `org_id` (or the `X-Zinn-Org` the dashboard sends); with neither, only a caller in a single organisation can deploy — a caller in several gets `404` rather than a guess.","parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCreate"}}}},"responses":{"201":{"description":"The agent, provisioning.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"400":{"$ref":"#/components/responses/UnprocessableEntity"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"No free Zinn® Agents plan to deploy on.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/agents/{agentId}":{"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAgent","tags":["zinn-agents"],"summary":"One agent.","responses":{"200":{"description":"The agent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"operationId":"updateAgent","tags":["zinn-agents"],"summary":"Rename an agent, choose its model, or set its monthly AI spend cap.","description":"Gated on `agents.manage`. `model` empty or `zinn-default` follows the cheapest verified model; `monthly_cap_micros` null removes the per-agent cap (the organisation's balance still bounds spend). The gateway refuses a call BEFORE spending once the cap is reached.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentUpdate"}}}},"responses":{"200":{"description":"The agent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"operationId":"deleteAgent","tags":["zinn-agents"],"summary":"Delete an agent and destroy its data volume.","responses":{"202":{"description":"Deleting; the plan slot frees once it is gone.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/agents/{agentId}/pause":{"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"pauseAgent","tags":["zinn-agents"],"summary":"Pause an agent (its data is kept; it stops using compute and AI).","responses":{"202":{"description":"Pausing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/agents/{agentId}/resume":{"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"resumeAgent","tags":["zinn-agents"],"summary":"Resume a paused agent.","description":"Refused with `402 NOT_IN_GOOD_STANDING` while the agent's plan is unpaid (it then resumes on its own once paid) and `403 STAFF_PAUSED` when Zinn® staff paused it.","responses":{"202":{"description":"Resuming.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"The plan is not in good standing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/agents/{agentId}/login":{"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"revealAgentLogin","tags":["zinn-agents"],"summary":"Show how to sign in to the agent app (its token or password).","description":"Gated on `agents.login.reveal` — its own permission, held by the organisation OWNER only (not `dev`, not any read role), because the secret opens the agent and everything it is connected to. Every call is audit-logged as `agent.login_revealed`; the audit row and the logs carry no part of the secret. The secret is recomputed from the agent id on each call and stored nowhere. `method` is `password` (Hermes: `username` + `secret` — a backup; the Open button already signs in), `open` (OpenClaw: no secret exists — our sign-in check in front of the agent signs the owner in from `openAgent`), `app_account` (Paperclip, Activepieces: the app has its own account sign-up on first visit; no secret), or `token` (an app that reads its token from a URL fragment; none today). Refused with `409 LOGIN_PAUSED` while the agent is paused and `402 LOGIN_UNPAID` while its plan is not in good standing. ⛔ **A POST rather than a GET on purpose**: a GET would put the credential in browser history and proxy logs. The response is `Cache-Control: no-store`.","responses":{"200":{"description":"The sign-in details.","headers":{"Cache-Control":{"schema":{"type":"string","enum":["no-store"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentLogin"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"The agent's plan is not in good standing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The agent is paused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agents/{agentId}/open":{"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"openAgent","tags":["zinn-agents"],"summary":"A one-click, single-use link that opens the agent app signed in.","description":"Every `*.zinnagents.com` request passes our sign-in check before it can reach the agent's pod (docs/1047 §12): only the OWNER of the agent's organisation gets through (`agents.login.reveal`; not `dev`, not any read role, not an owner of another organisation), and everyone else gets 401/403 from the check. This call returns `url` — `https://<agent>/_zinn/open?t=<ticket>` — where the ticket is signed, bound to this agent, its organisation, the caller and the agent's host, valid for `expires_in` seconds and redeemable ONCE. Redeeming it audit-logs `agent.edge_login`, sets a host-only session cookie on the agent's host and redirects to the app, already signed in: OpenClaw runs in trusted-proxy mode with device auto-approval (no token, no pairing step) and Hermes receives its basic-auth credentials from the check. The session is re-checked on every request, so a removed owner or a paused agent loses access within seconds. Session users only (an API key gets 404). Refused with `409 LOGIN_PAUSED` while the agent is paused and `402 LOGIN_UNPAID` while its plan is not in good standing. A POST, `no-store`.","responses":{"200":{"description":"The link.","headers":{"Cache-Control":{"schema":{"type":"string","enum":["no-store"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentOpenLink"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"The agent's plan is not in good standing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The agent is paused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agents/{agentId}/memory":{"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getAgentMemory","tags":["zinn-agents"],"parameters":[{"name":"currency","in":"query","required":false,"schema":{"type":"string"},"description":"The currency to price `unit_price` in (as on the agents list)."}],"summary":"The agent's \"+1 GB memory\" add-on — what counts now, the price per GB, how many more.","description":"`plan_mb` is the plan's memory; `addon_gb` the add-on GB that count today (an add-on counts while it is paid: a refunded, stopped-and-expired or unpaid-renewal-paused one does not); `effective_mb` = plan + add-on (the pod's guaranteed REQUEST) and `limit_mb` twice it (the burst limit); `applied_addon_mb` what the running pod was last started with. `unit_price` is ONE GB per month in the caller's currency (integer minor units). `offered` is false while the add-on's launch switch is off for this organisation. docs/1047 §13.","responses":{"200":{"description":"The memory panel.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentMemory"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"buyAgentMemory","tags":["zinn-agents"],"summary":"Buy N GB of extra memory for this agent, billed monthly per GB.","description":"Needs `agents.manage` and `billing.payment.manage`. Priced unit × `gb` in the chosen currency, taxed, and renewed monthly like every add-on; the agent restarts with the new memory within minutes. With no stored payment method nothing is charged: the purchase waits and `422 PAYMENT_METHOD_REQUIRED` carries `payment` (the order to pay in place). Refused BEFORE any charge with `403 MEMORY_NOT_OPEN` (not on sale yet), `409 MEMORY_NOT_RUNNING` (paused agent or unpaid plan), `409 MEMORY_CEILING` (one agent uses at most 8 GB), `409 MEMORY_POOL_FULL`, `400 MEMORY_QUANTITY`. Never bought twice by a repeat: an `Idempotency-Key` retry replays the first answer, and the same caller asking for the same GB on the same agent within 60 seconds (a double click, a retry with a fresh key) gets `200` naming the purchase already made — nothing is charged again.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["gb"],"properties":{"gb":{"type":"integer","minimum":1,"maximum":8},"currency":{"type":"string","description":"The currency the customer was quoted in."},"gateway":{"type":"string","description":"The payment rail the customer chose."}}}}}},"responses":{"200":{"description":"A repeat of a buy made in the last 60 seconds — the purchase already made, nothing charged again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentMemoryPurchase"}}}},"201":{"description":"Bought; the agent is being restarted with the memory.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentMemoryPurchase"}}}},"400":{"description":"Bad quantity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Refused before any charge.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Waiting for payment, or declined.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agents/{agentId}/memory/{purchaseId}/stop":{"parameters":[{"name":"agentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"purchaseId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"stopAgentMemory","tags":["zinn-agents"],"summary":"Stop one memory add-on renewing; it keeps working to the end of the paid month.","description":"No refund; `ends_on` is the last day it counts (null for a comp or one already stopped). After it the agent restarts with its plan's memory. Needs `agents.manage` and `billing.payment.manage`.","responses":{"200":{"description":"Stopped.","content":{"application/json":{"schema":{"type":"object","required":["purchase_id","ends_on","memory"],"properties":{"purchase_id":{"type":"string","format":"uuid"},"ends_on":{"type":"string","format":"date","nullable":true},"memory":{"$ref":"#/components/schemas/AgentMemory"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/agent-gateway/chat/completions":{"post":{"operationId":"agentGatewayChatCompletions","tags":["zinn-agents"],"summary":"OpenAI-compatible chat completions for an agent app, metered on Zinn® AI credit.","description":"Called by the agent apps themselves with their per-agent key (`Authorization: Bearer zak_…`), never by a person. `model` = `zinn-default` resolves per call to the cheapest verified model; any model id from `/v1/agent-gateway/models` may be named. Refused BEFORE any spend when the agent is paused, its plan is not in good standing, its monthly cap is reached, or the organisation has no Zinn® AI credit and no own key — errors use the OpenAI error envelope with a `zinn_failure` class. `stream: true` is answered as server-sent events.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["messages"],"additionalProperties":true,"properties":{"model":{"type":"string","default":"zinn-default"},"messages":{"type":"array","items":{"type":"object","additionalProperties":true}},"tools":{"type":"array","items":{"type":"object","additionalProperties":true}},"tool_choice":{},"max_tokens":{"type":"integer"},"max_completion_tokens":{"type":"integer"},"temperature":{"type":"number"},"stream":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"An OpenAI `chat.completion` object (or an SSE stream when `stream` is true).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}},"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"The request is not a valid chat completion.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentGatewayError"}}}},"401":{"description":"Invalid agent key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentGatewayError"}}}},"402":{"description":"No credit, spend cap reached, or the plan is not in good standing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentGatewayError"}}}},"403":{"description":"The agent is paused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentGatewayError"}}}},"502":{"description":"The AI provider could not answer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentGatewayError"}}}}}}},"/v1/agent-gateway/models":{"get":{"operationId":"agentGatewayModels","tags":["zinn-agents"],"summary":"The models an agent may name (OpenAI `list` shape).","security":[],"responses":{"200":{"description":"The model list, `zinn-default` first.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Invalid agent key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentGatewayError"}}}}}}},"/v1/databases/catalogue":{"get":{"operationId":"getManagedDatabaseCatalogue","summary":"The managed-database sizes and engine versions on sale.","description":"What may be bought right now, per engine. Gated on `databases.view`. Each engine's versions are served from its own fence, so a major approaching end of life disappears from the picker with no frontend change — we stop selling one 180 days before upstream stops patching it, because a customer part-way through a term must never be stranded on an unpatched engine. MySQL 8.0 is the one exception and it says so: it is past upstream end of life, offered under a recorded carve-out on Percona's patched build, and flagged `past_upstream_eol` so a customer choosing it knows what they are choosing.","tags":["databases"],"responses":{"200":{"description":"The sizes and engine versions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedDatabaseCatalogue"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/databases/my-address":{"get":{"operationId":"getManagedDatabaseClientAddress","summary":"The address this request came from, to suggest for a database allow-list.","description":"Gated on `databases.view`. A database hostname publishes both an A and an AAAA record, so a client that prefers IPv6 connects from its IPv6 address and is refused if only its IPv4 address is listed. The dashboard offers this address (and the one its own origin sees, which may be the other family) so the customer can add both. Read from the forwarding header our own ingress writes, never from a value the caller supplies; `address` is null when it cannot be resolved.","tags":["databases"],"responses":{"200":{"description":"The caller's public address, or null.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedDatabaseClientAddress"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/databases":{"get":{"operationId":"listManagedDatabases","summary":"The organisation's managed databases.","description":"Every managed database in scope. Gated on `databases.view`. ⛔ Never includes the password — see `POST /v1/databases/{databaseId}/credentials`.","tags":["databases"],"responses":{"200":{"description":"The databases.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedDatabaseList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createManagedDatabase","summary":"Validate a managed database, and say where to buy it.","description":"⛔ **This endpoint no longer creates a database — it always answers `422`** (`docs/497` §8). Until 2026-09-05 it created a real cluster for nothing: no order, no invoice, no subscription and no charge, so a customer could run a highly-available database that never appeared on any bill.\n\nA managed database is **bought**: `POST /v1/carts/{cartId}/lines` with `kind=managed_database` and a `database` block, then checkout. Fulfilment creates the instance in `provisioning` and starts the Temporal workflow that builds it.\n\nThe request is still **validated first**, so a caller learns *why* it would be refused before it goes to the basket and pays: the account is not in good standing, the label is blank or already used in this organisation, the size is not on sale, the engine or version is not one we run, the size belongs to a different engine, or the organisation already holds the self-service maximum. Only when all of that passes does it answer with the `PURCHASE_REQUIRED` code that names the basket.\n\nGated on `databases.manage` in addition to `databases.view`.","tags":["databases"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedDatabaseCreate"}}}},"responses":{"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/databases/{databaseId}":{"parameters":[{"name":"databaseId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getManagedDatabase","summary":"One managed database.","description":"Everything needed to understand and operate the database — host, port, database name, username, size, backup history and whether a restore has ever been proved. Gated on `databases.view`. ⛔ Never includes the password.","tags":["databases"],"responses":{"200":{"description":"The database.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedDatabase"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"operationId":"deleteManagedDatabase","summary":"Delete a managed database and its backups.","description":"Gated on `databases.manage`. Returns `202` — the instance moves to `deleting` and **stops accruing charges at that moment**, not when the last volume detaches; teardown latency is ours, not the customer's. ⛔ Irreversible: the cluster, its volumes and its backup chain all go.","tags":["databases"],"responses":{"202":{"description":"Accepted; the database is being torn down.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedDatabase"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/databases/{databaseId}/allowed-ips":{"parameters":[{"name":"databaseId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"listManagedDatabaseAllowedIps","summary":"Which sources may connect to this database.","description":"Gated on `databases.view`. The allow-list is **default-deny**: a new database reaches nobody until a source is added — an empty list means nothing on earth can connect, which is the opposite of what \"no rules\" usually reads as.","tags":["databases"],"responses":{"200":{"description":"The allow-list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedDatabaseAllowedIpList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"allowManagedDatabaseAddress","summary":"Permit a source address or range to connect.","description":"Gated on `databases.manage`. A bare address is normalised to a `/32` or `/128`. Refused with 422 for an address inside our own cluster network (which would let any pod — including another tenant's database — reach this one), for an unparseable value, for a missing description, and for `0.0.0.0/0` unless `acknowledge_public` is true.","tags":["databases"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedDatabaseAllowedIpCreate"}}}},"responses":{"201":{"description":"The created rule.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedDatabaseAllowedIp"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/databases/{databaseId}/allowed-ips/{ruleId}":{"parameters":[{"name":"databaseId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"ruleId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"delete":{"operationId":"revokeManagedDatabaseAddress","summary":"Revoke a source's access.","description":"Gated on `databases.manage`. Audit-logged.","tags":["databases"],"responses":{"204":{"description":"Revoked."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/databases/{databaseId}/upgrade":{"parameters":[{"name":"databaseId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"upgradeManagedDatabase","summary":"Move the database to a newer PostgreSQL major.","description":"Gated on `databases.manage`. Returns `202` — the upgrade runs as a durable workflow because the operator rolls the primary over to an upgraded replica, which takes minutes and must survive a deploy or the customer closing the tab. ⛔ Refused with 422 when the target is not a major we run, when it is not newer than the current one (downgrading is not possible), and — importantly — when **the database has never been backed up**: if a switchover goes wrong the way back is a restore, and a restore with no backup is not a way back.","tags":["databases"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedDatabaseUpgrade"}}}},"responses":{"202":{"description":"Accepted; the upgrade is running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedDatabase"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/databases/{databaseId}/credentials":{"parameters":[{"name":"databaseId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"revealManagedDatabaseCredentials","summary":"Reveal the database password.","description":"Gated on `databases.credentials.reveal` — its own permission, held by no read-only role, because this is the one call that moves a secret opening every row the customer has. Every call is audit-logged. ⛔ **A POST rather than a GET on purpose.** A GET would put the credential in browser history, proxy logs and `Referer` headers.","tags":["databases"],"responses":{"200":{"description":"The credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedDatabaseCredentials"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/boards":{"get":{"operationId":"listAgencyBoards","summary":"The agency's project boards.","description":"Boards this agency runs client work on. Archived boards are excluded unless `include_archived` is set — a board carries the client's question history and the record of what was delivered, so it is archived rather than deleted.","tags":["agency-board"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Narrow to one organisation in the caller's subtree. ⛔ **Narrow only** — it is intersected with what the caller may already read, so it can never widen scope."},{"name":"client_org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Only boards whose work is for this client organisation."},{"name":"include_archived","in":"query","required":false,"schema":{"type":"boolean","default":false}},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"A page of boards.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"createAgencyBoard","summary":"Create a project board.","description":"Creates the board **and a working default pipeline** — Requests · Backlog · In progress · Review · Done — with *Requests* marked as the client intake column and *Requests*, *In progress* and *Done* already client-visible. ⛔ Not a placeholder (§2.41): the board is usable by an agency and by its client the moment it exists, rather than after a configuration step nobody documents.\n\nRequires the `agency_project_board` entitlement on the acting org.","tags":["agency-board"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardCreate"}}}},"responses":{"201":{"description":"The new board.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoard"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/time/projects":{"get":{"operationId":"listTimeProjects","summary":"The agency's time-tracking projects.","description":"Bodies of work an agency logs time against. A project with no `client_id` is **internal** work — reported on, never invoiced — which an agency needs or the timesheet stops being a record of where the week went.","tags":["agency-time"],"parameters":[{"name":"client_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"include_archived","in":"query","required":false,"schema":{"type":"boolean","default":false}},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"A page of projects.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeProjectPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createTimeProject","summary":"Create a time-tracking project.","description":"Requires `agency.time.manage` and the `agency_project_board` entitlement.\n\n`currency` is set on the PROJECT rather than derived from whichever rate card wins, because an invoice has exactly one currency: a project whose rates disagreed would produce a document that cannot be issued. A rate card in another currency is refused rather than converted — FX is a driver decision, not a timesheet's.","tags":["agency-time"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeProjectCreate"}}}},"responses":{"201":{"description":"The new project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeProject"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/time/projects/from-quote":{"post":{"operationId":"createTimeProjectFromQuote","summary":"Start a project from a free-quote request.","description":"Zinn Digital®'s own organisation only (docs/670 §2). In one transaction: the requester becomes a client (found by e-mail, or created, carrying the request's country), a project board is opened with the brief, a time project is linked to both in the quoted currency, the quoted price becomes a fixed-price task, and the request is marked `won` — which is what stops the admin queue's charge conversion and the draft-from-quote invoice billing the same job again.\n\nRequires `agency.time.manage` in the organisation **and** the `quotes.manage` staff permission the admin queue requires. Idempotent per request: a second call returns the project the first one made, with `created: false`.","tags":["agency-time"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeProjectFromQuote"}}}},"responses":{"200":{"description":"The project this request had already become.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeProjectFromQuoteResult"}}}},"201":{"description":"The new client, board and project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeProjectFromQuoteResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/time/projects/{projectId}":{"patch":{"operationId":"updateTimeProject","summary":"Rename, re-assign or archive a project.","description":"⛔ Archiving hides a project from the pickers; it never deletes it. Time already logged against it stays on the timesheet and on any invoice it reached, because a project is part of how that money was arrived at.\n\nChanging `client_id` re-points FUTURE work only — an entry denormalises its client at creation, so hours already logged stay attributed to the client they were done for.","tags":["agency-time"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeProjectUpdate"}}}},"responses":{"200":{"description":"The updated project.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeProject"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/time/tasks":{"get":{"operationId":"listTimeTasks","summary":"The named pieces of work inside a project.","description":"A task is the finest thing a rate can be set on — the owner's *\"a per hour rate for each thing\"*. `fixed_price_billed` says whether a fixed-price task has already been invoiced, so the screen can say \"already billed\" rather than showing it as free work.","tags":["agency-time"],"parameters":[{"name":"project_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"include_archived","in":"query","required":false,"schema":{"type":"boolean","default":false}},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"A page of tasks.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeTaskPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createTimeTask","summary":"Add a task to a project.","description":"A task is the finest scope a rate can be set on, and the thing a **fixed price** attaches to. Requires `agency.time.manage`.","tags":["agency-time"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeTaskCreate"}}}},"responses":{"201":{"description":"The new task.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeTask"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/time/tasks/{taskId}":{"patch":{"operationId":"updateTimeTask","summary":"Rename or archive a task.","description":"⛔ Archives; never deletes, and the database enforces it — `TimeEntry.task` is `PROTECT`ed, so a task with hours against it cannot be removed. Deleting one would orphan the record of what those hours were for.","tags":["agency-time"],"parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeTaskUpdate"}}}},"responses":{"200":{"description":"The updated task.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeTask"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/agency/time/entries":{"get":{"operationId":"listTimeEntries","summary":"The timesheet.","description":"Logged minutes, newest first. An entry that has not been billed carries `rate_minor_per_hour` — the rate that WOULD apply, resolved against its own `work_date` — so the timesheet shows what an hour is worth before it is invoiced.\n\n⛔ `null` there means **unpriced**, not free. Work with no rate card is shown as unpriced with the remedy on the screen; it is never invoiced at zero, because billing it at zero would take it out of the unbilled pool for ever and the agency could never charge for it once the rate was set.","tags":["agency-time"],"parameters":[{"name":"client_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"project_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"user_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"billed","in":"query","required":false,"schema":{"type":"boolean"},"description":"Only billed (`true`) or only outstanding (`false`) work."},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"A page of time entries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeEntryPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createTimeEntry","summary":"Log time.","description":"`minutes` is an integer, 1..1440. Requires `agency.time.log` for your own time, or `agency.time.manage` to pass `user_id` and log on somebody else's behalf.\n\nIf this client's billing schedule is *\"invoice straight away\"*, logging arms it and starts the billing workflow immediately — the invoice is raised in seconds rather than at the next sweep, without the invoicing call ever sitting in this request.","tags":["agency-time"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeEntryCreate"}}}},"responses":{"201":{"description":"The logged entry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeEntry"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/time/entries/{entryId}":{"patch":{"operationId":"updateTimeEntry","summary":"Correct a time entry.","description":"⛔ An entry that has been invoiced cannot be changed — 422. Changing the minutes on an invoiced line would make the timesheet disagree with a document the client is holding; the remedy is to void the draft invoice, which releases the time back into the pool.","tags":["agency-time"],"parameters":[{"name":"entryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeEntryUpdate"}}}},"responses":{"200":{"description":"The updated entry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeEntry"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"deleteTimeEntry","summary":"Delete a time entry.","description":"⛔ Refused with 422 once the entry has been invoiced. Void the draft first.","tags":["agency-time"],"parameters":[{"name":"entryId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/time/rates":{"get":{"operationId":"listTimeRates","summary":"The agency's rate cards.","description":"Resolution is most-specific-first — **task → project → client → organisation default** — taking the newest card whose `effective_from` is on or before the **work's** date.\n\n⛔⛔ Against the work's date, never against today. An agency that raises its rate on the 1st must still bill last month at last month's rate; resolving on `now()` silently re-prices every unbilled hour behind it, upward, which is the direction nobody checks.","tags":["agency-time"],"parameters":[{"name":"include_archived","in":"query","required":false,"schema":{"type":"boolean","default":false}},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"A page of rate cards.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeRatePage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createTimeRate","summary":"Set a rate.","description":"`amount_minor` is the price of ONE HOUR for `kind: hourly`, and the price of the whole job for `kind: fixed`.\n\n⛔ A fixed price is billed **once** for the task it is set on, however many hours are logged against it — the minutes are still recorded and reported, they simply do not each carry money. It is not \"an hourly rate of zero\".","tags":["agency-time"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeRateCreate"}}}},"responses":{"201":{"description":"The new rate card.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeRate"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/time/rates/{rateId}":{"delete":{"operationId":"archiveTimeRate","summary":"Archive a rate card.","description":"⛔ Archives; never deletes. A rate card that priced an invoice is part of how that money was arrived at, and a deleted row makes an issued document unexplainable.","tags":["agency-time"],"parameters":[{"name":"rateId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The archived rate card.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeRate"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/agency/time/schedules":{"get":{"operationId":"listTimeBillingSchedules","summary":"When each client is invoiced.","description":"One row per client, plus one org-wide default (`client_id: null`) covering every client without a row of its own. A per-client row **replaces** the default rather than layering on it — merging two partial schedules would let one client be billed twice.\n\nBoth cursor columns are on the wire. `last_attempted_at` is advanced for every schedule the sweep reaches, before its result is read; `last_succeeded_at` is what a staleness alarm reads. A screen showing only the first cannot tell a healthy client from one that has been failing for a month.","tags":["agency-time"],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"A page of billing schedules.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeBillingSchedulePage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"setTimeBillingSchedule","summary":"Set a client's billing trigger.","description":"Idempotent by `(org, client)` — a second POST updates rather than creating a second row, because two schedules for one client is the arrangement that bills them twice.\n\nFour triggers: `manual` (on demand only), `on_log` (immediately, as time is logged), `day_of_month`, and `threshold` (when unbilled work reaches an amount).\n\n⛔ `day_of_month` is 1–28, and that is not a limitation of the storage. A schedule set to the 31st would silently skip February, April, June, September and November — seven months a year in which the agency is not paid and nothing is red. \"The end of the month\" is expressed as 28.","tags":["agency-time"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeBillingScheduleWrite"}}}},"responses":{"200":{"description":"The updated schedule.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeBillingSchedule"}}}},"201":{"description":"The new schedule.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeBillingSchedule"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/time/schedules/{scheduleId}":{"delete":{"operationId":"deleteTimeBillingSchedule","summary":"Remove a billing schedule.","description":"Removes this client's schedule. ⭐ They then fall back to the organisation's default (`client_id: null`) if one exists, and to nothing otherwise — meaning invoices are raised only when somebody presses **Create draft invoice**. No time is affected either way.","tags":["agency-time"],"parameters":[{"name":"scheduleId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/agency/time/unbilled":{"get":{"operationId":"getUnbilledTime","summary":"What is outstanding, per client and currency.","description":"The **same** figure a threshold trigger fires on — one function, deliberately, because two implementations of \"how much is outstanding\" is how a client is shown £900 and invoiced £1,100.\n\n`unpriced_minutes` is reported separately from the money: hours logged against work with no rate card are not worth zero, they are unpriced, and an agency that cannot see them will not fix them. `can_bill` says whether the invoicing suite is reachable at all, so the console never offers a Bill-now button that can only refuse.","tags":["agency-time"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"client_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"until","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Only count work up to and including this date."}],"responses":{"200":{"description":"The unbilled pool.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnbilledTime"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/time/billing-runs":{"get":{"operationId":"listTimeBillingRuns","summary":"Billing history — what has been billed, and what it consumed.","description":"`actual` is derived from the time entries themselves rather than read off the run's stored columns, so a divergence between what was sent to the invoicing suite and what the rows now say is visible on the screen instead of theoretical.","tags":["agency-time"],"parameters":[{"name":"client_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["claimed","invoiced","failed","released"]}},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"A page of billing runs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeBillingRunPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createTimeBillingRun","summary":"Bill now — turn unbilled time into a draft invoice.","description":"The owner's *\"as well as sending on demand invoices\"*. Claims the client's unbilled, priced work, hands it to the agency invoicing suite as a **draft**, and records what came back.\n\n⛔ The entries are claimed in a committed transaction **before** the invoicing suite is called, so no other trigger can select them while the call is in flight. The idempotency key handed to the suite is derived from the sorted entry ids rather than minted, so a retry after a crash is given back the invoice that already exists instead of raising a second one for the same hours.\n\n`reconcile_state` is `ok` only when the invoice's total for these lines equals our own exact arithmetic. `mismatch` means do not send it.","tags":["agency-time"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeBillNow"}}}},"responses":{"201":{"description":"The billing run and the draft invoice it raised.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeBillingRun"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/time/report":{"get":{"operationId":"getTimeReport","summary":"Time reporting for a period, by person, client and project.","description":"⛔ **Unbilled, unpriced and non-billable are three different things and this says which.** Collapsing them is how an agency loses money quietly: hours with no rate card and hours marked internal both contribute nothing to revenue, but one is money about to be lost and the other is a decision they made.\n\n`billable_minutes` is the total minus non-billable — *not* \"billed\". An hour logged as billable and not yet invoiced is billable work, and calling it anything else is how an agency talks itself out of chasing it.","tags":["agency-time"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Defaults to the first of the current month."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Defaults to today."},{"name":"client_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"user_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeReport"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/time/quote-requests":{"get":{"operationId":"listTimeQuoteRequests","summary":"Free-quote requests that could still become a project.","description":"Open requests (`new` or `quoted`), oldest first, capped at 200 with the true total beside them. Zinn Digital®'s own organisation only; requires `agency.time.manage` and the `quotes.manage` staff permission the admin queue requires (docs/670 §2).","tags":["agency-time"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The open requests.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeQuoteRequestList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/time/checkout-bills/{billId}/send":{"post":{"operationId":"sendTimeCheckoutBill","summary":"E-mail a checkout bill raised from tracked time.","description":"Mails the pay link to the client, then marks the bill sent — in that order, so a bill is never shown as sent that did not leave. Only a bill time tracking raised; requires `agency.time.manage` and the `billing.entitlement.manage` staff permission (docs/670 §3).","tags":["agency-time"],"parameters":[{"name":"billId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeCheckoutBillSend"}}}},"responses":{"200":{"description":"The bill, now sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeCheckoutBill"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/agency/time/checkout-bills/{billId}/void":{"post":{"operationId":"voidTimeCheckoutBill","summary":"Withdraw an unpaid checkout bill; its hours return to the unbilled pool.","description":"The pay link stops working at once and the time the bill carried is released immediately, so it can be billed again. A paid bill cannot be voided. Requires `agency.time.manage` and the `billing.entitlement.manage` staff permission (docs/670 §3).","tags":["agency-time"],"parameters":[{"name":"billId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeCheckoutBillVoid"}}}},"responses":{"200":{"description":"The bill, now void.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeCheckoutBill"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/board-clients":{"get":{"operationId":"listAgencyBoardClients","summary":"The organisations a board may be for.","description":"The client organisations this agency can attach to a board — its own client accounts, searchable by name. Backs the picker on board creation and the \"attach a client\" control on a board that has none.\n\n⛔ The population is exactly `orgs_for(org.read)`, the same set `GET /v1/orgs` returns, so this endpoint exposes nothing new: \"search\" means everything tenancy already lets this caller read, never another tenant's organisations. The acting org is excluded, because a board cannot be its own client.\n\n⭐ Requires `org.read` **as well as** `agency.board.manage`, so a caller who cannot read organisations gets a `403` with a reason rather than an empty page — an empty picker and \"you have no clients\" are otherwise indistinguishable, and the reassuring reading is the wrong one.","tags":["agency-board"],"parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Case-insensitive substring match on the organisation's name."},{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The acting agency organisation. Defaults to the `X-Zinn-Org` header."},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"A page of candidate client organisations, ordered by name.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardClientPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/agency/boards/{boardId}":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"}],"get":{"operationId":"getAgencyBoard","summary":"One board, with its columns, cards and labels.","tags":["agency-board"],"parameters":[{"name":"include_archived","in":"query","required":false,"description":"Include archived cards in `cards`. ⛔ This parameter was on `/cards` from the day the board shipped and NOT here — and this is the endpoint the board screen calls, so an archived card was unreachable from every human surface. Spelled identically to the one on `listAgencyBoardCards` on purpose.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"The board.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"operationId":"updateAgencyBoard","summary":"Rename a board or attach a client organisation to it.","description":"Attaching a client to a board that has none is always allowed — that is how a board created for internal work becomes a client's board.\n\n⛔ **Changing or clearing a client that is already attached is refused with a `422` once the client has seen anything on the board** — a client-visible card, a question asked of them, or one of their people invited to it. Re-pointing such a board would hand a second client the first one's brief, answers and complaints through a screen whose whole promise is that a client sees only what the agency shared. Archive the board and start a new one for the other client. Sending the client id the board already holds is not a change and is never refused, so a rename carrying the whole form still works.","tags":["agency-board"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardUpdate"}}}},"responses":{"200":{"description":"The updated board.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoard"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"archiveAgencyBoard","summary":"Archive a board.","description":"Archives rather than deletes — the history is what somebody asks about later.","tags":["agency-board"],"responses":{"204":{"description":"Archived."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/agency/boards/{boardId}/columns":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"}],"get":{"operationId":"listAgencyBoardColumns","summary":"The board's columns.","tags":["agency-board"],"responses":{"200":{"description":"The columns, in board order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardColumnList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"createAgencyBoardColumn","summary":"Add a column.","tags":["agency-board"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardColumnCreate"}}}},"responses":{"201":{"description":"The new column.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardColumn"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/boards/{boardId}/columns/{columnId}":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"},{"$ref":"#/components/parameters/AgencyBoardColumnId"}],"patch":{"operationId":"updateAgencyBoardColumn","summary":"Rename a column, change what the client sees, or make it the intake column.","description":"⛔ Setting `visibility` to `internal` hides **every card in the column** from the client at once, by the AND rule — nothing is rewritten on the cards, so setting it back to `client` restores exactly the previous state rather than a guess at it.\n\n`is_intake: true` moves the client's \"raise a request\" column here; at most one column per board holds it, and the previous one is cleared in the same transaction.","tags":["agency-board"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardColumnUpdate"}}}},"responses":{"200":{"description":"The updated column.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardColumn"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"deleteAgencyBoardColumn","summary":"Delete an empty column.","description":"⛔ Refused while the column still holds live cards. Cascading would delete a customer's work as a side effect of tidying a board.","tags":["agency-board"],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/boards/{boardId}/cards":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"}],"get":{"operationId":"listAgencyBoardCards","summary":"The board's cards.","tags":["agency-board"],"parameters":[{"name":"include_archived","in":"query","required":false,"schema":{"type":"boolean","default":false}},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"A page of cards.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardCardPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"createAgencyBoardCard","summary":"Add a payment method.","description":"`visibility` defaults to `internal`. A card is shown to the client only when it is `client` **and its column is too** — the accident is a card the client did not see rather than one they did.","tags":["agency-board"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardCardCreate"}}}},"responses":{"201":{"description":"The new card.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardCard"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/boards/{boardId}/cards/{cardId}":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"},{"$ref":"#/components/parameters/AgencyBoardCardId"}],"get":{"operationId":"getAgencyBoardCard","summary":"One card, with its comments and questions.","tags":["agency-board"],"responses":{"200":{"description":"The card.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardCardDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"operationId":"updateAgencyBoardCard","summary":"Edit a card.","description":"⭐ Sending `assignee_id: null` **unassigns**; omitting the field leaves the assignee alone. The two are different requests and the API distinguishes them, because a `null`-means-absent API cannot express \"unassign\" at all.","tags":["agency-board"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardCardUpdate"}}}},"responses":{"200":{"description":"The updated card.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardCard"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"archiveAgencyBoardCard","summary":"Archive a card.","tags":["agency-board"],"responses":{"204":{"description":"Archived."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/agency/boards/{boardId}/cards/{cardId}/move":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"},{"$ref":"#/components/parameters/AgencyBoardCardId"}],"post":{"operationId":"moveAgencyBoardCard","summary":"Move a card to a column and position.","description":"⛔ The card's own `visibility` is untouched. Moving a shared card into an internal column hides it (the AND), and moving it back reveals exactly what it was — the decision about *this card* survives a change to the *pipeline*.","tags":["agency-board"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardCardMove"}}}},"responses":{"200":{"description":"The moved card.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardCard"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/boards/{boardId}/columns/{columnId}/move":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"},{"$ref":"#/components/parameters/AgencyBoardColumnId"}],"post":{"operationId":"moveAgencyBoardColumn","summary":"Reorder a column in the board's strip.","description":"⛔⛔ A separate operation, because `PATCH` on a column no longer accepts `position` at all. It used to: it wrote the value and shifted no neighbour, so dragging the last column to the front left two columns claiming position 0 and the board fell back to `created_at` order — the write succeeded, the response was 200, and the column appeared not to have moved. This opens a gap and reindexes the strip, exactly as a card move does.\n\n⭐ It returns the WHOLE strip rather than the moved column: a reorder renumbers every neighbour, so a response carrying one column would leave the caller holding stale positions for the rest.","tags":["agency-board"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardColumnMove"}}}},"responses":{"200":{"description":"Every column on the board, in its new order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardColumnList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/boards/{boardId}/cards/{cardId}/checklist":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"},{"$ref":"#/components/parameters/AgencyBoardCardId"}],"get":{"operationId":"listAgencyBoardChecklist","summary":"The card's checklist.","tags":["agency-board"],"responses":{"200":{"description":"Every item on the card's checklist, in order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardChecklistList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"addAgencyBoardChecklistItem","summary":"Append one line to the card's checklist.","description":"⛔ A checklist has no visibility of its own — it inherits the card's. A client shown \"3 of 7 done\" over a list whose four hidden items they cannot see is a progress figure that does not match its own list, which reads as a bug.","tags":["agency-board"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardChecklistItemCreate"}}}},"responses":{"201":{"description":"The new item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardChecklistItem"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/boards/{boardId}/cards/{cardId}/checklist/{itemId}":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"},{"$ref":"#/components/parameters/AgencyBoardCardId"},{"$ref":"#/components/parameters/AgencyBoardChecklistItemId"}],"patch":{"operationId":"setAgencyBoardChecklistItemDone","summary":"Tick or un-tick one checklist item.","description":"⛔ Idempotent, and it records nothing on the board's timeline when the state already matches. A checkbox re-sending its state would otherwise read as \"ticked Deploy, 6 times\" for one tick.\n\n⭐ `done_by` is kept when an item is un-ticked. \"Who ticked this and then un-ticked it\" is a question an agency gets asked by its client, and clearing the field makes it unanswerable while looking tidier.","tags":["agency-board"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardChecklistItemUpdate"}}}},"responses":{"200":{"description":"The item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardChecklistItem"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"deleteAgencyBoardChecklistItem","summary":"Remove one checklist item.","tags":["agency-board"],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/agency/boards/{boardId}/cards/{cardId}/attachments":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"},{"$ref":"#/components/parameters/AgencyBoardCardId"}],"get":{"operationId":"listAgencyBoardCardAttachments","summary":"The files on a card, with the organisation's storage quota.","description":"⭐ The quota travels with the list so a composer can say \"1.2 GB of 2 GB used\" BEFORE somebody picks a 25 MB file and waits for a refusal.","tags":["agency-board"],"responses":{"200":{"description":"The card's files and the org's quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardAttachmentList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"uploadAgencyBoardCardAttachment","summary":"Attach a file to a card.","description":"⚖️ 25 MB per file and 2 GB per organisation, owner-ruled 2026-09-03. The organisation quota is counted across every board it owns, because a per-board cap is escaped by making another board.\n\n⛔⛔ A stored file is `pending` and **not downloadable by anybody, including the agency's own staff**, until a malware scan has passed it. A client's upload is the best phishing route into an agency there is, and the person opening it has production access to that client's sites. `pending`, `infected` and `error` all refuse — an unscannable file is not a clean file.\n\nAccepted types are PNG, JPEG, GIF, WebP, PDF, plain text and CSV, each validated by its magic bytes rather than by the declared content type. No archives (a way to smuggle every format not on the list), no Office documents (macros), no SVG (a script container browsers execute).","tags":["agency-board"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"}}}}}},"responses":{"201":{"description":"The stored file, awaiting its scan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardAttachment"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/boards/{boardId}/cards/{cardId}/attachments/{attachmentId}":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"},{"$ref":"#/components/parameters/AgencyBoardCardId"},{"$ref":"#/components/parameters/AgencyBoardAttachmentId"}],"get":{"operationId":"downloadAgencyBoardCardAttachment","summary":"The file's bytes, if it has passed a scan.","description":"⛔ Served with `Content-Disposition: attachment`, `X-Content-Type-Options: nosniff` and a sandboxing CSP, on the assumption the scan was wrong. Refuses with 422 while the scan is pending and after it fails.","tags":["agency-board"],"responses":{"200":{"description":"The file.","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"patch":{"operationId":"setAgencyBoardCardAttachmentVisibility","summary":"Choose whether the client can see this file.","tags":["agency-board"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardAttachmentUpdate"}}}},"responses":{"200":{"description":"The file.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardAttachment"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"deleteAgencyBoardCardAttachment","summary":"Delete a file and its bytes.","tags":["agency-board"],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/agency/boards/{boardId}/views":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"}],"get":{"operationId":"listAgencyBoardViews","summary":"The board's saved views.","tags":["agency-board"],"responses":{"200":{"description":"Every saved view on the board.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardViewList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"saveAgencyBoardView","summary":"Create or replace a named cut of the board.","description":"⛔ Server-side rather than per-browser, because the value of a saved view is that the whole team opens the same one — on a second laptop, on a phone, and after a browser reset.\n\n⭐ Upsert by name: saving over a view you already have is what a person means by pressing Save with the same name, and a uniqueness error there is a dead end with no remedy in a UI. Unknown keys in `definition` are DROPPED rather than refused, so a newer console and an older engine can coexist during a deploy.","tags":["agency-board"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardViewCreate"}}}},"responses":{"201":{"description":"The saved view.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardView"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/boards/{boardId}/views/{viewId}":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"},{"$ref":"#/components/parameters/AgencyBoardViewId"}],"delete":{"operationId":"deleteAgencyBoardView","summary":"Delete a saved view.","tags":["agency-board"],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/agency/boards/{boardId}/cards/{cardId}/restore":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"},{"$ref":"#/components/parameters/AgencyBoardCardId"}],"post":{"operationId":"restoreAgencyBoardCard","summary":"Take a card back out of the archive.","description":"⛔ A separate operation rather than `PATCH {\"archived_at\": null}`, because `archived_at` is a timestamp the server owns: a caller who may write it may also write a date in 2031, and the position reindex that has to happen alongside it would not. The card returns at the END of its column — the position it held was reindexed away when it was archived, and the bottom is where a person looks for something they have just restored.","tags":["agency-board"],"responses":{"200":{"description":"The restored card.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardCard"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/agency/boards/{boardId}/cards/{cardId}/labels":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"},{"$ref":"#/components/parameters/AgencyBoardCardId"}],"put":{"operationId":"setAgencyBoardCardLabels","summary":"Set the labels on a card.","description":"Replaces the card's whole label set. Every id is re-checked against **this board**, so a label from another board is refused rather than quietly attached.","tags":["agency-board"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardCardLabels"}}}},"responses":{"200":{"description":"The card, with its new labels.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardCard"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/boards/{boardId}/labels":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"}],"get":{"operationId":"listAgencyBoardLabels","summary":"The board's label vocabulary.","tags":["agency-board"],"responses":{"200":{"description":"Every label defined on this board.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardLabelList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"createAgencyBoardLabel","summary":"Define a label.","description":"Labels are per BOARD, not per organisation — an agency running *Website relaunch* and *Monthly SEO* wants different vocabularies, and a shared org-wide list makes every picker a list of somebody else's categories. Names are unique per board, case-insensitively.","tags":["agency-board"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardLabelCreate"}}}},"responses":{"201":{"description":"The new label.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardLabel"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/boards/{boardId}/labels/{labelId}":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"},{"$ref":"#/components/parameters/AgencyBoardLabelId"}],"patch":{"operationId":"updateAgencyBoardLabel","summary":"Rename or recolour a label.","tags":["agency-board"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardLabelUpdate"}}}},"responses":{"200":{"description":"The updated label.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardLabel"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"deleteAgencyBoardLabel","summary":"Delete a label, taking it off every card wearing it.","description":"Deleted, not archived — a label is a vocabulary word rather than a record of work, and a tombstoned one would leave cards wearing a tag that is not in the picker, which reads as a rendering bug. Cards themselves are archived precisely because they ARE a record.","tags":["agency-board"],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/agency/boards/{boardId}/cards/{cardId}/comments":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"},{"$ref":"#/components/parameters/AgencyBoardCardId"}],"post":{"operationId":"commentOnAgencyBoardCard","summary":"Comment on a card.","description":"`visibility` defaults to `internal`, so an agency comment must be widened deliberately to reach the client.","tags":["agency-board"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardCommentCreate"}}}},"responses":{"201":{"description":"The new comment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardComment"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/boards/{boardId}/cards/{cardId}/questions":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"},{"$ref":"#/components/parameters/AgencyBoardCardId"}],"post":{"operationId":"askAgencyBoardQuestion","summary":"Ask the client a question about this card.","description":"⛔⛔ **Asking a question SHARES the card**, and its column, in the same transaction — explicitly, and written to the board's activity feed so the agency can see it happened. A question the client is expected to answer, on a card they cannot open, is a state no screen can render: the client would be emailed a link to nothing.\n\nNotifies the **client** organisation (`agency_board.question_asked`).","tags":["agency-board"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardQuestionCreate"}}}},"responses":{"201":{"description":"The question.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardQuestion"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/boards/{boardId}/questions/{questionId}":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"},{"$ref":"#/components/parameters/AgencyBoardQuestionId"}],"post":{"operationId":"answerAgencyBoardQuestionAsAgency","summary":"Record an answer the agency was given another way.","description":"For an answer that arrived by phone or email. The client's own answer route is `POST /v1/agency/client/boards/{boardId}/questions/{questionId}/answer`.","tags":["agency-board"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardAnswer"}}}},"responses":{"200":{"description":"The answered question.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardQuestion"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"withdrawAgencyBoardQuestion","summary":"Withdraw a question.","description":"Marks it `cancelled` rather than deleting it — the client may already have seen it and started answering, and a question that vanishes is worse than one marked withdrawn.","tags":["agency-board"],"responses":{"204":{"description":"Withdrawn."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/boards/{boardId}/members":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"}],"get":{"operationId":"listAgencyBoardMembers","summary":"Who is on this board, and who has been invited.","description":"Pending invitations are read from the platform's **one** invitation system (`tenancy.Invitation`) rather than mirrored into a board table — one place an invite expires, is revoked, and is audited.","tags":["agency-board"],"responses":{"200":{"description":"Members and pending invitations.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardMemberList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"addAgencyBoardMember","summary":"Put somebody on a board, or invite them by email.","description":"Give `user_id` for somebody who already has an account, or `email` to invite somebody who does not — the invitation goes through `tenancy.Invitation` and the person joins on acceptance, authenticated by Keycloak with no secret token in the flow.\n\n⛔ A `client` seat may only be given to a member of the board's own client organisation, and **no seat is written for a pending invite**: a client's authorisation is a live membership of that organisation, re-read on every request, so a seat created before acceptance would look like access and confer none.","tags":["agency-board"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardMemberCreate"}}}},"responses":{"201":{"description":"The new board member.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardMember"}}}},"202":{"description":"An invitation was sent; the seat follows on acceptance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardInvitationAccepted"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/boards/{boardId}/members/{memberId}":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"},{"$ref":"#/components/parameters/AgencyBoardMemberId"}],"delete":{"operationId":"removeAgencyBoardMember","summary":"Take somebody off a board.","description":"⚠️ For a **client** this removes the roster row and its unread marker. It does not revoke their access, because their access is not granted here: revoke it by removing them from the client organisation, which the client read re-checks on every request.","tags":["agency-board"],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/agency/boards/{boardId}/activity":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"}],"get":{"operationId":"listAgencyBoardActivity","summary":"The board's timeline.","tags":["agency-board"],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"A page of activity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardActivityPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/agency/boards/{boardId}/ai/run":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"}],"post":{"operationId":"runAgencyBoardAi","summary":"Run one AI function on this board.","description":"Runs a board AI function and returns its output.\n\n**A refusal to spend is a `200`, not a `4xx`.** When the org has no AI credit, no\nprovider key, or is not in good standing, the response carries `skipped: true` with a\n`skipReason` and a customer-readable `text` — because the customer asked and we told\nthem why not, which is a complete answer rather than a fault in their request.\n\n⛔ A client reading `200` as \"it ran\" will record a success for a call that did\nnothing. **Read `skipped`.**\n\n`apply` defaults to `false`: AI on a board proposes and a person commits.\n","tags":["agency-board"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardAiRunRequest"}}}},"responses":{"200":{"description":"The function ran, or was skipped with a reason.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardAiRun"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/boards/{boardId}/ai/settings":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"}],"get":{"operationId":"getAgencyBoardAiSettings","summary":"What AI this board has turned on.","tags":["agency-board"],"responses":{"200":{"description":"The board's AI settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardAiSettings"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"operationId":"updateAgencyBoardAiSettings","summary":"Turn auto-triage or the standup digest on or off.","description":"Both are **opt-in and off by default** — each is recurring billed work, so a board\ncreated for a test or an import must not start spending on a schedule nobody chose.\n\nSetting `digestCadence` to anything but `off` schedules the first digest; setting it\nto `off` clears the schedule.\n","tags":["agency-board"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardAiSettingsUpdate"}}}},"responses":{"200":{"description":"The updated settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardAiSettings"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/boards/{boardId}/ai/models":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"}],"get":{"operationId":"listAgencyBoardAiModels","summary":"The models this org may choose from, cheapest first.","description":"Computed per org, never a constant. On the customer's **own** provider key it is every\nmodel we have verified for that provider; on **Zinn® credits** it is only the models we\ncan price, because an unpriced model would be given away.\n\n`reason` says which constraint produced the list — including when it is empty, so an\nempty picker is distinguishable from one that failed to look.\n","tags":["agency-board"],"responses":{"200":{"description":"The selectable models and the computed default.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardAiModels"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/agency/boards/{boardId}/ai/runs":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"}],"get":{"operationId":"listAgencyBoardAiRuns","summary":"What the AI did on this board, refusals included.","description":"Skipped runs appear in this list rather than being filtered out: a customer asking\nwhy nothing happened on Tuesday needs the refusal to be visible.\n","tags":["agency-board"],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"A page of AI runs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardAiRunPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/agency/boards/{boardId}/invites":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"}],"get":{"operationId":"listAgencyBoardInvites","summary":"The share links for this board.","description":"⛔ The link itself is **never** returned here and no endpoint can return it. Only the SHA-256 digest is stored, so nothing on the platform can re-derive the token from a row — `token_prefix` exists so a manager with three links open can tell them apart. A screen that needs the full link must keep it from the create response.","tags":["agency-board"],"responses":{"200":{"description":"Every share link ever minted for this board, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardInviteList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"createAgencyBoardInvite","summary":"Mint a copy-paste link to this board.","description":"Returns a link you can paste into anything — a chat, an email you write yourself, a document. **No email is sent by us**, which is the point.\n\nA `viewer` link is read-only and needs **no Zinn® account**: whoever opens it sees exactly what the client sees, and can write nothing. Any other role seats the person on the board and therefore requires them to sign in first.\n\n⛔ `token` appears in **this response only**. It cannot be read back later.\n\n⛔ For a seat-bearing role this refuses unless the caller could grant that seat's organisation role themselves. The check has to happen here rather than at redemption, because by then the person redeeming is a stranger and there is no principal whose privileges could bound the grant.","tags":["agency-board"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardInviteCreate"}}}},"responses":{"201":{"description":"The new link. `token` is present here and nowhere else.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardInvite"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/boards/{boardId}/invites/{inviteId}":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"},{"$ref":"#/components/parameters/AgencyBoardInviteId"}],"delete":{"operationId":"revokeAgencyBoardInvite","summary":"Revoke a share link, and everybody who joined through it.","description":"⛔⛔ **This cascades.** Revoking a link also removes the board seats that link created, and the response says how many. That is deliberate and it is what separates revocation from expiry: expiry is a door closing, and nobody already inside is turned out; revocation is *\"that link went somewhere it should not have\"*, which a closed door does not answer.","tags":["agency-board"],"responses":{"200":{"description":"Revoked, with the number of seats removed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardInviteRevoked"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/public/boards/shared/{shareToken}":{"parameters":[{"$ref":"#/components/parameters/BoardShareToken"}],"get":{"operationId":"getSharedBoard","summary":"Open a board someone shared with you. No account needed.","description":"**Unauthenticated.** The token in the path is the whole authorisation: whoever holds it holds the grant, which is what makes the link pasteable into a channel we do not control.\n\nWhat comes back is the **client projection** — the same field-listed view the agency's client gets in their own console, and literally the same code path. Anything the agency marked internal is excluded at the queryset, not in the UI.\n\n⭐ `sign_in` names the brand whose board this is, resolved by walking **up** the organisation tree, so a reseller's client is sent to the reseller's branded login and never to ours. `requires_account` answers \"must I register?\" as data, so a client never has to work out the rule from the role name.","tags":["public"],"security":[],"responses":{"200":{"description":"The board, as the client sees it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SharedBoard"}}}},"404":{"$ref":"#/components/responses/NotFound"},"410":{"description":"The link is revoked, expired, used up, or its board is gone. A different status from 404 on purpose — *\"this link has expired\"* and *\"there is nothing here\" are different sentences to a person who was legitimately sent a link.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SharedBoardExpired"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/boards/shared/{shareToken}/join":{"parameters":[{"$ref":"#/components/parameters/BoardShareToken"}],"post":{"operationId":"joinSharedBoard","summary":"Take the seat a share link grants you.","description":"Requires a signed-in person — this is the *\"one screen from the invite, with the board waiting on the other side\"* half of the flow. A `viewer` link needs no join and says so rather than refusing, because a UI offering **Join** on a read-only link is a UI bug and the honest answer costs one field.\n\nIdempotent: somebody already on the board gets their existing seat back and it does **not** consume one of the link's uses. A client who bookmarks the link and opens it every Monday must not exhaust a 5-use link by themselves.","tags":["public"],"responses":{"200":{"description":"Nothing to do — either a read-only link, or you were already on this board.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SharedBoardJoined"}}}},"201":{"description":"Seated on the board.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SharedBoardJoined"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"410":{"description":"The link is no longer valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SharedBoardExpired"}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/client/boards":{"get":{"operationId":"listSharedAgencyBoards","summary":"Boards my agency has shared with us.","description":"Names only — never any board content. A caller sees a board here when they hold a live membership of an organisation that a board names as its client, and the agency's plan includes the board.","tags":["agency-board"],"responses":{"200":{"description":"The shared boards.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SharedAgencyBoardList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/agency/client/boards/{boardId}":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"}],"get":{"operationId":"getSharedAgencyBoard","summary":"The client's view of one board.","description":"Returns **only** what the agency shared: columns marked client-visible, cards that are client-visible **and** sit in such a column, client-visible comments and attachments on those cards, and every question asked on them.\n\n⛔ Anything not shared is absent from the response, not merely hidden in the UI. The payload is built by a hand-written projection with a test pinning its exact field set — it carries no assignee, no author identity beyond \"from the client or not\", no internal ids and no WIP limits.","tags":["agency-board"],"responses":{"200":{"description":"The shared board.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SharedAgencyBoardDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/agency/client/boards/{boardId}/activity":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"}],"get":{"operationId":"listSharedAgencyBoardActivity","summary":"What has happened on the shared board.","description":"Client-visible activity only. Reading it marks the board read for this person, which is what clears their unread badge.","tags":["agency-board"],"responses":{"200":{"description":"The visible timeline.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SharedAgencyBoardActivityList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/agency/client/boards/{boardId}/requests":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"}],"post":{"operationId":"raiseSharedAgencyBoardRequest","summary":"Raise a request with the agency.","description":"⚖️ Owner ruling 2026-08-31 — a client may raise a card, in the board's single intake column and nowhere else. The request body carries a title and a body and nothing that could steer it elsewhere: the column and the visibility are set by the engine, not accepted and overridden, because a field accepted and overridden is a field somebody later stops overriding.","tags":["agency-board"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SharedAgencyBoardRequestCreate"}}}},"responses":{"201":{"description":"The card, as the client sees it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SharedAgencyBoardCard"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/client/boards/{boardId}/cards/{cardId}/comments":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"},{"$ref":"#/components/parameters/AgencyBoardCardId"}],"post":{"operationId":"commentOnSharedAgencyBoardCard","summary":"Comment on a shared card.","description":"The card is looked up through the same filter the read uses, so a client cannot comment on a card they cannot see — including by guessing its id. A client's comment is always visible to them and to the agency.","tags":["agency-board"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SharedAgencyBoardCommentCreate"}}}},"responses":{"201":{"description":"The comment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SharedAgencyBoardComment"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/agency/client/boards/{boardId}/questions/{questionId}/answer":{"parameters":[{"$ref":"#/components/parameters/AgencyBoardId"},{"$ref":"#/components/parameters/AgencyBoardQuestionId"}],"post":{"operationId":"answerSharedAgencyBoardQuestion","summary":"Answer a question the agency asked.","description":"Notifies the agency (`agency_board.answered`).","tags":["agency-board"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyBoardAnswer"}}}},"responses":{"200":{"description":"The answered question.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SharedAgencyBoardQuestion"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/public/domains/whois":{"get":{"operationId":"getPublicWhois","summary":"Free public WHOIS lookup for any domain.","description":"What the public registry says about a domain — registrar, registration and expiry dates, status codes, nameservers and DNSSEC — for **any** name, whether it is with us or not. No account, one domain per request. Read from RDAP (RFC 7482/7483), which the registries serve themselves and which needs no credential.\n\n**`state` is three-valued and that is load-bearing.** `registered` means the registry returned a record. `not_registered` means it answered `404` — there is no such registration. `unknown` means we could not find out: the extension publishes no RDAP service, the registry timed out, rate-limited us, or answered with something we could not read. ⛔ A client must never render `unknown` as `not_registered`: they send a visitor to opposite actions, and collapsing them is the defect that once offered `google.com` for sale with a valid checkout token.\n\n`registry` is `null` for both non-`registered` states. Inside it every field is nullable, and `null` means *the registry did not publish it* — never that the domain lacks it. A client rendering `transfer_locked: null` as \"unlocked\" would tell somebody to go and protect a domain that is already protected.\n\nNo registrant, admin or technical contact is ever carried: post-GDPR most registries redact them, and republishing the ones that do not would be exporting personal data for no product reason.\n\n**Rate limited per caller and globally**, and answers are cached for 24 hours per domain. There is deliberately no bulk or CSV input — the bulk surface is the authenticated one, where the caller has an organisation.","tags":["public","domains"],"security":[],"parameters":[{"name":"domain","in":"query","required":true,"description":"The domain to look up, including its extension. A trailing dot is ignored, case is ignored, and an internationalised name must already be punycoded.","schema":{"type":"string","minLength":3,"maxLength":253}}],"responses":{"200":{"description":"What we established about the domain. A `200` does **not** mean the domain is registered — read `state`.","headers":{"Cache-Control":{"description":"Always `public, max-age=300`.","schema":{"type":"string"}},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicWhoisAnswer"}}}},"422":{"description":"The `domain` parameter is missing or is not a domain name.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"description":"The lookup service is not available on this deployment. ⛔ Deliberately **not** an empty body and **not** `state: unknown`: this is our own fault rather than anything about the domain, and the two must not be indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/public/domains/nameserver-check":{"get":{"operationId":"getPublicNameserverCheck","summary":"Which registrar holds a domain, what to enter, and whether it has taken effect.","description":"Everything a per-registrar instruction card needs, for **any** domain, with no account. It answers three questions in one request: who the registry says holds the name (so the right instruction card is shown), which nameservers to enter, and whether the change has landed yet.\n\n**`outcome` is four-valued and none of the four may be collapsed.** `delegated` — public DNS resolves the domain to our pair, the job is done. `propagating` — the registry has our pair on record and public DNS does not show it yet; the customer did everything right and there is nothing to do but wait. `not_delegated` — a real, positive reading that it points somewhere else, or nowhere. `unknown` — we could not find out.\n\n⛔ A client must never render `unknown` as `not_delegated`, and must never render `propagating` as a failure. Both mistakes send somebody who succeeded back to redo work that was correct, which is the single most likely way to make this feature feel broken while it is working perfectly.\n\n`expected` is **derived per request** from the platform's own nameserver assignment, never written into card content. `observed` is what the domain points at right now — public DNS where it answered, the registry's record otherwise — and is empty when the reading was positive and there was nothing there.\n\n**Rate limited per caller and globally.** Answers are cached for sixty seconds only: this endpoint's whole population is somebody who has just changed their nameservers and is reloading to check, so a long cache would hide the very change it is asked about. There is deliberately no bulk input.","tags":["public","domains"],"security":[],"parameters":[{"name":"domain","in":"query","required":true,"description":"The domain to check, including its extension. A trailing dot is ignored, case is ignored, and an internationalised name must already be punycoded.","schema":{"type":"string","minLength":3,"maxLength":253}}],"responses":{"200":{"description":"The card to show and what we established about the delegation. A `200` does **not** mean the domain is delegated to us — read `outcome`.","headers":{"Cache-Control":{"description":"Always `private, max-age=0, no-store`.","schema":{"type":"string"}},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicNameserverCheck"}}}},"422":{"description":"The `domain` parameter is missing or is not a domain name.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"description":"The check is not available on this deployment — the public egress identity is not configured. ⛔ Deliberately **not** `outcome: unknown`: this is our own fault rather than anything about the domain, and the two must not be indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/domains/{domainId}/registrar-guide":{"parameters":[{"$ref":"#/components/parameters/DomainId"}],"get":{"operationId":"getDomainRegistrarGuide","summary":"Where and how to change this domain's nameservers.","description":"*\"Where do I actually go to change my nameservers?\"* — the question a customer asks after being handed two hostnames. This answers it **without asking them which registrar they use**: the public registry already publishes the sponsoring registrar and its IANA id, so the answer is read from the same RDAP record the WHOIS card renders.\n\n`slug` is the instruction set to render — `godaddy`, `namecheap`, `porkbun`, `cloudflare`, `squarespace` or `generic`. ⛔ It is a **slug and never step text**: a client renders its own localized steps from it, because English instructions returned from an API cannot be translated for 58 locales.\n\n⭐ `generic` is a real answer, not a failure. There are roughly 2,500 accredited registrars and \"set these two nameservers wherever you bought the domain\" is correct at every one of them.\n\n`self_serve` says whether we can make the change **for** the customer with an API key they supply, and it is derived from which delegation adapters exist rather than stated per registrar. `locked` says the domain **cannot** be delegated elsewhere at all — true for Cloudflare Registrar, which requires its own nameservers. Those two are different states and need different copy: `self_serve: false` means \"you will have to do this by hand\", `locked: true` means \"there is nothing to do and no setting to look for\".\n\n`expected` is the pair to set, resolved from the **zone's own** nameservers first rather than a fleet-wide constant — a footprint-free domain gets a provider-assigned pair. `nameservers` is where the registry says the domain points right now, so a client can say \"already done\" instead of repeating an instruction.\n\nRequires `sites.view`, RLS-scoped. A registry that does not answer is a `503`, never a generic card: both mean \"we do not know your registrar\" and only one of them says so.","tags":["domains"],"responses":{"200":{"description":"The instruction card for this domain's registrar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistrarGuide"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"description":"The public registry did not answer, so the registrar is unknown. ⛔ Deliberately not a `generic` card — a silence dressed as an answer would send the customer to follow instructions that may be impossible for them.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/domains/{domainId}/registrar-guide/verify":{"parameters":[{"$ref":"#/components/parameters/DomainId"}],"post":{"operationId":"verifyDomainDelegation","summary":"Check now whether this domain's nameserver change has taken effect.","description":"The **verify button** on the instruction card. Reads the live public DNS and the domain's registry record and answers in four states, so the customer can tell whether the steps they just followed worked.\n\n⛔ **Four outcomes, where `GET /v1/domains/{domainId}/delegation` has three, and the fourth is the point.** That endpoint is a drift watch and answers `delegated` / `not_delegated` / `unknown` — correct for what it does. It is not sufficient here: a customer who pressed Save at their registrar thirty seconds ago is genuinely `not_delegated` to any resolver, because the registry has the change and nothing else does yet. Telling them \"not yet\" is true, useless, and reads as failure. `propagating` is that state told honestly — **the registry has the pair we asked for and public DNS has not caught up** — and it is a success message, not a warning.\n\n⛔ `unknown` is not `not_delegated`. They send a customer to opposite actions, and a lookup that failed must never be rendered as \"you have not done it\".\n\n`expected` is resolved **per domain** from the zone's own nameservers where the DNS provider assigns them, so a footprint-free domain is compared against its own pair rather than a platform constant. `observed` is what it points at right now — public DNS where that answered, the registry's record otherwise.\n\n**Writes nothing.** The recorded reading, the drift ladder and the \"your domain has left us\" alarm belong to `GET`/`POST /v1/domains/{domainId}/delegation`; a customer pressing a button on an instruction card is asking a question, not supplying evidence. `POST` rather than `GET` only because it makes two live outbound lookups and must never be cached or prefetched.\n\nRequires `sites.view`, RLS-scoped. It changes nothing about the domain, and gating it behind a management permission would leave a read-only user looking at instructions they can never confirm they have followed.","tags":["domains"],"responses":{"200":{"description":"The freshly-taken reading.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DelegationVerdict"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/domains/{domainId}/premium-dns":{"parameters":[{"$ref":"#/components/parameters/DomainId"}],"get":{"operationId":"getDomainPremiumDns","summary":"Whether Premium DNS can be sold for this domain, and which row to sell.","description":"Premium DNS by Sectigo is sold **per zone**, so it is meaningless without a domain and its catalogue rows are deliberately not public — the account-level storefront must not offer it and the domain's own screen must. This is the read that screen uses.\n\n⛔ **The offer is SUPPRESSED where the domain cannot use the product**, computed here rather than in a client. A Cloudflare-registrar domain cannot be delegated anywhere else at all, and a domain riding the shared fleet nameservers has no authoritative zone of its own for Sectigo to replace. Selling to either would charge the customer and then refuse them.\n\n`reason` is a **code**, never a sentence — the customer-facing wording is localizable and belongs in the client's own catalogue. `registrar_locks_nameservers` means the registrar permits no other nameservers; `no_zone_of_its_own` means there is no zone to upgrade; `registry_unavailable` means the public registry did not answer, so we cannot tell which case this is — and an unknown is not a yes.\n\n`code` is the `Extra.code` to purchase, chosen by the domain's product line through the catalogue's own fence rather than by a second price table. `site_id` is the site the purchase must name: the extra is site-scoped, so a buy button offered without one produces a charge that fulfilment then refuses.\n\nRequires `sites.view`, RLS-scoped.","tags":["domains"],"parameters":[{"name":"locale","in":"query","required":false,"description":"The language the app is rendering in (a BCP 47 tag such as `ar` or `pt-PT`). A supported value is the language the offered extra's `name` and `description` are served in; an absent or unsupported one falls back to the caller's stored language preference. Never read from `Accept-Language`.","schema":{"type":"string","maxLength":35}}],"responses":{"200":{"description":"Whether to show the offer, and what to sell.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PremiumDnsOffer"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/board-github/discover":{"post":{"operationId":"discoverGitHubProjects","summary":"List the GitHub Projects a credential can see.","description":"Asked before anything is linked, so the customer picks a project from a list rather than pasting a node id. Reads **both** owner shapes — GitHub's `organization` query returns null for a user login and `user` returns null for an org login, so a single-shape read would answer \"no projects\" for half of all customers with no error anywhere.\n\n`count` is returned beside `projects` deliberately: an owner with genuinely no projects and a credential that cannot *see* any would otherwise be the same empty array.","tags":["board-github"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitHubProjectDiscovery"}}}},"responses":{"200":{"description":"The projects this credential can see for that owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitHubProjectDiscoveryResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/board-github/rollup":{"get":{"operationId":"getGitHubProjectRollup","summary":"Every linked GitHub Project, summed into one view.","description":"GitHub shows one project at a time; this is the screen that does not exist there. An agency running four client projects gets one answer to *\"how much is in progress and how much is late\"*.\n\n`links_never_synced`, `links_failing` and `coverage_is_complete` are part of the answer, not diagnostics. A roll-up that silently omitted a project which failed to sync would be a number somebody makes a staffing decision on, and *\"nothing is late\"* must never render the same as *\"I cannot see whether anything is late\"*.","tags":["board-github"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Required only when the caller holds the permission in several orgs."}],"responses":{"200":{"description":"The roll-up, with its own coverage stated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitHubProjectRollup"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/board-github/roadmap":{"get":{"operationId":"getGitHubProjectRoadmap","summary":"A dated timeline across every linked GitHub Project.","description":"Built from whichever DATE and ITERATION fields each project actually has. Lanes are the iteration where a project has one and the project where it does not, so one timeline stays readable across a sprint-driven engineering project and a date-driven client project at once. GitHub's own roadmap layout can do neither — it is per-project and cannot see our board cards.\n\nItems with no date are **omitted and counted** in `items_without_dates`, never given an invented date: a chart of our guesses would be worse than a gap.","tags":["board-github"],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The timeline.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitHubProjectRoadmap"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/board-github/links":{"get":{"operationId":"listGitHubProjectLinks","summary":"The GitHub Projects this organisation has connected.","description":"Each row carries `webhook_state`, which is the honest answer to *\"is GitHub pushing changes at us, or are we polling?\"*. It has three outcomes and not two: `automatic` (we created the hook), `manual` (GitHub would not let us, so the customer creates it and we hand them the URL and secret) and `failed`. `manual` is the commonest and is an instruction, not an error — creating an organisation webhook needs a permission most customers will not grant. The five-minute reconciliation sweep covers a project in every state, so this decides latency and never correctness.","tags":["board-github"],"parameters":[{"name":"board_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Only links surfaced alongside this board."},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"A page of connections.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitHubProjectLinkPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"connectGitHubProject","summary":"Connect a GitHub Project to this organisation.","description":"Two-way from the moment it is connected (owner ruling, 2026-09-03). The first sync runs inside this request, so the 201 already carries the project's fields — a connect that returned an empty board and left the customer waiting for the sweep would read as a broken connection.\n\n`auth_kind: app` stores only the **installation id**, which is public and appears in the customer's own install URL; nothing long-lived is at rest and an hour-long token is minted per use. `auth_kind: pat` writes the token straight to Vault and never echoes it.","tags":["board-github"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitHubProjectConnect"}}}},"responses":{"201":{"description":"The connection, with the project's fields already read.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitHubProjectLink"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/board-github/links/{linkId}":{"parameters":[{"$ref":"#/components/parameters/GitHubLinkId"}],"get":{"operationId":"getGitHubProjectLink","summary":"One connection, with its WIP report and its open notices.","description":"The connection screen's whole payload in one call: the project, its fields with their options, the per-status counts against any WIP limits, and the notices GitHub does not raise — overdue items, items nothing has touched for a fortnight, and columns over their limit. `last_synced_at` and `last_attempted_at` are both returned and are different questions: a connection GitHub keeps refusing has a recent attempt and a stale success, and reporting only the first would show a healthy timestamp on a connection that has been broken for a week.","tags":["board-github"],"responses":{"200":{"description":"The connection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitHubProjectLinkDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"operationId":"updateGitHubProjectLink","summary":"Change a connection's sync direction or the board it sits alongside.","description":"`direction` moves a connection between two-way and read-only. A new connection is two-way immediately; read-only exists for a customer who wants a mirror they cannot break, and it is the honest remedy when GitHub keeps refusing our writes — turning writes off is better than a screen that accepts edits which never arrive.","tags":["board-github"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitHubProjectLinkUpdate"}}}},"responses":{"200":{"description":"The updated connection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitHubProjectLink"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"disconnectGitHubProject","summary":"Disconnect a GitHub Project.","description":"Any stored token is **deleted from Vault** in the same act. A token left behind after the customer disconnected is a live credential we were asked to stop holding, and it would be invisible to every screen.","tags":["board-github"],"responses":{"204":{"description":"Disconnected."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/board-github/links/{linkId}/webhook":{"parameters":[{"$ref":"#/components/parameters/GitHubLinkId"}],"get":{"operationId":"getGitHubProjectWebhook","summary":"The payload URL and signing secret for a connection the customer configures.","description":"Read when `webhook_state` is `manual`, which is the commonest case: creating an organisation webhook needs a permission most customers will not grant, so they create it themselves and this is what they need to do it. The secret is returned in full — there is no way to configure a webhook without it — so the read is audit-logged and requires the manage permission rather than the view one. An App connection returns an empty secret because it is signed with the platform app's own, and there is nothing for the customer to set up.","tags":["board-github"],"responses":{"200":{"description":"What to paste into GitHub.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitHubWebhookSetup"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"retryGitHubProjectWebhook","summary":"Try again to create the webhook on GitHub, and mint a fresh secret.","description":"For the customer who has just granted the permission that was missing, and for rotating a secret that has been shown to somebody it should not have been. **The secret changes on every call**, so a hook the customer created by hand stops verifying until they paste the new one — which is why the response says which state resulted.","tags":["board-github"],"responses":{"200":{"description":"The resulting state, with the new secret when there is one to show.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitHubWebhookSetup"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/board-github/webhook/{endpointKey}":{"post":{"operationId":"receiveGitHubProjectsWebhook","summary":"One GitHub webhook delivery for a linked project.","description":"**Public and unauthenticated — the HMAC is the authentication.** GitHub cannot present a session, so `X-Hub-Signature-256` over the raw body with this connection's own secret is the whole control.\n\nAnswers **202 for every valid delivery, including ones we do not act on** — a ping, or an event type we ignore. Answering those with an error paints the endpoint permanently red on the customer's own GitHub screen, so a working integration looks broken; the `reason` field says which. A bad or absent signature is **401 with an empty body**: a response that distinguished \"no such endpoint\" from \"wrong secret\" would be an oracle for guessing endpoint keys.","tags":["board-github"],"security":[],"parameters":[{"name":"endpointKey","in":"path","required":true,"schema":{"type":"string"},"description":"The connection's opaque endpoint key, or `app` for the platform GitHub App's own shared webhook. Not the connection's id — a URL the customer pastes into GitHub ends up in their logs and their screenshots, and a tenant-scoped id there is a tenant-scoped id in somebody else's hands."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"GitHub's own `projects_v2` or `projects_v2_item` payload, verbatim."}}}},"responses":{"202":{"description":"Accepted. `accepted` says whether it led to a refresh.","content":{"application/json":{"schema":{"type":"object","required":["accepted"],"properties":{"accepted":{"type":"boolean"},"reason":{"type":"string","description":"Why a valid delivery was not acted on (`ping`, an unhandled event, an unlinked project)."},"link_id":{"type":"string","format":"uuid"},"queued":{"type":"boolean"}}}}}},"401":{"description":"The signature did not verify, or no such endpoint. Deliberately the same answer for both."}}}},"/v1/board-github/links/{linkId}/sync":{"parameters":[{"$ref":"#/components/parameters/GitHubLinkId"}],"post":{"operationId":"syncGitHubProjectLink","summary":"Refresh one connection from GitHub now.","description":"The Temporal sweep does this every five minutes and the webhook does it in seconds; this is the button for somebody who does not want to wait.\n\nBoth cursors come back. `last_attempted_at` moves for every attempt and `last_synced_at` only on success — so *\"last synced 4 minutes ago\"* beside *\"last attempted 10 seconds ago\"* is how a customer sees that we are trying and GitHub is refusing. One timestamp cannot say that.","tags":["board-github"],"responses":{"200":{"description":"What the refresh did.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitHubProjectSyncResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/board-github/links/{linkId}/conflicts":{"parameters":[{"$ref":"#/components/parameters/GitHubLinkId"}],"get":{"operationId":"listGitHubProjectConflicts","summary":"Every field whose value was overwritten by the sync.","description":"Conflicts resolve **last-writer-wins with no banner** (owner ruling, 2026-09-03), so nothing interrupts anyone. This endpoint is where somebody who asks *\"what happened to my change\"* gets both values and both timestamps. A resolution rule that kept no record of what it discarded would be data loss with a policy attached.","tags":["board-github"],"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"A page of resolved conflicts, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitHubProjectConflictPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/board-github/links/{linkId}/items":{"parameters":[{"$ref":"#/components/parameters/GitHubLinkId"}],"get":{"operationId":"listGitHubProjectItems","summary":"The items on a connected project.","description":"Issues, pull requests and draft items, each with its field values already resolved to both a stored value and a display string, so a board can render a column without a second lookup per card. Archived items are excluded unless `include_archived` is set: GitHub keeps them on the project for ever and a board that showed them would grow without bound while looking like work in progress.","tags":["board-github"],"parameters":[{"name":"include_archived","in":"query","required":false,"schema":{"type":"boolean"},"description":"An item removed from the project on GitHub is marked archived here rather than deleted, so a board card linked to it keeps its link and its history."},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"A page of items.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitHubProjectItemPage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"createGitHubProjectItem","summary":"Post a new item to the GitHub Project from our UI.","description":"Creates a draft item on GitHub and sets whatever field values were sent, then **reads the item back from GitHub** rather than assembling the response from our own input. A mutation's echo is our own payload handed back, so building the row from it would make the row agree with our intention whether or not GitHub stored it.\n\nA field whose type GitHub's field-value mutation cannot set is skipped rather than refused, and the read-back is what tells the truth about which values landed.","tags":["board-github"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitHubProjectItemCreate"}}}},"responses":{"201":{"description":"The item, as GitHub reports it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitHubProjectItem"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/board-github/links/{linkId}/items/{itemId}":{"parameters":[{"$ref":"#/components/parameters/GitHubLinkId"},{"$ref":"#/components/parameters/GitHubItemId"}],"delete":{"operationId":"deleteGitHubProjectItem","summary":"Remove an item from the GitHub Project, permanently.","description":"**There is no undo, on either side.** For a draft item GitHub destroys the content outright; for an issue or a pull request the item leaves the project and the issue itself survives. A customer cannot be expected to know which of those they are about to do, so the screen says it and this endpoint refuses without an explicit confirmation.\n\n`confirm` must equal the item's own GitHub node id (`item_node_id`), not a boolean and not the word \"delete\". A boolean confirms *that you meant to delete something*; the node id confirms *which one*, so a stale tab, a re-sorted board or a double submit that lands on a neighbouring row is refused rather than granted.\n\nArchiving is the reversible alternative and is usually what a person clearing a Done column actually wants — see the `archive` sub-resource.","tags":["board-github"],"parameters":[{"name":"confirm","in":"query","required":true,"description":"The item's own `item_node_id`. A query parameter rather than a request body because a `DELETE` body is dropped by enough proxies that a confirmation carried in one silently becomes absent — and an absent confirmation here must refuse.","schema":{"type":"string"}}],"responses":{"204":{"description":"The item is gone from the project and from our copy."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/board-github/links/{linkId}/items/{itemId}/archive":{"parameters":[{"$ref":"#/components/parameters/GitHubLinkId"},{"$ref":"#/components/parameters/GitHubItemId"}],"put":{"operationId":"setGitHubProjectItemArchived","summary":"Archive a GitHub Project item, or restore it.","description":"The reversible half of clearing a board, and how a person empties a Done column without destroying anything.\n\n`archived` is required and carries both directions; there is no default, because a default would make a request that lost its body in a proxy mean *archive* — the opposite of a restore, applied silently.\n\n`isArchived` in the response is read back from GitHub with a second query rather than taken from the mutation's own echo, which returns the item it was handed and would therefore agree with us whether or not GitHub applied anything.","tags":["board-github"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitHubProjectItemArchive"}}}},"responses":{"200":{"description":"The item, re-read from GitHub after the change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitHubProjectItem"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/board-github/links/{linkId}/items/{itemId}/field":{"parameters":[{"$ref":"#/components/parameters/GitHubLinkId"},{"$ref":"#/components/parameters/GitHubItemId"}],"put":{"operationId":"setGitHubProjectItemField","summary":"Set or clear one field value on a GitHub Project item.","description":"`value: null` **clears** the field, through a different GitHub mutation. Sending an empty string would set the field *to* the empty string, which a date field refuses and a text field renders as a permanent blank chip — a save that looks like it worked.\n\nOnly TEXT, NUMBER, DATE, SINGLE_SELECT and ITERATION are writable; every other type is either computed by GitHub or set on the underlying issue. The `writable` flag on each field in the connection payload is computed server-side so the UI never keeps its own copy of that list.","tags":["board-github"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitHubProjectFieldValue"}}}},"responses":{"200":{"description":"The item, re-read from GitHub after the write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitHubProjectItem"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/board-github/links/{linkId}/items/{itemId}/card":{"parameters":[{"$ref":"#/components/parameters/GitHubLinkId"},{"$ref":"#/components/parameters/GitHubItemId"}],"put":{"operationId":"linkGitHubProjectItemToCard","summary":"Attach a GitHub item to a board card, or detach it.","description":"The linkage the integration exists for: an agency shows its client *\"the work is In Progress\"* without giving the client a GitHub seat. `card_id: null` detaches.\n\nThe card must belong to the same organisation as the connection. RLS already bounds both reads to the caller's tenancy; this bounds them to each other, because a card from another of the same agency's boards is in scope for RLS and is still the wrong card.","tags":["board-github"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitHubProjectItemCardLink"}}}},"responses":{"200":{"description":"The item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitHubProjectItem"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/board-github/links/{linkId}/fields/{fieldId}/wip":{"parameters":[{"$ref":"#/components/parameters/GitHubLinkId"},{"$ref":"#/components/parameters/GitHubFieldId"}],"put":{"operationId":"setGitHubProjectWipLimit","summary":"Set an advisory WIP limit on one status option.","description":"**GitHub has no WIP limit feature at all**, so this is new capability rather than a nicer rendering of theirs. It writes nothing to GitHub and cannot fail because of them.\n\nAdvisory, exactly as a board column's limit is: a limit that *refused* a move would turn a management convention into an outage at 17:55 on a Friday — and here it would be refusing a write into somebody else's GitHub. `limit: null` clears it.","tags":["board-github"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitHubProjectWipLimit"}}}},"responses":{"200":{"description":"The field, with its limits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitHubProjectField"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/sites/{siteId}/chat-agent":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"get":{"operationId":"getSiteChatAgent","summary":"The AI chat agent on this site — how it is configured and what it knows.","description":"The agent's name, personality, colours, the domains it may be embedded on, what it has read, how many messages it has answered this month, and the snippet to paste into a site we do not host.\n\n404 when this site has no agent. Buying `ai_chat_agent` from the add-on store creates one; so does `POST` to this path once the product is owned.","tags":["hosting"],"parameters":[{"name":"absent","in":"query","required":false,"description":"`no_content` answers a site with no agent yet with a `204` instead of the 404. A site outside the caller's scope is still a 404.","schema":{"type":"string","enum":["no_content"]}}],"responses":{"200":{"description":"The agent and its knowledge sources.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatAgent"}}}},"204":{"description":"Only with `absent=no_content`: this site has no agent yet."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"createSiteChatAgent","summary":"Switch on the chat agent for this site.","description":"Creates the agent, named after the site and pre-authorised for the site's own domains so the snippet works the moment it is pasted.\n\n⛔ Refuses with 422 when the product has not been bought for this site, or when the account is not in good standing — two different refusals with two different remedies, told apart by the `code` in the error details (`not_purchased` / `not_in_good_standing`). A suspension is not cleared by credit, so that refusal deliberately offers no top-up.\n\nCalling it twice returns the existing agent with 200 rather than an error.","tags":["hosting"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatAgentUpdate"}}}},"responses":{"200":{"description":"The agent that already existed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatAgent"}}}},"201":{"description":"The agent that was created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatAgent"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Not bought for this site, or the account is not in good standing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateSiteChatAgent","summary":"Change the agent's name, personality, brand or the domains it may appear on.","description":"Everything a visitor sees is here — and it is the customer's brand, not ours.\n\n⛔ `allowed_origins` is a fence, not a preference. The public endpoints answer only for an origin on this list, and an **empty list refuses everything**: it means \"not installed anywhere yet\", never \"allow anything\". Entries are normalised to `scheme://host`, so pasting a full page address works.\n\n`monthly_message_cap` is checked before each answer, not reconciled afterwards, so it is a real limit on what this agent can spend rather than a report on what it did.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatAgentUpdate"}}}},"responses":{"200":{"description":"The saved agent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatAgent"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"A malformed colour or origin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteSiteChatAgent","summary":"Remove the agent and everything it had indexed.","description":"The agent, its conversations and every page it had read are deleted together. The widget stops answering immediately.","tags":["hosting"],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/sites/{siteId}/chat-agent/sources":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"addSiteChatAgentSource","summary":"Tell the agent what to read, and read it now.","description":"Three kinds of source, and the first is the one no other host can offer.\n\n`hosted_files` reads the site's pages **straight off the box we host it on** — no crawl, no rate limit, no robots.txt, and no page missed because nothing links to it. It is available only on our own fleet; on a platform we do not run, this returns a source in state `failed` saying so in as many words rather than quietly falling back.\n\n`crawl` fetches pages over HTTP from an address you give and follows same-site links. It works anywhere, including sites we do not host.\n\n`manual` is text you type — opening hours, a returns policy, an FAQ.\n\nIndexing runs immediately and the response says how many pages were read and whether it stopped at a ceiling. `truncated` is present when it did.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatAgentSourceCreate"}}}},"responses":{"201":{"description":"The source, and what indexing it did.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatAgentSourceRun"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"A website source with no address, or an empty note.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/sites/{siteId}/chat-agent/sources/{sourceId}":{"parameters":[{"$ref":"#/components/parameters/SiteId"},{"name":"sourceId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The knowledge source to remove."}],"delete":{"operationId":"deleteSiteChatAgentSource","summary":"Stop the agent using this source, and forget what it read from it.","description":"The pages this source contributed are removed from the index in the same call, so the agent stops citing them immediately. Other sources are untouched.","tags":["hosting"],"responses":{"204":{"description":"Removed."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/sites/{siteId}/chat-agent/reindex":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"reindexSiteChatAgent","summary":"Re-read every source, so the agent knows what the site says today.","description":"Runs each source again and replaces what it previously contributed — a page you deleted stops being cited, and a page you changed is answered from its new text.","tags":["hosting"],"responses":{"200":{"description":"The agent, and one result per source.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatAgentReindex"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/sites/{siteId}/chat-agent/preview":{"parameters":[{"$ref":"#/components/parameters/SiteId"}],"post":{"operationId":"previewSiteChatAgent","summary":"Ask your own agent a question, as a visitor would.","description":"The same answer path the widget uses, so what you see here is what a visitor gets.\n\n⛔ Metered and capped exactly like a visitor's message. A free preview would be a path that spends money nobody counts.","tags":["hosting"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatAgentAsk"}}}},"responses":{"200":{"description":"The reply, its citations, and whether a person is needed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatAgentAnswer"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/public/chat-agents/{publicKey}/config":{"parameters":[{"name":"publicKey","in":"path","required":true,"schema":{"type":"string"},"description":"The agent's public key, as carried in the embed snippet."}],"get":{"operationId":"getPublicChatAgentConfig","parameters":[{"name":"locale","in":"query","required":false,"schema":{"type":"string","maxLength":35},"description":"The visitor's language tag (the page's `lang`, else the browser's). Chooses the language of `strings`; an unknown tag answers in English."}],"summary":"What the widget on a customer's website needs in order to draw itself.","description":"Unauthenticated by necessity: a visitor on a customer's website has no account, and that is the product.\n\nEverything returned is already visible to whoever is reading that page — a name, a greeting and a colour. There is no secret here, no organisation id and no site id.\n\n⛔ Answers **404 both** when the key is unknown and when the calling `Origin` is not one the customer authorised. One answer for two causes, deliberately: a distinguishable refusal would tell a stranger that a key is real and merely mis-embedded, which is an enumeration oracle over every customer who owns this product.\n\n⭐ Fetched on every page view, so it is browser-cacheable (`Cache-Control: private, max-age=60, stale-while-revalidate=300`, `Vary: Origin`; never a shared cache) and is rate-limited in its own per-address bucket, apart from the visitor's messages.","tags":["public"],"security":[],"responses":{"200":{"description":"The widget's appearance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicChatAgentConfig"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/chat-agents/{publicKey}/messages":{"parameters":[{"name":"publicKey","in":"path","required":true,"schema":{"type":"string"},"description":"The agent's public key, as carried in the embed snippet."}],"post":{"operationId":"askPublicChatAgent","summary":"One visitor turn — a question, and the answer from that site's own pages.","description":"The agent answers **only** from content belonging to this one site. That is enforced in the database query, not by instructing the model, so there is no phrasing a visitor can use to reach another customer's content.\n\n`handoff_suggested` is its own field and is **not** an error. It is `true` when the agent could not find the answer on the site — nothing is broken, those pages simply do not say — and the right response is to offer a person, never a guess.\n\n`refusal` is present only when the turn was refused rather than answered, and names the class so a widget can render the right thing: `provider_outage`, `credential_problem`, `refused` (a deliberate decline, such as a monthly cap reached) or `unavailable` (our fault, and no vendor is named).\n\nAnswers 404 for an unauthorised `Origin`, exactly as the config route does and for the same reason.","tags":["public"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatAgentAsk"}}}},"responses":{"200":{"description":"The reply, its citations, and whether a person is needed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatAgentAnswer"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/chat/canned-replies":{"get":{"operationId":"listChatCannedReplies","summary":"The saved answers operators insert with a shortcut.","description":"Requires `livechat.view` or `livechat.reply`.","tags":["live-chat"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"}],"responses":{"200":{"description":"Every canned reply in scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCannedReplyList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createChatCannedReply","summary":"Save an answer for reuse.","description":"Requires `livechat.manage`.","tags":["live-chat"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCannedReplyCreate"}}}},"responses":{"201":{"description":"The saved reply.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCannedReply"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/chat/canned-replies/{cannedReplyId}":{"parameters":[{"name":"cannedReplyId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"delete":{"operationId":"deleteChatCannedReply","summary":"Delete a saved answer.","description":"Requires `livechat.manage`.","tags":["live-chat"],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/chat/conversations/{conversationId}":{"parameters":[{"$ref":"#/components/parameters/ChatConversationId"}],"get":{"operationId":"getChatConversation","summary":"One conversation's full transcript.","description":"Requires `livechat.view`.","tags":["live-chat"],"parameters":[{"name":"after","in":"query","required":false,"schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"The conversation and its messages.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatConversationDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/chat/conversations/{conversationId}/close":{"parameters":[{"$ref":"#/components/parameters/ChatConversationId"}],"post":{"operationId":"closeChatConversation","summary":"Close a conversation.","description":"Requires `livechat.reply`. Idempotent. A visitor who writes again reopens it rather than being told the conversation is over.","tags":["live-chat"],"responses":{"200":{"description":"The closed conversation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatConversation"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/chat/conversations/{conversationId}/messages":{"parameters":[{"$ref":"#/components/parameters/ChatConversationId"}],"post":{"operationId":"replyToChatConversation","summary":"An operator answers a visitor.","description":"Requires `livechat.reply`. Claims the conversation for the caller if nobody has it yet, so the assistant stops answering over the top of a person.","tags":["live-chat"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatReplyCreate"}}}},"responses":{"201":{"description":"The conversation and the message just written.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatReplyResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/chat/conversations/{conversationId}/transfer":{"parameters":[{"$ref":"#/components/parameters/ChatConversationId"}],"post":{"operationId":"transferChatConversation","summary":"Hand a conversation to a colleague.","description":"Requires `livechat.reply`.","tags":["live-chat"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatTransferCreate"}}}},"responses":{"200":{"description":"The conversation, now theirs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatConversation"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/chat/inbox":{"get":{"operationId":"getChatInbox","summary":"Every live conversation, and what is new in each.","description":"Requires `livechat.view`. **One request serves the whole inbox**: pass what this browser already has as `cursors`, and the response carries only what it does not. An operator with eleven conversations open costs one poll, not eleven.","tags":["live-chat"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"cursors","in":"query","required":false,"description":"`conversationId:seq` pairs, comma-separated — what the caller already holds.","schema":{"type":"string"}}],"responses":{"200":{"description":"Live conversations with their new turns.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatInbox"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/chat/widgets":{"get":{"operationId":"listChatWidgets","summary":"The chats this organisation runs.","description":"Requires `livechat.view` or `livechat.manage`. `site_id` narrows the list to one site's chat — what a site's own settings panel asks. A malformed id returns an empty list.","tags":["live-chat"],"parameters":[{"$ref":"#/components/parameters/OrgIdQuery"},{"name":"site_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Every widget in scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatWidgetList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createChatWidget","summary":"Create a chat for a site.","description":"Requires `livechat.manage`. The new widget is created **switched off**: a chat window that starts talking to a customer's visitors before they have asked for one is a consent problem, not a feature.","tags":["live-chat"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatWidgetCreate"}}}},"responses":{"201":{"description":"The widget, with the public key to embed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatWidget"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/chat/widgets/{widgetId}":{"parameters":[{"$ref":"#/components/parameters/ChatWidgetId"}],"get":{"operationId":"getChatWidget","summary":"One chat's settings and its AI allowance.","description":"Requires `livechat.view` or `livechat.manage`.","tags":["live-chat"],"responses":{"200":{"description":"The widget.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatWidget"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"operationId":"updateChatWidget","summary":"Change a chat's settings, or switch it on.","description":"Requires `livechat.manage`. Switching a widget on with no `allowedOrigins` is refused with `422` rather than accepted: the widget only answers pages on origins the customer listed, so an empty list would leave the chat live, looking configured, and invisible on every page with nothing saying why.","tags":["live-chat"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatWidgetUpdate"}}}},"responses":{"200":{"description":"The updated widget.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatWidget"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"deleteChatWidget","summary":"Delete a chat, with its conversations and canned replies.","description":"Requires `livechat.manage`. Removes the widget and everything stored under it (its conversations, their transcripts and the canned replies scoped to it); the embed key stops answering at once. On a WordPress site we host, the managed install is re-applied so the widget leaves the site's pages. Another organisation's chat is `404`. Our own sites' chat cannot be deleted (`422`). Audit-logged as `livechat.widget.deleted`.","tags":["live-chat"],"responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/chat/widgets/{widgetId}/logo":{"parameters":[{"$ref":"#/components/parameters/ChatWidgetId"}],"post":{"operationId":"uploadChatWidgetLogo","summary":"Upload the logo shown in this chat window's header.","description":"Requires `livechat.manage`. PNG, JPEG, WebP or GIF, up to 256 KB and 4000 px a side; SVG is refused because it can carry scripts. Stored on any tier and shown to visitors only when the chat is on Premium, the same gate as hiding the Zinn® Chat mark.","tags":["live-chat"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["logo"],"properties":{"logo":{"type":"string","format":"binary"}}}}}},"responses":{"200":{"description":"The widget, with its new `logo_url`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatWidget"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"operationId":"deleteChatWidgetLogo","summary":"Stop showing a logo in this chat window.","description":"Requires `livechat.manage`.","tags":["live-chat"],"responses":{"200":{"description":"The widget, with `logo_url` empty.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatWidget"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/chat/widgets/{widgetId}/copy-settings":{"parameters":[{"$ref":"#/components/parameters/ChatWidgetId"}],"post":{"operationId":"copyChatWidgetSettings","summary":"Copy this chat's branding and settings onto other sites' chats.","description":"Requires `livechat.view` or `livechat.manage` on this chat and `livechat.manage` on every target. Copies the colour, position, team name, greeting, logo, opening hours, the \"hide Zinn® Chat branding\" choice and this chat's own saved replies (a mirror: replies the target has and this chat does not are removed). Never copies the public key, the allowed web addresses, the on/off switch, the name, the missed-chat email address, the AI switch, the tier or any conversation.\n\nA site with no chat gets one, created switched off with no web addresses. With `dry_run` the full diff is returned and nothing is written. At most 100 targets per request — a page, not a limit on the work: send the rest in the next request. A target outside the organisations you manage answers `404`, and nothing is changed.","tags":["live-chat"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatSettingsCopyRequest"}}}},"responses":{"200":{"description":"One result per target, in the order given.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatSettingsCopyResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/chat/widgets/{widgetId}/settings-export":{"parameters":[{"$ref":"#/components/parameters/ChatWidgetId"}],"get":{"operationId":"exportChatWidgetSettings","summary":"Download this chat's portable settings as a file.","description":"Requires `livechat.view` or `livechat.manage`. The same set the copy moves, with the logo carried as its own bytes. Canonical — keys sorted, no ids, no timestamps — so an export, imported elsewhere and exported again, is byte-for-byte the same file. Served with `Content-Disposition: attachment`.","tags":["live-chat"],"responses":{"200":{"description":"The settings file.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatSettingsDocument"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/chat/widgets/{widgetId}/settings-import":{"parameters":[{"$ref":"#/components/parameters/ChatWidgetId"}],"post":{"operationId":"importChatWidgetSettings","summary":"Apply a settings file to this chat.","description":"Requires `livechat.manage`. The file is validated in full — an unknown format, a newer version, a missing key, a malformed colour or opening hours, a duplicate saved reply or a logo that does not match its fingerprint answers `422` and changes nothing. With `dry_run=true` the diff is returned and nothing is written.","tags":["live-chat"],"parameters":[{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatSettingsDocument"}}}},"responses":{"200":{"description":"What changed, or would change.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatSettingsTransferResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/public/chat/{publicKey}/config":{"parameters":[{"$ref":"#/components/parameters/ChatPublicKey"}],"get":{"operationId":"getPublicChatConfig","summary":"What the chat widget on this site should look like.","description":"**Anonymous** — no credential, no tenant. The widget calls this to learn its greeting, colour, position and whether a person is likely to answer right now.\n\nThe `publicKey` names a widget and authorises nothing: it ships in the page source of every site that embeds the widget, exactly like a publishable key. What actually gates the call is the `Origin` header, which must be one the customer listed on the widget. An unknown key, a disabled widget and an unlisted origin all answer `404` alike — which of the three it is is the customer's business, and distinguishing them would make this an oracle about other people's accounts.\n\n⭐ The WordPress plugin never calls this: it already holds these settings server-side and inlines them into the page, so a WordPress visitor's browser makes no request at all until they open the chat.\n\n⭐ Fetched on every page view, so it is browser-cacheable (`Cache-Control: private, max-age=60, stale-while-revalidate=300`, `Vary: Origin`; never a shared cache) and is bounded by its own per-client budget only: it does not spend the caller's anonymous allowance that the other public reads (the catalogue among them) share.","tags":["public"],"security":[],"responses":{"200":{"description":"The widget's appearance and availability.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicChatConfig"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/chat/{publicKey}/challenge":{"parameters":[{"$ref":"#/components/parameters/ChatPublicKey"}],"get":{"operationId":"getPublicChatChallenge","summary":"The ticket form's Turnstile challenge, as a page to frame (our own chat only).","description":"**Anonymous.** An HTML page holding one Cloudflare Turnstile challenge. The chat's ticket form frames it and receives the token by `postMessage`, so one Turnstile widget (listing our own API hostname) serves every site the chat runs on — a widget lists at most 10 hostnames and an account holds at most 20 widgets (Q272).\n\nAn iframe navigation sends no `Origin`, so the parent page is named in `origin` and must be one the widget lists; the response's `frame-ancestors` is exactly that origin and the token is posted to it alone. `404` for every customer's widget, for an origin the widget does not list, and when no Turnstile site key is configured.","tags":["public"],"security":[],"parameters":[{"name":"origin","in":"query","required":true,"description":"The framing page's origin, e.g. `https://storeflips.com`.","schema":{"type":"string","maxLength":200}},{"name":"locale","in":"query","required":false,"description":"The challenge's language (the visitor's page language).","schema":{"type":"string","maxLength":16}}],"responses":{"200":{"description":"The challenge page.","content":{"text/html":{"schema":{"type":"string"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/chat/{publicKey}/conversations":{"parameters":[{"$ref":"#/components/parameters/ChatPublicKey"}],"post":{"operationId":"startPublicChatConversation","summary":"A visitor says something for the first time.","description":"**Anonymous.** Opens a conversation and writes the visitor's first message, then lets the assistant answer it inline if the customer has AI switched on.\n\nThe response carries a `visitorToken` **once and never again**. It is a bearer secret — the only thing standing between one visitor and another's transcript on the same site — so the widget keeps it in the visitor's own storage and presents it in `X-Zinn-Chat-Token` on every subsequent call. It is never accepted in a query string, because a query string is written to every access log.\n\nOur own proof walks send `X-Zinn-Probe-Token`. When it matches the platform's live-probe secret exactly, the conversation is marked as test traffic: it never sends a \"Missed chat\" email and never alerts staff. Any other value, or no configured secret, changes nothing.","tags":["public"],"security":[],"parameters":[{"name":"X-Zinn-Probe-Token","in":"header","required":false,"description":"Platform-internal. Marks a conversation started by our own proof walk as test traffic. A visitor never sends it; a wrong value is ignored.","schema":{"type":"string","maxLength":256}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicChatMessageCreate"}}}},"responses":{"201":{"description":"The conversation, its token, and everything said so far.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicChatStarted"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/chat/{publicKey}/conversations/{conversationId}/human":{"parameters":[{"$ref":"#/components/parameters/ChatPublicKey"},{"$ref":"#/components/parameters/ChatConversationId"}],"post":{"operationId":"requestPublicChatHuman","summary":"The visitor asks for a person.","description":"**Anonymous**, authorised by `X-Zinn-Chat-Token`. Moves the conversation into the operator queue. Idempotent — asking twice is the same as asking once.","parameters":[{"name":"after","in":"query","required":false,"description":"Return the turns after this `seq`. Omitted, only the turns this call wrote are returned — the widget appends what it is handed, so the thread from 0 would show the visitor the whole conversation twice (D34424).","schema":{"type":"integer","minimum":0}}],"tags":["public"],"security":[],"responses":{"200":{"description":"The thread, now waiting for an operator.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicChatThread"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/chat/{publicKey}/conversations/{conversationId}/ticket":{"parameters":[{"$ref":"#/components/parameters/ChatPublicKey"},{"$ref":"#/components/parameters/ChatConversationId"}],"post":{"operationId":"submitPublicChatTicket","summary":"The visitor turns the chat into a support ticket (our own websites only).","description":"**Anonymous**, authorised by `X-Zinn-Chat-Token`. Only OUR OWN chat widget (owned by the platform org) has this route; every customer's widget answers `404`, like an unknown key. Files a real support ticket in the plugin-support desk with the chat transcript attached, e-mails the visitor a copy, and the AI ticket agent answers it.\n\nFour controls in order, so the vendor call is last: a fail-closed budget per client and globally (`429`), the visitor token, a honeypot field (`website`, answered `202` and discarded), and Cloudflare Turnstile verified server-side and fail-closed (`422`).","parameters":[{"name":"after","in":"query","required":false,"description":"Return the turns after this `seq`. Omitted, only the turns this call wrote are returned — the widget appends what it is handed, so the thread from 0 would show the visitor the whole conversation twice (D34424).","schema":{"type":"integer","minimum":0}}],"tags":["public"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicChatTicketCreate"}}}},"responses":{"201":{"description":"The ticket reference and the thread, with the confirmation line.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicChatTicketCreated"}}}},"202":{"description":"Accepted and discarded (the honeypot was filled)."},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/chat/{publicKey}/conversations/{conversationId}/ticket/answer":{"parameters":[{"$ref":"#/components/parameters/ChatPublicKey"},{"$ref":"#/components/parameters/ChatConversationId"}],"post":{"operationId":"answerPublicChatTicket","summary":"The AI answer shown before the chat's ticket is filed (our own websites only).","description":"**Anonymous**, authorised by `X-Zinn-Chat-Token` (s1014 L39). Only OUR OWN chat widget has this route; every customer's widget answers `404`. The same grounded answer as `POST /v1/public/support/deflect` (surface `chat`); pass its `deflection_id` to the ticket route when the visitor still wants the ticket. Never blocks the ticket.","tags":["public"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","maxLength":8000},"locale":{"type":"string","maxLength":20}}}}}},"responses":{"200":{"description":"The answer, its record id and the matching help articles.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicSupportAnswer"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/chat/{publicKey}/conversations/{conversationId}/ticket/solved":{"parameters":[{"$ref":"#/components/parameters/ChatPublicKey"},{"$ref":"#/components/parameters/ChatConversationId"}],"post":{"operationId":"markPublicChatAnswerSolved","summary":"\"That solved it\" on the chat's ticket form (our own websites only).","description":"**Anonymous**, authorised by `X-Zinn-Chat-Token` (s1014 L39). Counts the answer from `answerPublicChatTicket` as a ticket the AI prevented. Moves only a PUBLIC answer from the last 24 hours; `204` whether or not anything moved.","tags":["public"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["deflection_id"],"properties":{"deflection_id":{"$ref":"#/components/schemas/Uuid"}}}}}},"responses":{"204":{"description":"Recorded (or nothing to record)."},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/v1/public/chat/{publicKey}/conversations/{conversationId}/messages":{"parameters":[{"$ref":"#/components/parameters/ChatPublicKey"},{"$ref":"#/components/parameters/ChatConversationId"}],"get":{"operationId":"pollPublicChatMessages","summary":"Anything said since the visitor's cursor.","description":"**Anonymous**, authorised by `X-Zinn-Chat-Token`. Returns immediately — empty if there is nothing — and tells the caller when to ask again in `pollAfterMs`.\n\n⛔ This endpoint does **not** hold the connection open, and no future version of it should. The engine is WSGI with a small fixed number of concurrent request slots, so a long-poll or an SSE stream here would consume a share of the entire platform's capacity per open chat. When concurrency outgrows short-polling, chat moves to its own ASGI service — it does not become a socket on this one.\n\n⭐ `pollAfterMs` is decided by the server, never by the widget. A cadence baked into a JavaScript file is cached on somebody else's site behind somebody else's CDN, so the one number governing fleet-wide load would be the one number we could not change.","tags":["public"],"security":[],"parameters":[{"name":"after","in":"query","required":false,"description":"The highest `seq` the caller already has. A per-conversation counter, not a timestamp: two messages written in the same millisecond are indistinguishable by clock, so a time cursor either repeats one or loses one.","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"New turns, the cursor, and when to come back.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicChatThread"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}},"post":{"operationId":"sendPublicChatMessage","summary":"The visitor says something else.","description":"**Anonymous**, authorised by `X-Zinn-Chat-Token`. The message is written to the database in this request, before any operator or assistant is involved — so nothing is lost when a consumer is down. A visitor writing into a conversation the operator had closed reopens it rather than being told it is over.","tags":["public"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicChatMessageCreate"}}}},"responses":{"201":{"description":"The thread, including whatever was said in reply.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicChatThread"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}}},"webhooks":{"ads.finding.opened":{"post":{"operationId":"adsWebhookFindingOpened","summary":"A Zinn® Ads finding opened on an ad account (za-192).","description":"Sent to every verified webhook endpoint subscribed to `ads.finding.opened` (`PUT /v1/ads/webhooks/{connection_id}`). The body is `{\"id\",\"type\",\"topic\":\"ads\",\"org_id\", \"subject\",\"text\",\"html\",\"data\"}`; `data` is this event. Verify `X-Zinn-Signature` (HMAC-SHA256 of `\"<X-Zinn-Timestamp>.<raw body>\"` with the endpoint's signing secret), reject a timestamp older than 5 minutes, dedupe on `X-Zinn-Delivery`, answer 2xx within 10 seconds.","tags":["ads"],"parameters":[{"name":"X-Zinn-Signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Zinn-Timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Zinn-Delivery","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-Zinn-Event","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","topic","org_id","data"],"properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["ads.finding.opened"]},"topic":{"type":"string","enum":["ads"]},"org_id":{"type":"string","format":"uuid"},"subject":{"type":"string"},"text":{"type":"string"},"html":{"type":"string"},"data":{"$ref":"#/components/schemas/AdsWebhookEventFindingOpened"}}}}}},"responses":{"200":{"description":"Received. Any 2xx counts; anything else is retried."}}}},"ads.change.applied":{"post":{"operationId":"adsWebhookChangeApplied","summary":"A change reached an ad account (za-192).","description":"Sent to every verified webhook endpoint subscribed to `ads.change.applied` (`PUT /v1/ads/webhooks/{connection_id}`). The body is `{\"id\",\"type\",\"topic\":\"ads\",\"org_id\", \"subject\",\"text\",\"html\",\"data\"}`; `data` is this event. Verify `X-Zinn-Signature` (HMAC-SHA256 of `\"<X-Zinn-Timestamp>.<raw body>\"` with the endpoint's signing secret), reject a timestamp older than 5 minutes, dedupe on `X-Zinn-Delivery`, answer 2xx within 10 seconds.","tags":["ads"],"parameters":[{"name":"X-Zinn-Signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Zinn-Timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Zinn-Delivery","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-Zinn-Event","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","topic","org_id","data"],"properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["ads.change.applied"]},"topic":{"type":"string","enum":["ads"]},"org_id":{"type":"string","format":"uuid"},"subject":{"type":"string"},"text":{"type":"string"},"html":{"type":"string"},"data":{"$ref":"#/components/schemas/AdsWebhookEventChangeApplied"}}}}}},"responses":{"200":{"description":"Received. Any 2xx counts; anything else is retried."}}}},"ads.alert.started":{"post":{"operationId":"adsWebhookAlertStarted","summary":"A Zinn® Ads warning started (za-192).","description":"Sent to every verified webhook endpoint subscribed to `ads.alert.started` (`PUT /v1/ads/webhooks/{connection_id}`). The body is `{\"id\",\"type\",\"topic\":\"ads\",\"org_id\", \"subject\",\"text\",\"html\",\"data\"}`; `data` is this event. Verify `X-Zinn-Signature` (HMAC-SHA256 of `\"<X-Zinn-Timestamp>.<raw body>\"` with the endpoint's signing secret), reject a timestamp older than 5 minutes, dedupe on `X-Zinn-Delivery`, answer 2xx within 10 seconds.","tags":["ads"],"parameters":[{"name":"X-Zinn-Signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Zinn-Timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Zinn-Delivery","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-Zinn-Event","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","topic","org_id","data"],"properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["ads.alert.started"]},"topic":{"type":"string","enum":["ads"]},"org_id":{"type":"string","format":"uuid"},"subject":{"type":"string"},"text":{"type":"string"},"html":{"type":"string"},"data":{"$ref":"#/components/schemas/AdsWebhookEventAlertStarted"}}}}}},"responses":{"200":{"description":"Received. Any 2xx counts; anything else is retried."}}}}},"components":{"headers":{"RateLimitRemaining":{"description":"Requests remaining in the current rate-limit window.","schema":{"type":"integer","minimum":0}}},"parameters":{"ActiveOrg":{"name":"X-Zinn-Org","in":"header","required":false,"description":"**Which organisation this call acts for.** Send a client organisation's id and every org-scoped endpoint answers for that client alone; omit it and the answer covers everything the credential can read.\n\n⭐ This is what gives a **reseller or agency full parity with a first-party customer**: a wholesale credential can read its entire subtree, so without a way to say *which client*, a list returns every client's estate at once and a create has no stated owner. The header is read once, centrally (`engine.api.scoping.adopt_active_org_header`), so it applies to every org-scoped operation in this document — including ones added after you integrate.\n\n⛔ It can only ever **narrow**. An organisation outside the credential's reach narrows the answer to nothing rather than returning `403`, because a `403` would confirm that organisation exists. It never grants reach a credential does not already have, and the per-organisation permission check is unchanged.\n\n⛔ Where an operation also declares an `org_id` query parameter, **the parameter wins.** Send either; send both only if they agree.\n\n⚠️ A value that is not a UUID is **ignored**, not refused — the answer is exactly what you would get with no header at all.","schema":{"type":"string","format":"uuid"}},"AdsAnalyticsCampaign":{"name":"campaign","in":"query","required":false,"description":"Comma-separated `<connection_id>:<campaign_id>` tokens.","schema":{"type":"string"}},"AdsAnalyticsClient":{"name":"client","in":"query","required":false,"description":"za-287: comma-separated client organisation ids. The read narrows to each client and its own clients, so an agency sees the same screen for one client. A client the caller cannot view is a 404 (`refusal.adsconnect.noSuchOrg`), never an empty answer.","schema":{"type":"string"}},"AdsAnalyticsCompare":{"name":"compare","in":"query","required":false,"schema":{"type":"string","enum":["previous","year","none"],"default":"previous"}},"AdsAnalyticsConnection":{"name":"connection","in":"query","required":false,"description":"Comma-separated ad-account connection ids.","schema":{"type":"string"}},"AdsAnalyticsCountry":{"name":"country","in":"query","required":false,"description":"Comma-separated ISO 3166-1 alpha-2 codes. Reads the country-level figures.","schema":{"type":"string"}},"AdsAnalyticsCurrency":{"name":"currency","in":"query","required":false,"description":"Reporting currency (ISO 4217). Default the one currency in play, else the organisation's.","schema":{"type":"string"}},"AdsAnalyticsDevice":{"name":"device","in":"query","required":false,"description":"Comma-separated devices: `mobile`, `desktop`, `tablet`, `tv`, `other` (za-282). Reads the device-level figures (Google Ads accounts, campaign grain). No stored level is split by both country and device, so `device` with `country` is refused (422, field `device`).","schema":{"type":"string"}},"AdsAnalyticsFrom":{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date"}},"AdsAnalyticsGrain":{"name":"grain","in":"query","required":false,"description":"Bucket size. Default day up to 92 days, week up to 366, month beyond.","schema":{"type":"string","enum":["day","week","month"]}},"AdsAnalyticsNetwork":{"name":"network","in":"query","required":false,"description":"Comma-separated networks (google, microsoft, meta, linkedin, tiktok, x, pinterest, amazon).","schema":{"type":"string"}},"AdsAnalyticsOffering":{"name":"offering","in":"query","required":false,"description":"Comma-separated product/site ids (za-290), or `unassigned`.","schema":{"type":"string"}},"AdsAnalyticsRange":{"name":"range","in":"query","required":false,"description":"The period. `custom` takes `from` and `to`.","schema":{"type":"string","enum":["7d","30d","90d","ytd","12m","custom"],"default":"30d"}},"AdsAnalyticsTo":{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date"}},"AgencyBoardAttachmentId":{"name":"attachmentId","in":"path","required":true,"description":"Board card attachment ID (UUIDv7).","schema":{"$ref":"#/components/schemas/Uuid"}},"AgencyBoardCardId":{"name":"cardId","in":"path","required":true,"description":"Board card ID (UUIDv7).","schema":{"$ref":"#/components/schemas/Uuid"}},"AgencyBoardChecklistItemId":{"name":"itemId","in":"path","required":true,"description":"Board checklist item ID (UUIDv7).","schema":{"$ref":"#/components/schemas/Uuid"}},"AgencyBoardColumnId":{"name":"columnId","in":"path","required":true,"description":"Board column ID (UUIDv7).","schema":{"$ref":"#/components/schemas/Uuid"}},"AgencyBoardId":{"name":"boardId","in":"path","required":true,"description":"Project board ID (UUIDv7).","schema":{"$ref":"#/components/schemas/Uuid"}},"AgencyBoardInviteId":{"name":"inviteId","in":"path","required":true,"description":"Board share-link ID (UUIDv7). Not the token — see `BoardShareToken`.","schema":{"$ref":"#/components/schemas/Uuid"}},"AgencyBoardLabelId":{"name":"labelId","in":"path","required":true,"description":"Board label ID (UUIDv7).","schema":{"$ref":"#/components/schemas/Uuid"}},"AgencyBoardMemberId":{"name":"memberId","in":"path","required":true,"description":"Board membership ID (UUIDv7).","schema":{"$ref":"#/components/schemas/Uuid"}},"AgencyBoardQuestionId":{"name":"questionId","in":"path","required":true,"description":"Board question ID (UUIDv7).","schema":{"$ref":"#/components/schemas/Uuid"}},"AgencyBoardViewId":{"name":"viewId","in":"path","required":true,"description":"Board saved-view ID (UUIDv7).","schema":{"$ref":"#/components/schemas/Uuid"}},"AgencyInvoicingOrgId":{"name":"org_id","in":"query","required":false,"description":"Which of your organizations is invoicing. Required only when you belong to more than one — otherwise it is inferred from your DIRECT membership, never from the subtree-expanded scope set. ⛔ That distinction is load-bearing: an agency owner's scope includes every client org beneath them, so picking one arbitrarily would file an invoice, and the agency's own VAT number, under the wrong tenant. An id outside your direct memberships is a `404` rather than a `403`, so this can never widen scope.","schema":{"$ref":"#/components/schemas/Uuid"}},"ApiKeyId":{"name":"apiKeyId","in":"path","required":true,"description":"The API key's id.","schema":{"$ref":"#/components/schemas/Uuid"}},"BackupId":{"name":"backupId","in":"path","required":true,"description":"The backup's id (UUIDv7), as `getSiteBackups` reports it. **Ours**, minted when the row was written — never the storage key, which is an internal object path and is deliberately never published.","schema":{"$ref":"#/components/schemas/Uuid"}},"BoardAutomationRuleId":{"name":"ruleId","in":"path","required":true,"description":"Automation rule ID (UUIDv7).","schema":{"$ref":"#/components/schemas/Uuid"}},"BoardEventSubscriptionId":{"name":"subscriptionId","in":"path","required":true,"description":"Platform-event subscription ID (UUIDv7).","schema":{"$ref":"#/components/schemas/Uuid"}},"BoardInboundEndpointId":{"name":"endpointId","in":"path","required":true,"description":"Inbound endpoint ID (UUIDv7).","schema":{"$ref":"#/components/schemas/Uuid"}},"BoardInboundEndpointKey":{"name":"endpointKey","in":"path","required":true,"description":"The endpoint's opaque key — 32 hex characters. Deliberately not the board id: a board id in a URL customers paste into third-party systems leaks an internal identifier into somebody else's logs.","schema":{"type":"string","pattern":"^[0-9a-f]{32}$"}},"BoardShareToken":{"name":"shareToken","in":"path","required":true,"description":"The share link's bearer token, as it appears in the URL somebody pasted. **This is a credential**: 256 bits from a CSPRNG behind a `zbi_` prefix, and whoever holds it holds the grant.\n\n⛔ It travels in the path because a pasteable link is the entire feature — there is no header to put it in when the transport is a chat message. The mitigations that make that acceptable are a mandatory expiry, an optional use cap, revocation that cascades to seats, and a default grant that can read one board's client projection and write nothing (`docs/458` §3).","schema":{"type":"string","pattern":"^zbi_[A-Za-z0-9_-]{43}$","example":"zbi_hV3n2QpR8sT1uV4wX7yZ0aB3cD6eF9gH2iJ5kL8mN1o"}},"BoardWebhookDeliveryId":{"name":"deliveryId","in":"path","required":true,"description":"Webhook delivery ID (UUIDv7).","schema":{"$ref":"#/components/schemas/Uuid"}},"BoardWebhookId":{"name":"webhookId","in":"path","required":true,"description":"Outbound webhook subscription ID (UUIDv7).","schema":{"$ref":"#/components/schemas/Uuid"}},"BulkJobId":{"name":"bulkJobId","in":"path","required":true,"description":"Bulk job ID (UUIDv7).","schema":{"$ref":"#/components/schemas/Uuid"}},"CartId":{"name":"cartId","in":"path","required":true,"description":"The cart's id.","schema":{"$ref":"#/components/schemas/Uuid"}},"CdnRuleId":{"name":"ruleId","in":"path","required":true,"description":"The provider's own id for the rule.","schema":{"type":"string","maxLength":200}},"CertificateOrderId":{"name":"orderId","in":"path","required":true,"description":"The order's id, as `listCertificateOrders` reports it. Ours (UUIDv7).","schema":{"$ref":"#/components/schemas/Uuid"}},"ChatConversationId":{"name":"conversationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"ChatPublicKey":{"name":"publicKey","in":"path","required":true,"description":"The widget's public key. Public by design — it ships in the page source of every site that embeds the widget — so it NAMES a widget and authorises nothing; the `Origin` header is what gates the call.","schema":{"type":"string","maxLength":64}},"ChatWidgetId":{"name":"widgetId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"ComputeAddonPurchaseId":{"name":"purchaseId","in":"path","required":true,"description":"The purchase's id. **Ours** (UUIDv7), minted when the option was bought — never the provider's identifier for the add-on contract, which no client ever sees.","schema":{"$ref":"#/components/schemas/Uuid"}},"ComputeClusterId":{"name":"clusterId","in":"path","required":true,"description":"The cluster's id, as `listComputeClusters` reports it.","schema":{"$ref":"#/components/schemas/Uuid"}},"ComputeNetworkId":{"name":"networkId","in":"path","required":true,"description":"The private network's id, as `listComputeNetworks` reports it.","schema":{"$ref":"#/components/schemas/Uuid"}},"ComputeServerId":{"name":"serverId","in":"path","required":true,"description":"The server's id, as `listComputeServers` reports it. **Ours** (UUIDv7), minted when the order row was written — never the provider's own identifier for the machine.","schema":{"$ref":"#/components/schemas/Uuid"}},"ConfirmMailChange":{"name":"confirm_mail_change","in":"query","required":false,"description":"Set `true` to proceed with a record change that would move or remove this domain's inbound email (issue #622). Without it, a write that stops mail reaching a host it reaches today is refused `409 MAIL_CHANGE_REFUSED`, and the message names the mail hosts involved. Only the values `true` and `1` confirm — `false`, `0` and an empty value do not, so an unticked checkbox rendered into the query string cannot confirm on the customer's behalf.\n\nNothing else is gated by it: a write that does not touch the apex `MX` set, and the first `MX` added to a domain that has none, both proceed untouched.","schema":{"type":"boolean"}},"ConnectionId":{"name":"connectionId","in":"path","required":true,"description":"The MCP connection's id.","schema":{"$ref":"#/components/schemas/Uuid"}},"ConnectionProviderPath":{"name":"provider","in":"path","required":true,"description":"The third-party provider whose connections are addressed.","schema":{"$ref":"#/components/schemas/ConnectionProvider"}},"Cursor":{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a previous page's `page.next_cursor`.","schema":{"type":"string","maxLength":512}},"DeploymentId":{"name":"deploymentId","in":"path","required":true,"description":"Deployment ID (UUIDv7).","schema":{"$ref":"#/components/schemas/Uuid"}},"DevRequestId":{"name":"request_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"DomainId":{"name":"domainId","in":"path","required":true,"description":"The domain's id.","schema":{"$ref":"#/components/schemas/Uuid"}},"EmailRoutingAddressId":{"name":"addressId","in":"path","required":true,"description":"The provider's own id for the destination address.","schema":{"type":"string","maxLength":200}},"EmailRoutingRuleId":{"name":"ruleId","in":"path","required":true,"description":"The provider's own id for the routing rule.","schema":{"type":"string","maxLength":200}},"ExtraCode":{"name":"code","in":"path","required":true,"description":"The extra's code (e.g. `db_maintenance`).","schema":{"type":"string","maxLength":64}},"ExtraPurchaseId":{"name":"purchaseId","in":"path","required":true,"description":"The extra purchase's id.","schema":{"$ref":"#/components/schemas/Uuid"}},"GitHubFieldId":{"name":"fieldId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project field, by OUR id."},"GitHubItemId":{"name":"itemId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The item, by OUR id — not GitHub's node id, which is not a path-safe value."},"GitHubLinkId":{"name":"linkId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The GitHub Projects connection."},"HolderVerificationCaseId":{"name":"caseId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Uuid"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Client-generated key that makes an unsafe request replay-safe: the server stores the first response and returns it verbatim for repeats.","schema":{"type":"string","format":"uuid"}},"ImportId":{"name":"importId","in":"path","required":true,"description":"Site-import job ID (UUIDv7).","schema":{"$ref":"#/components/schemas/Uuid"}},"InvitationId":{"name":"invitationId","in":"path","required":true,"description":"The invitation's id.","schema":{"type":"string","format":"uuid"}},"InvoiceId":{"name":"invoiceId","in":"path","required":true,"description":"The billing document's id. This is the `Invoice`/`CreditNote` id — **not** the order's. It was the order's id while `/v1/invoices` projected orders (docs/34 §7); the projection was retired in #710 and `order_id` is now a separate field.","schema":{"$ref":"#/components/schemas/Uuid"}},"Limit":{"name":"limit","in":"query","required":false,"description":"Maximum items to return (page size).","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},"LineId":{"name":"lineId","in":"path","required":true,"description":"The cart line's id.","schema":{"$ref":"#/components/schemas/Uuid"}},"LinkEditId":{"name":"editId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The bulk edit's id."},"LinkTargetId":{"name":"targetId","in":"path","required":true,"description":"Link target ID (UUIDv7).","schema":{"$ref":"#/components/schemas/Uuid"}},"MailServiceId":{"name":"mailServiceId","in":"path","required":true,"description":"Email service ID (UUIDv7).","schema":{"$ref":"#/components/schemas/Uuid"}},"MailboxId":{"name":"mailboxId","in":"path","required":true,"description":"Mailbox ID (UUIDv7).","schema":{"$ref":"#/components/schemas/Uuid"}},"MigrationId":{"name":"migrationId","in":"path","required":true,"description":"The migration job's id (UUIDv7), as `listSiteMigrations` reports it. **Ours**, minted when the row was written — never anything the source host knows about.","schema":{"$ref":"#/components/schemas/Uuid"}},"OrderId":{"name":"orderId","in":"path","required":true,"description":"The order's id.","schema":{"$ref":"#/components/schemas/Uuid"}},"OrgId":{"name":"orgId","in":"path","required":true,"description":"Organization ID (UUIDv7).","schema":{"$ref":"#/components/schemas/Uuid"}},"OrgIdQuery":{"name":"org_id","in":"query","required":false,"description":"The organization this call acts on. Optional for a caller with exactly one direct membership; **required** for anyone with more than one — which is every reseller and every agency — because the engine refuses rather than guesses (a wrong guess here writes one tenant's gateway credentials under another tenant's Vault path).","schema":{"$ref":"#/components/schemas/Uuid"}},"PanelConnectionId":{"name":"connectionId","in":"path","required":true,"description":"The connected panel's id, as `listPanelConnections` reports it.","schema":{"$ref":"#/components/schemas/Uuid"}},"PanelLicenceId":{"name":"licenceId","in":"path","required":true,"description":"The licence's id, as `listPanelLicences` reports it. Ours (UUIDv7).","schema":{"$ref":"#/components/schemas/Uuid"}},"PartnerExternalId":{"name":"externalId","in":"path","required":true,"description":"YOUR id for that customer — whatever your own system calls them. It is what makes linking idempotent, and it is scoped to your partner programme: another partner's id is a `404` here.","schema":{"type":"string","maxLength":128}},"PartnerSiteMoveId":{"name":"moveId","in":"path","required":true,"description":"The move's `id`, as `createPartnerSiteMove` returned it.","schema":{"type":"string","format":"uuid"}},"PaymentMethodId":{"name":"paymentMethodId","in":"path","required":true,"description":"The stored payment method's id.","schema":{"type":"string","format":"uuid"}},"PluginSlug":{"name":"slug","in":"path","required":true,"description":"The plugin's directory name and text domain, e.g. `zinn-cache`.","schema":{"type":"string","maxLength":64,"pattern":"^[a-z0-9-]+$"}},"ProDiscountProduct":{"name":"product","in":"path","required":true,"description":"The Pro product's key, from `listProDiscounts` (`offers[].product`).","schema":{"type":"string","pattern":"^[a-z0-9-]+$","maxLength":64}},"ProposalId":{"name":"proposalId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"ProposalToken":{"name":"token","in":"path","required":true,"description":"The capability token from the link in the proposal e-mail.","schema":{"type":"string"}},"PublicCartItemId":{"name":"itemId","in":"path","required":true,"description":"The cart item's id.","schema":{"type":"string","format":"uuid"}},"PublicCartToken":{"name":"token","in":"path","required":true,"description":"The anonymous cart's opaque bearer token (`zgc_…`), as returned by `createPublicCart`. **It is a credential** — anyone holding it can read and modify the cart — and it travels in the URL, so it is logged wherever URLs are logged. That is tolerable only because the cart holds no personal data before checkout, the token dies the moment the cart is checked out, and it expires within 24 hours. Do not store it beyond the purchase and do not put it in a shared link.","schema":{"type":"string","minLength":8,"maxLength":128}},"QuotaResourceName":{"name":"resource","in":"path","required":true,"description":"Which metered per-site resource. Every SELLABLE resource is addressable: `disk` and `inodes` are written to the box where the driver can hold them, while `bandwidth` (since the owner's 2026-08-19 freeze ruling) and `database` (W43-78) are limits the platform enforces itself by freezing the site. A resource this site's platform cannot sell answers `404`.","schema":{"type":"string","enum":["disk","inodes","bandwidth","database"]}},"ReaderLocale":{"name":"locale","in":"query","required":false,"description":"BCP-47 language the reader is reading in (the app sends its UI locale). Used to translate communication text for this reader (docs/1067); verbatim text such as anchor texts and URLs is never translated. Defaults to the account locale.","schema":{"type":"string","maxLength":16}},"RecordId":{"name":"recordId","in":"path","required":true,"description":"The DNS record's provider id.","schema":{"type":"string","maxLength":255}},"RefundRequestId":{"name":"refundRequestId","in":"path","required":true,"description":"The refund request's id.","schema":{"$ref":"#/components/schemas/Uuid"}},"SeoDataSource":{"name":"source","in":"path","required":true,"description":"The SEO data source.","schema":{"type":"string","enum":["ahrefs_free","ahrefs","majestic","moz","semrush","se_ranking","openpagerank","zinn_authority"]}},"SeoProductCode":{"name":"product","in":"path","required":true,"description":"The credit tool (`listSeoProducts`).","schema":{"$ref":"#/components/schemas/SeoProductCode"}},"SiteBlueprintId":{"name":"siteBlueprintId","in":"path","required":true,"description":"A SITE blueprint's id (UUIDv7) — one of the customer's own captured sites. ⛔ Not a `blueprintId`: that names a published stack recipe, and the two are different resources that unfortunately share a word.","schema":{"$ref":"#/components/schemas/Uuid"}},"SiteId":{"name":"siteId","in":"path","required":true,"description":"Site ID (UUIDv7).","schema":{"$ref":"#/components/schemas/Uuid"}},"TransferId":{"name":"transferId","in":"path","required":true,"description":"Site transfer offer ID (UUIDv7).","schema":{"$ref":"#/components/schemas/Uuid"}},"VisibilityTargetId":{"name":"targetId","in":"path","required":true,"description":"The watched domain's id.","schema":{"$ref":"#/components/schemas/Uuid"}},"WordPressUploadId":{"name":"uploadId","in":"path","required":true,"description":"A resumable upload's id, from `startSiteWordPressUpload`.","schema":{"type":"string","format":"uuid"}}},"responses":{"CdnZoneNotOnAccount":{"description":"`CDN_ZONE_NOT_ON_ACCOUNT` — the CDN account the platform drives for this site holds no zone for its domain, so nothing zone-scoped can be read or written. **Not the caller's to retry** (W43-06, D25305).\n\nA `502` for the same reason `VENDOR_CREDENTIAL_REJECTED` is one: the provider answered, and its answer was that it does not have that zone. The credential is valid and is pointed at the wrong account, which is an operator's routing fault — so retrying is the one action guaranteed never to help, and a `503` asks for exactly that.\n\nIts own error `code` because the resolution differs from both neighbours: nothing needs re-issuing and nothing needs connecting — the site's CDN placement has to be repointed at the account that holds its zone. Until W43-06 every CDN operation below collapsed this into the `503`, and a site still on its `*.zinnpreview.com` preview domain hit it on every panel of the CDN tab, permanently.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"The request conflicts with current state (e.g. duplicate).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Authenticated but not permitted (RBAC scope or tenancy). Code `SITE_SUSPENDED` instead when the path is a suspended or quarantined site's access surface (file manager, web editor, SSH/SFTP/FTP credentials, WordPress sign-in, staging, backup downloads, cron, deploys, databases, mail, PHP/secrets, transfer): the caller holds the role, the site is closed until it is unsuspended (ABUSEINTAKE, docs/65 §7).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"MailChangeRefused":{"description":"The change would move or remove the domain's inbound email and was not confirmed (`MAIL_CHANGE_REFUSED`). Repeat the request with `confirm_mail_change=true` once the customer has agreed. Distinguished from a plain `CONFLICT` on purpose: this one is resolved by asking and retrying, not by refreshing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"The resource does not exist or is not in scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PayloadTooLarge":{"description":"The uploaded body exceeds the endpoint's documented size cap. Its own status rather than a `422`, because the client's response is different in kind: nothing about the request is malformed and re-sending it unchanged cannot help — the customer has to choose a smaller file.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ProviderNotConfigured":{"description":"`PROVIDER_NOT_CONFIGURED` — the account has no provider connected for this capability, so the platform **refused to serve the request rather than fake it** (issue #1039, ADR 0020). Nothing was changed.\n\nA `503` because nothing about the request is wrong and the identical call succeeds once an operator adds the account; its own error `code` rather than `SERVICE_UNAVAILABLE` because the resolution differs — this one is \"add a provider account\", not \"retry later\" — and a client cannot render the right panel if both arrive under one code.\n\n⛔ **Not retryable by the client.** The condition holds until a human acts, so an automatic retry loop only costs requests. The `request_id` is what support needs: the message deliberately withholds the org id, the Vault path and the seam name, which live in the correlated log line instead.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServiceUnavailable":{"description":"A dependency is unavailable. **Branch on `error.code`, not on the status** — two different facts arrive here and the caller's next action is opposite:\n\n* `SERVICE_UNAVAILABLE` — transient. The dependency was reached and failed, or was\n  briefly unreachable. Retrying shortly is the correct response. This includes the\n  platform's own database refusing a new connection, on ANY endpoint: nothing of the\n  request ran, and `Retry-After` (5 seconds) says when to try again (engine defects\n  2026-10-14 — these were `500`s before).\n\n* `PROVIDER_NOT_CONFIGURED` — **permanent until a human acts** (issue #1039). The\n  account has no provider connected for this capability and the platform refused to\n  serve the request on a fake rather than fabricate a result. Nothing was changed,\n  the request itself is fine, and **retrying can never succeed**. `Retry-After` is\n  set to an hour to say so; the operator fix is to add a provider account.\n\n\nA client that renders both as \"something went wrong, try again\" tells a customer to retry a condition only staff can clear — which is the exact failure this second code exists to prevent, so collapsing them re-introduces it one layer up.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequests":{"description":"Rate limit exceeded; retry after the indicated delay.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":0}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing or invalid credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnprocessableEntity":{"description":"The request was well-formed but failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"VendorCredentialRejected":{"description":"`VENDOR_CREDENTIAL_REJECTED` — the third-party provider answered and refused the credential we hold for this resource. **Not the caller's to retry** (W35-E, D16804).\n\nA `502` rather than a `503`, and the distinction is the whole point: the upstream answered us and said no, so nothing is unavailable and waiting changes nothing. Until W35-E every DNS provider failure — including a revoked token — arrived as the `503` that says *\"please try again shortly\"*, and a retry sends the same credential to the same endpoint, so the only remedy offered was the one that cannot ever work.\n\nIts own error `code` rather than `BAD_GATEWAY` because the resolution differs and a client cannot render the right panel otherwise: for a provider account the customer connected themselves the fix is on their Connections page; for one of ours it is a support request. The vendor's own words are logged and never returned — they name our pool account's endpoint."}},"schemas":{"AccelerateWp":{"type":"object","required":["tier","status","trial_ends_at","price_minor","currency","features","premium_available"],"properties":{"premium_available":{"type":"boolean","description":"Whether Premium may be bought right now. When false, `PUT` with `accelerate_wp_tier: premium` answers `409 ACCELERATE_WP_PREMIUM_UNAVAILABLE` and no trial starts. It is false while the premium features cannot run on the hosting fleet (W43-38)."},"tier":{"$ref":"#/components/schemas/AccelerateWpTier"},"status":{"$ref":"#/components/schemas/AccelerateWpStatus"},"trial_ends_at":{"type":["string","null"],"format":"date-time","description":"End of the per-site trial while trialing, else null."},"price_minor":{"type":"integer","minimum":0,"description":"Monthly price in integer minor units (CLAUDE.md §2.8). A flat integer plus code pair rather than a nested `MoneyAmount`, matching the shape the dashboard already consumes (docs/40 §7.3). Converted from the USD catalog price into the caller's currency."},"currency":{"type":"string","description":"ISO-4217 code the price_minor above is expressed in."},"features":{"type":"array","items":{"type":"string"},"description":"Stable machine identifiers for the premium features, localized by the client. Never human-readable text — that would put untranslatable English in front of every non-English locale (CLAUDE.md §2.7)."}}},"AccelerateWpStatus":{"type":"string","enum":["inactive","trialing","active"],"description":"Where the premium subscription sits in its lifecycle. Distinct from the tier, because a site can be on the premium tier while still in its trial."},"AccelerateWpTier":{"type":"string","enum":["free","premium"],"description":"The AccelerateWP tier. `free` is the absence of the upsell, not a tier of it — the free cache layers are separate booleans on `SitePerformance`."},"AccountBoostOffer":{"type":"object","required":["level","extra_code","multiplier_pct","cpu_percent","memory_mb","per_site_standard_minor","per_site_heavy_minor","minimum_minor","price_minor","currency","sites"],"additionalProperties":false,"properties":{"level":{"type":"integer"},"extra_code":{"type":"string"},"multiplier_pct":{"type":"integer","description":"CPU and memory as a percentage of the plan's rung."},"cpu_percent":{"type":"integer","description":"On a site at the growth floor (the usual plan rung)."},"memory_mb":{"type":"integer"},"per_site_standard_minor":{"type":"integer"},"per_site_heavy_minor":{"type":"integer"},"minimum_minor":{"type":"integer"},"price_minor":{"type":"integer","description":"What this account would pay a month today."},"currency":{"type":"string"},"sites":{"$ref":"#/components/schemas/AccountBoostSiteCounts"}}},"AccountBoostSiteCounts":{"type":"object","required":["standard","heavy"],"additionalProperties":false,"properties":{"standard":{"type":"integer","minimum":0},"heavy":{"type":"integer","minimum":0}}},"AccountBoostState":{"type":"object","required":["on_sale","level","held_level","suspended","held","eligible","lines","site_count","site_counts","sites","offers"],"additionalProperties":false,"properties":{"on_sale":{"type":"boolean","description":"False until the owner approves the prices; nothing can be bought while false."},"level":{"type":"integer","minimum":0,"maximum":3},"held_level":{"type":"integer","minimum":0,"maximum":3},"suspended":{"type":"boolean"},"held":{"oneOf":[{"$ref":"#/components/schemas/PbnBoostHeld"},{"type":"null"}]},"eligible":{"type":"boolean","description":"The account has a site or plan on a boosted line."},"lines":{"type":"array","items":{"type":"string"},"description":"The boosted lines the account holds."},"site_count":{"type":"integer","minimum":0},"site_counts":{"$ref":"#/components/schemas/AccountBoostSiteCounts"},"sites":{"$ref":"#/components/schemas/PbnBoostSites"},"offers":{"type":"array","items":{"$ref":"#/components/schemas/AccountBoostOffer"}}}},"AcquisitionTouchRequest":{"type":"object","required":["touch"],"properties":{"org_id":{"type":"string","format":"uuid","description":"The org to record against; optional when the caller owns exactly one."},"touch":{"type":"object","description":"Captured on landing. Kept keys: utm_source, utm_medium, utm_campaign, utm_term, utm_content, gclid, gbraid, wbraid, fbclid, ttclid, msclkid, twclid (a malformed twclid is dropped), oppref, ref, zd_vid, referrer_host, landing_page, and entry (only the value `direct`). Others are dropped.","additionalProperties":{"type":"string","maxLength":2048}},"latest":{"type":"object","description":"The campaign the visitor landed with most recently (the marketing edge's zinn_camp slot: the UTM parameters and landing_page), sent when it differs from `touch`. `touch` can still become the first touch; this becomes the last touch. Same kept keys as `touch`.","additionalProperties":{"type":"string","maxLength":2048}}}},"AcquisitionTouchResult":{"type":"object","required":["recorded","reason"],"properties":{"recorded":{"type":"boolean"},"reason":{"type":"string","enum":["","empty","impersonation","late","not_owner"]},"org_id":{"type":"string","format":"uuid"}}},"ActiveSurveys":{"type":"object","description":"⛔ `available: false` with an empty list is NOT the same fact as an empty list on its own. The first means we could not read; the second means every survey is archived.","required":["available","reason","surveys"],"properties":{"available":{"type":"boolean"},"reason":{"type":"string","enum":["","unconfigured","unreachable","refused","not_found","malformed"]},"surveys":{"type":"array","items":{"$ref":"#/components/schemas/Survey"}}}},"AddSiteSshKeyRequest":{"type":"object","description":"⛔ Shape only. What makes a public key valid is checked in the engine, deliberately: those rules are facts about what OpenSSH and the vendor accept, they must hold for a management command as well as for this endpoint, and the sentence a customer reads must be the same whichever door they came through — including the one that says *\"that is your private key\"*.","required":["handle","key"],"additionalProperties":false,"properties":{"handle":{"type":"string","minLength":1,"maxLength":64,"description":"What to file the key under. Constrained to `[A-Za-z0-9][A-Za-z0-9._-]{0,63}`; anything else is refused with our wording rather than the vendor's.","example":"laptop-2026"},"key":{"type":"string","minLength":1,"maxLength":8192,"description":"The public key line, as OpenSSH writes it."}}},"AdhocCharge":{"type":"object","description":"One staff-added billing instruction for one customer — an instruction to bill, not a bill. Every time its schedule comes due it becomes an ordinary order line on an ordinary order.\n\nThe staff-only fields (`internal_note`, `tax_note`, `created_by`, `created_reason`, `canceled_by`, `cancel_reason`) are present on the admin surface and absent from the customer's own read: one text field is written for them, the other is written about them.","required":["id","org_id","description","amount_minor","currency","taxable","recurrence","starts_on","status","created_at"],"properties":{"renews_as":{"description":"Q321 — for an SEO add-on's renewal, the smaller tier of the same tool the customer chose to replace it with at the next renewal (`scheduleExtraTierSwitch`); `null` otherwise.","oneOf":[{"type":"null"},{"type":"object","required":["code","name"],"properties":{"code":{"type":"string"},"name":{"type":"string"}}}]},"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"description":{"type":"string","maxLength":200,"description":"What the CUSTOMER reads on their invoice, verbatim. The whole of what they are given to recognise the charge by — an unexplained charge is a chargeback."},"amount_minor":{"type":"integer","format":"int64","description":"**NET**, in integer minor units of `currency`. Never a float and never a formatted string. Tax is added on top, never carved out."},"discount_minor":{"type":"integer","format":"int64","description":"The saving already taken off `amount_minor` — an SEO tool's yearly and 3-tool savings (D19), re-priced as the organisation's tool count crosses three. The renewal's invoice line shows `amount_minor + discount_minor` less this discount."},"currency":{"type":"string","minLength":3,"maxLength":3},"taxable":{"type":"boolean","description":"`false` means the supply is OUTSIDE THE SCOPE of VAT — a stated treatment on the invoice line, with `tax_note` giving the reason. It does not mean the tax seam was skipped."},"recurrence":{"type":"string","enum":["once","monthly","quarterly","semiannual","annual"]},"starts_on":{"type":"string","format":"date","description":"The first billing date AND the anchor for every later one. An item starting on the 31st bills on the 31st, or on that month's last day — never permanently on the 28th because February happened once."},"ends_on":{"type":"string","format":"date","nullable":true,"description":"Inclusive. A date named here is billed, not skipped."},"next_charge_on":{"type":"string","format":"date","nullable":true,"description":"Null once the schedule is finished or the item was stopped."},"status":{"type":"string","enum":["scheduled","completed","canceled"],"description":"`completed` and `canceled` are different facts: a one-off that billed has done its job; an item somebody stopped has not."},"created_at":{"type":"string","format":"date-time"},"internal_note":{"type":"string","description":"Staff-only. Why WE added it. Never returned to a customer."},"tax_note":{"type":"string","description":"Staff-only. Why this supply is outside the scope of VAT."},"created_by":{"type":"string","description":"Staff-only. `actor_ref` of the person who added it."},"created_reason":{"type":"string","description":"Staff-only. The answer to a chargeback months from now."},"canceled_at":{"type":"string","format":"date-time","nullable":true},"canceled_by":{"type":"string"},"cancel_reason":{"type":"string"},"invoice_lead_days":{"type":"integer","minimum":0,"maximum":60,"description":"How many days BEFORE each due date the invoice is issued (0 = on the due date). An advance invoice is payable at once and is charged and chased only from the due date (s1014 MOVEBUILD, docs/1104 §6)."},"tax_service_type":{"type":"string","enum":["","electronically_supplied","general_service"],"description":"Staff-only. The VAT classification; blank = the platform's answer for an ad-hoc item. `electronically_supplied` rates it as hosting at the customer's destination."},"subject_kind":{"type":"string","description":"Staff-only. What the charge bills — blank, `compute_service` (it IS the price of one of the customer's servers: unpaid on the suspend rung suspends that server, payment restores it), or a machine-written kind (`extra_purchase`, `compute_server`)."},"subject_id":{"type":"string","format":"uuid","nullable":true,"description":"Staff-only."}}},"AdhocChargeOccurrence":{"type":"object","description":"One billed period of one ad-hoc item — the claim, and the receipt. It exists only because the customer really was billed: the row and the order line are written in one transaction, so neither can exist without the other.","required":["id","charge_id","due_on","order_id","amount_minor","currency"],"properties":{"id":{"type":"string","format":"uuid"},"charge_id":{"type":"string","format":"uuid"},"due_on":{"type":"string","format":"date"},"order_id":{"type":"string","format":"uuid"},"amount_minor":{"type":"integer","format":"int64"},"currency":{"type":"string","minLength":3,"maxLength":3},"paid":{"type":"boolean","nullable":true,"description":"Tri-state. `null` means the order could not be read, which is a different fact from \"not paid\"."}}},"AdsAccountAds":{"type":"object","required":["connection_id","campaigns","ad_groups","ads"],"properties":{"connection_id":{"type":"string","format":"uuid"},"campaigns":{"type":"array","items":{"type":"object","required":["resource","id","name","status"],"properties":{"resource":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","description":"Google's status: ENABLED or PAUSED."}}}},"ad_groups":{"type":"array","items":{"type":"object","required":["resource","id","name","status","campaign_id"],"properties":{"resource":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"campaign_id":{"type":"string"}}}},"ads":{"type":"array","items":{"type":"object","required":["resource","id","status","type","headlines","descriptions","final_url","ad_strength","ad_group_id","campaign_id","rebuildable"],"properties":{"resource":{"type":"string"},"id":{"type":"string"},"status":{"type":"string"},"type":{"type":"string","description":"Google's ad type, e.g. RESPONSIVE_SEARCH_AD."},"headlines":{"type":"array","items":{"type":"string"}},"descriptions":{"type":"array","items":{"type":"string"}},"final_url":{"type":"string"},"ad_strength":{"type":"string"},"ad_group_id":{"type":"string"},"campaign_id":{"type":"string"},"rebuildable":{"type":"boolean","description":"A delete of this ad can be rebuilt (a responsive search ad with its texts and final URL); other types are deleted with their snapshot but cannot be rebuilt."}}}}}},"AdsAccountChecks":{"type":"object","required":["currency","window_days","maturity","shared_budgets","recommendations","self_audit","reconcile"],"properties":{"currency":{"type":"string"},"window_days":{"type":"integer"},"maturity":{"type":"object","required":["rate","clicks_needed","account_clicks","account_conversions","prior_rate","prior_clicks","window_days"],"properties":{"rate":{"type":"number"},"clicks_needed":{"type":"integer"},"account_clicks":{"type":"integer"},"account_conversions":{"type":"number"},"prior_rate":{"type":"number"},"prior_clicks":{"type":"integer"},"window_days":{"type":"integer"}}},"shared_budgets":{"type":"object","required":["moved","waiting","refused"],"properties":{"moved":{"type":"array","items":{"type":"object","required":["campaign","from_budget_name","to_micros"],"properties":{"campaign":{"type":"string"},"from_budget_name":{"type":"string"},"to_micros":{"type":"integer","format":"int64"}}}},"waiting":{"type":"array","items":{"type":"object","required":["suggestion_id","budget_name","shared_micros","campaigns"],"properties":{"suggestion_id":{"type":"string","format":"uuid"},"budget_name":{"type":"string"},"shared_micros":{"type":"integer","format":"int64"},"campaigns":{"type":"array","items":{"type":"string"}}}}},"refused":{"type":"array","items":{"type":"string"}}}},"recommendations":{"type":"object","required":["totals","data"],"properties":{"totals":{"type":"object","required":["ignored","part","owner","accepted"],"properties":{"ignored":{"type":"integer"},"part":{"type":"integer"},"owner":{"type":"integer"},"accepted":{"type":"integer"}}},"data":{"type":"array","items":{"type":"object","required":["google_type","outcome","campaign","reviewed_at"],"properties":{"google_type":{"type":"string"},"outcome":{"type":"string","enum":["ignored","part","owner","accepted"]},"campaign":{"type":"string"},"reviewed_at":{"type":"string","format":"date-time"}}}}}},"self_audit":{"type":"object","required":["window_days","negatives","keywords","collisions_refused"],"properties":{"window_days":{"type":"integer"},"negatives":{"type":"object","required":["count","cost_before_micros","cost_after_micros","clicks_blocked"],"properties":{"count":{"type":"integer"},"cost_before_micros":{"type":"integer","format":"int64"},"cost_after_micros":{"type":"integer","format":"int64"},"clicks_blocked":{"type":"integer"}}},"keywords":{"type":"array","items":{"type":"object","required":["term","campaign","added","clicks","cost_micros","conversions_milli","paused"],"properties":{"term":{"type":"string"},"campaign":{"type":"string"},"added":{"type":"string","format":"date"},"clicks":{"type":"integer"},"cost_micros":{"type":"integer","format":"int64"},"conversions_milli":{"type":"integer","format":"int64","description":"RECORDED conversions x 1000 (MSALLCONV-FU2): every conversion the network recorded, biddable goal or not."},"paused":{"type":"boolean"}}}},"collisions_refused":{"type":"integer"}}},"reconcile":{"type":"object","description":"za-87 — the customer's outcomes of the window against Google's latest count of them. `states` splits the difference: `processing` = uploaded in the last two days (Google reports hours later, so not counted yet — not a loss); `queued`, `refused` (by Google), `not_uploadable`; `no_ad_click` = not from an advert click, nothing to attribute.","required":["from_ad_click","states","google"],"properties":{"from_ad_click":{"type":"integer"},"states":{"type":"object","required":["uploaded","processing","queued","refused","not_uploadable","no_ad_click"],"properties":{"uploaded":{"type":"integer"},"processing":{"type":"integer"},"queued":{"type":"integer"},"refused":{"type":"integer"},"not_uploadable":{"type":"integer"},"no_ad_click":{"type":"integer"}}},"google":{"type":["object","null"],"description":"The latest tracking check; null = none has run yet.","required":["day","window_start","window_end","status","real","credited","gap_pct"],"properties":{"day":{"type":"string","format":"date"},"window_start":{"type":"string","format":"date"},"window_end":{"type":"string","format":"date"},"status":{"type":"string","enum":["ok","gap","unreadable","too_few"]},"real":{"type":"integer"},"credited":{"type":["integer","null"]},"gap_pct":{"type":["integer","null"]}}}}}}},"AdsAccountConnection":{"type":"object","description":"One of the organisation's connected ad accounts. The token is never served.","required":["id","org_id","platform","external_id","login_external_id","label","status","modes","daily_ceiling_minor","monthly_ceiling_minor","ceiling_currency","account_currency","datamanager_granted","uploads_need_reconnect","needs_reconnect","grant_ref","pending_changes","created_at","disconnected_at","hold_until_sale","roas_target_pct","markets","competitor_automation","collision_mode","auto_new_countries","new_country_max_per_month","new_country_budget_minor","new_country_min_conversions","new_country_min_clicks","auto_cap_raise","auto_bid_switch","auto_push_tests","push_test_max_running","push_test_confidence_pct","push_test_confidence_recommended","budget_raise_mode","budget_raise_scope","budget_raise_campaigns","budget_raise_built","warm_start_until","pacing_mode","pacing_deviation_pct","pacing_target_minor","pacing_strategy","pacing_change_cap_pct","pacing_rollover","pacing_pause_over","pacing_minimums","tidy_paused_days","tidy_paused_mode","shield_min_clicks","shield_stale_days","shield_waste_min_clicks","shield_recommended","business_type","ladder_signals","campaign_ladder","excluded_countries","country_waste_mode","country_cut_on","country_cut_window_days","country_cut_spend_minor","country_cut_share_pct","country_cut_rate_pct","country_cut_keep","country_cut_recommended","conversion_lag_days","cta_words","waste_threshold_minor","cluster_min_terms","focus_min_conversions","free_plan_campaigns","offer_profiles","rsa_tests","rsa_test_confidence_pct","rsa_test_min_impressions","rsa_test_min_clicks","rsa_test_min_days","rsa_test_metric","rsa_test_recommended","reach_min_searches","reach_test_days","reach_recommended"],"properties":{"rsa_tests":{"type":"boolean","description":"RSATEST (za-197) — RSA A/B tests in the daily audit: the two ads of an ad group rotate evenly, a winner is called only at `rsa_test_confidence_pct` with the minimum data, and the loser is replaced through the `ads` mode and the za-171 ad-quality gate. Recommended on."},"rsa_test_confidence_pct":{"type":"integer","minimum":80,"maximum":99,"description":"RSATEST (za-197) — the confidence a winner needs (p below 1 - this/100). Recommended 95."},"rsa_test_min_impressions":{"type":"integer","minimum":100,"maximum":10000000,"description":"RSATEST (za-197) — impressions EACH variant needs before any verdict. Recommended 1000."},"rsa_test_min_clicks":{"type":"integer","minimum":1,"maximum":1000000,"description":"RSATEST (za-197) — clicks EACH variant needs before any verdict. Recommended 50."},"rsa_test_min_days":{"type":"integer","minimum":7,"maximum":90,"description":"RSATEST (za-197) — days measured (from the day rotation is even) before any verdict. Recommended 14."},"rsa_test_metric":{"type":"string","enum":["ctr","conversions"],"description":"RSATEST (za-197) — clicks per impression, or conversions per impression. Recommended `ctr`."},"rsa_test_recommended":{"description":"RSATEST (za-197) — the Recommended value of each `rsa_test*` setting (\"Reset to recommended\").","allOf":[{"$ref":"#/components/schemas/AdsRsaTestSettings"}]},"reach_min_searches":{"type":"integer","minimum":1,"maximum":1000000,"description":"za-86 (PARITY86) — the measured monthly searches a phrase needs before it broadens a campaign that cannot enter the auction (added as a PHRASE keyword through the `keywords` mode). Recommended 10."},"reach_test_days":{"type":"integer","minimum":7,"maximum":60,"description":"za-86 (PARITY86) — days of the reach test after a broadening; still no impression at the end → paused (Automatic `pauses`) or offered as one click (Ask me first). Recommended 14."},"reach_recommended":{"description":"za-86 (PARITY86) — the Recommended value of each `reach_*` setting (\"Reset to recommended\").","allOf":[{"$ref":"#/components/schemas/AdsReachSettings"}]},"waste_threshold_minor":{"type":["integer","null"],"format":"int64","minimum":1,"maximum":10000000000,"description":"WASTEFIX r3 (za-79, owner 2026-10-30 \"they should be able to edit all things like this with their own values and we honour it\") — the spend, in minor units of the account currency, after which a search that never converted counts as waste (blocked or suggested). null = the recommended value, what one conversion costs on this account (`AdsAutopilot.own_values.waste_threshold_recommended_minor`), the default."},"cluster_min_terms":{"type":["integer","null"],"minimum":2,"maximum":50,"description":"WASTEFIX r3 (za-79) — how many small searches that never converted must share a word before that word is blocked as a cluster negative. null = the recommended 5, the default."},"focus_min_conversions":{"type":["integer","null"],"minimum":1,"maximum":1000,"description":"ADSFOCUS-GUARD (za-258) — the conversions the account's enabled primary actions must record in 30 days before a Google campaign bidding for clicks is moved to Maximise conversions with no target. null = the recommended 15, the default."},"conversion_lag_days":{"type":["integer","null"],"minimum":1,"maximum":90,"description":"PARITY-B (za-93) — the customer's own trial or sales window in days: a sales verdict waits for trials and leads still inside it (counted pending, never \"no sale\"). null = sales are judged at once, the default."},"cta_words":{"type":"array","maxItems":10,"items":{"type":"string","maxLength":60},"description":"PARITY-B (za-92) — the words a landing-page button must say (\"Book a call\"); an ad whose page has no button saying any of them is an `lp_cta_wrong` finding. [] = not checked, the default."},"free_plan_campaigns":{"type":"array","items":{"type":"string","pattern":"^[0-9]{1,20}$"},"description":"za-251 (NEGPLAN): the Google campaign ids whose product has a free plan or free listing — the customer's tickbox. Those campaigns get no \"free\" starter negatives and a \"free\" search there is not a waste class (judged on its spend like any other). [] = none, the default: \"free\" searches are blocked everywhere."},"offer_profiles":{"type":"object","description":"OFFERFIT (docs/1006.d/features/za-261-offerfit.md): per Google campaign id, what the campaign sells. `auto` is the profile the daily audit read from its ads, keywords and landing pages (null until the first audit); `edit` is the customer's own words, which win when present. Every search and own keyword is judged against the profile in force: a search judged off it is blocked EXACT from its first click, an off-offer keyword, a tighter match type and a PHRASE negative are one-click proposals.","additionalProperties":{"type":"object","required":["auto","edit","edited"],"properties":{"auto":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/AdsOfferProfile"}]},"edit":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/AdsOfferProfileEdit"}]},"edited":{"type":"boolean"}}}},"excluded_countries":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"},"description":"ZWASTE1 (za-175): countries this account never serves (ISO 3166-1 alpha-2). Each day every enabled campaign that does not already exclude one gets it as a negative location, through the `negatives` mode (approve-first unless Automatic)."},"country_waste_mode":{"type":"string","enum":["auto","suggest","off"],"description":"ZWASTE1 (za-175 / za-176): countries that spent with no FIRST-PARTY outcome (an activation, a real install, a real domain live, a sale — never a platform sign-up or trial) over 60 days, while expected to have brought at least 2 at the account's own rate. `suggest` (the default) queues the exclusion for approval; `auto` makes it inside the `negatives` mode (a country in `markets` still waits for a person); `off` does not look. An account whose deeper signals recorded nothing is never judged."},"country_cut_on":{"type":"boolean","description":"COUNTRYCUT (owner 2026-10-30, docs/1006 §COUNTRYCUT) — on by default. Inside an enabled campaign that serves several countries, a country with no sale is excluded from THAT campaign when, over `country_cut_window_days`, it spent at least `country_cut_spend_minor`, or it took more than `country_cut_share_pct` of the campaign's spend while converting below `country_cut_rate_pct` of the campaign's rate — once its clicks are enough to judge it. Applied on Automatic `negatives`, queued otherwise; every cut has the one-click Undo. Never the campaign's only target, never a pinned (`country_cut_keep`) country."},"country_cut_window_days":{"type":"integer","minimum":7,"maximum":90,"description":"The customer's window; recommended 14."},"country_cut_spend_minor":{"type":["integer","null"],"minimum":1,"maximum":10000000000,"description":"Spend with no sale that cuts a country, in account-currency minor units. null = the recommended £25 converted at today's stored rate (`country_cut_recommended`)."},"country_cut_share_pct":{"type":"integer","minimum":5,"maximum":95,"description":"Share of the campaign's spend; recommended 30."},"country_cut_rate_pct":{"type":"integer","minimum":5,"maximum":100,"description":"A country's conversion rate as a percentage of its campaign's; recommended 50 (half)."},"country_cut_keep":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"},"description":"Pinned countries (ISO 3166-1 alpha-2) — never cut."},"country_cut_recommended":{"$ref":"#/components/schemas/AdsCountryCutRecommended"},"business_type":{"$ref":"#/components/schemas/AdsBusinessType"},"ladder_signals":{"$ref":"#/components/schemas/AdsLadderSignals"},"campaign_ladder":{"$ref":"#/components/schemas/AdsCampaignLadder"},"pacing_mode":{"$ref":"#/components/schemas/AdsPacingMode"},"pacing_deviation_pct":{"type":"integer","minimum":5,"maximum":50,"description":"za-N17: how far (percent) the month-end spend forecast may drift from the target before it is a warning (default 10)."},"pacing_target_minor":{"type":["integer","null"],"format":"int64","description":"za-N17: the month's spend target in minor units of the account's currency; null = what the enabled daily budgets plan for the month, never above the monthly ceiling."},"pacing_strategy":{"$ref":"#/components/schemas/AdsPacingStrategy"},"pacing_change_cap_pct":{"type":"integer","minimum":5,"maximum":50,"description":"za-199 — the most one pacing run changes a budget, percent (default 30)."},"pacing_rollover":{"type":"boolean","description":"za-199 — carry last month's unspent spend target into this month (an explicit `pacing_target_minor` only, never chained, never past the monthly ceiling)."},"pacing_pause_over":{"type":"boolean","description":"za-199 — once the month has spent its monthly ceiling, pause the campaigns that spend (through the `pauses` mode, with Undo) and resume them on the 1st. Off by default: under the ceiling the budgets are trimmed and the account is never paused."},"pacing_minimums":{"type":"object","additionalProperties":{"type":"integer","format":"int64","minimum":1},"description":"za-199 — Google campaign id → minimum daily budget in minor units; a pacing cut never takes the campaign under it."},"tidy_paused_days":{"type":["integer","null"],"minimum":1,"maximum":365,"description":"ADMGMT1 \"Tidy paused ads after N days\": an ad paused this many days (counted from the day Zinn® Ads first saw it paused) is deleted, keeping its snapshot and Rebuild. null = off, the default for every account."},"shield_min_clicks":{"type":["integer","null"],"description":"IPROTATE (za-59): suspected clicks from one address before the click shield proposes excluding it. null = our recommended value (`shield_recommended`)."},"shield_stale_days":{"type":["integer","null"],"description":"An exclusion whose source cost money within this many days is never rotated out at Google's 500-per-campaign cap. null = recommended."},"shield_waste_min_clicks":{"type":["integer","null"],"description":"Clicks with cost and no conversion (30 days) before a placement or audience segment is proposed for exclusion. null = recommended."},"shield_recommended":{"type":"object","description":"Our recommended value of each shield threshold (shown as \"Recommended\").","required":["shield_min_clicks","shield_stale_days","shield_waste_min_clicks"],"properties":{"shield_min_clicks":{"type":"integer"},"shield_stale_days":{"type":"integer"},"shield_waste_min_clicks":{"type":"integer"}}},"tidy_paused_mode":{"type":"string","enum":["auto","suggest"],"description":"`suggest` (the default) queues each delete for approval; `auto` deletes it inside the `ads` mode (`off` still wins; a plan without autopilot queues it instead)."},"auto_bid_switch":{"type":"boolean","description":"LADDERFIX (owner 2026-11-03): \"Let Zinn® Ads switch bidding automatically when there's enough data\". Default `false`: a move onto Maximise conversions, target CPA, Maximise conversion value or target ROAS needs at least 15 of the campaign's OWN primary conversions in 30 days (with values for a value strategy) and then waits as a pending `bids` change for a person; `true` lets the ladder send it itself (inside the `bids` mode and the plan's autopilot). Never a switch without the data either way."},"auto_cap_raise":{"type":"boolean","description":"AUTO3 (za-141, owner 2026-10-21: \"Auto ON by default\"): a converting campaign losing auctions on price gets its CPC cap raised by itself (+20%, once a week, at most twice the cap it started at, never while the month is projected at or over the spend ceiling, with its 30-day Undo) — the one exception to approve-first. `bids` set to `off` still wins; a plan without autopilot queues it for approval instead."},"auto_push_tests":{"type":"boolean","description":"za-110 (docs/1006 §69a, default on): the autopilot's push tests. A campaign on its own budget that loses at least 20% of its searches to budget (14 days, at least 30 clicks) gets a dated budget test: +25% for 14 days, judged on the end day (keep, revert or 7 more days). It follows the `budgets` mode: approve-first queues it for a person, `auto` starts it (unless \"hold until a sale\" or the ROAS target holds it), `off` writes nothing. A campaign is not tested again within 90 days of its last test."},"push_test_max_running":{"type":"integer","minimum":1,"maximum":10,"description":"Push tests waiting or running at once on the account (default 2)."},"push_test_confidence_pct":{"type":"integer","minimum":80,"maximum":99,"description":"PUSHTESTS (za-16, docs/1006 §82) — the confidence a budget test's result needs: a test is called worse only when its results per click moved with p below 1 - this/100. Recommended 90 (`push_test_confidence_recommended`)."},"push_test_confidence_recommended":{"type":"integer","minimum":80,"maximum":99,"description":"PUSHTESTS (za-16) — the Recommended `push_test_confidence_pct` (\"Reset to recommended\")."},"budget_raise_mode":{"$ref":"#/components/schemas/AdsBudgetRaiseMode"},"budget_raise_scope":{"type":"string","enum":["all","campaigns"],"description":"za-144: `all` — `budget_raise_mode` for every campaign; `campaigns` — only the campaigns in `budget_raise_campaigns`, each with its own mode (the rest are flagged)."},"budget_raise_campaigns":{"type":"object","description":"Google campaign id → its budget-raise mode (used when the scope is `campaigns`).","additionalProperties":{"$ref":"#/components/schemas/AdsBudgetRaiseMode"}},"budget_raise_built":{"type":"boolean","description":"za-111 (default on): a campaign Zinn® Ads built for this account (an applied, not undone, campaign create) is raised by itself while the autopilot is on; the account's own campaigns keep `budget_raise_mode`. An explicit per-campaign choice, `off`, the spend ceiling, good standing, the geo hold-out and the 7-day guard still win. Counted from the moment it was turned on — no older flag is raised by it."},"warm_start_until":{"type":["string","null"],"format":"date-time","description":"za-264: the end of a NEW Google connection's learning period (14 days from connect; `null` for an account connected before za-264, or one whose learning was ended). Until then an automatic bid, budget, pause or keyword change is proposed for a person instead of sent (a person's approval still sends it); a guarded automatic negative still applies by itself (owner rule); and no bid-strategy switch is proposed or sent by itself. End it early with `endAdsWarmStart`."},"hold_until_sale":{"type":"boolean","description":"\"Hold until a sale\" (default on): the autopilot never raises a budget by itself while the account had no conversion in the last 30 days; the raise waits for approval."},"roas_target_pct":{"type":["integer","null"],"description":"The 30-day return (conversion value per unit of spend, as a percentage: 400 = 4.0x) the autopilot needs before it raises a budget by itself; null = no target."},"markets":{"type":"array","description":"Where new campaigns may run; empty = no limit. Launch skips the rest.","items":{"$ref":"#/components/schemas/AdsBuildMarket"}},"competitor_automation":{"type":"boolean","description":"Competitor campaigns are launched only while this is on AND the plan includes competitor groups (Pro and above)."},"collision_mode":{"type":"string","enum":["approve","refuse"],"description":"za-70: what happens to a negative keyword or keyword the collision simulator says would block this account's own keywords or the searches that bring results. `approve` (default): never sent by itself — it waits for a person with the collisions shown (`AdsChange.summary.collision`). `refuse`: never sent, whoever asked (`error` `collides`). Every such change is replayed either way."},"auto_new_countries":{"type":"boolean","description":"AUTO1 (za-105): when a country brings enough conversions cheaply inside campaigns that are not its own, propose it a campaign of its own (excluded from its parents in the same change). Goes through the `campaigns` mode — approve-first by default."},"new_country_max_per_month":{"type":"integer","minimum":0,"maximum":10,"description":"At most this many new-country campaigns proposed (or made) per calendar month."},"new_country_budget_minor":{"type":["integer","null"],"format":"int64","description":"Starting daily budget in minor units of the account currency; null = five whole units, raised to the country's measured spend before the split."},"new_country_min_conversions":{"type":"integer","description":"The trigger — conversions the country brought in 30 days."},"new_country_min_clicks":{"type":"integer","description":"The trigger — clicks those conversions came from (30 days)."},"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"platform":{"$ref":"#/components/schemas/AdsPlatform"},"external_id":{"type":"string"},"login_external_id":{"type":"string","description":"The manager account it is reached through."},"label":{"type":"string"},"status":{"type":"string","enum":["active","paused","disconnected"]},"modes":{"$ref":"#/components/schemas/AdsModes"},"daily_ceiling_minor":{"type":["integer","null"],"format":"int64"},"monthly_ceiling_minor":{"type":["integer","null"],"format":"int64"},"ceiling_currency":{"type":"string"},"account_currency":{"type":"string","description":"The ad account's own ISO 4217 currency."},"datamanager_granted":{"type":"boolean","description":"DMAPI2: this connection's conversions can be uploaded through the Data Manager API — the Google sign-in its token came from granted the `auth/datamanager` scope, or (za-238) it is the platform's own Google account, whose uploads run on the platform credential rather than a sign-in. Always false for Microsoft, Meta and X connections."},"uploads_need_reconnect":{"type":"boolean","description":"DMAPI2: show \"reconnect to enable conversion uploads\" — a live Google connection whose grant lacks `auth/datamanager` while Connect asks for that scope. Signing in again and picking the same account replaces its token."},"meta_scopes":{"type":"array","items":{"type":"string","enum":["ads_management","business_management","pages_show_list","pages_read_engagement"]},"description":"METABUILD: the extended Meta permissions this connection's sign-in granted, each checked on its own (`ads_read` is always granted on a connection). Empty for every other network and for a Meta sign-in made before they were asked for."},"meta_needs_reconnect":{"type":"boolean","description":"METABUILD: show \"Reconnect Meta Ads\" — a live Meta connection lacking one of the extended permissions while Connect asks for them (`ZINN_ADS_META_EXTENDED_SCOPES`). Signing in again and picking the same account replaces its token and its permissions."},"vendor_grants":{"type":"object","additionalProperties":{"type":"boolean"},"description":"TTFULL: what this connection's grant may do, MEASURED from the network's own answers (never typed). TikTok keys: `writes` (campaign, ad group, ad and negative keyword changes), `audiences` (audience exclusions), `diagnosis` (TikTok's own ad group diagnosis). A key that is absent was never measured (the daily audit measures it); `false` means the network refused it for this grant. Empty for a network that does not measure its grant."},"grants_missing":{"type":"array","items":{"type":"string"},"description":"TTFULL: the `vendor_grants` keys the network refused for this grant. Non-empty: show \"Reconnect\" — signing in again and picking the same account replaces the token, and TikTok grants every permission the Zinn® Ads app now holds."},"linkedin_write":{"type":["object","null"],"description":"LIFULL: on a LinkedIn connection, whether its sign-in granted `rw_ads` (LinkedIn's own answer on the grant, never a typed flag), so an approved change can be sent; `null` on every other network. `needs_reconnect` true = a read-only grant: show the LinkedIn Reconnect prompt so approved changes can be sent. LinkedIn's Development Tier allows changes on a limited set of ad accounts; a change LinkedIn refuses there fails with `linkedinWriteNotAllowed` on the change itself.","required":["granted","needs_reconnect"],"properties":{"granted":{"type":"boolean"},"needs_reconnect":{"type":"boolean"}}},"needs_reconnect":{"type":"boolean","description":"ADSUI1 (za-243): the connection DROPPED — its latest finished read with its own token (the daily audit; for Meta the campaigns read) failed because the customer's credential was revoked or expired, or the token is gone or refused at refresh. Only a new sign-in fixes it: signing in again and picking the same account replaces its token (settings and history stay). Clears by itself on the next successful read."},"grant_ref":{"type":"string","description":"ADSUI1 (za-246): the sign-in (OAuth grant) this connection's token came from. Accounts picked from one sign-in share it, so the dashboard groups accounts by network, then by sign-in. Empty for the house connection."},"pending_changes":{"type":"integer"},"pinterest_write":{"type":["object","null"],"description":"PINFULL: on a Pinterest connection, whether its sign-in granted `ads:write` (read from Pinterest's own token answer, never typed) so approved changes can be sent, and whether the card offers \"Reconnect Pinterest Ads\" to add it. On Trial access Pinterest lets only the app creator's own account grant it. `null` for every other network.","required":["granted","needs_reconnect"],"properties":{"granted":{"type":"boolean"},"needs_reconnect":{"type":"boolean"}}},"created_at":{"type":"string","format":"date-time"},"disconnected_at":{"type":["string","null"],"format":"date-time"}}},"AdsAcquisitionQuality":{"type":"object","description":"Customer quality by advert on one connection (za-215, docs/1006 §45).","required":["as_of","basis","paid","bad","baseline_bp","rule","data","total","page"],"properties":{"as_of":{"type":"string","format":"date-time","nullable":true},"total":{"type":"integer","description":"Every term in the report, across all pages."},"page":{"$ref":"#/components/schemas/PageMeta"},"basis":{"type":"array","items":{"type":"string","enum":["refund","chargeback","early_cancel","support"]}},"paid":{"type":"integer","description":"Paid customers an advert term acquired."},"bad":{"type":"integer"},"baseline_bp":{"type":"integer","description":"The whole account's bad-customer rate, basis points."},"rule":{"type":"object","required":["min_bad","min_baseline_paid","rate_factor","early_cancel_days"],"properties":{"min_bad":{"type":"integer"},"min_baseline_paid":{"type":"integer"},"rate_factor":{"type":"string","description":"A decimal, e.g. 1.5."},"early_cancel_days":{"type":"integer"}}},"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsAcquisitionQualityRow"}}}},"AdsAcquisitionQualityRow":{"type":"object","required":["dimension","value","campaign_id","campaign","paid","bad","refunds","chargebacks","early_cancels","support","rate_bp","baseline_bp","verdict"],"properties":{"dimension":{"type":"string","enum":["keyword","ad_group","country"]},"value":{"type":"string","description":"The keyword text, ad group name or ISO country code."},"campaign_id":{"type":"string","description":"Blank for a country (it spans campaigns)."},"campaign":{"type":"string"},"paid":{"type":"integer"},"bad":{"type":"integer"},"refunds":{"type":"integer"},"chargebacks":{"type":"integer"},"early_cancels":{"type":"integer"},"support":{"type":"integer"},"rate_bp":{"type":"integer"},"baseline_bp":{"type":"integer","description":"The rest of the account, this term left out."},"verdict":{"type":"string","enum":["finding","owner_locked","held_sample","held_baseline","held_rate"]}}},"AdsAdActionRequest":{"type":"object","required":["action","level","resource"],"properties":{"action":{"type":"string","enum":["pause","unpause","delete"]},"level":{"type":"string","enum":["ad","ad_group","campaign"]},"resource":{"type":"string","maxLength":128,"description":"The Google Ads resource name from `listAdsAccountAds` (`customers/<id>/adGroupAds/ <group>~<ad>`, `.../adGroups/<id>`, `.../campaigns/<id>`) of THIS account."},"label":{"type":"string","maxLength":200,"description":"What the change line calls it."}}},"AdsAiMax":{"type":"object","description":"The AI Max for Search guard on one connection (za-204, docs/1006 §97).","required":["as_of","currency","skipped","expanded","keyword","verdict","basis","return_pct","campaigns","waste_terms","rules","own","recommended","bounds"],"properties":{"as_of":{"type":"string","format":"date-time","nullable":true},"currency":{"type":"string"},"skipped":{"type":"string","enum":["","notInGoodStanding","readRefused"]},"expanded":{"$ref":"#/components/schemas/AdsAiMaxFigures"},"keyword":{"$ref":"#/components/schemas/AdsAiMaxFigures"},"verdict":{"type":"string","enum":["none","learning","no_keyword_return","ok","below"]},"basis":{"type":"string","enum":["","value","conversions"]},"return_pct":{"type":"integer","nullable":true},"campaigns":{"type":"array","items":{"$ref":"#/components/schemas/AdsAiMaxCampaign"}},"waste_terms":{"type":"array","maxItems":500,"items":{"type":"object","required":["finding_id","term","campaign","match_source","clicks","cost_micros","status","blocked_by_collision"],"properties":{"finding_id":{"type":"string","format":"uuid"},"term":{"type":"string"},"campaign":{"type":"string"},"match_source":{"type":"string","enum":["AI_MAX_BROAD_MATCH","AI_MAX_KEYWORDLESS"]},"clicks":{"type":"integer"},"cost_micros":{"type":"integer"},"status":{"type":"string"},"blocked_by_collision":{"type":"boolean","description":"The collision replay refused it."}}}},"rules":{"$ref":"#/components/schemas/AdsAiMaxRules"},"own":{"type":"array","items":{"type":"string"},"description":"The rules the customer set (the rest are Recommended)."},"recommended":{"$ref":"#/components/schemas/AdsAiMaxRules"},"bounds":{"type":"object","additionalProperties":{"type":"object","required":["min","max"],"properties":{"min":{"type":"integer"},"max":{"type":"integer"}}}}}},"AdsAiMaxCampaign":{"type":"object","required":["campaign_id","campaign","expanded","keyword","verdict","basis","return_pct"],"properties":{"campaign_id":{"type":"string"},"campaign":{"type":"string"},"expanded":{"$ref":"#/components/schemas/AdsAiMaxFigures"},"keyword":{"$ref":"#/components/schemas/AdsAiMaxFigures"},"verdict":{"type":"string","enum":["none","learning","no_keyword_return","ok","below"]},"basis":{"type":"string","enum":["","value","conversions"]},"return_pct":{"type":"integer","nullable":true}}},"AdsAiMaxFigures":{"type":"object","required":["clicks","cost_micros","conversions_milli","value_micros","searches"],"properties":{"clicks":{"type":"integer"},"cost_micros":{"type":"integer","description":"Account currency, micros (Google's unit)."},"conversions_milli":{"type":"integer","description":"RECORDED conversions x 1000 (MSALLCONV-FU2): every conversion the network recorded, biddable goal or not."},"value_micros":{"type":"integer"},"searches":{"type":"integer","description":"Distinct searches."}}},"AdsAiMaxRules":{"type":"object","required":["guard","waste_min_clicks","waste_min_cost_minor","compare_min_clicks","min_return_pct"],"properties":{"guard":{"type":"boolean","description":"Judge expanded searches on these bars (off = the account's ordinary bars)."},"waste_min_clicks":{"type":"integer"},"waste_min_cost_minor":{"type":"integer","description":"Minor units of the account currency."},"compare_min_clicks":{"type":"integer"},"min_return_pct":{"type":"integer"}}},"AdsAllowedTerm":{"type":"object","description":"One competitor name allowed in ONE ad group's ad text (za-237, docs/1006 §53).","required":["id","ad_group_id","ad_group_name","term","added_by","added_at"],"properties":{"id":{"type":"string","format":"uuid"},"ad_group_id":{"type":"string","description":"The ad group's id at the network."},"ad_group_name":{"type":"string","description":"The group's name when it was allowed."},"term":{"type":"string","maxLength":60},"added_by":{"type":"string"},"added_at":{"type":["string","null"],"format":"date-time"}}},"AdsAllowedTermCreate":{"type":"object","required":["ad_group_id","term"],"properties":{"ad_group_id":{"type":"string","maxLength":200},"ad_group_name":{"type":"string","maxLength":255},"term":{"type":"string","maxLength":200}}},"AdsAllowedTermEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AdsAllowedTerm"}}},"AdsAllowedTermList":{"type":"object","required":["connection_id","data"],"properties":{"connection_id":{"type":"string","format":"uuid"},"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsAllowedTerm"}}}},"AdsAmazonAdGroup":{"type":"object","description":"One Amazon Ads ad group, its default bid and its keywords (AMZBIDS).","required":["id","name","state","default_bid_micros","keywords"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"state":{"type":"string"},"default_bid_micros":{"type":"integer","format":"int64"},"keywords":{"type":"array","items":{"$ref":"#/components/schemas/AdsAmazonKeyword"}}}},"AdsAmazonBidRequest":{"type":"object","additionalProperties":false,"required":["bid_micros"],"properties":{"bid_micros":{"type":"integer","format":"int64","minimum":1,"maximum":100000000000,"description":"The new bid in micros of the profile currency (1 unit = 1,000,000)."}}},"AdsAmazonCampaign":{"type":"object","description":"One Amazon Ads Sponsored Products campaign and its daily budget (AMZBIDS). Money is micros of the profile currency (§2.8).","required":["id","name","state","daily_budget_micros"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"state":{"type":"string","description":"Amazon's state (ENABLED, PAUSED)."},"daily_budget_micros":{"type":["integer","null"],"format":"int64"}}},"AdsAmazonKeyword":{"type":"object","description":"One Amazon Ads keyword and its bid (AMZBIDS); `bid_micros` null = the ad group's default bid.","required":["id","text","match_type","state","bid_micros"],"properties":{"id":{"type":"string"},"text":{"type":"string"},"match_type":{"type":"string"},"state":{"type":"string"},"bid_micros":{"type":["integer","null"],"format":"int64"}}},"AdsAnalyticsAnomaly":{"type":"object","required":["day","metric","direction","value","expected","change_pct","linked","linked_first_day","linked_last_day"],"properties":{"day":{"type":"string","format":"date"},"metric":{"type":"string","enum":["cost_micros","conversions_milli"]},"direction":{"type":"string","enum":["up","down"]},"value":{"type":"integer","format":"int64"},"expected":{"type":"integer","format":"int64","description":"The mean of the baseline days."},"change_pct":{"type":"integer"},"linked":{"$ref":"#/components/schemas/AdsAnalyticsMarkerCounts"},"linked_first_day":{"type":"string","format":"date"},"linked_last_day":{"type":"string","format":"date"}}},"AdsAnalyticsBreakdown":{"allOf":[{"$ref":"#/components/schemas/AdsAnalyticsFrame"},{"type":"object","required":["by","total","offset","limit","rows"],"properties":{"by":{"type":"string","enum":["network","connection","campaign","country","device","offering","client"]},"total":{"type":"integer"},"offset":{"type":"integer"},"limit":{"type":"integer"},"rows":{"type":"array","items":{"$ref":"#/components/schemas/AdsAnalyticsRow"}}}}]},"AdsAnalyticsFigures":{"type":"object","required":["cost_micros","value_micros","conversions_milli","clicks","impressions","roas_bp","cpa_micros","cpc_micros","ctr_bp","conv_rate_bp"],"properties":{"cost_micros":{"type":"integer","format":"int64"},"value_micros":{"type":"integer","format":"int64"},"conversions_milli":{"type":"integer","format":"int64","description":"RECORDED conversions x 1000 (MSALLCONV-FU2): every conversion the network recorded, biddable goal or not (Microsoft `AllConversions`, Google `metrics.all_conversions`; a day stored before that column read its biddable figure)."},"clicks":{"type":"integer","format":"int64"},"impressions":{"type":"integer","format":"int64"},"roas_bp":{"type":"integer","format":"int64","nullable":true},"cpa_micros":{"type":"integer","format":"int64","nullable":true},"cpc_micros":{"type":"integer","format":"int64","nullable":true},"ctr_bp":{"type":"integer","format":"int64","nullable":true},"conv_rate_bp":{"type":"integer","format":"int64","nullable":true}}},"AdsAnalyticsForecast":{"type":"object","required":["today","month_first_day","month_last_day","currency","fx","unconverted","accounts","spent_micros","forecast_micros","low_micros","high_micros","band_pct","rate_days","days_left","ceiling","state","days"],"properties":{"today":{"type":"string","format":"date"},"month_first_day":{"type":"string","format":"date"},"month_last_day":{"type":"string","format":"date"},"currency":{"type":"string"},"fx":{"type":"array","items":{"$ref":"#/components/schemas/AdsAnalyticsFx"}},"unconverted":{"type":"array","items":{"type":"string"}},"accounts":{"type":"integer"},"spent_micros":{"type":"integer","format":"int64"},"forecast_micros":{"type":"integer","format":"int64"},"low_micros":{"type":"integer","format":"int64"},"high_micros":{"type":"integer","format":"int64"},"band_pct":{"type":"integer"},"rate_days":{"type":"integer"},"days_left":{"type":"integer"},"ceiling":{"type":"object","required":["comparable","complete","micros","source","missing"],"properties":{"comparable":{"type":"boolean"},"complete":{"type":"boolean"},"micros":{"type":"integer","format":"int64","nullable":true},"source":{"type":"string","enum":["","accounts","cross","mixed"]},"missing":{"type":"integer"}}},"state":{"type":"string","enum":["no_spend","no_ceiling","at_ceiling","over","at_risk","under"]},"days":{"type":"array","items":{"$ref":"#/components/schemas/AdsAnalyticsForecastDay"}}}},"AdsAnalyticsForecastDay":{"type":"object","required":["day","actual","mid","low","high"],"properties":{"day":{"type":"string","format":"date"},"actual":{"type":"integer","format":"int64","nullable":true,"description":"Cumulative spend, before today."},"mid":{"type":"integer","format":"int64","nullable":true},"low":{"type":"integer","format":"int64","nullable":true},"high":{"type":"integer","format":"int64","nullable":true}}},"AdsAnalyticsFrame":{"type":"object","required":["first_day","last_day","range","compare","compare_first_day","compare_last_day","grain","currency","fx","unconverted","accounts"],"properties":{"first_day":{"type":"string","format":"date"},"last_day":{"type":"string","format":"date"},"range":{"type":"string"},"compare":{"type":"string","enum":["previous","year","none"]},"compare_first_day":{"type":"string","format":"date","nullable":true},"compare_last_day":{"type":"string","format":"date","nullable":true},"grain":{"type":"string","enum":["day","week","month"]},"currency":{"type":"string"},"fx":{"type":"array","items":{"$ref":"#/components/schemas/AdsAnalyticsFx"}},"unconverted":{"type":"array","items":{"type":"string"},"description":"Currencies left out of the blended figures for want of a stored rate; `???` stands for accounts whose currency is not known."},"accounts":{"type":"integer"},"unreported_networks":{"type":"array","items":{"type":"string"},"description":"za-283: networks in scope whose figures are NOT in this read because the network does not report the level it reads (a country board or filter reads country figures; X reports no country). Shown as a note, never as zero. Absent on a read cached before za-283's device car."}}},"AdsAnalyticsFunnel":{"allOf":[{"$ref":"#/components/schemas/AdsAnalyticsFrame"},{"type":"object","required":["attributable","not_split_by","steps","paid_value_micros","network_value_micros","truth"],"properties":{"attributable":{"type":"boolean","description":"`false` when a filter the customer's own outcomes cannot follow is set (they carry no campaign, country, device or product/site)."},"not_split_by":{"type":"array","items":{"type":"string","enum":["campaign","country","device","offering"]}},"steps":{"type":"array","items":{"$ref":"#/components/schemas/AdsAnalyticsFunnelStep"}},"paid_value_micros":{"type":"integer","format":"int64","nullable":true},"network_value_micros":{"type":"integer","format":"int64"},"truth":{"allOf":[{"$ref":"#/components/schemas/AdsAnalyticsTruth"}],"nullable":true}}}]},"AdsAnalyticsFunnelStep":{"type":"object","required":["step","count_milli","rate_bp"],"properties":{"step":{"type":"string","enum":["impressions","clicks","conversions","paid"]},"count_milli":{"type":"integer","format":"int64","nullable":true,"description":"Thousandths (a network may report part conversions). `null` on `paid` when the first-party side cannot be read for these filters or no account has a first-party source."},"rate_bp":{"type":"integer","format":"int64","nullable":true,"description":"This step over the step before it, in basis points. `null` on the first step, with nothing before, and on `paid` while an account with figures in the period has no first-party source."}}},"AdsAnalyticsFx":{"type":"object","required":["from","to","rate","as_of"],"properties":{"from":{"type":"string"},"to":{"type":"string"},"rate":{"type":"string","description":"Major-unit multiplier","decimal string.":null},"as_of":{"type":"string","description":"When the stored rate was fetched (ISO 8601)."}}},"AdsAnalyticsImpact":{"allOf":[{"$ref":"#/components/schemas/AdsAnalyticsFrame"},{"type":"object","required":["money_saved_micros","waste","fraud","refunds","recovered","changes","hours_saved","effect","before_after"],"properties":{"money_saved_micros":{"type":"integer","format":"int64","description":"Waste blocked plus fraud blocked plus refunds won (measured)."},"waste":{"type":"object","required":["count","cost_micros","clicks","items"],"properties":{"count":{"type":"integer"},"cost_micros":{"type":"integer","format":"int64"},"clicks":{"type":"integer","format":"int64"},"items":{"type":"array","items":{"type":"object","required":["id","kind","text","campaign","cost_micros","clicks","blocked_at","connection_id","change_id","can_undo"],"properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["waste_term","poor_keyword"]},"text":{"type":"string"},"campaign":{"type":"string"},"cost_micros":{"type":"integer","format":"int64"},"clicks":{"type":"integer"},"blocked_at":{"type":"string","format":"date-time","nullable":true},"connection_id":{"type":"string","format":"uuid"},"change_id":{"type":"string","format":"uuid","nullable":true},"can_undo":{"type":"boolean"}}}}}},"fraud":{"type":"object","required":["count","cost_micros","clicks","items"],"properties":{"count":{"type":"integer"},"cost_micros":{"type":"integer","format":"int64"},"clicks":{"type":"integer","format":"int64"},"items":{"type":"array","items":{"type":"object","required":["id","kind","label","clicks","cost_micros","blocked_at","connection_id","can_undo"],"properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string"},"label":{"type":"string"},"clicks":{"type":"integer"},"cost_micros":{"type":"integer","format":"int64"},"blocked_at":{"type":"string","format":"date-time","nullable":true},"connection_id":{"type":"string","format":"uuid"},"can_undo":{"type":"boolean"}}}}}},"refunds":{"type":"object","required":["count","credited_micros","items"],"properties":{"count":{"type":"integer"},"credited_micros":{"type":"integer","format":"int64"},"items":{"type":"array","items":{"type":"object","required":["id","month","credited_micros","connection_id"],"properties":{"id":{"type":"string","format":"uuid"},"month":{"type":"string","format":"date","nullable":true},"credited_micros":{"type":"integer","format":"int64"},"connection_id":{"type":"string","format":"uuid"}}}}}},"recovered":{"type":"object","required":["conversions","value_micros"],"properties":{"conversions":{"type":"integer"},"value_micros":{"type":"integer","format":"int64"}}},"changes":{"type":"object","required":["total","undoable","by_kind"],"properties":{"total":{"type":"integer"},"undoable":{"type":"integer"},"by_kind":{"type":"array","items":{"type":"object","required":["kind","count","undoable"],"properties":{"kind":{"type":"string"},"count":{"type":"integer"},"undoable":{"type":"integer"}}}}}},"hours_saved":{"type":"object","required":["minutes","modelled","minutes_per_change","default_minutes"],"properties":{"minutes":{"type":"integer"},"modelled":{"type":"boolean","description":"Always true - an estimate from the stated minutes per change","never a measurement.":null},"minutes_per_change":{"type":"object","additionalProperties":{"type":"integer"}},"default_minutes":{"type":"integer"}}},"effect":{"type":"object","required":["better","same","worse","no_data","conversions_gained_milli"],"properties":{"better":{"type":"integer"},"same":{"type":"integer"},"worse":{"type":"integer"},"no_data":{"type":"integer"},"conversions_gained_milli":{"type":"integer","format":"int64"}}},"before_after":{"type":"object","required":["started_on","before","after"],"properties":{"started_on":{"type":"string","format":"date","nullable":true},"before":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/AdsAnalyticsImpactPeriod"}]},"after":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/AdsAnalyticsImpactPeriod"}]}}}}}]},"AdsAnalyticsImpactPeriod":{"allOf":[{"$ref":"#/components/schemas/AdsAnalyticsFigures"},{"type":"object","required":["first_day","last_day"],"properties":{"first_day":{"type":"string","format":"date"},"last_day":{"type":"string","format":"date"}}}]},"AdsAnalyticsMarkerBucket":{"type":"object","required":["bucket","zinn","you","google","google_breaks","anomalies"],"properties":{"bucket":{"type":"string","format":"date"},"zinn":{"type":"integer"},"you":{"type":"integer"},"google":{"type":"integer"},"google_breaks":{"type":"integer"},"anomalies":{"type":"array","items":{"$ref":"#/components/schemas/AdsAnalyticsAnomaly"}}}},"AdsAnalyticsMarkerChange":{"type":"object","required":["id","connection_id","account","network","applied_at","action_class","summary","proposed_by","decided_by","who","status","can_undo","undo_until"],"properties":{"id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid"},"account":{"type":"string"},"network":{"type":"string"},"applied_at":{"type":"string","format":"date-time","nullable":true},"action_class":{"type":"string"},"summary":{"type":"object","additionalProperties":true},"proposed_by":{"type":"string"},"decided_by":{"type":"string"},"who":{"type":"string","enum":["zinn","you"]},"status":{"type":"string","enum":["applied","undone"]},"can_undo":{"type":"boolean"},"undo_until":{"type":"string","format":"date-time","nullable":true}}},"AdsAnalyticsMarkerCounts":{"type":"object","required":["zinn","you","google"],"properties":{"zinn":{"type":"integer","description":"Changes Zinn® Ads made (the audit, the autopilot, Simple mode, the assistant)."},"you":{"type":"integer","description":"Changes a person made in the dashboard or the customer's own API key made."},"google":{"type":"integer","description":"Changes Google made in the account by itself."}}},"AdsAnalyticsMarkerGoogleChange":{"type":"object","required":["id","connection_id","account","network","changed_at","actor","resource_type","operation","changed_fields","verdict","undoable","undo_requested"],"properties":{"id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid"},"account":{"type":"string"},"network":{"type":"string"},"changed_at":{"type":"string","format":"date-time"},"actor":{"type":"string","enum":["auto_apply","recommendation","google"]},"resource_type":{"type":"string"},"operation":{"type":"string"},"changed_fields":{"type":"array","items":{"type":"string"}},"verdict":{"type":"string","enum":["within_rules","risky","needs_approval","breaks_rule"]},"undoable":{"type":"boolean"},"undo_requested":{"type":"boolean"}}},"AdsAnalyticsMarkerItems":{"type":"object","required":["first_day","last_day","offset","limit","changes","google"],"properties":{"first_day":{"type":"string","format":"date"},"last_day":{"type":"string","format":"date"},"offset":{"type":"integer"},"limit":{"type":"integer"},"changes":{"type":"object","required":["count","rows"],"properties":{"count":{"type":"integer"},"rows":{"type":"array","items":{"$ref":"#/components/schemas/AdsAnalyticsMarkerChange"}}}},"google":{"type":"object","required":["count","rows"],"properties":{"count":{"type":"integer"},"rows":{"type":"array","items":{"$ref":"#/components/schemas/AdsAnalyticsMarkerGoogleChange"}}}}}},"AdsAnalyticsMarkers":{"type":"object","required":["first_day","last_day","grain","currency","unconverted","accounts","narrowed","link_days","buckets"],"properties":{"first_day":{"type":"string","format":"date"},"last_day":{"type":"string","format":"date"},"grain":{"type":"string","enum":["day","week","month"]},"currency":{"type":"string"},"unconverted":{"type":"array","items":{"type":"string"}},"accounts":{"type":"integer"},"narrowed":{"type":"boolean"},"link_days":{"type":"integer"},"buckets":{"type":"array","items":{"$ref":"#/components/schemas/AdsAnalyticsMarkerBucket"}}}},"AdsAnalyticsNarrative":{"type":"object","description":"za-285: the period narrative. `status` `empty` carries only `status` and `cached`. `text` is empty unless `status` is `written`. `facts` are the cited facts (figures as the strings shown).","required":["status","cached"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["empty","writing","written","withheld","refused","failed"]},"cached":{"type":"boolean"},"first_day":{"type":"string","format":"date"},"last_day":{"type":"string","format":"date"},"text":{"type":"string"},"locale":{"type":"string"},"cites":{"type":"array","items":{"type":"string"}},"facts":{"type":"array","items":{"$ref":"#/components/schemas/AdsNarrativeFact"}},"model":{"type":"string"},"funding":{"type":"string"},"failure":{"oneOf":[{"$ref":"#/components/schemas/VendorFailure"},{"type":"null"}]},"can_buy":{"type":"boolean"},"error_code":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}}},"AdsAnalyticsPoint":{"allOf":[{"$ref":"#/components/schemas/AdsAnalyticsFigures"},{"type":"object","required":["bucket"],"properties":{"bucket":{"type":"string","format":"date"}}}]},"AdsAnalyticsRow":{"allOf":[{"$ref":"#/components/schemas/AdsAnalyticsFigures"},{"type":"object","required":["key","label","previous","currencies","spark_cost_micros"],"properties":{"key":{"type":"string"},"label":{"type":"string"},"network":{"type":"string"},"connection_id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"campaign_id":{"type":"string"},"account":{"type":"string"},"country":{"type":"string"},"device":{"type":"string","enum":["mobile","desktop","tablet","tv","other"],"description":"za-282: the device of a `by=device` row."},"offering_id":{"type":"string","format":"uuid","nullable":true},"kind":{"type":"string"},"assigned":{"type":"boolean"},"own":{"type":"boolean","description":"za-287: a `by=client` row that is the agency's OWN accounts (not a client's)."},"previous":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/AdsAnalyticsFigures"}]},"currencies":{"type":"array","items":{"type":"string"}},"spark_cost_micros":{"type":"array","items":{"type":"integer","format":"int64"}}}}]},"AdsAnalyticsSeries":{"type":"object","required":["cost_micros","value_micros","conversions_milli","clicks","impressions"],"properties":{"buckets":{"type":"array","items":{"type":"string","format":"date"}},"cost_micros":{"type":"array","items":{"type":"integer","format":"int64"}},"value_micros":{"type":"array","items":{"type":"integer","format":"int64"}},"conversions_milli":{"type":"array","description":"RECORDED conversions x 1000 (MSALLCONV-FU2): every conversion the network recorded, biddable goal or not (Microsoft `AllConversions`, Google `metrics.all_conversions`; a day stored before that column read its biddable figure). One per bucket.","items":{"type":"integer","format":"int64"}},"clicks":{"type":"array","items":{"type":"integer","format":"int64"}},"impressions":{"type":"array","items":{"type":"integer","format":"int64"}}}},"AdsAnalyticsSummary":{"allOf":[{"$ref":"#/components/schemas/AdsAnalyticsFrame"},{"type":"object","required":["current","previous","sparklines","previous_sparklines","by_currency"],"properties":{"current":{"$ref":"#/components/schemas/AdsAnalyticsFigures"},"previous":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/AdsAnalyticsFigures"}]},"sparklines":{"$ref":"#/components/schemas/AdsAnalyticsSeries"},"previous_sparklines":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/AdsAnalyticsSeries"}]},"by_currency":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/AdsAnalyticsFigures"},{"type":"object","required":["currency"],"properties":{"currency":{"type":"string"}}}]}}}}]},"AdsAnalyticsTimeseries":{"allOf":[{"$ref":"#/components/schemas/AdsAnalyticsFrame"},{"type":"object","required":["points","previous","networks"],"properties":{"points":{"type":"array","items":{"$ref":"#/components/schemas/AdsAnalyticsPoint"}},"previous":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/AdsAnalyticsPoint"}},"networks":{"type":"array","items":{"type":"object","required":["network","cost_micros","value_micros"],"properties":{"network":{"type":"string"},"cost_micros":{"type":"array","items":{"type":"integer","format":"int64"}},"value_micros":{"type":"array","items":{"type":"integer","format":"int64"}}}}}}}]},"AdsAnalyticsTruth":{"type":"object","required":["tracked_accounts","untracked_accounts","untracked_active_accounts","network_conversions_milli","measured_conversions","measured_conversions_per_account","recorded_on_several_accounts","gap_bp","gap_verdict","gap_limit_bp","min_conversions","network_value_micros","measured_value_micros","by_kind","accounts","settling_from"],"properties":{"tracked_accounts":{"type":"integer"},"untracked_accounts":{"type":"integer","description":"Accounts that have never sent a first-party outcome; left out of the comparison (they have no truth","which is not zero).":null},"untracked_active_accounts":{"type":"integer","description":"Of those","the ones with figures in the period.":null},"network_conversions_milli":{"type":"integer","format":"int64","description":"BIDDABLE: the tracked accounts' conversions on the goals that count for bidding (every primary action). A sale on any other goal is still RECORDED by the network and is not in this figure; the dashboard labels it 'what the networks' bidding can see'."},"measured_conversions":{"type":"integer","format":"int64","description":"Outcomes the customer's own source recorded on the tracked accounts, of the kinds each account's tracking settings compare, each ONCE per organisation (the same order recorded on two ad accounts is one)."},"measured_conversions_per_account":{"type":"integer","format":"int64","description":"The per-account recorded counts summed: what the networks were each sent. `gap_bp` and `gap_verdict` compare THIS with the networks' summed claims."},"recorded_on_several_accounts":{"type":"integer","format":"int64","description":"How many more the per-account sum is than the once-per-organisation count."},"gap_bp":{"type":"integer","format":"int64","nullable":true},"gap_verdict":{"type":"string","enum":["none","too_few","matches","missed","overcounted"],"description":"The gap in words by the daily tracking-truth check's thresholds: `missed` = the networks counted fewer than happened, `overcounted` = more."},"gap_limit_bp":{"type":"integer","description":"The gap within which the counts match (the daily check's threshold)."},"min_conversions":{"type":"integer","description":"The fewest recorded conversions a gap is judged on."},"network_value_micros":{"type":"integer","format":"int64"},"measured_value_micros":{"type":"integer","format":"int64","description":"The recorded outcomes' value net of partial refunds, each outcome once per organisation; refunded-in-full outcomes add no value."},"by_kind":{"type":"array","items":{"type":"object","required":["kind","count"],"properties":{"kind":{"type":"string"},"count":{"type":"integer"}}}},"accounts":{"type":"array","items":{"$ref":"#/components/schemas/AdsAnalyticsTruthAccount"},"description":"The 20 accounts with the largest gap; `tracked_accounts` is the full count."},"settling_from":{"type":"string","format":"date","nullable":true,"description":"The first day still settling at the network (an upload lands hours later) when the period reaches it."}}},"AdsAnalyticsTruthAccount":{"type":"object","required":["connection_id","label","network","network_conversions_milli","measured_conversions","gap_bp","check"],"properties":{"connection_id":{"type":"string","format":"uuid"},"label":{"type":"string"},"network":{"type":"string"},"network_conversions_milli":{"type":"integer","format":"int64","description":"BIDDABLE: this account's conversions on the goals that count for bidding; a sale on any other goal is recorded by the network but not counted here."},"measured_conversions":{"type":"integer","format":"int64"},"gap_bp":{"type":"integer","format":"int64","nullable":true,"description":"(measured - network) / measured in basis points; negative = the network counts more than happened; `null` with nothing measured."},"check":{"allOf":[{"$ref":"#/components/schemas/AdsAnalyticsTruthCheck"}],"nullable":true}}},"AdsAnalyticsTruthCheck":{"type":"object","required":["status","gap_pct","window_start","window_end","real","credited","checked_at"],"properties":{"status":{"type":"string","description":"The latest daily tracking-truth verdict (za-115)."},"gap_pct":{"type":"integer","nullable":true},"window_start":{"type":"string","format":"date"},"window_end":{"type":"string","format":"date"},"real":{"type":"integer"},"credited":{"type":"integer","nullable":true},"checked_at":{"type":"string","format":"date-time"}}},"AdsAsk":{"type":"object","description":"One \"Ask your ads\" question and its checked answer (za-N7, docs/1006 §ASKADS).","required":["id","question","locale","days","connection_id","status","answer","cites","facts","fix","error","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"question":{"type":"string"},"locale":{"type":"string"},"days":{"type":"integer"},"connection_id":{"type":"string","format":"uuid","nullable":true},"status":{"type":"string","enum":["answered","facts_only","refused","failed"]},"answer":{"type":"string","description":"Empty unless `answered`. Fact ids appear in square brackets after the figures they back."},"cites":{"type":"array","items":{"type":"string"}},"facts":{"type":"array","items":{"$ref":"#/components/schemas/AdsAskFact"}},"fix":{"type":"object","nullable":true,"required":["fact_id","action","connection_id","change_id"],"properties":{"fact_id":{"type":"string"},"action":{"type":"string","enum":["pause_campaign","pause_keyword"]},"connection_id":{"type":"string","format":"uuid"},"change_id":{"type":"string","format":"uuid","nullable":true,"description":"Set once proposed."}}},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"can_buy":{"type":"boolean"},"reason":{"type":"string"},"failure":{"$ref":"#/components/schemas/VendorFailure"}}},"created_at":{"type":"string","format":"date-time"}}},"AdsAskFact":{"type":"object","description":"One cited fact. `kind`: `account`, `day`, `campaign`, `keyword`, `search_term`, `findings`, `pending`; `figures` are the strings shown (money with its currency code, truncated to the currency's minor unit).","required":["id","kind","connection_id","figures"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["account","day","campaign","keyword","search_term","findings","pending"]},"connection_id":{"type":"string","format":"uuid"},"figures":{"type":"object","additionalProperties":{"type":"string"}},"fix":{"type":"object","properties":{"action":{"type":"string","enum":["pause_campaign","pause_keyword"]}}}}},"AdsAudience":{"type":"object","description":"A customer's own Customer Match list (docs/1006 §72). Counts only, never an identifier.","required":["id","name","active","consent","members","blocked_by","last_status","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"active":{"type":"boolean","description":"False once emptied."},"consent":{"type":"object","properties":{"ad_user_data":{"type":"string","enum":["GRANTED","DENIED","UNSPECIFIED"]},"ad_personalization":{"type":"string","enum":["GRANTED","DENIED","UNSPECIFIED"]},"basis":{"type":"string"},"recorded_by":{"type":"string","description":"Who last recorded the consent, by name (else e-mail) — set ONLY when `recorded_by_kind` is `person` (a current member of this org); empty otherwise. Never a raw `user:<id>` (VERIFY-ADSACTOR)."},"recorded_by_kind":{"type":["string","null"],"enum":["person","support","agency","former_member","assistant","automatic","integration","other",null],"description":"Who recorded the consent, as a kind the screen translates — the same kinds as `AdsBudgetDecision.decided_by_kind` (`support` = our staff, including while impersonating). `null` when nobody has."},"recorded_at":{"type":["string","null"],"format":"date-time"},"terms_accepted_by":{"type":"string","description":"Who accepted the Customer Match terms — the same rule as `recorded_by`."},"terms_accepted_by_kind":{"type":["string","null"],"enum":["person","support","agency","former_member","assistant","automatic","integration","other",null],"description":"Who accepted the terms, as a kind (as `recorded_by_kind`); `null` when nobody has."},"terms_accepted_at":{"type":["string","null"],"format":"date-time"}}},"members":{"type":"object","properties":{"wanted":{"type":"integer"},"at_network":{"type":"integer"},"to_add":{"type":"integer"},"to_remove":{"type":"integer"}}},"blocked_by":{"type":["string","null"],"enum":["notGoogle","noConsent","noSourceConsent","noTerms","noDataManager","paused","disconnected","killed","notInGoodStanding","needsReconnect","deferred",null],"description":"Why nothing is sent now. `noSourceConsent` (za-95) = the list is filled from a CRM source whose Customer Match consents (BOTH ad_user_data and ad_personalization) are not attested; the remedy is to attest both for that source on the list. A list that may not add people (`noConsent` / `noSourceConsent`) still has its removals sent: withdrawing consent or unlinking the CRM takes everyone off at the network."},"last_status":{"type":"string","enum":["never","synced","processing","refused","failed"]},"last_reason":{"type":"string"},"last_run_at":{"type":["string","null"],"format":"date-time"},"last_ok_at":{"type":["string","null"],"format":"date-time"},"added_last":{"type":"integer"},"removed_last":{"type":"integer"},"at_network_list":{"type":"boolean"},"crm_feed":{"oneOf":[{"$ref":"#/components/schemas/AdsAudienceCrmFeed"},{"type":"null"}],"description":"za-95 — the CRM source filling this list automatically (null = an uploaded list)."},"created_at":{"type":"string","format":"date-time"}}},"AdsAudienceCrmFeed":{"type":"object","description":"za-95 (docs/1006 §72a): a Customer Match list filled from one of the customer's own CRM sources. People whose lead or deal is at one of `stages` join; a person who leaves those stages, or whose CRM consent field reads a refusal, is removed. The Customer Match attestation is this source's OWN (both consents, who and when) — never the CRM source's ad-measurement `consent_attested`. Until both are attested the CRM is not read for the list. Counts only, never a person.","required":["source_id","stages","attest_ad_user_data","attest_ad_personalization","attested","attested_by","attested_at","last_fed_at","leads_read","joined","left","not_consented"],"properties":{"source_id":{"type":"string","format":"uuid"},"stages":{"type":"array","items":{"type":"string"}},"attest_ad_user_data":{"type":"boolean"},"attest_ad_personalization":{"type":"boolean"},"attested":{"type":"boolean","description":"Both attested","with who and when.":null},"attested_by":{"type":"string"},"attested_at":{"type":["string","null"],"format":"date-time"},"last_fed_at":{"type":["string","null"],"format":"date-time"},"leads_read":{"type":"integer"},"joined":{"type":"integer"},"left":{"type":"integer"},"not_consented":{"type":"integer","description":"Leads at a feed stage whose CRM consent field refused."}}},"AdsAudienceCrmFeedPut":{"type":"object","required":["source_id","stages","attest_ad_user_data","attest_ad_personalization"],"properties":{"source_id":{"type":"string","format":"uuid","description":"A lead or deal source on this ad account (not a calls source)."},"stages":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","maxLength":128}},"attest_ad_user_data":{"type":"boolean","description":"The customer attests every person in these stages consented to their data being sent to Google for advertising."},"attest_ad_personalization":{"type":"boolean","description":"The customer attests every person in these stages consented to personalised advertising."}}},"AdsAuditRun":{"type":"object","description":"One audit of one ad account (za-39: the platform-neutral audit for Microsoft Advertising; the Google audit for Google). Counts only, never vendor text.","required":["id","started_at","finished_at","ok","summary"],"properties":{"id":{"type":"string","format":"uuid"},"started_at":{"type":"string","format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"},"ok":{"type":"boolean"},"summary":{"type":"object","additionalProperties":true,"properties":{"changes":{"type":"integer"},"proposed":{"type":"integer"},"applied":{"type":"integer"},"refused":{"type":"integer"},"skipped_recent":{"type":"integer"},"failed":{"type":"integer"},"found":{"type":"object","additionalProperties":{"type":"integer"}},"read":{"type":"object","additionalProperties":{"type":"integer"}},"failure":{"$ref":"#/components/schemas/VendorFailure"},"skipped_learning":{"type":"integer","description":"Proposals a learning rule held (nothing sent or queued)."},"learning_held":{"type":"object","description":"za-326: the proposals a learning rule held, per rule code — `bid_strategy` (our 14-day freeze after a bid-strategy switch), `meta_learning_phase` (Meta reports the ad set as learning), `tiktok_learning_phase` (TikTok's first 7 days / 25 results). Each network's rule comes from the network registry; a Google negative or exclusion is never held (Google: targeting changes never trigger Learning). Absent when none.","additionalProperties":{"type":"integer"}},"sanity_unchecked":{"type":"string","enum":["x_no_targeting_read","no_keyword_read","held_trackingUnreadable","held_trackingUnreliable","held","names_unread"],"description":"ZA323-r2: the keyword sweep and the shield check (za-323) did not run on this network because it reports no keyword-targeting rows or search terms (`x_no_targeting_read` on X). ZA323-FU: `held_<reason>` (`held` for another reason) when the za-116 tracking hold stopped the whole audit; never on Meta or LinkedIn, which have no keywords. ZA323-GAPS: `names_unread` when the sweep ran only PARTLY — the account's rival names could not be read, so at least one one-word or rival keyword was not judged (fragments still were). Absent where they ran in full. Every keyword WRITE is still judged by the gate."},"waste":{"type":"object","description":"za-331: the waste check on this network — every search judged by the za-325 judge (`guards.classify` with the OFFERFIT verdict and the account's maturity), the same one the Google audit uses; a search sharing a word with a converting search is no longer exempt. Zero counts are omitted. `unavailable` (with `unavailable_source`) means the network reports no search terms at all (`noSearchTermReport`: Pinterest, X, ChatGPT Ads, LinkedIn, Meta) — \"could not see\", never a 0 — and then `read.search_terms` is absent. `basis: keyword` with `keywords` means keyword-level figures (Pinterest's KEYWORD targeting breakdown, the only network whose rows are keywords) were judged instead, never called search terms; on the others `basis` stays `search_term` and `keywords` is absent. `pending`: the network builds the report asynchronously (Amazon) and the next audit reads it (`read.search_terms` is absent meanwhile). `read_only`: waste found on a network Zinn® Ads does not change yet, so nothing was sent. `offer`: `checked`, `skipped` (not in good standing: nothing spent, data-proven waste only) or `blind`.","required":["network"],"properties":{"network":{"type":"string"},"terms":{"type":"integer"},"judged":{"type":"integer"},"off":{"type":"integer"},"learning":{"type":"integer"},"proposed":{"type":"integer"},"person":{"type":"integer"},"read_only":{"type":"integer"},"clicks_needed":{"type":"integer"},"offer":{"type":"string","enum":["checked","skipped","blind"]},"pending":{"type":"boolean"},"unavailable":{"type":"string"},"unavailable_source":{"type":"string"},"basis":{"type":"string","enum":["search_term","keyword"]},"keywords":{"type":"integer"}}},"search_term_report":{"type":"object","additionalProperties":true,"description":"za-331: Amazon's search-term report handle while Amazon builds it; the next audit polls that same report (never a second request)."},"placements":{"type":"object","description":"za-331: the placement review on a network that serves ads on placements outside its own surface — the LinkedIn Audience Network per campaign, X Audience Platform per line item, every Meta placement per ad set. A placement that spent, recorded no conversion and has had the clicks or the spend the account's maturity says should have bought one is a finding; below that it is `learning`; one whose conversions the network could not report is `unread`, never judged. Judged per (campaign, placement), summed across the campaign's groups; a group's only spending placement is left to the audience rule. ⛔ Nothing is sent: every finding is a person's call in the network's own screen. `status`: `checked`; `unavailable` with `reason` (`notRead`: no reader for this network yet; `noConversionTag` (X) / `noConversionTracking` (Meta): the network counts no conversion, so no placement can be judged) — \"could not see\", never a 0; `guard`: the placement guard reviews them (`reason: placement_guard`, Microsoft); `error`: the read was refused, the rest of the audit stands. Absent on a network with no placements. Zero counts are omitted.","required":["network","status","proposed"],"properties":{"network":{"type":"string"},"status":{"type":"string","enum":["checked","unavailable","guard","error"]},"reason":{"type":"string"},"source":{"type":"string"},"groups":{"type":"integer"},"placements":{"type":"integer"},"judged":{"type":"integer"},"proposed":{"type":"integer"},"learning":{"type":"integer"},"clicks_needed":{"type":"integer"},"unread":{"type":"integer"},"waste_micros":{"type":"integer","format":"int64"},"currency":{"type":"string"},"findings":{"type":"array","items":{"type":"object","description":"One wasted placement of one campaign, summed across its groups (a placement that converts in any group of the campaign is never a finding). `groups` are the groups it can be turned off in (`group` their names, joined).","required":["placement","label","campaign_id","group_id","group","groups","cost_micros","clicks"],"properties":{"placement":{"type":"string","description":"Stable code: `linkedin_audience_network`, `x_audience_platform`, or Meta's `<publisher_platform>:<platform_position>`."},"label":{"type":"string","description":"The network's own name for the placement (never translated)."},"group_id":{"type":"string"},"group":{"type":"string"},"groups":{"type":"array","items":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}}},"campaign_id":{"type":"string"},"cost_micros":{"type":"integer","format":"int64"},"clicks":{"type":"integer"},"impressions":{"type":"integer"}}}}}}}}}},"AdsAutopilot":{"type":"object","description":"za-14 — what the autopilot does on one connected ad account.","required":["connection_id","platform","steps","last_run","own_values","account_hold"],"properties":{"connection_id":{"type":"string","format":"uuid"},"platform":{"type":"string","example":"google"},"own_values":{"type":"object","description":"WASTEFIX r3 (za-79) — \"Automatic actions, your values\": each threshold the waste autopilot decides by, the customer's value beside the recommended one (the screen's \"Recommended\" label and \"Reset to recommended\"). Set through `updateAdsConnection` (`waste_threshold_minor`, `cluster_min_terms`, `modes.negatives`).","required":["currency","waste_threshold_minor","waste_threshold_recommended_minor","cluster_min_terms","cluster_min_terms_recommended","negatives_auto_block","negatives_auto_block_recommended"],"properties":{"currency":{"type":"string","description":"The account currency (ISO 4217); empty before the first sync."},"waste_threshold_minor":{"type":["integer","null"],"format":"int64","description":"The customer's own value; null = following the recommended one."},"waste_threshold_recommended_minor":{"type":["integer","null"],"format":"int64","description":"What one conversion costs on this account (minor units); null while no spend is on record."},"cluster_min_terms":{"type":["integer","null"],"description":"The customer's own value; null = following the recommended one."},"cluster_min_terms_recommended":{"type":"integer"},"negatives_auto_block":{"type":"boolean","description":"True when the negatives mode is `auto` (clear waste is blocked with no person; Undo for 30 days)."},"negatives_auto_block_recommended":{"type":"boolean"}}},"steps":{"type":"array","items":{"type":"object","required":["step","ledger","classes","mode","does"],"properties":{"step":{"type":"string","enum":["negatives","pauses","keywords","budgets","bids","assets","compare_page","goals","reach","country_campaigns"],"description":"za-72 `compare_page`: a competitor ad moved onto the customer's own comparison page for its rival, under the `ads` mode."},"ledger":{"type":"string","description":"The Zinn® Ads feature id that brought the step to customers."},"classes":{"type":"array","items":{"type":"string"},"description":"The action classes (modes) that govern its writes."},"mode":{"type":"string","enum":["auto","approve","off"],"description":"The account's mode for the step. za-78 `goals` is approve-first always: `auto` on its `conversions` class still queues each change, so it reads `approve`."},"does":{"type":"string","description":"What the step does","in one line (English; the dashboard shows its own translated copy).":null}}}},"last_run":{"type":"object","nullable":true,"required":["id","finished_at","ok","negatives_added","keywords_paused","keywords_added","changes_proposed"],"properties":{"id":{"type":"string","format":"uuid"},"finished_at":{"type":"string","format":"date-time","nullable":true},"ok":{"type":"boolean"},"negatives_added":{"type":"integer","minimum":0},"keywords_paused":{"type":"integer","minimum":0},"keywords_added":{"type":"integer","minimum":0},"changes_proposed":{"type":"integer","minimum":0,"description":"Changes kept for a person to approve (approve-first)."},"assets_unlinked":{"type":"integer","minimum":0,"description":"za-77: disapproved assets unlinked from their campaigns on this account (each undoable from the change list; the asset itself is kept)."},"keywords_collided":{"type":"integer","minimum":0,"description":"za-81: search terms the collision check kept from becoming keywords (each would take searches from another ad group of this account)."},"keywords_held":{"type":"integer","minimum":0,"description":"za-81: new keywords not added because Google holds the whole account (za-80); retried once the hold lifts."},"goals_queued":{"type":"integer","minimum":0,"description":"za-78: conversion-goal changes (a recording sale or lead made primary, a page view or download made secondary) waiting for the customer's approval."},"goals_held":{"type":"integer","minimum":0,"description":"za-78: conversion-goal changes not proposed because Google holds the whole account (za-80); retried once the hold lifts."},"goals_refused":{"type":"integer","minimum":0,"description":"za-78: conversion-goal changes refused at the gate (`goalStarves`: no recording primary goal would be left; `goalUnreadable`: the account's conversion actions could not be read to check, proposed again by the next audit; or the account is not in good standing)."}}},"account_hold":{"type":["object","null"],"description":"za-80 (docs/1006 §53): whether Google has paused the whole account (advertiser verification, suspension, billing), read every hour. While `held`, no automatic change judged on traffic is sent or queued; the hour it lifts the autopilot resumes and every running push test's end date moves on by the days it was paused (`tests_extended`). Null before the account was first checked. Read from rows only.","required":["held","reason","since","lifted_at","last_checked","tests_extended"],"properties":{"held":{"type":"boolean"},"reason":{"type":"string","description":"Google's signal, in English (e.g. `customer.status SUSPENDED`); empty when never held."},"since":{"type":"string","format":"date-time","nullable":true,"description":"When serving stopped (the current or the last hold)."},"lifted_at":{"type":"string","format":"date-time","nullable":true,"description":"When the last hold lifted; null while held or never held."},"last_checked":{"type":"string","format":"date-time","nullable":true},"tests_extended":{"type":"array","items":{"type":"string"},"description":"The push tests whose end date the last lift moved on."}}}}},"AdsAutopilotDecisions":{"type":"object","description":"The organisation's autopilot decisions (za-166, docs/1006 §77).","required":["pinned_campaigns","held_campaigns","protected_keywords","held_back","held_back_total"],"properties":{"pinned_campaigns":{"type":"array","items":{"type":"string"}},"held_campaigns":{"type":"array","items":{"type":"string"}},"protected_keywords":{"type":"array","items":{"type":"string"}},"held_back":{"type":"array","description":"The latest automatic changes these decisions held back, newest first (at most 50 shown).","items":{"type":"object","properties":{"code":{"type":"string","enum":["decisionHeld","decisionPinned","decisionProtected"]},"campaign_id":{"type":"string"},"keyword":{"type":"string"},"action_class":{"type":"string"},"connection_id":{"type":"string","format":"uuid"},"path":{"type":"string"},"at":{"type":"string","format":"date-time"}}}},"held_back_total":{"type":"integer","format":"int64"},"updated_by":{"type":"string"},"updated_at":{"type":["string","null"],"format":"date-time"}}},"AdsBidLadderRow":{"type":"object","description":"One campaign on the bid-strategy ladder (za-183, docs/1006 §39).","required":["campaign_id","campaign","platform","channel","step","next_step","verdict","need","have","need_7d","have_7d","window_days","vendor_min","source","verified","conversions","cost_micros","cpa_micros","roas","currency","frozen_until","switched_at","switched_from","switched_to","pending_change","dismissed","review"],"properties":{"campaign_id":{"type":"string"},"campaign":{"type":"string"},"platform":{"type":"string","enum":["google","microsoft"]},"channel":{"type":"string","description":"The network's campaign type (SEARCH, SHOPPING, DISPLAY, VIDEO, MULTI_CHANNEL, DEMAND_GEN, PERFORMANCE_MAX, …)."},"step":{"type":"string","enum":["clicks","conversions","target_cpa","target_roas","impression_share",""],"description":"`impression_share` (Target Impression Share) is kept unless the campaign's objective asks for a share (za-184)."},"next_step":{"type":"string","enum":["clicks","conversions","target_cpa","target_roas","impression_share",""]},"verdict":{"type":"string","enum":["up","down","not_yet","top","learning","kept"]},"need":{"type":"integer","description":"Conversions the next step needs in window_days (vendor minimum x 1.5","or our own figure).":null},"have":{"type":"number"},"need_7d":{"type":"integer","description":"Demand Gen: conversions also needed in the last 7 days (0: none)."},"have_7d":{"type":"number"},"window_days":{"type":"integer"},"vendor_min":{"type":["integer","null"],"description":"The network's published minimum; null when it publishes none (the figure is ours)."},"focus":{"type":"boolean","description":"za-258: the campaign bids for clicks while the account tracks conversions — its enabled primary conversion actions recorded at least `focus_floor` conversions in the last 30 days (ADSFOCUS-GUARD: the customer's own floor, else 15) — so it moves to Maximise conversions with no target whatever its own count, and is not stepped back to clicks for lacking one."},"focus_short":{"type":"boolean","description":"ADSFOCUS-GUARD: the account recorded conversions, but fewer than `focus_floor`: the campaign stays on Maximise clicks (`account_conversions` of `focus_floor`)."},"account_conversions":{"type":["number","null"],"description":"The account's 30-day conversions from enabled primary actions, when read for the focus (null: not read)."},"focus_floor":{"type":"integer","description":"The floor the focus was judged against (0: not judged)."},"serve_revert":{"type":["object","null"],"description":"ADSFOCUS-GUARD: the serving watch's verdict on the last switch — impressions fell more than half for 6 consecutive hours against the same hours before the switch, with under 60% of the day's budget spent. `outcome` `applied` = the old bidding was put back at once (our own switch); `queued` = putting it back waits for a person (a switch recorded before the guard, or a customer whose bids are approve-first); `refused:…` / `nothing_to_put_back` = told, not changed.","required":["at","outcome","drop_pct","now_per_hour","normal_per_hour","hours","spent_pct","change_id"],"properties":{"at":{"type":"string","format":"date-time"},"outcome":{"type":"string"},"drop_pct":{"type":"integer"},"now_per_hour":{"type":"number"},"normal_per_hour":{"type":"number"},"hours":{"type":"integer"},"spent_pct":{"type":"integer"},"change_id":{"type":["string","null"]}}},"no_switch_until":{"type":["string","null"],"format":"date-time","description":"ADSFOCUS-GUARD: after the serving watch put a switch back, the ladder does not switch this campaign again before this time (14 days)."},"source":{"type":"string","description":"The vendor page the figure was read from."},"verified":{"type":"string","description":"The day the figure was read at the vendor."},"conversions":{"type":"number"},"cost_micros":{"type":"integer"},"cpa_micros":{"type":"integer"},"roas":{"type":"number"},"currency":{"type":"string"},"frozen_until":{"type":["string","null"],"format":"date-time"},"switched_at":{"type":["string","null"],"format":"date-time"},"switched_from":{"type":["string","null"]},"switched_to":{"type":["string","null"]},"pending_change":{"type":["string","null"],"description":"The approved change carrying a switch the customer clicked."},"sufficiency":{"type":"boolean","description":"LADDERFIX: on a conversion strategy with fewer of its own primary conversions (30 days) than the gate needs — `need`/`have`; proposed back to Maximise clicks with `gate_cap_micros` (approve-first)."},"sufficiency_short":{"type":"boolean","description":"LADDERFIX: ready by the ladder's rule but under the gate — it stays where it is (`have` of `need`)."},"approve_first":{"type":"boolean","description":"LADDERFIX: this proposal is never sent without a person's approval."},"gate_cap_micros":{"type":"integer","description":"LADDERFIX: the max CPC limit the step back to Maximise clicks sets (0: no clicks to measure)."},"valued_conversions":{"type":"number","description":"LADDERFIX: the 30-day primary conversions that carried a value."},"proposed_change":{"type":["string","null"],"description":"LADDERFIX: the pending change the ladder kept for approval."},"warm_start_until":{"type":["string","null"],"description":"za-264: no bid strategy change before this (an imported account's warm start)."},"health_short":{"type":"boolean","description":"za-329: ready to step up, but held until the conversion-health checks pass (`health`)."},"health":{"type":"array","items":{"$ref":"#/components/schemas/AdsSmartBidHealthItem"},"description":"za-329: the checks holding the step up (empty when none)."},"dismissed":{"type":"boolean"},"review":{"type":["object","null"],"description":"The measured result 14 days after a switch, per day against the 30 days before.","required":["outcome","days","conversions_per_day_before","conversions_per_day_after","cpa_micros_before","cpa_micros_after"],"properties":{"outcome":{"type":"string","enum":["better","same","worse"]},"days":{"type":"integer"},"conversions_per_day_before":{"type":"number"},"conversions_per_day_after":{"type":"number"},"cpa_micros_before":{"type":"integer"},"cpa_micros_after":{"type":"integer"}}}}},"AdsBrandBidder":{"type":"object","required":["id","key","source","share_bp","top_share_bp","first_seen_at","last_seen_at","new","mailed"],"properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string","description":"The competitor's domain (from Auction Insights), or `unnamed`."},"source":{"type":"string","enum":["auctionInsights","brandPosition"]},"share_bp":{"type":"integer","description":"Their impression share (Auction Insights) or our share lost to ad rank — basis points."},"top_share_bp":{"type":"integer","description":"Our absolute-top share on the brand keywords — basis points."},"first_seen_at":{"type":"string","format":"date-time"},"last_seen_at":{"type":"string","format":"date-time"},"new":{"type":"boolean","description":"Not yet marked seen on the dashboard."},"mailed":{"type":"boolean","description":"Already said in the daily e-mail (never said twice)."}}},"AdsBrandWatch":{"type":"object","description":"za-N9 (docs/1006 §80) — a connection's competitor watch: its settings, and the competitors seen bidding on its brand terms.","required":["settings","bidders","new"],"properties":{"settings":{"$ref":"#/components/schemas/AdsBrandWatchSettings"},"bidders":{"type":"array","items":{"$ref":"#/components/schemas/AdsBrandBidder"}},"new":{"type":"integer","minimum":0,"description":"Alerts not yet marked seen."}}},"AdsBrandWatchSettings":{"type":"object","required":["enabled","min_share_pct","top_floor_pct","rank_lost_pct","min_impressions","terms","recommended","bounds","last_check"],"properties":{"enabled":{"type":"boolean"},"min_share_pct":{"type":"integer","description":"Auction Insights — another domain's impression share on the brand keywords that counts as bidding, in percent."},"top_floor_pct":{"type":"integer","description":"Our absolute-top share on the brand keywords below this (with rank loss) means someone is placed above us."},"rank_lost_pct":{"type":"integer","description":"Share of brand impressions lost to ad rank that, with the floor, counts as an unnamed bidder."},"min_impressions":{"type":"integer","description":"Brand-keyword impressions in the window below which nothing is judged."},"terms":{"type":"array","items":{"type":"string"},"description":"Extra brand terms the customer added (the build plan's brand is always watched)."},"recommended":{"type":"object","description":"The Recommended value of each threshold (\"Reset to recommended\").","additionalProperties":{"type":"integer"}},"bounds":{"type":"object","additionalProperties":{"type":"object","required":["min","max"],"properties":{"min":{"type":"integer"},"max":{"type":"integer"}}}},"last_check":{"type":"object","description":"The last daily check — `at`, `source` (`auctionInsights` | `brandPosition`), `auction_insights` (`available` | `denied`: Google keeps it off the API for most accounts), `window_days`, `brand_terms`, `brand_keywords`, `impressions`, `top_share_bp`, `rank_lost_bp`; or `skipped` (e.g. `notInGoodStanding`). Empty before the first check.","additionalProperties":true}}},"AdsBrief":{"type":"object","required":["org_id","brief","test_share_recommended","test_share_min","test_share_max","keep_days","measured_at","blocked","split","moves","last_apply","can_undo_brief","versions"],"properties":{"org_id":{"type":"string","format":"uuid"},"brief":{"type":["object","null"],"required":["objective","target","test_share_pct","budget_minor","currency","mode"],"properties":{"objective":{"type":"string","enum":["leads","revenue"]},"target":{"type":["integer","null"]},"test_share_pct":{"type":"integer"},"budget_minor":{"type":["integer","null"],"description":"Integer minor units (§2.8)."},"currency":{"type":"string"},"mode":{"type":"string","enum":["suggest","auto"]}}},"test_share_recommended":{"type":"integer"},"test_share_min":{"type":"integer"},"test_share_max":{"type":"integer"},"keep_days":{"type":"integer"},"measured_at":{"type":["string","null"],"format":"date-time"},"blocked":{"type":"string","enum":["","noReturnYet"]},"split":{"type":"array","items":{"type":"object","required":["connection_id","platform","label","current_minor","proposed_minor","why","cost_minor","conversions_milli","value_minor"],"properties":{"connection_id":{"type":"string","format":"uuid"},"platform":{"type":"string"},"label":{"type":"string"},"current_minor":{"type":["integer","null"]},"proposed_minor":{"type":["integer","null"]},"why":{"$ref":"#/components/schemas/AdsBriefWhy"},"cost_minor":{"type":"integer"},"conversions_milli":{"type":"integer"},"value_minor":{"type":"integer"}}}},"moves":{"type":"array","items":{"$ref":"#/components/schemas/AdsCrossBudgetMove"}},"last_apply":{"type":["object","null"],"required":["at","by","moves","undone_at","can_undo"],"properties":{"at":{"type":["string","null"]},"by":{"type":["string","null"]},"moves":{"type":"array","items":{"$ref":"#/components/schemas/AdsCrossBudgetMove"}},"undone_at":{"type":["string","null"]},"can_undo":{"type":"boolean"}}},"can_undo_brief":{"type":"boolean"},"versions":{"type":"array","items":{"type":"object","required":["id","at","by","brief","undone_at"],"properties":{"id":{"type":"string","format":"uuid"},"at":{"type":"string","format":"date-time"},"by":{"type":"string"},"brief":{"type":"object","additionalProperties":true},"undone_at":{"type":["string","null"],"format":"date-time"}}}}}},"AdsBriefNetwork":{"type":"object","required":["network","label","state","connections"],"properties":{"network":{"type":"string"},"label":{"type":"string"},"state":{"type":"string","enum":["ready","connect","coming_soon"]},"connections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"currency":{"type":"string"}}}}}},"AdsBriefPlan":{"type":"object","required":["id","network","connection_id","share_pct","status","preview","change_ids"],"properties":{"id":{"type":"string","format":"uuid"},"network":{"type":"string","enum":["google","microsoft","x"]},"connection_id":{"type":"string","format":"uuid"},"share_pct":{"type":"integer"},"status":{"type":"string","enum":["preview","queued","empty","paused"],"description":"`paused`: was queued; Unlaunch paused or cancelled everything it launched (za-317)."},"preview":{"type":"object","description":"`campaigns` (name, countries, language, daily_budget_micros, keywords, keyword_count, ad_groups, and `headlines`/`descriptions` or, on X, `tweets`), `daily_budget_micros`, `campaign_count`, `requests`, and `skipped` (ADBRAND: each campaign the plan cannot launch: `name`, `skipped` = noBudget | adIncomplete | adBelowGood, `guards` [{code, part}] and `reasons` [{code, have, want}], so an empty plan says why).","additionalProperties":true},"change_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"launched_at":{"type":"string","format":"date-time","nullable":true}}},"AdsBriefUnlaunch":{"type":"object","description":"za-317: a brief's Unlaunch. `status` is empty (launched, or never launched), `pausing` (pauses wait for approval, or a launch change is still being applied) or `done` (everything the brief launched is paused or gone: the offering's ceiling and currency are free). Nothing is ever deleted; the brief, its plans and every change are kept.","required":["status","items","requested_at","unlaunched_at"],"properties":{"status":{"type":"string","enum":["","pausing","done"]},"requested_at":{"type":"string","format":"date-time","nullable":true},"unlaunched_at":{"type":"string","format":"date-time","nullable":true},"items":{"type":"array","description":"One entry per launched change and per campaign it created.","items":{"type":"object","required":["change_id","network","campaign","state"],"properties":{"change_id":{"type":"string","format":"uuid"},"network":{"type":"string"},"campaign":{"type":"string","description":"The network's campaign id, or empty."},"pause_change_id":{"type":"string","description":"The approve-first pause change","or empty.":null},"state":{"type":"string","description":"Done states: `cancelled` (was pending, rejected by Unlaunch), `not_created` (rejected, refused or failed before Unlaunch), `gone` (undone), `no_campaign` (applied, created no campaign), `paused`. Not yet done: `pending`, `in_flight` (being applied), `pausing` (its pause waits for approval), `pause_rejected`, `pause_failed` (asking again proposes it again). A preview also shows `will_cancel` and `will_pause`.","enum":["cancelled","not_created","gone","no_campaign","paused","pending","in_flight","pausing","pause_rejected","pause_failed","will_cancel","will_pause"]}}}}}},"AdsBriefWhy":{"type":"string","enum":["bestReturn","offTarget","testShare","held","unreadable","otherCurrency","noReturn"]},"AdsBudgetDecision":{"type":"object","description":"The customer's own budget for one campaign (za-84, docs/1006 §84).","required":["key","kind","status","campaign_id","campaign","budget_micros","baseline_micros","reason","decided_by","decided_by_kind","starts_on","ends_on","verdict","since","before","live_micros","drifted","held_back","change_id","step_status"],"properties":{"key":{"type":"string"},"kind":{"type":"string","enum":["budget","test"]},"status":{"type":"string","enum":["pending","active","awaiting","ended"]},"campaign_id":{"type":"string"},"campaign":{"type":"string"},"budget_micros":{"type":"integer","format":"int64"},"baseline_micros":{"type":"integer","format":"int64"},"reason":{"type":"string"},"decided_by":{"type":"string","description":"The person who decided, by name (else e-mail) — set ONLY when `decided_by_kind` is `person`, i.e. a current member of this org; empty for every other kind. Never a raw `user:<id>` or `mcp:<id>`: the audit trail keeps the stored actor."},"decided_by_kind":{"type":"string","enum":["person","support","agency","former_member","assistant","automatic","integration","other"],"description":"Who decided, as a kind the screen translates: `person` (a current member, named in `decided_by`), `support` (our staff — including a decision made while our staff were signed in to this account on the customer's behalf (impersonation): it is recorded as the staff member, never the customer), `agency` (a member of the parent org), `former_member` (removed, deleted or not of this org), `assistant` (the AI assistant over MCP), `automatic` (the autopilot), `integration` (an API key, stored as `apikey:<id>`), `other`."},"starts_on":{"type":"string","format":"date"},"ends_on":{"type":["string","null"],"format":"date"},"verdict":{"type":["string","null"],"enum":["keep","revert",null]},"since":{"oneOf":[{"$ref":"#/components/schemas/AdsBudgetDecisionFigures"},{"type":"null"}]},"before":{"oneOf":[{"$ref":"#/components/schemas/AdsBudgetDecisionFigures"},{"type":"null"}]},"live_micros":{"type":["integer","null"],"format":"int64"},"drifted":{"type":"boolean"},"held_back":{"type":"integer"},"change_id":{"type":["string","null"]},"step_status":{"type":["string","null"]}}},"AdsBudgetDecisionFigures":{"type":"object","description":"One campaign's stored figures over a window (za-84).","required":["clicks","cost_micros","conversions_milli","days"],"properties":{"clicks":{"type":"integer"},"cost_micros":{"type":"integer","format":"int64"},"conversions_milli":{"type":"integer","format":"int64"},"value_micros":{"type":"integer","format":"int64"},"days":{"type":"integer"}}},"AdsBudgetDecisionList":{"type":"object","required":["currency","time_zone","data","campaigns"],"properties":{"currency":{"type":"string","description":"The account's ISO 4217 currency."},"time_zone":{"type":"string","description":"ACCTTZ (docs/1006 §84) — the Google Ads account's own time zone (IANA name, Google's customer.time_zone, refreshed on every sync). Every date in this list (starts_on, ends_on) is that account's calendar day and starts at 00:00 in this zone. Empty until the first sync has read it; the dates are then UTC days."},"campaigns":{"type":"array","description":"The campaigns a person can pick (those the daily audit stored figures for lately).","items":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}}},"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsBudgetDecision"}}}},"AdsBudgetFlag":{"type":"object","description":"za-142 — one campaign its budget holds back while it converts at or below the account's cost per conversion. Money is in micros of `currency` (the ad account's).","required":["id","connection_id","campaign_id","campaign","state","currency","budget_micros","raise_to_micros","lost_budget","cpa_micros","account_cpa_micros","quality_signal","quality_rate","quality_account_rate","zinn_built","change_id","change_status","change_error","first_seen_at","last_seen_at"],"properties":{"id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid"},"campaign_id":{"type":"string"},"campaign":{"type":"string"},"state":{"type":"string","enum":["raised","suggested","ceiling","recent","flagged","held","quality"],"description":"`raised` automatically · `suggested` (a pending change: the one click approves it) · `ceiling` (the spend ceiling stops the raise) · `recent` (its budget changed in the last 7 days) · `flagged` (budget raises off for it) · `held` (an automatic raise waits: no sale yet, the ROAS target or unreliable tracking) · `quality` (za-157: the campaign turns fewer sign-ups into activations, or paying customers, than the account average — no automatic raise and no suggestion; see `quality_*`)."},"currency":{"type":"string"},"budget_micros":{"type":"integer","format":"int64"},"raise_to_micros":{"type":"integer","format":"int64"},"lost_budget":{"type":"number","description":"Share of impressions lost to budget (7 days)."},"cpa_micros":{"type":"integer","format":"int64"},"account_cpa_micros":{"type":"integer","format":"int64"},"quality_signal":{"type":"string","enum":["","activation","paid"],"description":"za-157 (docs/1006 §74) — what the quality gate on automatic raises judged on: `activation` (stage-2 signals per sign-up), `paid` once the account has paid data, or empty while no stage-2 data exists yet (the gate is open and never holds)."},"quality_rate":{"type":"number","description":"The campaign's `quality_signal` signals per sign-up (7 days, 0-1+)."},"quality_account_rate":{"type":"number","description":"The account average of the same rate; a raise needs `quality_rate` ≥ it."},"zinn_built":{"type":"boolean","description":"za-111 — Zinn® Ads built this campaign, so it is raised by itself while the autopilot and `budget_raise_built` are on (inside the ceiling and every guard); the customer's own campaigns get the one-click suggestion."},"change_id":{"type":["string","null"],"format":"uuid"},"change_status":{"type":["string","null"]},"change_error":{"type":["string","null"],"description":"AUTO3b — why the raise was not sent when `change_status` is `refused` (the code leads: `ceiling`, `ceilingCurrency`, `killed`, `paused`, `standing: …`). A refusal by the spend ceiling moves the flag to `ceiling` at once; any other refusal to `flagged`, so the one click is offered again once the cause is fixed."},"first_seen_at":{"type":"string","format":"date-time"},"last_seen_at":{"type":"string","format":"date-time"}}},"AdsBudgetRaiseMode":{"type":"string","enum":["auto","suggest","off"],"description":"za-144 — a converting campaign held back by its budget (≥50% of impressions lost to budget at a cost per conversion at or below the account's, 7 days): `auto` raises it +25% by itself, `suggest` (the default) queues the raise for approval, `off` only flags it (za-142). Never a budget changed in the last 7 days; the spend ceiling always wins."},"AdsBuild":{"type":"object","required":["id","org_id","url","domain","monthly_budget_minor","currency","markets","languages","offer","offers_free","status","error","created_at","updated_at","connection_id","change_ids","launched_at"],"properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"url":{"type":"string"},"domain":{"type":"string"},"monthly_budget_minor":{"type":"integer"},"currency":{"type":"string"},"markets":{"type":"array","items":{"$ref":"#/components/schemas/AdsBuildMarket"}},"languages":{"type":"array","description":"za-106: the site languages the customer confirmed or overrode; empty = the plan uses what the scan detected (`site.languages`).","items":{"$ref":"#/components/schemas/AdsSiteLanguage"}},"market_languages":{"type":"array","description":"Full reads only. Per market, before any research is paid for: can it run (a language the site has and Google serves), where its ads land, and why not — `languageNotOnSite` (with the Tranzly offer, za-108) or `languageNotTargetable` (with `reach_via`, za-113).","items":{"$ref":"#/components/schemas/AdsMarketLanguage"}},"offer":{"type":"string"},"offers_free":{"type":"boolean","description":"za-251 (NEGPLAN): the customer's \"This product has a free plan / free listing\" tick (default false: \"free\" searches are blocked from the start)."},"status":{"type":"string","enum":["scanning","scanned","building","ready","failed","launched"]},"error":{"type":"object","description":"Empty, or `code` (and for an AI failure `message`, `failure`, `can_buy`).","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"},"connection_id":{"type":["string","null"],"format":"uuid"},"change_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"launched_at":{"type":["string","null"],"format":"date-time"},"site":{"type":"object","description":"What the scan read (pages, sentence count, brand, language) and, za-106, every language the site declares (`languages`, each with its address and where it was found) and the translation plugin serving them (`language_plugin`). Full reads only.","additionalProperties":true},"prefill":{"type":"object","description":"The AI's pre-fill (offer, brand, products, sitelinks, callouts). Full reads only.","additionalProperties":true},"plan":{"type":"object","description":"The plan (full reads only): campaigns, ads, dropped_lines, policy, competitors, forecast, assumptions, tracking, extensions, unallocated_minor. NEGPLAN: each campaign's `negatives` are the negatives it starts with, every one replayed against the plan's own keywords; `starter_negatives` lists them as `{text, class, narrowed_from}` (`narrowed_from` names the broad word a narrow phrase replaced because the word would have blocked one of the campaign's keywords). za-251: `free` is `{offers_free, free_searches: allowed|blocked}`, the review's \"Free searches\" line. za-26: `ai` is `{model, funding}` — who paid for the writing (`byo` the organisation's own key, `credits` Zinn® AI credits, `included` the free allowance).","additionalProperties":true}}},"AdsBuildMarket":{"type":"object","required":["country","language"],"properties":{"country":{"type":"string","description":"ISO 3166-1 alpha-2"},"language":{"type":"string","description":"Google Ads language code (en, de, iw, zh_CN, ...)"}}},"AdsBusinessType":{"type":"string","enum":["","free_trial","freemium","lead_gen","ecommerce","local","b2b"],"description":"BUILDL2 (za-153) — the kind of business the account sells for; it decides which conversion action is each signal-ladder stage's signal by default (by Google's conversion-action category) and how long the truth (stage 3) takes to arrive. `\"\"` = not chosen (every category is read). Changes what is measured, never what is written."},"AdsCallNumber":{"type":"object","description":"One Zinn® tracking number (bought from our voice vendor) forwarding to the customer's own number (za-160). Prices in USD micros.","required":["id","connection_id","name","phone_number","country","forward_to","status","monthly_usd_micros","paid_through","suspended_at","calls","refused_calls","ordered_at","released_at"],"properties":{"id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"phone_number":{"type":"string"},"country":{"type":"string"},"forward_to":{"type":"string","description":"Where calls are forwarded; `\"\"` = forwarding switched off (calls refused unanswered)."},"status":{"type":"string","enum":["ordering","active","suspended","releasing","released","failed"]},"monthly_usd_micros":{"type":"integer","format":"int64"},"paid_through":{"type":"string","format":"date-time","nullable":true},"suspended_at":{"type":"string","format":"date-time","nullable":true},"calls":{"type":"integer"},"refused_calls":{"type":"integer"},"ordered_at":{"type":"string","format":"date-time","nullable":true},"released_at":{"type":"string","format":"date-time","nullable":true}}},"AdsCallNumberList":{"type":"object","required":["numbers","open","countries","margin_bps","credit","max_numbers","per_minute_usd_micros","session_minutes","grace_days","source_id","pool_key"],"properties":{"margin_bps":{"type":"integer","description":"The platform margin over the measured vendor price, basis points (owner 2026-10-31: 2000, that is 20 %). Already inside every price shown."},"credit":{"type":"object","description":"The org's prepaid credit against the next month of the account's numbers plus the warning's minutes of calls. `low` is the dashboard warning and the same line the low-credit e-mail (`ads.call_credit.low_balance`) is sent on, before calls stop. `exhausted` is the credit no longer paying a minute of a call: with `stop_forwarding` calls are refused (and `ads.call_credit.exhausted` is e-mailed) until a top-up, after which forwarding resumes by itself.","required":["balance_usd_micros","needed_usd_micros","low","exhausted","out_of_credit"],"properties":{"balance_usd_micros":{"type":"integer","format":"int64"},"needed_usd_micros":{"type":"integer","format":"int64"},"low":{"type":"boolean"},"exhausted":{"type":"boolean"},"out_of_credit":{"type":"string","enum":["stop_forwarding","keep_forwarding"]}}},"numbers":{"type":"array","items":{"$ref":"#/components/schemas/AdsCallNumber"}},"open":{"type":"boolean"},"countries":{"type":"array","items":{"type":"string"}},"max_numbers":{"type":"integer"},"per_minute_usd_micros":{"type":"integer","format":"int64"},"session_minutes":{"type":"integer"},"grace_days":{"type":"integer"},"source_id":{"type":"string","format":"uuid","nullable":true},"pool_key":{"type":"string","nullable":true}}},"AdsCallNumberOffer":{"type":"object","required":["phone_number","locality","first_month_usd_micros","monthly_usd_micros"],"properties":{"phone_number":{"type":"string"},"locality":{"type":"string"},"first_month_usd_micros":{"type":"integer","format":"int64","description":"What buying it costs now — the vendor's upfront fee plus the first month, with the margin."},"monthly_usd_micros":{"type":"integer","format":"int64"}}},"AdsCampaignDiagnosis":{"type":"object","description":"One campaign's \"not showing — why\" and budget pacing (za-76). Money in micros of the account currency.","required":["campaign_id","campaign","state","reasons","why","primary_status","bid_status","days_live","impressions","clicks","cost_micros","conversions","impression_share","lost_budget","lost_rank","shared_budget","cpc_cap_micros","budget_micros","today_micros","today_pct","month_micros","daily_rate_micros","projection_micros","plan_micros","days_in_month","days_left","pace","frozen_until"],"properties":{"campaign_id":{"type":"string"},"campaign":{"type":"string"},"state":{"type":"string","enum":["held","not_showing","limited","new","showing"]},"reasons":{"type":"array","items":{"type":"string","enum":["held","policy","not_eligible","new","budget","rank","learning","no_auctions","low_volume"]}},"why":{"type":"string","description":"The plain English sentence the daily e-mail carries."},"primary_status":{"type":"string","description":"The network's own campaign status (e.g. LEARNING, LIMITED)."},"bid_status":{"type":"string","description":"The network's bid-strategy system status."},"days_live":{"type":"integer"},"impressions":{"type":"integer","description":"Last 7 days."},"clicks":{"type":"integer"},"cost_micros":{"type":"integer","description":"Last 7 days."},"conversions":{"type":"number"},"impression_share":{"type":["number","null"]},"lost_budget":{"type":["number","null"],"description":"Share of impressions lost to the budget (0-1)."},"lost_rank":{"type":["number","null"],"description":"Share of impressions lost to ad rank (0-1)."},"shared_budget":{"type":"boolean"},"cpc_cap_micros":{"type":"integer"},"budget_micros":{"type":"integer","description":"The daily budget."},"today_micros":{"type":"integer","description":"Spent today (the account's day)."},"today_pct":{"type":["integer","null"],"description":"Today's spend as a percentage of the daily budget."},"month_micros":{"type":"integer","description":"Spent this month so far."},"daily_rate_micros":{"type":"integer"},"projection_micros":{"type":"integer"},"plan_micros":{"type":"integer","description":"What the daily budget allows for the whole month."},"days_in_month":{"type":"integer"},"days_left":{"type":"integer"},"pace":{"type":"string","enum":["over","under","on_track","shared","no_budget"]},"frozen_until":{"type":["string","null"],"format":"date-time"}}},"AdsCampaignLadder":{"type":"object","description":"BUILDL3 (gap a) — one account can sell two kinds of thing (hosting judged on a real domain going live, plugins on installs), so a campaign can carry its own `business_type` and/or `signals` (the `AdsLadderSignals` shape); the account's choice fills whatever it does not set, and a campaign not listed follows the account. Keyed by the network's campaign id (digits), at most 500; an empty entry is dropped. `422 badLadderSetting` otherwise.","maxProperties":500,"additionalProperties":{"type":"object","additionalProperties":false,"properties":{"business_type":{"$ref":"#/components/schemas/AdsBusinessType"},"signals":{"$ref":"#/components/schemas/AdsLadderSignals"}}}},"AdsCampaignObjectiveRow":{"type":"object","description":"One campaign's objective, its proposal and the judgement against it (za-184).","required":["campaign_id","campaign","platform","channel","step","currency","objective","pending","proposed_by","proposed_at","approved_at","judgement","ladder"],"properties":{"campaign_id":{"type":"string"},"campaign":{"type":"string"},"platform":{"type":"string","enum":["google","microsoft"]},"channel":{"type":"string"},"step":{"type":"string","description":"The bid-strategy ladder step it is on (§39)."},"currency":{"type":"string"},"objective":{"oneOf":[{"$ref":"#/components/schemas/AdsObjectiveTargets"},{"type":"null"}]},"pending":{"oneOf":[{"$ref":"#/components/schemas/AdsObjectiveTargets"},{"type":"null"}]},"proposed_by":{"type":["string","null"]},"proposed_at":{"type":["string","null"],"format":"date-time"},"approved_at":{"type":["string","null"],"format":"date-time"},"judgement":{"type":["object","null"],"description":"The latest daily verdict against the objective in force.","required":["verdict","label","reason","ladder","at","figures"],"properties":{"verdict":{"type":"string","enum":["on_target","off_target","no_data"]},"label":{"type":"string","description":"The objective and its target in words."},"reason":{"type":"string","description":"The figures it was judged on","in words.":null},"ladder":{"type":"string","description":"The ladder's verdict the same day."},"at":{"type":["string","null"],"format":"date-time"},"figures":{"type":"object","description":"The numbers judged on (money in micros of `currency`): cpa_micros, target_cpa_micros, conversions, roas_pct, target_roas_pct, profit_micros, clicks, cpc_micros, share_pct_measured, share_pct, under_10 (1 when Google reports the share only as under 10%) — each present when it applies.","additionalProperties":{"type":"number"}}}},"ladder":{"type":["object","null"],"required":["verdict","next_step","reason"],"properties":{"verdict":{"type":"string","enum":["up","down","not_yet","top","learning","kept"]},"next_step":{"type":"string"},"reason":{"type":"string"}}}}},"AdsCampaignOffering":{"type":"object","required":["connection_id","campaign_id","offering_id","source"],"properties":{"connection_id":{"type":"string","format":"uuid"},"campaign_id":{"type":"string"},"offering_id":{"type":"string","format":"uuid","nullable":true},"source":{"type":"string","enum":["auto","person","launch"],"nullable":true}}},"AdsChange":{"type":"object","description":"One change to an ad account. `summary` holds figures (service, operations, resources, values), never sentences. za-326 r3: a change queued (or approved and waiting) while the network says its ad set is learning carries `learning` (`rule`: an `AdsAuditRun` `learning_held` code, `network`: the network's name; ZA326-FU: `bid_strategy` is the 14-day za-183 freeze, which in an `approve` class queues the change and a person's approval sends it). While it waits it also carries `learning_unread` (re-checks in a row that could not read the learning state) and `learning_since`; all three go when the wait ends (sent, refused, failed, withdrawn) or when the change is queued again and nothing holds it. A withdrawn change carries `withdrawn` (`by`, `at`). STALESUGG: a waiting change (or a proposal) whose campaign was removed, deleted or has ended, or whose ad group was removed, on any network, is withdrawn by Zinn® Ads itself — `rejected`, `decided_by` `zinn-ads`, `withdrawn` (`by` `zinn-ads`, `at`, `reason` `campaignEnded` · `adGroupRemoved`, and the `campaign` or `ad_group` id); it is never sent and never blocks the same item elsewhere. A waiting change whose campaign could not be read carries `stale` (`code` `targetUnread`, `at`) until it reads. A Microsoft website exclusion re-added by the hourly repair (PG2FIX) carries `reason: reapplied_after_concurrent_edit`. An automatic raise (AUTO3) carries `auto_action` (`cap_raise` za-141 · `budget_raise` za-144), `campaign`, `campaign_id`, `from_micros`, `to_micros`, `cpa_micros`, `account_cpa_micros` and `lost_rank` or `lost_budget`, plus za-157's quality gate figures `quality_signal`, `quality_rate` and `quality_account_rate`. A conflicting negative keyword (za-182, `auto_action: negative_conflict`) carries `decision` (`pause_keywords` · `narrow_negative` · `remove_negative` · `move_to_campaigns`, with `keep_campaigns` `id`/`name`), `reasons` (`negative_newer` · `owner_kept` · `shared_list` · `waste_negative` · `keyword_converts` · `keyword_newer` · `keyword_wins` · `list_reaches_sibling`), `negative` (`text`, `match`, `level` campaign · ad_group · list · account, `where`, `resource`), `blocked` (up to 20 keywords: `text`, `match`, `campaign`, `ad_group`, `resource`) and `blocked_count`. A write that would ADD a negative blocking an enabled keyword is refused before it is sent or queued, whoever asked. A new keyword the audit adds (za-81, `auto_action: new_keyword`) carries `keyword`, `campaign`, `campaign_id`, `ad_group`, `clicks`, `conversions`, `est_daily_micros` and `currency`; when approved it is checked for collisions once more as it is sent, and refused (`error` starting `collides:`) when it would take searches from another ad group. A conversion-goal change (za-78, `auto_action: primary_goal`) carries `goal_action` (the conversion action's name), `goal_category`, `goal_primary` (the new flag), `goal_rule` (`outcome_secondary` · `soft_primary`) and `goal_recorded` (its 30-day count); it is approve-first always, and refused (`error` `goalStarves`, figures in `goal_check`: `recording_now`, `recording_after`) when it would leave no primary conversion action that records — whoever approved it; `error` `goalUnreadable` (no `goal_check`) when the account's conversion actions could not be read to check it. za-70: every change on a customer's account that adds a negative keyword or a keyword is replayed by the collision simulator first, and the replay is kept in `collision`: `checked_at`, `unread` (the account could not be read — a collision, never \"clean\"), `changes` (each `kind` negative · keyword, `text`, `match`, `ad_group`), `collisions` (each `kind` keyword · converted · main · growing · competes · takes, `text`, `campaign`, `ad_group`) with `collisions_total`, `hits` (up to 10 searches of the last 30 days with a click or a conversion it would block or compete for: `term`, `campaign`, `ad_group`, `clicks`, `conversions_milli`) with `hits_total`, `clicks` and `conversions_milli` (totals). A colliding change is never sent by itself: with the connection's `collision_mode` `approve` it waits in the queue, and a person's approval sends it only when a fresh replay finds no collision they were not shown; otherwise, and with `refuse`, it is refused (`error` `collides`). When the account could not be read for the replay (`collision.unread`) an approval, or `refuse`, refuses it `collisionUnread` — nothing established, asked again once the account reads. za-213 (site-to-ad sync for a site hosted with us, `proposed_by: site-sync`): `auto_action: site_sync` is an ad text edit writing a hosted page's new price (`url`, `old_price_minor`, `new_price_minor`, `currency`, integer minor units); `auto_action: site_sync_pause` pauses the ads of a page whose offer ended (`url`).","required":["id","org_id","connection_id","action_class","status","summary","budget_delta_minor","proposed_by","proposed_by_kind","proposed_at","decided_by","decided_at","applied_at","undoable","undo_until","undone_at","error"],"properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid"},"action_class":{"type":"string"},"status":{"$ref":"#/components/schemas/AdsChangeStatus"},"summary":{"type":"object","additionalProperties":true,"description":"What the change does, for the card. SERVEWATCH adds `serving_check` (a bid-strategy switch simulated before the send: `verdict` ok · unknown · starves, `strategy`, `reason`, `ceiling_micros`, `need_micros`, `reach_pct` of the searches the ceiling can win, `raise_to_micros`, `fix`), `restores_served` (a serving-watch revert of the change that stopped a campaign) and `converting_removal` (a removal of campaigns that produced `share_pct`% of the account's results in 30 days: `campaigns`, `share_pct`, `conversions` — an automatic one waits for a person). za-327 adds `ceiling_check` (a CPC ceiling judged before the send against the campaign's measured 30-day average CPC, the top-of-page estimate and the break-even CPC, target CPA x conversion rate: `verdict` ok · refuse · notJudged, `kind` maxClicks · targetImpressionShare · manualCpc · microsoftMaxCpc · microsoftKeywordBid, `ceiling_micros`, `avg_cpc_micros`, `top_micros`, `break_even_micros`, `line_micros` the owner row's line max(2x average CPC, top-of-page high) rounded down to the currency's billable unit, `suggest_micros` the priced fix (0 when no ceiling of one billable unit passes), `cut_micros` what it takes off the most a click costs, `no_fix` true when no ceiling passes (pause the campaign or raise its target), `strategy_id` the portfolio bid strategy whose ceiling it is, `reasons` aboveAverage · aboveTopOfPage · aboveBreakEven · noData · unreadable, `notes` accountFigures (a Microsoft keyword judged on the whole account: its campaign could not be read) · placementUnreadable (a Target impression share ceiling held to break-even: its placement could not be read) — refused above the line or above break-even; also kept on a change that was SENT (an automatic one, or one a person approved) when it was not judged or carries a note; an Undo or serving-watch revert that raises a ceiling is judged too). UNDOSTRAT adds `bidding_before` on a change that alters a campaign's bidding: one entry per campaign (`resource`, `type` the bidding strategy type, `portfolio` a portfolio strategy's resource or `settings` the strategy's own values — `location`, `locationFractionMicros`, `cpcBidCeilingMicros`, `cpcBidFloorMicros`, `targetCpaMicros`, `targetRoas`, `enhancedCpcEnabled`), read before the send. Its Undo restores exactly that, and is marked undone only when Google reads it back. za-323 adds `keywordSanity`: the keywords the keyword sanity gate took out of the request, each `{text, code}` with `code` keywordFragment (only stopwords, comparison or generic words) · keywordOneWord (a phrase or broad keyword with fewer than two meaningful words and no name the account knows) · keywordRivalNotName (a keyword about a rival with no rival named). A refused change's `error` leads with the same code. GATE-PERSON r4 adds `about` `{campaign, keyword}`: the campaign or keyword the change was proposed about (a budget or keyword criterion does not name it), so an approval by an API key or MCP is still bound by a pin or hold set after it was queued (`error` `decisionPinned` / `decisionHeld`, or `decisionUnread` when the campaigns a budget serves could not be read). GATE-PERSON r5: a Microsoft, X, Meta or ChatGPT budget or bid change that names no campaign the pins and holds can see, approved by an API key or MCP while anything is pinned or held, is refused `decisionUnread` too. GATE-PERSON r6: a Google bid change that names an ad group, an ad group criterion or bid modifier, or a portfolio bid strategy is judged on the campaigns read as serving it (`decisionPinned` / `decisionHeld`); unreadable, or naming no campaign at all, is refused `decisionUnread`. GATE-PERSON r7: while anything is held, a change of any other kind (keyword, negative, ad, asset, pause) that names only an ad group or something in one is judged on that ad group's campaign the same way (`decisionHeld` / `decisionUnread`). GATE-PERSON r8: while anything is held, a change naming a shared set (a shared negative list entry, the set, the account-level list's link), automatic or approved by an API key or MCP, is judged on every campaign the set reaches (`decisionHeld` / `decisionUnread`). GATE-PERSON r9: every resource resolves to its campaign first — a Performance Max asset group and anything in one, a budget, a strategy; a kind with no campaign (an account-level asset, conversion goal, negative list unlink, experiment promote) reaches every held campaign. A Microsoft shared negative list associated with a held campaign takes no item. Only a person's approval or Apply passes. An AUTOMATIC change to a shared list that reaches a held campaign (the za-333 sync) is kept `pending` for a person instead of refused, with `summary.heldForPerson` `{code: decisionHeld, campaign_id}`. GATE-PERSON r10: an ad (`ads/<id>`) is read to its campaign; an AUTOMATIC ad change (final URL, display path, status) reaching a held campaign is kept `pending` the same way, and one elsewhere is sent. An existing asset's update reaches every held campaign. When the customer releases the hold, a change still kept for a person on that campaign is closed `refused` with `error` `holdReleased` (the next audit makes the change itself). GATE-PERSON-FU: a change kept for a person also carries `summary.held_campaign_name` (the held campaign's name, \"\" when it could not be read) and, for an ad change, `summary.ad_edits` `[{ad, field (final_url|path1|path2|status), from, to}]` (at most 20; `from` is null when the ad's current value could not be read) with `summary.ad_edits_total`."},"budget_delta_minor":{"type":["integer","null"],"format":"int64"},"proposed_by":{"type":"string","description":"Who proposed the change: who stored it (`user:<id>`, `autopilot`, `mcp:<id>`, `apikey:<id>`, …) — except a member of our staff, who reads `support` and never their id (VERIFY-ADSACTOR: an impersonated write is recorded as the staff member); a reseller's sign-in into this account (`apikey:<reseller key>` or the reseller's own `user:<id>`) reads the reseller's display name — `support` when that actor's sign-ins reach the clients of more than one parent, or its org is gone (ACTORS7, VERIFY-ACTORS7)."},"proposed_by_kind":{"type":["string","null"],"enum":["person","agency","support","integration","assistant","ask","automatic","other",null],"description":"PROPOSERKIND: who proposed the change, as a kind the screen translates — the same words as a decision's `decided_by_kind`. `person` a member of this account's org; `agency` a member of the parent (reseller) org or the parent org's API key (a reseller's sign-in); `support` our staff; `integration` this org's own API key; `assistant` the customer's AI assistant over MCP; `ask` Ask Zinn® Ads' one-click fix on a question; `automatic` one of Zinn® Ads' own producers (the autopilot, the audit, a rule, …); `other` a person or key that is none of these (deleted). Stored when the change is proposed, so a later change of membership never rewrites it. `null` = the proposer cannot be classified (free text, or a person or key on a change made before 2026-11-15): show `proposed_by`."},"proposed_at":{"type":"string","format":"date-time"},"decided_by":{"type":"string","description":"Who approved or declined it (`autopilot` when the audit made it by itself; a person who applied the audit's one-click suggestion is named here although `proposed_by` stays `autopilot`, WALK239): who stored it (`user:<id>`, `autopilot`, `mcp:<id>`, `apikey:<id>`, …) — except a member of our staff, who reads `support` and never their id (VERIFY-ADSACTOR: an impersonated write is recorded as the staff member); a reseller's sign-in into this account (`apikey:<reseller key>` or the reseller's own `user:<id>`) reads the reseller's display name — `support` when that actor's sign-ins reach the clients of more than one parent, or its org is gone (ACTORS7, VERIFY-ACTORS7)."},"decided_at":{"type":["string","null"],"format":"date-time"},"applied_at":{"type":["string","null"],"format":"date-time"},"undoable":{"type":"boolean"},"undo_until":{"type":["string","null"],"format":"date-time"},"undone_at":{"type":["string","null"],"format":"date-time"},"error":{"type":"string","description":"Why the change was not sent, its CODE leading (`ceiling`, `killed`, `paused`, `holdReleased` — GATE-PERSON r10: kept for a person while its campaign was held, and the hold was released, so the automatic path makes it instead — `disconnected`, `standing: …`, `needsReconnect`, `adBelowGood`, `xWritesOff`, za-70 `collides` — the collision simulator found what `summary.collision` names — or `collisionUnread` — the account could not be read for the replay — and za-10 `convertingSearch: …` — a negative keyword that would block a search with a conversion in the last 30 days, refused at the send even when a person approved it; SERVEWATCH `strategyStarves` — a bid-strategy switch whose ceiling or bids cannot win most of the campaign's searches against Google's own top-of-page estimates, refused whoever asked, its figures in `summary.serving_check`; za-327 `ceilingAboveLine` — a CPC ceiling above max(2x the 30-day average CPC, the top-of-page estimate) or above the break-even CPC, refused whoever asked, its figures in `summary.ceiling_check`; UNDOSTRAT, on an APPLIED change whose Undo puts a bid strategy back: `killed` · `paused` · `standing` · `strategyStarves` followed by `: undo refused` — the restore passes the kill switch, good standing and the same simulation — and `undoReadBackDiffers: <campaigns>`, the strategy Google read back after the Undo is not `summary.bidding_before`, so the change stays applied and its Undo can be sent again); otherwise the network's own sentence. Empty when nothing went wrong."},"decision_reason":{"type":"string","maxLength":500,"description":"za-104: the reason given with the decision. An agency's client must give one to reject on the approval portal; `decided_by` then reads `client-portal:<link id>:<the name they typed>`. Empty otherwise."}}},"AdsChangeStatus":{"type":"string","enum":["pending","approved","applied","rejected","refused","failed","undone"]},"AdsChatChannel":{"type":"object","description":"A Slack or Microsoft Teams channel the organisation's Zinn® Ads alerts go to (za-198).","required":["id","kind","label","hint","alerts","enabled","last_status","last_failure","last_sent_at","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["slack","teams"]},"label":{"type":"string"},"hint":{"type":"string","description":"The webhook's host only — never the URL."},"alerts":{"type":"array","items":{"type":"string","enum":["needs","changes","alerts"]}},"enabled":{"type":"boolean"},"last_status":{"type":"string","enum":["","sent","failed"]},"last_failure":{"type":"string","enum":["","channel_gone","channel_unreachable","bad_url","our_fault"]},"last_sent_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"AdsCheckoutSource":{"type":"object","description":"One checkout provider sending its sales, trials and refunds to this ad account by signed webhook (docs/1006 §22). The signing secret is write-only and lives only in Vault.","required":["id","connection_id","provider","label","test_mode","enabled","has_secret","webhook_url","created_at","last_delivery_at","last_delivery_note","deliveries","outcomes"],"properties":{"id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid"},"provider":{"type":"string","enum":["stripe","paddle","freemius"]},"label":{"type":"string"},"test_mode":{"type":"boolean","description":"true = only the provider's test / sandbox events count; false = only live ones."},"enabled":{"type":"boolean"},"has_secret":{"type":"boolean","description":"Whether the provider's signing secret has been given (it is never returned)."},"webhook_url":{"type":"string","format":"uri","description":"The URL to paste into the provider."},"created_at":{"type":"string","format":"date-time"},"last_delivery_at":{"type":"string","format":"date-time","nullable":true},"last_delivery_note":{"type":"string","description":"What the last delivery was: received, ignored, otherMode, noSignature, badSignature, staleTimestamp, badTimestamp, noSecret, vaultUnavailable (empty = none yet)."},"deliveries":{"type":"integer"},"outcomes":{"type":"integer","description":"Outcomes created from this source."}}},"AdsCheckoutWebhookError":{"type":"object","description":"A checkout webhook refusal (no request id — the caller is a provider, not a person).","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["NOT_FOUND","INVALID_SIGNATURE","TOO_LARGE","UNAVAILABLE"]},"message":{"type":"string"}}}}},"AdsClientApprovalLink":{"type":"object","description":"za-104 (docs/1006 §112): one expiring link that lets an agency's client approve or reject the changes waiting on THEIR org's ad accounts, under the agency's brand.","required":["id","org_id","label","created_by","created_at","expires_at","revoked_at","last_used_at","decisions","live"],"properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid","description":"The CLIENT org the link reaches."},"label":{"type":"string","maxLength":120},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"revoked_at":{"type":["string","null"],"format":"date-time"},"last_used_at":{"type":["string","null"],"format":"date-time"},"decisions":{"type":"integer","minimum":0},"live":{"type":"boolean"},"url":{"type":"string","format":"uri","description":"Only in the `201` that made the link — the token is never stored and cannot be shown again. On the agency's own panel address once that address is live."}}},"AdsClientPortal":{"type":"object","required":["brand","expires_at","pending","decided"],"properties":{"brand":{"type":"object","description":"The brand the client org renders under — the agency's, when it has one.","required":["name","logo_url","primary_colour","support_url","is_white_label"],"properties":{"name":{"type":"string"},"logo_url":{"type":"string"},"primary_colour":{"type":"string"},"support_url":{"type":"string"},"is_white_label":{"type":"boolean"}}},"expires_at":{"type":"string","format":"date-time"},"pending":{"type":"array","maxItems":200,"items":{"$ref":"#/components/schemas/AdsClientPortalChange"}},"decided":{"type":"array","maxItems":200,"description":"What this link decided in the last 30 days.","items":{"$ref":"#/components/schemas/AdsClientPortalChange"}}}},"AdsClientPortalChange":{"type":"object","description":"What the agency's client sees of one change — no vendor path, no actor ids.","required":["id","action_class","status","summary","budget_delta_minor","currency","account_name","proposed_at","decided_at","decided_by_name","decision_reason","error"],"properties":{"id":{"type":"string","format":"uuid"},"action_class":{"type":"string"},"status":{"type":"string","enum":["pending","approved","applied","rejected","refused","failed","undone"]},"summary":{"type":"object","additionalProperties":true},"budget_delta_minor":{"type":["integer","null"],"format":"int64","description":"The daily budget increase asked for, minor units of `currency`."},"currency":{"type":"string","description":"ISO 4217 code of the ad account."},"account_name":{"type":"string"},"proposed_at":{"type":"string","format":"date-time"},"decided_at":{"type":["string","null"],"format":"date-time"},"decided_by_name":{"type":"string","description":"The name the client typed; empty while pending."},"decision_reason":{"type":"string"},"error":{"type":"string","description":"Only on a refused or failed change."}}},"AdsCompetitorGroup":{"type":"object","required":["rival","language","campaign_id","ad_group","status"],"properties":{"kind":{"type":"string","enum":["group","block"],"description":"za-71: a built group, or a blocked rival's campaign negatives."},"verdict":{"type":"string","enum":["free_host","wrong_market"],"description":"za-71: why a block blocks."},"negatives":{"type":"array","items":{"type":"string"},"description":"za-71: the EXACT campaign negatives of a block."},"refused":{"type":"array","items":{"type":"string"},"description":"Searches of a block the pre-check refused (an enabled keyword's query, or a search that converted); the rest were still sent."},"rival":{"type":"string"},"language":{"type":"string","description":"The market's language code."},"campaign_id":{"type":"string"},"campaign":{"type":"string"},"ad_group":{"type":"string","description":"The proposed group, `<Rival> alternative`."},"impressions":{"type":"integer"},"clicks":{"type":"integer"},"status":{"type":"string","enum":["proposed","applied","waiting","refused","failed","off"],"description":"applied = sent by the Automatic mode, with an Undo (za-71)."},"reason":{"type":"string","description":"Why it waits - noApprovedAd, noLandingPage, gateRefused, noBid (no enabled group bid and no Maximise-clicks ceiling to start the new group on), refused, failed, conflict."},"detail":{"type":"array","items":{"type":"string"}},"change_id":{"type":"string","format":"uuid"},"keywords":{"type":"array","items":{"type":"string"}},"final_url":{"type":"string"},"source":{"type":"string","enum":["copied","translated","written"]},"headlines":{"type":"array","items":{"type":"string"}},"descriptions":{"type":"array","items":{"type":"string"}}}},"AdsCompetitorGroupsEnvelope":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["enabled","switch","settings","last_run","pending"],"properties":{"enabled":{"type":"boolean"},"switch":{"type":"boolean"},"settings":{"type":"object","required":["min_impressions","min_clicks","lookback_days","max_keywords","block_free_hosts","block_off_market"],"properties":{"block_free_hosts":{"$ref":"#/components/schemas/AdsCompetitorGroupsSwitch"},"block_off_market":{"$ref":"#/components/schemas/AdsCompetitorGroupsSwitch"},"min_impressions":{"$ref":"#/components/schemas/AdsCompetitorGroupsThreshold"},"min_clicks":{"$ref":"#/components/schemas/AdsCompetitorGroupsThreshold"},"lookback_days":{"$ref":"#/components/schemas/AdsCompetitorGroupsThreshold"},"max_keywords":{"$ref":"#/components/schemas/AdsCompetitorGroupsThreshold"}}},"last_run":{"oneOf":[{"$ref":"#/components/schemas/AdsCompetitorGroupsRun"},{"type":"null"}]},"pending":{"type":"integer","description":"Proposals waiting for approval."},"found_rivals":{"type":"array","items":{"$ref":"#/components/schemas/AdsFoundRival"}}}}}},"AdsCompetitorGroupsPatch":{"type":"object","additionalProperties":false,"properties":{"block_free_hosts":{"type":["boolean","null"],"description":"za-71: block searches for a free host. null = Recommended (on)."},"block_off_market":{"type":["boolean","null"],"description":"za-71: block a local brand searched outside its market. null = Recommended (on)."},"min_impressions":{"type":["integer","null"],"minimum":1,"maximum":1000000},"min_clicks":{"type":["integer","null"],"minimum":0,"maximum":100000},"lookback_days":{"type":["integer","null"],"minimum":7,"maximum":90},"max_keywords":{"type":["integer","null"],"minimum":1,"maximum":15},"rivals":{"type":"object","description":"za-73: add or dismiss competitors found on the account, by name (from `found_rivals`). An unknown name or value refuses the whole request (competitorGroupsInvalid, field `rivals`).","additionalProperties":{"type":"string","enum":["added","dismissed"]}}}},"AdsCompetitorGroupsRun":{"type":"object","required":["at","skipped","proposed","waiting","covered","groups"],"properties":{"at":{"type":"string","format":"date-time"},"skipped":{"type":"string","description":"Empty when it ran; else why not (competitorsOff, notInGoodStanding, ...)."},"proposed":{"type":"integer"},"applied":{"type":"integer","description":"za-71: builds and blocks the Automatic mode sent."},"blocked":{"type":"integer","description":"za-71: blocks decided this run (applied or proposed)."},"waiting":{"type":"integer"},"covered":{"type":"integer","description":"Rival + language pairs that already have a group or a decided proposal."},"found_rivals":{"type":"integer","description":"za-73: found competitors waiting for a person to add or dismiss."},"groups":{"type":"array","items":{"$ref":"#/components/schemas/AdsCompetitorGroup"}}}},"AdsCompetitorGroupsSwitch":{"type":"object","required":["value","recommended","custom"],"properties":{"value":{"type":"boolean"},"recommended":{"type":"boolean"},"custom":{"type":"boolean","description":"True when the customer set it; false = Recommended."}}},"AdsCompetitorGroupsThreshold":{"type":"object","required":["value","recommended","min","max","custom"],"properties":{"value":{"type":"integer"},"recommended":{"type":"integer"},"min":{"type":"integer"},"max":{"type":"integer"},"custom":{"type":"boolean","description":"True when the customer set it; false = Recommended."}}},"AdsConnectionSettingsUpdate":{"type":"object","description":"One connected account's autopilot settings (UI1, za-18). Only what is sent changes. Plan rules: `auto` in `modes`, `hold_until_sale` and `roas_target_pct` need autopilot (Starter and above); more than one language in `markets` and turning `competitor_automation` on need Pro and above. Turning a thing off is never refused.","properties":{"label":{"type":"string","maxLength":200},"status":{"type":"string","enum":["active","paused"]},"modes":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/AdsMode"}},"daily_ceiling_minor":{"type":["integer","null"],"format":"int64","minimum":0},"monthly_ceiling_minor":{"type":["integer","null"],"format":"int64","minimum":0},"ceiling_currency":{"type":"string","pattern":"^[A-Z]{3}$"},"hold_until_sale":{"type":"boolean"},"roas_target_pct":{"type":["integer","null"],"minimum":50,"maximum":10000},"markets":{"type":"array","maxItems":8,"items":{"$ref":"#/components/schemas/AdsBuildMarket"}},"competitor_automation":{"type":"boolean"},"collision_mode":{"type":"string","enum":["approve","refuse"]},"auto_new_countries":{"type":"boolean"},"new_country_max_per_month":{"type":"integer","minimum":0,"maximum":10},"new_country_budget_minor":{"type":["integer","null"],"format":"int64","minimum":1,"maximum":10000000000},"new_country_min_conversions":{"type":"integer","minimum":1,"maximum":1000},"new_country_min_clicks":{"type":"integer","minimum":1,"maximum":100000},"auto_cap_raise":{"type":"boolean"},"auto_bid_switch":{"type":"boolean","description":"LADDERFIX: let Zinn® Ads switch bidding automatically when there's enough data (default false: approve-first)."},"auto_push_tests":{"type":"boolean"},"push_test_max_running":{"type":"integer","minimum":1,"maximum":10},"push_test_confidence_pct":{"type":"integer","minimum":80,"maximum":99},"budget_raise_mode":{"$ref":"#/components/schemas/AdsBudgetRaiseMode"},"budget_raise_scope":{"type":"string","enum":["all","campaigns"]},"budget_raise_built":{"type":"boolean","description":"za-111: campaigns Zinn® Ads built are raised by themselves while the autopilot is on. Turning it back on counts from that moment (nothing back-dated)."},"budget_raise_campaigns":{"type":"object","description":"Google campaign id (digits) → mode, at most 500. Setting `auto` (for all or for a campaign) needs autopilot (Starter and above).","additionalProperties":{"$ref":"#/components/schemas/AdsBudgetRaiseMode"}},"pacing_mode":{"$ref":"#/components/schemas/AdsPacingMode"},"pacing_deviation_pct":{"type":"integer","minimum":5,"maximum":50},"pacing_target_minor":{"type":["integer","null"],"format":"int64","minimum":1,"maximum":1000000000000},"pacing_strategy":{"$ref":"#/components/schemas/AdsPacingStrategy"},"pacing_change_cap_pct":{"type":"integer","minimum":5,"maximum":50},"pacing_rollover":{"type":"boolean"},"pacing_pause_over":{"type":"boolean"},"pacing_minimums":{"type":"object","maxProperties":500,"additionalProperties":{"type":"integer","format":"int64","minimum":1,"maximum":10000000000}},"tidy_paused_days":{"type":["integer","null"],"minimum":1,"maximum":365},"shield_min_clicks":{"type":["integer","null"],"minimum":1,"maximum":50,"description":"IPROTATE (za-59). null = recommended. `422 badShieldSetting` outside the bounds."},"shield_stale_days":{"type":["integer","null"],"minimum":1,"maximum":60},"shield_waste_min_clicks":{"type":["integer","null"],"minimum":1,"maximum":100000},"tidy_paused_mode":{"type":"string","enum":["auto","suggest"],"description":"Setting `auto` needs autopilot (Starter and above). `422 badTidyDays`."},"conversion_lag_days":{"type":["integer","null"],"minimum":1,"maximum":90},"cta_words":{"type":"array","maxItems":10,"items":{"type":"string","maxLength":60},"description":"Trimmed and de-duplicated; more than 10 or one over 60 characters is `422 badCtaWords`."},"free_plan_campaigns":{"type":"array","maxItems":500,"items":{"type":"string","maxLength":20},"description":"za-251: Google campaign ids whose product has a free plan / free listing (replaces the list; digits only, de-duplicated). Anything else is `422 badFreePlanCampaigns`."},"offer_profiles":{"type":"object","description":"OFFERFIT: `{campaign_id: profile | null}` — the customer's own words for what a campaign sells (`sells` required, up to 20 items of 120 characters each); `null` resets it to the automatic profile. Campaigns not named are unchanged. No `sells` is `422 badOfferProfile` (field `offer_profile.sells`).","additionalProperties":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/AdsOfferProfileEdit"}]}},"waste_threshold_minor":{"type":["integer","null"],"format":"int64","minimum":1,"maximum":10000000000,"description":"WASTEFIX r3 — the customer's own waste threshold (minor units of the account currency); null = back to the recommended value. Out of range is `422 badWasteSetting`."},"cluster_min_terms":{"type":["integer","null"],"minimum":2,"maximum":50,"description":"WASTEFIX r3 — the customer's own cluster size; null = back to the recommended 5. Out of range is `422 badWasteSetting`."},"focus_min_conversions":{"type":["integer","null"],"minimum":1,"maximum":1000,"description":"ADSFOCUS-GUARD (za-258) — the customer's own floor of account conversions for the campaign-focus switch; null = back to the recommended 15. Out of range is `422 badLimit`."},"excluded_countries":{"type":"array","maxItems":250,"items":{"type":"string","minLength":2,"maxLength":2},"description":"ISO 3166-1 alpha-2 codes Google can target; anything else is `422 badExcludedCountries`."},"country_waste_mode":{"type":"string","enum":["auto","suggest","off"]},"country_cut_on":{"type":"boolean"},"country_cut_window_days":{"type":"integer","minimum":7,"maximum":90},"country_cut_spend_minor":{"type":["integer","null"],"minimum":1,"maximum":10000000000,"description":"null = the recommended £25 in the account currency (\"Reset to recommended\")."},"country_cut_share_pct":{"type":"integer","minimum":5,"maximum":95},"country_cut_rate_pct":{"type":"integer","minimum":5,"maximum":100},"country_cut_keep":{"type":"array","maxItems":250,"items":{"type":"string","minLength":2,"maxLength":2},"description":"ISO 3166-1 alpha-2 codes Google can target; anything else is `422 badCountryCutSetting`."},"business_type":{"$ref":"#/components/schemas/AdsBusinessType"},"ladder_signals":{"$ref":"#/components/schemas/AdsLadderSignals"},"campaign_ladder":{"$ref":"#/components/schemas/AdsCampaignLadder"},"rsa_tests":{"type":"boolean"},"rsa_test_confidence_pct":{"type":"integer","minimum":80,"maximum":99},"rsa_test_min_impressions":{"type":"integer","minimum":100,"maximum":10000000},"rsa_test_min_clicks":{"type":"integer","minimum":1,"maximum":1000000},"rsa_test_min_days":{"type":"integer","minimum":7,"maximum":90},"rsa_test_metric":{"type":"string","enum":["ctr","conversions"]},"reach_min_searches":{"type":"integer","minimum":1,"maximum":1000000},"reach_test_days":{"type":"integer","minimum":7,"maximum":60}}},"AdsControls":{"type":"object","required":["org_id","killed","killed_at","daily_email","report_email","global_killed"],"properties":{"org_id":{"type":"string","format":"uuid"},"killed":{"type":"boolean"},"killed_at":{"type":["string","null"],"format":"date-time"},"daily_email":{"type":"boolean"},"report_email":{"type":"boolean","description":"za-08: the weekly return-on-ad-spend e-mail (Mondays) and the monthly growth review (the 1st) are sent. True until the customer switches them off."},"global_killed":{"type":"boolean"}}},"AdsConversionSetup":{"type":"object","description":"One ad account's conversion setup (za-12, docs/1006 §80).","required":["connection_id","platform","customer_id","method","quiet_days","recommended_quiet_days","quiet_days_min","quiet_days_max","ga4","server","ga4_property_id","ga4_key_events","needs_reconnect","failure"],"properties":{"connection_id":{"type":"string","format":"uuid"},"platform":{"type":"string"},"customer_id":{"type":"string","description":"The ad account id (digits) the customer links GA4 to."},"method":{"type":"string","enum":["","ga4","server"]},"quiet_days":{"type":"integer"},"recommended_quiet_days":{"type":"integer"},"quiet_days_min":{"type":"integer"},"quiet_days_max":{"type":"integer"},"ga4_property_id":{"type":"string"},"ga4_key_events":{"type":"array","items":{"type":"string"}},"needs_reconnect":{"type":"boolean"},"failure":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/VendorFailure"}]},"ga4":{"type":"object","description":"Google only; empty on Microsoft.","properties":{"state":{"type":"string","enum":["not_linked","not_chosen","ready","queued","not_mapped","waiting","working","unreadable"]},"properties":{"type":"array","items":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}}},"events":{"type":"array","items":{"type":"object","required":["resource","event","name","property_id","status","primary","chosen","conversions"],"properties":{"resource":{"type":"string"},"event":{"type":"string"},"name":{"type":"string"},"property_id":{"type":"string"},"status":{"type":"string"},"primary":{"type":"boolean"},"chosen":{"type":"boolean"},"conversions":{"type":"number"}}}}}},"server":{"type":"object","required":["state","actions","mapped","received","uploaded","last_outcome_at"],"properties":{"state":{"type":"string","enum":["not_linked","not_chosen","ready","queued","not_mapped","waiting","working","unreadable"]},"actions":{"type":"array","items":{"type":"object","required":["resource","name","status"],"properties":{"resource":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"}}}},"mapped":{"type":"object","additionalProperties":{"type":"string"}},"received":{"type":"integer"},"uploaded":{"type":"integer"},"last_outcome_at":{"type":"string","format":"date-time","nullable":true}}}}},"AdsCopyWinner":{"type":"object","required":["campaign_id","ad_group","ad_id","language","countries","clicks","conversions","rate","baseline_rate","p_value"],"properties":{"campaign_id":{"type":"string"},"campaign":{"type":"string"},"ad_group":{"type":"string"},"ad_id":{"type":"string"},"language":{"type":"string","description":"The source market's language code."},"countries":{"type":"array","items":{"type":"string"},"description":"ISO country codes the source campaign targets."},"clicks":{"type":"integer"},"conversions":{"type":"number","description":"First-party conversions only."},"rate":{"type":"number"},"baseline_rate":{"type":"number","description":"The campaign's other ads, pooled."},"p_value":{"type":"number"}}},"AdsCopyWinnerCopy":{"type":"object","required":["source_ad_id","ad_group","connection_id","campaign_id","language","status"],"properties":{"source_ad_id":{"type":"string"},"ad_group":{"type":"string"},"connection_id":{"type":"string","format":"uuid","description":"The target connection (same org)."},"campaign_id":{"type":"string"},"campaign":{"type":"string"},"language":{"type":"string"},"countries":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["proposed","approved","waiting"]},"reason":{"type":"string","description":"Why it waits - noTranslation, tooLong, gateRefused, noStartBid."},"detail":{"type":"array","items":{"type":"string"}},"change_id":{"type":"string","format":"uuid"},"headlines":{"type":"array","items":{"type":"string"}},"descriptions":{"type":"array","items":{"type":"string"}},"keywords":{"type":"array","items":{"type":"string"}}}},"AdsCopyWinnersEnvelope":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["on","mode","settings","last_run","pending"],"properties":{"on":{"type":"boolean"},"mode":{"type":"string","enum":["suggest","auto"]},"settings":{"type":"object","required":["min_clicks","min_conversions","confidence_pct","lookback_days"],"properties":{"min_clicks":{"$ref":"#/components/schemas/AdsCompetitorGroupsThreshold"},"min_conversions":{"$ref":"#/components/schemas/AdsCompetitorGroupsThreshold"},"confidence_pct":{"$ref":"#/components/schemas/AdsCompetitorGroupsThreshold"},"lookback_days":{"$ref":"#/components/schemas/AdsCompetitorGroupsThreshold"}}},"last_run":{"oneOf":[{"$ref":"#/components/schemas/AdsCopyWinnersRun"},{"type":"null"}]},"pending":{"type":"integer","description":"This account's copies waiting for approval, in any of the org's accounts."}}}}},"AdsCopyWinnersPatch":{"type":"object","additionalProperties":false,"properties":{"on":{"type":"boolean"},"mode":{"type":"string","enum":["suggest","auto"]},"min_clicks":{"type":["integer","null"],"minimum":10,"maximum":1000000},"min_conversions":{"type":["integer","null"],"minimum":1,"maximum":100000},"confidence_pct":{"type":["integer","null"],"minimum":80,"maximum":99},"lookback_days":{"type":["integer","null"],"minimum":14,"maximum":90}}},"AdsCopyWinnersRun":{"type":"object","required":["at","skipped","winners","proposed","applied","waiting","covered","other_site","winner_list","copy_list"],"properties":{"at":{"type":"string","format":"date-time"},"skipped":{"type":"string","description":"Empty when it ran; else why not (switchedOff, noFirstPartyProof, notInGoodStanding, ...)."},"winners":{"type":"integer"},"proposed":{"type":"integer"},"applied":{"type":"integer","description":"Copies approved at once (mode auto)."},"waiting":{"type":"integer"},"covered":{"type":"integer","description":"Targets that already have the group or a decided copy."},"other_site":{"type":"integer","description":"Campaigns skipped because they advertise another website."},"winner_list":{"type":"array","items":{"$ref":"#/components/schemas/AdsCopyWinner"}},"copy_list":{"type":"array","items":{"$ref":"#/components/schemas/AdsCopyWinnerCopy"}}}},"AdsCountryCampaign":{"type":"object","description":"One campaign whose only location is one country (za-75). Money in micros of the account currency; 7 days.","required":["campaign_id","campaign","country","state","why","budget_micros","lost_budget","cost_micros","conversions","cost_per_conversion_micros","built_by","built_at","change_id","held_by_budget","budget_flag"],"properties":{"campaign_id":{"type":"string"},"campaign":{"type":"string"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 code."},"state":{"type":"string","enum":["held","not_showing","limited","new","showing"]},"why":{"type":"string","description":"The diagnosis's plain English sentence (za-76)."},"budget_micros":{"type":"integer","format":"int64"},"lost_budget":{"type":["number","null"],"description":"Share of impressions lost to budget, 0-1."},"cost_micros":{"type":"integer","format":"int64"},"conversions":{"type":"number"},"cost_per_conversion_micros":{"type":["integer","null"],"format":"int64"},"built_by":{"type":"string","enum":["autopilot","you"]},"built_at":{"type":["string","null"],"format":"date-time"},"change_id":{"type":["string","null"],"format":"uuid"},"held_by_budget":{"type":"boolean"},"budget_flag":{"type":["object","null"],"required":["state","raise_to_micros"],"properties":{"state":{"type":"string","enum":["raised","suggested","ceiling","recent","flagged"]},"raise_to_micros":{"type":"integer","format":"int64"}}}}},"AdsCountryCandidate":{"type":"object","description":"A country that converted in 30 days inside campaigns that are not its own (za-75).","required":["country","clicks","conversions","cost_micros","cost_per_conversion_micros","standing"],"properties":{"country":{"type":"string","description":"ISO 3166-1 alpha-2 code."},"clicks":{"type":"integer"},"conversions":{"type":"number"},"cost_micros":{"type":"integer","format":"int64"},"cost_per_conversion_micros":{"type":["integer","null"],"format":"int64"},"standing":{"type":"string","enum":["proposed","ready","watching","monthly_limit","excluded","off"]}}},"AdsCountryCutRecommended":{"type":"object","additionalProperties":false,"required":["window_days","spend_minor","spend_gbp_minor","currency","share_pct","rate_pct"],"description":"COUNTRYCUT — our recommended values, in the connection's currency.","properties":{"window_days":{"type":"integer"},"spend_minor":{"type":["integer","null"],"description":"£25 in the account currency at today's stored rate; null = no stored rate."},"spend_gbp_minor":{"type":"integer"},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"share_pct":{"type":"integer"},"rate_pct":{"type":"integer"}}},"AdsCrmSource":{"type":"object","description":"One CRM / sheet / call-log source feeding offline conversions (za-160). The credential is never returned.","required":["id","connection_id","vendor","name","enabled","has_secret","instance","sandbox","object_type","sheet_gid","stage_map","field_map","currency","consent_attested","consent_values","min_call_seconds","call_action","call_value_minor","cursor_at","last_attempted_at","last_synced_at","last_failure","failure","leads_read","outcomes_made","not_consented","unmapped","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid"},"vendor":{"type":"string","enum":["hubspot","pipedrive","salesforce","sheet","csv","calls_csv","telnyx"]},"name":{"type":"string"},"enabled":{"type":"boolean"},"has_secret":{"type":"boolean"},"instance":{"type":"string","description":"Salesforce My Domain name, or the Google Sheet id."},"sandbox":{"type":"boolean"},"object_type":{"type":"string","description":"Salesforce: `Lead` or `Opportunity`."},"sheet_gid":{"type":"string"},"stage_map":{"type":"array","items":{"$ref":"#/components/schemas/AdsCrmStageRule"}},"field_map":{"type":"object","additionalProperties":{"type":"string"},"description":"Which CRM property / column holds each value (`gclid`, `msclkid`, `email`, `consent` …)."},"currency":{"type":"string"},"consent_attested":{"type":"boolean"},"consent_values":{"type":"array","items":{"type":"string"}},"min_call_seconds":{"type":"integer"},"call_action":{"type":"string"},"call_value_minor":{"type":["integer","null"]},"cursor_at":{"type":["string","null"],"format":"date-time"},"last_attempted_at":{"type":["string","null"],"format":"date-time"},"last_synced_at":{"type":["string","null"],"format":"date-time"},"last_failure":{"type":"string"},"failure":{"oneOf":[{"$ref":"#/components/schemas/VendorFailure"},{"type":"null"}]},"leads_read":{"type":"integer"},"outcomes_made":{"type":"integer"},"not_consented":{"type":"integer"},"unmapped":{"type":"integer"},"created_at":{"type":["string","null"],"format":"date-time"}}},"AdsCrmSourceIn":{"type":"object","properties":{"name":{"type":"string","maxLength":80},"enabled":{"type":"boolean"},"token":{"type":"string","minLength":8,"writeOnly":true},"client_id":{"type":"string","minLength":8,"writeOnly":true},"client_secret":{"type":"string","minLength":8,"writeOnly":true},"instance":{"type":"string","maxLength":100},"sandbox":{"type":"boolean"},"object_type":{"type":"string","enum":["Lead","Opportunity"]},"sheet_gid":{"type":"string","pattern":"^[0-9]{0,20}$"},"stage_map":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/AdsCrmStageRule"}},"field_map":{"type":"object","additionalProperties":{"type":"string","maxLength":80}},"currency":{"type":"string","pattern":"^([A-Za-z]{3})?$"},"consent_attested":{"type":"boolean"},"consent_values":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":40}},"min_call_seconds":{"type":"integer","minimum":1,"maximum":3600},"call_action":{"type":"string","maxLength":200},"call_value_minor":{"type":["integer","null"],"minimum":0}}},"AdsCrmSources":{"type":"object","required":["sources","vendors","steps","lead_fields","call_fields","currency"],"properties":{"currency":{"type":"string","description":"The ad account's currency: a new source's values are in it."},"sources":{"type":"array","items":{"$ref":"#/components/schemas/AdsCrmSource"}},"vendors":{"type":"array","items":{"type":"string"}},"steps":{"type":"array","items":{"type":"string"}},"lead_fields":{"type":"array","items":{"type":"string"}},"call_fields":{"type":"array","items":{"type":"string"}}}},"AdsCrmStageRule":{"type":"object","required":["stage","step","action"],"properties":{"stage":{"type":"string","maxLength":100,"description":"The stage id in the CRM (`sql`, a Pipedrive stage id, `won`)."},"step":{"type":"string","enum":["lead","qualified","opportunity","won"]},"action":{"type":"string","maxLength":200,"description":"One of this account's conversion actions."},"value_minor":{"type":["integer","null"],"minimum":0,"description":"A fixed value in integer minor units of the source currency."},"use_crm_value":{"type":"boolean","description":"Send the CRM's own deal value instead."}}},"AdsCrmStages":{"type":"object","required":["stages","failure"],"properties":{"stages":{"type":"array","items":{"type":"object","required":["id","label"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}}},"failure":{"oneOf":[{"$ref":"#/components/schemas/VendorFailure"},{"type":"null"}]}}},"AdsCrmSyncResult":{"type":"object","required":["read","stored","not_consented","unmapped","short_calls","no_click_id","more","failure","skipped"],"properties":{"read":{"type":"integer"},"stored":{"type":"integer"},"not_consented":{"type":"integer"},"unmapped":{"type":"integer"},"short_calls":{"type":"integer"},"no_click_id":{"type":"integer"},"list_changes":{"type":"integer","description":"za-95: people who joined or left a CRM-fed Customer Match list (CSV uploads)."},"more":{"type":"boolean"},"failure":{"type":"string"},"skipped":{"type":"string"}}},"AdsCrossBudget":{"type":"object","required":["org_id","ceiling_minor","currency","mode","measured_at","networks","proposal","last_apply"],"properties":{"org_id":{"type":"string","format":"uuid"},"ceiling_minor":{"type":["integer","null"]},"currency":{"type":["string","null"]},"mode":{"type":"string","enum":["suggest","auto"]},"measured_at":{"type":["string","null"],"format":"date-time"},"networks":{"type":"array","items":{"$ref":"#/components/schemas/AdsCrossBudgetNetwork"}},"proposal":{"type":"object","required":["targets","moves","blocked"],"properties":{"targets":{"type":"object","additionalProperties":{"type":"integer"},"description":"The new monthly ceiling (minor units) per connection id; absent = left alone."},"moves":{"type":"array","items":{"$ref":"#/components/schemas/AdsCrossBudgetMove"}},"blocked":{"type":"string","enum":["","noReturnYet"]},"why":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/AdsBriefWhy"},"description":"za-208 — per connection id, why it gets what it gets (absent on a proposal made before the brief existed)."}}},"last_apply":{"type":["object","null"],"required":["at","by","moves","undone_at","can_undo"],"properties":{"at":{"type":["string","null"],"format":"date-time"},"by":{"type":["string","null"]},"moves":{"type":"array","items":{"$ref":"#/components/schemas/AdsCrossBudgetMove"}},"undone_at":{"type":["string","null"],"format":"date-time"},"can_undo":{"type":"boolean"}}}}},"AdsCrossBudgetMove":{"type":"object","required":["from","to","amount_minor"],"properties":{"from":{"type":["string","null"]},"to":{"type":["string","null"]},"amount_minor":{"type":"integer"}}},"AdsCrossBudgetNetwork":{"type":"object","required":["connection_id","platform","label","currency","ceiling_minor","cost_minor","conversions_milli","value_minor","cost_per_conversion_minor","roas_pct","reason"],"properties":{"connection_id":{"type":"string","format":"uuid"},"platform":{"type":"string"},"label":{"type":"string"},"currency":{"type":"string"},"ceiling_minor":{"type":["integer","null"]},"cost_minor":{"type":"integer"},"conversions_milli":{"type":"integer","description":"RECORDED conversions x 1000 (MSALLCONV): every conversion the network recorded, biddable goal or not. Not the same noun as `value_minor`."},"value_minor":{"type":"integer","description":"Conversion value on the goals used for BIDDING only (Google `conversions_value`; 0 for a network whose value is not read). `roas_pct` is over this value; never divide it by `conversions_milli`."},"cost_per_conversion_minor":{"type":["integer","null"],"description":"Cost per RECORDED conversion."},"roas_pct":{"type":["integer","null"],"description":"Biddable value per unit spent","as a percent.":null},"reason":{"type":"string","enum":["","otherCurrency","held","unreadable","noReturn"]}}},"AdsExperiment":{"type":"object","description":"One budget test (za-193): its pending or applied change and, once applied, its dated review. Budgets are the account's integer micros in `currency`.","required":["id","change_id","name","origin","state","change_pct","days","campaigns","currency","proposed_by","proposed_at","applied_at","undoable","review","significance"],"properties":{"significance":{"nullable":true,"description":"PUSHTESTS (za-16) — the judged result at the connection's `push_test_confidence_pct`; null until the review is judged.","allOf":[{"$ref":"#/components/schemas/AdsExperimentSignificance"}]},"id":{"type":"string","format":"uuid"},"change_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"origin":{"type":"string","enum":["customer","autopilot"],"description":"`customer` — started by a person or an AI agent; `autopilot` — a push test the autopilot proposed for a campaign held back by its budget (za-110, `auto_push_tests`)."},"state":{"type":"string","description":"awaiting_approval, starting, running, ended, failed, or the change status (rejected, undone, …)."},"change_pct":{"type":"integer"},"days":{"type":"integer"},"campaigns":{"type":"array","items":{"type":"object","required":["id","name","from_micros","to_micros"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"from_micros":{"type":"integer","format":"int64"},"to_micros":{"type":"integer","format":"int64"}}}},"currency":{"type":"string"},"proposed_by":{"type":"string"},"proposed_at":{"type":"string","format":"date-time"},"applied_at":{"type":"string","format":"date-time","nullable":true},"undoable":{"type":"boolean"},"review":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/AdsReview"}]}}},"AdsExperimentSignificance":{"type":"object","description":"PUSHTESTS (za-16) — results per click before the test against during it, a pooled two-proportion z-test. Integers only: `p_x10000` is p × 10 000, rates are × 10 000.","required":["confidence_pct","p_x10000","significant","before_rate_x10000","after_rate_x10000"],"properties":{"confidence_pct":{"type":"integer","minimum":80,"maximum":99},"p_x10000":{"type":"integer","minimum":0,"maximum":10000},"significant":{"type":"boolean"},"before_rate_x10000":{"type":"integer","minimum":0},"after_rate_x10000":{"type":"integer","minimum":0}}},"AdsExperimentSpec":{"type":"object","description":"A dated budget test (za-193). Closed ranges; anything outside is refused.","required":["name","campaign_ids","change_pct"],"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"campaign_ids":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string","pattern":"^[0-9]{1,24}$"}},"change_pct":{"type":"integer","minimum":-50,"maximum":100,"description":"Budget step in percent; not 0."},"days":{"type":"integer","minimum":7,"maximum":60,"default":14}}},"AdsFinding":{"type":"object","description":"FINDALL1 (za-211) — one thing the daily audit found on the account, in figures. Money is in micros of `figures.currency` (the ad account's).","required":["id","connection_id","kind","why","detector","status","suggested","can_apply","automatic","figures","change_id","first_seen_at","last_seen_at","closed_at"],"properties":{"id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["waste_term","good_term","poor_keyword","policy","pacing","credit","tracking","country","new_keyword","new_market","ad_copy","budget_shift","remarketing","self_check"]},"why":{"type":"string","description":"The reason in one code (`budget_limited`, `rank_limited`, `landing_below_average`, `suggest_asset_unlink`, …; the registry in `engine/engine/adsreport/registry.py` lists every one). SERVEWATCH: `serve_dropped`, `serve_never` (hourly: a campaign that stopped serving or never served, the change named, its revert waiting), and the daily `serve_rank_lost`, `bid_floor`, `tis_cap_low`, `tis_target_high`, `phrase_wrong_intent`, `results_zero`, `rebuild_drop`, `shared_negatives_missing`, `qs_systemic`, `bid_above_estimate`. Empty when the finding has no code of its own: the `kind` says it. za-212: `lp_seen_geo_block`, `lp_seen_cookie_wall`, `lp_seen_language` and `lp_seen_price` are the page as the searcher in a targeted market sees it, with `figures.named_markets` (`country/device/language`), `market_count`, `ad_price`, `page_price` and `wall_says`."},"detector":{"type":"string","description":"The detector that found it."},"status":{"type":"string","enum":["open","applied"]},"suggested":{"type":"boolean","description":"The change a step would have made with automatic changes on."},"can_apply":{"type":"boolean","description":"The one click (`apply`) is offered."},"automatic":{"type":"boolean","description":"An automatic change the audit made."},"figures":{"type":"object","additionalProperties":true,"description":"The finding's numbers: e.g. `campaign`, `lost_budget_pct`, `lost_rank_pct`, `not_made` (ZA323-FU: why a change a person applied was not made, on the card that is open again: `class_off`, `stopped`, `learning` or `refused`), `impression_share_pct`, `clicks`, `extra_clicks` (a week, an estimate), `needed_micros`, `donor`, `move_micros`, `keywords`, `below_landing_page`, `below_ad_relevance`, `below_expected_ctr`, `fix`, `named_keywords`, `pages`; a dead campaign (`suggest_dead_campaign` / `dead_campaign`, za-218): `cost_micros`, `clicks`, `days`; paused-ad clutter (`suggest_paused_clutter` / `paused_clutter`, za-170): `campaign`, `ad_group`, `paused_ads`, `kept_ads`, `days`, `examples`; the month's run rate (`run_rate_warning`, za-220, from 90% of the ceiling): `projected_micros`, `ceiling_micros`, `share_pct`, `over`, `trim_campaigns` (the campaigns the trim cuts first, in its order), and the za-169 pacing verdict: `pacing` (`inside` | `trim` | `hold`), `trim_total_micros` (what the trim takes off the month), `landing_micros` (where the month then lands), `short_micros` (what no safe trim can cover) and `raises_held` (true when no budget is raised until the month fits); an intent cluster (`suggest_cluster_negative` / `cluster_negative`, za-223; `suggest_cluster_narrow` when the word alone would block a keyword or a converting search, and `cluster_negative_auto` when the audit blocked clear waste by itself, WASTEFIX docs/1006 §36.10a): `term` (the shared word), `match` (`PHRASE` for the word, `NARROW` for the searches themselves), `negatives` (the `[text, match]` pairs Apply adds), `covers` (the searches they block), `terms_count`, `examples`, `clicks`, `cost_micros`, `currency`; a search for a rival's brand (`suggest_brand_nav_elsewhere` / `brand_nav_elsewhere`: outside the competitor campaign, the brand as a PHRASE negative there; `suggest_brand_nav_bare` / `brand_nav_bare`: a bare or navigational brand search inside it, as an EXACT negative; za-114, docs/1006 §76): `brand`, `term`, `match`, `form` (`elsewhere`/`bare`), `terms_count`, `examples`, `clicks`, `cost_micros` (the 30-day spend the block frees); a free-host search Google credited with a conversion, which is not value (`suggest_free_seeker_negative` / `free_seeker_negative` / `free_seeker_pack_negative`, za-167): `term`, `match`, `conversions_milli`, `value_micros`, `clicks`, `cost_micros`, `vertical`, `pack_count`, `examples` (the first negatives of the vertical's free-seeker pack), `pack_of` on a pack row; a paused keyword that converted (`suggest_reenable_keyword` / `keyword_reenabled`, za-222): `keyword`, `conversions_milli`, `clicks`, `cost_micros`, `days`; a keyword that sells another product than its campaign (`wrong_product`, ADCOPY1): `keyword`, `ad_group`, `product`, `other_product`, `words`, `evidence` (keywords of the other product that carry the words); Apply pauses it. A keyword in several ad groups that serve one language and place (`duplicate_keyword`, DUPEKW1): `keyword`, `match_type`, `keeper` (\"campaign > ad group\" kept by its 30-day figures), `groups` (how many ad groups hold it), `copy_groups` (the copies Apply pauses), `twin_groups` (other match types, named, never paused); `duplicate_keyword_last` (the copy is its group's only active keyword: never paused, no Apply) and `duplicate_keyword_paused` (a copy paused, with its Undo) carry `keyword`, `ad_group`, `keeper`, `groups`. A copy is paused only when its campaign's places sit inside the keeper's (DUPEGEO1); `duplicate_keyword_overlap` (two campaigns whose places only overlap: nothing paused, no Apply — exclude the shared places from the broader campaign or keep it) carries `keyword`, `campaign`, `other_campaign`, `broader`, `overlap` (English place names) and `overlap_codes` (ISO country codes, empty unless every shared place is a country). BUDGETMV1 (za-186) on a budget-limited campaign: `options` (items are `AdsBudgetMoveOption`), `donor_reason`, `blocked` (`no_return`, `learning`, `owner`, `shared_budget`, `no_donor`, `too_small` or empty), `increase_micros`, `headroom_micros` (what the ceiling allows a day; null = no ceiling), `extra_clicks_day`, `extra_conversions_day`."},"change_id":{"type":["string","null"],"format":"uuid"},"first_seen_at":{"type":"string","format":"date-time"},"last_seen_at":{"type":"string","format":"date-time"},"closed_at":{"type":["string","null"],"format":"date-time"}}},"AdsFindingApplyOption":{"type":"object","description":"BUDGETMV1 (za-186) — which option of a budget-move proposal to apply.","properties":{"option":{"type":"string","enum":["move","increase"],"default":"move"}}},"AdsFoundRival":{"type":"object","description":"za-73: a competitor this account's own searches (or a brand bidder Auction Insights named) point at, that nobody added. Added, it joins the competitor list: its ad groups are proposed and no ad may name it. Dismissed, it is never suggested again.","required":["name","status","source","impressions","clicks","examples"],"properties":{"name":{"type":"string"},"status":{"type":"string","enum":["new","added","dismissed"]},"source":{"type":"string","enum":["search","brand_bidder"]},"impressions":{"type":"integer"},"clicks":{"type":"integer"},"examples":{"type":"array","items":{"type":"string"},"description":"Up to three comparison searches that named it."},"first_seen_at":{"type":["string","null"],"format":"date-time"},"decided_at":{"type":["string","null"],"format":"date-time"}}},"AdsGeoHoldout":{"type":"object","description":"One geo hold-out (za-202, docs/1006 §80).","required":["id","connection_id","campaign_id","campaign","country","state","days","min_sales","baseline_days","baseline_sales","claimed_per_day","raise_change_id","pause_change_id","pause_status","started_at","ends_at","resumed_at","verdict","reason","result","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid"},"campaign_id":{"type":"string"},"campaign":{"type":"string"},"country":{"type":"string","description":"ISO 3166-1 alpha-2."},"state":{"type":"string","enum":["proposed","running","done","declined"]},"days":{"type":"integer"},"min_sales":{"type":"integer"},"baseline_days":{"type":"integer"},"baseline_sales":{"type":"integer"},"claimed_per_day":{"type":"number","description":"Google's own conversions per day in the country."},"raise_change_id":{"type":["string","null"],"format":"uuid"},"pause_change_id":{"type":["string","null"],"format":"uuid"},"pause_status":{"type":["string","null"]},"started_at":{"type":["string","null"],"format":"date-time"},"ends_at":{"type":["string","null"],"format":"date-time"},"resumed_at":{"type":["string","null"],"format":"date-time"},"verdict":{"type":"string","enum":["","lift","noLift","inconclusive"]},"reason":{"type":"string","enum":["","tooFewSales","underpowered","noSignal","endedEarly"]},"result":{"type":"object","description":"expected, observed, drop, noise, claimed, incrementality_pct (null when not measured); resume_error while a resume is retried.","additionalProperties":true},"created_at":{"type":"string","format":"date-time"}}},"AdsGeoHoldoutSettings":{"type":"object","description":"The customer's geo hold-out thresholds (za-202); Recommended where never set.","required":["mode","raise_pct","days","min_sales","recommended","bounds"],"properties":{"mode":{"type":"string","enum":["auto","suggest","off"]},"raise_pct":{"type":"integer","description":"A budget raise of at least this many percent gets a test first."},"days":{"type":"integer","description":"Days one country is held out."},"min_sales":{"type":"integer","description":"First-party sales needed in the baseline."},"recommended":{"type":"object","required":["mode","raise_pct","days","min_sales"],"properties":{"mode":{"type":"string","enum":["auto","suggest","off"]},"raise_pct":{"type":"integer"},"days":{"type":"integer"},"min_sales":{"type":"integer"}}},"bounds":{"type":"object","additionalProperties":{"type":"object","required":["min","max"],"properties":{"min":{"type":"integer"},"max":{"type":"integer"}}}}}},"AdsGoogleChange":{"type":"object","required":["id","changed_at","actor","client_type","resource_type","resource_name","operation","changed_fields","old","new","action_class","verdict","reasons","undoable","undo"],"properties":{"id":{"type":"string","format":"uuid"},"changed_at":{"type":"string","format":"date-time"},"actor":{"type":"string","enum":["auto_apply","recommendation","google"]},"client_type":{"type":"string"},"resource_type":{"type":"string"},"resource_name":{"type":"string"},"operation":{"type":"string","enum":["CREATE","UPDATE","REMOVE"]},"changed_fields":{"type":"array","items":{"type":"string"}},"old":{"type":"object","additionalProperties":true},"new":{"type":"object","additionalProperties":true},"action_class":{"type":"string"},"verdict":{"type":"string","enum":["within_rules","risky","needs_approval","breaks_rule"]},"reasons":{"type":"array","items":{"type":"string"}},"undoable":{"type":"boolean"},"undo":{"oneOf":[{"type":"null"},{"type":"object","required":["change_id","status"],"properties":{"change_id":{"type":"string","format":"uuid"},"status":{"type":"string"}}}]}}},"AdsGoogleChanges":{"type":"object","required":["items","counts","auto_apply"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AdsGoogleChange"}},"counts":{"type":"object","description":"Rows per verdict.","additionalProperties":{"type":"integer"}},"auto_apply":{"type":"object","required":["types"],"properties":{"read_at":{"type":["string","null"],"format":"date-time"},"types":{"type":"array","items":{"type":"object","required":["type","status","resource_name","risky"],"properties":{"type":{"type":"string"},"status":{"type":"string","description":"`ENABLED` or `PAUSED`."},"resource_name":{"type":"string"},"risky":{"type":"boolean"}}}}}}}},"AdsGoogleSays":{"type":"object","description":"za-334 — one of Google's own `ad_group_ad.action_items` for the ad (\"A list of recommendations to improve the ad strength\", Google Ads API v25), as a code the dashboard says in every language; `text` is Google's English wording, verbatim (`googleOther` shows it as written).","required":["code","text"],"properties":{"code":{"type":"string","enum":["googleUniqueOrUnpin","googleKeywordsInHeadlines","googleKeywordsInDescriptions","googleSitelinks","googleMoreHeadlines","googleMoreDescriptions","googleOther"]},"text":{"type":"string"},"have":{"type":"integer","description":"`googleSitelinks`: how many more Google asks for."}}},"AdsGrantAccount":{"type":"object","required":["customer_id","login_customer_id","name","manager","currency","status","connected"],"properties":{"customer_id":{"type":"string"},"login_customer_id":{"type":"string"},"name":{"type":"string"},"manager":{"type":"boolean"},"currency":{"type":"string"},"status":{"type":"string"},"connected":{"type":"boolean"},"connected_org_id":{"type":"string","description":"za-52: the organisation (this one or one of its client organisations) the account is connected under; \"\" when it is not connected."},"error":{"type":"string","description":"Why Google would not list this account's details."},"business_id":{"type":"string","description":"METABUILD (Meta, `business_management` granted): the Meta business portfolio the ad account sits in; the picker groups accounts under it. Absent otherwise."},"business_name":{"type":"string","description":"METABUILD — the business portfolio's name."},"parent_id":{"type":"string","description":"Google only (za-52): the manager account this account sits under (\"\" for one the person reaches directly)."},"parent_name":{"type":"string","description":"Google only (za-52): that manager's name."},"sandbox":{"type":"boolean","description":"X Ads only (XADS1): a SANDBOX account (`ads-api-sandbox`), which runs no ads and spends nothing. Its `customer_id` is `sbx-<id>`."},"timezone":{"type":"string","description":"ChatGPT Ads only (za-318): the account's IANA time zone."},"review_status":{"type":"string","description":"ChatGPT Ads only (za-318): OpenAI's brand review of the account (`in_review`, `rejected`, `approved`); an account serves only once it is `approved`."}}},"AdsGrantRevokeOutcome":{"type":"object","description":"za-97: what Disconnect did with the person's grant at the network (docs/1006 §Connect).","required":["network","state","reason","remove_url"],"properties":{"network":{"type":"string","description":"The platform (`google`, `microsoft`, `meta`, `x`, `pinterest`)."},"state":{"type":"string","enum":["revoked","already_invalid","retrying","kept"]},"reason":{"type":"string","enum":["revoke","shared","unsupported","unconfirmed"]},"remove_url":{"type":"string","description":"The network's own page where the person removes Zinn® Ads themselves (\"\" when unknown)."}}},"AdsGrowPlan":{"type":"object","required":["week","generated_at","data","calendar"],"properties":{"week":{"type":"string","format":"date"},"generated_at":{"type":"string","format":"date-time","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsGrowSuggestion"}},"calendar":{"type":"array","items":{"type":"object","required":["on","kind","in_days"],"properties":{"on":{"type":"string","format":"date"},"kind":{"type":"string","enum":["peak","copy_refresh","structure_review","review"]},"in_days":{"type":"integer"},"peak":{"type":"string","enum":["new_year","back_to_work","black_friday","cyber_monday","year_end"]},"review_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"connection_id":{"type":"string","format":"uuid"}}}}}},"AdsGrowSuggestion":{"type":"object","description":"One weekly \"Suggestion to grow\" (za-85). `detail` depends on `kind`; money in integer micros with `currency`.","required":["id","connection_id","week","kind","key","rank","detail","status","decided_by","decided_at"],"properties":{"id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid"},"week":{"type":"string","format":"date","description":"The Monday of the suggestion's week."},"kind":{"type":"string","enum":["scale_test","country","competitor","experiment"]},"key":{"type":"string"},"rank":{"type":"integer"},"detail":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["open","done","dismissed","superseded"]},"decided_by":{"type":"string"},"decided_at":{"type":"string","format":"date-time","nullable":true}}},"AdsHistoryImport":{"type":"object","description":"One history import (za-159, docs/1006 §80). Money in integer minor units of `currency`; ad-network costs in micros.","required":["id","connection_id","source_connection_id","revenue_source","window_start","window_end","currency","thresholds","months_read","months_total","status","error","evidence","seeds","created_at","finished_at"],"properties":{"id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid"},"source_connection_id":{"type":["string","null"],"format":"uuid"},"revenue_source":{"type":"string","enum":["first_party","csv","none"]},"window_start":{"type":"string","format":"date"},"window_end":{"type":"string","format":"date"},"currency":{"type":"string"},"thresholds":{"$ref":"#/components/schemas/AdsHistoryThresholds"},"months_read":{"type":"integer"},"months_total":{"type":"integer"},"status":{"type":"string","enum":["queued","reading","done","failed"]},"error":{"type":"string","description":"Why a failed import stopped, e.g. `sourceNotYours`, `notInGoodStanding`, `sourceNeedsReconnect`."},"evidence":{"type":"object","additionalProperties":true},"seeds":{"type":"array","items":{"$ref":"#/components/schemas/AdsHistorySeed"}},"created_at":{"type":"string","format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"}}},"AdsHistorySeed":{"type":"object","description":"One seeded starting value with its evidence (za-159).","required":["key","kind","value","evidence"],"properties":{"key":{"type":"string","enum":["target_cpa","target_roas","roas_target_pct","start_countries","exclude_countries","excluded_countries","device_modifiers"]},"kind":{"type":"string","enum":["account","setting"],"description":"`account` = pending changes in the approval queue; `setting` = a Zinn® Ads setting a person accepts."},"value":{"type":"object","additionalProperties":true},"evidence":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["proposed","nothingToChange","noCampaigns"]},"change_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"accepted_at":{"type":"string","format":"date-time"},"accepted_by":{"type":"string"},"added":{"type":"array","items":{"type":"string"},"description":"`start_countries`, once accepted: the countries added to the markets."},"dropped":{"type":"array","items":{"type":"string"},"description":"`start_countries`, once accepted: the markets the person ticked to remove."}}},"AdsHistoryThresholds":{"type":"object","description":"History-import thresholds (za-159, docs/1006 §80); the Recommended defaults when returned as `recommended`.","properties":{"window_days":{"type":"integer","minimum":30,"maximum":3650},"min_customers_total":{"type":"integer","minimum":1,"maximum":1000},"min_clicks_country":{"type":"integer","minimum":1,"maximum":100000},"min_customers_country":{"type":"integer","minimum":1,"maximum":1000},"start_revenue_share_pct":{"type":"integer","minimum":10,"maximum":100},"max_start_countries":{"type":"integer","minimum":1,"maximum":8},"exclude_min_spend_pct_of_cpa":{"type":"integer","minimum":10,"maximum":1000},"device_min_clicks":{"type":"integer","minimum":1,"maximum":1000000},"device_modifier_min_pct":{"type":"integer","minimum":-90,"maximum":0},"device_modifier_max_pct":{"type":"integer","minimum":0,"maximum":300},"device_modifier_min_change_pct":{"type":"integer","minimum":1,"maximum":100},"revenue_sources":{"type":"array","maxItems":50,"items":{"type":"string","maxLength":64}}}},"AdsHistoryThresholdsInput":{"description":"Any of the thresholds (the rest keep their Recommended value), or `{reset: true}` for the defaults.","allOf":[{"$ref":"#/components/schemas/AdsHistoryThresholds"},{"type":"object","properties":{"reset":{"type":"boolean"}}}]},"AdsImportedAccount":{"type":"object","description":"za-262: a connected Google Ads account's structure as read (read only). Money is integer micros of `currency`, never a float; a shared budget is counted once in `enabled_daily_budget_micros`.","required":["account_name","currency","optimization_score_pct","totals","campaigns","conversion_actions","read_at"],"properties":{"account_name":{"type":"string"},"currency":{"type":"string"},"optimization_score_pct":{"type":["integer","null"]},"read_at":{"type":"string","format":"date-time"},"totals":{"type":"object","required":["campaigns","campaigns_enabled","ad_groups","keywords","ads","negatives","conversion_actions","primary_conversion_actions","shared_budgets","learning","enabled_daily_budget_micros"],"properties":{"campaigns":{"type":"integer"},"campaigns_enabled":{"type":"integer"},"ad_groups":{"type":"integer"},"keywords":{"type":"integer"},"ads":{"type":"integer"},"negatives":{"type":"integer"},"conversion_actions":{"type":"integer"},"primary_conversion_actions":{"type":"integer"},"shared_budgets":{"type":"integer"},"learning":{"type":"integer"},"enabled_daily_budget_micros":{"type":"integer","format":"int64"}}},"campaigns":{"type":"array","items":{"type":"object","required":["id","name","status","channel","bid_strategy","bid_strategy_status","learning","portfolio","target_cpa_micros","target_roas_pct","daily_budget_micros","budget_shared","budget_shared_by","budget_id","ad_groups","keywords","keywords_by_match","ad_group_negatives","ads","ads_enabled","campaign_negatives","location_targets","location_exclusions"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"channel":{"type":"string"},"bid_strategy":{"type":"string"},"bid_strategy_status":{"type":"string"},"learning":{"type":"boolean"},"portfolio":{"type":"boolean"},"target_cpa_micros":{"type":["integer","null"],"format":"int64"},"target_roas_pct":{"type":["integer","null"]},"daily_budget_micros":{"type":"integer","format":"int64"},"budget_shared":{"type":"boolean"},"budget_shared_by":{"type":"integer"},"budget_id":{"type":"string","description":"The budget's resource name (a shared budget is counted once by it)."},"ad_groups":{"type":"integer"},"keywords":{"type":"integer"},"keywords_by_match":{"type":"object","additionalProperties":{"type":"integer"}},"ad_group_negatives":{"type":"integer"},"ads":{"type":"integer"},"ads_enabled":{"type":"integer"},"campaign_negatives":{"type":"integer"},"location_targets":{"type":"integer"},"location_exclusions":{"type":"integer"}}}},"conversion_actions":{"type":"array","items":{"type":"object","required":["id","name","category","status","primary","counting"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"status":{"type":"string"},"primary":{"type":"boolean"},"counting":{"type":"string"}}}}}},"AdsImportedHistory":{"type":"object","description":"za-263: the connected account's own history read back on Temporal (month by month, resumable, deferred to Google's reset when the day's op budget is spent). Money in integer micros; conversions in thousandths.","required":["state","window_start","window_end","months_read","months_total","first_day","days_with_data","cost_micros","clicks","conversions_milli","value_micros","error"],"properties":{"state":{"type":"string","enum":["reading","done","paused"]},"window_start":{"type":["string","null"],"format":"date"},"window_end":{"type":["string","null"],"format":"date"},"months_read":{"type":"integer"},"months_total":{"type":"integer"},"first_day":{"type":["string","null"],"format":"date"},"days_with_data":{"type":"integer"},"cost_micros":{"type":"integer","format":"int64"},"clicks":{"type":"integer","format":"int64"},"conversions_milli":{"type":"integer","format":"int64","description":"RECORDED conversions x 1000 (MSALLCONV-FU2): every conversion the network recorded, biddable goal or not."},"value_micros":{"type":"integer","format":"int64"},"error":{"type":["string","null"]}}},"AdsImportedPlan":{"type":"object","description":"za-265: the imported account's plan from its own history. `state` is `ok`, `notEnoughHistory` or `noConversions` (no waste is judged on a thin or conversion-less history — `decided_by` carries the counts and the bars that decided it) or `paused` (the org is not in good standing). Money in integer micros; conversions in thousandths.","required":["state","built_at"],"properties":{"state":{"type":"string","enum":["ok","notEnoughHistory","noConversions","paused"]},"built_at":{"type":"string","format":"date-time"},"decided_by":{"type":"object","properties":{"days_with_data":{"type":"integer"},"clicks":{"type":"integer","format":"int64"},"cost_micros":{"type":"integer","format":"int64"},"conversions_milli":{"type":"integer","format":"int64"},"min_days":{"type":"integer"},"min_clicks":{"type":"integer"},"account_cpa_micros":{"type":"integer","format":"int64"}}},"keep":{"type":"object","properties":{"campaigns":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/AdsImportedPlanFigures"}],"type":"object","properties":{"campaign_id":{"type":"string"},"name":{"type":"string"}}}},"keywords":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/AdsImportedPlanFigures"}],"type":"object","properties":{"resource":{"type":"string"},"keyword":{"type":"string"},"campaign":{"type":"string"}}}},"countries":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/AdsImportedPlanFigures"}],"type":"object","properties":{"country":{"type":"string"}}}}}},"waste":{"type":"array","items":{"$ref":"#/components/schemas/AdsImportedPlanItem"}},"structural":{"type":"array","items":{"$ref":"#/components/schemas/AdsImportedPlanItem"}}}},"AdsImportedPlanFigures":{"type":"object","properties":{"cost_micros":{"type":"integer","format":"int64"},"clicks":{"type":"integer","format":"int64"},"conversions_milli":{"type":"integer","format":"int64"}}},"AdsImportedPlanItem":{"type":"object","description":"One plan item. `kind`: `searchNegative` (an EXACT negative for `term` on `campaigns`), `keywordPause` (`keyword`, `resource`), `countryExclude` (`country`, ISO 3166-1 alpha-2, with `expected_conversions` at the account's own rate), `bidForConversions` (`campaign_id`, `campaign`, `from`, `conversions_30d`, `need` — the bid-ladder rung), `sharedBudget` (`budget`, `campaigns` — a person's step) or `noConversionAction`. A write carries the pending change it queued (`change_id`, `change_status`). za-329: a `bidForConversions` item is never written from the plan (`via: ladder`): the bid ladder proposes the switch once its data gate and its conversion-health gate pass, and `health` lists the checks holding it.","required":["kind"],"properties":{"kind":{"type":"string","enum":["searchNegative","keywordPause","countryExclude","bidForConversions","sharedBudget","noConversionAction"]},"term":{"type":"string"},"keyword":{"type":"string"},"resource":{"type":"string"},"country":{"type":"string"},"campaign":{"type":"string"},"campaign_id":{"type":"string"},"campaigns":{"type":"array","items":{"type":"string"}},"budget":{"type":"string"},"from":{"type":"string"},"conversions_30d":{"type":"integer"},"need":{"type":"integer"},"expected_conversions":{"type":"number"},"cost_micros":{"type":"integer","format":"int64"},"clicks":{"type":"integer","format":"int64"},"conversions_milli":{"type":"integer","format":"int64"},"change_id":{"type":"string","format":"uuid"},"change_status":{"type":"string"},"via":{"type":"string","enum":["ladder"],"description":"za-329: the producer that proposes this step (the bid ladder, behind its gates)."},"health":{"type":"array","items":{"$ref":"#/components/schemas/AdsSmartBidHealthItem"},"description":"za-329: the conversion-health checks holding the bid ladder's switch (empty: none, or not judged yet)."}}},"AdsInsightReading":{"type":["object","null"],"description":"One reading of an account, or null before its first audit. `figures` depends on `kind` (docs/1006 §30): money is integer minor units (`*_minor`) or micros (`*_micros`) of the account's currency, never a float; missed clicks and conversions are estimates.","required":["kind","state","day","updated_at","figures"],"properties":{"kind":{"type":"string","enum":["pacing","tracking","missed","ladder","share"]},"state":{"type":"string","description":"pacing: `on_track` · `over` · `under` · `no_target` · `no_spend` · `unreadable`; tracking: `ok` · `broken` · `quiet` (no action has the history to judge yet) · `no_actions` · `unreadable`; missed: `ok` · `missing` · `unreadable`. `unreadable` is never a pass. ladder: `ok` · `alert` (a stage's signal stopped, or went silent while the stage below kept coming) · `unproven` (no stage-1 signal recorded) · `no_campaigns` · `unreadable`. share (ZWASTE3, za-179): `split` (a multi-country campaign lets one country crowd out a targeted one) · `lost` (a new campaign loses impressions from day 3) · `ok` · `noData` (nothing read — never a pass)."},"day":{"type":"string","format":"date"},"updated_at":{"type":"string","format":"date-time"},"figures":{"type":"object","additionalProperties":true,"description":"pacing: `spent_minor`, `forecast_minor`, `target_minor`, `target_source` (`target`/`budgets`/`ceiling`), `off_by_pct`, `deviation_pct`, `daily_rate_minor`, `needed_daily_minor`, `days_left`, `monthly_ceiling_minor`, `note` (`notBudget`), `corrections` [{campaign, campaign_id, budget_resource, from_micros, to_micros, outcome (applied/queued/recent/weekly/undone/pending/ceiling/refused:*/failed), change_id}]; tracking: `judged`, `actions`, `broken` [{action, name, type, kind (tag/upload/ga4/call/app/other), primary, code (stopped/dropped), expected, recorded, recent_clicks, window_start, window_end, last_seen}]; missed: `days`, `count`, `total_clicks`, `total_conversions`, `total_value`, `total_budget_cost_micros`, `campaigns` [{campaign_id, campaign, impressions, clicks, conversions, share, lost_budget, lost_rank, missed_clicks_budget, missed_clicks_rank, missed_conversions_budget, missed_conversions_rank, missed_value, budget_cost_micros, budget_micros, cap_micros, fix (raiseBudget/raiseCap/improveRank), flag_id}]; ladder (BUILDL2, docs/1006 §34): `business_type`, `currency`, `at_risk` [campaign_id], `chosen`, `wait_days`, `window_start`, `window_end`, `stages` [{stage, signal (signup/activation/paid), truth (proven/silent/missing/broken), alert, recorded, per_1000_clicks, actions [{resource, name, category, recorded, broken}]}], `unassigned` [{resource, name, category}], `counts` {\"1\",\"2\",\"3\"}, `campaigns` [{campaign_id, campaign, stage, judged_on, age_days, clicks, cost_micros, signals {signup, activation, paid}, cost_per_signal_micros, paid_value, value_bidding, next {stage, reason (signalNotProven/tooEarly/notEnoughData), truth, need_days, need_signals, signal, need_clicks} | null, allowed, not_allowed, at_risk {signal, signals, deeper, deeper_recorded, days, cost_micros, truth, recommend (bidOnDeeper/recordDeeper), actions} | null}]; share (ZWASTE3, za-179, docs/1006 §36): `window_days`, `window_start`, `window_end`, `currency`, `splits` [{campaign_id, campaign, dominant, dominant_share, starved [{country, share, impressions}], impressions, lost_budget, lost_rank, fix (splitCountry)}], `new_lost` [{campaign_id, campaign, age_days, lost_budget, lost_rank, fix (raiseBudget/improveRank)}], `cheap` (ZWASTE5, za-216: Maximize clicks buying the cheapest countries; state `cheap` when no split) [{campaign_id, campaign, countries [{country, click_share, cpc_micros, cost_micros}], click_share, cost_micros, other_cpc_micros, clicks, fix (excludeOrBidOnConversions)}]; campaign feed (za-40, za-54): `currency`, `since`, `until`, `spend_micros`, `campaigns`, and (za-331) `placements` — the placement review read with the same reading, shaped as `AdsAuditRun.summary.placements` (LinkedIn Audience Network, Meta placements; every finding a person's call, nothing sent)."}}},"AdsInsights":{"type":"object","required":["connection_id","currency","pacing","tracking","missed","ladder"],"properties":{"connection_id":{"type":"string","format":"uuid"},"currency":{"type":"string"},"pacing":{"$ref":"#/components/schemas/AdsInsightReading"},"tracking":{"$ref":"#/components/schemas/AdsInsightReading"},"missed":{"$ref":"#/components/schemas/AdsInsightReading"},"ladder":{"$ref":"#/components/schemas/AdsInsightReading"},"share":{"description":"ZWASTE3 (za-179) country share + new-campaign lost share; null until the first audit.","oneOf":[{"$ref":"#/components/schemas/AdsInsightReading"},{"type":"null"}]}}},"AdsLadderSignals":{"type":"object","description":"BUILDL2 (za-153) — the customer's own choice of signal per stage: `\"1\"` (sign-up / lead), `\"2\"` (activation / qualified), `\"3\"` (paid) → conversion action resource names (`customers/<id>/conversionActions/<id>`), at most 50 each, an action on one stage only; a stage left out follows the business type. `422 badLadderSetting` otherwise.","propertyNames":{"enum":["1","2","3"]},"additionalProperties":{"type":"array","maxItems":50,"items":{"type":"string","maxLength":80}}},"AdsLandingPage":{"type":"object","description":"One ad final URL's last daily check (LPDIAG2, docs/1006 §41).","required":["url","checked","status","ad_groups","problems"],"properties":{"url":{"type":"string"},"checked":{"type":"boolean","description":"false — the page could not be read that day."},"status":{"type":"integer","description":"The HTTP status after redirects (0 = not read)."},"final_url":{"type":"string"},"lang":{"type":"string","description":"The page's <html lang>."},"h1":{"type":"string"},"cta_above_fold":{"type":"boolean","nullable":true},"lcp_ms":{"type":"integer","nullable":true,"description":"Mobile largest contentful paint."},"cls_milli":{"type":"integer","nullable":true,"description":"Mobile layout shift x 1000."},"google_below":{"type":"integer","description":"Keywords Google rates BELOW_AVERAGE for the landing page here (its own rating, which lags a fixed page)."},"ad_groups":{"type":"array","items":{"type":"string"}},"problems":{"type":"array","description":"The `why` of each finding on this page.","items":{"type":"string","enum":["lp_broken","lp_redirect","lp_language","lp_competitor","lp_intent","lp_cta_fold","lp_cta_wrong","lp_slow","lp_qs_below"]}}}},"AdsLaunchBrief":{"type":"object","required":["id","org_id","offering_id","build_id","monthly_budget_minor","currency","split"],"properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"offering_id":{"type":"string","format":"uuid"},"offering":{"$ref":"#/components/schemas/AdsOffering"},"build_id":{"type":"string","format":"uuid"},"build_status":{"type":"string"},"domain":{"type":"string"},"name":{"type":"string"},"monthly_budget_minor":{"type":"integer"},"currency":{"type":"string"},"objective":{"type":"string"},"split":{"type":"object","additionalProperties":{"type":"integer"}},"created_at":{"type":"string","format":"date-time"},"plans":{"type":"array","items":{"$ref":"#/components/schemas/AdsBriefPlan"}},"can_add":{"type":"array","items":{"type":"string"}},"unlaunch":{"$ref":"#/components/schemas/AdsBriefUnlaunch"},"networks":{"type":"array","items":{"type":"object","properties":{"network":{"type":"string"},"status":{"type":"string"},"share_pct":{"type":"integer"}}}}}},"AdsLinkedinCampaign":{"type":"object","description":"One LinkedIn campaign (LIFULL). Money is micros of `currency` (§2.8).","required":["id","name","status","serving","currency","daily_budget_micros","total_budget_micros","unit_cost_micros","cost_type","spend_micros"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","description":"LinkedIn's campaign status (ACTIVE, PAUSED, DRAFT, ARCHIVED, …)."},"serving":{"type":"boolean","description":"Serving now: ACTIVE, inside its run schedule and on no serving hold."},"currency":{"type":"string","description":"ISO 4217 code."},"daily_budget_micros":{"type":["integer","null"],"format":"int64"},"total_budget_micros":{"type":["integer","null"],"format":"int64"},"unit_cost_micros":{"type":["integer","null"],"format":"int64","description":"The bid."},"cost_type":{"type":"string","description":"CPC, CPM, …"},"spend_micros":{"type":"integer","format":"int64","description":"Spend over the response's `days`."}}},"AdsMarketLanguage":{"type":"object","required":["country","language","ok","code","url","reach_via","offer"],"properties":{"country":{"type":"string"},"language":{"type":"string"},"ok":{"type":"boolean"},"code":{"type":"string","enum":["","languageNotOnSite","languageNotTargetable"]},"url":{"type":"string","description":"Where this market's ads land (its language's page)."},"reach_via":{"type":"array","description":"Languages Google serves that reach the country instead (za-113).","items":{"type":"string"}},"offer":{"type":["object","null"],"description":"The Tranzly offer for a language the site has no version in (za-108).","properties":{"language":{"type":"string"},"product":{"type":"string","enum":["tranzly"]},"url":{"type":"string"}}}}},"AdsMatchingPage":{"type":"object","description":"One matching landing page for one ad group on a site hosted with us (za-N6, docs/1006 §94).","required":["id","ad_group","ad_group_name","site_id","domain","slug","language","languages","keywords","rival","rival_name","facts","content","dropped","state","error","page_url","url_change_id","approved_at","published_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"ad_group":{"type":"string","description":"customers/<cid>/adGroups/<id>"},"ad_group_name":{"type":"string"},"site_id":{"type":"string","format":"uuid"},"domain":{"type":"string"},"slug":{"type":"string"},"language":{"type":"string","description":"The site's own language; the page is written in it."},"languages":{"type":"array","items":{"type":"string"},"description":"The other languages it is translated into."},"keywords":{"type":"array","items":{"type":"string"}},"rival":{"type":"string","description":"za-109 (docs/1006.d/features/za-109-alternative-pages.md): the competitor this ad group is named after, from the org's competitor registry; \"\" for a plain matching page. A rival's page is an \"alternative to <rival>\" page: its headline names the rival in text only, and no line compares."},"rival_name":{"type":"string","description":"The rival's name as written on the page (\"\" for a plain page)."},"facts":{"type":"array","description":"za-109: what the rival's OWN public page says, word for word, with that page's address and the date it was read. Empty when we do not know the rival's address (never guessed).","items":{"type":"object","required":["quote","source_url","read_on","language"],"properties":{"quote":{"type":"string"},"source_url":{"type":"string","format":"uri"},"read_on":{"type":"string","format":"date"},"language":{"type":"string"}}}},"content":{"type":"object","description":"Empty until written. Every line restates the site's own page.","properties":{"headline":{"type":"string"},"intro":{"type":"string"},"points":{"type":"array","items":{"type":"string"}},"cta_label":{"type":"string"},"source_url":{"type":"string"}}},"dropped":{"type":"integer","description":"Lines the writer offered that the site's own pages did not back."},"state":{"type":"string","enum":["candidate","generating","ready","publishing","live","unpublishing","unpublished","discarded"]},"error":{"type":"string","description":"The last problem's code, e.g. landingNotBacked, landingNoText, landingNotServing."},"page_url":{"type":"string"},"url_change_id":{"type":"string","format":"uuid","nullable":true},"approved_at":{"type":"string","format":"date-time","nullable":true,"description":"When the page was last approved. Once set, its files may be on the site (a switch that was refused, a write that failed half-way), so it is unpublished, never discarded."},"published_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time"}}},"AdsMeasurementHealth":{"type":"object","description":"ADSOPT (za-253, docs/1006 §ADSOPT) — what the audit's measurement-health step stored.","additionalProperties":false,"required":["connection_id","checked_at","score_bp","trend","campaigns","goals","uploads","automation"],"properties":{"connection_id":{"type":"string","format":"uuid"},"checked_at":{"type":["string","null"],"format":"date-time"},"score_bp":{"type":["integer","null"],"minimum":0,"maximum":10000},"trend":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["day","score_bp"],"properties":{"day":{"type":"string","format":"date"},"score_bp":{"type":"integer","minimum":0,"maximum":10000}}}},"campaigns":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["campaign_id","campaign","score_bp"],"properties":{"campaign_id":{"type":"string"},"campaign":{"type":"string"},"score_bp":{"type":"integer","minimum":0,"maximum":10000}}}},"goals":{"type":"object","additionalProperties":false,"required":["missing","suggested","open","switched_off"],"properties":{"missing":{"type":"integer","minimum":0},"suggested":{"type":"integer","minimum":0},"open":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","why","campaign","campaign_id","goal","goals","since"],"properties":{"id":{"type":"string","format":"uuid"},"why":{"type":"string","enum":["goal_missing","suggest_goal_no_primary"]},"campaign":{"type":"string"},"campaign_id":{"type":"string"},"goal":{"type":"string"},"goals":{"type":"array","items":{"type":"string"}},"since":{"type":"string","format":"date-time"}}}},"switched_off":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","campaign","goal","at"],"properties":{"id":{"type":"string","format":"uuid"},"campaign":{"type":"string"},"goal":{"type":"string"},"at":{"type":["string","null"],"format":"date-time"}}}}}},"uploads":{"type":"object","additionalProperties":false,"required":["failing","data"],"properties":{"failing":{"type":"integer","minimum":0},"data":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","action","failed","total","error","last_upload","since"],"properties":{"id":{"type":"string","format":"uuid"},"action":{"type":"string"},"failed":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0},"error":{"type":"string"},"last_upload":{"type":"string"},"since":{"type":"string","format":"date-time"}}}}}},"automation":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["campaign_id","campaign","switches"],"properties":{"campaign_id":{"type":"string"},"campaign":{"type":"string"},"switches":{"type":"object","additionalProperties":{"type":"boolean"}}}}}}},"AdsMerchantFeed":{"type":"object","description":"za-188 (docs/1006 §80): a connection's Shopping feed audit. `result` is the last daily audit (empty before the first): `counts` (whole, never capped), `threshold` (`recommended_micros`, `customer_micros`, `used_micros`, `source`), `issues`, `mismatches`, `out_of_stock`, `waste` (each at most 50 rows, most spend first), `stock_pause_link`, `disapprovals_reported` (false on Microsoft — its Content API reports no serving status), `merchant_api` (`off` · `read` · `refused` · `truncated`). Money in micros of the account's currency.","required":["connection_id","platform","supported","mode","waste_threshold_micros","store_id","last_run_at","result","currency","merchant_scope_asked"],"properties":{"connection_id":{"type":"string","format":"uuid"},"platform":{"type":"string"},"supported":{"type":"boolean"},"mode":{"type":"string","enum":["off","suggest"]},"waste_threshold_micros":{"type":["integer","null"],"format":"int64"},"store_id":{"type":"string"},"last_run_at":{"type":["string","null"],"format":"date-time"},"result":{"type":"object","additionalProperties":true},"currency":{"type":"string"},"merchant_scope_asked":{"type":"boolean"}}},"AdsMetaAdset":{"type":"object","description":"One Meta ad set (METABUILD). Money is micros of `currency` (§2.8).","required":["id","name","campaign_id","campaign","status","effective_status","daily_budget_micros","daily_budget_minor","lifetime_budget","spend_micros","currency"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"campaign_id":{"type":"string"},"campaign":{"type":"string"},"status":{"type":"string","description":"Meta's configured status (ACTIVE, PAUSED, …)."},"effective_status":{"type":"string"},"daily_budget_micros":{"type":["integer","null"],"format":"int64"},"daily_budget_minor":{"type":["integer","null"],"format":"int64","description":"The same budget in Meta's own units."},"lifetime_budget":{"type":"boolean"},"spend_micros":{"type":"integer","format":"int64"},"currency":{"type":"string"}}},"AdsMetaPage":{"type":"object","required":["page_id","name","link","picture_url","followers","fans"],"properties":{"page_id":{"type":"string"},"name":{"type":"string"},"link":{"type":"string","description":"The Page's https link, or empty."},"picture_url":{"type":"string"},"followers":{"type":"integer"},"fans":{"type":"integer"}}},"AdsMode":{"type":"string","description":"`off`, `approve` (a person approves first — the default) or `auto`.","enum":["off","approve","auto"]},"AdsModes":{"type":"object","description":"The mode per action class. A class the account never set reads `approve`, except `negatives`, which reads `auto`: the audit blocks clear waste (searches that spent the money of a sale or the account's clicks with no conversion, off-intent consumer searches and wasteful clusters whose negatives pass the collision guard) by itself, each with its 30-day Undo (owner 2026-10-30, WASTEFIX, docs/1006 §36.10a). A stored mode is kept.","required":["negatives","keywords","pauses","budgets","bids","exclusions","campaigns","ads","assets","audiences","conversions"],"properties":{"negatives":{"allOf":[{"$ref":"#/components/schemas/AdsMode"}],"description":"Negative keywords and negative keyword lists (UI1)."},"pauses":{"allOf":[{"$ref":"#/components/schemas/AdsMode"}],"description":"Pausing or re-enabling a campaign, ad group, ad or keyword (a status-only update, UI1)."},"bids":{"allOf":[{"$ref":"#/components/schemas/AdsMode"}],"description":"Bids and bidding — a CPC bid, a target CPA/ROAS, a bid strategy (UI1)."},"budgets":{"$ref":"#/components/schemas/AdsMode"},"campaigns":{"$ref":"#/components/schemas/AdsMode"},"keywords":{"$ref":"#/components/schemas/AdsMode"},"ads":{"$ref":"#/components/schemas/AdsMode"},"assets":{"$ref":"#/components/schemas/AdsMode"},"audiences":{"$ref":"#/components/schemas/AdsMode"},"conversions":{"$ref":"#/components/schemas/AdsMode"},"exclusions":{"allOf":[{"$ref":"#/components/schemas/AdsMode"}],"description":"The click shield's IP and placement exclusions (SHIELD2). Approve-first by default: each is an ad-account change with its 30-day Undo."}}},"AdsNarrativeFact":{"type":"object","description":"One fact a narrative cites. `kind`: `period`, `total`, `campaign`, `anomaly`, `changes`, `forecast`; `connection_id` is the account for a campaign fact, else empty.","required":["id","kind","connection_id","figures"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["period","total","campaign","anomaly","changes","forecast"]},"connection_id":{"type":"string"},"figures":{"type":"object","additionalProperties":{"type":"string"}}}},"AdsNetworkNotice":{"type":"object","required":["id","slug","platform","effective_on","source_url","title","summary","advice","detector","active"],"properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"platform":{"type":"string"},"effective_on":{"type":"string","format":"date"},"source_url":{"type":"string","format":"uri"},"title":{"type":"string"},"summary":{"type":"string"},"advice":{"type":"string"},"detector":{"type":"string"},"active":{"type":"boolean"}}},"AdsNextCountry":{"type":"object","description":"za-N10 (docs/1006 §NEXTCOUNTRY) — the next-country advisor.","required":["mode","mode_recommended","buying_only","thresholds","cadence_days","pending_change_id","reading"],"properties":{"mode":{"type":"string","enum":["suggest","off"]},"mode_recommended":{"type":"string"},"buying_only":{"type":"boolean"},"thresholds":{"type":"array","items":{"type":"object","required":["name","value","recommended","min","max"],"properties":{"name":{"type":"string","enum":["window_days","min_sales","min_signups"]},"value":{"type":["integer","null"],"description":"The customer's own value; null = the recommended one."},"recommended":{"type":"integer"},"min":{"type":"integer"},"max":{"type":"integer"}}}},"cadence_days":{"type":"integer"},"pending_change_id":{"type":["string","null"],"format":"uuid","description":"The waiting proposal in the change queue."},"reading":{"oneOf":[{"type":"null"},{"type":"object","required":["state","day","window_days","buying_only","basis","evidence_currency","account_currency","countries"],"properties":{"state":{"type":"string","enum":["judged","nothingNew","noFirstParty"]},"day":{"type":"string","format":"date"},"window_days":{"type":"integer"},"buying_only":{"type":"boolean"},"basis":{"type":"string","enum":["billing","product"]},"evidence_currency":{"type":"string","description":"Currency of `revenue_minor`."},"account_currency":{"type":"string","description":"Currency of `cpc_micros`."},"account_cpc_micros":{"type":"integer"},"core_campaign":{"type":"string"},"ad_language":{"type":"string"},"proposal":{"type":["object","null"],"properties":{"change_id":{"type":"string","format":"uuid"},"country":{"type":"string"},"campaign":{"type":"string"},"budget_micros":{"type":"integer"},"keywords":{"type":"integer"},"collisions_dropped":{"type":"integer"},"approve_only":{"type":"boolean"}}},"countries":{"type":"array","items":{"type":"object","required":["rank","country","sales","revenue_minor","signups","searches","cpc_micros","verdict","risks","outcome"],"properties":{"rank":{"type":"integer"},"country":{"type":"string"},"location":{"type":"integer"},"sales":{"type":"integer"},"revenue_minor":{"type":"integer"},"signups":{"type":"integer"},"searches":{"type":"integer","description":"Average monthly searches (Keyword Planner)."},"cpc_micros":{"type":"integer","description":"Expected cost per click (Keyword Planner)."},"verdict":{"type":"string","enum":["open","notBuying","fewSignals","excluded","noSearchVolume","noCoreKeywords"]},"risks":{"type":"array","items":{"type":"string","enum":["signupsOnly","thinEvidence","noSearchVolume","cpcAboveAccount","adsNotInLocalLanguage","noVatRateOnFile"]}},"tax":{"type":"object","properties":{"regime":{"type":"string","enum":["uk","eu_oss","outside"]},"rate_bps":{"type":"integer"}}},"outcome":{"type":"string"},"collisions":{"type":"array","items":{"type":"object","properties":{"keyword":{"type":"string"},"why":{"type":"string"}}}}}}}}}]}}},"AdsNoticeMatch":{"type":"object","required":["id","connection_id","notice","items","more","change_id","first_seen_at","acknowledged_at"],"properties":{"id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid"},"notice":{"$ref":"#/components/schemas/AdsNetworkNotice"},"items":{"type":"array","description":"At most 50; `more` counts the rest (§2.50).","items":{"type":"object","required":["kind","id","name","why"],"properties":{"kind":{"type":"string","enum":["campaign","adGroup"]},"id":{"type":"string"},"name":{"type":"string"},"why":{"type":"string","enum":["keepsMaxCpc","noMaxCpc","pausedRsa","noRsa"]}}}},"more":{"type":"integer"},"change_id":{"type":"string","format":"uuid","nullable":true,"description":"The pending safe fix","if any.":null},"first_seen_at":{"type":"string","format":"date-time"},"acknowledged_at":{"type":"string","format":"date-time","nullable":true}}},"AdsObjectiveTargets":{"type":"object","description":"A campaign objective and its targets (za-184, docs/1006 §43). Only the fields the objective uses are kept. Money is integer micros of the account's currency (§2.8).","required":["objective"],"properties":{"objective":{"type":"string","enum":["leads","revenue","profit","top_of_page","brand_defence","traffic","reach","none"]},"target_cpa_micros":{"type":"integer","format":"int64","minimum":0},"target_roas_pct":{"type":"integer","minimum":0,"description":"400 = a 4.00x return."},"margin_pct":{"type":"integer","minimum":0,"maximum":100},"share_pct":{"type":"integer","minimum":0,"maximum":100},"placement":{"type":"string","enum":["anywhere","top","absolute_top",""]},"max_cpc_micros":{"type":"integer","format":"int64","minimum":0,"description":"The max-CPC limit; never sent above 3x the campaign's own 30-day average cost per click."},"max_cpm_micros":{"type":"integer","format":"int64","minimum":0,"description":"Reach only (za-201): the most 1,000 people reached may cost; 0 is no limit."}}},"AdsOfferProfile":{"type":"object","description":"OFFERFIT — the automatic profile the audit read for one campaign.","required":["summary","sells","not_sells","rivals","edited"],"properties":{"summary":{"type":"string"},"sells":{"type":"array","items":{"type":"string"}},"not_sells":{"type":"array","items":{"type":"string"}},"rivals":{"type":"array","items":{"type":"string"}},"edited":{"type":"boolean"}}},"AdsOfferProfileEdit":{"type":"object","description":"OFFERFIT — a customer's own profile of what one campaign sells.","required":["sells"],"properties":{"summary":{"type":"string","maxLength":300},"sells":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string","maxLength":120}},"not_sells":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":120}},"rivals":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":120}}}},"AdsOffering":{"type":"object","required":["id","org_id","kind","name","tags","urls","domains","markets","archived","campaigns"],"properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"kind":{"$ref":"#/components/schemas/AdsOfferingKind"},"name":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"urls":{"type":"array","items":{"type":"string"}},"domains":{"type":"array","items":{"type":"string"}},"markets":{"type":"array","items":{"type":"object","additionalProperties":true}},"monthly_budget_minor":{"type":"integer","nullable":true},"currency":{"type":"string","nullable":true},"objective":{"type":"string"},"archived":{"type":"boolean"},"campaigns":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}},"AdsOfferingInput":{"type":"object","properties":{"org_id":{"type":"string","format":"uuid","description":"On create, which of the caller's organisations owns it (required when there are several)."},"archived":{"type":"boolean","description":"On update, archive (true) or restore (false) the offering."},"name":{"type":"string","maxLength":120},"kind":{"$ref":"#/components/schemas/AdsOfferingKind"},"tags":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":40}},"urls":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":500}},"markets":{"type":"array","items":{"type":"object","properties":{"country":{"type":"string"},"language":{"type":"string"}}}},"monthly_budget_minor":{"type":"integer","minimum":1,"nullable":true},"currency":{"type":"string","minLength":3,"maxLength":3},"objective":{"type":"string","enum":["","leads","revenue","traffic","installs"]}}},"AdsOfferingKind":{"type":"string","enum":["website","product","service","app","location","event","lead_form","affiliate_offer","other"]},"AdsOrganic":{"type":"object","description":"za-191 / za-N3 (docs/1006 §78): paid beside organic for one Google Ads account, and the saver's thresholds.","required":["connection_id","site","granted","scope_offered","currency","window_days","settings","recommended","bounds","rows"],"properties":{"connection_id":{"type":"string","format":"uuid"},"site":{"type":"string"},"granted":{"type":"boolean"},"scope_offered":{"type":"boolean"},"currency":{"type":"string"},"window_days":{"type":"integer"},"settings":{"$ref":"#/components/schemas/AdsOrganicSettings"},"recommended":{"$ref":"#/components/schemas/AdsOrganicSettings"},"bounds":{"type":"object","description":"`[min, max]` per numeric threshold.","additionalProperties":{"type":"array","minItems":2,"maxItems":2,"items":{"type":"number"}}},"rows":{"type":"array","items":{"$ref":"#/components/schemas/AdsOrganicRow"}}}},"AdsOrganicRow":{"type":"object","description":"One enabled keyword beside the same query's organic reading (za-191).","required":["query","campaign","match_type","paid_clicks","paid_cost_micros","paid_conversions","cpc_bid_micros","organic_found","organic_clicks","organic_impressions","organic_position","verdict","last_action","last_proposed_at","refreshed_at"],"properties":{"query":{"type":"string"},"campaign":{"type":"string"},"match_type":{"type":"string"},"paid_clicks":{"type":"integer"},"paid_cost_micros":{"type":"integer","description":"Micros of the account currency."},"paid_conversions":{"type":"number"},"cpc_bid_micros":{"type":"integer","description":"The keyword's own manual bid; 0 = none (automated bidding)."},"organic_found":{"type":"boolean","description":"False: Search Console has no row for this query in the window."},"organic_clicks":{"type":"integer"},"organic_impressions":{"type":"integer"},"organic_position":{"type":"number","nullable":true},"verdict":{"type":"string","description":"`top` · `weak` · `fine` · `thin` (too few clicks to judge) · empty before the first run."},"last_action":{"type":"string","description":"`lower` · `pause` · `raise` — the last proposal made, or empty."},"last_proposed_at":{"type":"string","format":"date-time","nullable":true},"refreshed_at":{"type":"string","format":"date-time"}}},"AdsOrganicSettings":{"type":"object","description":"The paid-vs-organic saver's thresholds (za-N3) — the customer's own values.","required":["organic_saver_mode","organic_top_position","organic_min_clicks","organic_paid_min_clicks","organic_saver_action","organic_lower_pct","organic_weak_position","organic_raise_pct","organic_cooldown_days"],"properties":{"organic_saver_mode":{"type":"string","enum":["suggest","off"]},"organic_top_position":{"type":"number","minimum":1,"maximum":10},"organic_min_clicks":{"type":"integer","minimum":1,"maximum":100000},"organic_paid_min_clicks":{"type":"integer","minimum":1,"maximum":100000},"organic_saver_action":{"type":"string","enum":["lower","pause"]},"organic_lower_pct":{"type":"integer","minimum":5,"maximum":90},"organic_weak_position":{"type":"number","minimum":2,"maximum":100},"organic_raise_pct":{"type":"integer","minimum":5,"maximum":100},"organic_cooldown_days":{"type":"integer","minimum":1,"maximum":365}}},"AdsOrganicSite":{"type":"object","description":"One Search Console property (`sc-domain:example.com` or a URL prefix).","required":["property","permission"],"properties":{"property":{"type":"string"},"permission":{"type":"string","description":"Google's own level: `siteOwner` · `siteFullUser` · `siteRestrictedUser`."}}},"AdsOrganicUpdate":{"type":"object","additionalProperties":false,"description":"Any of the thresholds, and/or the Search Console property (`site`).","properties":{"site":{"type":"string","maxLength":300},"organic_saver_mode":{"type":"string","enum":["suggest","off"]},"organic_top_position":{"type":"number","minimum":1,"maximum":10},"organic_min_clicks":{"type":"integer","minimum":1,"maximum":100000},"organic_paid_min_clicks":{"type":"integer","minimum":1,"maximum":100000},"organic_saver_action":{"type":"string","enum":["lower","pause"]},"organic_lower_pct":{"type":"integer","minimum":5,"maximum":90},"organic_weak_position":{"type":"number","minimum":2,"maximum":100},"organic_raise_pct":{"type":"integer","minimum":5,"maximum":100},"organic_cooldown_days":{"type":"integer","minimum":1,"maximum":365}}},"AdsOutcome":{"type":"object","required":["id","source","kind","external_ref","occurred_at","value_minor","currency","click_id","has_email_hash","consent","referrer_host","outcome_host","recovery_status","recovery_reason","recovered_at","refunded_at"],"properties":{"id":{"type":"string","format":"uuid"},"source":{"type":"string","description":"`store`, `plugin`, `crm`, `events`, `checkout` (a checkout provider's webhook) or `product` (the customer's product analytics, za-190: kinds `retained7`, `retained30`, `upgrade`)."},"kind":{"type":"string"},"external_ref":{"type":"string"},"occurred_at":{"type":"string","format":"date-time"},"value_minor":{"type":"integer","nullable":true},"currency":{"type":"string"},"click_id":{"type":"string","description":"Masked to a prefix."},"has_email_hash":{"type":"boolean"},"consent":{"type":"string","enum":["","GRANTED","DENIED","UNSPECIFIED"],"description":"The ad-user-data consent the sender declared for this conversion, kept and passed to the network exactly as sent (\"\" = not stated); it is never inferred."},"referrer_host":{"type":"string"},"outcome_host":{"type":"string"},"recovery_status":{"type":"string","enum":["pending","uploaded","skipped","failed"]},"recovery_reason":{"type":"string"},"recovered_at":{"type":"string","format":"date-time","nullable":true},"refunded_at":{"type":"string","format":"date-time","nullable":true,"description":"When the checkout provider reported the sale refunded, or it was withdrawn with `retractAdsOutcomes`. A refunded sale that had not been uploaded is never uploaded."}}},"AdsOutcomeIn":{"type":"object","required":["kind","external_ref","occurred_at"],"properties":{"kind":{"type":"string","enum":["purchase","trial","lead","signup","activation","free_listing","renewal"]},"external_ref":{"type":"string","pattern":"^[\\w.:\\-/#]{1,128}$"},"occurred_at":{"type":"string","format":"date-time"},"source":{"type":"string","enum":["store","plugin","crm","events"]},"value_minor":{"type":"integer","nullable":true,"minimum":0,"description":"Integer minor units. A `free_listing` carries none (omit it or send 0; a positive value is a 422)."},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$","description":"ISO 4217, any case; must be a currency the engine's money registry knows (the one the upload prices minor units with), else a 422."},"gclid":{"type":"string","maxLength":200},"gbraid":{"type":"string","maxLength":200},"wbraid":{"type":"string","maxLength":200},"msclkid":{"type":"string","maxLength":200},"twclid":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,200}$","description":"X's click id (za-302), uploaded to X's Conversion API."},"email":{"type":"string","format":"email","writeOnly":true,"description":"Hashed at the door; never stored."},"email_hash":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"},"referrer":{"type":"string","maxLength":2000,"description":"Where the visitor came from (host kept)."},"outcome_url":{"type":"string","maxLength":2000,"description":"The page the outcome happened on (host kept)."},"consent":{"type":"string","enum":["","GRANTED","DENIED","UNSPECIFIED"]}}},"AdsOutcomesIngested":{"type":"object","required":["created","updated","unchanged"],"properties":{"created":{"type":"integer"},"updated":{"type":"integer"},"unchanged":{"type":"integer"},"rate_limited":{"type":"integer","description":"WordPress plugin only, present when above 0: leads dropped because the site sent more than 300 in this hour (a spam run against its form). Not retried."}}},"AdsOutcomesRetracted":{"type":"object","required":["retracted","withheld","already","not_found","push_started"],"properties":{"retracted":{"type":"integer","description":"Already uploaded; a retraction is queued for the network."},"withheld":{"type":"integer","description":"Not uploaded yet; it never will be."},"already":{"type":"integer","description":"Withdrawn or refunded before; nothing new."},"not_found":{"type":"integer","description":"No outcome with that kind and id on this connection."},"push_started":{"type":"boolean","description":"Whether an upload run was started to send the retractions now."}}},"AdsOwnShare":{"type":"object","required":["share_learning","share_mode","swept_on","company_id","learned","shared_changes"],"properties":{"share_learning":{"type":"boolean"},"share_mode":{"type":"string","enum":["approve","auto"]},"swept_on":{"type":["string","null"],"format":"date"},"company_id":{"type":"string","format":"uuid"},"learned":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/AdsOwnShareKind"}},"shared_changes":{"type":"object","additionalProperties":{"type":"integer"}}}},"AdsOwnShareKind":{"type":"object","required":["count","top"],"properties":{"count":{"type":"integer"},"top":{"type":"array","items":{"type":"object","required":["value","evidence","learned_in","connection_id"],"properties":{"value":{"type":"object","additionalProperties":true},"evidence":{"type":"object","additionalProperties":true},"learned_in":{"type":"string"},"connection_id":{"type":"string","format":"uuid"}}}}}},"AdsPacingMode":{"type":"string","enum":["auto","suggest","off"],"description":"za-N17 — when the month-end spend forecast drifts beyond `pacing_deviation_pct` from the target: `auto` corrects the daily budgets by itself (at most `pacing_change_cap_pct`, default 30%, a step, once a week per budget, inside the spend ceiling, with the 30-day Undo; needs autopilot, Starter and above), `suggest` (the default) queues the correction for approval, `off` only warns."},"AdsPacingStrategy":{"type":"string","enum":["even","day_of_week","front_loaded"],"default":"even","description":"za-199 (BUDGETMV1) — how the month's money is spread over its days: `even` (the same each day), `day_of_week` (the account's own weekday pattern over the last 28 days; the forecast runs on it too), `front_loaded` (each day weighted by the days left, the 1st heaviest). The correction scales the budgets to today's share of what is left."},"AdsPageFix":{"type":"object","description":"za-210 (docs/1006 §111): a landing-page fix applied on a page hosted with us — the text edits, the page file, its state, and the before/after measurement (landing-page Quality Score part and first-party outcomes, 14 days each side).","required":["id","finding_id","why","url","domain","path","state","error","edits","words","before","after","can_undo"],"properties":{"id":{"type":"string","format":"uuid"},"finding_id":{"type":"string","format":"uuid"},"why":{"type":"string","enum":["lp_intent","lp_competitor","lp_cta_wrong"]},"ad_group":{"type":"string"},"url":{"type":"string"},"domain":{"type":"string"},"path":{"type":"string","description":"The page file inside the served docroot."},"state":{"type":"string","enum":["generating","ready","applying","applied","undoing","undone","failed","discarded","expired"]},"error":{"type":"string","description":"The refusal code of a failed step (`pageFix*`); `pageFixGaveUp` when the hourly reconcile re-started a lost run six times without it finishing."},"failure":{"nullable":true,"description":"§2.57: when the AI writer failed, what kind of failure it was (provider outage with its status page, the customer's own key, a refusal, or ours) — rendered by the dashboard's VendorFailureNotice. Null otherwise.","allOf":[{"$ref":"#/components/schemas/VendorFailure"}]},"edits":{"type":"array","items":{"$ref":"#/components/schemas/AdsPageFixEdit"}},"words":{"type":"array","items":{"type":"string"}},"before":{"type":"object","additionalProperties":true},"after":{"type":"object","additionalProperties":true},"can_undo":{"type":"boolean"},"approved_at":{"type":["string","null"],"format":"date-time"},"applied_at":{"type":["string","null"],"format":"date-time"},"undo_until":{"type":["string","null"],"format":"date-time"},"undone_at":{"type":["string","null"],"format":"date-time"}}},"AdsPageFixEdit":{"type":"object","required":["field","before","after"],"properties":{"field":{"type":"string","enum":["title","h1","description","cta"]},"before":{"type":"string"},"after":{"type":"string"}}},"AdsPageFixable":{"type":"object","required":["finding_id","why","url","ad_group","words"],"properties":{"finding_id":{"type":"string","format":"uuid"},"why":{"type":"string","enum":["lp_intent","lp_competitor","lp_cta_wrong"]},"url":{"type":"string"},"ad_group":{"type":"string"},"words":{"type":"array","items":{"type":"string"}}}},"AdsPaidGeo":{"type":"object","description":"za-168 (docs/1006 §PAIDGEO) — paid revenue by country and device.","required":["mode","mode_recommended","thresholds","min_account_sales","pending_changes","reading"],"properties":{"mode":{"type":"string","enum":["off","suggest","auto"]},"mode_recommended":{"type":"string"},"thresholds":{"type":"array","items":{"type":"object","required":["name","value","recommended","min","max"],"properties":{"name":{"type":"string","enum":["window_days","min_sales","country_share_pct","device_gap_pct","device_step_pct"]},"value":{"type":["integer","null"],"description":"The customer's own value; null = the recommended one."},"recommended":{"type":"integer"},"min":{"type":"integer"},"max":{"type":"integer"}}}},"min_account_sales":{"type":"integer"},"pending_changes":{"type":"integer","description":"Proposals waiting in the change queue."},"reading":{"oneOf":[{"type":"null"},{"type":"object","required":["state","day","window_days","currency","account","countries","devices"],"properties":{"state":{"type":"string","enum":["judged","noPaidSignal"]},"day":{"type":"string","format":"date"},"window_days":{"type":"integer"},"currency":{"type":"string"},"sale_actions":{"type":"integer","description":"Conversion actions counted as a sale."},"account":{"type":"object","properties":{"cost_micros":{"type":"integer"},"sales":{"type":"number"},"revenue_minor":{"type":"integer"}}},"countries":{"type":"array","items":{"type":"object","required":["country","cost_micros","sales","revenue_minor","share_pct","verdict","outcome"],"properties":{"country":{"type":"string"},"cost_micros":{"type":"integer"},"clicks":{"type":"integer"},"sales":{"type":"number"},"revenue_minor":{"type":"integer"},"share_pct":{"type":"number"},"verdict":{"type":"string","enum":["campaign","ownCampaign","excluded","belowShare","learning"]},"outcome":{"type":"string"}}}},"devices":{"type":"array","items":{"type":"object","required":["campaign_id","campaign","device","cost_micros","sales","revenue_minor","modifier","proposed_modifier","verdict","outcome"],"properties":{"campaign_id":{"type":"string"},"campaign":{"type":"string"},"device":{"type":"string","enum":["DESKTOP","MOBILE","TABLET","CONNECTED_TV"]},"cost_micros":{"type":"integer"},"sales":{"type":"number"},"revenue_minor":{"type":"integer"},"modifier":{"type":"number"},"proposed_modifier":{"type":["number","null"]},"verdict":{"type":"string","enum":["up","down","hold","learning","deviceExcluded"]},"outcome":{"type":"string"}}}}}}]}}},"AdsPlacementGoal":{"type":"object","description":"One campaign's top-of-page goal and the daily audit's latest reading of it (za-187).","required":["campaign_id","campaign","keywords","placement","share_pct","max_cpc_micros","daily_budget_micros","source","set_by","updated_at","reported_at","report"],"properties":{"campaign_id":{"type":"string"},"campaign":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"placement":{"type":"string","enum":["top","absolute_top"]},"share_pct":{"type":"integer"},"max_cpc_micros":{"type":"integer","format":"int64"},"daily_budget_micros":{"type":"integer","format":"int64"},"source":{"type":"string","enum":["goal","objective"]},"set_by":{"type":["string","null"]},"updated_at":{"type":["string","null"],"format":"date-time"},"reported_at":{"type":["string","null"],"format":"date-time"},"report":{"type":["object","null"],"description":"The latest measurement and diagnosis (null until the first audit after the goal was set).","required":["verdict","measured_pct","lost_rank_pct","lost_budget_pct","budget_micros","currency","first","one_click","concentrate","quality_note","causes","proposals","price"],"properties":{"verdict":{"type":"string","enum":["on_target","off_target","no_data"]},"measured_pct":{"type":["number","null"],"description":"The share measured over the last 7 days, in percent."},"lost_rank_pct":{"type":["integer","null"]},"lost_budget_pct":{"type":["integer","null"]},"budget_micros":{"type":["integer","null"],"format":"int64"},"currency":{"type":["string","null"]},"first":{"type":["string","null"],"description":"The cause to fix first."},"one_click":{"type":["boolean","null"],"description":"A proposal a person can apply with one click."},"concentrate":{"type":["boolean","null"],"description":"The monthly ceiling cannot fund this goal as well: concentrate the budget."},"quality_note":{"type":["string","null"]},"causes":{"type":"array","items":{"type":"object","required":["cause","fix","keywords"],"properties":{"cause":{"type":"string","enum":["missing_keywords","ad_relevance","landing_page","expected_ctr","bid","budget"]},"fix":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}}}}},"proposals":{"type":"array","items":{"type":"object","required":["step","kind","fix"],"properties":{"step":{"type":"integer"},"kind":{"type":"string","enum":["rewrite_ads","fix_page","lift_ctr","tis","cap","keep_objective","budget","concentrate"]},"placement":{"type":"string"},"share_pct":{"type":"integer"},"cap_micros":{"type":"integer","format":"int64"},"from_micros":{"type":"integer","format":"int64"},"to_micros":{"type":"integer","format":"int64"},"fix":{"type":"string"}}}},"price":{"type":["object","null"],"description":"The price of the placement from the network's own estimates: the max CPC (cap), the cost per click expected there, the top-of-page clicks a day the keywords can give, the budget floor.","properties":{"priced":{"type":"boolean"},"source":{"type":"string"},"cap_micros":{"type":"integer","format":"int64"},"cpc_micros":{"type":"integer","format":"int64"},"searches_month":{"type":"integer"},"clicks_day_possible":{"type":"number"},"budget_floor_micros":{"type":"integer","format":"int64"},"budget_needed_micros":{"type":"integer","format":"int64"},"volume_limited":{"type":"boolean"},"ctr_measured":{"type":"boolean"}}},"under_10":{"type":["boolean","null"],"description":"Google reports any share under 10% as 0.0999: the share is under 10%, not the number."}}}}},"AdsPlacementGoalInput":{"type":"object","description":"A campaign's top-of-page goal (za-187, docs/1006 §47). Money is integer micros of the account's currency (§2.8); 0 leaves it to Zinn® Ads to price from the network's own top-of-page bid estimates.","required":["keywords","share_pct"],"properties":{"keywords":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string","minLength":1,"maxLength":80},"description":"The campaign's main keywords."},"placement":{"type":"string","enum":["top","absolute_top"],"default":"top"},"share_pct":{"type":"integer","minimum":1,"maximum":100,"description":"The target share of the placement."},"max_cpc_micros":{"type":"integer","format":"int64","minimum":0},"daily_budget_micros":{"type":"integer","format":"int64","minimum":0}}},"AdsPlan":{"type":"object","required":["org_id","source","plan_code","plan_name","interval","connections","monthly_spend_usd","managed_spend_usd","addons","overage","features","click_shield","in_good_standing"],"properties":{"org_id":{"type":"string","format":"uuid"},"source":{"type":"string","enum":["plan","trial","staff","none"],"description":"`trial` = the tier comes from a live 14-day Zinn® Ads trial (za-295; `trial` says until when). A trial that ended unpaid reads `plan` on the Free plan with `trial_ended: true`."},"plan_code":{"type":["string","null"]},"plan_name":{"type":["string","null"]},"interval":{"type":["string","null"]},"trial":{"type":["object","null"],"description":"The live Zinn® Ads trial folded into this plan, or null.","required":["id","ends_at"],"properties":{"id":{"type":"string","format":"uuid"},"ends_at":{"type":"string","format":"date-time"}}},"trial_ended":{"type":"boolean","description":"The org's Zinn® Ads trial ended unpaid, so it runs on the Free plan's limits (nothing deleted; automatic changes wait for approval). Buying any plan restores everything."},"trial_end_reason":{"type":"string","enum":["","ended","shared_ad_account"],"description":"za-298: why the trial ended, \"\" while `trial_ended` is false. `shared_ad_account` = the one-trial-per-ad-account rule ended it early, because an ad account this org connected had already had a Zinn® Ads free trial in another customer's organisation. `ended` = any other end (the 14 days ran out, or staff ended it)."},"subscription_id":{"type":["string","null"],"format":"uuid","description":"The subscription that names the tier, when this org holds it itself. Moving to another Zinn® Ads plan CHANGES this subscription pro rata (`changeSubscriptionPlan`); it is never bought again beside it. Null for a staff plan, a plan held by a parent organisation, or no plan."},"connections":{"type":"object","required":["limit","used"],"description":"`used` is the same count the connect-time refusal (`connectionLimit`) checks: active and paused accounts across every org the plan pays for, never disconnected ones. It can be ABOVE `limit` (a downgrade, a trial ending on Free): nothing is disconnected, and no account can be connected until `used` is below `limit` again. `limit` -1 = no limit.","properties":{"limit":{"type":"integer"},"used":{"type":"integer"}}},"monthly_spend_usd":{"type":"integer"},"managed_spend_usd":{"type":["integer","null"]},"addons":{"type":"object","required":["extra_account_blocks","extra_spend_blocks"],"properties":{"extra_account_blocks":{"type":"integer"},"extra_spend_blocks":{"type":"integer"}}},"overage":{"type":"object","required":["automatic","blocks","usd_minor"],"properties":{"automatic":{"type":"boolean"},"blocks":{"type":"integer"},"usd_minor":{"type":"integer","description":"US cents a month billed for the overage"}}},"features":{"type":"object","additionalProperties":{"type":"boolean"}},"click_shield":{"type":"object","required":["included","source"],"properties":{"included":{"type":"boolean"},"source":{"type":"string","enum":["staff","plan","hosting","addon","none"]}}},"in_good_standing":{"type":"boolean"}}},"AdsPlatform":{"type":"string","description":"An advertising platform (docs/1006 §4.1).","enum":["google","microsoft","meta","linkedin","tiktok","x","pinterest","amazon","chatgpt"]},"AdsPluginFeed":{"type":"object","description":"The plugin conversion feed on one ad account (za-96, docs/1006 §PLUGINFEED).","required":["connection_id","platform","enabled","checked_at","change_id","window_days","roles"],"properties":{"connection_id":{"type":"string","format":"uuid"},"platform":{"type":"string"},"enabled":{"type":"boolean"},"checked_at":{"type":"string","format":"date-time","nullable":true,"description":"When the tracking step last read the account for the feed."},"change_id":{"type":"string","format":"uuid","nullable":true,"description":"The create waiting in the change queue","if any.":null},"window_days":{"type":"integer"},"roles":{"type":"array","items":{"type":"object","required":["role","kind","name","primary","action","state","received","uploaded"],"properties":{"role":{"type":"string","enum":["purchase","trial","install","renewal"]},"kind":{"type":"string","enum":["purchase","trial","activation","renewal"]},"name":{"type":"string","description":"The action's name on the ad account."},"primary":{"type":"boolean"},"action":{"type":"string","description":"The action found (Google resource name; Microsoft goal name); empty when not found."},"state":{"type":"string","enum":["mapped","kept_yours","queued","declined","missing"]},"received":{"type":"integer"},"uploaded":{"type":"integer"}}}}}},"AdsPmaxFigures":{"type":"object","description":"One row's figures over the window; money in micros of the account's currency.","properties":{"impressions":{"type":"integer"},"clicks":{"type":"integer"},"conversions":{"type":"number"},"cost_micros":{"type":"integer","format":"int64"}}},"AdsPmaxReading":{"type":["object","null"],"description":"za-185 (docs/1006 §78): the Performance Max reading, or null before the first audit. `state`: `ok` · `attention` (a low-rated asset, a search that spends and never converts, a campaign at 10,000 negatives or with no brand exclusion) · `noPmax`.","required":["kind","state","day","updated_at","figures"],"properties":{"kind":{"type":"string","enum":["pmax"]},"state":{"type":"string","enum":["ok","attention","noPmax"]},"day":{"type":"string","format":"date"},"updated_at":{"type":"string","format":"date-time"},"figures":{"type":"object","required":["window_days","has_search","campaigns"],"properties":{"window_days":{"type":"integer"},"has_search":{"type":"boolean","description":"The account runs enabled Search campaigns."},"campaigns":{"type":"array","items":{"type":"object","required":["campaign_id","campaign","asset_groups","channels","terms","insights","negatives","negatives_limit","brand_exclusion"],"properties":{"campaign_id":{"type":"string"},"campaign":{"type":"string"},"negatives":{"type":"integer"},"negatives_limit":{"type":"integer","description":"Google's limit per PMax campaign (10,000)."},"brand_exclusion":{"type":"boolean"},"asset_groups":{"type":"array","items":{"type":"object","properties":{"asset_group_id":{"type":"string"},"asset_group":{"type":"string"},"status":{"type":"string"},"ad_strength":{"type":"string","description":"Google's ad strength (POOR, AVERAGE, GOOD, EXCELLENT, PENDING)."},"ratings":{"type":"object","properties":{"best":{"type":"integer"},"good":{"type":"integer"},"low":{"type":"integer"},"learning":{"type":"integer"}}},"low":{"type":"array","items":{"type":"object","properties":{"resource":{"type":"string"},"asset_id":{"type":"string"},"field_type":{"type":"string"},"impressions":{"type":"integer"},"clicks":{"type":"integer"},"conversions":{"type":"number"},"ctr_pct":{"type":"number"},"group_ctr_pct":{"type":"number"},"rating":{"type":"string"},"removable":{"type":"boolean","description":"The group keeps its minimum of this kind without it."}}}}}}},"channels":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/AdsPmaxFigures"},{"type":"object","properties":{"network":{"type":"string"}}}]}},"terms":{"type":"array","description":"The top searches by clicks.","items":{"allOf":[{"$ref":"#/components/schemas/AdsPmaxFigures"},{"type":"object","properties":{"term":{"type":"string"}}}]}},"insights":{"type":"array","description":"Google's search categories (campaign_search_term_insight), top by clicks.","items":{"allOf":[{"$ref":"#/components/schemas/AdsPmaxFigures"},{"type":"object","properties":{"category":{"type":"string"}}}]}}}}}}}}},"AdsProductAnalytics":{"type":"object","required":["source","regions","stages","quality"],"properties":{"source":{"oneOf":[{"$ref":"#/components/schemas/AdsProductSource"},{"type":"null"}]},"regions":{"type":"array","items":{"type":"string"}},"stages":{"type":"array","items":{"type":"string","enum":["signup","activated","retained7","retained30","upgraded"]}},"quality":{"type":"object","required":["totals","paid_rate","average_upgrade_minor","currency","rows"],"properties":{"totals":{"type":"object","additionalProperties":{"type":"integer"}},"paid_rate":{"type":"object","additionalProperties":{"type":"number"}},"average_upgrade_minor":{"type":["integer","null"],"description":"Integer minor units of `currency`."},"currency":{"type":"string"},"rows":{"type":"array","items":{"type":"object","required":["keyword","country","stages"],"properties":{"keyword":{"type":"string"},"country":{"type":"string"},"stages":{"type":"object","additionalProperties":{"type":"object","required":["people","upgraded","paid_rate","value_minor"],"properties":{"people":{"type":"integer"},"upgraded":{"type":"integer"},"paid_rate":{"type":"number"},"value_minor":{"type":["integer","null"]}}}}}}}}}}},"AdsProductAnalyticsIn":{"type":"object","required":["region","project_id","api_key"],"properties":{"region":{"type":"string","enum":["eu","us"]},"project_id":{"type":"string","maxLength":12,"pattern":"^[0-9]+$"},"api_key":{"type":"string","minLength":8,"writeOnly":true},"signup_event":{"type":"string","maxLength":100},"activated_event":{"type":"string","maxLength":100},"upgraded_event":{"type":"string","maxLength":100},"active_event":{"type":"string","maxLength":100},"value_property":{"type":"string","maxLength":64},"currency":{"type":"string","pattern":"^([A-Za-z]{3})?$"}}},"AdsProductCost":{"type":"object","description":"What one product / plan costs the customer, in integer minor units (za-189).","required":["product_ref","cost_minor","currency"],"properties":{"product_ref":{"type":"string","maxLength":120,"description":"The provider's id: Stripe metadata.product (or zinn_product / plan), Paddle product id, Freemius plan id."},"label":{"type":"string","maxLength":80},"cost_minor":{"type":"integer","format":"int64","minimum":0},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}}},"AdsProductSource":{"type":"object","description":"A connected product analytics project (za-190). The API key is never returned.","required":["id","connection_id","vendor","region","project_id","has_key","enabled","events","active_event","value_property","currency","cursor_at","last_attempted_at","last_synced_at","last_failure","failure","events_read","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid"},"vendor":{"type":"string","enum":["posthog"]},"region":{"type":"string","enum":["eu","us"]},"project_id":{"type":"string"},"has_key":{"type":"boolean"},"enabled":{"type":"boolean"},"events":{"type":"object","description":"The customer's event name per stage (`\"\"` = not tracked).","additionalProperties":{"type":"string"}},"active_event":{"type":"string","description":"The event that proves a person is still using the product (retention)."},"value_property":{"type":"string","description":"The event property carrying the upgrade value."},"currency":{"type":"string"},"cursor_at":{"type":["string","null"],"format":"date-time"},"last_attempted_at":{"type":["string","null"],"format":"date-time"},"last_synced_at":{"type":["string","null"],"format":"date-time"},"last_failure":{"type":"string","description":"The stored failure class of the last sync, `\"\"` when it worked."},"failure":{"oneOf":[{"$ref":"#/components/schemas/VendorFailure"},{"type":"null"}]},"events_read":{"type":"integer"},"created_at":{"type":["string","null"],"format":"date-time"}}},"AdsProductTrial":{"type":"object","description":"One product's free-trial length (za-100).","required":["product_ref","label","trial_days","recommended_days","custom"],"properties":{"product_ref":{"type":"string","maxLength":120,"description":"The id the product's sales and trials carry (a checkout provider's product / plan id; the plugin store slug on our own account)."},"label":{"type":"string","maxLength":80},"trial_days":{"type":"integer","enum":[0,7,14,30],"description":"0 = no free trial."},"recommended_days":{"type":"integer","enum":[0,7,14,30],"readOnly":true},"custom":{"type":"boolean","readOnly":true,"description":"true = the customer's own choice; false = it follows the recommendation."}}},"AdsProductTrials":{"type":"object","required":["connection_id","business_type","choices","recommended_days","longest_days","products"],"properties":{"connection_id":{"type":"string","format":"uuid"},"business_type":{"type":"string","description":"The account's business type (\"\" = not chosen); the recommendation follows it."},"choices":{"type":"array","items":{"type":"integer"},"description":"The lengths that may be chosen","in days.":null},"recommended_days":{"type":"integer","description":"Our recommended trial length for this account."},"longest_days":{"type":"integer","description":"The longest trial the account's products run — how long a campaign's sales verdict waits."},"products":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/AdsProductTrial"}}}},"AdsProductTrialsSettings":{"type":"object","required":["products"],"properties":{"products":{"type":"array","maxItems":500,"items":{"type":"object","required":["product_ref","trial_days"],"properties":{"product_ref":{"type":"string","maxLength":120},"label":{"type":"string","maxLength":80},"trial_days":{"type":["integer","null"],"enum":[0,7,14,30,null],"description":"null = reset to recommended."}}}}}},"AdsProfit":{"type":"object","required":["connection_id","value_basis","default_cost_bp","products","sources","summary"],"properties":{"connection_id":{"type":"string","format":"uuid"},"value_basis":{"type":"string","enum":["revenue","profit"]},"default_cost_bp":{"type":"integer"},"products":{"type":"array","items":{"$ref":"#/components/schemas/AdsProductCost"}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/AdsProfitSourceFee"}},"summary":{"type":"object","required":["days","by_currency","revenue_basis_sales","no_product_sales","unpriced_products"],"properties":{"days":{"type":"integer"},"by_currency":{"type":"array","items":{"type":"object","required":["currency","sales","revenue_minor","margin_minor","cost_minor","fee_minor","tax_minor"],"properties":{"currency":{"type":"string"},"sales":{"type":"integer"},"revenue_minor":{"type":"integer","format":"int64"},"margin_minor":{"type":"integer","format":"int64"},"cost_minor":{"type":"integer","format":"int64"},"fee_minor":{"type":"integer","format":"int64"},"tax_minor":{"type":"integer","format":"int64"}}}},"revenue_basis_sales":{"type":"integer","description":"Sales that arrived on the revenue basis (before profit bidding was on)."},"no_product_sales":{"type":"integer","description":"Profit-basis sales whose provider named no product (they took default_cost_bp)."},"unpriced_products":{"type":"array","items":{"type":"object","required":["product_ref","sales"],"properties":{"product_ref":{"type":"string"},"sales":{"type":"integer"}}}}}}}},"AdsProfitSettings":{"type":"object","properties":{"value_basis":{"type":"string","enum":["revenue","profit"]},"default_cost_bp":{"type":"integer","minimum":0,"maximum":10000,"description":"Cost of a product with no cost row","in basis points of its price.":null},"products":{"type":"array","maxItems":5000,"items":{"$ref":"#/components/schemas/AdsProductCost"}},"sources":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/AdsProfitSourceFee"}}}},"AdsProfitSourceFee":{"type":"object","description":"One checkout source's fee estimate, used when its webhook reports no fee.","required":["id"],"properties":{"id":{"type":"string","format":"uuid"},"provider":{"type":"string","enum":["stripe","paddle","freemius"],"readOnly":true},"label":{"type":"string","readOnly":true},"reports_fee":{"type":"boolean","readOnly":true,"description":"true = the provider reports its own fee (Paddle, Freemius); the estimate is not used."},"fee_bp":{"type":"integer","minimum":0,"maximum":10000,"description":"Basis points of the sale (290 = 2.9 %)."},"fee_fixed_minor":{"type":"integer","format":"int64","minimum":0},"fee_currency":{"type":"string","pattern":"^([A-Z]{3})?$","description":"The fixed part applies only to sales in this currency."}}},"AdsProspectingInfoEnvelope":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["intents","matches","business_types","business_type","currency","recommended_budget_minor","pending"],"properties":{"intents":{"type":"array","items":{"type":"string","enum":["category","problem","alternative","brand"]}},"matches":{"type":"array","items":{"type":"string","enum":["EXACT","PHRASE"]}},"business_types":{"type":"array","items":{"type":"object","required":["value","paid_by_default","starter_negatives"],"properties":{"value":{"type":"string"},"paid_by_default":{"type":"boolean"},"starter_negatives":{"type":"array","items":{"type":"string"}}}}},"business_type":{"type":"string"},"currency":{"type":"string"},"recommended_budget_minor":{"type":"integer"},"pending":{"type":"integer"}}}}},"AdsProspectingPlan":{"type":"object","required":["status","change_id","campaign","business_type","paid","free_seeker","groups","negatives","refused"],"properties":{"status":{"type":"string","enum":["preview","proposed","refused","nothingReady","rejectedBefore"]},"change_id":{"type":["string","null"]},"campaign":{"type":"object","required":["name","country","language","daily_budget_minor","recommended_budget_minor","currency","final_url"],"properties":{"name":{"type":"string"},"country":{"type":"string"},"language":{"type":"string"},"daily_budget_minor":{"type":"integer"},"recommended_budget_minor":{"type":"integer"},"currency":{"type":"string"},"final_url":{"type":"string"}}},"business_type":{"type":"string"},"paid":{"type":"boolean"},"free_seeker":{"type":"boolean"},"groups":{"type":"array","items":{"type":"object","required":["intent","name","keywords","status","reason"],"properties":{"intent":{"type":"string","enum":["category","problem","alternative","brand"]},"name":{"type":"string"},"rival":{"type":"string"},"status":{"type":"string","enum":["ready","waiting","skipped"]},"reason":{"type":"string"},"keywords":{"type":"array","items":{"type":"object","required":["text","match"],"properties":{"text":{"type":"string"},"match":{"type":"string","enum":["EXACT","PHRASE"]}}}},"headlines":{"type":"array","items":{"type":"string"}},"descriptions":{"type":"array","items":{"type":"string"}}}}},"negatives":{"type":"array","items":{"type":"object","required":["text","match","class","status","reasons"],"properties":{"text":{"type":"string"},"match":{"type":"string","enum":["EXACT","PHRASE"]},"class":{"type":"string","enum":["starter","free_seeker"]},"status":{"type":"string","enum":["kept","dropped"]},"reasons":{"type":"array","items":{"type":"string"}}}}},"refused":{"type":["object","null"],"additionalProperties":true}}},"AdsProspectingPreviewEnvelope":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["preview_id","status","plan","error"],"properties":{"preview_id":{"type":"string"},"status":{"type":"string","enum":["building","ready","failed","expired"]},"plan":{"oneOf":[{"$ref":"#/components/schemas/AdsProspectingPlan"},{"type":"null"}]},"error":{"oneOf":[{"type":"object","required":["code","field"],"properties":{"code":{"type":"string"},"field":{"type":"string"}}},{"type":"null"}]}}}}},"AdsProspectingRequest":{"type":"object","required":["brand","category","final_url","country"],"properties":{"business_type":{"type":"string","enum":["free_trial","freemium","lead_gen","ecommerce","local","b2b"]},"paid":{"type":["boolean","null"],"description":"null = the business type's default (freemium is not paid)."},"brand":{"type":"string","maxLength":40},"brand_terms":{"type":"array","maxItems":10,"items":{"type":"string","maxLength":80}},"category":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","maxLength":80}},"problems":{"type":"array","maxItems":10,"items":{"type":"string","maxLength":80}},"competitors":{"type":"array","maxItems":5,"items":{"type":"string","maxLength":80}},"final_url":{"type":"string","format":"uri"},"country":{"type":"string","description":"ISO 3166-1 alpha-2."},"language":{"type":"string","default":"en"},"daily_budget_minor":{"type":["integer","null"],"description":"Minor units of the account currency; null = Recommended (five whole units, also the floor)."},"headlines":{"type":"array","maxItems":15,"items":{"type":"string","maxLength":30}},"descriptions":{"type":"array","maxItems":4,"items":{"type":"string","maxLength":90}}}},"AdsQsDiagnosis":{"type":"object","required":["id","keyword","match_type","ad_group","campaign","quality_score","ad_relevance","expected_ctr","landing_page","impressions","weakest","fix","change","final_url","report","seen_at"],"properties":{"id":{"type":"string","format":"uuid"},"keyword":{"type":"string"},"match_type":{"type":"string"},"ad_group":{"type":"string"},"campaign":{"type":"string"},"quality_score":{"type":"integer","minimum":1,"maximum":10},"ad_relevance":{"type":"string","description":"BELOW_AVERAGE, AVERAGE, ABOVE_AVERAGE or empty."},"expected_ctr":{"type":"string"},"landing_page":{"type":"string"},"impressions":{"type":"integer"},"weakest":{"type":"string","enum":["ad_relevance","expected_ctr","landing_page"]},"fix":{"type":"object","required":["kind","status"],"properties":{"kind":{"type":"string","enum":["move_keyword","ad_with_keyword","split_group","rsa_assets","page_speed"]},"status":{"type":"string","description":"`proposed:<change status>`, `gateRefused`, `advice`, `tooLongForHeadline`, `noLiveAd`, `noNewLines`, `slow`, `fast` or `unread`."},"target":{"type":"string","description":"move_keyword: the ad group it moves to."},"reasons":{"type":"array","items":{"type":"string"}},"hosted":{"type":"boolean"}}},"change":{"type":"object","nullable":true,"required":["id","status"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"}}},"final_url":{"type":"string"},"report":{"type":"object","description":"The landing page's page-speed reading (landing page only).","properties":{"url":{"type":"string"},"checked":{"type":"boolean"},"lcp_ms":{"type":"integer","nullable":true},"cls_milli":{"type":"integer","nullable":true},"lcp_limit_ms":{"type":"integer"},"slow":{"type":"boolean"},"opportunities":{"type":"array","items":{"type":"string"}},"hosting":{"type":"object","properties":{"site_id":{"type":"string","format":"uuid"},"fixes":{"type":"array","items":{"$ref":"#/components/schemas/AdsQsHostingFix"}}}}}},"seen_at":{"type":"string","format":"date-time"}}},"AdsQsFixer":{"type":"object","required":["settings","checked_at","keywords"],"properties":{"settings":{"$ref":"#/components/schemas/AdsQualityScoreSettings"},"checked_at":{"type":"string","format":"date-time","nullable":true},"keywords":{"type":"array","items":{"$ref":"#/components/schemas/AdsQsDiagnosis"}}}},"AdsQsHostingFix":{"type":"object","required":["code","href"],"properties":{"code":{"type":"string","enum":["page_cache_off","object_cache_off","cdn_off","speed_review"]},"href":{"type":"string","description":"The dashboard page that switches it."}}},"AdsQsLimit":{"type":"object","required":["value","recommended","custom","min","max"],"properties":{"value":{"type":"integer","description":"The value in force: the customer's own, else recommended."},"recommended":{"type":"integer"},"custom":{"type":"boolean","description":"true = the customer set their own value."},"min":{"type":"integer"},"max":{"type":"integer"}}},"AdsQualityFinding":{"type":"object","description":"One reason an ad may not be published (za-162..165) — `brandNotPinned`, `brandMissingHeadline`, `brandMissingDescription`, `competitorInText`, `freeSoftware`, `genericOnly`, ADCOPY1's `duplicateHeadlines` / `topicMissing` / `stitched` / `titleJunk`, za-334's `sameMeaning` (two lines make the same offer about the same thing, by meaning in every language the angle table reads), `angleOverused` (more than `want` lines of one part carry one offer `angle`), `pinnedBeyondBrand` (a pin at `position` other than headline 1), `pinnedSameAngle` (two pinned lines with one offer `angle`), `offerPinned` (an offer pinned while an unpinned line already makes it), `meaningJudgeUnavailable` (za-334 r11: the same-offer judge gave no verdict, so the ad is refused — fail closed — with the reason in `failure`), `unsupportedUrgency` (za-334 r22: a line claims a deadline, a weekday deadline or a count of what is left that none of the advertiser's own page sentences backs; refused in every ad, offer or not. r23: only an offer sentence on the page that makes the same claim, the same end date, weekday or count, backs it; the build keeps those sentences for the launch and the change gate. r24: the backing sentence must be a current OFFER sentence, its date today or later, re-checked against today at the gate. R25a: a past or expired offer sentence backs nothing, and a weekday or \"today\" deadline backs only while the page read still holds it), `mixedScript` (za-334 r24: a word mixes alphabets or hides an invisible character, such as \"Last Chance\" typed with a Cyrillic Es for the C; R25a: a lookalike of any script, Unicode UTS #39, and only when it folds to a different Latin word, so \"10kΩ\" or \"Ωmega\" is no disguise), or on keywords `competitorBareName` / `competitorLandsOnHome`. A `sameMeaning` named by the semantic judge carries `by: judge` and the later line in `drop`.","required":["code","part"],"properties":{"code":{"type":"string"},"part":{"type":"string","enum":["headline","description","path","ad","keyword"]},"text":{"type":"string"},"want":{"type":"integer"},"have":{"type":"integer"},"angle":{"type":"string","description":"za-334 — the offer the lines repeat.","enum":["trial","noCard","moneyBack","price","discount","noContract","free"]},"position":{"type":"string","description":"za-334 — the pinned position (`pinnedBeyondBrand`)."},"by":{"type":"string","description":"za-334 r11 — `judge` when the semantic judge named the pair."},"drop":{"type":"string","description":"za-334 r11 — the later line of a judged pair (dropped by the rewrite)."},"lines":{"type":"array","items":{"type":"string"},"description":"za-334 r16 — every line a multi-line finding (`sameMeaning`, `duplicateHeadlines`, `pinnedSameAngle`) names, one item per ad line; `text` joins them with \" / \", which a single line may itself contain (\"Monthly / Annual Plans\")."},"failure":{"$ref":"#/components/schemas/VendorFailure"}}},"AdsQualityScore":{"type":"object","description":"Zinn® Ads' own ad strength for an ad the network has not rated yet (the rubric: 15 distinct headlines, 4 descriptions, the ad group's own keywords in headlines and its top keyword word for word in two descriptions, no repetition, length used, exactly one pin — headline 1, the advertiser's domain or brand — and six or more sitelinks on the campaign). Only GOOD or EXCELLENT with no `blocked` finding is ever published.","required":["strength","points","max_points","publishable","blocked","reasons"],"properties":{"strength":{"type":"string","enum":["POOR","AVERAGE","GOOD","EXCELLENT"]},"points":{"type":"integer"},"max_points":{"type":"integer"},"publishable":{"type":"boolean"},"rounds":{"type":"integer"},"rewritten":{"type":"boolean"},"blocked":{"type":"array","items":{"$ref":"#/components/schemas/AdsQualityFinding"}},"reasons":{"type":"array","items":{"type":"object","required":["code"],"description":"`fewHeadlines`, `fewDescriptions`, `repetitive`, `keywordsMissing`, `keywordsUnknown`, `keywordsAreCompetitors`, `keywordsNotInDescriptions`, `shortLines`, `overPinned`, `fewSitelinks` — with `have` / `want` where they apply; `singlePin` (a position holding ONE pinned asset, `positions`: Google held every such ad at AVERAGE or below) and `popularKeywordsMissing` (none of the group's most searched `keywords` in a headline; `share` = impressions the headlines cover) — ADSTRENGTH1, docs/1006 §50; `headlineKeywordCoverage` and `descriptionKeywordCoverage` (the share, in percent, of the group's own keywords the free headlines / the descriptions carry, `have` under `want`, with the missing `keywords`, most searched first: Google held such ads below GOOD) — ADSTRENGTH3.","properties":{"code":{"type":"string"},"have":{"type":"integer"},"want":{"type":"integer"},"positions":{"type":"array","items":{"type":"string"}},"keywords":{"type":"array","items":{"type":"string"}},"share":{"type":"number"}}}}}},"AdsQualityScoreSettings":{"type":"object","required":["enabled","max_score","min_impressions","lcp_ms"],"properties":{"enabled":{"type":"boolean","description":"The fixer's on/off switch (recommended on)."},"max_score":{"$ref":"#/components/schemas/AdsQsLimit"},"min_impressions":{"$ref":"#/components/schemas/AdsQsLimit"},"lcp_ms":{"$ref":"#/components/schemas/AdsQsLimit"}}},"AdsQualityScoreSettingsUpdate":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean"},"max_score":{"type":"integer","nullable":true,"minimum":1,"maximum":10},"min_impressions":{"type":"integer","nullable":true,"minimum":0,"maximum":1000000},"lcp_ms":{"type":"integer","nullable":true,"minimum":500,"maximum":20000}}},"AdsQualitySegment":{"type":"object","required":["dimension","value","label","clicks","cost_micros","signups","activated","paid","verdict","action","outcome","held"],"properties":{"dimension":{"type":"string","enum":["keyword","term","country","device"]},"value":{"type":"string"},"label":{"type":"string"},"clicks":{"type":"integer"},"cost_micros":{"type":"integer"},"signups":{"type":"number"},"activated":{"type":"number"},"paid":{"type":"number"},"verdict":{"type":"string","enum":["learning","ok","low","never"]},"action":{"type":"string","description":"pause, bidDown, negative, or empty."},"outcome":{"type":"string","description":"queued, applied, held, failed, refused:<reason>, or empty."},"held":{"type":"array","items":{"type":"string"},"description":"The collision guard's reasons."}}},"AdsQualitySegments":{"type":"object","required":["mode","mode_recommended","thresholds","min_account_activations","pending_changes","reading"],"properties":{"mode":{"type":"string","enum":["off","suggest","auto"]},"mode_recommended":{"type":"string"},"thresholds":{"type":"array","items":{"type":"object","required":["name","value","recommended","min","max"],"properties":{"name":{"type":"string","enum":["min_signups","window_days","cut_ratio_pct","bid_down_pct"]},"value":{"type":["integer","null"],"description":"The customer's own value; null = the recommended one."},"recommended":{"type":"integer"},"min":{"type":"integer"},"max":{"type":"integer"}}}},"min_account_activations":{"type":"integer"},"pending_changes":{"type":"integer","description":"Proposals waiting in the change queue."},"reading":{"oneOf":[{"type":"null"},{"type":"object","required":["state","day","window_days","account","segments"],"properties":{"state":{"type":"string","enum":["judged","noActivationSignal","killed"]},"day":{"type":"string","format":"date"},"window_days":{"type":"integer"},"thresholds":{"type":"object","additionalProperties":{"type":"integer"}},"currency":{"type":"string"},"account":{"type":"object","properties":{"signups":{"type":"number"},"activated":{"type":"number"},"paid":{"type":"number"},"activation_rate":{"type":"number"}}},"segments":{"type":"array","items":{"$ref":"#/components/schemas/AdsQualitySegment"}}}}]}}},"AdsReachSettings":{"type":"object","description":"za-86 (PARITY86) — a connection's reach settings for campaigns that cannot enter the auction (stored, or the Recommended).","required":["reach_min_searches","reach_test_days"],"properties":{"reach_min_searches":{"type":"integer","minimum":1,"maximum":1000000},"reach_test_days":{"type":"integer","minimum":7,"maximum":60}}},"AdsReport":{"type":"object","required":["window_days","first_day","last_day","clients","accounts","detail"],"properties":{"window_days":{"type":"integer"},"first_day":{"type":"string","format":"date"},"last_day":{"type":"string","format":"date"},"clients":{"type":"array","items":{"$ref":"#/components/schemas/AdsReportClient"}},"accounts":{"type":"array","items":{"$ref":"#/components/schemas/AdsReportAccount"}},"detail":{"type":"object","nullable":true,"required":["connection_id","currency","campaigns","products","countries"],"properties":{"connection_id":{"type":"string","format":"uuid"},"currency":{"type":"string"},"campaigns":{"type":"array","items":{"$ref":"#/components/schemas/AdsReportBreakdownRow"}},"products":{"type":"array","items":{"$ref":"#/components/schemas/AdsReportBreakdownRow"}},"countries":{"type":"array","items":{"$ref":"#/components/schemas/AdsReportBreakdownRow"}}}}}},"AdsReportAccount":{"allOf":[{"$ref":"#/components/schemas/AdsReportFigures"},{"type":"object","required":["connection_id","org_id","platform","external_id","label","status","currency","fraud_exclusions","fraud_clicks","fraud_cost_minor","recovered_minor","changes_applied","changes_pending"],"properties":{"connection_id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid","description":"The client organisation it sits under."},"platform":{"type":"string"},"external_id":{"type":"string"},"label":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"fraud_exclusions":{"type":"integer"},"fraud_clicks":{"type":"integer","format":"int64"},"fraud_cost_minor":{"type":"integer","format":"int64"},"recovered_minor":{"type":"integer","format":"int64"},"changes_applied":{"type":"integer"},"changes_pending":{"type":"integer"}}}]},"AdsReportBreakdownRow":{"allOf":[{"$ref":"#/components/schemas/AdsReportFigures"},{"type":"object","properties":{"campaign_id":{"type":"string"},"campaign":{"type":"string"},"product":{"type":"string"},"country":{"type":"string"}}}]},"AdsReportClient":{"type":"object","required":["org_id","name","accounts","changes_applied","fraud_exclusions","totals"],"properties":{"org_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"accounts":{"type":"integer"},"changes_applied":{"type":"integer"},"fraud_exclusions":{"type":"integer"},"totals":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/AdsReportFigures"},{"type":"object","required":["currency","recovered_minor"],"properties":{"currency":{"type":"string"},"recovered_minor":{"type":"integer","format":"int64"}}}]}}}},"AdsReportFigures":{"type":"object","required":["cost_micros","clicks","impressions","conversions_milli","value_micros","roas_bp"],"properties":{"cost_micros":{"type":"integer","format":"int64"},"clicks":{"type":"integer","format":"int64"},"impressions":{"type":"integer","format":"int64"},"conversions_milli":{"type":"integer","format":"int64","description":"RECORDED conversions x 1000 (MSALLCONV-FU2): every conversion the network recorded, biddable goal or not (Microsoft `AllConversions`, Google `metrics.all_conversions`; a day stored before that column read its biddable figure)."},"value_micros":{"type":"integer","format":"int64"},"roas_bp":{"type":"integer","format":"int64","nullable":true}}},"AdsReportRows":{"type":"object","required":["fields","start","end","rows","next_offset"],"properties":{"fields":{"type":"array","items":{"type":"object","required":["name","type"],"properties":{"name":{"type":"string"},"type":{"type":"string","description":"The Looker Studio semantic type."}}}},"start":{"type":"string","format":"date"},"end":{"type":"string","format":"date"},"next_offset":{"type":["integer","null"]},"rows":{"type":"array","items":{"type":"object","required":["day","client_org_id","client","connection_id","account","platform","currency","campaign_id","campaign","impressions","clicks","cost_micros","conversions_milli","value_micros","recorded_conversions_milli"],"properties":{"day":{"type":"string","format":"date"},"client_org_id":{"type":"string","format":"uuid"},"client":{"type":"string"},"connection_id":{"type":"string","format":"uuid"},"account":{"type":"string"},"platform":{"type":"string"},"currency":{"type":"string"},"campaign_id":{"type":"string"},"campaign":{"type":"string"},"impressions":{"type":"integer"},"clicks":{"type":"integer"},"cost_micros":{"type":"integer"},"conversions_milli":{"type":"integer","description":"BIDDABLE conversions x 1000 only (the goals the network bids on). Kept under its old name so a saved Looker Studio report never changes meaning; see recorded_conversions_milli."},"value_micros":{"type":"integer"},"recorded_conversions_milli":{"type":"integer","description":"RECORDED conversions x 1000 (MSALLCONV-FU2): every conversion the network recorded, biddable goal or not (Microsoft `AllConversions`, Google `metrics.all_conversions`; a day stored before that column read its biddable figure)."}}}}}},"AdsReportSchedule":{"type":"object","required":["id","org_id","cadence","window_days","recipients","locale","enabled","next_run_at","last_sent_at","last_error"],"properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"cadence":{"type":"string","enum":["weekly","monthly"]},"window_days":{"type":"integer"},"recipients":{"type":"array","items":{"type":"string"}},"locale":{"type":"string"},"enabled":{"type":"boolean"},"next_run_at":{"type":["string","null"],"format":"date-time"},"last_sent_at":{"type":["string","null"],"format":"date-time"},"last_error":{"type":"string","description":"`notInGoodStanding`, `mailRefused`, `renderFailed` or empty."}}},"AdsReportScheduleInput":{"type":"object","required":["cadence","recipients"],"properties":{"org_id":{"type":"string","format":"uuid","description":"The client organisation the report is about."},"cadence":{"type":"string","enum":["weekly","monthly"]},"window_days":{"type":"integer","enum":[7,30,90],"description":"Default 7 (weekly) or 30 (monthly)."},"recipients":{"type":"array","items":{"type":"string","format":"email"},"minItems":1,"maxItems":10},"locale":{"type":"string","default":"en","description":"One of the 58 platform languages."},"enabled":{"type":"boolean","default":true}}},"AdsReview":{"type":"object","description":"A scheduled review (AUTOREVIEW1). `figures` are the measurements the verdict rests on: the judged window (`after`) and the same length before it (`before`) with impressions, clicks, cost in the account's integer micros and conversions in thousandths (plus our own first-party `outcomes` on the house account), per campaign; a funnel's `idle` campaigns; a Quality Score review's `now` and `before` (`qs_x10`, `lp_below`, `keywords`); `stale` when the stored figures could not be read.","required":["id","connection_id","subject","title","question","campaign_ids","change_id","test_key","measure_from","due_on","options","source","created_by","created_at","status","judged_at","verdict","recommended","figures","decision","decided_by","decided_by_kind","decided_at","can_undo"],"properties":{"id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid"},"subject":{"type":"string","enum":["results","change","experiment","quality","funnel","ending"]},"title":{"type":"string"},"question":{"type":"string"},"campaign_ids":{"type":"array","items":{"type":"string"}},"change_id":{"type":"string","format":"uuid","nullable":true},"test_key":{"type":"string"},"measure_from":{"type":"string","format":"date"},"due_on":{"type":"string","format":"date"},"options":{"type":"array","items":{"type":"string","enum":["keep","pause","revert","extend","extend30","extend60","extend90"]}},"source":{"type":"string","enum":["customer","autopilot","owner"]},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["scheduled","due","decided","cancelled"]},"judged_at":{"type":"string","format":"date-time","nullable":true},"verdict":{"type":"string","enum":["","working","worse","not_working","too_early","unchanged","no_data"]},"recommended":{"type":"string","enum":["","keep","pause","revert","extend","extend30","extend60","extend90"]},"figures":{"type":"object","additionalProperties":true},"decision":{"type":"string","enum":["","keep","pause","revert","extend","extend30","extend60","extend90"]},"decided_by":{"type":"string","description":"Who decided, by name (else e-mail) — set ONLY when `decided_by_kind` is `person`, a current member of this org; empty otherwise. Never the stored `user:<id>` (ADSACTOR r2): the audit trail keeps it."},"decided_by_kind":{"type":["string","null"],"enum":["person","support","agency","former_member","assistant","automatic","integration","other",null],"description":"Who decided, as a kind the screen translates — the same rule as a budget decision's `decided_by_kind` (`automatic` also covers a review settled by the autopilot's own test). `null` while nothing is decided."},"decided_at":{"type":"string","format":"date-time","nullable":true},"can_undo":{"type":"boolean"}}},"AdsReviewDecision":{"type":"object","required":["option"],"properties":{"option":{"type":"string","enum":["keep","pause","revert","extend","extend30","extend60","extend90"]}}},"AdsReviewSpec":{"type":"object","description":"A scheduled review to create (AUTOREVIEW1, docs/1006 §54). `due_on` or `days`.","required":["title"],"properties":{"subject":{"type":"string","enum":["results","change","experiment","quality","funnel"],"default":"results"},"title":{"type":"string","maxLength":200},"question":{"type":"string","maxLength":2000},"due_on":{"type":"string","format":"date"},"days":{"type":"integer","minimum":1,"maximum":366},"measure_from":{"type":"string","format":"date"},"campaign_ids":{"type":"array","maxItems":50,"items":{"type":"string","pattern":"^[0-9]{1,24}$"}},"change_id":{"type":"string","format":"uuid"},"options":{"type":"array","items":{"type":"string","enum":["keep","pause","revert","extend"]}}}},"AdsRsaTest":{"type":"object","description":"RSATEST (za-197) — one A/B test between two responsive search ads of one ad group.","required":["id","ad_group","control_ad","challenger_ad","status","figures"],"properties":{"id":{"type":"string","format":"uuid"},"ad_group":{"type":"string"},"ad_group_name":{"type":"string"},"campaign":{"type":"string"},"control_ad":{"type":"string","description":"The older ad (an ad group ad resource name)."},"challenger_ad":{"type":"string","description":"The newer ad."},"status":{"type":"string","enum":["running","decided","done","stopped"]},"started_on":{"type":"string","format":"date","nullable":true,"description":"First day measured (rotation even); null while rotation waits."},"metric":{"type":"string","enum":["","ctr","conversions"]},"confidence_pct":{"type":"integer","nullable":true},"figures":{"type":"object","description":"`control` / `challenger` {impressions, clicks, conversions}, `days`, `state` (waiting, noWinnerYet, winner), `reason` (minDays, minImpressions, minClicks), `p_value`.","additionalProperties":true},"winner":{"type":"string"},"loser":{"type":"string"},"decided_at":{"type":"string","format":"date-time","nullable":true},"change_id":{"type":"string","format":"uuid","nullable":true,"description":"The change in flight (rotation","then the swap) on the approvals screen.":null},"outcome":{"type":"string"},"reason":{"type":"string","description":"Why a stopped test stopped (adChanged","rotationRefused":null,"swapNotApplied":null,"turnedOff).":null}}},"AdsRsaTestSettings":{"type":"object","description":"RSATEST (za-197) — a connection's RSA A/B test settings (stored, or the Recommended).","required":["rsa_tests","rsa_test_confidence_pct","rsa_test_min_impressions","rsa_test_min_clicks","rsa_test_min_days","rsa_test_metric"],"properties":{"rsa_tests":{"type":"boolean"},"rsa_test_confidence_pct":{"type":"integer","minimum":80,"maximum":99},"rsa_test_min_impressions":{"type":"integer","minimum":100,"maximum":10000000},"rsa_test_min_clicks":{"type":"integer","minimum":1,"maximum":1000000},"rsa_test_min_days":{"type":"integer","minimum":7,"maximum":90},"rsa_test_metric":{"type":"string","enum":["ctr","conversions"]}}},"AdsRule":{"type":"object","required":["id","connection_id","name","metric","window_days","comparator","threshold","currency","action","action_pct","mode","cooldown_days","campaign_ids","hour_utc","enabled","schedule_id","schedule_state","created_by","created_at","updated_at","last_run"],"properties":{"id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"metric":{"type":"string"},"window_days":{"type":"integer"},"comparator":{"type":"string"},"threshold":{"type":"integer"},"currency":{"type":"string","description":"The account currency a money threshold is in."},"action":{"type":"string"},"action_pct":{"type":["integer","null"]},"mode":{"type":"string","enum":["approve","auto"]},"cooldown_days":{"type":"integer"},"campaign_ids":{"type":"array","items":{"type":"string"}},"hour_utc":{"type":"integer"},"enabled":{"type":"boolean"},"schedule_id":{"type":"string","description":"The rule's own Temporal schedule."},"schedule_state":{"type":"string","enum":["ok","pending","paused","error"],"description":"`pending`/`error`: the schedule could not be written yet; the next daily audit writes it."},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"last_run":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/AdsRuleRun"}]}}},"AdsRuleCatalogue":{"type":"object","required":["metrics","windows","comparators","actions","pct_min","pct_max","cooldown_min","cooldown_max","preview_days_max"],"properties":{"metrics":{"type":"array","items":{"type":"object","required":["key","unit"],"properties":{"key":{"type":"string"},"unit":{"type":"string","enum":["money_minor","count","basis_points","percent"]}}}},"windows":{"type":"array","items":{"type":"integer"}},"comparators":{"type":"array","items":{"type":"string"}},"actions":{"type":"array","items":{"type":"string"}},"pct_min":{"type":"integer"},"pct_max":{"type":"integer"},"cooldown_min":{"type":"integer"},"cooldown_max":{"type":"integer"},"preview_days_max":{"type":"integer"}}},"AdsRulePreview":{"type":"object","required":["days","from","to","currency","campaigns_checked","firings","held","stale","latest_day"],"properties":{"days":{"type":"integer"},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"currency":{"type":"string"},"campaigns_checked":{"type":"integer"},"stale":{"type":"boolean"},"latest_day":{"type":["string","null"],"format":"date"},"firings":{"type":"array","items":{"type":"object","required":["day","campaign_id","campaign","value","action"],"properties":{"day":{"type":"string","format":"date"},"campaign_id":{"type":"string"},"campaign":{"type":"string"},"value":{"type":"integer","description":"The reading, in the metric's unit."},"action":{"type":"string"}}}},"held":{"type":"array","items":{"type":"object","required":["campaign_id","campaign","reason"],"properties":{"campaign_id":{"type":"string"},"campaign":{"type":"string"},"reason":{"type":"string","enum":["ownerLocked","learning"]}}}}}},"AdsRuleRun":{"type":"object","required":["id","rule_id","started_at","finished_at","trigger","state","reason","checked","matched","applied","queued","refused","items"],"properties":{"id":{"type":"string","format":"uuid"},"rule_id":{"type":"string","format":"uuid"},"started_at":{"type":"string","format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"},"trigger":{"type":"string","enum":["schedule","manual"]},"state":{"type":"string","enum":["running","ok","skipped","failed"]},"reason":{"type":"string","description":"Why a run was skipped or failed (disabled, notInGoodStanding, killed, staleData, currency, needsReconnect, …)."},"checked":{"type":"integer"},"matched":{"type":"integer"},"applied":{"type":"integer"},"queued":{"type":"integer"},"refused":{"type":"integer"},"items":{"type":"array","items":{"type":"object","required":["campaign_id","campaign","value","outcome","reason","change_id"],"properties":{"campaign_id":{"type":"string"},"campaign":{"type":"string"},"value":{"type":"integer"},"outcome":{"type":"string","enum":["applied","queued","refused","cooldown","ownerLocked","learning","notified","failed","skipped"]},"reason":{"type":"string"},"change_id":{"type":["string","null"],"format":"uuid"}}}}}},"AdsRuleSpec":{"type":"object","description":"A customer rule (za-196, docs/1006 §46): IF `metric` over the last `window_days` days `comparator` `threshold` THEN `action`. Closed sets only. Units of `threshold` by metric: `cost`, `cost_without_conversions`, `cpa` — integer minor units of the account currency; `clicks`, `impressions`, `conversions` — whole counts; `ctr`, `conversion_rate` — basis points (1% = 100); `roas` — percent (conversion value / cost x 100). A rate with nothing under it (no impressions, clicks, conversions or cost) has no reading and never matches. `conversions`, `cpa`, `conversion_rate` and `cost_without_conversions` read the RECORDED conversions (every conversion the network recorded, including those not used for bidding; Microsoft All conversions), never the narrower biddable figure; a day the network did not report has no reading and is never read as zero.","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"metric":{"type":"string","enum":["cost","cost_without_conversions","clicks","impressions","conversions","cpa","ctr","conversion_rate","roas"]},"window_days":{"type":"integer","enum":[1,3,7,14,30]},"comparator":{"type":"string","enum":["gt","gte","lt","lte"]},"threshold":{"type":"integer","minimum":0,"maximum":1000000000000},"action":{"type":"string","enum":["notify","pause_campaign","budget_down","budget_up"]},"action_pct":{"type":["integer","null"],"minimum":1,"maximum":50,"description":"The budget step, for budget_down / budget_up only."},"mode":{"type":"string","enum":["approve","auto"],"description":"Default approve: each change waits for a person."},"cooldown_days":{"type":"integer","minimum":1,"maximum":30,"description":"Default 7."},"campaign_ids":{"type":"array","maxItems":1000,"description":"Campaigns the rule reads; empty = every enabled campaign.","items":{"type":"string","pattern":"^[0-9]{1,20}$"}},"hour_utc":{"type":"integer","minimum":0,"maximum":23,"description":"When its daily schedule fires (default 11, after the morning audit stores yesterday's figures)."},"enabled":{"type":"boolean","description":"Default true."}}},"AdsSavedView":{"type":"object","required":["id","org_id","name","params","chart","created_by","created_at","updated_at","mail_cadence","mail_recipients","mail_next_run_at","mail_last_sent_at","mail_last_error"],"properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"name":{"type":"string","maxLength":80},"params":{"$ref":"#/components/schemas/AdsSavedViewParams"},"chart":{"$ref":"#/components/schemas/AdsSavedViewChart"},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true},"mail_cadence":{"$ref":"#/components/schemas/AdsSavedViewCadence"},"mail_recipients":{"type":"array","items":{"type":"string","format":"uuid"}},"mail_next_run_at":{"type":"string","format":"date-time","nullable":true},"mail_last_sent_at":{"type":"string","format":"date-time","nullable":true},"mail_last_error":{"type":"string","description":"`notInGoodStanding`, `mailRefused` (a recipient refused fewer than 3 times this period: retried within the hour), `recipientRefused` (a recipient refused 3 times, left until the next period), `renderFailed` (retried within the hour), `renderGaveUp` (could not be prepared 3 times: tried again at the next scheduled send), `noRecipients` (nobody on the list can still receive it: nothing sent) or empty."}}},"AdsSavedViewCadence":{"type":"string","enum":["","daily","weekly","monthly"]},"AdsSavedViewChart":{"type":"object","additionalProperties":false,"properties":{"metric":{"type":"string","enum":["cost","value","roas","conversions","cpa","ctr","cpc","clicks","impressions","convRate"]},"board":{"type":"string","enum":["network","connection","campaign","country","device","offering","client"]}}},"AdsSavedViewInput":{"type":"object","required":["name","params"],"properties":{"org_id":{"type":"string","format":"uuid"},"name":{"type":"string","maxLength":80},"params":{"$ref":"#/components/schemas/AdsSavedViewParams"},"chart":{"$ref":"#/components/schemas/AdsSavedViewChart"},"mail_cadence":{"$ref":"#/components/schemas/AdsSavedViewCadence"},"mail_recipients":{"type":"array","maxItems":20,"items":{"type":"string","format":"uuid"}}}},"AdsSavedViewParams":{"type":"object","description":"The `/ads/analytics` filters, exactly the analytics API's query parameters (only those set).","additionalProperties":false,"properties":{"range":{"type":"string","enum":["7d","30d","90d","ytd","12m","custom"]},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"compare":{"type":"string","enum":["previous","year","none"]},"grain":{"type":"string","enum":["day","week","month"]},"network":{"type":"string"},"connection":{"type":"string"},"campaign":{"type":"string"},"country":{"type":"string"},"device":{"type":"string"},"offering":{"type":"string"},"client":{"type":"string"},"currency":{"type":"string"}}},"AdsSavedViewPatch":{"type":"object","properties":{"name":{"type":"string","maxLength":80},"params":{"$ref":"#/components/schemas/AdsSavedViewParams"},"chart":{"$ref":"#/components/schemas/AdsSavedViewChart"},"mail_cadence":{"$ref":"#/components/schemas/AdsSavedViewCadence"},"mail_recipients":{"type":"array","maxItems":20,"items":{"type":"string","format":"uuid"}}}},"AdsSavedViewRecipient":{"type":"object","required":["user_id","name","email"],"properties":{"user_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"email":{"type":"string"}}},"AdsSavedViewSent":{"type":"object","required":["view_id","recipients"],"properties":{"view_id":{"type":"string","format":"uuid"},"recipients":{"type":"integer"}}},"AdsScoreRow":{"type":"object","description":"za-214 — one automatic change's stated expected effect and its measured 14-day verdict. Money in micros of `currency`; outcomes in thousandths.","required":["id","source","change_id","action","campaign_id","campaign","applied_at","due_at","expected","basis","outcomes_before_milli","outcomes_after_milli","cost_before_micros","cost_after_micros","currency","change_bp","verdict","scored_at","undo_state","undo_at","suggestion_id"],"properties":{"id":{"type":"string","format":"uuid"},"source":{"type":"string","enum":["finding","change"]},"change_id":{"type":"string","format":"uuid","nullable":true},"action":{"type":"string","description":"The action class (negatives, keywords, pauses, budgets, bids, …)."},"campaign_id":{"type":"string","description":"Blank: the change names no campaign (the whole account is measured)."},"campaign":{"type":"string"},"applied_at":{"type":"string","format":"date-time"},"due_at":{"type":"string","format":"date-time"},"expected":{"type":"object","required":["metric","direction","size_pct","harm_pct","window_days"],"properties":{"metric":{"type":"string","enum":["outcomes","cost_per_outcome"]},"direction":{"type":"string","enum":["up","down"]},"size_pct":{"type":"integer"},"harm_pct":{"type":"integer"},"window_days":{"type":"integer"}}},"basis":{"type":"string","enum":["","first_party","google"]},"outcomes_before_milli":{"type":"integer","format":"int64"},"outcomes_after_milli":{"type":"integer","format":"int64"},"cost_before_micros":{"type":"integer","format":"int64"},"cost_after_micros":{"type":"integer","format":"int64"},"currency":{"type":"string"},"change_bp":{"type":"integer","nullable":true},"verdict":{"type":"string","enum":["pending","better","same","worse","no_data","gone"]},"scored_at":{"type":"string","format":"date-time","nullable":true},"undo_state":{"type":"string","enum":["","proposed","undoing","undone","owner_lock","freeze","standing","not_undoable","failed","expired"]},"undo_at":{"type":"string","format":"date-time","nullable":true},"suggestion_id":{"type":"string","format":"uuid","nullable":true}}},"AdsSeasonalPlanner":{"type":"object","description":"The seasonal planner per country for one connection (za-N16, docs/1006 §81).","required":["connection_id","currency","measured_on","settings","countries","plans"],"properties":{"connection_id":{"type":"string","format":"uuid"},"currency":{"type":"string","description":"ISO 4217 of the ad account"},"measured_on":{"type":["string","null"],"format":"date"},"settings":{"type":"array","items":{"type":"object","required":["key","value","recommended","min","max","customised"],"properties":{"key":{"type":"string"},"value":{"type":["integer","string"]},"recommended":{"type":["integer","string"]},"min":{"type":["integer","null"]},"max":{"type":["integer","null"]},"customised":{"type":"boolean"}}}},"countries":{"type":"array","items":{"type":"object","required":["country","source","months","conv_rate","clicks","months_seen","conversions","measured_on"],"properties":{"country":{"type":"string","description":"ISO 3166-1 alpha-2"},"source":{"type":"string","enum":["history","planner","none"]},"months":{"type":"array","description":"Twelve demand indexes, January first (100 = the average month).","items":{"type":["integer","null"]}},"conv_rate":{"type":"array","description":"Twelve conversion-rate indexes, January first (history only).","items":{"type":["integer","null"]}},"clicks":{"type":"integer"},"months_seen":{"type":"integer"},"conversions":{"type":"integer"},"measured_on":{"type":"string","format":"date"}}}},"plans":{"type":"array","items":{"type":"object","required":["id","country","kind","starts_on","ends_on","index_pct","source","budget_pct","budgets","bid_modifier_pct","bid_ends_on","state","budget_change_id","restore_change_id","bid_change_id"],"properties":{"id":{"type":"string","format":"uuid"},"country":{"type":"string"},"kind":{"type":"string","enum":["peak","quiet"]},"starts_on":{"type":"string","format":"date"},"ends_on":{"type":"string","format":"date"},"index_pct":{"type":"integer"},"source":{"type":"string","enum":["history","planner","none"]},"budget_pct":{"type":"integer","description":"The budget change in percent (negative = lower)."},"budgets":{"type":"array","items":{"type":"object","properties":{"campaign":{"type":"string"},"name":{"type":"string"},"budget":{"type":"string"},"from_micros":{"type":"integer"},"to_micros":{"type":"integer"}}}},"bid_modifier_pct":{"type":["integer","null"],"description":"The seasonality adjustment's conversion-rate modifier in percent."},"bid_ends_on":{"type":["string","null"],"format":"date"},"state":{"type":"string","enum":["proposed","active","restoring","done","expired","dismissed"]},"budget_change_id":{"type":["string","null"],"format":"uuid"},"restore_change_id":{"type":["string","null"],"format":"uuid"},"bid_change_id":{"type":["string","null"],"format":"uuid"}}}}}},"AdsServerEvent":{"type":"object","required":["event_id","kind","occurred_at","received_at","value_minor","currency","has_email_hash","click_ids","consent","fanned_out_at","deliveries"],"properties":{"event_id":{"type":"string"},"kind":{"type":"string"},"occurred_at":{"type":"string","format":"date-time"},"received_at":{"type":"string","format":"date-time"},"value_minor":{"type":"integer","nullable":true},"currency":{"type":"string"},"has_email_hash":{"type":"boolean"},"click_ids":{"type":"array","items":{"type":"string","enum":["gclid","gbraid","wbraid","msclkid","fbclid","twclid"]},"description":"Which click ids it carried (never their values)."},"consent":{"type":"string"},"fanned_out_at":{"type":"string","format":"date-time","nullable":true},"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/AdsServerEventDelivery"}}}},"AdsServerEventDelivery":{"type":"object","required":["connection_id","platform","status","reason","uploaded_at"],"properties":{"connection_id":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["google","microsoft","meta","x"]},"status":{"type":"string","enum":["waiting","not_sent","pending","uploaded","failed","skipped"]},"reason":{"type":"string"},"uploaded_at":{"type":"string","format":"date-time","nullable":true}}},"AdsServerEventIn":{"type":"object","required":["event_id","kind","occurred_at"],"properties":{"event_id":{"type":"string","pattern":"^[\\w.:\\-/#]{1,128}$","description":"Your own id for this conversion (the order / trial / lead id). The dedupe key: per organisation here, and the transaction / event id at every network."},"kind":{"type":"string","enum":["purchase","trial","lead","signup","activation","retained7","retained30","upgrade","free_listing"]},"occurred_at":{"type":"string","format":"date-time"},"value_minor":{"type":"integer","nullable":true,"minimum":0,"description":"Integer minor units (4999 = 49.99). A `free_listing` carries none."},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$","description":"ISO 4217; required with `value_minor`."},"gclid":{"type":"string","maxLength":200},"gbraid":{"type":"string","maxLength":200},"wbraid":{"type":"string","maxLength":200},"msclkid":{"type":"string","maxLength":200},"fbclid":{"type":"string","maxLength":200,"description":"Meta's click id (the `fbclid` query parameter)."},"twclid":{"type":"string","maxLength":200,"description":"X's click id (the `twclid` query parameter)."},"email":{"type":"string","format":"email","writeOnly":true,"description":"Hashed at the door (SHA-256 of the normalised address); never stored."},"email_hash":{"type":"string","pattern":"^[0-9a-fA-F]{64}$","description":"SHA-256 of the lower-cased","trimmed address":null,"if you hash it yourself.":null},"consent":{"type":"string","enum":["","GRANTED","DENIED","UNSPECIFIED"]}}},"AdsServerEventList":{"type":"object","required":["data","networks","waiting"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsServerEvent"}},"networks":{"type":"array","items":{"$ref":"#/components/schemas/AdsServerEventNetwork"}},"waiting":{"type":"integer"}}},"AdsServerEventNetwork":{"type":"object","required":["connection_id","platform","external_id","label","status"],"properties":{"connection_id":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["google","microsoft","meta","x"]},"external_id":{"type":"string"},"label":{"type":"string"},"status":{"type":"string","enum":["active","paused"]}}},"AdsServerEventsReceived":{"type":"object","required":["created","duplicates","duplicate_event_ids","fan_out_started"],"properties":{"created":{"type":"integer"},"duplicates":{"type":"integer","description":"Events whose `event_id` was already stored (or repeated in this request)."},"duplicate_event_ids":{"type":"array","items":{"type":"string"},"description":"The first 50 duplicate ids."},"fan_out_started":{"type":"boolean","description":"False only when nothing was new, or the background fan-out could not start (it then runs with the daily step)."}}},"AdsShield":{"type":"object","required":["org_id","enabled","avg_cpc_minor","currency","conversion_paths","period_days","clicks","suspected","converted","by_reason","estimated_wasted","suspect_at","reasons_known","claim_window_days","retention_days"],"properties":{"org_id":{"type":"string","format":"uuid"},"enabled":{"type":"boolean"},"avg_cpc_minor":{"type":"integer"},"currency":{"type":"string"},"conversion_paths":{"type":"array","items":{"type":"string"}},"period_days":{"type":"integer"},"clicks":{"type":"integer"},"suspected":{"type":"integer"},"converted":{"type":"integer"},"by_reason":{"type":"object","additionalProperties":{"type":"integer"}},"estimated_wasted":{"type":"array","items":{"type":"object","required":["currency","amount_minor"],"properties":{"currency":{"type":"string"},"amount_minor":{"type":"integer"}}}},"suspect_at":{"type":"integer"},"reasons_known":{"type":"array","items":{"type":"string"}},"claim_window_days":{"type":"integer"},"retention_days":{"type":"integer"},"estimate_sources":{"type":"object","description":"How many estimated costs came from Google's measured average CPC for the click's keyword (`keyword_day`) or campaign (`campaign_day`) that day, or from the organisation's own `avg_cpc` — every one is an estimate.","additionalProperties":{"type":"integer"}},"exclusions_enabled":{"type":"boolean"},"placements_enabled":{"type":"boolean","description":"The placement guard's switch (za-N18)."},"placement_guard":{"type":"array","description":"Per connection, what the placement guard's last pass read (za-N18).","items":{"type":"object","required":["connection_id","platform","skipped","listed","unexcludable","basis","first_batch","tracking_hold","junk","collided","checked_at"],"properties":{"connection_id":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["google","microsoft","meta"],"description":"PLACEGUARD2: the network the pass ran on."},"skipped":{"type":"string","enum":["","vendorNotGranted"],"description":"`vendorNotGranted` = Meta refused the per-publisher read: our Meta app lacks the `brand_safety_third_party_partners` capability, so nothing could be listed."},"listed":{"type":"integer","description":"Meta only: publishers put on the connection's Zinn-held block list in the pass (nothing is sent to Meta)."},"unexcludable":{"type":"integer","description":"Microsoft only: spending placements with no website URL (an app) — Microsoft excludes websites only."},"basis":{"type":"string","enum":["first_party","platform"],"description":"`first_party` = only conversions on the actions that stand for the customer's real outcomes count as a result (a platform conversion alone protects nothing); `platform` = no such mapping, the network's conversions are what there is."},"first_batch":{"type":"boolean","description":"Nobody has decided a placement exclusion yet (every proposal waits for a person, even on autopilot), or proposals of a za-N18 class nobody on this connection has decided yet are waiting for a person. Each class is unlocked only by a decision on that class: apps, YouTube, Performance Max account-level, and each junk class (children's channels, parked sites, made-for-ads sites) separately."},"tracking_hold":{"type":"boolean","description":"The tracking-truth check holds the account: every proposal waits for a person."},"junk":{"type":"integer","description":"Junk-class placements proposed in the pass."},"collided":{"type":"integer","description":"Placements that are the customer's own site or brand — never excluded."},"checked_at":{"type":["string","null"],"format":"date-time"}}}},"exclusions":{"type":"object","description":"The organisation's shield exclusions counted by status.","additionalProperties":{"type":"integer"}}}},"AdsShieldClaim":{"type":"object","required":["id","connection_id","account","account_label","month","status","clicks","estimated_cost_minor","currency","filed_at","reference","credited_minor","credit_checked_at","credit_note","google_form_url"],"properties":{"id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid"},"account":{"type":"string","description":"The Google Ads customer id."},"account_label":{"type":"string"},"month":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}$"},"status":{"type":"string","enum":["ready","filed","credited","declined"]},"clicks":{"type":"integer"},"estimated_cost_minor":{"type":"integer"},"currency":{"type":"string"},"filed_at":{"type":["string","null"],"format":"date-time"},"reference":{"type":"string"},"credited_minor":{"type":["integer","null"],"description":"Google's invalid-activity credit for the month, integer minor units of `currency`: read from the account's invoices, or recorded by a person from Google's answer (`credit_note` = `recorded_by_person`). `0` once declined; null = no answer yet."},"credit_checked_at":{"type":["string","null"],"format":"date-time"},"credit_note":{"type":"string","description":"`no_monthly_invoicing` when the account has no invoices to read (record Google's answer by hand); `no_credit_on_invoices` when the three invoices after the month closed with no credit (declined); `recorded_by_person` when a person recorded it."},"google_form_url":{"type":"string","format":"uri","description":"Google's invalid-click investigation form."}}},"AdsShieldClick":{"type":"object","required":["id","site_id","host","platform","click_kind","clicked_at","score","reasons","verdict","asn","asn_name","ip_masked","estimated_cost_minor","currency","evidence_available","evidence_expires_at"],"properties":{"id":{"type":"string","format":"uuid"},"site_id":{"type":"string","format":"uuid"},"host":{"type":"string"},"platform":{"type":"string","enum":["google","microsoft","meta","tiktok","linkedin","x","pinterest"]},"click_kind":{"type":"string","enum":["gclid","msclkid","fbclid","ttclid","li_fat_id","twclid","epik"]},"clicked_at":{"type":"string","format":"date-time"},"score":{"type":"integer","minimum":0,"maximum":100},"reasons":{"type":"array","items":{"type":"string","enum":["bot_ua","datacenter","repeat_ip","repeat_network","network","zero_dwell","no_js","geo_mismatch","converted"]}},"verdict":{"type":"string","enum":["suspected","clean","converted"]},"asn":{"type":["integer","null"]},"asn_name":{"type":"string"},"ip_masked":{"type":"string"},"estimated_cost_minor":{"type":["integer","null"]},"currency":{"type":"string"},"evidence_available":{"type":"boolean"},"evidence_expires_at":{"type":"string","format":"date-time"},"cost_source":{"type":"string","enum":["","avg_cpc","keyword_day","campaign_day"]},"campaign_id":{"type":"string"},"campaign_name":{"type":"string"},"keyword":{"type":"string"},"ip_country":{"type":"string","description":"The address's country (IP Geolocation by DB-IP)."},"google_country":{"type":"string","description":"The country Google placed the click in."}}},"AdsShieldExclusion":{"type":"object","required":["id","connection_id","platform","campaign_id","kind","value_masked","measured_cost_minor","currency","clicks","criterion","display_name","reason","junk_class","status","level","last_cost_at","applied_at","removed_at","can_undo","change_id","remove_change_id","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid"},"campaign_id":{"type":"string","description":"Empty for an account-level exclusion."},"kind":{"type":"string","enum":["ip","placement","audience"]},"value_masked":{"type":"string","description":"An IP exclusion as its network (/24 or /48) — never the whole address; a placement as its URL; an audience as its user list / interest resource name."},"level":{"type":"string","enum":["campaign","account"],"description":"`account` = an account-level placement exclusion (how Google takes one for Performance Max)."},"last_cost_at":{"type":["string","null"],"format":"date-time","description":"The newest suspected click from this source that cost money; within the connection's shield_stale_days it is never rotated out."},"applied_at":{"type":["string","null"],"format":"date-time"},"removed_at":{"type":["string","null"],"format":"date-time","description":"When it was rotated out; a source that comes back is judged only on clicks after this."},"can_undo":{"type":"boolean","description":"The network holds it and no removal is on its way — or it is `listed` (Meta: Undo only takes it off the list): the one-click Undo works."},"measured_cost_minor":{"type":"integer","description":"What the source cost the campaign (estimated, integer minor units)."},"currency":{"type":"string"},"clicks":{"type":"integer"},"criterion":{"type":"string","enum":["","placement","mobile_application","youtube_channel","youtube_video","user_list","user_interest"],"description":"Which criterion `value_masked` fills (za-N18): a website URL, an app id, a YouTube channel or video id, an audience; empty for an IP."},"display_name":{"type":"string","description":"The placement's name as Google shows it (an app's or a channel's title)."},"reason":{"type":"string","enum":["","waste","junk"],"description":"Why a placement was proposed: it spent with no result (`waste`) or belongs to a junk class (`junk`)."},"junk_class":{"type":"string","enum":["","mobile_app","kids","parked","mfa"],"description":"`parked` = a parked / for-sale domain page; `mfa` = a made-for-ads site (two or more named signals; always approve-first)."},"platform":{"type":"string","enum":["google","microsoft","meta","linkedin","tiktok","x","pinterest","amazon","chatgpt"],"description":"PLACEGUARD2: the connection's network. A Meta exclusion is only ever `listed`."},"status":{"type":"string","enum":["queued","applied","rejected","removed","undone","failed","listed"],"description":"`listed` (Meta) = on the connection's Zinn-held block list: nothing was sent, because Meta's API does not let us apply a block list (it needs app permissions our Meta app does not hold). The customer downloads it (`getAdsShieldMetaBlockList`)."},"change_id":{"type":["string","null"],"format":"uuid","description":"The ad-account change that adds it (approve / Undo there)."},"remove_change_id":{"type":["string","null"],"format":"uuid","description":"The change that rotates it out, when one is waiting or done."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"AdsSignalValue":{"type":"object","description":"What one signal is worth on the account (za-155). Money is minor units of `currency`; rates are basis points.","required":["kind","action","target_action","auto","override_minor","cohort","paid","unjoined","measured_bp","prior_bp","blended_bp","revenue_minor","value_minor","currency","network_minor","proposed_minor","change_id","status","reason","measured_at","sent_at"],"properties":{"kind":{"type":"string","enum":["signup","activation"]},"action":{"type":"string","description":"The customer's chosen conversion action (\"\" = the upload action for the kind)."},"target_action":{"type":"string","readOnly":true,"description":"The conversion action the value is set on (\"\" = none)."},"auto":{"type":"boolean"},"override_minor":{"type":["integer","null"],"format":"int64","description":"The customer's own value; null = the measured one."},"cohort":{"type":"integer","readOnly":true},"paid":{"type":"integer","readOnly":true},"unjoined":{"type":"integer","readOnly":true},"measured_bp":{"type":["integer","null"],"readOnly":true},"prior_bp":{"type":"integer","readOnly":true},"blended_bp":{"type":"integer","readOnly":true},"revenue_minor":{"type":["integer","null"],"format":"int64","readOnly":true},"value_minor":{"type":["integer","null"],"format":"int64","readOnly":true},"currency":{"type":"string","pattern":"^([A-Z]{3})?$","readOnly":true},"network_minor":{"type":["integer","null"],"format":"int64","readOnly":true},"proposed_minor":{"type":["integer","null"],"format":"int64","readOnly":true},"change_id":{"type":["string","null"],"format":"uuid","readOnly":true},"status":{"type":"string","enum":["sent","queued","unchanged","refused","failed","off","no_action","no_revenue","unsupported","unreadable","not_measured"],"readOnly":true},"reason":{"type":"string","readOnly":true},"measured_at":{"type":["string","null"],"format":"date-time","readOnly":true},"sent_at":{"type":["string","null"],"format":"date-time","readOnly":true}}},"AdsSignalValues":{"type":"object","required":["connection_id","business_type","wait_days","window_days","prior_weight","change_pct","signals"],"properties":{"connection_id":{"type":"string","format":"uuid"},"business_type":{"type":"string"},"wait_days":{"type":"integer","description":"Days a signal waits to pay before it counts in the rate."},"window_days":{"type":"integer"},"prior_weight":{"type":"integer","description":"Pseudo-signals the business type's default counts as."},"change_pct":{"type":"integer","description":"A value is re-sent only when it moved by more than this."},"signals":{"type":"array","maxItems":2,"items":{"$ref":"#/components/schemas/AdsSignalValue"}}}},"AdsSignalValuesSettings":{"type":"object","required":["signals"],"properties":{"signals":{"type":"array","minItems":1,"maxItems":2,"items":{"type":"object","required":["kind"],"properties":{"kind":{"type":"string","enum":["signup","activation"]},"auto":{"type":"boolean"},"override_minor":{"type":["integer","null"],"format":"int64","minimum":0,"maximum":10000000},"action":{"type":"string","maxLength":200}}}}}},"AdsSiteGuard":{"type":"object","description":"za-N1 (docs/1006 §91): an uptime monitor guarding an ad account. `state` is `watching` (nothing held) or `holding` (campaigns paused by the guard, listed in `held`).","required":["id","connection_id","monitor","campaign_ids","enabled","auto","hold_reason","state","held_at","released_at","held","last_result","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid"},"monitor":{"$ref":"#/components/schemas/AdsSiteGuardMonitor"},"campaign_ids":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"auto":{"type":"boolean","description":"za-207: made by the platform for a site we host (hosting-aware ads, default on). Its scope is the campaigns whose ads' final URL lands on the site. Deleting one switches it off instead (it would be made again at the next outage)."},"hold_reason":{"type":"string","enum":["","down","slow"],"description":"za-207 — why the current hold began."},"state":{"type":"string","enum":["watching","holding"]},"held_at":{"type":["string","null"],"format":"date-time"},"released_at":{"type":["string","null"],"format":"date-time"},"held":{"type":"array","items":{"type":"object","required":["campaign_id","name","change_id"],"properties":{"campaign_id":{"type":"string"},"name":{"type":"string"},"change_id":{"type":"string"}}}},"last_result":{"type":"object","description":"The last sync: `at`, `direction` (`pause` · `resume`), `paused` / `resumed` counts, `refused` (`[{campaign_id, code}]`) and `reason` when it was skipped.","additionalProperties":true},"created_at":{"type":"string","format":"date-time"}}},"AdsSiteGuardMonitor":{"type":"object","description":"One of the org's own uptime monitors (za-N1).","required":["id","url","label","state"],"properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"label":{"type":"string"},"state":{"type":"string","description":"`unknown` · `up` · `down` (the monitor's own state)."}}},"AdsSiteGuardSettings":{"type":"object","description":"za-207 (docs/1006 §64a): hosting-aware ads for one account. Every number is the customer's own; `recommended` holds our defaults (for \"Reset to recommended\") and `bounds` the accepted range. The guard reads the stored values.","required":["auto","down_minutes","slow_ms","recovery_minutes","recommended","bounds"],"properties":{"auto":{"type":"boolean","description":"Pause the ads of a site we host while it is down or slow (default on)."},"down_minutes":{"type":"integer","minimum":1,"maximum":1440,"description":"Minutes down (or slow) before the ads pause."},"slow_ms":{"type":"integer","minimum":0,"maximum":60000,"description":"A response slower than this counts as slow; 0 = never pause for slowness."},"recovery_minutes":{"type":"integer","minimum":1,"maximum":1440,"description":"Minutes healthy before the ads resume."},"recommended":{"type":"object","required":["auto","down_minutes","slow_ms","recovery_minutes"],"properties":{"auto":{"type":"boolean"},"down_minutes":{"type":"integer"},"slow_ms":{"type":"integer"},"recovery_minutes":{"type":"integer"}}},"bounds":{"type":"object","additionalProperties":{"type":"object","required":["min","max"],"properties":{"min":{"type":"integer"},"max":{"type":"integer"}}}}}},"AdsSiteLanguage":{"type":"object","description":"One language of the customer's website (za-106) and its own address.","required":["code"],"properties":{"code":{"type":"string","description":"Google's language code (fr, pt, iw, zh_CN)."},"url":{"type":"string","description":"The address of the site in that language."},"sources":{"type":"array","description":"Where it was found (html_lang, hreflang, locale_url). Detected rows only.","items":{"type":"string","enum":["html_lang","hreflang","locale_url"]}}}},"AdsSiteTag":{"type":"object","required":["id","org_id","site_host","public_key","google_ads_id","ga4_id","google_labels","microsoft_uet_id","meta_pixel_id","consent_default","wait_for_update_ms","keep_click_ids","enabled","version","updated_at","install"],"properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"site_host":{"type":"string"},"public_key":{"type":"string","description":"Public (it is in the page source); never an API credential."},"google_ads_id":{"type":"string"},"ga4_id":{"type":"string"},"google_labels":{"type":"object","additionalProperties":{"type":"string"}},"microsoft_uet_id":{"type":"string"},"meta_pixel_id":{"type":"string"},"consent_default":{"type":"string","enum":["denied_eea","denied","granted"]},"wait_for_update_ms":{"type":"integer"},"keep_click_ids":{"type":"boolean"},"enabled":{"type":"boolean"},"version":{"type":"integer"},"updated_at":{"type":["string","null"],"format":"date-time"},"served":{"type":"object","description":"za-126: the ids this site actually serves — its own, else the organisation's tracking hub's.","properties":{"google_ads_id":{"type":"string"},"ga4_id":{"type":"string"},"google_labels":{"type":"object","additionalProperties":{"type":"string"}},"microsoft_uet_id":{"type":"string"},"meta_pixel_id":{"type":"string"}}},"install":{"$ref":"#/components/schemas/AdsSiteTagInstall"},"shield":{"type":"object","description":"What the click shield has seen through this tag (SHIELDTAG, docs/1006.d/features/za-316-shieldtag.md): when the last paid-click landing beacon arrived and the clicks scored from it in 30 days. Set on the list and the single read; the tag protects a site we do not host as soon as it is installed and the organisation has the shield.","required":["last_landing_at","clicks_30d","suspected_30d"],"properties":{"last_landing_at":{"type":"string","format":"date-time","nullable":true},"clicks_30d":{"type":"integer","minimum":0},"suspected_30d":{"type":"integer","minimum":0}}}}},"AdsSiteTagCreate":{"allOf":[{"$ref":"#/components/schemas/AdsSiteTagSettings"},{"type":"object","required":["site_host"],"properties":{"org_id":{"type":"string","format":"uuid","description":"Required when you manage more than one organisation."}}}]},"AdsSiteTagFirstParty":{"type":"object","required":["status","path","route_pattern","snippet"],"properties":{"status":{"type":"string","enum":["off","ok","needs_token","failed"]},"path":{"type":"string","description":"The path on the site host: /ztag."},"provider":{"type":"string"},"zone_name":{"type":"string"},"route_pattern":{"type":"string"},"script_name":{"type":"string"},"last_error":{"type":"string","description":"An error code: tokenRejected, permissionMissing, zoneNotFound, rateLimited, unavailable, unexpected or routeMissing; empty when ok."},"token_hint":{"type":"string","description":"The token's last four characters","never the token.":null},"checked_at":{"type":"string","format":"date-time","nullable":true},"snippet":{"type":"string"}}},"AdsSiteTagFirstPartyConnect":{"type":"object","additionalProperties":false,"required":["token"],"properties":{"token":{"type":"string","writeOnly":true,"minLength":20,"maxLength":200}}},"AdsSiteTagInstall":{"type":"object","required":["script_url","snippet_html","conversion_example","shopify_pixel","gtm_container_path","data_layer_example"],"properties":{"script_url":{"type":"string","format":"uri"},"snippet_html":{"type":"string","description":"The two lines to paste into every page's head."},"conversion_example":{"type":"string"},"shopify_pixel":{"type":"string","description":"Code for Shopify admin → Settings → Customer events → Add custom pixel."},"gtm_container_path":{"type":"string"},"data_layer_example":{"type":"string"}}},"AdsSiteTagList":{"type":"object","required":["items","suggested_hosts"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AdsSiteTag"}},"suggested_hosts":{"type":"array","items":{"type":"string"}}}},"AdsSiteTagSettings":{"type":"object","description":"The editable settings of a site tag (za-128, docs/1006 §84).","properties":{"site_host":{"type":"string","maxLength":253,"example":"shop.example.com"},"google_ads_id":{"type":"string","description":"Google Ads tag id, AW- plus digits; empty for none.","example":"AW-123456789"},"ga4_id":{"type":"string","description":"GA4 measurement id, G- plus letters/digits; empty for none."},"google_labels":{"type":"object","description":"Google Ads conversion label per outcome kind (purchase, trial, lead, signup, activation, retained7, retained30, upgrade, free_listing). An empty label removes the kind.","additionalProperties":{"type":"string"}},"microsoft_uet_id":{"type":"string","description":"Microsoft Advertising UET tag id (digits)."},"meta_pixel_id":{"type":"string","description":"Meta pixel id (digits). Loaded only once ad consent is granted."},"consent_default":{"type":"string","enum":["denied_eea","denied","granted"],"description":"Ad consent before the visitor's banner answers: denied in the EEA, UK and Switzerland (default), denied everywhere, or granted."},"wait_for_update_ms":{"type":"integer","minimum":0,"maximum":5000,"description":"How long Google's tags wait for the banner's answer."},"keep_click_ids":{"type":"boolean","description":"Keep gclid, gbraid, wbraid, msclkid and fbclid in a first-party cookie for 90 days, only after ad consent."},"enabled":{"type":"boolean"}}},"AdsSiteTagUpdate":{"$ref":"#/components/schemas/AdsSiteTagSettings"},"AdsSmartBidHealthItem":{"type":"object","description":"za-329: one conversion-health check that holds a step up onto a conversion strategy. `failing`: the check found a problem (fix it); `unreadable`: it could not be read, which holds too (never a pass).","required":["code","state","status","network","category","actions","count"],"properties":{"code":{"type":"string","enum":["primary_7d","tracking","tracking_reason","dedupe","free_primary","duplicate_primary","enhanced","uploads"]},"state":{"type":"string","enum":["failing","unreadable"]},"status":{"type":"string","enum":["","gap","unreadable","not_checked"],"description":"tracking only (every other check serves `\"\"`): `gap` or `unreadable` is the status of a tracking check that ran and failed (state `failing`); `not_checked` means no tracking check ran in the last 2 days (state `unreadable`)."},"network":{"type":"string","description":"dedupe: the network's name."},"category":{"type":"string","description":"duplicate_primary: the conversion category counted twice, as Google's ConversionActionCategory code (`PURCHASE`, `ADD_TO_CART`, ...); a client translates it and shows an unknown code as a generic word."},"actions":{"type":"array","items":{"type":"string"},"description":"free_primary / duplicate_primary / tracking_reason: the conversion actions' names."},"count":{"type":"integer","description":"uploads: open upload or goal problems; tracking_reason: actions with a tracking fault."},"have":{"type":"number","description":"primary_7d (stored-figures networks): the biddable (primary) conversions the network counted in the 7 days."},"recorded":{"type":"number","description":"MSALLCONV, primary_7d (stored-figures networks): every conversion the network RECORDED in the 7 days, biddable or not (Microsoft AllConversions). Above `have`: the conversions are recorded on goals kept out of bidding."}}},"AdsSocial":{"type":"object","required":["accounts"],"properties":{"accounts":{"type":"array","items":{"type":"object","required":["connection_id","platform","label","currency","levers","review","pending"],"properties":{"connection_id":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["x","meta","tiktok","pinterest"]},"label":{"type":"string"},"currency":{"type":"string"},"levers":{"type":"array","items":{"type":"object","required":["lever","state","where"],"properties":{"lever":{"type":"string","enum":["audiences","placements","creatives","budgets"]},"state":{"type":"string","enum":["judged","elsewhere","not_offered"]},"where":{"type":"string"}}}},"review":{"type":"object","nullable":true,"required":["at","ok","audiences","creatives","waste_micros","needs_permission","held","proposed","applied","findings"],"properties":{"at":{"type":"string","format":"date-time"},"ok":{"type":"boolean"},"audiences":{"type":"integer"},"creatives":{"type":"integer"},"waste_micros":{"type":"integer"},"needs_permission":{"type":"boolean"},"held":{"type":"boolean"},"proposed":{"type":"integer"},"applied":{"type":"integer"},"findings":{"type":"array","items":{"type":"object","required":["lever","id","name","cost_micros","clicks"],"properties":{"lever":{"type":"string","enum":["audiences","creatives"]},"id":{"type":"string"},"name":{"type":"string"},"cost_micros":{"type":"integer"},"clicks":{"type":"integer"}}}}}},"pending":{"type":"integer"}}}}}},"AdsStockPauseSettings":{"type":"object","description":"za-N2 out-of-stock pause settings of one connection. Each value is the customer's own; `recommended` holds our Recommended defaults and `bounds` the accepted range (minutes).","required":["stock_pause_auto","stock_pause_hold_minutes","stock_resume_hold_minutes","recommended","bounds"],"properties":{"stock_pause_auto":{"type":"boolean"},"stock_pause_hold_minutes":{"type":"integer"},"stock_resume_hold_minutes":{"type":"integer"},"recommended":{"type":"object","required":["stock_pause_auto","stock_pause_hold_minutes","stock_resume_hold_minutes"],"properties":{"stock_pause_auto":{"type":"boolean"},"stock_pause_hold_minutes":{"type":"integer"},"stock_resume_hold_minutes":{"type":"integer"}}},"bounds":{"type":"object","additionalProperties":{"type":"object","required":["min","max"],"properties":{"min":{"type":"integer"},"max":{"type":"integer"}}}}}},"AdsStockProduct":{"type":"object","required":["id","product_id","name","url","in_stock","changed_at","state","held","last_result"],"properties":{"id":{"type":"string","format":"uuid"},"product_id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string","description":"The product page, normalised (host/path)."},"in_stock":{"type":"boolean"},"changed_at":{"type":"string","format":"date-time","nullable":true},"state":{"type":"string","enum":["watching","holding"]},"held":{"type":"array","items":{"type":"object","properties":{"level":{"type":"string","enum":["ad","ad_group"]},"resource":{"type":"string"},"label":{"type":"string"},"change_id":{"type":"string"}}}},"last_result":{"type":"object","additionalProperties":true}}},"AdsStockStore":{"type":"object","required":["id","host","label","enabled","webhook_path","webhook_url","deliveries","products"],"properties":{"id":{"type":"string","format":"uuid"},"host":{"type":"string"},"label":{"type":"string"},"enabled":{"type":"boolean"},"webhook_path":{"type":"string"},"webhook_url":{"type":"string","format":"uri"},"created_at":{"type":"string","format":"date-time","nullable":true},"last_delivery_at":{"type":"string","format":"date-time","nullable":true},"last_delivery_note":{"type":"string"},"deliveries":{"type":"integer"},"products":{"type":"array","items":{"$ref":"#/components/schemas/AdsStockProduct"}}}},"AdsTracking":{"type":"object","required":["connection_id","org_id","platform","settings","latest","history","hold","outcomes","given_up","fix_offer","thresholds","kinds","sources"],"properties":{"connection_id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"platform":{"type":"string"},"settings":{"$ref":"#/components/schemas/AdsTrackingSettings"},"latest":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/AdsTrackingCheck"}]},"history":{"type":"array","items":{"$ref":"#/components/schemas/AdsTrackingCheck"}},"hold":{"type":"object","nullable":true,"description":"Why the autopilot is not judging this account today (za-116), or null.","properties":{"reason":{"type":"string","enum":["trackingUnreliable","trackingUnreadable"]},"status":{"type":"string"},"gap_pct":{"type":"integer","nullable":true},"real":{"type":"integer"},"credited":{"type":"integer","nullable":true},"day":{"type":"string","format":"date"}}},"outcomes":{"type":"object","description":"Outcomes per recovery status.","additionalProperties":{"type":"integer"}},"given_up":{"type":"integer","description":"Uploads Google accepted and never gave a verdict on within 3 days (not refunded, still inside the network's upload window). Nothing more is sent automatically; `POST .../tracking/retry` sends exactly these again."},"fix_offer":{"type":"object","nullable":true,"required":["code","price_minor","currency","path"],"properties":{"code":{"type":"string"},"price_minor":{"type":"integer","description":"Integer minor units of `currency`."},"currency":{"type":"string"},"path":{"type":"string"}}},"thresholds":{"type":"object","required":["gap_pct","min_outcomes","days","processing_days","recovery_window_days"],"properties":{"gap_pct":{"type":"integer"},"min_outcomes":{"type":"integer"},"days":{"type":"integer"},"processing_days":{"type":"integer"},"recovery_window_days":{"type":"integer"}}},"kinds":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}}}},"AdsTrackingCheck":{"type":"object","required":["day","window_start","window_end","status","holds_autopilot","real","credited","recovered","credited_after","gap_pct","by_kind","by_action","by_provider","diagnoses","recovery","failure","checked_at"],"properties":{"day":{"type":"string","format":"date"},"window_start":{"type":"string","format":"date"},"window_end":{"type":"string","format":"date"},"status":{"type":"string","enum":["ok","gap","unreadable","too_few","no_source"]},"holds_autopilot":{"type":"boolean"},"real":{"type":"integer"},"credited":{"type":"integer","nullable":true},"recovered":{"type":"integer"},"credited_after":{"type":"integer","nullable":true},"gap_pct":{"type":"integer","nullable":true,"description":"Negative = the network over-counts."},"by_kind":{"type":"object","additionalProperties":{"type":"integer"}},"by_action":{"type":"object","additionalProperties":{"type":"number"},"description":"What the network credited per compared action. On ChatGPT Ads (za-320) with no action chosen the one key is `all_goals` (every goal conversion of the account); otherwise the keys are the chosen conversion event setting ids."},"by_provider":{"type":"array","description":"za-124: the real outcomes per checkout provider (stripe, paddle, freemius) or other source (store, plugin, crm, events, ledger), largest first, and how many of them the network can match (its click id or a hashed e-mail). The network credits per conversion action, never per provider, so `lost` is the provider's own gap: real outcomes no tag and no upload can be credited for. Rows sum to `real`.","items":{"type":"object","required":["provider","checkout","real","matchable","uploaded","lost","lost_pct"],"properties":{"provider":{"type":"string"},"checkout":{"type":"boolean","description":"True for a checkout provider."},"real":{"type":"integer"},"matchable":{"type":"integer"},"uploaded":{"type":"integer"},"lost":{"type":"integer"},"lost_pct":{"type":"integer"}}}},"diagnoses":{"type":"array","description":"The fix assistant's findings, filtered by the network's registry row on read (ZA320-FU3): no upload finding (noUploadAction, uploadActionNotPrimary, uploadRequestRejected, uploadResponseUnreadable) on a network that takes no conversion upload (ChatGPT Ads), no click-id finding (lostClickIds, checkoutRoundTrip, providerGap) and an empty `by_provider` on a network none of whose click ids an outcome stores. `lostClickIds` figures carry `clickIds`, that network's own click ids.","items":{"type":"object","required":["code","figures"],"properties":{"code":{"type":"string","enum":["noSource","unreadable","lostClickIds","checkoutRoundTrip","offSiteOutcome","missingTag","noUploadAction","uploadActionNotPrimary","uploadRequestRejected","uploadResponseUnreadable","undercount","doubleCounting","providerGap"]},"figures":{"type":"object","additionalProperties":true}}}},"recovery":{"type":"object","additionalProperties":true,"description":"The recovery run's counts. `confirm` is Google's verdict (Data Manager request status, TENANT-DM-STATUS) on requests it accepted earlier: `refused` rows Google refused after accepting the request (never an undecided or refunded row), `again` the ones of those sent again later (a refused request goes again whole, then split once in two, each try waiting longer), `partial` requests Google recorded only in part, `undecided` rows Google gave no verdict on within 3 days (sent again), `refunded` rows refunded while awaiting and never recorded, `unreadable` requests whose status could not be read this run (asked again after a back-off).","properties":{"confirm":{"type":"object","additionalProperties":true,"properties":{"checked":{"type":"integer"},"confirmed":{"type":"integer"},"refused":{"type":"integer"},"held":{"type":"integer"},"waiting":{"type":"integer"},"partial":{"type":"integer"},"again":{"type":"integer"},"undecided":{"type":"integer"},"refunded":{"type":"integer"},"unreadable":{"type":"integer"}}}}},"failure":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/VendorFailure"}]},"checked_at":{"type":"string","format":"date-time"}}},"AdsTrackingEvent":{"type":"object","required":["kind","external_ref","occurred_at","source","value_minor","currency","networks"],"properties":{"kind":{"type":"string","enum":["purchase","trial","lead","signup","activation","free_listing","renewal"]},"external_ref":{"type":"string","description":"The order / trial id in YOUR system."},"occurred_at":{"type":"string","format":"date-time"},"source":{"type":"string","enum":["store","plugin","crm","events","checkout","ledger"]},"value_minor":{"type":["integer","null"],"description":"Integer minor units of `currency`."},"currency":{"type":"string"},"networks":{"type":"array","items":{"$ref":"#/components/schemas/AdsTrackingEventNetwork"}}}},"AdsTrackingEventNetwork":{"type":"object","required":["connection_id","network","account","verdict","reason","upload_action","has_click_id","has_email_hash","attempted_at","accepted_at","adjustments"],"properties":{"connection_id":{"type":"string","format":"uuid"},"network":{"type":"string"},"account":{"type":"string","description":"The ad account's label, else its id."},"verdict":{"type":"string","enum":["accepted","rejected","waiting","not_sendable"]},"reason":{"type":"string","description":"The network's refusal, or why it cannot be sent."},"upload_action":{"type":"string"},"has_click_id":{"type":"boolean"},"has_email_hash":{"type":"boolean"},"attempted_at":{"type":["string","null"],"format":"date-time"},"accepted_at":{"type":["string","null"],"format":"date-time"},"adjustments":{"type":"array","items":{"type":"object","required":["kind","status","reason","value_minor","currency","sent_at"],"properties":{"kind":{"type":"string","enum":["retraction","restatement"]},"status":{"type":"string","enum":["pending","sent","failed","closed"]},"reason":{"type":"string"},"value_minor":{"type":["integer","null"]},"currency":{"type":"string"},"sent_at":{"type":["string","null"],"format":"date-time"}}}}}},"AdsTrackingEventsPage":{"type":"object","required":["data","page","summary","window"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AdsTrackingEvent"}},"page":{"$ref":"#/components/schemas/PageMeta"},"summary":{"type":"array","description":"Per network, for the same window and filters.","items":{"$ref":"#/components/schemas/AdsTrackingEventsSummary"}},"window":{"type":"object","required":["since","days"],"properties":{"since":{"type":"string","format":"date-time"},"days":{"type":"integer"}}}}},"AdsTrackingEventsSummary":{"type":"object","required":["network","accepted","rejected","waiting","not_sendable","adjustments"],"properties":{"network":{"type":"string"},"accepted":{"type":"integer"},"rejected":{"type":"integer"},"waiting":{"type":"integer"},"not_sendable":{"type":"integer"},"adjustments":{"type":"object","description":"Value corrections by status (`pending`, `sent`, `failed`, `closed`).","additionalProperties":{"type":"integer"}}}},"AdsTrackingHub":{"type":"object","description":"One organisation's tracking hub (docs/1006 §104, za-126).","required":["org_id","tags","conversions","server_keys","server_routes","server_sends","networks","kinds","version","updated_at"],"properties":{"org_id":{"type":"string","format":"uuid"},"tags":{"type":"object","description":"Network -> its browser tag id (google_ads, ga4, microsoft_uet, meta_pixel, tiktok_pixel, linkedin_insight, x_pixel, pinterest_tag, amazon_tag, chatgpt_pixel).","additionalProperties":{"type":"string"}},"conversions":{"type":"object","description":"Network -> outcome kind -> conversion id (a Google Ads label, a Meta custom conversion, a TikTok event …).","additionalProperties":{"type":"object","additionalProperties":{"type":"string"}}},"server_keys":{"type":"array","items":{"type":"object","required":["kind","network","set","set_at","hint","account_id","test_code"],"properties":{"kind":{"type":"string","enum":["meta_capi","tiktok_events","ga4_mp","linkedin_capi","pinterest_capi","openai_capi"]},"network":{"type":"string"},"set":{"type":"boolean"},"set_at":{"type":"string","format":"date-time","nullable":true},"hint":{"type":"string","description":"The key's last four characters (blank when not set)."},"account_id":{"type":"string","description":"The Pinterest ad account id (blank for every other kind)."},"test_code":{"type":"string","description":"The network test code the key sends with (blank = live sends)."}}}},"server_routes":{"type":"object","description":"Network -> how its server-side conversions travel.","additionalProperties":{"type":"object","required":["route","key_kind","connected_provider"],"properties":{"route":{"type":"string","enum":["connected","key","stored","none"],"description":"key = a key in Vault that sends; stored = a key in Vault that cannot send yet (server_sends says why)."},"key_kind":{"type":"string","nullable":true},"connected_provider":{"type":"string","nullable":true}}}},"server_sends":{"type":"object","description":"Key kind -> what that key really sent (docs/1006 §122), computed from the per-outcome delivery receipts. Only outcomes whose source reported ad_user_data consent GRANTED are sent, with the hashed e-mail only.","additionalProperties":{"type":"object","required":["sending","not_sending_reason","last_sent_at","sent_24h","last_error","needs_new_key","test_mode","status_url","keys_url"],"properties":{"sending":{"type":"boolean","description":"The key is stored AND can send."},"not_sending_reason":{"type":"string","enum":["","noKey","noTagId","noAccountId","noConversionId"],"description":"Why a stored key is not used for sending (blank when it sends or is not stored)."},"last_sent_at":{"type":"string","format":"date-time","nullable":true},"sent_24h":{"type":"integer","description":"Outcomes this key sent in the last 24 hours."},"last_error":{"type":"object","nullable":true,"required":["class","at"],"properties":{"class":{"type":"string","enum":["provider_outage","rate_limited","credential_invalid","provider_billing","entitlement_exhausted","target_unreachable","permanent"]},"at":{"type":"string","format":"date-time"}}},"needs_new_key":{"type":"boolean","description":"The network refused this key since it was set; nothing more is sent until it is replaced."},"test_mode":{"type":"boolean","description":"The key sends with a network test code."},"status_url":{"type":"string","description":"The network's status board ('' when it publishes none)."},"keys_url":{"type":"string","description":"Where the network mints a replacement key."}}}},"networks":{"type":"array","items":{"type":"string"}},"kinds":{"type":"array","items":{"type":"string"}},"version":{"type":"integer","description":"0 when no hub has been saved yet."},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"AdsTrackingHubUpdate":{"type":"object","additionalProperties":false,"properties":{"org_id":{"type":"string","format":"uuid"},"tags":{"type":"object","additionalProperties":{"type":"string"}},"conversions":{"type":"object","description":"Network -> {outcome kind: conversion id}. A LinkedIn conversion id is numeric and an X event id is tw-PIXEL-EVENT (for example tw-o1abc-o1xyz); any other shape for those two is refused (badConversion), since the page could never fire it.","additionalProperties":{"type":"object","additionalProperties":{"type":"string"}}}}},"AdsTrackingSettings":{"type":"object","description":"One ad account's tracking-truth settings (docs/1006 §21).","properties":{"compare_actions":{"type":"array","maxItems":50,"description":"Network actions that stand for these outcomes; empty = every PRIMARY one.","items":{"type":"string","minLength":1,"maxLength":200}},"upload_actions":{"type":"object","description":"{kind: action} — where a missed outcome of that kind is uploaded.","additionalProperties":{"type":"string"}},"recovery_mode":{"type":"string","enum":["off","validate","live"]},"site_url":{"type":"string","format":"uri"},"kinds":{"type":"array","description":"Outcome kinds the tracking-truth check compares (empty = every kind but activation, which is uploaded and never tagged — za-154 — and free_listing, which goes to a secondary action outside the Conversions column).","items":{"type":"string","enum":["purchase","trial","lead","signup","activation","free_listing","renewal"]}}}},"AdsUniversalNegatives":{"type":"object","description":"za-333 — the account's one list of universal negatives.","required":["connection_id","platform","supported","list_name","terms","cap","sync","checked_at"],"properties":{"connection_id":{"type":"string","format":"uuid"},"platform":{"type":"string"},"supported":{"type":"boolean","description":"Google and Microsoft keep the list."},"list_name":{"type":"string","description":"The name the list is made with."},"terms":{"type":"array","items":{"type":"string"},"description":"The za-217 junk set, each added as a PHRASE negative."},"cap":{"type":"integer","description":"The most entries the network allows on the list."},"sync":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/AdsUniversalNegativesSync"}]},"checked_at":{"type":["string","null"],"format":"date-time"}}},"AdsUniversalNegativesSync":{"type":"object","required":["network","state"],"properties":{"network":{"type":"string","enum":["google","microsoft"]},"state":{"type":"string","enum":["planned","waiting_approval","refused","full","synced","error"]},"list_name":{"type":"string"},"linked":{"type":"boolean","description":"Linked to the account (Google) or every campaign (Microsoft)."},"entries":{"type":"integer","description":"Entries on the list as read","ours and the customer's.":null},"cap":{"type":"integer"},"terms":{"type":"integer"},"present":{"type":"array","items":{"type":"string"}},"missing":{"type":"array","items":{"type":"string"}},"skipped":{"type":"array","description":"Terms left off because they would block a keyword (or a search that converted).","items":{"type":"object","properties":{"text":{"type":"string"},"blocks":{"type":"string"}}}},"unlinked_campaigns":{"type":"integer"},"copies":{"type":["integer","null"],"description":"Per-campaign copies the list covers, as read by this run. `null` when this run did not read them (Microsoft skips the per-campaign read on a quiet synced account for at most 7 days); never 0 for an unread figure."},"copies_read_at":{"type":"string","description":"When the per-campaign copies were last actually read (ISO 8601; empty if never)."},"copies_removed":{"type":"integer"},"change_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"reason":{"type":"string","description":"Why a step did not go out — `accountListFull`, a refusal code such as `notInGoodStanding`, `killed` or `notAutomatic`, `unreadBack`, or `vendor`. With `waiting_approval`, `decisionHeld` means the step waits for a PERSON because the list covers a campaign the customer holds (`held_campaign`); a person's approve of `change_ids[0]` sends it, an API key's or MCP's approval is refused (GATE-PERSON r9)."},"held_campaign":{"type":"string","description":"The held campaign a `decisionHeld` step waits on a person for (empty otherwise)."},"held_campaign_name":{"type":"string","description":"That held campaign's name (\"\" when it could not be read; show `held_campaign`) — GATE-PERSON-FU."}}},"AdsVideoReading":{"type":["object","null"],"description":"za-201 (docs/1006 §80): the Video and Demand Gen reading, or null before the first audit. `state`: `ok` · `attention` (a placement that spends and never converts, a frequency over 6 a person, mostly view-through conversions, more claimed than real sales, or no YouTube channel saved) · `noVideo`. Money is integer micros of `figures.currency`.","required":["kind","state","day","updated_at","figures"],"properties":{"kind":{"type":"string","enum":["video"]},"state":{"type":"string","enum":["ok","attention","noVideo"]},"day":{"type":"string","format":"date"},"updated_at":{"type":"string","format":"date-time"},"figures":{"type":"object","required":["window_days","currency","campaigns","youtube"],"properties":{"window_days":{"type":"integer"},"currency":{"type":"string"},"claimed":{"type":"number","description":"Click-through plus view-through conversions Google reports for all video campaigns."},"real_sales":{"type":["integer","null"],"description":"Outcomes the customer's own source recorded in the same days; null with no source."},"youtube":{"type":"object","required":["channel_id","videos"],"properties":{"channel_id":{"type":"string"},"videos":{"type":"array","items":{"type":"object","required":["video_id","title","channel_id","own","link_status"],"properties":{"video_id":{"type":"string"},"title":{"type":"string"},"channel_id":{"type":"string"},"own":{"type":"boolean","description":"The video is on the channel saved on the connection."},"link_status":{"type":"string","description":"Google's data link status (REQUESTED, PENDING_APPROVAL, ENABLED, …); empty when not linked."}}}}}},"campaigns":{"type":"array","items":{"type":"object","required":["campaign_id","campaign","type","impressions","clicks","views","cost_micros","conversions","view_through","unique_users","frequency","frequency_caps","placements"],"properties":{"campaign_id":{"type":"string"},"campaign":{"type":"string"},"type":{"type":"string","enum":["VIDEO","DEMAND_GEN"]},"impressions":{"type":"integer"},"clicks":{"type":"integer"},"views":{"type":"integer"},"cost_micros":{"type":"integer","format":"int64"},"conversions":{"type":"number"},"view_through":{"type":"number"},"unique_users":{"type":"integer"},"frequency":{"type":"number","description":"Average impressions per person in the window."},"frequency_caps":{"type":"array","items":{"type":"object","properties":{"level":{"type":"string"},"event":{"type":"string"},"unit":{"type":"string"},"cap":{"type":"integer"}}}},"placements":{"type":"array","items":{"type":"object","required":["placement","type","name","url","impressions","clicks","cost_micros","conversions","view_through"],"properties":{"placement":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"impressions":{"type":"integer"},"clicks":{"type":"integer"},"cost_micros":{"type":"integer","format":"int64"},"conversions":{"type":"number"},"view_through":{"type":"number"}}}}}}}}}}},"AdsVideoResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["connection_id","currency","youtube_channel_id","reading"],"properties":{"connection_id":{"type":"string","format":"uuid"},"currency":{"type":"string"},"youtube_channel_id":{"type":["string","null"],"description":"The customer's own YouTube channel saved on the connection."},"reading":{"$ref":"#/components/schemas/AdsVideoReading"}}}}},"AdsWebhookEndpoint":{"type":"object","required":["connection_id","label","target","verified","events"],"properties":{"connection_id":{"type":"string","format":"uuid"},"label":{"type":"string"},"target":{"type":"string","description":"The endpoint's https URL."},"verified":{"type":"boolean","description":"Nothing is sent until a test POST was accepted."},"events":{"type":"array","items":{"$ref":"#/components/schemas/AdsWebhookEventName"}}}},"AdsWebhookEventAlertStarted":{"type":"object","description":"`ads.alert.started` — a warning started (tracking stopped, every ad disapproved, the ceiling reached …).","required":["event","version","id","occurred_at","org_id","connection_id","alert"],"properties":{"event":{"type":"string"},"version":{"type":"integer","enum":[1]},"id":{"type":"string","format":"uuid","description":"The event id (UUIDv5 — the same moment is the same id)."},"occurred_at":{"type":"string","format":"date-time"},"org_id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid","description":"The ad-account connection (GET /v1/ads/connections)."},"test":{"type":"boolean","description":"Present and true only on a Test press."},"alert":{"type":"object","required":["finding_id","key","line","critical","first_seen_at"],"properties":{"finding_id":{"type":"string","format":"uuid"},"key":{"type":"string"},"line":{"type":"string","description":"The warning in English (the customer's screen words it in their language)."},"critical":{"type":"boolean"},"first_seen_at":{"type":["string","null"],"format":"date-time"}}}}},"AdsWebhookEventChangeApplied":{"type":"object","description":"`ads.change.applied` — a change reached the ad account, approved by a person or applied by the autopilot.","required":["event","version","id","occurred_at","org_id","connection_id","change"],"properties":{"event":{"type":"string"},"version":{"type":"integer","enum":[1]},"id":{"type":"string","format":"uuid","description":"The event id (UUIDv5 — the same moment is the same id)."},"occurred_at":{"type":"string","format":"date-time"},"org_id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid","description":"The ad-account connection (GET /v1/ads/connections)."},"test":{"type":"boolean","description":"Present and true only on a Test press."},"change":{"type":"object","required":["id","action_class","summary","budget_delta_minor","proposed_by","decided_by","applied_at","can_undo","undo_until"],"properties":{"id":{"type":"string","format":"uuid"},"action_class":{"type":"string"},"summary":{"type":"object"},"budget_delta_minor":{"type":["integer","null"],"description":"Daily budget increase in integer minor units of the account currency."},"proposed_by":{"type":"string"},"decided_by":{"type":"string"},"applied_at":{"type":["string","null"],"format":"date-time"},"can_undo":{"type":"boolean"},"undo_until":{"type":["string","null"],"format":"date-time"}}}}},"AdsWebhookEventFindingOpened":{"type":"object","description":"`ads.finding.opened` — the audit found something, or a resolved finding became true again.","required":["event","version","id","occurred_at","org_id","connection_id","finding"],"properties":{"event":{"type":"string"},"version":{"type":"integer","enum":[1]},"id":{"type":"string","format":"uuid","description":"The event id (UUIDv5 — the same moment is the same id)."},"occurred_at":{"type":"string","format":"date-time"},"org_id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid","description":"The ad-account connection (GET /v1/ads/connections)."},"test":{"type":"boolean","description":"Present and true only on a Test press."},"finding":{"type":"object","required":["id","kind","key","status","detail","first_seen_at","last_seen_at"],"properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","description":"waste_term, good_term, poor_keyword, landing, pacing, … (docs/1006)."},"key":{"type":"string"},"status":{"type":"string"},"detail":{"type":"object","description":"The figures (campaign","cost in micros":null,"clicks …)":null,"never sentences.":null},"first_seen_at":{"type":["string","null"],"format":"date-time"},"last_seen_at":{"type":["string","null"],"format":"date-time"}}}}},"AdsWebhookEventName":{"type":"string","enum":["ads.finding.opened","ads.change.applied","ads.alert.started"],"description":"A Zinn® Ads webhook event (za-192, docs/1006 §70)."},"AdsWebhooks":{"type":"object","required":["events","endpoints"],"properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/AdsWebhookEventName"}},"endpoints":{"type":"array","items":{"$ref":"#/components/schemas/AdsWebhookEndpoint"}}}},"AdsWordPressConfig":{"type":"object","description":"What the Zinn® Ads plugin needs to run. Public ids only, never a credential.","required":["site_id","site_host","mode","cloudflare_detected","offer_zaraz","heartbeat_seconds","shield"],"properties":{"site_id":{"type":"string","format":"uuid"},"site_host":{"type":"string"},"mode":{"type":"string","enum":["browser","zaraz"]},"cloudflare_detected":{"type":"boolean"},"offer_zaraz":{"type":"boolean"},"heartbeat_seconds":{"type":"integer"},"tag":{"type":["object","null"],"description":"The site's Zinn® Ads tag (the same `AdsSiteTag` \"Install on any site\" edits; claiming a host creates or links it). Browser mode loads `script_url` and hands each conversion to it. `null` when the tag was deleted or switched off there.","required":["script_url","public_key","version"],"properties":{"script_url":{"type":"string","format":"uri"},"public_key":{"type":"string"},"version":{"type":"integer"}}},"ref_prefix":{"type":"string","pattern":"^zw[0-9a-f]{8}$","description":"The site's order-reference prefix: an order's transaction id is `<ref_prefix>-<order number>` in the browser tag and the server-side upload alike."},"shield":{"type":"object","required":["enabled","refusal","max_hits","dwell_seconds"],"properties":{"enabled":{"type":"boolean"},"refusal":{"type":["string","null"],"enum":["clickShieldRequired","notInGoodStanding",null],"description":"Why the shield may not score this site's clicks now (a site we do not host needs the click-shield add-on; §2.46 good standing). While set, the plugin collects nothing and shows the add-on offer."},"max_hits":{"type":"integer"},"dwell_seconds":{"type":"integer"}}}}},"AdsWordPressPathHealth":{"type":"object","required":["expected","delivered","status"],"description":"One delivery path of a Zaraz-mode site (WPPAID); `short` when more than 10% of at least 5 expected went missing.","properties":{"expected":{"type":"integer"},"delivered":{"type":"integer"},"status":{"type":"string","enum":["ok","short","tooFew"]}}},"AdsWordPressSite":{"type":"object","required":["id","org_id","status","site_host","mode","cloudflare_detected","offer_zaraz","zaraz_health","click_shield_refusal"],"properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","active"]},"site_host":{"type":"string"},"site_url":{"type":"string"},"token_hint":{"type":"string","description":"The token's last 4 characters."},"plugin_version":{"type":"string"},"wp_version":{"type":"string"},"cloudflare_detected":{"type":"boolean"},"click_shield_refusal":{"type":["string","null"],"enum":["clickShieldRequired","notInGoodStanding",null],"description":"Why this site's paid clicks are not checked now: a site Zinn Digital® does not host needs the click-shield add-on (or a plan that carries it), and the account must be in good standing. The card shows the add-on offer or the billing link instead."},"mode":{"type":"string","enum":["browser","zaraz"]},"offer_zaraz":{"type":"boolean"},"tag_id":{"type":["string","null"],"format":"uuid","description":"The site's tag in \"Install on any site\" (`null` = none for this host)."},"tag_enabled":{"type":"boolean","description":"Whether that tag loads (browser mode sends nothing without it)."},"zaraz_health":{"type":"object","required":["status"],"description":"Zaraz-sent purchases vs network-credited, per SITE: compared only when the organisation's credit can be attributed to this site (it is the only connected WordPress site, enabled site tag and recorded sale host in the window); otherwise `cannotAttribute` with `credited` null — never a gap alarm, never a hidden loss. WPPAID: first, each path on its own over the last 7 complete UTC days (`paths`; null for a plugin build that reports no per-path counts) — the browser path (purchases handed to Zaraz vs Zaraz purchases on order pages, less those withheld for want of consent) and the server upload (orders it delivered vs paid orders queued). The ad network de-duplicates the two, so its credit alone hides a Zaraz loss; a short path makes the status `pathShort` and `short_path` names it.","properties":{"status":{"type":"string","enum":["notZaraz","noCheck","cannotAttribute","unreadable","tooFew","ok","gap","pathShort"]},"sent":{"type":["integer","null"]},"credited":{"type":["integer","null"]},"gap_pct":{"type":["integer","null"]},"window_start":{"type":"string","format":"date"},"window_end":{"type":"string","format":"date"},"short_path":{"type":["string","null"],"enum":["browser","server","both",null]},"paths":{"type":["object","null"],"required":["window_start","window_end","browser","server"],"properties":{"window_start":{"type":"string","format":"date"},"window_end":{"type":"string","format":"date"},"browser":{"$ref":"#/components/schemas/AdsWordPressPathHealth"},"server":{"$ref":"#/components/schemas/AdsWordPressPathHealth"}}}}},"pairing_expires_at":{"type":["string","null"],"format":"date-time"},"last_seen_at":{"type":["string","null"],"format":"date-time"},"claimed_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":["string","null"],"format":"date-time"}}},"AdsWordPressZaraz":{"type":"object","required":["zone_names","connection","installed_at","drift","hub_networks","skipped","zone_consent_on"],"properties":{"zone_names":{"type":"array","items":{"type":"string"}},"connection":{"oneOf":[{"$ref":"#/components/schemas/AdsZarazConnection"},{"type":"null"}]},"installed_at":{"type":["string","null"],"format":"date-time"},"drift":{"type":"string","description":"The connection's drift state, empty before any install."},"hub_networks":{"type":"array","items":{"type":"string"}},"skipped":{"type":"array","items":{"$ref":"#/components/schemas/AdsZarazSkipped"}},"zone_consent_on":{"type":["boolean","null"],"description":"The zone's Zaraz consent switch as last read (a check reads it); null before any read. The plugin's consent checkbox starts from it, as the dashboard card's does."}}},"AdsXCampaign":{"type":"object","description":"One X Ads campaign and its budgets (za-43). Money is micros of `currency` (§2.8).","required":["id","name","status","currency","daily_budget_micros","total_budget_micros","spend_micros"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","description":"X's entity_status (ACTIVE, PAUSED, DRAFT, …)."},"currency":{"type":"string","description":"ISO 4217 code."},"daily_budget_micros":{"type":["integer","null"],"format":"int64"},"total_budget_micros":{"type":["integer","null"],"format":"int64"},"spend_micros":{"type":"integer","format":"int64","description":"Spend over the response's `days`."}}},"AdsZarazActionResult":{"type":"object","required":["drift","version"],"properties":{"drift":{"$ref":"#/components/schemas/AdsZarazDrift"},"skipped":{"type":"array","items":{"$ref":"#/components/schemas/AdsZarazSkipped"}},"version":{"$ref":"#/components/schemas/AdsZarazVersion"}}},"AdsZarazConnection":{"type":"object","description":"A Cloudflare zone connected for Zaraz (za-131). The token is in Vault, never here; `token_hint` is its last four characters.","required":["id","org_id","provider","zone_id","zone_name","account_name","status","workflow","token_hint","last_error","last_checked_at","connected_at"],"properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"provider":{"type":"string","enum":["cloudflare"]},"zone_id":{"type":"string"},"zone_name":{"type":"string"},"account_name":{"type":"string"},"status":{"type":"string","enum":["ok","needs_token"]},"workflow":{"type":"string","description":"Zaraz's publishing workflow on the zone as last read: realtime or preview."},"token_hint":{"type":"string"},"last_error":{"type":"string","description":"The last check's refusal code (empty when it passed)."},"last_checked_at":{"type":"string","format":"date-time","nullable":true},"connected_at":{"type":"string","format":"date-time"}}},"AdsZarazDrift":{"type":"object","required":["state"],"properties":{"state":{"type":"string","enum":["not_installed","in_sync","edited_in_cloudflare","hub_ahead","both","unknown"]},"edited":{"type":"boolean"},"hub_ahead":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/AdsZarazDriftItem"}},"item_count":{"type":"integer"},"hub_version":{"type":"integer"},"installed_hub_version":{"type":"integer"},"checked_at":{"type":"string","format":"date-time"},"error":{"type":"string","description":"The last daily read's refusal code (empty when it worked)."},"zone_consent_on":{"type":"boolean","description":"The zone's Zaraz consent switch as this read or write found it, kept whether or not the zone is installed."}}},"AdsZarazDriftItem":{"type":"object","required":["area","key","name","change","managed"],"properties":{"area":{"type":"string","enum":["tool","trigger","variable","consent","purpose","setting"]},"key":{"type":"string"},"name":{"type":"string"},"change":{"type":"string","enum":["added","removed","changed"]},"managed":{"type":"boolean","description":"A `zinn_*` part (written by Zinn® Ads)."}}},"AdsZarazSkipped":{"type":"object","required":["network","reason"],"properties":{"network":{"type":"string"},"reason":{"type":"string","enum":["needsServerKey","noIdSetting","noComponent"]}}},"AdsZarazSync":{"type":"object","required":["connection_id","drift","versions","undo_days"],"properties":{"connection_id":{"type":"string","format":"uuid"},"installed_at":{"type":["string","null"],"format":"date-time"},"consent_on":{"type":"boolean"},"zone_consent_on":{"type":["boolean","null"],"description":"Whether the zone's Zaraz consent banner is on, from the newest read or write (stored on every read, installed or not, so it is known before the first install once the card has read the zone); null before anything was read. The consent checkbox starts from it."},"drift":{"$ref":"#/components/schemas/AdsZarazDrift"},"drift_checked_at":{"type":["string","null"],"format":"date-time"},"hub_version":{"type":"integer"},"networks":{"type":"array","items":{"type":"object","required":["network","tool"],"properties":{"network":{"type":"string"},"tool":{"type":"string"}}}},"skipped":{"type":"array","items":{"$ref":"#/components/schemas/AdsZarazSkipped"}},"undo_days":{"type":"integer"},"versions":{"type":"array","items":{"$ref":"#/components/schemas/AdsZarazVersion"}}}},"AdsZarazVersion":{"type":"object","required":["id","source","created_at","undoable"],"properties":{"id":{"type":"string","format":"uuid"},"source":{"type":"string","enum":["install","seen","adopt","undo"]},"before_install":{"type":"boolean","description":"The zone as it stood before the first install: a version read from Cloudflare that is older than the oldest install version still held (none once every install was pruned). Shown as Before install, never as a Cloudflare edit."},"created_at":{"type":"string","format":"date-time"},"actor":{"type":"string"},"hub_version":{"type":"integer"},"tools":{"type":"array","items":{"type":"string"}},"summary":{"type":"array","items":{"$ref":"#/components/schemas/AdsZarazDriftItem"}},"undoable":{"type":"boolean","description":"Inside the 30-day undo window."}}},"AdsZarazZone":{"type":"object","description":"One Cloudflare zone a Zaraz token reaches (za-131).","required":["zone_id","zone_name","status","account_id","account_name"],"properties":{"zone_id":{"type":"string"},"zone_name":{"type":"string"},"status":{"type":"string","description":"Cloudflare's zone status (active, pending, …)."},"account_id":{"type":"string"},"account_name":{"type":"string"}}},"AffiliateAccount":{"type":"object","required":["id","org_id","state","code","referral_url","commission_plan","payout_destination","kyc_state"],"properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"state":{"type":"string","enum":["pending","approved","rejected","suspended"]},"code":{"type":"string","description":"The referral code. Its alphabet excludes the characters people transcribe wrongly (`0`/`O`, `1`/`I`/`l`), because it is read aloud and typed off a slide."},"referral_url":{"type":"string","description":"The link to share — the public site with `?ref=CODE`."},"commission_plan":{"type":"string","enum":["recurring_12m","lifetime"],"description":"The line **new** referrals will be created on. Changing it never affects customers already referred."},"payout_destination":{"type":"string","enum":["wallet","cash"]},"kyc_state":{"type":"string","enum":["not_required","required","submitted","verified","rejected"]},"review_note":{"type":"string"},"terms_accepted_at":{"type":"string","format":"date-time","nullable":true},"applied_at":{"type":"string","format":"date-time"}}},"AffiliateCommission":{"type":"object","required":["id","referral_id","state","amount","basis","rate_bps","earned_at","available_at"],"properties":{"id":{"type":"string","format":"uuid"},"referral_id":{"type":"string","format":"uuid"},"state":{"type":"string","enum":["pending","approved","paid","reversed"]},"amount":{"$ref":"#/components/schemas/AffiliateMoney"},"basis":{"allOf":[{"$ref":"#/components/schemas/AffiliateMoney"}],"description":"The payment this commission was computed from."},"rate_bps":{"type":"integer"},"earned_at":{"type":"string","format":"date-time"},"available_at":{"type":"string","format":"date-time","description":"When the holdback elapses and the entry can be paid."},"paid_at":{"type":"string","format":"date-time","nullable":true}}},"AffiliateCommissionPlan":{"type":"object","description":"One of the two lines an affiliate may choose. Served by the engine so a console can never carry a stale copy of a rate the customer was shown before signing up.","required":["plan","rate_bps","is_lifetime"],"properties":{"plan":{"type":"string","enum":["recurring_12m","lifetime"]},"rate_bps":{"type":"integer","description":"The rate in basis points — 2000 is 20%."},"duration_months":{"type":"integer","nullable":true,"description":"How many months a referral earns for. `null` means the plan never stops earning; it does **not** mean \"unset\"."},"is_lifetime":{"type":"boolean"}}},"AffiliateJoin":{"type":"object","required":["commission_plan","payout_destination","accept_terms"],"properties":{"commission_plan":{"type":"string","enum":["recurring_12m","lifetime"]},"payout_destination":{"type":"string","enum":["wallet","cash"]},"accept_terms":{"type":"boolean","description":"Must be `true`. An affiliate agreement is a contract about money, so acceptance is recorded explicitly rather than assumed."}}},"AffiliateMoney":{"type":"object","description":"An amount in integer minor units plus its ISO currency (§2.8 — money is never a float, and never a pre-formatted string the caller cannot sum or re-localise).","required":["amount_minor","currency"],"properties":{"amount_minor":{"type":"integer","format":"int64"},"currency":{"type":"string","minLength":3,"maxLength":3}}},"AffiliateReferral":{"type":"object","description":"A customer attributed to an affiliate, with the commission terms **frozen at the moment they converted**.","required":["id","referred_org_id","state","plan","rate_bps","converted_at"],"properties":{"id":{"type":"string","format":"uuid"},"referred_org_id":{"type":"string","format":"uuid"},"state":{"type":"string","enum":["active","expired","revoked"]},"plan":{"type":"string","enum":["recurring_12m","lifetime"]},"rate_bps":{"type":"integer"},"duration_months":{"type":"integer","nullable":true},"converted_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time","nullable":true,"description":"End of the earning window; `null` for a lifetime referral."}}},"AffiliateTotals":{"type":"object","required":["by_currency"],"properties":{"by_currency":{"type":"array","description":"Earnings per currency. Deliberately not summed across currencies — one total over mixed currencies is wrong in every one of them.","items":{"type":"object","required":["currency","pending","available","paid"],"properties":{"currency":{"type":"string","minLength":3,"maxLength":3},"pending":{"$ref":"#/components/schemas/AffiliateMoney"},"available":{"$ref":"#/components/schemas/AffiliateMoney"},"paid":{"$ref":"#/components/schemas/AffiliateMoney"}}}}}},"AffiliateUpdate":{"type":"object","description":"Send `commission_plan`, `payout_destination`, or both.","properties":{"commission_plan":{"type":"string","enum":["recurring_12m","lifetime"]},"payout_destination":{"type":"string","enum":["wallet","cash"]}}},"AgedDomain":{"type":"object","required":["id","domain","price_minor","currency","categories","indexed"],"properties":{"id":{"type":"string","format":"uuid"},"domain":{"type":"string"},"description":{"type":"string"},"da":{"type":"integer","nullable":true},"dr":{"type":"integer","nullable":true},"tf":{"type":"integer","nullable":true},"cf":{"type":"integer","nullable":true},"rd":{"type":"integer","nullable":true},"uniques":{"type":"integer","nullable":true},"indexed":{"type":"boolean"},"tld":{"type":"string"},"language":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"possible_use":{"type":"string"},"added_year":{"type":"integer","nullable":true,"description":"Year the domain was first registered, or null when unknown. Never a value outside 1985..this year: the V1 feed's legacy column held a count, which is dropped (D35801)."},"has_wiki":{"type":"boolean"},"has_gnews":{"type":"boolean"},"price_minor":{"type":"integer","description":"USD cents; supplier list price, no markup (D55)."},"currency":{"type":"string"}}},"AgedDomainDetail":{"allOf":[{"$ref":"#/components/schemas/AgedDomain"},{"type":"object","required":["available","date_added_on","enquire_only","price_local","live","shop_open","hold_hours","wayback_url","similar"],"properties":{"available":{"type":"boolean"},"date_added_on":{"type":"string","format":"date","nullable":true,"description":"\"History from\" — when the supplier first recorded the domain."},"enquire_only":{"type":"boolean"},"price_local":{"type":"object","nullable":true,"required":["minor","currency"],"description":"The USD price in the visitor's currency at the stored rate, for display only (the charge is USD).","properties":{"minor":{"type":"integer"},"currency":{"type":"string"}}},"live":{"$ref":"#/components/schemas/AgedDomainLiveCheck"},"shop_open":{"type":"boolean"},"hold_hours":{"type":"integer"},"wayback_url":{"type":"string","format":"uri"},"similar":{"type":"array","items":{"$ref":"#/components/schemas/AgedDomain"}}}}]},"AgedDomainFacetCount":{"type":"object","required":["value","count"],"properties":{"value":{"type":"string"},"count":{"type":"integer"}}},"AgedDomainLiveCheck":{"type":"object","required":["state","message","checked_at","checking"],"properties":{"state":{"type":"string","nullable":true,"enum":["available","held","sold","unknown","paused","busy"],"description":"The last live answer. `held` — another customer's open order holds it; `unknown` — the supplier did not answer (never read as sold); null — never checked."},"message":{"type":"string"},"checked_at":{"type":"string","format":"date-time","nullable":true},"checking":{"type":"boolean","description":"A check asked for has not answered yet."}}},"AgedDomainOrder":{"type":"object","required":["id","domain","aged_domain_id","state","open","price_minor","currency","destination","order_id","ticket_id","hold_expires_at","delivered_at","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"domain":{"type":"string"},"aged_domain_id":{"type":"string","format":"uuid"},"state":{"type":"string","enum":["holding","paid","ordered","delivered","refunded","expired","cancelled"]},"open":{"type":"boolean","description":"Whether this order holds the domain now."},"price_minor":{"type":"integer","description":"USD cents; the supplier list price quoted, no markup (D55)."},"currency":{"type":"string"},"destination":{"type":"object","properties":{"kind":{"type":"string","enum":["registrar","zinn"]},"registrar":{"type":"string"},"account":{"type":"string"}}},"order_id":{"type":"string","format":"uuid","nullable":true},"ticket_id":{"type":"string","format":"uuid","nullable":true},"hold_expires_at":{"type":"string","format":"date-time"},"delivered_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"AgedDomainPage":{"type":"object","required":["data","total","page","per_page","facets"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgedDomain"}},"total":{"type":"integer"},"page":{"type":"integer"},"per_page":{"type":"integer"},"applied":{"type":"object","additionalProperties":true},"facets":{"type":"object","description":"EVERY TLD, language and category on sale, each with the number of domains carrying it, sorted A-Z (case-folded). Never truncated (s1014: a 400-value cap cut the 2,281 live categories at \"Ch\"). Cached 15 minutes.","properties":{"tlds":{"type":"array","items":{"$ref":"#/components/schemas/AgedDomainFacetCount"}},"languages":{"type":"array","items":{"$ref":"#/components/schemas/AgedDomainFacetCount"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/AgedDomainFacetCount"}},"has_added_year":{"type":"boolean","description":"Whether any domain on sale has a registration year; the app offers the year filter and column only when one does."}}}}},"AgedDomainPublicPage":{"type":"object","required":["data","total","page","per_page","applied","currency","facets"],"properties":{"data":{"type":"array","items":{"type":"object","required":["id","masked_domain","tld","language","categories","indexed","has_wiki","has_gnews","price_minor","currency","enquire_only"],"properties":{"id":{"type":"string","format":"uuid","description":"Opens the signed-in detail page (`getAgedDomain`)."},"masked_domain":{"type":"string","example":"e••••••••••••••t.com"},"tld":{"type":"string"},"language":{"type":"string"},"categories":{"type":"array","maxItems":3,"items":{"type":"string"}},"da":{"type":"integer","nullable":true},"dr":{"type":"integer","nullable":true},"tf":{"type":"integer","nullable":true},"cf":{"type":"integer","nullable":true},"rd":{"type":"integer","nullable":true},"indexed":{"type":"boolean"},"has_wiki":{"type":"boolean"},"has_gnews":{"type":"boolean"},"added_year":{"type":"integer","nullable":true},"price_minor":{"type":"integer","description":"USD cents; supplier list price, no markup (D55)."},"currency":{"type":"string"},"enquire_only":{"type":"boolean","description":"Sold by our team personally rather than self-serve."}}}},"total":{"type":"integer"},"page":{"type":"integer"},"per_page":{"type":"integer"},"applied":{"type":"object","additionalProperties":true},"currency":{"type":"string","enum":["USD"]},"facets":{"type":"object","required":["total","categories","category_count","tlds","tld_count","languages","dr_bands","tf_mins","rd_mins","age_mins"],"properties":{"total":{"type":"integer","description":"Aged domains on sale now (unfiltered)."},"categories":{"type":"array","description":"The sixty most stocked categories, most first; `category_count` says how many exist.","items":{"$ref":"#/components/schemas/AgedDomainFacetCount"}},"category_count":{"type":"integer"},"tlds":{"type":"array","description":"The forty most stocked TLDs, most first.","items":{"$ref":"#/components/schemas/AgedDomainFacetCount"}},"tld_count":{"type":"integer"},"languages":{"type":"array","items":{"$ref":"#/components/schemas/AgedDomainFacetCount"}},"dr_bands":{"type":"array","items":{"type":"object","required":["low","high","count"],"properties":{"low":{"type":"integer"},"high":{"type":"integer","nullable":true},"count":{"type":"integer"}}}},"tf_mins":{"type":"array","items":{"type":"object","required":["min","count"],"properties":{"min":{"type":"integer"},"count":{"type":"integer"}}}},"rd_mins":{"type":"array","items":{"type":"object","required":["min","count"],"properties":{"min":{"type":"integer"},"count":{"type":"integer"}}}},"age_mins":{"type":"array","description":"Domains at least `years` old (a `max_added_year` filter); empty when no row carries a year.","items":{"type":"object","required":["years","max_added_year","count"],"properties":{"years":{"type":"integer"},"max_added_year":{"type":"integer"},"count":{"type":"integer"}}}}}}}},"AgedDomainPublicSummary":{"type":"object","required":["total","as_of","currency","price_from_minor","priced_under_100","with_wiki","indexed","dr_bands","tlds","languages","category_count","tld_count","language_count","categories","sample"],"properties":{"total":{"type":"integer","description":"Aged domains on sale now."},"as_of":{"type":"string","format":"date-time","nullable":true,"description":"When the stock on sale was last confirmed against the source (hourly since s1014 — a complete pass or an unchanged 304)."},"currency":{"type":"string","enum":["USD"]},"price_from_minor":{"type":"integer","nullable":true,"description":"The lowest list price on sale","USD minor units.":null},"priced_under_100":{"type":"integer","description":"Domains on sale at or under USD 100.00."},"with_wiki":{"type":"integer"},"indexed":{"type":"integer"},"dr_bands":{"type":"array","items":{"type":"object","required":["low","high","count"],"properties":{"low":{"type":"integer"},"high":{"type":"integer","nullable":true,"description":"Inclusive; null = and above."},"count":{"type":"integer"}}}},"tlds":{"type":"array","items":{"$ref":"#/components/schemas/AgedDomainFacetCount"}},"languages":{"type":"array","items":{"$ref":"#/components/schemas/AgedDomainFacetCount"}},"category_count":{"type":"integer","description":"Distinct categories (niches) across the domains on sale."},"tld_count":{"type":"integer","description":"Distinct TLDs on sale."},"language_count":{"type":"integer","description":"Distinct languages on sale."},"categories":{"type":"array","description":"The twelve categories with the most domains on sale, most first.","items":{"$ref":"#/components/schemas/AgedDomainFacetCount"}},"sample":{"type":"array","items":{"type":"object","required":["masked_domain","tld","language","dr","price_minor","currency"],"properties":{"masked_domain":{"type":"string","example":"e••••••••••••••t.com"},"tld":{"type":"string"},"language":{"type":"string"},"dr":{"type":"integer"},"da":{"type":"integer","nullable":true},"tf":{"type":"integer","nullable":true},"cf":{"type":"integer","nullable":true},"rd":{"type":"integer","nullable":true},"added_year":{"type":"integer","nullable":true},"price_minor":{"type":"integer"},"currency":{"type":"string"}}}}}},"AgencyBoard":{"type":"object","required":["id","org_id","name","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"org_id":{"allOf":[{"$ref":"#/components/schemas/Uuid"}],"description":"The agency that owns this board."},"client_org_id":{"type":"string","format":"uuid","nullable":true,"description":"The client organisation this board's work is for, if any. This is what authorises a client's read — never the org tree, because \"is a descendant of the agency\" is a weaker claim than \"is this board's client\"."},"client_org_name":{"type":"string","nullable":true,"description":"That client organisation's name, resolved by the engine. `client_org_id` set with this `null` is a real state and not an error — the board names a client the caller may not read — and a surface must say so rather than render a blank or fall back to the id."},"name":{"type":"string"},"description":{"type":"string"},"archived_at":{"type":"string","format":"date-time","nullable":true},"open_question_count":{"type":"integer"},"locked":{"type":"object","nullable":true,"required":["code","plan_name"],"description":"Why this board cannot be opened right now — the owning organisation's plan no longer includes project boards — as the same MACHINE CODE and plan name `create_blocked` carries, or `null` when it can be opened. ⛔ The list does not gate (an org invited to somebody else's board must still reach this page), so a board created on a plan that has since lapsed is listed and then refused on open; without this field the list offered a link to a failure page (W43-101).","properties":{"code":{"type":"string"},"plan_name":{"type":"string","nullable":true}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by":{"allOf":[{"$ref":"#/components/schemas/AgencyBoardActor"}],"nullable":true,"description":"Who created the board. `null` if that account no longer exists."},"updated_by":{"allOf":[{"$ref":"#/components/schemas/AgencyBoardActor"}],"nullable":true,"description":"Who last changed the board itself — its name, description or client organisation. ⛔ NOT \"who last touched anything on it\": that is the activity feed. It moves exactly when `updated_at` does, so the pair is always consistent."}}},"AgencyBoardActivity":{"type":"object","required":["id","board_id","verb","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"board_id":{"$ref":"#/components/schemas/Uuid"},"card_id":{"type":"string","format":"uuid","nullable":true},"actor_id":{"type":"string","format":"uuid","nullable":true},"actor":{"allOf":[{"$ref":"#/components/schemas/AgencyBoardActor"}],"nullable":true,"description":"Who did it. `null` when an API key acted, or when the account has since been deleted — the console shows a neutral label rather than the id."},"actor_is_client":{"type":"boolean","description":"Whether the actor acted from the client's side of the board."},"actor_kind":{"$ref":"#/components/schemas/AgencyBoardActorKind"},"subject":{"allOf":[{"$ref":"#/components/schemas/AgencyBoardActor"}],"nullable":true,"description":"The person the act was *about*, where that differs from the actor — `member.added` and `member.removed`. `null` for every other verb."},"verb":{"type":"string","description":"A stable machine key (`card.created`, `question.answered`). The engine never stores a rendered English sentence — the console translates this (§2.7)."},"payload":{"type":"object","additionalProperties":true,"description":"Bounded interpolation values for the translated sentence. `card.updated` and `column.updated` carry a `fields` array naming what actually changed; `member.added`/`member.removed` carry the `member_id` of the person the act was about, who is not the actor."},"visibility":{"$ref":"#/components/schemas/AgencyBoardVisibility"},"occurrences":{"type":"integer","minimum":1,"description":"How many times this act happened. Repeats of the same act, by the same person, on the same card inside ten minutes are folded into one row and counted here rather than appended. ⛔ The count is shown to the reader: a truncation nobody counts reads as a complete list (§2.50)."},"created_at":{"type":"string","format":"date-time","description":"When the FIRST occurrence happened. Never rewritten by a fold."},"last_at":{"type":"string","format":"date-time","description":"When the most recent occurrence happened. Equal to `created_at` on an unfolded row."}}},"AgencyBoardActivityPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgencyBoardActivity"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"AgencyBoardActor":{"type":"object","required":["id","name"],"description":"One person, resolved to something a human recognises. ⛔ Every `*_by` field on the AGENCY's side of this API carries one of these rather than a bare id — the People drawer rendered a raw UUID at a colleague's name until 2026-09-01, and an object with no id-shaped field to reach for is what stops that recurring.","properties":{"id":{"allOf":[{"$ref":"#/components/schemas/Uuid"}],"nullable":true,"description":"Null when a member of staff did this from an impersonated session — `name` is then `support` and no person is named (VERIFY-ACTORS6)."},"name":{"type":"string","description":"Display name, falling back to the email address when the account has never set one. Never blank. `support` for an act a member of staff did while impersonating."},"email":{"type":"string"}}},"AgencyBoardActorKind":{"type":"string","description":"*What sort of thing* performed an act on a board. ⛔ Not derivable from `actor_id`: an automation rule, an AI function, a connected system and the platform itself all act with no user behind them, and a reader shown three anonymous rows cannot tell \"a rule you wrote moved this\" from \"GitHub moved this\" — three different answers to the only question a timeline reader asks, which is *whose behaviour do I change?*\n\n⭐ Always present, `person` on every row written before automations could act. A caller that has to branch on the field's absence is one that will read a missing value as \"a person did it\", which is wrong on exactly the rows this field exists for.","enum":["person","automation","ai","integration","system"]},"AgencyBoardAiModels":{"type":"object","required":["items","reason"],"properties":{"items":{"type":"array","items":{"type":"object","required":["model_id"],"properties":{"model_id":{"type":"string"}}}},"default_model":{"type":"string","nullable":true},"default_provider":{"type":"string","nullable":true},"reason":{"type":"string","description":"Which constraint produced this list — including when it is empty, so an empty picker is distinguishable from one that failed to look."}}},"AgencyBoardAiRun":{"type":"object","required":["function","text","skipped"],"properties":{"function":{"type":"string"},"text":{"type":"string","description":"The output, or the reason it was skipped."},"payload":{"type":"object","additionalProperties":true,"description":"Structured result — labels, sub-tasks, candidate duplicates."},"model":{"type":"string","nullable":true,"description":"The model that served it. Null on a skip, because none was chosen."},"provider":{"type":"string","nullable":true},"funding":{"type":"string","nullable":true,"enum":["byo","credits","included"],"description":"Who paid. `byo` is the customer's own provider key; `credits` and `included` are Zinn®'s. All three are recorded on the same meter."},"usage_id":{"allOf":[{"$ref":"#/components/schemas/Uuid"}],"nullable":true,"description":"The meter row, so board history and AI spend join up. Null on a skip."},"skipped":{"type":"boolean","description":"**Read this.** True means nothing ran and nothing was charged. A caller that treats `200` as \"it worked\" records a success for a call that did nothing."},"skip_reason":{"type":"string","nullable":true,"description":"Machine-readable cause, e.g. `AI_BUDGET_EXHAUSTED`, `PLAN_CREDITS_AI_HOSTING_ONLY` (only AI Hosting plan-included credit is left, and it pays for AI Hosting only), `AI_NOT_IN_GOOD_STANDING`, `not_enough_discussion`, `nothing_blocked`."},"skip_kind":{"type":"string","nullable":true,"enum":["nothing_to_do","not_in_good_standing","not_entitled","unavailable"],"description":"The CLASS of the skip, beside its code. `nothing_to_do` is the product working (a healthy board has nothing blocked; a thread is too short to summarise) and is good news, not a fault. `not_in_good_standing` and `not_entitled` are the customer's to act on. `unavailable` is ours. A client paints the tone from this field, never by matching `skip_reason`, whose vocabulary is open. Null when the call ran."},"skip_params":{"type":"object","additionalProperties":true,"description":"The values the refusal sentence quotes (`count`, `column`), sent structurally so a client can render that sentence in the customer's own language rather than the engine's English. ABSENT — never `{}` — when this engine did not author the sentence: `ai_budget` and `ai_unresolved` carry the meter's and the resolver's own text over an open code vocabulary, and a client must fall back to `text` for those rather than substitute a vaguer translated line that drops the only words telling the customer what to do."},"failure":{"allOf":[{"$ref":"#/components/schemas/VendorFailure"}],"description":"`CLAUDE.md` §57 — what to tell the customer about a refusal, as a stable message key plus a tone, so the dashboard renders the sentence in their own language. Present only on a refusal THIS ENGINE HOLDS A KEY FOR AND THE BOARD DOES NOT AUTHOR: an empty credit balance, and \"no provider is set up\". ABSENT (never `null`) otherwise — including every product-logic refusal, which carries `skip_reason` plus `skip_params` instead, because the board's own sentence quotes `{count}` and `{column}` and picks a real singular, and this payload interpolates neither. A client therefore prefers its own key for the reason when it has one, renders this notice when it does not, and falls back to `text` last. Its class is always `refused`: a skip never names a vendor and never carries a status link. A FAILED run (a 422) carries the same shape on the error envelope's `failure` instead, where the class may be `provider_outage`, `credential_problem` (the customer's own key) or `our_fault`."},"cached":{"type":"boolean","description":"Served from the previous identical run rather than the model."},"created_card_ids":{"type":"array","items":{"$ref":"#/components/schemas/Uuid"}},"run_id":{"allOf":[{"$ref":"#/components/schemas/Uuid"}],"nullable":true}}},"AgencyBoardAiRunPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgencyBoardAiRun"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"AgencyBoardAiRunRequest":{"type":"object","required":["function"],"properties":{"function":{"type":"string","enum":["draft_card","split_epic","summarise_card","summarise_board","triage_card","find_duplicates","release_notes","whats_blocked"],"description":"Which AI function to run."},"card_id":{"$ref":"#/components/schemas/Uuid"},"apply":{"type":"boolean","default":false,"description":"Write the result to the board. Defaults to **false**: AI on a board proposes and a person commits, so the irreversible half must be asked for explicitly."},"force":{"type":"boolean","default":false,"description":"Re-run rather than replay. An identical call within 15 minutes is served from the previous run with no model call and no charge, so a retried automation cannot bill twice; `force` opts out of that."},"options":{"type":"object","additionalProperties":true,"description":"Per-function input. `draft_card` takes `brief` and optionally `source`; `release_notes` takes `column_id`."}}},"AgencyBoardAiSettings":{"type":"object","required":["board_id","auto_triage","digest_cadence"],"properties":{"board_id":{"$ref":"#/components/schemas/Uuid"},"auto_triage":{"type":"boolean","description":"Triage a card when it lands in the intake column. Off by default."},"auto_triage_applies":{"type":"boolean","description":"Apply the triage suggestions, or only propose them. Separate from `auto_triage` because \"tell me what you think\" and \"do it\" are different appetites."},"digest_cadence":{"type":"string","enum":["off","daily","weekdays","weekly"]},"digest_hour_utc":{"type":"integer","minimum":0,"maximum":23},"digest_next_at":{"type":"string","format":"date-time","nullable":true},"digest_last_ok_at":{"type":"string","format":"date-time","nullable":true,"description":"When a digest last SUCCEEDED. Kept separate from `digest_next_at` deliberately: one column cannot serve both a cursor and a staleness alarm."},"preferred_provider":{"type":"string"},"preferred_model":{"type":"string","description":"Blank means the cheapest model we can run, computed from the price table."},"entitled":{"type":"boolean","description":"Whether this organisation's plan includes board AI at all, so a client can stop offering what the engine would refuse. `false` means every run on this board answers `200` with `skipped: true` and `skip_kind: not_entitled`; the customer needs a plan change, not a retry. ABSENT — never `null` and never `false` — when the caller did not scope the question to an organisation, so a client must block only on an explicit `false`: treating the missing case as \"not entitled\" tells a paying customer to upgrade while their settings are still loading. ⛔ It is a claim about ENTITLEMENT only. A run may still be refused for a reason this field cannot see — no credit, no provider key, an account not in good standing — so `true` is permission to OFFER the controls, never a promise the call will spend. ⛔⛔ AND SINCE 2026-09-08 `entitled: false` NO LONGER MEANS \"no AI on this board\" — read it together with `own_key`. An organisation without the entitlement may still run every function on ITS OWN provider key, because we spend nothing there; only the branch that spends OUR credits is refused. A client that blocks on `entitled === false` alone hides a working feature."},"own_key":{"type":"boolean","description":"Whether this organisation holds a live BYO provider key. Present under exactly the same condition as `entitled` — both are omitted when the caller did not scope the question to an organisation — so a client blocks the panel only on `entitled === false && own_key === false`, and offers the controls otherwise. ⛔ It is a PREDICTION, and deliberately weaker than the engine's own gate. The gate in `functions.run` reads the funding decision itself, so it can never wave a spend through; this field asks the cheaper question \"is there a live credential\" and can be wrong in both directions — a key for a different provider than the one requested still resolves to credits, and a key that exists may have been revoked upstream. Being wrong here costs a button that then refuses politely; being wrong in the gate would cost money, which is why only one of the two is allowed to be an inference. ⛔ NOT a claim the key WORKS. A dead key produces a `credential_problem` refusal naming the customer's own provider, which is the actionable answer."}}},"AgencyBoardAiSettingsUpdate":{"type":"object","properties":{"auto_triage":{"type":"boolean"},"auto_triage_applies":{"type":"boolean"},"digest_cadence":{"type":"string","enum":["off","daily","weekdays","weekly"]},"digest_hour_utc":{"type":"integer","minimum":0,"maximum":23},"preferred_provider":{"type":"string","maxLength":16},"preferred_model":{"type":"string","maxLength":100}}},"AgencyBoardAnswer":{"type":"object","required":["body"],"properties":{"body":{"type":"string","maxLength":20000}}},"AgencyBoardAttachment":{"type":"object","required":["id","card_id","filename","size_bytes","scan_state","downloadable"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"card_id":{"$ref":"#/components/schemas/Uuid"},"filename":{"type":"string","maxLength":255},"content_type":{"type":"string"},"size_bytes":{"type":"integer"},"visibility":{"$ref":"#/components/schemas/AgencyBoardVisibility"},"scan_state":{"$ref":"#/components/schemas/AgencyBoardAttachmentScanState"},"downloadable":{"type":"boolean","description":"⭐ Whether these bytes may be fetched right now. Computed from the scan state by the engine rather than derived by a caller — two copies of \"may this leave the building\" is how the second one ends up more permissive."},"uploaded_by":{"allOf":[{"$ref":"#/components/schemas/AgencyBoardActor"}],"nullable":true},"created_at":{"type":"string","format":"date-time"}}},"AgencyBoardAttachmentList":{"type":"object","required":["data","quota"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgencyBoardAttachment"}},"quota":{"$ref":"#/components/schemas/AgencyBoardAttachmentQuota"}}},"AgencyBoardAttachmentQuota":{"type":"object","required":["used_bytes","limit_bytes","max_file_bytes","max_per_card"],"properties":{"used_bytes":{"type":"integer","description":"Bytes this organisation already holds across every board it owns."},"limit_bytes":{"type":"integer","description":"The organisation's ceiling."},"max_file_bytes":{"type":"integer","description":"The largest single file accepted."},"max_per_card":{"type":"integer","description":"How many files one card may hold."}}},"AgencyBoardAttachmentScanState":{"type":"string","description":"Where an uploaded file is in the malware pipeline. ⛔ `clean` is the ONLY state the bytes are ever served in — `pending`, `infected` and `error` all refuse, including to the agency's own staff. An unscannable file is not a clean file.","enum":["pending","clean","infected","error"]},"AgencyBoardAttachmentUpdate":{"type":"object","required":["visibility"],"properties":{"visibility":{"$ref":"#/components/schemas/AgencyBoardVisibility"}}},"AgencyBoardCard":{"type":"object","required":["id","board_id","column_id","title","visibility","position"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"board_id":{"$ref":"#/components/schemas/Uuid"},"column_id":{"$ref":"#/components/schemas/Uuid"},"title":{"type":"string"},"body":{"type":"string"},"visibility":{"$ref":"#/components/schemas/AgencyBoardVisibility"},"position":{"type":"integer"},"assignee_id":{"type":"string","format":"uuid","nullable":true},"due_at":{"type":"string","format":"date-time","nullable":true},"created_by_client":{"type":"boolean","description":"Whether the client raised this card themselves."},"archived_at":{"type":"string","format":"date-time","nullable":true},"cover_colour":{"allOf":[{"$ref":"#/components/schemas/AgencyBoardLabelColour"}],"description":"A colour band across the top of the card, or the empty string for none. ⛔ Shares the label palette rather than declaring a second one: two palettes on one screen is how a cover and a label chip end up two different greens, which a customer reads as a bug."},"labels":{"type":"array","description":"The labels this card wears, in the board's label order. ⛔ Agency-only — the client's projection of a card carries no labels at all, because a label is the agency's private vocabulary for its own pipeline (*Chasing payment*, *Low margin*) and a card can be fine to share when the word it is filed under is not.","items":{"$ref":"#/components/schemas/AgencyBoardLabel"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"AgencyBoardCardCreate":{"type":"object","required":["column_id","title"],"properties":{"column_id":{"type":"string","format":"uuid"},"title":{"type":"string","maxLength":300},"body":{"type":"string","maxLength":20000},"visibility":{"$ref":"#/components/schemas/AgencyBoardVisibility"},"assignee_id":{"type":"string","format":"uuid","nullable":true},"due_at":{"type":"string","format":"date-time","nullable":true}}},"AgencyBoardCardDetail":{"allOf":[{"$ref":"#/components/schemas/AgencyBoardCard"},{"type":"object","properties":{"comments":{"type":"array","items":{"$ref":"#/components/schemas/AgencyBoardComment"}},"questions":{"type":"array","items":{"$ref":"#/components/schemas/AgencyBoardQuestion"}}}}]},"AgencyBoardCardLabels":{"type":"object","required":["label_ids"],"properties":{"label_ids":{"type":"array","maxItems":50,"description":"The COMPLETE set the card should wear afterwards — this replaces, it does not add. An empty array takes every label off, which is why the array may be empty: an add/remove pair could not express \"remove the last one\" in a single request, and the picker is one interaction.","items":{"type":"string","format":"uuid"}},"created_by":{"allOf":[{"$ref":"#/components/schemas/AgencyBoardActor"}],"nullable":true},"updated_by":{"allOf":[{"$ref":"#/components/schemas/AgencyBoardActor"}],"nullable":true,"description":"Who last edited this card. Moves exactly when `updated_at` does."},"assignee":{"allOf":[{"$ref":"#/components/schemas/AgencyBoardActor"}],"nullable":true,"description":"The resolved form of `assignee_id`."}}},"AgencyBoardCardMove":{"type":"object","required":["column_id","position"],"properties":{"column_id":{"type":"string","format":"uuid"},"position":{"type":"integer","minimum":0}}},"AgencyBoardCardPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgencyBoardCard"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"AgencyBoardCardUpdate":{"type":"object","properties":{"title":{"type":"string","maxLength":300},"body":{"type":"string","maxLength":20000},"visibility":{"$ref":"#/components/schemas/AgencyBoardVisibility"},"assignee_id":{"type":"string","format":"uuid","nullable":true},"due_at":{"type":"string","format":"date-time","nullable":true},"cover_colour":{"type":"string","description":"A palette token, or the empty string to clear the cover. ⛔ The empty string is the CLEAR rather than `null`, so there is exactly one spelling of \"no cover\".","enum":["neutral","info","violet","ok","warn","crit",""]}}},"AgencyBoardChecklistItem":{"type":"object","required":["id","card_id","text","position"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"card_id":{"$ref":"#/components/schemas/Uuid"},"text":{"type":"string","maxLength":300},"position":{"type":"integer"},"done_at":{"type":"string","format":"date-time","nullable":true,"description":"When it was ticked. `null` means outstanding."},"done_by":{"allOf":[{"$ref":"#/components/schemas/AgencyBoardActor"}],"nullable":true,"description":"Who ticked it. ⛔ Kept when the item is un-ticked as well, so \"Sam ticked this and then un-ticked it\" stays answerable."},"created_at":{"type":"string","format":"date-time"}}},"AgencyBoardChecklistItemCreate":{"type":"object","required":["text"],"properties":{"text":{"type":"string","maxLength":300}}},"AgencyBoardChecklistItemUpdate":{"type":"object","required":["done"],"properties":{"done":{"type":"boolean"}}},"AgencyBoardChecklistList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgencyBoardChecklistItem"}}}},"AgencyBoardClient":{"type":"object","required":["id","name"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"name":{"type":"string"},"type":{"type":"string"}}},"AgencyBoardClientPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgencyBoardClient"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"AgencyBoardColumn":{"type":"object","required":["id","board_id","name","position","visibility","is_intake"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"board_id":{"$ref":"#/components/schemas/Uuid"},"name":{"type":"string"},"position":{"type":"integer"},"visibility":{"$ref":"#/components/schemas/AgencyBoardVisibility"},"is_intake":{"type":"boolean","description":"The single column a client may raise a request in. At most one per board."},"wip_limit":{"type":"integer","nullable":true,"description":"Advisory only, shown in the UI. ⛔ It never refuses a move: a WIP limit that blocks work turns a management convention into an outage on a Friday evening."}}},"AgencyBoardColumnCreate":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":120},"visibility":{"$ref":"#/components/schemas/AgencyBoardVisibility"},"wip_limit":{"type":"integer","minimum":1,"nullable":true}}},"AgencyBoardColumnList":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AgencyBoardColumn"}}}},"AgencyBoardColumnMove":{"type":"object","required":["position"],"properties":{"position":{"type":"integer","minimum":0}}},"AgencyBoardColumnUpdate":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"visibility":{"$ref":"#/components/schemas/AgencyBoardVisibility"},"wip_limit":{"type":"integer","minimum":1,"nullable":true},"position":{"type":"integer","minimum":0},"is_intake":{"type":"boolean"}}},"AgencyBoardComment":{"type":"object","required":["id","card_id","body","visibility","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"card_id":{"$ref":"#/components/schemas/Uuid"},"author_id":{"type":"string","format":"uuid","nullable":true},"author_is_client":{"type":"boolean"},"author":{"allOf":[{"$ref":"#/components/schemas/AgencyBoardActor"}],"nullable":true},"body":{"type":"string"},"visibility":{"$ref":"#/components/schemas/AgencyBoardVisibility"},"created_at":{"type":"string","format":"date-time"}}},"AgencyBoardCommentCreate":{"type":"object","required":["body"],"properties":{"body":{"type":"string","maxLength":20000},"visibility":{"$ref":"#/components/schemas/AgencyBoardVisibility"}}},"AgencyBoardCreate":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":4000},"org_id":{"type":"string","format":"uuid"},"client_org_id":{"type":"string","format":"uuid","nullable":true}}},"AgencyBoardDetail":{"allOf":[{"$ref":"#/components/schemas/AgencyBoard"},{"type":"object","properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/AgencyBoardColumn"}},"cards":{"type":"array","items":{"$ref":"#/components/schemas/AgencyBoardCard"}},"labels":{"type":"array","description":"The board's whole label vocabulary, so the card picker needs no second request. A board holds a handful of these.","items":{"$ref":"#/components/schemas/AgencyBoardLabel"}}}}]},"AgencyBoardInvitationAccepted":{"type":"object","required":["invitation_id","email","role","board_id"],"properties":{"invitation_id":{"$ref":"#/components/schemas/Uuid"},"email":{"type":"string"},"role":{"type":"string","enum":["manager","member","client"]},"member_org_id":{"$ref":"#/components/schemas/Uuid"},"board_id":{"$ref":"#/components/schemas/Uuid"}}},"AgencyBoardInvite":{"type":"object","required":["id","board_id","role","token_prefix","expires_at","uses","created_at","is_live"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"board_id":{"$ref":"#/components/schemas/Uuid"},"role":{"$ref":"#/components/schemas/AgencyBoardInviteRole"},"token":{"type":"string","description":"The full link token. ⛔ **Present on the create response and NOWHERE ELSE.** Only its SHA-256 digest is stored, so nothing can re-derive it — a screen that needs it must keep it from this response, which is why the UI offers *copy* and not *show*."},"token_prefix":{"type":"string","description":"The first few characters, so a manager with three links open can tell them apart. Far too short to shorten the search space of the secret part."},"label":{"type":"string","description":"A note the manager typed. Never shown to the recipient."},"member_org_id":{"type":"string","format":"uuid","nullable":true,"description":"The organisation a seat from this link belongs to. `null` for `viewer`, which seats nobody."},"expires_at":{"type":"string","format":"date-time","description":"When the link stops admitting **new** people. ⛔ Expiry does not evict anybody who already joined — a colleague who joined in March must not lose the board in April because the string somebody pasted has aged out. Revocation is the remedy for a link that went astray, and that one does cascade. There is deliberately no \"never expires\" option; the ceiling is 90 days."},"max_uses":{"type":"integer","nullable":true,"minimum":1,"description":"`null` is unlimited. `1` makes the link single-use."},"uses":{"type":"integer","minimum":0,"description":"Seats created through this link. A repeat visit by somebody already on the board does **not** count, so a client who bookmarks the link cannot exhaust it."},"revoked_at":{"type":"string","format":"date-time","nullable":true},"last_used_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"is_live":{"type":"boolean","description":"Whether the link may admit somebody new right now — not revoked, not expired, not exhausted. Computed, so a caller never has to re-implement all three conditions."}}},"AgencyBoardInviteCreate":{"type":"object","properties":{"role":{"allOf":[{"$ref":"#/components/schemas/AgencyBoardInviteRole"}],"default":"viewer"},"label":{"type":"string","maxLength":120},"expires_in_days":{"type":"integer","minimum":1,"maximum":90,"default":14},"max_uses":{"type":"integer","minimum":1,"description":"Omit for an unlimited link."}}},"AgencyBoardInviteList":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AgencyBoardInvite"}}}},"AgencyBoardInviteRevoked":{"type":"object","required":["revoked","seats_removed"],"properties":{"revoked":{"type":"boolean"},"seats_removed":{"type":"integer","minimum":0,"description":"How many board seats the revocation removed. Reported rather than swallowed: a silent side effect on a destructive action is how somebody removes four people believing they only closed a door."}}},"AgencyBoardInviteRole":{"type":"string","enum":["viewer","client","member","manager"],"description":"What a share link grants. `viewer` is **link-only**: it creates no board seat and no organisation membership, because it grants no identity — it is read-through-the-token, which is what lets somebody open a pasted link with no account. The other three seat the person on the board and therefore require them to sign in."},"AgencyBoardLabel":{"type":"object","required":["id","board_id","name","colour","position"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"board_id":{"$ref":"#/components/schemas/Uuid"},"name":{"type":"string","maxLength":60},"colour":{"$ref":"#/components/schemas/AgencyBoardLabelColour"},"position":{"type":"integer"}}},"AgencyBoardLabelColour":{"type":"string","description":"⛔ A palette **token**, never a hex string. The consoles render in the viewer's theme and every colour the design system owns has a dark variant; a hex an agency picked in daylight is a white-on-white chip at night, on a screen no type, test or gate can check because the value is data rather than code.","enum":["neutral","info","violet","ok","warn","crit"]},"AgencyBoardLabelCreate":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":60},"colour":{"$ref":"#/components/schemas/AgencyBoardLabelColour"}}},"AgencyBoardLabelList":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AgencyBoardLabel"}}}},"AgencyBoardLabelUpdate":{"type":"object","properties":{"name":{"type":"string","maxLength":60},"colour":{"$ref":"#/components/schemas/AgencyBoardLabelColour"}}},"AgencyBoardMember":{"type":"object","required":["id","board_id","user_id","member_org_id","role"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"board_id":{"$ref":"#/components/schemas/Uuid"},"user_id":{"$ref":"#/components/schemas/Uuid"},"member_org_id":{"allOf":[{"$ref":"#/components/schemas/Uuid"}],"description":"The organisation this seat belongs to — the agency's, or the client's."},"role":{"type":"string","enum":["manager","member","client"]},"last_read_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"user":{"allOf":[{"$ref":"#/components/schemas/AgencyBoardActor"}],"nullable":true,"description":"Who holds this seat, by name. ⛔ Render THIS, never `user_id` — the People drawer printed the id at a colleague's name until 2026-09-01 (`docs/425`)."},"invited_by":{"allOf":[{"$ref":"#/components/schemas/AgencyBoardActor"}],"nullable":true,"description":"Who gave the seat. A seat given by our staff from an impersonated session reads `{\"id\": null, \"name\": \"support\"}` — never the customer the session was minted for and never the staff member (ACTORS7); a reseller's own person signed in through the reseller's single sign-on reads `{\"id\": null, \"name\": \"<reseller name>\"}` (VERIFY-ACTORS7); the admin console reads the activity row's `acting_ref`."}}},"AgencyBoardMemberCreate":{"type":"object","required":["role"],"properties":{"user_id":{"type":"string","format":"uuid","description":"Somebody who already has an account. Give this **or** `email`, not both."},"email":{"type":"string","format":"email","description":"Invite somebody who does not have an account yet."},"role":{"type":"string","enum":["manager","member","client"]},"member_org_id":{"type":"string","format":"uuid","description":"Which organisation this seat belongs to. Ignored for a `client` seat, which is always the board's own client organisation."}}},"AgencyBoardMemberList":{"type":"object","required":["items","pending_invitations"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AgencyBoardMember"}},"pending_invitations":{"type":"array","items":{"$ref":"#/components/schemas/AgencyBoardPendingInvitation"}}}},"AgencyBoardPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgencyBoard"}},"page":{"$ref":"#/components/schemas/PageMeta"},"create_blocked":{"type":"object","nullable":true,"required":["code","plan_name"],"description":"Why this caller cannot create a board here, as a MACHINE CODE the client renders in the customer's own language — or `null` when they can.\n\n⛔⛔ It exists because the list deliberately does **not** refuse an un-entitled caller, and must not: an organisation invited to somebody else's board is not entitled to boards of its own and still has to be able to open this page. So the list succeeds, the create refuses, and without this field the screen between them offers a button that can only fail. Measured on production 2026-09-03: `GET` returned `200 {\"data\": []}` and `POST` returned `422 FEATURE_NOT_INCLUDED` for the same organisation.\n\n⛔ A CODE, not a sentence, and it carried the entitlement layer's English prose until W39-A measured what that meant: this console ships in 57 locales and was rendering the sentence verbatim, so an agency reading the product in German got an English refusal on the one screen where they are already blocked (§2.7).\n\n⭐ It is also where a QUOTA refusal belongs — a plan that includes boards but has run out of them is a different refusal with the same consequence for the button, and one field beats two concepts a console must combine.","properties":{"code":{"type":"string","enum":["boards_not_in_plan","no_active_plan"],"description":"`boards_not_in_plan` — the organisation has a plan and boards are not in it, so the remedy is an upgrade. `no_active_plan` — nothing in the org chain grants anything, so the remedy is choosing a plan. The two are kept apart because telling an org with no subscription to \"upgrade\" sends them to compare their current plan against nothing, which is what `require_feature`'s own docstring warns about."},"plan_name":{"type":"string","nullable":true,"description":"The plan the organisation is actually on, so the client can name it. Always `null` for `no_active_plan` — there is no plan to name."}}}}},"AgencyBoardPendingInvitation":{"type":"object","required":["id","email","org_id","is_client"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"email":{"type":"string"},"org_id":{"$ref":"#/components/schemas/Uuid"},"is_client":{"type":"boolean","description":"Whether this invite is into the board's client organisation."},"expires_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"AgencyBoardQuestion":{"type":"object","required":["id","card_id","body","status","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"card_id":{"$ref":"#/components/schemas/Uuid"},"body":{"type":"string"},"status":{"type":"string","enum":["open","answered","cancelled"]},"answer_body":{"type":"string"},"answered_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"asked_by":{"allOf":[{"$ref":"#/components/schemas/AgencyBoardActor"}],"nullable":true},"answered_by":{"allOf":[{"$ref":"#/components/schemas/AgencyBoardActor"}],"nullable":true}}},"AgencyBoardQuestionCreate":{"type":"object","required":["body"],"properties":{"body":{"type":"string","maxLength":4000}}},"AgencyBoardUpdate":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":4000},"client_org_id":{"type":"string","format":"uuid","nullable":true}}},"AgencyBoardView":{"type":"object","required":["id","board_id","name","definition","is_default"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"board_id":{"$ref":"#/components/schemas/Uuid"},"name":{"type":"string","maxLength":120},"definition":{"$ref":"#/components/schemas/AgencyBoardViewDefinition"},"is_default":{"type":"boolean","description":"What a member sees on opening this board cold. At most one per board."},"created_at":{"type":"string","format":"date-time"}}},"AgencyBoardViewCreate":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":120},"definition":{"$ref":"#/components/schemas/AgencyBoardViewDefinition"},"is_default":{"type":"boolean"}}},"AgencyBoardViewDefinition":{"type":"object","description":"The filters, grouping and search that make up one cut of a board. ⛔ Unknown keys are DROPPED on save rather than refused, so a newer console's extra control does not 400 against an older engine mid-deploy — and dropping is safe because no value here is ever executed.","properties":{"search":{"type":"string"},"filter":{"type":"string","enum":["all","client","internal","questions","overdue","unassigned"]},"labelId":{"type":"string"},"groupBy":{"type":"string","enum":["none","assignee","visibility","label"]},"showArchived":{"type":"boolean"}}},"AgencyBoardViewList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgencyBoardView"}}}},"AgencyBoardVisibility":{"type":"string","enum":["internal","client"],"description":"Who may see this object. `internal` is always the default. A **card** reaches the client only when it is `client` **and its column is too** — an AND, not inheritance, because that is the only rule under which both of the obvious slips (dragging a shared card into an internal column; marking a column shared while it already holds internal cards) fail towards hiding."},"AgencyClient":{"type":"object","description":"A client an agency invoices. ⛔ A contact record the agency typed, NOT a platform organization — the client may have no account here at all.","required":["id","name","currency"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"name":{"type":"string"},"contact_name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"address":{"type":"string"},"tax_number_label":{"type":"string"},"tax_number":{"type":"string"},"currency":{"type":"string"},"country":{"type":"string","nullable":true,"minLength":2,"maxLength":2,"description":"ISO-3166-1 alpha-2, optional. Required only to bill this client on Zinn®'s own checkout (the platform organisation, docs/670 §3), where the country decides the VAT on the bill and is never guessed."},"locale":{"type":"string","description":"Which language this client's invoices and payment page render in. An agency in Berlin invoicing a French client sends a French invoice."},"notes":{"type":"string"},"archived":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"AgencyClientHistory":{"allOf":[{"$ref":"#/components/schemas/AgencyClient"},{"type":"object","properties":{"invoices":{"type":"array","items":{"$ref":"#/components/schemas/AgencyInvoice"}},"outstanding_minor":{"type":"integer","description":"What this client still owes, in minor units."},"invoiced_total_minor":{"type":"integer","description":"Everything ever billed to them, void invoices excluded."}}}]},"AgencyClientList":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AgencyClient"}}}},"AgencyClientWrite":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"contact_name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"address":{"type":"string"},"tax_number_label":{"type":"string"},"tax_number":{"type":"string"},"currency":{"type":"string"},"country":{"type":"string","nullable":true,"description":"Two-letter ISO code, or empty or null to clear. Anything else is refused."},"locale":{"type":"string"},"notes":{"type":"string"},"archived":{"type":"boolean"}}},"AgencyInvoice":{"type":"object","description":"One invoice an agency has raised against its own client. ⛔⛔ Not a Zinn® invoice: different company, different tax registration, different number series, and money that never touches our balance.","required":["id","status","currency","issue_date","total_minor"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"number":{"type":"string","description":"The agency's own number. ⛔ Empty until issue: a number allocated to something that may never be sent leaves a hole in a sequence."},"status":{"type":"string","enum":["draft","sent","partially_paid","paid","void"]},"is_overdue":{"type":"boolean","description":"⭐ DERIVED from the due date and the status, never stored — so there is no sweep to maintain a flag and nothing to go stale. A draft is never overdue however old it is: nobody has been asked to pay it."},"client_id":{"$ref":"#/components/schemas/Uuid"},"client_name":{"type":"string"},"currency":{"type":"string"},"issue_date":{"type":"string","format":"date"},"due_date":{"type":"string","format":"date","nullable":true},"reference":{"type":"string"},"notes":{"type":"string"},"footer":{"type":"string"},"subtotal_minor":{"type":"integer"},"discount_minor":{"type":"integer"},"tax_minor":{"type":"integer"},"total_minor":{"type":"integer"},"amount_paid_minor":{"type":"integer"},"amount_due_minor":{"type":"integer"},"tax_breakdown":{"type":"array","items":{"$ref":"#/components/schemas/AgencyInvoiceTaxGroup"}},"source":{"type":"string","description":"Where the invoice came from — `time_tracking` when it was generated from tracked hours, empty when an agency typed it."},"sent_at":{"type":"string","format":"date-time","nullable":true},"last_sent_to":{"type":"string"},"paid_at":{"type":"string","format":"date-time","nullable":true},"void_reason":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/AgencyInvoiceLine"}},"payments":{"type":"array","items":{"$ref":"#/components/schemas/AgencyInvoicePayment"}},"portal_url":{"type":"string","nullable":true,"description":"The payment link to send to the client. ⛔ Returned on a SINGLE-invoice read only, never in a list: a list is the thing that gets logged, cached and pasted into a support ticket, and every row of it would be a live payment capability. `null` while the invoice is a draft, void, or the link has been revoked."}}},"AgencyInvoiceBlock":{"type":"object","description":"A reusable free-text block an agency saves once and reuses.","required":["id","name","kind"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"name":{"type":"string"},"kind":{"type":"string","enum":["footer","notes","terms"]},"body":{"type":"string"},"is_default":{"type":"boolean"}}},"AgencyInvoiceBlockList":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AgencyInvoiceBlock"}}}},"AgencyInvoiceBlockWrite":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["footer","notes","terms"]},"body":{"type":"string"},"is_default":{"type":"boolean"}}},"AgencyInvoiceCheckout":{"type":"object","required":["status","amount_minor","currency"],"properties":{"status":{"type":"string","description":"`captured` when the rail settled synchronously, `pending` for a crypto invoice or an unconfirmed intent, `requires_action` for 3-D Secure."},"provider_code":{"type":"string"},"client_token":{"type":"string","nullable":true,"description":"A short-lived client-side credential for the gateway's browser SDK. ⛔ Never persisted anywhere."},"redirect_url":{"type":"string","nullable":true,"description":"Where to send the payer for rails that use an approval or hosted page."},"action_kind":{"type":"string","nullable":true,"enum":["authenticate","approve","pay","add_payment_method"]},"amount_minor":{"type":"integer"},"currency":{"type":"string"}}},"AgencyInvoiceCreate":{"type":"object","additionalProperties":false,"description":"⚖️ Both doors the owner asked for: name a saved `client_id`, or send a `client` object to create one inline — a client typed during invoicing is SAVED, so next time it can simply be selected.","properties":{"client_id":{"$ref":"#/components/schemas/Uuid"},"client":{"$ref":"#/components/schemas/AgencyClientWrite"},"currency":{"type":"string"},"issue_date":{"type":"string","format":"date"},"due_date":{"type":"string","format":"date"},"reference":{"type":"string"},"notes":{"type":"string"},"footer":{"type":"string"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/AgencyInvoiceLineWrite"}}}},"AgencyInvoiceLine":{"allOf":[{"$ref":"#/components/schemas/AgencyInvoiceLineWrite"},{"type":"object","properties":{"id":{"$ref":"#/components/schemas/Uuid"},"position":{"type":"integer"},"quantity_display":{"type":"string","description":"The quantity as the document prints it, at the precision that makes the row multiply out — 7 minutes at £60.00/h reads `0.116667`, and 0.116667 × 60 is £7.00 to the penny."},"tax_rate_bps":{"type":"integer","description":"The rate as it was when this line was saved. ⭐ Copied, not looked up, so changing \"VAT\" from 20% to 17.5% next April cannot restate last month's invoice."},"tax_rate_name":{"type":"string"},"line_total_minor":{"type":"integer"},"source_ref":{"type":"string","description":"Where the line came from — a time-entry id when the invoice was generated from tracked time. Empty for a line typed by hand."}}}]},"AgencyInvoiceLineWrite":{"type":"object","additionalProperties":false,"description":"One line, as the builder sends it. Two shapes, chosen by `kind`. ⛔⛔ An **hourly** line carries the RATE and the minutes — never a per-minute unit price. £50.00/h ÷ 60 = 83.333p, and 83p × 90 min is £74.70 against a true £75.00: a silent, systematic under-bill on every hourly line, invisible to any test that only compares integers. The engine rounds once, from the rate.","properties":{"description":{"type":"string"},"kind":{"type":"string","enum":["hourly","quantity"],"default":"quantity"},"minutes":{"type":"integer","minimum":0,"description":"`kind: hourly` — the duration billed."},"rate_minor_per_hour":{"type":"integer","minimum":0,"description":"`kind: hourly` — the hourly rate in minor units."},"quantity_micro":{"type":"integer","minimum":0,"description":"\"`kind: quantity` — MILLIONTHS of a unit. One item is `1000000`. Micro rather than milli because milli cannot represent a third: 0.333 h × £50.00 is £16.65 against a true £16.67.\""},"unit_price_minor":{"type":"integer","minimum":0},"unit_label":{"type":"string","description":"\"hour\", \"item\", \"word\" — presentational only."},"discount_bps":{"type":"integer","minimum":0,"maximum":10000},"tax_rate_id":{"$ref":"#/components/schemas/Uuid"}}},"AgencyInvoiceList":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AgencyInvoice"}}}},"AgencyInvoiceLogo":{"type":"object","required":["logo_sha256"],"properties":{"logo_sha256":{"type":"string","description":"The content digest. ⛔ Not a URL — the invoice renderer inlines the bytes as a `data:` URI and follows no external reference at render time."},"width":{"type":"integer"},"height":{"type":"integer"},"byte_size":{"type":"integer"}}},"AgencyInvoicePayment":{"type":"object","required":["id","amount_minor","currency","method"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"amount_minor":{"type":"integer"},"currency":{"type":"string"},"method":{"type":"string","enum":["card","wallet","crypto","bank_transfer","cash","cheque","other"]},"provider_code":{"type":"string","description":"Which of the agency's own gateways collected it. Empty when the agency recorded the payment by hand."},"received_at":{"type":"string","format":"date-time"},"note":{"type":"string"}}},"AgencyInvoicePaymentWrite":{"type":"object","additionalProperties":false,"properties":{"amount_minor":{"type":"integer","minimum":1,"description":"Defaults to the outstanding balance."},"method":{"type":"string","enum":["card","wallet","crypto","bank_transfer","cash","cheque","other"]},"note":{"type":"string"}}},"AgencyInvoicePdfLink":{"type":"object","required":["url","expires_at"],"properties":{"url":{"type":"string","description":"⛔ A signed URL, and therefore a **credential** until it expires. Do not log it, persist it or put it in a query string of your own — hand it to the thing that will fetch it and let it lapse."},"expires_at":{"type":"string","format":"date-time","description":"When the signature stops verifying. ⛔ An absolute instant, not a duration — the spec said `expires_in` for one commit and the handler read a field that does not exist, which was an `AttributeError` inside the view and a **500 on every PDF download**."}}},"AgencyInvoicePortal":{"type":"object","description":"The invoice as the payer sees it — already localized and already formatted, so the page needs no money or date logic of its own.","required":["number","status","currency","total","amount_due_minor"],"properties":{"number":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"issue_date":{"type":"string","format":"date"},"due_date":{"type":"string","format":"date","nullable":true},"seller":{"type":"object","additionalProperties":true,"description":"The issuing agency, frozen at issue."},"buyer":{"type":"object","additionalProperties":true},"lines":{"type":"array","items":{"type":"object","additionalProperties":true}},"tax_groups":{"type":"array","items":{"type":"object","additionalProperties":true}},"subtotal":{"type":"string"},"tax_total":{"type":"string"},"total":{"type":"string"},"amount_due":{"type":"string"},"amount_due_minor":{"type":"integer"},"labels":{"type":"object","additionalProperties":{"type":"string"},"description":"Every label on the page, already in the client's language. ⛔ Served from the platform's translation catalogue rather than a gettext call: this engine has no `.po` files, so `gettext` would return English for ever in all 58 locales with nothing red anywhere."},"direction":{"type":"string","enum":["ltr","rtl"]},"notes":{"type":"string"},"offline":{"type":"object","description":"How to pay when the agency has connected no gateway — their own written payment instructions and contact address, frozen onto the document. ⭐ A payment page that offered nothing to such an agency's client would be useless to them.","properties":{"payment_instructions":{"type":"string"},"contact_email":{"type":"string"}}}}},"AgencyInvoiceSendResult":{"allOf":[{"$ref":"#/components/schemas/AgencyInvoice"},{"type":"object","properties":{"sent_to":{"type":"string"}}}]},"AgencyInvoiceTaxGroup":{"type":"object","description":"One tax line on the document. ⭐ Tax is rounded once per rate GROUP at invoice level, never per line: three £0.01 lines at 20% are £0.01 of tax together and £0.00 each, and a tax authority expects the figure on the document to be the tax actually charged.","required":["rate_bps","taxable_minor","tax_minor"],"properties":{"tax_rate_id":{"type":"string","nullable":true,"description":"`null` for lines carrying no tax at all — which is not the same as a 0% registration."},"rate_bps":{"type":"integer"},"taxable_minor":{"type":"integer"},"tax_minor":{"type":"integer"}}},"AgencyInvoiceTotals":{"type":"object","required":["subtotal_minor","tax_minor","total_minor"],"properties":{"line_totals_minor":{"type":"array","items":{"type":"integer"}},"subtotal_minor":{"type":"integer"},"discount_minor":{"type":"integer"},"tax_minor":{"type":"integer"},"total_minor":{"type":"integer"},"tax_groups":{"type":"array","items":{"$ref":"#/components/schemas/AgencyInvoiceTaxGroup"}}}},"AgencyInvoiceUpdate":{"type":"object","additionalProperties":false,"description":"⛔ Draft only. An issued invoice's figures are frozen and this answers `409`.","properties":{"currency":{"type":"string"},"issue_date":{"type":"string","format":"date"},"due_date":{"type":"string","format":"date","nullable":true},"reference":{"type":"string"},"notes":{"type":"string"},"footer":{"type":"string"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/AgencyInvoiceLineWrite"}}}},"AgencyInvoicingGatewayStatus":{"type":"object","required":["established","gateways"],"properties":{"established":{"type":"boolean","description":"⛔ `false` means we could NOT look, which is not the same fact as \"you have none\" — one is ours to fix and the other is yours. A screen must not render them the same way."},"gateways":{"type":"array","items":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"name":{"type":"string"}}}},"can_collect_online":{"type":"boolean"}}},"AgencyInvoicingProfile":{"type":"object","description":"An agency's invoicing identity — what its invoices say they are FROM (docs/589). ⛔ Not the same thing as its panel branding: an invoice needs a legal entity, and an agency may bill under a different one from the one on its dashboard.","required":["default_currency","number_prefix","next_number"],"properties":{"business_name":{"type":"string"},"address":{"type":"string","description":"The registered address, one line per newline. Free-form because address shape is a property of a country, not of our schema."},"email":{"type":"string"},"phone":{"type":"string"},"website":{"type":"string"},"tax_number_label":{"type":"string","description":"What the agency calls its tax registration — \"VAT number\", \"ABN\", \"GSTIN\", \"EIN\". ⛔ Printed only when the number is set too: a label with no number is an empty row, and a number with no label is an unexplained identifier on a legal document."},"tax_number":{"type":"string"},"payment_instructions":{"type":"string","description":"Bank details or a \"PayPal me at …\" line, printed on the document verbatim and shown on the payment page. ⭐ Never translated — translating a payment instruction is not a safe act."},"logo_sha256":{"type":"string","description":"A digest into the content-addressed logo store, never a URL. That is what lets the PDF inline the mark with no network call at render time."},"accent_colour":{"type":"string"},"default_currency":{"type":"string"},"default_payment_terms_days":{"type":"integer"},"default_footer":{"type":"string"},"default_notes":{"type":"string"},"number_prefix":{"type":"string"},"number_padding":{"type":"integer"},"next_number":{"type":"integer","description":"The next sequence number. ⛔ Read-only. Rewinding it would mint a duplicate number for a document already in a client's hands."},"next_number_preview":{"type":"string","description":"What the next invoice will be called, e.g. `INV-0042`."}}},"AgencyInvoicingProfileUpdate":{"type":"object","additionalProperties":false,"description":"⛔ `next_number` is deliberately absent — see the read schema.","properties":{"business_name":{"type":"string"},"address":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"website":{"type":"string"},"tax_number_label":{"type":"string"},"tax_number":{"type":"string"},"payment_instructions":{"type":"string"},"logo_sha256":{"type":"string"},"accent_colour":{"type":"string"},"default_currency":{"type":"string"},"default_payment_terms_days":{"type":"integer"},"default_footer":{"type":"string"},"default_notes":{"type":"string"},"number_prefix":{"type":"string"},"number_padding":{"type":"integer"}}},"AgencySeoOverview":{"type":"object","required":["data","page","summary"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgencySeoSite"}},"page":{"$ref":"#/components/schemas/PageMeta"},"summary":{"type":"object","required":["org_id","currency","credits","totals"],"properties":{"org_id":{"type":"string","format":"uuid"},"currency":{"type":"string"},"credits":{"type":"object","required":["balance_micros","is_low","is_empty","forecast","held_since","needed_micros"],"properties":{"balance_micros":{"type":"integer"},"is_low":{"type":"boolean"},"is_empty":{"type":"boolean"},"forecast":{"type":"object","properties":{"spend_micros":{"type":"integer"},"balance_micros":{"type":"integer"},"days":{"type":"integer"},"runs_out_on":{"type":["string","null"],"format":"date"},"short":{"type":"boolean"},"currency":{"type":"string"}}},"held_since":{"type":["string","null"],"format":"date-time"},"needed_micros":{"type":"integer"}}},"totals":{"type":"object","required":["sites","active_sites","spent_this_month_micros","open_guard_incidents"],"properties":{"sites":{"type":"integer"},"active_sites":{"type":"integer"},"spent_this_month_micros":{"type":"integer"},"open_guard_incidents":{"type":"integer"}}}}}}},"AgencySeoSite":{"type":"object","required":["connection_id","site_url","domain","status","scopes","plugin_version","last_used_at","created_at","target_id","monthly_spend_cap_micros","spent_this_month_micros","cap_remaining_micros","held_kinds","open_guard_incidents","scores","client"],"properties":{"connection_id":{"type":"string","format":"uuid"},"site_url":{"type":"string"},"domain":{"type":"string"},"status":{"type":"string","enum":["active","revoked"]},"scopes":{"type":"array","items":{"type":"string"}},"plugin_version":{"type":"string"},"last_used_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"target_id":{"type":["string","null"],"format":"uuid"},"monthly_spend_cap_micros":{"type":["integer","null"],"description":"USD micros."},"spent_this_month_micros":{"type":"integer","description":"USD micros, net of refunds, from the credit ledger."},"cap_remaining_micros":{"type":["integer","null"]},"held_kinds":{"type":"object","additionalProperties":{"type":"string","format":"date-time"},"description":"Kinds held for credit","and since when.":null},"open_guard_incidents":{"type":"integer"},"scores":{"$ref":"#/components/schemas/AgencySeoSiteScores"},"client":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}}},"AgencySeoSiteScores":{"type":"object","properties":{"rank_tracked":{"type":"integer"},"rank_top10":{"type":"integer"},"rank_average":{"type":["number","null"]},"onpage_score":{"type":["integer","null"]},"ai_score":{"type":["integer","null"]},"backlinks_domains":{"type":["integer","null"]},"measured_at":{"type":"string","format":"date-time"},"index":{"type":["object","null"],"properties":{"checked":{"type":"integer"},"indexed":{"type":"integer"}}}}},"AgencyTaxRate":{"type":"object","description":"One tax rate an agency charges. ⭐ `rate_bps` is integer **basis points** — 20% VAT is `2000`. Nothing on this path is a float.","required":["id","name","rate_bps"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"name":{"type":"string","description":"What the document calls it. ⛔ Free text, not an enum: the line must read \"VAT\", \"MwSt.\", \"TVA\" or \"Sales tax\" depending on who is being invoiced."},"rate_bps":{"type":"integer","minimum":0,"maximum":100000},"registration_number":{"type":"string"},"note":{"type":"string"},"is_default":{"type":"boolean"}}},"AgencyTaxRateList":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AgencyTaxRate"}}}},"AgencyTaxRateWrite":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"rate_bps":{"type":"integer","minimum":0,"maximum":100000},"registration_number":{"type":"string"},"note":{"type":"string"},"is_default":{"type":"boolean"}}},"Agent":{"type":"object","required":["id","org_id","name","app","status","status_detail","suspend_reason","plan_code","paid_by","resources","url","model","monthly_cap_micros","spent_period_micros","created_at","provisioned_at"],"properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"app":{"$ref":"#/components/schemas/AgentAppCode"},"status":{"$ref":"#/components/schemas/AgentRunState"},"status_detail":{"type":"string"},"suspend_reason":{"type":"string","enum":["","standing","customer","ended","staff"]},"plan_code":{"type":"string"},"paid_by":{"type":"string","enum":["subscription","trial"]},"resources":{"$ref":"#/components/schemas/AgentResources"},"url":{"type":"string","format":"uri"},"model":{"type":"string"},"monthly_cap_micros":{"type":"integer","nullable":true},"spent_period_micros":{"type":"integer"},"memory_addon_mb":{"type":"integer","description":"The \"+1 GB memory\" add-on memory the running pod was started with (MiB), on top of `resources.memory_mb` (the plan's). See `getAgentMemory`."},"created_at":{"type":"string","format":"date-time","nullable":true},"provisioned_at":{"type":"string","format":"date-time","nullable":true}}},"AgentApp":{"type":"object","required":["code","name","version","licence","upstream","min_memory_mb","has_login_secret"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"version":{"type":"string"},"licence":{"type":"string"},"upstream":{"type":"string","format":"uri"},"min_memory_mb":{"type":"integer"},"has_login_secret":{"type":"boolean","description":"Whether `revealAgentLogin` has a token or password to show for this app."},"kind":{"type":"string","enum":["agent","environment"],"description":"`agent` runs on a Zinn® Agents plan; `environment` is a one-click AI environment (JupyterLab with Python and PyTorch on CPU) that runs only on a Zinn® AI Hosting plan granting `ai_environments`. A slot runs only apps whose `kind` equals its `app_kind`."}}},"AgentAppCode":{"type":"string","description":"The app an agent runs. One named component so a generator never derives the name `AgentApp` from `Agent.app`, which collides with the `AgentApp` catalogue object below.","enum":["openclaw","hermes","paperclip","activepieces"]},"AgentCreate":{"type":"object","required":["app"],"properties":{"app":{"type":"string","maxLength":32},"name":{"type":"string","maxLength":80},"slot_id":{"type":"string","format":"uuid"}}},"AgentGatewayError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type","code"],"properties":{"message":{"type":"string"},"type":{"type":"string"},"code":{"type":"string"},"zinn_failure":{"type":"object","additionalProperties":true}}}}},"AgentList":{"type":"object","required":["agents","free_slots","apps","plans","trial_available","open"],"properties":{"agents":{"type":"array","items":{"$ref":"#/components/schemas/Agent"}},"free_slots":{"type":"array","items":{"$ref":"#/components/schemas/AgentSlot"}},"apps":{"type":"array","items":{"$ref":"#/components/schemas/AgentApp"}},"plans":{"type":"array","items":{"$ref":"#/components/schemas/AgentPlanOffer"}},"trial_available":{"type":"boolean"},"open":{"type":"boolean"}}},"AgentLogin":{"type":"object","required":["method","url","username","secret","open_url"],"properties":{"method":{"type":"string","enum":["token","password","app_account","open"]},"url":{"type":"string","format":"uri","description":"The agent's public address."},"username":{"type":"string","nullable":true,"description":"Set for `password` only."},"secret":{"type":"string","nullable":true,"description":"The token (`token`) or password (`password`); null for `app_account` and `open`."},"open_url":{"type":"string","format":"uri","description":"Opens the app signed in where the app reads its token from a URL fragment (`token`: `url` + `/#token=…`); otherwise `url`. To open an agent signed in, use `openAgent`."}}},"AgentMemory":{"type":"object","required":["plan_mb","addon_gb","effective_mb","applied_addon_mb","limit_mb","max_more_gb","offered","unit_price","addons"],"properties":{"plan_mb":{"type":"integer"},"addon_gb":{"type":"integer","description":"Add-on GB that count today."},"effective_mb":{"type":"integer","description":"Plan + add-on — the pod's guaranteed request."},"applied_addon_mb":{"type":"integer","description":"Add-on MiB the running pod was started with."},"limit_mb":{"type":"integer","description":"The burst limit (twice `effective_mb`)."},"max_more_gb":{"type":"integer"},"offered":{"type":"boolean"},"unit_price":{"type":"object","nullable":true,"required":["amount_minor","currency"],"properties":{"amount_minor":{"type":"integer","description":"One GB per month","minor units.":null},"currency":{"type":"string"}}},"addons":{"type":"array","items":{"$ref":"#/components/schemas/AgentMemoryAddon"}}}},"AgentMemoryAddon":{"type":"object","required":["purchase_id","gb","counts","status","amount_minor","currency","comp","renewal","next_charge_on","created_at"],"properties":{"purchase_id":{"type":"string","format":"uuid"},"gb":{"type":"integer"},"counts":{"type":"boolean","description":"Whether these GB count today."},"status":{"type":"string"},"amount_minor":{"type":"integer","description":"The monthly price of this add-on (unit × gb)."},"currency":{"type":"string"},"comp":{"type":"boolean","description":"Given free by Zinn® staff."},"renewal":{"type":"string","enum":["active","ended","none"]},"next_charge_on":{"type":"string","format":"date","nullable":true},"created_at":{"type":"string","format":"date-time","nullable":true}}},"AgentMemoryPurchase":{"type":"object","required":["purchase_id","gb","status","memory"],"properties":{"purchase_id":{"type":"string","format":"uuid"},"gb":{"type":"integer"},"status":{"type":"string"},"memory":{"$ref":"#/components/schemas/AgentMemory"}}},"AgentOpenLink":{"type":"object","required":["url","expires_in"],"properties":{"url":{"type":"string","format":"uri","description":"The single-use sign-in link (`https://<agent>/_zinn/open?t=…`). Open it in a new tab without a referrer."},"expires_in":{"type":"integer","description":"Seconds the link stays valid."}}},"AgentPlanOffer":{"type":"object","required":["plan_code","plan_name","plan_version_id","currency","monthly_minor","first_month_minor","resources","ai_credit_monthly_micros"],"properties":{"plan_code":{"type":"string"},"plan_name":{"type":"string"},"plan_version_id":{"type":"string","format":"uuid"},"currency":{"type":"string"},"monthly_minor":{"type":"integer","description":"Monthly price in minor units (renewal)."},"first_month_minor":{"type":"integer","nullable":true,"description":"The first month's price when the intro applies to this organisation, else null."},"resources":{"$ref":"#/components/schemas/AgentResources"},"ai_credit_monthly_micros":{"type":"integer"}}},"AgentProposal":{"type":"object","required":["id","action","action_title","state","mode","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"action":{"type":"string"},"conversation_id":{"allOf":[{"$ref":"#/components/schemas/Uuid"}],"nullable":true,"description":"The AI conversation this came out of, or `null` for one raised by a scheduled review. ⭐ Lets a chat surface show its own suggestions without a second endpoint, and lets `/ai` say where one came from."},"action_title":{"type":"string"},"target_label":{"type":"string"},"rationale":{"type":"string","description":"Why, citing the measurement. This is what a person reads before approving."},"state":{"$ref":"#/components/schemas/AgentProposalState"},"mode":{"$ref":"#/components/schemas/AgentProposalMode"},"reversibility":{"type":"string","enum":["automatic","self_healing","manual"],"description":"Whether this change can be put back, carried on the proposal itself so a client rendering an undo control does not have to join this list against the capability catalogue — a second source of truth about the same fact, and the one that goes stale. `self_healing` means there is nothing to put back and `POST .../revert` answers `422` saying so."},"approval_means":{"type":"string"},"outcome":{"type":"string"},"proposed_by":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"decided_at":{"type":["string","null"],"format":"date-time"},"applied_at":{"type":["string","null"],"format":"date-time"},"reverted":{"type":"boolean"}}},"AgentProposalDecision":{"type":"object","required":["decision"],"properties":{"decision":{"type":"string","enum":["approve","reject"]},"reason":{"type":"string","maxLength":500}}},"AgentProposalMode":{"type":"string","description":"How an approved proposal executes — decided by the authority ladder at the moment of approval, never frozen when the proposal was written. `attended` is a person clicking; `canary` and `fleet` are the agent acting under earned authority.","enum":["attended","canary","fleet"]},"AgentProposalPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgentProposal"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"AgentProposalState":{"type":"string","enum":["proposed","approved","applying","applied","reverted","rejected","failed"]},"AgentResources":{"type":"object","required":["cpu_millis","memory_mb","disk_gb"],"properties":{"cpu_millis":{"type":"integer"},"memory_mb":{"type":"integer"},"disk_gb":{"type":"integer"}}},"AgentRunState":{"type":"string","description":"Where a hosted agent is in its life. A named component because a generator would otherwise derive `AgentStatus` from `Agent.status`, which collides with the `AgentStatus` capability object.","enum":["provisioning","running","suspended","failed","deleting","deleted"]},"AgentSlot":{"type":"object","required":["id","kind","plan_code","plan_name","resources","ai_credit_monthly_micros","ends_at"],"properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["subscription","trial"]},"plan_code":{"type":"string"},"plan_name":{"type":"string"},"resources":{"$ref":"#/components/schemas/AgentResources"},"ai_credit_monthly_micros":{"type":"integer"},"ends_at":{"type":"string","format":"date-time","nullable":true},"app_kind":{"type":"string","enum":["agent","environment"],"description":"Which apps this slot may run. An AI Hosting subscription is an `environment` slot, sized by its `ai_env_*` grants; its model calls spend the plan's included AI credit."}}},"AgentUpdate":{"type":"object","properties":{"name":{"type":"string","maxLength":80},"model":{"type":"string","maxLength":120},"monthly_cap_micros":{"type":"integer","nullable":true,"minimum":0}}},"AiAnchor":{"type":"object","required":["url","text"],"properties":{"url":{"type":"string","format":"uri","maxLength":500},"text":{"type":"string","maxLength":200,"description":"The exact link text. ⛔ Verified against the generated HTML after the call — a model that paraphrases an anchor has changed the one string the customer is buying this product to control."}}},"AiCredential":{"type":"object","description":"A pointer to a customer's own provider key. ⛔ There is deliberately no field here that could carry the secret.","required":["id","provider","label","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"provider":{"$ref":"#/components/schemas/AiProviderCode"},"label":{"type":"string","maxLength":100},"state":{"type":"string","enum":["untested","working","broken"],"description":"Whether the key is known to work. ⛔ Three values, not two: \"we have never tried it\" and \"we tried it and it failed\" must not collapse, because telling a customer their valid key is broken is worse than saying nothing."},"last_checked_at":{"type":["string","null"],"format":"date-time","description":"When we last *asked*, whatever the answer — distinct from `verified_at`, which is when it last *worked*. A key checked five minutes ago and broken has a recent `last_checked_at` and a stale `verified_at`."},"broken_since":{"type":["string","null"],"format":"date-time"},"tested_on_save":{"type":"boolean","description":"Only on the response to `addAiCredential`. Whether the on-save test actually **ran** — ⛔ not whether it passed. `false` means we could not even try, which is `untested` and not `broken`; a screen showing them the same would tell a customer with a good key that it had failed."},"last_error":{"type":"string","maxLength":300,"description":"The provider's own reason, trimmed, for the customer to act on. \"Your credit balance is too low\" needs a different response from \"this key was revoked\"."},"failure":{"oneOf":[{"$ref":"#/components/schemas/VendorFailure"},{"type":"null"}],"description":"What the customer is told about the last failure, and where they may be sent (CLAUDE.md §57). `null` when the key works or has never been tried — ⛔ which is not the same as \"fine\", and the screen must keep `state`'s three-way distinction rather than reading a null here as healthy. It sits beside `last_error` rather than replacing it: the vendor's own words are what a support engineer needs, and the class plus the link are what the customer needs."},"verified_at":{"type":["string","null"],"format":"date-time","description":"The last time a real call on this key succeeded. ⛔ `null` means **never proven**, not broken — telling a customer their valid key is invalid is worse than saying nothing."},"last_used_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"AiCredentialCheck":{"type":"object","description":"The result of testing one stored key.","required":["ok","exercised_prompt","state"],"properties":{"ok":{"type":"boolean"},"exercised_prompt":{"type":"boolean","description":"⭐ Whether a **real call with our own prompts** was made. `false` means we proved only that the key authenticates — a narrower claim a screen showing just \"working\" would erase, and the distinction the owner explicitly asked for."},"detail":{"type":"string","maxLength":300},"model":{"type":"string"},"latency_ms":{"type":"integer"},"state":{"type":"string","enum":["untested","working","broken"]}}},"AiCredentialCreate":{"type":"object","required":["provider","api_key"],"properties":{"provider":{"$ref":"#/components/schemas/AiProviderCode"},"api_key":{"type":"string","maxLength":512,"description":"The key itself. Written straight to Vault and never returned."},"label":{"type":"string","maxLength":100},"org_id":{"$ref":"#/components/schemas/Uuid"}}},"AiCredentialList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AiCredential"}}}},"AiCreditHistoryLine":{"type":"object","required":["id","kind","delta_micros","balance_after_micros","currency","note","ts"],"description":"One movement on the customer's own balance, read straight from the credit ledger and **never joined to usage**. Some movements are not model calls — a pack purchase, a staff adjustment, an AI-visibility audit billed from a data vendor — so a list built from usage rows would show a balance dropping with nothing explaining it.\n\n`reference` and `actor` are deliberately absent: the first is an internal idempotency key, the second is operator vocabulary. `note` is the readable field.","properties":{"id":{"$ref":"#/components/schemas/Uuid"},"kind":{"type":"string","enum":["purchase","spend","grant","refund"]},"delta_micros":{"type":"integer","format":"int64","description":"Signed USD micros. Positive credits the organization, negative debits it."},"balance_after_micros":{"type":"integer","format":"int64"},"currency":{"type":"string","example":"USD"},"note":{"type":"string"},"ts":{"type":"string","format":"date-time"}}},"AiCreditOverview":{"type":"object","required":["state","packs","settings","history","funding_routes","spends"],"properties":{"state":{"$ref":"#/components/schemas/AiCreditState"},"packs":{"type":"array","items":{"$ref":"#/components/schemas/AiCreditPack"}},"settings":{"$ref":"#/components/schemas/AiCreditSettings"},"history":{"type":"array","description":"The 25 most recent movements, newest first.","items":{"$ref":"#/components/schemas/AiCreditHistoryLine"}},"funding_routes":{"type":"array","description":"Who pays for the next call, per provider. Read on the SAME request as the balance, so a screen cannot render a funding claim from one moment beside a balance from another.","items":{"$ref":"#/components/schemas/AiProviderFunding"}},"spends":{"type":"array","description":"Everything this credit buys — the metered surfaces derived from the engine's own meter, the credit-only spends that write no usage row, and the fixed-price AI products.","items":{"$ref":"#/components/schemas/AiCreditSpend"}}}},"AiCreditPack":{"type":"object","required":["code","name","price_minor","currency","grant_micros","bonus_micros","bonus_bps","typical_calls"],"properties":{"code":{"type":"string","example":"ai_credits_25"},"name":{"type":"string","example":"AI credits — $25"},"price_minor":{"type":"integer","format":"int64","description":"What the customer pays, in integer minor units. Converted per request off the cached FX rates for a customer quoted in another currency, exactly as the rest of the extras catalogue is."},"currency":{"type":"string","example":"USD"},"grant_micros":{"type":"integer","format":"int64","description":"Credit granted, USD micros. **Derived from the price**, never stored beside it — a pack that states both a price and an amount of credit is two numbers that must agree, and nothing notices on the day they stop."},"bonus_micros":{"type":"integer","format":"int64","description":"The free part. `0` for the starter pack."},"bonus_bps":{"type":"integer","description":"The bonus as basis points of the price."},"typical_calls":{"type":"integer","description":"Roughly how many assistant questions this pack buys, from the measured cost of one real question. An **illustration**, and the screen says so: a long article costs many times a short question."}}},"AiCreditSettings":{"type":"object","description":"The customer's standing instruction about topping up, and what has become of it.\n\nOwner, 2026-08-24, reading `/ai` on production: *\"The auto top section doesnt allow you to select when my balance reaches x (min should be $5) recharge with x amount. Its just a toggle with no settings.\"* Two of the fields he asked for already existed here and the screen never sent them, which is why it looked like a bare toggle while the model looked finished.","required":["auto_topup_enabled","auto_topup_pack_code","auto_topup_threshold_micros","auto_topup_monthly_cap_micros","effective_threshold_micros","effective_monthly_cap_micros","min_threshold_micros","auto_topup_paused","auto_topup_last_error","auto_topup_failure_count","auto_topup_spent_this_month_micros"],"properties":{"auto_topup_enabled":{"type":"boolean","description":"**Off** until the customer turns it on. A default of `true` would charge a card nobody clicked, work perfectly, and raise no error."},"auto_topup_pack_code":{"type":"string","description":"Blank means the cheapest pack, resolved at run time."},"auto_topup_threshold_micros":{"type":"integer","format":"int64","description":"Buy below this. `0` means use the same low-balance threshold the banner uses, so a customer who never touched this gets one consistent idea of \"low\"."},"auto_topup_monthly_cap_micros":{"type":"integer","format":"int64","description":"The most automatic top-up may spend in one calendar month. `0` means the computed default (four packs). The hourly cooldown bounds the *rate* — 24 attempts a day, which on the $200 pack is $4,800 — and nothing bounded the *spend* until this."},"effective_threshold_micros":{"type":"integer","format":"int64","description":"What the engine will actually use, with the `0` fallbacks resolved. Sent so the screen can show the real number rather than an empty box, and so a client never re-implements the fallback rule for money."},"effective_monthly_cap_micros":{"type":"integer","format":"int64"},"min_threshold_micros":{"type":"integer","format":"int64","description":"The lowest threshold the engine accepts — $5, an owner ruling. Sent so an input's `min` and the engine's refusal cannot disagree."},"auto_topup_paused":{"type":"boolean","description":"True when the retry ladder gave up. Owner ruling 2026-08-24: a declined charge is retried at +1h and +6h, then automatic top-up **pauses itself** and the customer is told. It restarts only when they save these settings again — an automatic resume walks back into the same declining card on a slower clock."},"auto_topup_paused_at":{"type":["string","null"],"format":"date-time"},"auto_topup_last_error":{"type":"string","description":"The reason we authored for the last failed attempt, for the customer to act on. Never a gateway credential or a raw provider string."},"auto_topup_failure_count":{"type":"integer","description":"Consecutive failures. Reset by a success or by saving these settings."},"auto_topup_spent_this_month_micros":{"type":"integer","format":"int64","description":"What automatic top-up has already bought this calendar month, so the ceiling can be seen being approached rather than discovered by the feature stopping."}}},"AiCreditSettingsWrite":{"type":"object","required":["auto_topup_enabled"],"properties":{"auto_topup_enabled":{"type":"boolean"},"auto_topup_pack_code":{"type":"string","default":""},"auto_topup_threshold_micros":{"type":"integer","format":"int64","default":0,"minimum":0,"description":"`0` keeps the shared low-balance threshold. Any other value below `min_threshold_micros` is a `422` — but **only when `auto_topup_enabled` is true**: refusing to let somebody switch the feature OFF because a value stored before that floor existed is now too low would be a trap, not a guard."},"auto_topup_monthly_cap_micros":{"type":"integer","format":"int64","default":0,"minimum":0,"description":"`0` uses the computed default. A ceiling smaller than one top-up is a `422`: it is not a strict setting, it is an off switch wearing one — every attempt would exceed it and nothing would ever be bought."}}},"AiCreditSpend":{"type":"object","description":"One thing Zinn® AI credit pays for.\n\nOwner, 2026-08-24: *\"is it clear what the ai credits can be used for? as surely its not only asking ai a question, i thought credits where for other things too?\"* It was not. `code` is a stable key and never a label — for a metered spend it is the same value as `AiUsageLine.surface`, so a line on the enumeration matches a row on the customer's own 30-day breakdown. The words are translated by the client.","required":["code","pricing","price_minor","currency","customer_initiated"],"properties":{"code":{"type":"string","example":"assistant"},"pricing":{"type":"string","enum":["metered","fixed","free"],"description":"`metered` — you pay for what the model actually used, so the same job costs a different amount each time. `fixed` — a published price, charged once. `free` — it costs the customer nothing; the platform pays the provider and no balance moves. The three must not be presented alike: \"about 220 questions\" is a useful illustration for the first and a nonsense for the other two.\n\n⛔ `free` is a value of its own rather than `metered` with `price_minor: 0`, because a client cannot tell those apart: `metered` already carries `0` and means *\"the price varies\"*. Rendered as `metered`, Ask Zinn® appeared on the customer's credits page as **\"By use\"** — i.e. *your credit pays for this* — when it is free and has never charged anybody (owner ruling 2026-08-25)."},"price_minor":{"type":"integer","format":"int64","description":"Integer minor units for a `fixed` spend, `0` for a `metered` or `free` one. ⛔ A `0` here does not mean free — read `pricing`."},"currency":{"type":"string","example":"USD"},"customer_initiated":{"type":"boolean","description":"False for platform surfaces (`staff_agent`, `triage`) which run on our own scope and never debit a customer. They are listed so anyone reconciling a usage row has one vocabulary, and flagged so a \"what your credit buys\" list can exclude them."}}},"AiCreditState":{"type":"object","required":["balance_micros","currency","is_low","is_empty","on_byo","last_pack_micros","typical_calls_remaining","included_remaining_micros","plan_credit_micros"],"properties":{"balance_micros":{"type":"integer","format":"int64"},"plan_credit_micros":{"type":"integer","format":"int64","description":"The part of `balance_micros` an AI Hosting plan included, in USD micros. It is spendable on AI Hosting only (inference, the AI site builder and editor, chat, AI environments); every other credit-priced feature spends the rest (bought top-up credit) and refuses `PLAN_CREDITS_AI_HOSTING_ONLY` when only plan credit is left (owner ruling 2026-11-03)."},"currency":{"type":"string","example":"USD"},"is_low":{"type":"boolean","description":"Whether the upsell may speak. Decided server-side so the banner, the header chip and the AI page cannot disagree about one customer."},"is_empty":{"type":"boolean","description":"**Nothing can fund the next call** — no credit AND no included allowance left.\n\n⛔ NOT \"the balance is zero\". The banner this drives says *\"AI features have stopped until you top up\"*, and until 2026-08-25 it said exactly that with the day's included allowance unspent and the engine still funding calls from it. A balance of `0` with allowance remaining is `is_empty: false` (D13617)."},"included_remaining_micros":{"type":"integer","format":"int64","description":"What is LEFT of today's included allowance, in USD micros. Sent down rather than re-derived by a client, for the same reason `is_low` is: a second implementation of \"what is left\" is a second answer, and the screen's is the one the customer believes."},"on_byo":{"type":"boolean","description":"True only when a live customer key exists for EVERY provider we route to, so credits cannot be spent at all. The banner stays silent then. Not \"this org has a key\": one key still leaves the other providers billing credits."},"last_pack_micros":{"type":"integer","format":"int64"},"typical_calls_remaining":{"type":"integer","description":"How many assistant questions the current balance is worth, from the measured cost of one real question. An illustration — a long article costs several times more."}}},"AiFunding":{"type":"string","description":"Who paid for one AI call (D4). ⛔ A **field on the one meter**, never a second subsystem: BYO, credits and the included allowance differ only in this value.","enum":["byo","credits","included"]},"AiImageCredential":{"type":"object","description":"A pointer to a customer's own image-provider key. ⛔ There is deliberately no field here that could carry the secret.","required":["id","provider","label","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"provider":{"$ref":"#/components/schemas/AiImageProvider"},"label":{"type":"string","maxLength":100},"verified_at":{"type":["string","null"],"format":"date-time","description":"The last time a **real image generation** on this key succeeded. ⛔ `null` means never proven, not broken. Moved only by a generation, never by a cheap auth probe: a probe proves the key is accepted and says nothing about whether the account can actually draw anything."},"last_checked_at":{"type":["string","null"],"format":"date-time","description":"The last time any check ran, pass or fail. Separate from `verified_at` so *\"we have not looked recently\"* is distinguishable from *\"we looked and it failed\"*."},"last_check_ok":{"type":["boolean","null"]},"last_check_error":{"type":"string","description":"The provider's own words when the last check failed. Empty otherwise."},"broken_since":{"type":["string","null"],"format":"date-time","description":"When the key first failed after last passing, or `null` if it is not currently broken. ⭐ This is what makes \"notify on transition to broken, never per check\" possible — a key broken for a week produces one message, not seven."},"last_used_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"AiImageCredentialCreate":{"type":"object","required":["provider","api_key"],"properties":{"provider":{"$ref":"#/components/schemas/AiImageProvider"},"api_key":{"type":"string","maxLength":512,"description":"The key itself. Written straight to Vault and never returned."},"label":{"type":"string","maxLength":100},"org_id":{"$ref":"#/components/schemas/Uuid"}}},"AiImageCredentialList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AiImageCredential"}}}},"AiImageModel":{"type":"object","description":"One image model in the catalogue, as the picker renders it.","required":["id","provider","model_id","status"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"provider":{"$ref":"#/components/schemas/AiImageProvider"},"model_id":{"type":"string","description":"The id sent on the wire — `gpt-image-2`, `gemini-3.1-flash-image`."},"display_name":{"type":"string","description":"What a customer sees. ⭐ Taken from the provider's own listing where it publishes one — Google returns `Nano Banana 2` — so the marketing name arrives from the vendor rather than being hardcoded here to rot."},"status":{"type":"string","enum":["active","untested","legacy","retired"]},"is_default":{"type":"boolean","description":"The row a recipe set to \"latest\" follows. One per provider."},"capabilities":{"$ref":"#/components/schemas/AiImageModelCapabilities"},"price_usd_micros":{"type":"integer","description":"Per-image price in USD micros. ⛔ Operator-maintained and never written by the nightly refresh: no provider publishes a price on its model-listing endpoint, so \"keeping it current\" from a listing would zero every row it touched."},"last_tested_at":{"type":["string","null"],"format":"date-time","description":"When a real generation last proved this model works for us."}}},"AiImageModelCapabilities":{"type":"object","description":"What one provider will actually honour. ⛔ Every field defaults to the conservative answer, so an adapter that forgets to declare something under-promises rather than over-promises — a capability table whose default is \"yes\" lies about the next provider somebody adds.","properties":{"controls_shape":{"type":"boolean","description":"Whether the aspect ratio or pixel size can be controlled at all."},"max_images":{"type":"integer","description":"Most images one request may ask for."},"controls_output_format":{"type":"boolean"},"controls_moderation":{"type":"boolean","description":"Whether the provider exposes a moderation strictness dial we can set."},"rewrites_prompt":{"type":"boolean","description":"Whether the provider rewrites the prompt before drawing. Not a fault — a fact the customer should know, because it explains an image that does not match the words they typed."},"lists_models":{"type":"boolean","description":"Whether the provider publishes a model listing the nightly refresh can read. `false` for xAI, which publishes none — which is why an absent listing never retires a row."}}},"AiImageModelList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AiImageModel"}}}},"AiImageProvider":{"type":"string","enum":["openai","google","xai"],"description":"An image-generation provider. ⛔ Deliberately a different enum from the text `provider` on `AiCredential`: Anthropic publishes no image model and xAI publishes no text model we use, so one shared enum would offer every customer at least one combination that can be saved and can never work."},"AiImageProviderAvailability":{"type":"object","required":["provider","usable","reason","model_count","on_customer_key","key_broken"],"properties":{"provider":{"$ref":"#/components/schemas/AiImageProvider"},"usable":{"type":"boolean","description":"Whether a generation request naming this provider would succeed. Read the same way the generator decides — a key (the customer's own, or the platform's) **and** at least one selectable model."},"reason":{"type":"string","enum":["","no_key","no_model","key_broken"],"description":"Why not, as a code the client localizes. `no_key` — neither this organisation nor the platform holds a usable key. `no_model` — a key exists but nothing in the catalogue has been proven to draw. `key_broken` — the organisation's own key failed its last real check and there is no platform key behind it."},"model_count":{"type":"integer","description":"How many selectable models this provider has in the catalogue."},"on_customer_key":{"type":"boolean","description":"True when this organisation's own key is what a request would run on. False means platform credits — the default route (owner ruling 2026-08-20)."},"key_broken":{"type":"boolean","description":"The organisation's own key exists and its last **real generation** check failed. Independent of `usable`: with platform credits behind it the provider still works."}}},"AiImageProviderAvailabilityList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AiImageProviderAvailability"}}}},"AiInferenceChatRequest":{"type":"object","required":["messages"],"properties":{"org_id":{"$ref":"#/components/schemas/Uuid"},"model":{"type":"string","maxLength":200,"description":"A model from `GET /v1/ai/inference/models`; empty means the default."},"messages":{"type":"array","minItems":1,"maxItems":64,"items":{"$ref":"#/components/schemas/AiInferenceMessage"}},"max_output_tokens":{"type":"integer","minimum":1,"maximum":4096,"default":2048},"reasoning":{"type":"boolean","default":false,"description":"Let a reasoning model think before it answers. Off by default, because the thinking is output tokens: opted in, it counts against `max_output_tokens` and is billed like the answer. Models that do not reason ignore it."}}},"AiInferenceMessage":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["system","user","assistant"]},"content":{"type":"string","minLength":1,"maxLength":32000}}},"AiInferenceModel":{"type":"object","required":["id","input_micros_per_mtok","output_micros_per_mtok"],"properties":{"id":{"type":"string","description":"The model id to send as `model`."},"input_micros_per_mtok":{"type":"integer","format":"int64","description":"What one million input tokens charge the customer, in USD micros."},"output_micros_per_mtok":{"type":"integer","format":"int64","description":"What one million output tokens charge the customer, in USD micros."}}},"AiInferenceModels":{"type":"object","required":["default_model","models"],"properties":{"default_model":{"type":"string","description":"The cheapest priced model."},"models":{"type":"array","items":{"$ref":"#/components/schemas/AiInferenceModel"}}}},"AiInferenceReply":{"type":"object","required":["model","message","finish_reason","usage","charged_micros","balance_micros"],"properties":{"model":{"type":"string"},"message":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["assistant"]},"content":{"type":"string"}}},"finish_reason":{"type":"string"},"usage":{"type":"object","required":["input_tokens","output_tokens"],"properties":{"input_tokens":{"type":"integer"},"output_tokens":{"type":"integer"}}},"charged_micros":{"type":"integer","format":"int64","description":"What this call charged, in USD micros."},"balance_micros":{"type":"integer","format":"int64","description":"The org's Zinn® AI credit balance after the call, in USD micros."}}},"AiModel":{"type":"object","description":"One model, as read from the provider's own catalogue and proven against our prompts. ⛔ Model ids are **data, never a hardcoded list** (§2.2) — this table is refreshed daily from each vendor.","required":["provider","model_id","modality","status","supports_tools","last_seen_at"],"properties":{"provider":{"$ref":"#/components/schemas/AiProviderCode"},"model_id":{"type":"string","description":"Exactly as the provider reports it."},"display_name":{"type":"string"},"family":{"type":"string","description":"The generation family — what a recipe set to \"latest\" follows. A recipe naming a specific `model_id` is never moved by the catalogue (owner ruling 2026-08-20)."},"modality":{"type":"string","enum":["text","image"]},"status":{"type":"string","enum":["discovered","verified","failed","withdrawn"],"description":"`verified` is the only offerable state. `discovered` means the provider lists it and we have never proved our prompts run on it — offering one is how a customer's scheduled run fails on a model nobody has called."},"supports_tools":{"type":"boolean","description":"Proven by the verification call, not asserted from a catalogue. Every recipe uses a tool call, so a model that cannot call tools cannot serve one."},"context_window":{"type":"integer","description":"0 means the provider did not tell us."},"verified_at":{"type":["string","null"],"format":"date-time","description":"When OUR verification last succeeded. ⛔ Not a release date and not an ordering key: the nightly job walks the provider's newest-first list in order, so this column ascends exactly as release date descends. Ordering by it returns the provider's OLDEST model (D12409)."},"released_at":{"type":["string","null"],"format":"date-time","description":"The PROVIDER's own release date, read from its models endpoint (Anthropic sends `created_at`; OpenAI a unix `created`). This is what \"newest\" means, and what `GET /v1/ai/models` orders by. `null` when the vendor publishes none — such a model sorts LAST, so an unknown date never outranks a known one."},"last_seen_at":{"type":"string","format":"date-time","description":"The last refresh that saw this model in the provider's list. A model that stops appearing is marked `withdrawn`; a provider we could not *reach* changes nothing."}}},"AiModelCatalogueEnvelope":{"type":"object","description":"A signed AI model catalogue. Verify `signature` over the base64-decoded `payload` bytes with the Ed25519 public key for `key_id`, then decode `payload` as JSON (schema 1: `providers.<name>.models[]` with `id`, `label`, `context`, `price.input`/`price.output` in USD per million tokens, `structured`, `vision`; `providers.<name>.recommended.<task>.{best,cheap,fast}`; and `published_at`).","required":["format","key_id","payload","signature"],"additionalProperties":false,"properties":{"format":{"type":"string","enum":["zinn-ai-catalogue/1"],"description":"The envelope format. A client refuses any other value."},"key_id":{"type":"string","description":"Which signing key produced `signature`, e.g. `zd-cat-2026-09`."},"payload":{"type":"string","format":"byte","description":"Base64 of the exact catalogue JSON bytes that were signed."},"signature":{"type":"string","format":"byte","description":"Base64 of the 64-byte Ed25519 detached signature over the payload bytes."}}},"AiModelList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AiModel"}}}},"AiModelNotice":{"type":"object","required":["id","org_id","surface","object_id","provider","from_model","to_model","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"org_id":{"$ref":"#/components/schemas/Uuid"},"surface":{"type":"string","enum":["recipe","recipe_image","board"]},"object_id":{"type":"string"},"object_name":{"type":"string"},"provider":{"type":"string"},"from_model":{"type":"string"},"to_model":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"AiModelNoticeList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AiModelNotice"}}}},"AiMove":{"type":"object","required":["id","org_id","target_domain","stage","paused","taken_over","platform","source_urls","access_kinds","created_at","progress"],"properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"site_id":{"type":["string","null"],"format":"uuid"},"target_domain":{"type":"string"},"product_line":{"type":"string"},"stage":{"type":"string","enum":["received","checking_access","needs_access","checking_fit","needs_upgrade","ready_to_copy","copying","verifying","awaiting_cutover","done","needs_staff","cancelled"]},"paused":{"type":"boolean"},"taken_over":{"type":"boolean","description":"A person from our migration team has taken it over."},"platform":{"type":"string"},"source_urls":{"type":"array","items":{"type":"string"}},"access_kinds":{"type":"array","items":{"type":"string"}},"access_report":{"type":"object","description":"Per access kind, `ok` or the refusal code of the last check.","additionalProperties":{"type":"string"}},"route":{"type":"string","description":"The route chosen (ssh, cpanel, plesk, directadmin, ftp)."},"inventory":{"type":"object","additionalProperties":true},"fit":{"type":"object","additionalProperties":true,"description":"The plan-fit verdict and any upgrade offered (engine-quoted)."},"approx_size":{"type":"string"},"move_items":{"type":"array","items":{"type":"string"}},"cutover_window":{"type":"string"},"timezone":{"type":"string"},"ticket_id":{"type":["string","null"],"format":"uuid"},"migration_job_id":{"type":["string","null"],"format":"uuid","description":"The site migration this move started (copying onwards); its rollback state is on GET /v1/sites/{site_id}/migrations."},"checks":{"type":"object","additionalProperties":true,"description":"The switch-over verdict: `preview`, `app`, `passed` (both), then `live` after the switch-over."},"go_at":{"type":["string","null"],"format":"date-time","description":"When the GO was given."},"needs":{"type":"string","enum":["","access","mailboxes","replace","replace_existing","address_in_use"],"description":"What a waiting move is asking the customer for. `replace_existing`: the domain is already on another site of this organisation (`existing_site`) — confirm with `replace_site_id` on the access form. `address_in_use` (stage `needs_staff`): another organisation holds the address, so no site can be created for it here; the customer chooses another address or contacts support. Who holds it is never said."},"existing_site":{"type":["object","null"],"description":"When `needs` is `replace_existing`: the site in this organisation that already holds the domain.","required":["id","name","primary_domain"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"primary_domain":{"type":"string"}}},"preview_url":{"type":"string","description":"The preview address, while waiting to switch over."},"extra_purchase_id":{"type":["string","null"],"format":"uuid"},"started_by_staff":{"type":"boolean"},"created_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"progress":{"$ref":"#/components/schemas/AiMoveProgress"},"health":{"$ref":"#/components/schemas/AiMoveHealth"},"restarted_as":{"type":["string","null"],"format":"uuid","description":"When the customer restarted this move: the fresh move that replaced it."},"can_restart":{"type":"boolean","description":"Whether `POST .../restart` would start a fresh move now."}}},"AiMoveAccess":{"type":"object","description":"At least one of `ssh`, `panel`, `ftp`; `database` and `wp_admin` help the checks.","properties":{"ssh":{"$ref":"#/components/schemas/AiMoveAccessEntry"},"panel":{"$ref":"#/components/schemas/AiMoveAccessEntry"},"ftp":{"$ref":"#/components/schemas/AiMoveAccessEntry"},"database":{"$ref":"#/components/schemas/AiMoveAccessEntry"},"wp_admin":{"$ref":"#/components/schemas/AiMoveAccessEntry"}}},"AiMoveAccessEntry":{"type":"object","description":"One way in. `host`/`port`/`kind`/`url` are kept on the request; `username`, `password`, `private_key`, `api_token` and `name` go to Vault only and are never returned.","properties":{"kind":{"type":"string","enum":["cpanel","plesk","directadmin"],"description":"panel only"},"host":{"type":"string","maxLength":253},"url":{"type":"string","format":"uri","description":"wp_admin only"},"port":{"type":["integer","null"],"minimum":1,"maximum":65535},"username":{"type":"string","writeOnly":true},"password":{"type":"string","writeOnly":true},"private_key":{"type":"string","writeOnly":true},"api_token":{"type":"string","writeOnly":true},"name":{"type":"string","description":"database only: the database name","writeOnly":true}}},"AiMoveEligibility":{"type":"object","required":["offered","eligible","reason","plan_name","terms_version","own_cdn_connected"],"properties":{"offered":{"type":"boolean","description":"The AI Move offer is launched to this account."},"eligible":{"type":"boolean"},"reason":{"type":"string","enum":["","not_offered","trial","no_plan","not_in_good_standing"]},"plan_name":{"type":"string"},"terms_version":{"type":"string","description":"The consent line's version the intake records."},"own_cdn_connected":{"type":"boolean","description":"The account has its own CDN connected (offered as the default edge)."}}},"AiMoveHealth":{"type":"object","description":"The honest state beside the stage (owner row 1107#24). `on_track`: inside the time the stage normally takes. `slow`: past it, still working. `self_healing`: our AI hit a problem of ours and is retrying it on its own (`attempts` so far). `with_team`: the AI could not fix it and a person from our migration team has it. `since`: when the move entered its current stage.","required":["state","since","attempts"],"properties":{"state":{"type":"string","enum":["on_track","slow","self_healing","with_team"]},"since":{"type":"string","format":"date-time"},"attempts":{"type":"integer","minimum":0}}},"AiMoveIntake":{"type":"object","required":["target_domain","platform","source_urls","access","consent"],"properties":{"target_domain":{"type":"string","maxLength":253,"description":"The domain being moved."},"site_id":{"type":["string","null"],"format":"uuid","description":"Move into this site; omit to create one."},"replace_confirmation":{"type":"string","maxLength":253,"description":"With `site_id`: the chosen site's primary domain, typed back. Required when that site has ever served anything (its content is replaced; it is backed up first and can be restored for 30 days). `422` `replace_not_confirmed` when it is missing, `replace_confirmation_mismatch` when it is not that site's domain. Ignored without `site_id`."},"product_line":{"type":"string","description":"The line a new site is created on."},"platform":{"type":"string","enum":["cpanel","plesk","directadmin","wordpress","moodle","joomla","static","other"]},"source_urls":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","maxLength":500}},"access":{"$ref":"#/components/schemas/AiMoveAccess"},"approx_size":{"type":"string","enum":["under_1gb","1_10gb","10_50gb","over_50gb","unknown"]},"move_items":{"type":"array","items":{"type":"string","enum":["files","databases","mail","dns","other_sites"]}},"cutover_window":{"type":"string","maxLength":120},"timezone":{"type":"string","maxLength":64},"contact_name":{"type":"string","maxLength":200},"contact_email":{"type":"string","format":"email","maxLength":320},"notes":{"type":"string","maxLength":4000},"consent":{"type":"boolean","description":"Must be true: our AI may sign in to the old host and copy the site (read-only)."},"edge_choice":{"type":"string","enum":["auto","ours","theirs"],"description":"The CDN the new site is created on: `auto` uses the account's own connected CDN if it has one, else ours. Footprint-Free lines ignore it (pool rules)."}}},"AiMoveProgress":{"type":"object","description":"Where the move has got (owner row 1105#11). `step` of `steps` on the customer's path (a waiting stage sits on the step it waits in); `phase` of the copy; files, databases, mailboxes and bytes done of total; the copy rate and an estimate of the time left (only while files are being copied); `stalled` once files are still to copy and nothing has moved for 5 minutes; `retrying` while our own check is being re-run.","required":["step","steps","phase","files_done","files_total","databases_done","databases_total","mailboxes_done","mailboxes_total","bytes_done","bytes_total","bytes_per_second","eta_seconds","last_activity_at","stalled","retrying"],"properties":{"step":{"type":["integer","null"],"minimum":1},"steps":{"type":"integer"},"phase":{"type":"string","enum":["","connecting","listing","copying_files","installing","testing","ready","failed","cancelled"]},"files_done":{"type":"integer"},"files_total":{"type":"integer"},"databases_done":{"type":"integer"},"databases_total":{"type":"integer"},"mailboxes_done":{"type":"integer"},"mailboxes_total":{"type":"integer"},"bytes_done":{"type":"integer","format":"int64"},"bytes_total":{"type":"integer","format":"int64"},"bytes_per_second":{"type":["integer","null"]},"eta_seconds":{"type":["integer","null"]},"last_activity_at":{"type":["string","null"],"format":"date-time"},"stalled":{"type":"boolean"},"retrying":{"type":"boolean"}}},"AiProductSubscription":{"type":"object","required":["id","site_id","product","status","cadence_days","next_due_at","last_run_at"],"properties":{"id":{"type":"string","format":"uuid"},"site_id":{"type":"string","format":"uuid"},"product":{"type":"string","description":"The AI product's `Extra.category` — `ai_webmaster` or `ai_update_guard`. The CATEGORY rather than the catalogue code, because the on-demand row and the monthly row share a category and only differ by price and interval.","example":"ai_webmaster"},"status":{"type":"string","enum":["active","stopped"]},"cadence_days":{"type":"integer","description":"Days between automatic runs, as sold to this customer. Stored per row rather than read from the product default, so changing the default never silently re-times somebody who is already paying against the number they were quoted.","example":30},"next_due_at":{"type":"string","format":"date-time","description":"When the next automatic run falls due."},"last_run_at":{"type":"string","format":"date-time","nullable":true,"description":"When the last automatic run completed. Null means it has never run — which is not the same as having run and found nothing, and a client must not render the two identically."}}},"AiProductSubscriptionList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AiProductSubscription"}}}},"AiProviderCode":{"type":"string","enum":["anthropic","google","openai","xai"],"description":"An LLM vendor a customer may bring their own key for. `xai` was added by W24-G on the owner's 2026-08-20 instruction naming Grok alongside Claude and ChatGPT."},"AiProviderFunding":{"type":"object","description":"Who pays for the next call **to one named provider**.\n\nThis exists because one word cannot answer the question, and answering it with one word put two contradictory sentences on a live customer screen: `/ai` said *\"Your own provider key — we charge you nothing\"* directly above *\"You have run out of AI credit\"*. Both were produced correctly — the first from the org's oldest key of any provider, the second from whether a key exists for *every* provider — and a scalar has to be wrong for three providers out of four.","required":["provider","funding","has_key","credential_state"],"properties":{"provider":{"type":"string","enum":["anthropic","google","openai","xai"]},"funding":{"type":"string","enum":["byo","credits","included","none"]},"has_key":{"type":"boolean"},"credential_state":{"type":"string","enum":["","untested","working","broken"],"description":"The key's own state, or empty when there is no key. A **broken key still wins the route** — funding selects on whether a key is revoked and nothing else — so this is reported beside `funding` rather than folded into it. Production on 2026-08-24 showed \"we charge you nothing\" above a key badged *Not working*."}}},"AiProviderOption":{"type":"object","description":"One vendor, and whether **this organization** can actually use it. ⚖️ This is the owner's *\"tell them which ones\"* made addressable: a screen can say \"this recipe needs an OpenAI key\" and link to the paste box, instead of offering a provider that will refuse at the first call.","required":["provider","label","covered_by_credits","key_state","verified_model_count"],"properties":{"provider":{"$ref":"#/components/schemas/AiProviderCode"},"label":{"type":"string"},"console_url":{"type":"string","description":"Where the customer mints a key at that vendor."},"covered_by_credits":{"type":"boolean","description":"Whether Zinn® AI credits can run this vendor. `false` means BYO-only — we hold no platform key for it, so a customer on credits must add their own."},"key_state":{"type":"string","enum":["none","untested","working","broken"],"description":"The state of THIS organization's key for this vendor."},"credential_id":{"type":["string","null"],"format":"uuid"},"last_checked_at":{"type":["string","null"],"format":"date-time"},"last_error":{"type":"string"},"verified_model_count":{"type":"integer","description":"How many of this vendor's models we have proven work with our own prompts. ⛔ Zero is a real answer and a client must say so, rather than showing an empty picker with no explanation."}}},"AiProviderOptionList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AiProviderOption"}}}},"AiRecipe":{"type":"object","description":"A customer's reusable posting configuration — brief, tone, length, language, anchors, cadence, targets, images and how far it goes on its own.","required":["id","name","is_enabled","publish_mode","cadence","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"name":{"type":"string","maxLength":120},"is_enabled":{"type":"boolean"},"brief":{"type":"string","maxLength":4000},"tone":{"type":"string","maxLength":200},"word_count":{"type":"integer","minimum":150,"maximum":4000},"language":{"type":"string","maxLength":12,"description":"BCP-47, or empty for \"the language the brief is written in\"."},"posts_per_run":{"type":"integer","minimum":1,"maximum":10,"description":"⛔ Capped at 10. Two hundred articles from one brief are two hundred near-identical articles, which is a **footprint** — the exact thing the Footprint-Free line is sold to avoid."},"provider":{"type":"string","description":"Blank = whatever the funding route resolves to."},"model_id":{"type":"string","description":"Blank = the newest verified model in the family."},"model_family":{"type":"string"},"anchors":{"type":"array","maxItems":5,"items":{"$ref":"#/components/schemas/AiAnchor"}},"anchor_policy":{"type":"string","enum":["none","every_post","rotate"]},"link_set_id":{"type":"string","format":"uuid","nullable":true,"description":"The reusable link set this recipe draws its links from, or `null` to use the recipe's own `anchors`. When set it **replaces** `anchors` rather than adding to them — two sources with a merge rule between them is a distribution nobody can predict, and the point of a weighted set is that the split is stated. Send `null` to clear it. Refused if the set is not on this account."},"cadence":{"type":"string","enum":["manual","daily","weekly","monthly"]},"cadence_hour_utc":{"type":"integer","minimum":0,"maximum":23},"cadence_dow":{"type":"integer","minimum":0,"maximum":6,"description":"0 = Monday."},"cadence_dom":{"type":"integer","minimum":1,"maximum":28,"description":"⛔ Never 29-31: a monthly recipe set to the 31st would skip February silently, and a schedule that stops without an error is the failure this feature prevents."},"next_run_at":{"type":["string","null"],"format":"date-time"},"last_run_at":{"type":["string","null"],"format":"date-time"},"target_kind":{"type":"string","enum":["none","sites","site_group","cms_targets"]},"target_sites":{"type":"array","items":{"type":"string"}},"target_site_group_id":{"type":["string","null"],"format":"uuid"},"target_cms_target_ids":{"type":"array","items":{"type":"string"}},"target_category":{"type":"string","maxLength":120},"requires_capabilities":{"type":"array","items":{"type":"string"},"description":"Capability ids the target must support, e.g. `cms_target:featured_image`. Enforced on every run: each site's capabilities are read from its CMS target and any shortfall is handled per `capability_policy`. A site whose capabilities are not yet known — never probed — is NOT treated as a shortfall, because \"we have not looked\" and \"it cannot do this\" are different facts."},"capability_policy":{"type":"string","enum":["refuse","degrade","ask"],"description":"What to do when a target cannot do something the recipe requires. Default `refuse` — silently dropping a requested field is the failure this exists to stop. `refuse` skips that site and records why; `degrade` publishes without the field and records what was dropped; `ask` currently behaves as `refuse`, because there is no surface to ask on yet — it will never publish something you asked to be consulted about."},"image_provider":{"type":"string"},"image_model":{"type":"string"},"featured_image":{"type":"boolean"},"inline_image_count":{"type":"integer","minimum":0,"maximum":4},"inline_placement":{"type":"string","enum":["after_intro","between_sections","end"]},"image_style":{"type":"string","maxLength":200},"publish_mode":{"type":"string","enum":["draft","schedule","publish"],"description":"⚖️ Owner ruling 2026-08-20: a **per-recipe** switch defaulting to `draft`. `draft` writes into the library and schedules nothing; `schedule` queues placements the customer can still cancel; `publish` places them for the next sweep with no human step."},"schedule_offset_hours":{"type":"integer","minimum":0,"maximum":720},"schedule_stagger_minutes":{"type":"integer","minimum":0,"maximum":10080,"description":"Minutes between consecutive posts in one run. ⛔ Not cosmetic: a network whose articles all appear in the same minute is a footprint."},"blocking_providers":{"type":"array","items":{"type":"string"},"description":"Providers this recipe needs a working key for and does not have. Empty means it can run now. ⚖️ A recipe naming no provider is never blocked — credits are the default route and BYO keys the alternative (owner, 2026-08-20)."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"AiRecipeList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AiRecipe"}}}},"AiRecipeRun":{"type":"object","description":"One execution of a recipe.","required":["id","recipe_id","trigger","state","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"recipe_id":{"$ref":"#/components/schemas/Uuid"},"trigger":{"type":"string","enum":["manual","schedule"]},"state":{"type":"string","enum":["queued","running","succeeded","partial","failed"],"description":"⛔ `partial` is a real state, not a rounding of failure: some posts were written and a later step failed. Telling the customer the run failed would make them run it again and pay twice for content they already have."},"started_at":{"type":["string","null"],"format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"},"posts_created":{"type":"integer"},"post_ids":{"type":"array","items":{"type":"string"}},"anchor_warnings":{"type":"array","items":{"type":"string"},"description":"Anchors the model did not place verbatim, aggregated across the run so the customer sees it once instead of opening ten drafts to find out."},"funding":{"type":"string","description":"Who paid. `byo` means the article was written on the customer's own key and we charged nothing."},"model":{"type":"string"},"workflow_id":{"type":"string","description":"The durable execution, when there is one."},"error_code":{"type":"string","description":"A stable machine code for what went wrong, empty on a clean run. ⛔ Set on a `partial` run as well as a `failed` one — `no_target_sites` (the recipe schedules but names no site) and `placement_refused` (its sites cannot receive a post). A `partial` run carrying no code told the customer an outcome and no remedy, which is what D12060 measured on production."},"error":{"type":"string","description":"The engine's own English sentence, for a code a client does not recognise. ⛔ A client SHOULD render its own translated copy from `error_code` and fall back to this only for an unknown code: rendering this verbatim puts English prose beside a translated status in all 58 languages (D12061)."},"created_at":{"type":"string","format":"date-time"}}},"AiRecipeRunList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AiRecipeRun"}}}},"AiRecipeWrite":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":120},"is_enabled":{"type":"boolean"},"brief":{"type":"string","maxLength":4000},"tone":{"type":"string","maxLength":200},"word_count":{"type":"integer","minimum":150,"maximum":4000},"language":{"type":"string","maxLength":12},"posts_per_run":{"type":"integer","minimum":1,"maximum":10},"provider":{"type":"string"},"model_id":{"type":"string","maxLength":100},"model_family":{"type":"string","maxLength":60},"anchors":{"type":"array","maxItems":5,"items":{"$ref":"#/components/schemas/AiAnchor"}},"anchor_policy":{"type":"string","enum":["none","every_post","rotate"]},"link_set_id":{"type":"string","format":"uuid","nullable":true,"description":"The reusable link set this recipe draws its links from, or `null` to use the recipe's own `anchors`. When set it **replaces** `anchors` rather than adding to them — two sources with a merge rule between them is a distribution nobody can predict, and the point of a weighted set is that the split is stated. Send `null` to clear it. Refused if the set is not on this account."},"cadence":{"type":"string","enum":["manual","daily","weekly","monthly"]},"cadence_hour_utc":{"type":"integer","minimum":0,"maximum":23},"cadence_dow":{"type":"integer","minimum":0,"maximum":6},"cadence_dom":{"type":"integer","minimum":1,"maximum":28},"target_kind":{"type":"string","enum":["none","sites","site_group","cms_targets"]},"target_sites":{"type":"array","maxItems":500,"items":{"type":"string","maxLength":64}},"target_site_group_id":{"type":["string","null"],"format":"uuid"},"target_cms_target_ids":{"type":"array","maxItems":500,"items":{"type":"string","maxLength":64}},"target_category":{"type":"string","maxLength":120},"requires_capabilities":{"type":"array","maxItems":32,"items":{"type":"string","maxLength":64}},"capability_policy":{"type":"string","enum":["refuse","degrade","ask"]},"image_provider":{"type":"string"},"image_model":{"type":"string","maxLength":100},"featured_image":{"type":"boolean"},"inline_image_count":{"type":"integer","minimum":0,"maximum":4},"inline_placement":{"type":"string","enum":["after_intro","between_sections","end"]},"image_style":{"type":"string","maxLength":200},"publish_mode":{"type":"string","enum":["draft","schedule","publish"]},"schedule_offset_hours":{"type":"integer","minimum":0,"maximum":720},"schedule_stagger_minutes":{"type":"integer","minimum":0,"maximum":10080},"org_id":{"$ref":"#/components/schemas/Uuid"}}},"AiReport":{"type":"object","description":"One report written by an AI product the customer bought.","required":["id","kind","status","report","failure_reason","created_at","proposals"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"site_id":{"type":["string","null"],"format":"uuid"},"kind":{"$ref":"#/components/schemas/AiReportKind"},"status":{"$ref":"#/components/schemas/ExtraPurchaseStatus"},"report":{"type":"string","description":"The written review. ⛔ Empty while fulfilment is still running — which a client must render as \"in progress\", never as \"no problems found\"."},"failure_reason":{"type":"string","description":"Why the review was refused, when it was. Surfaced rather than swallowed: a refused review is refunded, and a customer whose charge came back with no explanation opens a ticket asking why."},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"proposals":{"type":"array","items":{"$ref":"#/components/schemas/AgentProposal"}}}},"AiReportKind":{"type":"string","description":"Which AI product wrote this report. ⛔ Both products write to the same store and arrive in the same list, so without this a $19 update pre-flight and a $39 site review render as indistinguishable paragraphs and the customer cannot tell which thing they paid for.","enum":["ai_webmaster","ai_update_guard"]},"AiReportList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AiReport"}}}},"AiSiteAgentAllowance":{"type":"object","required":["tier","monthly","granted","total","used","remaining","exhausted","in_good_standing","period_start"],"properties":{"tier":{"type":"string","description":"The tier this organization falls into."},"monthly":{"type":"integer","description":"Checks from the tier","per month.":null},"granted":{"type":"integer","description":"Extra checks granted by staff that have not expired."},"total":{"type":"integer","description":"`monthly` + `granted`."},"used":{"type":"integer","description":"Billable checks used this period. Ticket and staff checks are never counted."},"remaining":{"type":"integer"},"exhausted":{"type":"boolean","description":"The monthly allowance is spent. ⛔ This does NOT mean checks are refused — see `credit_checks`. Rendering \"0 left\" on this field alone tells a customer whose credit covers hundreds more that they must stop."},"credit_checks":{"type":"integer","description":"How many further checks the organization's Zinn® AI credit would cover once the allowance is gone. The allowance is the *included* tier of the one meter; beyond it a check is funded from credit and debited per run."},"exhausted_entirely":{"type":"boolean","description":"Out of allowance AND out of credit — the only state in which a self-serve check is actually refused."},"in_good_standing":{"type":"boolean","description":"False while the account is suspended or unpaid. Pauses metered checks only — the ticket path stays free and previously-purchased results stay readable."},"period_start":{"type":"string","format":"date-time"}}},"AiSiteAgentCheck":{"type":"object","required":["site_id","source","incomplete","refused","logs","findings","applied","offered"],"properties":{"site_id":{"$ref":"#/components/schemas/Uuid"},"source":{"type":"string","enum":["ticket","self_serve","staff"]},"incomplete":{"type":"boolean","description":"True when any source could not be read or the diagnosis was partial."},"refused":{"type":"boolean"},"refusal_code":{"type":"string","description":"`allowance_exhausted` or `not_in_good_standing`."},"refusal_message":{"type":"string"},"logs":{"$ref":"#/components/schemas/AiSiteAgentLogs"},"findings":{"type":"array","items":{"$ref":"#/components/schemas/AiSiteAgentFinding"}},"applied":{"type":"array","description":"Fixes the AI applied, and under which mode.","items":{"type":"object","required":["remedy_key","mode"],"properties":{"remedy_key":{"type":"string"},"mode":{"$ref":"#/components/schemas/AiSiteAgentMode"}}}},"offered":{"type":"array","description":"Fixes found but NOT applied, with why. `awaiting_your_approval` means the customer asked to be asked; anything else names a refusal.","items":{"type":"object","required":["remedy_key","finding_code","reason"],"properties":{"remedy_key":{"type":"string"},"finding_code":{"type":"string"},"reason":{"type":"string"}}}},"allowance":{"allOf":[{"$ref":"#/components/schemas/AiSiteAgentAllowance"}],"nullable":true}}},"AiSiteAgentFinding":{"type":"object","required":["code","severity","message_key"],"properties":{"code":{"type":"string"},"severity":{"type":"string"},"message_key":{"type":"string","description":"A message key, never a sentence — the console renders it in the reader's language."},"context":{"type":"object","additionalProperties":true},"remedy_key":{"type":"string"}}},"AiSiteAgentLogSource":{"type":"object","required":["source","state","lines","truncated"],"properties":{"source":{"type":"string","enum":["web_access","web_error","php_fatal","slow_query","cron","disk","memory"]},"state":{"type":"string","description":"`ok` means we read it. `unavailable` means we could not — which is NOT a clean bill of health and must never be rendered as one. `denied` means the read was refused.","enum":["ok","unavailable","denied"]},"reason":{"type":"string","description":"Why, when the state is not `ok`. For example `logging_disabled` (the server is not recording slow queries at all), `not_exposed_by_vendor`, `log_not_present`."},"lines":{"type":"integer"},"truncated":{"type":"boolean","description":"True when older lines were dropped to fit."},"masked":{"type":"object","additionalProperties":{"type":"integer"},"description":"How many runs of each kind were masked — `ip`, `email`, `secret`, `token`, `key`, `card`. Surfaced so a customer can see what was removed and why their log differs from the raw file."},"text":{"type":"string","description":"The redacted log text. Empty unless `state` is `ok`."}}},"AiSiteAgentLogs":{"type":"object","required":["channel","incomplete","sources"],"properties":{"channel":{"type":"string","description":"How the server was read — `direct` when we read the machine ourselves, `hosting_api` when we asked the hosting platform's API, empty when neither was possible."},"incomplete":{"type":"boolean"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/AiSiteAgentLogSource"}}}},"AiSiteAgentMode":{"type":"string","description":"What the customer wants the AI to do about one kind of fix. `ask` proposes it and waits for a button; `canary` applies it to one site and checks the result; `auto` applies it and reports afterwards.","enum":["ask","canary","auto"]},"AiSiteAgentPreference":{"type":"object","required":["action","requested","effective","ceiling","clamped"],"properties":{"action":{"type":"string","description":"The fix this row is about — an agent action key or a support remedy key."},"requested":{"allOf":[{"$ref":"#/components/schemas/AiSiteAgentMode"}],"description":"What the customer chose, stored as they chose it."},"effective":{"allOf":[{"$ref":"#/components/schemas/AiSiteAgentMode"}],"description":"What will actually happen — `requested` clamped to `ceiling`."},"ceiling":{"allOf":[{"$ref":"#/components/schemas/AiSiteAgentMode"}],"description":"The highest mode the PLATFORM currently permits for this fix. The customer cannot raise it; it moves when the fix earns a higher rung."},"clamped":{"type":"boolean","description":"True when the customer asked for more than the ceiling allows. The screen must say so — otherwise their choice looks as though it did not register."},"reason":{"type":"string","description":"Why the ceiling is where it is, in words a customer reads."}}},"AiSiteAgentPreferenceWrite":{"type":"object","required":["action","mode"],"properties":{"action":{"type":"string","maxLength":64},"mode":{"$ref":"#/components/schemas/AiSiteAgentMode"}}},"AiSiteAgentPreferences":{"type":"object","required":["preferences","modes"],"properties":{"preferences":{"type":"array","items":{"$ref":"#/components/schemas/AiSiteAgentPreference"}},"modes":{"type":"array","description":"The available modes in increasing order of autonomy.","items":{"type":"object","required":["value","order"],"properties":{"value":{"$ref":"#/components/schemas/AiSiteAgentMode"},"order":{"type":"integer"}}}}}},"AiSummary":{"type":"object","required":["credit_balance_micros","credit_currency","funding_route","funding_routes","included_daily_micros","included_remaining_micros","credentials","usage_30d","open_proposals","site_builder"],"properties":{"credit_balance_micros":{"type":"integer","format":"int64"},"credit_currency":{"type":"string","description":"The ledger's denomination. USD, with display converted per request off the cached FX rates — the same pattern `listExtras` uses, and for the same reason: every provider quotes us in USD and a per-currency balance would drift against it on every FX move."},"funding_route":{"type":"string","enum":["byo","credits","included","none","mixed"],"description":"Which route the NEXT call would take, for the organization as a whole. `none` means there is no way to fund one.\n\n`mixed` is the honest answer when the providers disagree, and it is the common case rather than an edge one: any org holding a single BYO key is mixed. A client rendering this word as a sentence about billing **must** read `funding_routes` instead — a field that reports \"I cannot be summarised\" is worth more than one that picks a member and presents it as the set."},"funding_routes":{"type":"array","description":"Who pays for the next call to each provider, and whether its key works.","items":{"$ref":"#/components/schemas/AiProviderFunding"}},"included_daily_micros":{"type":"integer","format":"int64"},"included_remaining_micros":{"type":"integer","format":"int64"},"credentials":{"type":"array","items":{"$ref":"#/components/schemas/AiCredential"}},"usage_30d":{"type":"array","items":{"$ref":"#/components/schemas/AiUsageLine"}},"open_proposals":{"type":"integer"},"site_builder":{"$ref":"#/components/schemas/SiteBuilderTrial"}}},"AiUsageLine":{"type":"object","description":"One (surface, funding) pair's metered usage over the window.","required":["surface","funding","calls","input_tokens","output_tokens","charged_micros"],"properties":{"surface":{"type":"string","description":"Which product consumed it — `assistant`, `webmaster`, `staff_agent`, `triage`."},"funding":{"$ref":"#/components/schemas/AiFunding"},"calls":{"type":"integer"},"input_tokens":{"type":"integer"},"output_tokens":{"type":"integer"},"charged_micros":{"type":"integer","format":"int64","description":"What we charged, in **micros** of `credit_currency` (1 minor unit = 10,000 micros; 1 USD = 1,000,000). Always `0` for `byo` and `included`, and stored as an explicit zero rather than null so \"we charged nothing\" and \"we do not know\" stay different answers. Micros rather than minor units because one call costs a fraction of one cent and rounding each to a penny over-bills by orders of magnitude."}}},"Alert":{"type":"object","description":"One open thing this customer should know about. ⛔ Carries a message **key** and parameters, never a rendered sentence — the dashboard catalogue owns the copy in 58 languages (§2.19). Six of the seven sources are DERIVED and have no row of their own, which is why `key` (not an id) is what read state is recorded against.","required":["key","severity","i18n_key","params","href","at","notice_id","dismissed","read","title","body_html"],"properties":{"key":{"type":"string","description":"Stable across requests for the same open condition. ⛔ Contains no timestamp and no count — one that did would silently un-read itself, and the customer would meet the same alert every day."},"severity":{"$ref":"#/components/schemas/AlertSeverity"},"i18n_key":{"type":"string","description":"The **whole** catalogue key — `alerts.item.domainExpiring` for a derived alert, `notice.body.upstream_maintenance` for a system notice. ⛔ Whole, not a stem: an earlier version sent the notice's bare key and the bell rendered `upstream_maintenance` at the customer, because the dashboard stores that copy under the `notice.body.` prefix the banner path adds. Empty for an operator-authored notice, which has no key — see `title`/`body_html`."},"params":{"type":"object","additionalProperties":{"type":"string"},"description":"Interpolation values. A `__list`/`__utc` suffix means the client must format the value for the reader's locale (D13240 — an English date welded into a translated sentence was live on every dashboard)."},"href":{"type":"string","description":"In-app path to deep-link to, or empty for an alert with nowhere to go."},"at":{"type":["string","null"],"format":"date-time"},"notice_id":{"type":"string","description":"Set only for a notice-backed alert — what `POST /v1/notices/{id}/dismiss` needs. Empty for a derived one, which has nothing to dismiss."},"dismissed":{"type":"boolean","description":"The customer closed this notice's banner. ⛔ Reported, never applied: dismissing a banner says *stop interrupting me*, not *delete the record*, so the row stays in the panel."},"read":{"type":"boolean","description":"The customer has seen this alert. Clears the badge; changes nothing else."},"title":{"type":"string","description":"An operator-authored notice's heading, already localised server-side. Empty for a derived alert and for a system notice, which carry `i18n_key` instead."},"body_html":{"type":"string","description":"An operator-authored notice's body — sanitised at WRITE time (`engine/notices/sanitiser.py`), so what arrives is already safe to render, the same contract the notice banner uses. Empty for everything else."}}},"AlertList":{"type":"object","required":["data","unread_action_count","degraded"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Alert"}},"unread_action_count":{"type":"integer","description":"The badge. Unread `critical` + `action` items only. ⛔ Computed server-side rather than by counting `data` in the client — a second copy of \"which severities count\" is a copy that agrees until one of them is edited."},"degraded":{"type":"array","items":{"type":"string"},"description":"⛔⛔ **Non-empty means the list above is INCOMPLETE.** Alert providers that raised, by name. A failing provider contributes nothing, and nothing is the reassuring value — without this field *\"you have no alerts\"* and *\"we could not look\"* render identically (§2.44). The panel says so rather than showing a confident empty state."}}},"AlertReadRequest":{"type":"object","required":["alert_keys"],"properties":{"alert_keys":{"type":"array","maxItems":200,"items":{"type":"string","maxLength":200},"description":"The keys the panel actually rendered. ⛔ A list, never a \"mark everything\" boolean: an alert that arrived between the render and the click must NOT be marked seen, and a server-side \"all\" would do exactly that. \"Mark all read\" is this same call with every key on screen."}}},"AlertSeverity":{"type":"string","enum":["critical","action","info"],"description":"How urgent an alert is, and what the bell's badge counts. ⚖️ Owner ruling 2026-08-26: the badge counts `critical` + `action` only, so a PHP-version announcement can never make the bell look as urgent as a failed payment. `info` items are in the list, below a divider, and are not counted."},"ApiKey":{"type":"object","description":"API key metadata. The secret and its hash are **never** returned — the full token appears only in the response to `createApiKey`, once (CLAUDE.md §2.4).","required":["id","name","prefix","scopes","sandbox","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"name":{"type":"string","example":"CI deploy key"},"prefix":{"type":"string","description":"The key's public lookup id (the middle segment of the token).","example":"EXAMPLEPREFIX00"},"scopes":{"type":"array","description":"The RBAC permission keys this key may exercise.","items":{"type":"string"},"example":["sites.view","sites.create"]},"sandbox":{"type":"boolean","description":"A sandbox (test-mode) key suppresses billing + provisioning (docs/09 §2).","example":false},"last_used_at":{"type":["string","null"],"format":"date-time","description":"When the key last authenticated a request; null if never used."},"revoked_at":{"type":["string","null"],"format":"date-time","description":"Always null on a listed/fetched key — revoked keys are not returned."},"created_at":{"type":"string","format":"date-time"}}},"ApiKeyCreate":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100,"example":"CI deploy key"},"scopes":{"type":"array","description":"RBAC permission keys to grant. Each must be a permission the caller holds in the target org (a key can never out-scope its creator); an unheld scope is a `403`, an unknown one a `422`. Defaults to an empty list — an inert key you can widen later by replacing it. Scopes apply to the key's org and every sub-account under it, EXCEPT the exact-org scopes, which reach the key's own org only: `ads.outcomes.write` (send and retract conversion outcomes — `sendAdsOutcomes`, `retractAdsOutcomes` — and nothing else; a caller holding `ads.manage` in the org may grant it).","default":[],"items":{"type":"string","maxLength":100},"example":["sites.view","sites.create"]},"sandbox":{"type":"boolean","description":"Mint a sandbox (test-mode) key. Defaults to false.","default":false},"org_id":{"description":"The organization the key belongs to. Defaults to the caller's org; the caller must hold `apikeys.manage` in the target org.","anyOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]}}},"ApiKeyCreated":{"allOf":[{"$ref":"#/components/schemas/ApiKey"},{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"The full `zdk_<mode>_<prefix>_<secret>` token. Shown **once, here only** — store it now; it cannot be retrieved again, only replaced.","example":"zdk_live_EXAMPLE000000000_EXAMPLEONLYNOTAREALKEY0000000000"}}}]},"ApiKeyPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"AppRelease":{"type":"object","required":["name","live","preview_id","preview_branch"],"properties":{"name":{"type":"string","description":"The release directory","named after its commit.":null},"live":{"type":"boolean","description":"Whether production serves this release."},"preview_id":{"type":"string","description":"The branch preview this release serves, or empty for none."},"preview_branch":{"type":"string","description":"The branch that preview was deployed from, or empty."}}},"AppReleaseAction":{"type":"object","required":["release","steps"],"properties":{"release":{"type":"string"},"steps":{"type":"array","items":{"type":"string"},"description":"What the server did, one sentence per step."}}},"AppReleaseList":{"type":"object","required":["runtime","releases"],"properties":{"runtime":{"$ref":"#/components/schemas/Runtime"},"releases":{"type":"array","items":{"$ref":"#/components/schemas/AppRelease"}}}},"ApplicationAccess":{"type":"object","description":"The sign-in details for the application installed on one site (docs/139).","required":["application","name","login_url","username","can_reveal","is_custom","can_sign_in"],"additionalProperties":false,"properties":{"application":{"type":"string","maxLength":64,"example":"nextcloud"},"name":{"type":"string","maxLength":128,"example":"Nextcloud"},"login_url":{"type":"string","maxLength":512,"description":"The full URL to sign in at.","example":"https://cloud.example.com/"},"username":{"type":"string","maxLength":128,"description":"The administrator account the installer created."},"can_reveal":{"type":"boolean","description":"Whether `revealSiteApplicationPassword` would return a password. The password itself is never part of this object (docs/72 D52510)."},"is_custom":{"type":"boolean","description":"The customer set their own password, so there is nothing of ours to show. The screen says so rather than offering a reveal that would produce a blank."},"vendor_url":{"type":"string","maxLength":512},"can_sign_in":{"type":"boolean","description":"One-click sign-in exists for this application (`signInSiteApplication`). False for an application with no proven sign-in adapter; the sign-in link and the audited password reveal remain the way in (docs/139 §\"One-click sign-in\"). True for AbanteCart, Concrete CMS, Craft, Dolibarr, Drupal, Joomla, Matomo, Mautic, MediaWiki, MODX, Moodle, Nextcloud, OpenCart, osTicket, ownCloud, phpBB, Piwigo, PrestaShop, Silverstripe, SuiteCRM, TYPO3 and Zenphoto; false for Laravel, CakePHP, custom PHP, .NET, Strapi, Payload and WHMCS."}}},"ApplicationPassword":{"type":"object","description":"The revealed administrator password of a site's one-click application. Never stored — derived on read from the platform master key and the site's rotation epoch.","required":["password"],"additionalProperties":false,"properties":{"password":{"type":"string","minLength":1,"maxLength":256}}},"ApplicationSignIn":{"type":"object","description":"A single-use link that signs the browser in to the site's application as its administrator. Open it at once: it expires at `expires_at` (about two minutes) and the site refuses it a second time.","required":["url","expires_at"],"additionalProperties":false,"properties":{"url":{"type":"string","format":"uri","maxLength":4096,"description":"`https://<domain>/zinn-login.php?t=<token>` for a PHP application; `https://<domain>/zinn-login#t=<token>` (fragment) for Strapi and Payload.","example":"https://cloud.example.com/zinn-login.php?t=eyJ2IjoxfQ.c2ln"},"expires_at":{"type":"string","format":"date-time"}}},"ArchivePlatform":{"type":"object","required":["domain","day","state","platform","confidence","was_dynamic","gains","losses","suggested_output"],"description":"What one domain's archive on one day was built on, and what a restore of it can and cannot give back. ⛔ Every string is a machine code the client renders through its own i18n layer — this is copy a customer reads while deciding, and a sentence composed in the engine reaches one of 58 locales.","properties":{"domain":{"type":"string"},"day":{"type":"string","description":"The snapshot day this verdict is about, `YYYY-MM-DD`."},"state":{"type":"string","enum":["pending","ready","stale","error"],"description":"The same four values `ArchiveSnapshotIndex.state` carries, and the same rule — `pending` (\"nobody has looked\") and `error` (\"we looked and the archive refused\") lead a customer to opposite actions."},"platform":{"type":"string","enum":["wordpress","joomla","drupal","magento","shopify","wix","squarespace","blogger","typo3","prestashop","opencart","dotnetnuke","frontpage","static_html","unknown"],"description":"⛔ `unknown` and `static_html` are different answers and must not be collapsed: the first is \"we could not tell\", the second is \"this was hand-written HTML, so there was nothing dynamic to lose\"."},"confidence":{"type":"integer","minimum":0,"maximum":2,"description":"`0` nothing seen · `1` a signature (an asset path or a script global) · `2` the page's own `<meta name=\"generator\">`. Carried so a client can say \"looks like\" on a `1` rather than asserting."},"was_dynamic":{"type":"boolean","description":"True when the site was an application rather than a set of pages — i.e. when the customer must be told something beyond \"here are your pages back\"."},"gains":{"type":"array","items":{"type":"string"},"description":"Codes for what the restore DOES recover. Stated as explicitly as the losses: a panel that lists only what is missing reads as \"this will not work\", and it is describing a feature we sell."},"losses":{"type":"array","items":{"type":"string"},"description":"Codes for what a web archive cannot contain, so cannot come back — `admin`, `database`, `plugins`, `checkout`, `forms`, and so on."},"suggested_output":{"type":"string","enum":["static","wordpress"],"description":"A recommendation the customer may override, never a forced choice. WordPress in, WordPress out — it is the one platform whose content we can genuinely re-home, because our WXR writer speaks its import format. Everything else is pages, and pages are what static is for."},"error":{"type":"string","description":"Why the last probe failed; empty when it did not."},"probed_at":{"type":"string","format":"date-time","nullable":true}}},"ArchiveSnapshotDay":{"type":"object","required":["day","captures","urls","anchor_timestamp"],"properties":{"day":{"type":"string","format":"date","description":"The calendar day, `YYYY-MM-DD`."},"captures":{"type":"integer","description":"Captures the archive holds on this day."},"urls":{"type":"integer","description":"Distinct URLs captured on this day."},"anchor_timestamp":{"type":"string","description":"The exact archive timestamp (`YYYYMMDDhhmmss`) a restore of this day anchors on, so the picker and the job agree on one instant."}}},"ArchiveSnapshotIndex":{"type":"object","required":["domain","state","days","total_captures","truncated","error"],"properties":{"domain":{"type":"string"},"state":{"type":"string","enum":["pending","ready","stale","error"],"description":"Four states, and they are not interchangeable — collapsing `error` into `pending` leaves a customer watching a spinner for something that will never arrive."},"days":{"type":"array","items":{"$ref":"#/components/schemas/ArchiveSnapshotDay"}},"total_captures":{"type":"integer"},"truncated":{"type":"boolean","description":"True when the archive stopped short of the whole index. Reported rather than swallowed: a picker showing the first 50,000 of 400,000 captures while implying completeness tells the customer their site's best years do not exist."},"error":{"type":"string","description":"Why the last refresh failed; empty when it did not."},"fetched_at":{"type":"string","format":"date-time","nullable":true}}},"AssignableRole":{"type":"object","required":["key","name","description"],"properties":{"key":{"type":"string","example":"billing"},"name":{"type":"string","example":"Billing Manager"},"description":{"type":"string"}}},"AssignableRoleList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AssignableRole"}}}},"AssistantAsk":{"type":"object","required":["question"],"properties":{"question":{"type":"string","maxLength":4000,"description":"The customer's question, in their own language. Longer than this is a paste, not a question, and an unbounded prompt is an unbounded bill — so it is a `422`."},"site_id":{"allOf":[{"$ref":"#/components/schemas/Uuid"}],"nullable":true,"description":"Which of your sites this is about. ⛔ Validated against your own sites before anything is read — an id from a client is a request, not a fact."},"page_context":{"type":"string","maxLength":120,"pattern":"^/[A-Za-z0-9/_.:@%-]*$","description":"The screen you asked from, as a route path — e.g. `/sites/{siteId}/backups`. \"Why is this failing?\" asked on the backups screen and on the DNS screen are different questions, and this is what tells the assistant which one you meant.\n\n⛔ **A hint, and it is given to the model as a hint.** It can never widen what the answer is allowed to read — only `site_id` decides that, and only `site_id` is validated against your own sites. The worst a forged value can do is make an answer about the wrong screen for whoever forged it."}}},"AssistantConversation":{"type":"object","required":["id","title","escalated_ticket_id","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"title":{"type":"string","description":"The first question, truncated, so a list of threads is readable."},"escalated_ticket_id":{"allOf":[{"$ref":"#/components/schemas/Uuid"}],"nullable":true,"description":"Set once this thread became a support ticket."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"AssistantConversationCreate":{"type":"object","properties":{"org_id":{"allOf":[{"$ref":"#/components/schemas/Uuid"}],"description":"Required only when you can act in more than one organization."}}},"AssistantConversationDetail":{"allOf":[{"$ref":"#/components/schemas/AssistantConversation"},{"type":"object","required":["messages","proposals"],"properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/AssistantMessage"}},"proposals":{"type":"array","description":"Actions the assistant suggested in this thread. **Nothing here has happened** — a proposal is a suggestion with a confirm button, and it is applied only by `POST /v1/ai/proposals/{proposalId}/decision`, which re-checks that you hold the action's own permission in that organization at the moment you press it.\n\n⭐ The same `AgentProposal` shape `GET /v1/ai/proposals` returns, deliberately: one row, one public shape, one decision endpoint.","items":{"$ref":"#/components/schemas/AgentProposal"}}}}]},"AssistantConversationPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AssistantConversation"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"AssistantEscalation":{"type":"object","required":["ticket_id"],"properties":{"ticket_id":{"$ref":"#/components/schemas/Uuid"},"merged":{"$ref":"#/components/schemas/TicketMerge"}}},"AssistantMessage":{"type":"object","required":["id","role","text","cited_slugs","needs_human","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"role":{"$ref":"#/components/schemas/AssistantRole"},"text":{"type":"string"},"cited_slugs":{"type":"array","items":{"type":"string"},"description":"Knowledge-base slugs the answer used, for `/kb/<slug>` links. ⭐ Always a subset of what the engine supplied — a slug the model invented is dropped, because a fabricated citation is the part of an answer a reader trusts most."},"needs_human":{"type":"boolean","description":"The model's own statement that it could not answer from what it was given. Recorded from its structured output, never inferred from the prose. This is what the \"open a ticket\" prompt keys on."},"created_at":{"type":"string","format":"date-time"}}},"AssistantRole":{"type":"string","enum":["customer","assistant"]},"AuditEntry":{"type":"object","description":"One immutable, append-only audit record (docs/06 §4).","required":["id","actor","action","target","metadata","ts"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"org_id":{"description":"The organization the action was taken in; null if that org was since deleted.","anyOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]},"actor":{"type":"string","description":"Who acted — `user:<id>` or `apikey:<id>`.","example":"user:0190f1a2-3b4c-7d8e-9f01-234567890abc"},"action":{"type":"string","description":"Machine-readable action code.","example":"apikey.created"},"target":{"type":"string","description":"What was acted on (e.g. a key prefix); may be empty. A customer reads it empty on an action whose target names an internal secret path (`ads.grant_retire`); staff read it whole.","example":"EXAMPLEPREFIX00"},"metadata":{"type":"object","additionalProperties":true,"description":"Action-specific context. Never contains secrets. An organisation's own reader receives only the keys published for that row's `action`: an action with no published keys answers `{}`, and staff-entered free text (a reason, a note) is never included. `action`, `target`, `actor` and `ts` are always returned. (Changed 2026-10-11: this object used to be returned unfiltered, which exposed internal staff notes; see the API changelog in docs/09.)"},"ts":{"type":"string","format":"date-time","description":"When the action was recorded."}}},"AuditLogPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AuditEntry"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"AuthCode":{"type":"object","required":["auth_code","expires_at"],"properties":{"auth_code":{"type":"string","description":"The EPP/auth code. **A credential** — it authorizes moving the domain to another registrar. Do not store, log or display it beyond the confirmation that requested it."},"expires_at":{"type":"string","format":"date-time","description":"How long to treat the displayed code as current. A presentation bound, not a promise of invalidation — most registrars do not publish a real lifetime."}}},"AuthPolicy":{"type":"object","description":"An org's per-org authentication policy (docs/35","required":["require_mfa"],"properties":{"require_mfa":{"type":"boolean","description":"When true, members must authenticate with a second factor (TOTP or a passkey) to exercise this org's access."}}},"BacklinkLink":{"type":"object","description":"One inbound link. Every rank and score is nullable on purpose: `null` is \"the provider gave no reading\" and `0` is \"it measured one, and it is zero\". A table shows hundreds of these at once, so collapsing the two makes a whole column of real links look worthless.\n\n`dofollow` is a plain boolean rather than nullable because the provider always states it. If a future provider cannot, widen it deliberately — do not let `false` stand in for silence, because `false` is the reading a customer acts on.","required":["url_from","domain_from","anchor","url_to","dofollow","is_broken","is_new","is_lost","is_image"],"properties":{"url_from":{"type":"string","description":"The page the link is on — what a customer clicks to go and look at it."},"domain_from":{"type":"string","description":"That page's domain, which is what de-duplicates a site-wide link."},"anchor":{"type":"string","description":"The visible anchor text. Empty is a real answer for an image link — see `is_image` — rather than a missing one."},"url_to":{"type":"string","description":"The page linked to, so a customer can see which of their pages earns links."},"domain_from_rank":{"type":"integer","nullable":true,"description":"The provider's authority rank for the linking DOMAIN, on its own scale."},"page_from_rank":{"type":"integer","nullable":true,"description":"The provider's authority rank for the linking PAGE. A strong domain can link from a worthless page, and showing only the domain's number hides exactly that."},"spam_score":{"type":"integer","nullable":true,"description":"The provider's 0-100 spam estimate for this single link. Higher is worse."},"dofollow":{"type":"boolean","description":"Whether the link passes authority."},"is_broken":{"type":"boolean","description":"Whether the target now fails — a link that exists and earns nothing."},"is_new":{"type":"boolean"},"is_lost":{"type":"boolean","description":"Still returned, and deliberately: \"you lost this one\" is the most actionable row on the screen."},"is_image":{"type":"boolean","description":"An image link with no text anchor, so an empty `anchor` reads correctly."},"first_seen":{"type":"string","format":"date-time","nullable":true}}},"BacklinkLinkPage":{"type":"object","description":"One page of links and the count they were drawn from. `total` is never `len(links)`: a page of 100 out of 40,000 and a complete answer of 100 are indistinguishable from the list alone, and `null` means the provider did not say rather than zero.","required":["domain","links","showing","measured_at"],"properties":{"domain":{"type":"string"},"links":{"type":"array","items":{"$ref":"#/components/schemas/BacklinkLink"}},"total":{"type":"integer","nullable":true,"description":"How many links exist in total. `null` when the provider did not say."},"showing":{"type":"integer","description":"How many rows this page holds — always stated beside `total`."},"measured_at":{"type":"string","format":"date-time"}}},"BackupDownloadGrant":{"type":"object","required":["url","expires_at","size_bytes","etag"],"description":"A short-lived, presigned grant for one backup archive. ⛔ `url` **is a credential** for the site's entire database and files until it expires: never log it, never persist it, never put it in a URL bar you keep. The engine deliberately keeps it out of the audit trail for the same reason.","properties":{"url":{"type":"string","format":"uri","description":"The presigned object-storage URL to fetch the archive from. Hand it straight to the customer's browser and let it expire; take a fresh grant rather than caching this one."},"expires_at":{"type":"string","format":"date-time","description":"When the signature stops working. A download that has already started is unaffected; a new one after this moment is refused by storage."},"size_bytes":{"type":"integer","format":"int64","description":"The archive's size, as object storage reported it when the backup was stored — so a client can warn before a multi-gigabyte download."},"etag":{"type":"string","description":"The stored object's entity tag, for a client that wants to verify the bytes it received are the bytes we hold. Empty when the backend did not report one."}}},"BackupDownloadPreparing":{"type":"object","required":["status","retry_after_seconds"],"description":"The complete archive of an incremental backup is being assembled; ask again.","properties":{"status":{"type":"string","enum":["preparing"]},"retry_after_seconds":{"type":"integer","minimum":1,"description":"Seconds to wait before asking for the grant again."}}},"BackupStatus":{"type":"string","description":"`on_host` is a real, reportable state and not a transient: a hosting adapter that keeps backups inside its own control panel, or a platform with no object storage configured, ends there. Saying so is the point — a backup on the same host as the site is one host loss from gone.","enum":["pending","running","on_host","stored","failed","expired"]},"BackupTrigger":{"type":"string","description":"Who asked for the backup. `pre_deploy`, `pre_restore` and `pre_migration` are taken automatically immediately before that operation overwrites the site, and do not count against the on-demand allowance. `clone` is the copy `POST /v1/sites/{siteId}/clone` takes to build the new site from, and does not count against it either. `pre_change` is taken immediately before a WordPress tool that cannot be undone (search and replace, reinstall, push to live); it is stored off the server and restorable like any other backup. `hourly` is taken every hour for a site with the paid hourly-backups add-on and kept for 48 hours; it does not count against the allowance.","enum":["manual","scheduled","pre_deploy","pre_restore","pre_migration","clone","pre_change","hourly"]},"BillingAddress":{"type":"object","description":"A billing address. Everything is optional **except** `country`, which tax determination needs (docs/34 §2.2). `country` is an ISO 3166-1 alpha-2 code, uppercased by the server.","required":["country"],"properties":{"line1":{"type":"string","maxLength":200,"example":"1 Example Street"},"line2":{"type":"string","maxLength":200,"example":""},"city":{"type":"string","maxLength":120,"example":"London"},"region":{"type":"string","maxLength":120,"example":""},"postcode":{"type":"string","maxLength":32,"example":"EC1A 1BB"},"country":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"ISO 3166-1 alpha-2 (e.g. GB). Uppercased by the server.","example":"GB"}}},"BillingCurrencyChange":{"type":"object","required":["currency"],"properties":{"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO-4217, the currency to invoice this organization in from now on. Must be one we can actually charge — enabled in the registry, not policy-blocked, and presentable by at least one gateway. Anything else is refused with a 422 telling the customer to pick from the list.","example":"EUR"},"dry_run":{"type":"boolean","default":false,"description":"Compute the change and report it **without applying it**. ⭐ The preview runs the real conversion in a transaction it rolls back, so the figures a customer confirms are the figures they get."}}},"BillingCurrencyChangeResult":{"type":"object","required":["dry_run","from_currency","to_currency","rate","converted","subscriptions_repriced","subscriptions_unpriced","invoices_left_in_old_currency"],"description":"Everything the change did. ⛔⛔ Every field is here because the alternative is a silent partial: a result reporting only what succeeded is indistinguishable from one that could not see the rest. `subscriptions_unpriced` and `invoices_left_in_old_currency` must reach the screen — they are the parts a customer would otherwise meet on a bill.","properties":{"dry_run":{"type":"boolean","description":"True when nothing was applied."},"from_currency":{"type":"string","minLength":3,"maxLength":3},"to_currency":{"type":"string","minLength":3,"maxLength":3},"rate":{"type":"string","description":"Units of `to_currency` per unit of `from_currency`, to ten decimal places. ⛔ A **string**: JSON has no decimal type, and a float here would be the one place in this path that breaks §2.8 — on the number every other figure was derived from.","example":"0.9240000000"},"converted":{"type":"array","items":{"$ref":"#/components/schemas/ConvertedPurse"},"description":"The purses that moved. A purse whose balance rounds to zero in the target currency is **left alone** and is absent here — debiting it would destroy the customer's credit."},"subscriptions_repriced":{"type":"integer","description":"Live subscriptions now priced from the catalogue in the new currency."},"subscriptions_unpriced":{"type":"integer","description":"Live subscriptions whose plan has **no** price in the target currency. Left untouched in their original currency — never converted, never zeroed."},"invoices_left_in_old_currency":{"type":"integer","description":"Issued invoices keeping the old currency, by design. Includes any still due."}}},"BillingInterval":{"type":"string","description":"The recurrence a price is quoted for.","enum":["monthly","annual"]},"BillingProfile":{"type":"object","description":"The organization's one \"Bill to\" block — what renders on its next invoice (docs/34 §2.5). Org-scoped. `vat_status` is read-only (the validate-not-trust flow, §2.3, owns it).","required":["org_id","legal_name","company_name","billing_address","vat_number","vat_status","custom_invoice_fields","billing_email","invoice_locale"],"properties":{"org_id":{"type":"string","format":"uuid"},"legal_name":{"type":"string","maxLength":200,"example":"Acme Ltd"},"company_name":{"type":"string","maxLength":200,"example":"Acme"},"billing_address":{"$ref":"#/components/schemas/BillingAddress"},"vat_number":{"type":"string","maxLength":32,"example":"GB123456789"},"vat_status":{"type":"string","enum":["unvalidated","pending","valid","invalid"],"description":"State of the validate-not-trust check on `vat_number` (docs/34 §2.3). Read-only; a change to `vat_number` resets it to `unvalidated`.","example":"unvalidated"},"tax_id":{"allOf":[{"$ref":"#/components/schemas/LabelValue"}],"nullable":true,"description":"A free-label secondary tax id (US EIN, AU ABN, …). Null when unset."},"custom_invoice_fields":{"type":"array","maxItems":5,"description":"Up to five customer-defined `{label, value}` lines, rendered verbatim.","items":{"$ref":"#/components/schemas/LabelValue"}},"billing_email":{"type":"string","maxLength":254,"description":"Where invoices are delivered; blank means the account email.","example":""},"invoice_locale":{"type":"string","maxLength":16,"description":"Preferred invoice language; blank means the account language.","example":""},"updated_at":{"type":"string","format":"date-time","nullable":true,"description":"When the profile was last saved. Null if it has never been saved."}}},"BillingProfileUpdate":{"type":"object","description":"Full replace of the editable billing-profile fields (PUT). Omitted fields reset to blank. `billing_address` is required (with its required `country`); `vat_status` and `updated_at` are not accepted (engine-owned / server-set).","required":["billing_address"],"properties":{"legal_name":{"type":"string","maxLength":200},"company_name":{"type":"string","maxLength":200},"billing_address":{"$ref":"#/components/schemas/BillingAddress"},"vat_number":{"type":"string","maxLength":32},"tax_id":{"allOf":[{"$ref":"#/components/schemas/LabelValue"}],"nullable":true},"custom_invoice_fields":{"type":"array","maxItems":5,"items":{"$ref":"#/components/schemas/LabelValue"}},"billing_email":{"type":"string","format":"email","maxLength":254},"invoice_locale":{"type":"string","maxLength":16}}},"BillingRailChange":{"type":"object","description":"The result of moving a subscription between recurring rails (ADR 0029).","required":["rail","active"],"properties":{"rail":{"type":"string","enum":["engine","paypal"]},"approval_url":{"type":["string","null"],"description":"Where the buyer must approve the PayPal agreement. ⛔⛔ **Until they approve there and PayPal sends us a signed `BILLING.SUBSCRIPTION.ACTIVATED`, nothing is agreed and nothing will be charged.** The browser's return from this URL is an attacker-supplied claim and is never treated as approval."},"active":{"type":"boolean","description":"Whether the named rail is charging yet. `false` immediately after switching to PayPal — a client that rendered \"you are now billed by PayPal\" here would be telling the customer something that is not true and may never become true."},"paypal_subscription_id":{"type":"string"}}},"BillingRailRequest":{"type":"object","required":["rail"],"properties":{"rail":{"type":"string","enum":["engine","paypal"]}}},"BoardAutomationAction":{"type":"object","required":["action"],"properties":{"action":{"type":"string"},"params":{"type":"object","additionalProperties":true,"description":"Validated against the catalogue; an unknown key is refused by name."}}},"BoardAutomationActionResult":{"type":"object","required":["action","ok"],"properties":{"action":{"type":"string"},"ok":{"type":"boolean"},"detail":{"type":"string"}}},"BoardAutomationActionSpec":{"type":"object","required":["key","needs_card","external","required","params"],"properties":{"key":{"type":"string"},"needs_card":{"type":"boolean"},"external":{"type":"boolean","description":"Whether the action reaches outside the engine."},"required":{"type":"array","items":{"type":"string"}},"params":{"type":"array","items":{"$ref":"#/components/schemas/BoardAutomationContextField"}}}},"BoardAutomationCatalogue":{"type":"object","required":["triggers","actions","operators","platform_events"],"properties":{"triggers":{"type":"array","items":{"$ref":"#/components/schemas/BoardAutomationTriggerSpec"}},"actions":{"type":"array","items":{"$ref":"#/components/schemas/BoardAutomationActionSpec"}},"operators":{"type":"array","items":{"$ref":"#/components/schemas/BoardAutomationOperatorSpec"}},"platform_events":{"type":"array","items":{"$ref":"#/components/schemas/BoardPlatformEventSpec"}}}},"BoardAutomationCondition":{"type":"object","required":["field","op"],"properties":{"field":{"type":"string","description":"A context field the trigger publishes. Anything else is refused at save time."},"op":{"type":"string","enum":["eq","ne","in","not_in","contains","not_contains","matches","is_set","is_not_set","lt","gt"],"description":"`matches` is a case-insensitive SUBSTRING test, deliberately not a regular expression — a customer-authored regex would run in our worker on a string we do not control, with a retry policy that re-runs the backtrack."},"value":{"type":"string"}}},"BoardAutomationConditionResult":{"type":"object","required":["field","op","value","actual","passed"],"properties":{"field":{"type":"string"},"op":{"type":"string"},"value":{"type":"string","description":"What the rule asked for."},"actual":{"type":"string","description":"What the rule actually saw."},"passed":{"type":"boolean"}}},"BoardAutomationContextField":{"type":"object","required":["key","type"],"properties":{"key":{"type":"string"},"type":{"type":"string","enum":["string","uuid","int","bool","datetime","enum"]},"choices":{"type":"array","items":{"type":"string"}}}},"BoardAutomationOperatorSpec":{"type":"object","required":["key","types"],"properties":{"key":{"type":"string"},"types":{"type":"array","items":{"type":"string"}}}},"BoardAutomationOutcome":{"type":"string","enum":["fired","conditions_failed","already_fired","failed","partial","chain_depth_exceeded","rate_limited","skipped"]},"BoardAutomationRule":{"type":"object","required":["id","board_id","name","trigger","status"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"board_id":{"$ref":"#/components/schemas/Uuid"},"name":{"type":"string"},"description":{"type":"string"},"trigger":{"type":"string"},"trigger_config":{"type":"object","additionalProperties":true},"conditions":{"type":"array","items":{"$ref":"#/components/schemas/BoardAutomationCondition"}},"actions":{"type":"array","items":{"$ref":"#/components/schemas/BoardAutomationAction"}},"status":{"$ref":"#/components/schemas/BoardAutomationStatus"},"position":{"type":"integer"},"run_count":{"type":"integer"},"fired_count":{"type":"integer"},"consecutive_failures":{"type":"integer"},"suspended_reason":{"type":"string","description":"Why we paused this rule, in authored copy from a closed table — never an exception, a status or a message from our own code. The per-failure detail lives on each run (`action_results`), which is the surface built to answer \"what did action three do\"; this field answers \"why is it off\".","example":"We paused this rule after it failed several times in a row. Open its history to see what each action did, fix the cause, then switch the rule back on."},"suspended_at":{"type":"string","format":"date-time","nullable":true},"last_fired_at":{"type":"string","format":"date-time","nullable":true},"last_run_at":{"type":"string","format":"date-time","nullable":true},"next_due_at":{"type":"string","format":"date-time","nullable":true,"description":"Only set for a wall-clock rule. Null for a rule on a live act."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"BoardAutomationRuleList":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/BoardAutomationRule"}}}},"BoardAutomationRuleWrite":{"type":"object","required":["name","trigger"],"properties":{"name":{"type":"string","maxLength":120},"description":{"type":"string","maxLength":2000},"trigger":{"type":"string"},"trigger_config":{"type":"object","additionalProperties":true,"description":"Per-trigger settings, e.g. `hours_before` for \"due date approaching\"."},"conditions":{"type":"array","maxItems":20,"items":{"$ref":"#/components/schemas/BoardAutomationCondition"},"description":"ANDed. An empty list means the rule always matches its trigger."},"actions":{"type":"array","maxItems":10,"items":{"$ref":"#/components/schemas/BoardAutomationAction"}},"status":{"type":"string","enum":["enabled","disabled"]},"position":{"type":"integer"}}},"BoardAutomationRun":{"type":"object","required":["id","rule_id","board_id","trigger","outcome","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"rule_id":{"$ref":"#/components/schemas/Uuid"},"rule_name":{"type":"string","description":"The rule's name as it was when the run happened, copied onto the run for the same reason `card_title` below is: deleting a rule must not erase the account of what it did while it existed. Empty on rows written before the field existed, where a client falls back to `rule_id`."},"board_id":{"$ref":"#/components/schemas/Uuid"},"card_id":{"$ref":"#/components/schemas/Uuid","nullable":true},"card_title":{"type":"string","description":"Kept as text rather than joined, so the history survives the card being deleted instead of reading \"(deleted) moved to Done\"."},"trigger":{"type":"string"},"source":{"$ref":"#/components/schemas/BoardAutomationTriggerSource"},"outcome":{"$ref":"#/components/schemas/BoardAutomationOutcome"},"reason":{"type":"string"},"condition_results":{"type":"array","items":{"$ref":"#/components/schemas/BoardAutomationConditionResult"}},"action_results":{"type":"array","items":{"$ref":"#/components/schemas/BoardAutomationActionResult"}},"duration_ms":{"type":"integer"},"chain_depth":{"type":"integer","description":"How deep in a rule-triggering-rule chain this run sat. 0 = a person or an outside system started it."},"created_at":{"type":"string","format":"date-time"}}},"BoardAutomationRunPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BoardAutomationRun"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"BoardAutomationStatus":{"type":"string","description":"`suspended` means WE paused it after repeated failure and it carries a reason the customer has not read. It is a third state rather than a reuse of `disabled`, because collapsing them makes our decision look like theirs.","enum":["enabled","disabled","suspended"]},"BoardAutomationTriggerSource":{"type":"string","description":"Where the act that fired a trigger came from. Every trigger publishes this as a condition field, so *\"when a card moves, except when GitHub moved it\"* is a rule rather than code on either side.","enum":["human","automation","schedule","inbound_webhook","platform_event","github"]},"BoardAutomationTriggerSpec":{"type":"object","required":["key","card_scoped","scheduled","context_fields"],"properties":{"key":{"type":"string"},"card_scoped":{"type":"boolean","description":"When false, a card action cannot be paired with this trigger — refused at save time rather than failing silently on its first real firing."},"scheduled":{"type":"boolean"},"context_fields":{"type":"array","items":{"$ref":"#/components/schemas/BoardAutomationContextField"}},"config_fields":{"type":"array","items":{"$ref":"#/components/schemas/BoardAutomationContextField"}}}},"BoardEventSubscription":{"type":"object","required":["id","board_id","event_type","column_id","enabled"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"board_id":{"$ref":"#/components/schemas/Uuid"},"event_type":{"type":"string"},"column_id":{"$ref":"#/components/schemas/Uuid"},"label_id":{"$ref":"#/components/schemas/Uuid","nullable":true},"card_visibility":{"type":"string","enum":["internal","client"]},"enabled":{"type":"boolean"},"card_count":{"type":"integer"},"last_card_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"BoardEventSubscriptionList":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/BoardEventSubscription"}}}},"BoardEventSubscriptionWrite":{"type":"object","required":["event_type","column_id"],"properties":{"event_type":{"type":"string"},"column_id":{"$ref":"#/components/schemas/Uuid"},"label_id":{"$ref":"#/components/schemas/Uuid","nullable":true},"card_visibility":{"type":"string","enum":["internal","client"]},"enabled":{"type":"boolean"}}},"BoardInboundAccepted":{"type":"object","required":["accepted"],"properties":{"accepted":{"type":"boolean"},"rules_fired":{"type":"integer"},"detail":{"type":"string"}}},"BoardInboundEndpoint":{"type":"object","required":["id","board_id","name","endpoint_key","signature_scheme","status","has_secret"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"board_id":{"$ref":"#/components/schemas/Uuid"},"name":{"type":"string"},"endpoint_key":{"type":"string","description":"The opaque path segment. Not the board id, and unchanged by a secret rotation."},"url":{"type":"string","description":"The full URL to paste into the sending system."},"signature_scheme":{"type":"string","enum":["zinn","github"]},"status":{"$ref":"#/components/schemas/BoardAutomationStatus"},"has_secret":{"type":"boolean"},"request_count":{"type":"integer"},"rejected_count":{"type":"integer"},"last_rejection":{"type":"string","description":"Why the last refused request was refused — so \"my n8n node says 404\" is answerable from this screen rather than from a support ticket."},"last_seen_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"BoardInboundEndpointList":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/BoardInboundEndpoint"}}}},"BoardInboundEndpointWithSecret":{"allOf":[{"$ref":"#/components/schemas/BoardInboundEndpoint"},{"type":"object","required":["secret"],"properties":{"secret":{"type":"string","description":"Shown ONCE, here."}}}]},"BoardInboundEndpointWrite":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":120},"signature_scheme":{"type":"string","enum":["zinn","github"],"description":"`zinn` verifies `X-Zinn-Signature` over `\"<timestamp>.<body>\"`; `github` verifies GitHub's own `X-Hub-Signature-256` over the body. One route, one rate limiter, one log, whichever the sender speaks."},"status":{"type":"string","enum":["enabled","disabled"]}}},"BoardInboundPayload":{"type":"object","description":"Any JSON object. `event`, `status`, `title`, `body` and `ref` are projected into the rule's condition surface as `payload_*`; everything else is logged and is not conditionable.","additionalProperties":true,"properties":{"event":{"type":"string"},"status":{"type":"string"},"title":{"type":"string"},"body":{"type":"string"},"ref":{"type":"string"}}},"BoardInboundRequest":{"type":"object","required":["id","endpoint_id","accepted","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"endpoint_id":{"$ref":"#/components/schemas/Uuid"},"accepted":{"type":"boolean"},"reason":{"type":"string"},"payload":{"type":"object","additionalProperties":true,"description":"The condition values this request produced."},"payload_bytes":{"type":"integer"},"truncated":{"type":"boolean"},"rules_fired":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}},"BoardInboundRequestPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BoardInboundRequest"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"BoardPlatformEventSpec":{"type":"object","required":["key","group"],"properties":{"key":{"type":"string"},"group":{"type":"string"},"suggests_client_visible":{"type":"boolean"}}},"BoardWebhook":{"type":"object","required":["id","board_id","name","url","status","has_secret"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"board_id":{"$ref":"#/components/schemas/Uuid"},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"status":{"$ref":"#/components/schemas/BoardAutomationStatus"},"has_secret":{"type":"boolean","description":"Whether a signing secret is stored. The secret itself is in Vault and is returned only by create and rotate; no endpoint can read it back."},"consecutive_failures":{"type":"integer"},"suspended_reason":{"type":"string","description":"Why we paused this webhook, in authored copy from a closed table — never an exception from our own code. It distinguishes your endpoint refusing a delivery, your endpoint being unreachable, and a fault of ours; per-attempt detail, including your endpoint's own response body, is on the delivery log.","example":"We paused this webhook after your endpoint refused several deliveries in a row. Check it is reachable over HTTPS and answers with a 2xx status, then switch it back on."},"suspended_at":{"type":"string","format":"date-time","nullable":true},"last_delivered_at":{"type":"string","format":"date-time","nullable":true},"last_failed_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"BoardWebhookDelivery":{"type":"object","required":["id","subscription_id","event","delivery_key","status","attempts","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"subscription_id":{"$ref":"#/components/schemas/Uuid"},"event":{"type":"string"},"delivery_key":{"type":"string","description":"Sent as `X-Zinn-Delivery`, so the receiver can dedupe too."},"payload":{"type":"object","additionalProperties":true,"description":"The body exactly as it was signed and sent."},"status":{"$ref":"#/components/schemas/BoardWebhookDeliveryStatus"},"attempts":{"type":"integer"},"response_status":{"type":"integer","nullable":true},"response_snippet":{"type":"string","description":"The first 500 bytes your endpoint answered with. When it answered but sent no body, the status we observed; when we could not reach it, or the fault was ours, authored copy saying so. Never text from an exception inside our own code — a bug of ours must not be shown to you as evidence about your endpoint."},"next_attempt_at":{"type":"string","format":"date-time","nullable":true},"delivered_at":{"type":"string","format":"date-time","nullable":true},"replay_of_id":{"$ref":"#/components/schemas/Uuid","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"BoardWebhookDeliveryPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BoardWebhookDelivery"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"BoardWebhookDeliveryStatus":{"type":"string","enum":["pending","delivered","failed","exhausted"]},"BoardWebhookList":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/BoardWebhook"}}}},"BoardWebhookWithSecret":{"allOf":[{"$ref":"#/components/schemas/BoardWebhook"},{"type":"object","required":["secret"],"properties":{"secret":{"type":"string","description":"Shown ONCE, here. Store it now; rotate to get a new one."}}}]},"BoardWebhookWrite":{"type":"object","required":["name","url"],"properties":{"name":{"type":"string","maxLength":120},"url":{"type":"string","format":"uri","description":"HTTPS only. Private and link-local addresses are refused when the socket opens, not when you save."},"events":{"type":"array","maxItems":40,"items":{"type":"string"},"description":"Empty means every event this board emits."},"status":{"type":"string","enum":["enabled","disabled"]}}},"BoardsBrand":{"type":"object","description":"The identity a board share link carries, plus whether the plan includes it. ⛔ Narrower than `ResellerBrand` on purpose — no panel hostname and no sending domain, because a Boards plan buys branding on a shared board and nothing else.","required":["configured","entitled","surface","name","logo_url","primary_colour"],"properties":{"configured":{"type":"boolean","description":"Whether a brand row exists yet. False renders an empty form, not a 404."},"entitled":{"type":"boolean","description":"Whether branding on shared boards is on this org's plan. ⛔ Computed on the shared-board surface, so a Boards Business org reads `true` here while holding no platform-wide white-label."},"surface":{"type":"string","description":"Which branding surface this answer is about. Always `shared_board`."},"name":{"type":"string"},"logo_url":{"type":"string","description":"Where the stored mark is served from, or empty. Read-only — the logo is an upload."},"primary_colour":{"type":"string"}}},"BoardsBrandLogo":{"type":"object","description":"The stored mark, as the byte store vetted it.","required":["logo_sha256","logo_url","width","height","byte_size"],"properties":{"logo_sha256":{"type":"string"},"logo_url":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"},"byte_size":{"type":"integer"}}},"BoardsBrandWrite":{"type":"object","description":"What a Boards customer may set. ⛔ `panel_hostname` and `sending_domain` are absent deliberately and are refused by name if sent — they are agency capabilities.","required":["name"],"properties":{"name":{"type":"string","maxLength":120,"description":"What your clients call you. Shown on every share link."},"primary_colour":{"type":"string","maxLength":32,"description":"A hex value such as `#2b8a3e`. Empty means use ours."}}},"BoostCancelResult":{"type":"object","required":["purchase_id","extra_code","ends_at"],"additionalProperties":false,"properties":{"purchase_id":{"type":"string","format":"uuid"},"extra_code":{"type":"string"},"ends_at":{"type":["string","null"],"format":"date","description":"The last day the boost works (the end of the paid month); after it the site drops back to its plan's limits at the next converge."}}},"Brand":{"type":"object","description":"A resolved brand identity. Every field is populated — the platform's own values stand in for anything a brand has not set — so a client never has to decide a fallback.","required":["name","dashboard_url","support_url","status_url","logo_url","primary_colour","is_white_label","is_client_of_reseller","locales","default_locale","locales_restricted","language_switcher","currencies","default_currency","currencies_restricted","currency_switcher","palette","font_stack","font_css_url","nav_position","density","corner_radius","colour_scheme","favicon_url","email_logo_url","menu_items"],"properties":{"name":{"type":"string","description":"The name shown in the page title, the sidebar header and the browser tab."},"dashboard_url":{"type":"string","description":"Where this brand's panel lives. The brand's own attached hostname when it has one, otherwise the platform panel — never a hostname that does not resolve yet, because a link the customer cannot reach is worse than the leak it hides."},"support_url":{"type":"string"},"status_url":{"type":"string"},"logo_url":{"type":"string","description":"Empty when the brand has set no logo; the client then renders the name."},"primary_colour":{"type":"string","description":"Empty when the brand has set no colour; the client then uses its default."},"is_white_label":{"type":"boolean","description":"`false` for Zinn®'s own identity. Lets a surface say \"this is white-labelled\" without comparing the name to a literal."},"is_client_of_reseller":{"type":"boolean","description":"`true` only when this brand belongs to an organisation **above** yours — that is, you are a reseller's client rather than the reseller.\n\n⛔ Not the same question as `is_white_label`, and support links turn on the difference: a reseller and their client both resolve the reseller's brand, so both read `is_white_label: true`. Only the client is kept away from Zinn® support (a client reaches their provider, never us); a surface keyed on `is_white_label` alone would take our own help away from the reseller too."},"locales":{"type":"array","items":{"type":"string"},"description":"The languages this panel may be shown in, in registry order. Every language we ship, unless the caller is a reseller's client and that reseller narrowed the list. Never empty.\n\nServed here rather than on its own endpoint so the language switcher and the brand can never disagree about which tenant they are rendering."},"default_locale":{"type":"string","description":"The language a new account under this brand starts in. Always a member of `locales`."},"locales_restricted":{"type":"boolean","description":"`true` when a reseller narrowed the list, so a surface can explain why a language is missing instead of looking broken."},"language_switcher":{"type":"boolean","description":"`false` when the reseller has removed the language control from their clients' panel. Render no picker — not a disabled one. `locales` stays populated regardless: hiding a control never narrows the set of languages that exist, and `default_locale` still has to be renderable."},"currencies":{"type":"array","items":{"type":"string","minLength":3,"maxLength":3},"description":"The currencies this panel may quote in, in registry order. Every currency we can charge, unless the caller is a reseller's client and that reseller narrowed the list. Never empty."},"default_currency":{"type":"string","description":"What a viewer under this brand is quoted in before they choose. Always a member of `currencies`."},"currencies_restricted":{"type":"boolean","description":"`true` when a reseller narrowed the list, so a surface can explain why a currency is missing instead of looking broken."},"currency_switcher":{"type":"boolean","description":"`false` when the reseller has removed the currency control. Every client of that reseller is then quoted in `default_currency`."},"palette":{"type":"object","additionalProperties":{"type":"string"},"description":"Design-system colour tokens the brand chose, `{token: \"#rrggbb\"}`. **Empty for the platform**, which means *\"use the design system's own\"* — expressed as absence rather than as our values, so a restyle of the design system cannot leave a panel painting yesterday's colours with every test green."},"font_stack":{"type":"string","description":"A complete CSS `font-family` value, fallbacks included. Never a bare family name: a brand whose webfont fails to load must land somewhere chosen, not on the browser's default serif."},"font_css_url":{"type":"string","description":"A stylesheet installing a self-hosted Google family, or `\"\"` for a catalogue font that needs no bytes.\n\n⛔ Served from **our** origin, never `fonts.googleapis.com`. A `<link>` to Google on a white-label panel sends every client's IP address and a `Referer` naming their provider's hostname to a third party on each page load."},"nav_position":{"type":"string"},"density":{"type":"string"},"corner_radius":{"type":"string"},"colour_scheme":{"type":"string","description":"The scheme a first visit lands on."},"favicon_url":{"type":"string","description":"The brand's icon, already falling back to its logo. Empty means *\"leave whatever the surface has\"* — never our mark, because on a reseller's hostname that is the leak."},"email_logo_url":{"type":"string","description":"The mark for transactional mail; falls back to the panel logo."},"menu_items":{"type":"array","items":{"$ref":"#/components/schemas/BrandNavLink"},"description":"Custom navigation links the provider added, **already filtered** to what this reader may see."}}},"BrandAccentContrast":{"type":"object","description":"How readable your accent colour is, and the ink we will paint on it.\n\n⚠️ **Reported, never enforced.** A legitimate corporate colour can be mid-grey, and refusing to save it would send you to support rather than to a better colour. What we do not do is let you set it without knowing.","required":["accent","ink","ratio","meets_aa"],"properties":{"accent":{"type":"string"},"ink":{"type":"string","description":"Derived from luminance, not chosen — see `palette`."},"ratio":{"type":"number","description":"WCAG 2.2 contrast ratio, 1.0 to 21.0."},"meets_aa":{"type":"boolean","description":"`ratio >= 4.5`. ⭐ True when no colour is chosen at all: the design system's own pair is accessible and that is what will render, so a warning there would be a false alarm on a screen nobody has touched."}}},"BrandDnsRecord":{"type":"object","description":"One DNS record to publish, **exactly** as the provider asked for it.\n\n⛔ Render it verbatim. Do not trim it, lower-case it, strip a trailing dot or re-root the name against the customer's zone: a human pastes these into a registrar's panel, and a value that was improved is a value that does not verify.","required":["record_type","name","value","purpose"],"properties":{"record_type":{"type":"string","description":"`CNAME`, `TXT`, `MX`…"},"name":{"type":"string"},"value":{"type":"string"},"priority":{"type":"integer","nullable":true,"description":"`MX` only. Null elsewhere rather than a fake 0."},"purpose":{"type":"string","description":"The provider's own grouping word (`DKIM`, `SPF`, `routing`, `ownership`, `certificate`) so a list of TXT records is not undifferentiated noise."}}},"BrandFontInstall":{"type":"object","required":["family","faces","css_url"],"properties":{"family":{"type":"string"},"faces":{"type":"integer","description":"How many `@font-face` files were stored. ⛔ Never zero on success — a family that returns no usable files is a refusal, because \"installed 0 faces\" and \"this family does not exist\" look identical and only one of them is safe to act on."},"css_url":{"type":"string","description":"The stylesheet, served from our origin."}}},"BrandHostnameClaim":{"type":"object","description":"A hostname you asked for and have not yet proven you control (za-24). Publish the TXT record in `records` (purpose `ownership`) in the hostname's own DNS zone.","required":["hostname","claimed_at","records"],"properties":{"hostname":{"type":"string"},"claimed_at":{"type":["string","null"],"format":"date-time"},"records":{"type":"array","items":{"$ref":"#/components/schemas/BrandDnsRecord"}}}},"BrandLogo":{"type":"object","description":"A stored brand logo. `sha256` is its identity — the digest of the exact bytes — and `logo_url` is where a browser fetches it. Both are empty after a delete.","required":["logo_url","sha256"],"properties":{"logo_url":{"type":"string"},"sha256":{"type":"string"},"purpose":{"type":"string","enum":["panel","favicon","email"],"description":"Which mark was stored — echoed back so a caller can confirm."},"content_type":{"type":"string"},"width":{"type":"integer"},"height":{"type":"integer"},"byte_size":{"type":"integer"}}},"BrandMention":{"type":"object","description":"One public web page that mentions one of the organisation's phrases.","required":["id","phrase","url","tone","first_seen_at","last_seen_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"phrase":{"type":"string","description":"The phrase it matched, lower-cased (the phrase's identity)."},"url":{"type":"string","format":"uri"},"domain":{"type":"string","description":"The site the page is on."},"title":{"type":"string"},"snippet":{"type":"string","description":"A short excerpt from the page."},"tone":{"type":"string","enum":["positive","neutral","negative"]},"language":{"type":"string"},"country":{"type":"string"},"domain_rank":{"type":["integer","null"],"description":"The source domain's authority, 0-1000. `null` when unmeasured, never `0`."},"published_at":{"type":["string","null"],"format":"date-time","description":"When the page was published. `null` when the data provider gave no date or a date in the future — a future date is not a date."},"first_seen_at":{"type":"string","format":"date-time","description":"When a check first found this page. What \"new\" means."},"last_seen_at":{"type":"string","format":"date-time"}}},"BrandMentionPage":{"type":"object","required":["mentions","total","limit","offset"],"properties":{"mentions":{"type":"array","items":{"$ref":"#/components/schemas/BrandMention"}},"total":{"type":"integer","description":"How many stored mentions match, of which `mentions` is one page. A page alone reads as complete; `total` is what lets a screen say \"showing 50 of 312\"."},"limit":{"type":"integer"},"offset":{"type":"integer"}}},"BrandMenu":{"type":"object","required":["items","entitled","max_items","icons","visibilities"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/BrandMenuItem"}},"entitled":{"type":"boolean"},"max_items":{"type":"integer","description":"How many links fit alongside the panel's own navigation. Served with the data so the app cannot hold a limit that disagrees with the engine."},"icons":{"type":"array","items":{"type":"string"}},"visibilities":{"type":"array","items":{"type":"string"}}}},"BrandMenuItem":{"type":"object","description":"One custom navigation link you add to your clients' panel.\n\n⛔ `url` is an **allow-list** of `https://`, `http://` and same-origin paths beginning `/` — never a deny-list of dangerous schemes. Your clients click these from inside an authenticated panel on your hostname, so the failure is not a broken link, it is a link that runs script in the origin holding their session.","required":["id","label","url","icon","position","new_tab","visibility","external"],"properties":{"id":{"type":"string"},"label":{"type":"string","maxLength":40},"url":{"type":"string","maxLength":500},"icon":{"type":"string","description":"A design-system icon name from `icons`, or `\"\"` for a label-only item."},"position":{"type":"integer","description":"Sort key. Ties break on the label, so the order is total and stable."},"new_tab":{"type":"boolean","description":"Renders `target=\"_blank\"`. The panel pairs it with `rel=\"noopener noreferrer\"` unconditionally — that is set on **every** external item, not only the new-tab ones, because `Referer` leaks either way and the panel's URL names a client's organisation."},"visibility":{"type":"string","enum":["both","client","staff"],"description":"Who sees it. Filtered **server-side** on `GET /v1/branding`: a payload carrying a staff-only link that the app hides has already disclosed it to anybody with a network tab, which on a white-label panel is your client."},"external":{"type":"boolean","description":"Whether the link leaves the panel. Computed here so every renderer agrees."}}},"BrandMenuItemInput":{"type":"object","required":["label","url"],"properties":{"label":{"type":"string","maxLength":40},"url":{"type":"string","maxLength":500},"icon":{"type":"string"},"position":{"type":"integer","minimum":0,"maximum":999},"new_tab":{"type":"boolean"},"visibility":{"type":"string","enum":["both","client","staff"]}}},"BrandNavLink":{"type":"object","description":"One custom navigation link as the panel renders it.\n\n⛔ There is deliberately **no `visibility` field here**, unlike `BrandMenuItem` on the authoring endpoint: this payload is filtered server-side, and carrying a staff-only link plus a flag for the app to honour would have disclosed it to anybody with a network tab.","required":["id","label","url","icon","new_tab","external"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"url":{"type":"string"},"icon":{"type":"string"},"new_tab":{"type":"boolean"},"external":{"type":"boolean","description":"Whether it leaves the panel. Computed here rather than derived from the URL by each renderer — a second implementation is a second chance to omit `rel=\"noopener noreferrer\"`."}}},"BrandPanelHostname":{"type":"object","description":"The hostname your clients sign in at, and whether it is serving yet.","required":["hostname","active","provider_status","records"],"properties":{"hostname":{"type":"string"},"active":{"type":"boolean","description":"Measured by fetching it, not read off the edge's status. See `ResellerBrand.panel_hostname_active`."},"provider_status":{"type":"string"},"records":{"type":"array","items":{"$ref":"#/components/schemas/BrandDnsRecord"}},"errors":{"type":"array","items":{"type":"string"},"description":"The edge's own complaints, verbatim, on the verify response — *\"custom hostname does not CNAME to this zone\"* is a sentence a customer can act on in thirty seconds, where \"pending\" is one they open a ticket about."},"claim":{"description":"The pending ownership claim, or `null` once proven or withdrawn.","oneOf":[{"$ref":"#/components/schemas/BrandHostnameClaim"},{"type":"null"}]}}},"BrandPanelHostnameWrite":{"type":"object","required":["hostname"],"properties":{"hostname":{"type":"string","maxLength":253,"description":"Just the hostname — `panel.acme.com`, with no scheme and no path. A hostname inside a domain Zinn® operates is refused."}}},"BrandSendingDomain":{"type":"object","description":"The domain your clients' e-mail is sent from, and where it is in verification.\n\n⛔ Until `verified` is true the platform sender is used. That is deliberate: mail from an unverified domain does not arrive, so treating \"they typed it\" as \"it works\" is how a reseller's clients silently stop being told their card was declined.","required":["domain","verified","provider","provider_status","records"],"properties":{"domain":{"type":"string"},"verified":{"type":"boolean","description":"The mail provider's answer. Never inferred from `domain` being set."},"provider":{"type":"string"},"provider_status":{"type":"string","description":"The provider's raw status word, for display. Never branch on it."},"records":{"type":"array","items":{"$ref":"#/components/schemas/BrandDnsRecord"}}}},"BrandSendingDomainWrite":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","maxLength":253,"description":"Just the domain — `acme.com` or `mail.acme.com`, with no scheme and no path."}}},"BrandSerpPage":{"type":"object","required":["terms","custom_terms","max_terms","quote","results","total","limit","offset","held","enabled"],"properties":{"enabled":{"type":"boolean","description":"Brand page 1 is switched on for this domain (it watches `brand_serp` and pays per check from Zinn® credits). Before it is, the page carries the quote and no results."},"terms":{"type":"array","items":{"type":"string"},"description":"The searches each run checks (the brand, when none are set)."},"custom_terms":{"type":"array","items":{"type":"string"}},"max_terms":{"type":"integer"},"quote":{"$ref":"#/components/schemas/BrandSerpQuote"},"results":{"type":"array","items":{"$ref":"#/components/schemas/BrandSerpResult"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"last_run":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/VisibilityAudit"}]},"held":{"type":"boolean","description":"Checks are paused for want of Zinn® credit; a top-up resumes them."}}},"BrandSerpQuote":{"type":"object","description":"What brand page 1 costs, read from the live per-check Zinn® credit price row — the same product the run debits, so the quote is the charge. USD micros (a check is under two cents, which minor units cannot express).","required":["unit","price_micros","units_per_run","per_run_micros","cadence_days","monthly_micros","currency"],"properties":{"unit":{"type":"string","enum":["brand_serp_check"]},"price_micros":{"type":"integer","description":"One check of one search."},"units_per_run":{"type":"integer","description":"Searches checked each run."},"per_run_micros":{"type":"integer"},"cadence_days":{"type":"integer"},"monthly_micros":{"type":"integer","description":"A month of runs at this cadence (365/12 days)."},"currency":{"type":"string","enum":["USD"]}}},"BrandSerpResult":{"type":"object","required":["id","term","position","url","sentiment","baseline"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"term":{"type":"string","description":"The brand search it appeared for."},"position":{"type":"integer","description":"Where it sat on page 1 when last seen (1-10)."},"url":{"type":"string"},"domain":{"type":"string"},"title":{"type":"string"},"snippet":{"type":"string"},"sentiment":{"type":"string","enum":["negative","neutral","positive","unclassified"],"description":"How it reads for the brand. `unclassified` means it has not been read yet (the reader was unavailable) — never treat it as neutral; it is read again on the next check."},"reason":{"type":"string","description":"The reader's one-line reason","in English.":null},"baseline":{"type":"boolean","description":"Already on page 1 at the search's first check — shown, never alerted on."},"first_seen_at":{"type":"string","format":"date-time","nullable":true},"last_seen_at":{"type":"string","format":"date-time","nullable":true}}},"BuildLog":{"type":"object","required":["lines","complete","total"],"properties":{"lines":{"type":"array","items":{"$ref":"#/components/schemas/BuildLogLine"}},"complete":{"type":"boolean","description":"Whether the build has finished producing lines. Read from the deployment's terminal state, never from \"no new lines this time\" — a stalled build and a finished one produce the same line count."},"total":{"type":"integer","description":"Lines the provider says exist, or `-1` where it publishes no total. Never `0` for unknown, which would read as an empty log."}}},"BuildLogLine":{"type":"object","required":["message","ts"],"properties":{"message":{"type":"string"},"ts":{"type":"string","format":"date-time","nullable":true,"description":"The provider's own timestamp, or null where it publishes none — never the time of the request. A manufactured timestamp on a build log reads as ordering evidence in a post-mortem."}}},"BuildMode":{"type":"string","enum":["publish","ci"],"description":"How the published files are produced. `publish` serves the repository's own files — right for plain HTML and for a repo whose generator output is committed. `ci` runs the build command in the repository's OWN CI, under the customer's identity and minutes, which commits the output to `publish_branch`; we publish that branch. ⛔ There is deliberately no third mode running a customer's build command on Zinn® workers: arbitrary code in a long-lived multi-tenant pod is the isolation boundary this platform is built on."},"BulkErrorCode":{"type":"string","description":"Why an item did not succeed, as a **stable machine code**.\n\n⛔⛔ A code and not a message. A hosting vendor's error text arrives in the vendor's language and the vendor's shape, and occasionally with a customer's filesystem path in it; rendering it to a customer breaks the platform's i18n rule outright. Render your own copy keyed on this value. The job's `note` field is operator detail and is not customer copy.","enum":["not_wordpress","not_serving","unsupported_platform","capability_denied","not_installed","unknown_blueprint","site_missing","driver_unresolved","vendor_refused","install_failed","not_in_good_standing","already_deleted","not_php","no_cdn","needs_addon","refused","file_missing","file_not_regular","domain_taken","domain_probe_budget","create_refused","invalid_row","unknown"],"example":"unsupported_platform"},"BulkInstalledPlugin":{"type":"object","description":"One plugin, and how far it reaches across the sites that were read.","required":["name","installed_on","active_on","updatable_on","versions"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"WordPress's own plugin name — the directory folder, which is what `plugin_activate` takes.","example":"wordpress-seo"},"installed_on":{"type":"integer","description":"How many of the read sites carry it at all."},"active_on":{"type":"integer","description":"How many have it switched on. Carried separately rather than derived: *\"active on 3 of the 9 that have it\"* is the sentence somebody about to press **Deactivate** needs, and it cannot be recovered from one number."},"updatable_on":{"type":"integer","description":"How many have an update waiting."},"versions":{"type":"array","items":{"type":"string"},"description":"Distinct versions seen, sorted. More than one is worth showing — a bulk update across a mixed estate behaves differently per site."}}},"BulkInstalledPlugins":{"type":"object","description":"One plugin listing aggregated over the sites that could be read.","required":["operation","matched","eligible","read","sampled","uniform","data","unreadable"],"additionalProperties":false,"properties":{"operation":{"type":"string","example":"plugin_activate"},"matched":{"type":"integer","description":"Sites the selection resolves to, counted over the whole selection."},"eligible":{"type":"integer","description":"Of those, how many could take the operation at all."},"read":{"type":"integer","description":"How many were actually listed. ⛔ The number that makes an empty `data` interpretable: `0` means *we looked at nothing*, never *nothing is installed*."},"sampled":{"type":"boolean","description":"True when the selection is larger than what was read."},"uniform":{"type":"boolean","description":"False when the read sites do not all carry the same plugins. Computed here rather than by the client, because it decides what the customer is told."},"data":{"type":"array","items":{"$ref":"#/components/schemas/BulkInstalledPlugin"}},"unreadable":{"type":"array","description":"Sites in the selection whose plugins could not be listed. ⛔ Reported, never dropped — a shorter list that looks complete is worse than a short list that says so.","items":{"type":"object","required":["site_id","primary_domain"],"additionalProperties":false,"properties":{"site_id":{"type":"string","format":"uuid"},"primary_domain":{"type":"string"}}}}}},"BulkInstalledPluginsRequest":{"type":"object","description":"Which sites to read. The selector fields are the same three `previewBulkJob` takes, so the survey and the job that follows it resolve the identical set.","required":["operation","selector"],"additionalProperties":false,"properties":{"operation":{"type":"string","enum":["plugin_activate","plugin_deactivate","plugin_remove","plugin_update"],"description":"⛔ Only the operations that act on something already installed. Anything else is a `422` — there is nothing to list, and the directory search is the right tool."},"selector":{"$ref":"#/components/schemas/BulkSelector"},"selector_value":{"type":"string","maxLength":100,"description":"The product line, for `selector: product_line`."},"site_ids":{"type":"array","maxItems":5000,"items":{"type":"string","format":"uuid"}},"sample":{"type":"integer","minimum":1,"maximum":100,"default":25,"description":"How many sites to read. A **latency** bound on an interactive read, not a capacity plan: the response reports what it did not reach, and the bulk job that follows covers the whole selection."}}},"BulkItemStatus":{"type":"string","description":"One site's outcome. `unsupported` means the site's platform cannot do this at all (no shell, no `wp-cli`) — a distinct state from `failed` because nothing went wrong and a retry cannot help, so it is never reopened by `retryBulkJobFailures`. `skipped` means the site stopped qualifying between the confirmation and its turn — suspended, or WordPress removed — which *can* change, so it is retried.","enum":["pending","succeeded","unsupported","skipped","failed"],"example":"succeeded"},"BulkJob":{"type":"object","required":["id","org_id","operation","params","selector","selector_value","status","requested_by","note","created_at","updated_at","settled_at","counts","progress"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"org_id":{"$ref":"#/components/schemas/Uuid"},"operation":{"$ref":"#/components/schemas/BulkOperation"},"params":{"$ref":"#/components/schemas/BulkJobParams"},"selector":{"$ref":"#/components/schemas/BulkSelector"},"selector_value":{"type":"string"},"status":{"$ref":"#/components/schemas/BulkJobStatus"},"requested_by":{"type":"string","description":"Who asked for it."},"note":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"settled_at":{"description":"When the job finished; `null` while it is still running.","type":["string","null"],"format":"date-time"},"counts":{"$ref":"#/components/schemas/BulkJobCounts"},"progress":{"$ref":"#/components/schemas/BulkJobProgress"}}},"BulkJobCounts":{"type":"object","required":["total","pending","succeeded","unsupported","skipped","failed"],"properties":{"total":{"type":"integer","example":12},"pending":{"type":"integer","example":0},"succeeded":{"type":"integer","example":9},"unsupported":{"type":"integer","example":2},"skipped":{"type":"integer","example":0},"failed":{"type":"integer","example":1}}},"BulkJobCreate":{"allOf":[{"$ref":"#/components/schemas/BulkJobRequest"},{"type":"object","properties":{"confirm":{"type":"string","description":"The typed confirmation phrase, required when `previewBulkJob` answers `confirmation_required: true`. Send exactly the value it returned in `confirmation_phrase`.\n\n⛔ Whether it is required depends on the **arguments** as well as the operation and the selector: `theme_install` needs it when `activate` is true (switching the theme changes what every visitor sees) and not otherwise (installing the files changes nothing). So read `confirmation_required` from the preview rather than deriving it — the preview is given the same parameters the create will be.","example":"APPLY TO ALL MATCHING SITES"},"note":{"type":"string","maxLength":2000,"description":"Free text kept with the job, for whoever reads the report later."}}}]},"BulkJobDetail":{"allOf":[{"$ref":"#/components/schemas/BulkJob"},{"type":"object","required":["items","delete_refusal"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/BulkJobItem"}},"delete_refusal":{"description":"For a `find_file` job: the refusal key (e.g. `refusal.bulk.fileProtected`) a `delete_file` of the same path would get, so a report never offers a delete the engine will refuse. `null` when the delete is allowed, and for every other operation.","type":["string","null"]}}}]},"BulkJobItem":{"type":"object","required":["site_id","site_domain","status","error_code","settled_at","retryable","file"],"properties":{"site_id":{"$ref":"#/components/schemas/Uuid"},"site_domain":{"type":"string","description":"Carried on the row rather than joined, so the report survives the site being deleted mid-job — which, on a long run, is not hypothetical."},"status":{"$ref":"#/components/schemas/BulkItemStatus"},"error_code":{"anyOf":[{"$ref":"#/components/schemas/BulkErrorCode"},{"type":"null"}]},"settled_at":{"type":["string","null"],"format":"date-time"},"retryable":{"type":"boolean","description":"Whether `retry-failed` would reopen this item: every `failed` item, and every `skipped` item whose code is not a final answer. A search that found no such file (`file_missing`, `file_not_regular`) has answered and is not retried. Count these to label a retry control; do not re-derive the rule from `status`."},"file":{"description":"For a `find_file` or `delete_file` item that succeeded: the file's size and last modified time. `null` for every other item, and for a file item written before these facts were recorded.","anyOf":[{"$ref":"#/components/schemas/BulkJobItemFile"},{"type":"null"}]},"row":{"type":["integer","null"],"minimum":2,"description":"`site_create` (Add many sites) only: the row's line in the uploaded file, the header being line 1, so the report says \"line 14\" in the customer's own terms. `null` for every other operation. Until the row's site exists, `site_id` is a placeholder."},"refusal":{"description":"`site_create` only: the one-site create path's own keyed refusal for a refused row (domain taken, no site slot, product line not allowed), rendered by the client in the reader's language. `null` otherwise. The row's create payload is never echoed.","anyOf":[{"$ref":"#/components/schemas/Refusal"},{"type":"null"}]}}},"BulkJobItemFile":{"type":"object","required":["size_bytes","modified_at"],"properties":{"size_bytes":{"type":"integer","format":"int64","minimum":0,"description":"Size in bytes. Format it for the reader's locale."},"modified_at":{"type":"string","format":"date-time","description":"When the file was last modified, as the site's filesystem reports it."}}},"BulkJobParams":{"type":"object","description":"The operation's arguments. Which keys are read depends on `operation`: `plugin_install` takes `slugs` + `activate`; `plugin_activate`, `plugin_deactivate` and `plugin_remove` take a single `slug`; `plugin_update` takes `slugs` and treats an empty list as *\"everything with an update waiting\"*, which is what a bulk update means in practice; `theme_install` takes `slug` + `activate`; `blueprint_apply` takes `blueprint_id`; `wp_search_replace` takes `search` + `replace`; `stack_apply`, `core_update` and `application_install` take nothing. ⛔ `application_install` deliberately accepts no `admin_email` or title: they come from the site's own blueprint and plan, exactly as they do for a single-site provision, because a bulk field for them is an account-takeover primitive with a form in front of it.","properties":{"slug":{"type":"string","pattern":"^[A-Za-z0-9_][A-Za-z0-9_-]*$","maxLength":128,"example":"wordpress-seo"},"slugs":{"type":"array","maxItems":50,"items":{"type":"string","pattern":"^[A-Za-z0-9_][A-Za-z0-9_-]*$","maxLength":128},"example":["wordpress-seo","wp-super-cache"]},"search":{"type":"string","minLength":1,"maxLength":2000,"description":"`wp_search_replace` only. The exact text to find. ⛔ Free text rather than a slug — a customer legitimately searches for a whole URL with a query string — so it is bounded by length rather than by a character class, and it is **refused rather than sanitised** when it does not fit: a truncated search term is a *different* search term, and running it would rewrite rows nobody named. It may not be empty.","example":"http://old.example.com"},"replace":{"type":"string","maxLength":2000,"description":"`wp_search_replace` only. What to put in its place. ⭐ May be an empty string, and that asymmetry with `search` is deliberate: an empty replacement is a **deletion**, which is a real and common network-wide instruction. Refusing it to look symmetrical would remove a capability. It may not equal `search` — that would rewrite and re-serialise every matching row for a guaranteed zero change.","example":"https://new.example.com"},"activate":{"type":"boolean","description":"Activate after installing. `false` is what a staged rollout of something risky wants — put the files on every site, switch it on later. Deliberately not the default: \"installed but dormant\" is the surprising outcome, so it is asked for.","default":true},"blueprint_id":{"description":"The blueprint whose declared plugins and theme to apply (`blueprint_apply`).","allOf":[{"$ref":"#/components/schemas/Uuid"}]},"path":{"type":"string","minLength":1,"maxLength":400,"description":"`find_file` and `delete_file` only. One exact path inside each site's document root (`wp-content/uploads/old.php`); a leading `/` means the same. Refused, never sanitised: wildcards, `..`, a part starting with `-`, control characters. Only a regular file is touched — never a folder or a link — and only inside the root. `delete_file` also refuses WordPress core and config files; a deleted file is kept in an archive on the server for 30 days.","example":"wp-content/uploads/old.php"},"version":{"type":"string","maxLength":8,"description":"`php_version` only. The PHP version to switch to (`8.3`). Each site's line decides whether it is allowed, exactly as the single-site switch does.","example":"8.3"},"enabled":{"type":"boolean","description":"`force_https` only. `true` forces HTTPS, `false` stops forcing it."},"canonical_host":{"type":"string","enum":["apex","www"],"description":"`canonical_www` only. Serve on the bare domain or on `www`."},"mode":{"type":"string","enum":["off","allow","block"],"description":"`country_lock` only. `allow` lets in only `countries`, `block` refuses them, `off` removes the rule. Sent together with `countries`, never alone — one flipped in isolation would invert who can reach the site."},"countries":{"type":"array","maxItems":40,"items":{"type":"string","minLength":2,"maxLength":2},"description":"`country_lock` only. ISO 3166-1 alpha-2 codes.","example":["GB","IE"]},"exempt_search_engines":{"type":"boolean","default":true,"description":"`country_lock` only. Verified search-engine crawlers stay exempt by default, because a one-country allow-list otherwise de-indexes the site it exists to rank."},"core":{"type":"string","enum":["off","minor","all"],"description":"`wp_auto_updates` only. WordPress core automatic updates."},"plugins":{"type":"boolean","description":"`wp_auto_updates` only. Plugin automatic updates on or off."},"themes":{"type":"boolean","description":"`wp_auto_updates` only. Theme automatic updates on or off."},"ring":{"type":"string","enum":["canary","early","general"],"default":"general","description":"`wp_auto_updates` only. The update ring; `general` unless opted in early."}},"additionalProperties":false},"BulkJobPreview":{"type":"object","required":["operation","selector","selector_value","matched","eligible","listed","max_sites","confirmation_required","confirmation_phrase","footprint_free_eligible","footprint_warning","sites"],"properties":{"operation":{"$ref":"#/components/schemas/BulkOperation"},"selector":{"$ref":"#/components/schemas/BulkSelector"},"footprint_free_eligible":{"type":"integer","description":"How many of the eligible sites are on the Footprint-Free Hosting product line, counted over the whole selection.","example":0},"footprint_warning":{"type":"boolean","description":"True when the operation installs the same plugin, theme, blueprint or stack on 5 or more Footprint-Free sites: an identical install across a network is a footprint. The job still runs (each footprint-free item waits a random 0-90 s first); the dashboard warns before the customer confirms.","example":false},"selector_value":{"type":"string"},"matched":{"type":"integer","description":"How many sites the selection resolves to, **counted over the whole selection**.","example":12},"eligible":{"type":"integer","description":"How many of those the operation can actually run on — the number that will be enrolled. Counted over the whole selection, never over the listed sample: a truncated count is worse than no count, because it is a smaller number that looks authoritative.","example":6},"listed":{"type":"integer","description":"How many rows are in `sites` (capped at 200); `matched` is the real total.","example":12},"max_sites":{"type":"integer","description":"The ceiling on one job. A larger selection is a `422`, never a silent truncation.","example":1000},"confirmation_required":{"type":"boolean"},"confirmation_phrase":{"description":"The exact phrase to send as `confirm`; `null` when none is needed.","type":["string","null"],"example":"APPLY TO ALL MATCHING SITES"},"sites":{"type":"array","items":{"$ref":"#/components/schemas/BulkJobPreviewSite"}}}},"BulkJobPreviewSite":{"type":"object","required":["site_id","primary_domain","name","eligible","reason"],"properties":{"site_id":{"$ref":"#/components/schemas/Uuid"},"primary_domain":{"$ref":"#/components/schemas/Hostname"},"name":{"type":"string","maxLength":200},"eligible":{"type":"boolean"},"reason":{"description":"Why this site cannot take the operation; `null` when it can.","anyOf":[{"$ref":"#/components/schemas/BulkErrorCode"},{"type":"null"}]}}},"BulkJobProgress":{"type":"object","description":"How far along a job is, how fast it is going and how much longer it has.\n\n⛔⛔ **Every estimate here is nullable, and a `null` must never be rendered as `0`.** `rate_per_minute: 0` says the run has stalled; `null` says no rate has been established yet. They are opposite operational facts, and a client that coalesces one into the other has replaced \"I cannot tell you\" with a confident wrong answer — the reassuring member of an ambiguous pair, which is the direction that gets acted on by doing nothing.\n\n⭐ The clock runs from the moment the **first item settled**, not from `created_at`. A job waits in Temporal's queue for however long the workers are busy, and folding that wait into the rate makes every job look slow at first and then impossibly fast — an estimate that walks backwards.","required":["total","settled","remaining","percent","started_at","elapsed_seconds","rate_per_minute","eta_seconds"],"properties":{"total":{"type":"integer","example":400},"settled":{"type":"integer","description":"Items that have reached a terminal status — anything but `pending`.","example":100},"remaining":{"type":"integer","example":300},"percent":{"description":"`null` for a job with no items. \"Nothing to do\" is not \"all done\", however tidy 100% would look on a progress bar.","type":["integer","null"],"example":25},"started_at":{"description":"When the first item settled. `null` before any work has landed.","type":["string","null"],"format":"date-time"},"elapsed_seconds":{"description":"Working time — from `started_at` to now, or to `settled_at` once finished. `null` before the job starts.","type":["integer","null"],"example":240},"rate_per_minute":{"description":"This job's own observed throughput. `null` until **at least two** items have settled: the clock starts at the first settle, so a single sample gives an arbitrarily large rate (\"4,000 sites/min, done in 0s\") that a screen would then sit on for twenty minutes.\n\n⛔ Deliberately this job's rate and not a platform average — a pass over 400 sites is not the speed of a pass over 5, and an average would be a claim about other people's jobs.","type":["number","null"],"example":25},"eta_seconds":{"description":"Seconds of work left at the current rate. `null` when no rate is established, when nothing remains, or when the job has finished — an ETA on a completed job is a countdown to something that already happened.","type":["integer","null"],"example":720}}},"BulkJobRequest":{"type":"object","required":["operation","selector"],"description":"A selection plus what to do with it. Shared by the preview and the create.","properties":{"operation":{"$ref":"#/components/schemas/BulkOperation"},"selector":{"$ref":"#/components/schemas/BulkSelector"},"selector_value":{"type":"string","maxLength":200,"description":"The selector's argument — a product-line code for `product_line`, an organization id for `org`, a site-group id for `group`, the `GET /v1/sites` query string for `filter`. Ignored for `sites`, whose members are `site_ids`.","example":"footprint_free"},"site_ids":{"type":"array","maxItems":1000,"items":{"$ref":"#/components/schemas/Uuid"},"description":"The explicit selection, for `selector: sites`. Every id is fenced to the organizations you can reach, so one belonging to somebody else resolves to nothing rather than to a cross-tenant write."},"params":{"$ref":"#/components/schemas/BulkJobParams"}},"additionalProperties":false},"BulkJobStatus":{"type":"string","description":"⛔ `partial` is a real outcome, not a rounding of the other two. A job where 4 of 900 sites failed is neither a success nor a failure, and reporting it as either is how a bulk action gets believed — the number to act on is *which* four.","enum":["pending","running","completed","partial","failed"],"example":"partial"},"BulkOperation":{"type":"string","description":"What a bulk job does to each of its sites.\n\n⛔ One job model with an operation discriminator, not eight job models. A selection, a frozen work-list, a durable pass and a per-site report is the same machine for all of them; eight models would give the estate eight previews, eight confirmations and eight report screens that could each drift from the others.\n\n**Platform reach differs by operation, and the difference is not cosmetic.** `featured_image_backfill` draws a featured image for every published post that has none and attaches it. ⛔ It is the only operation here that spends money **per item**: each image is a billed vendor call, so it asks whether the account may be spent on before it starts, counts the sites it skipped, and is bounded per site per run. That bound is a cost control — the remainder is reached by the next run, because a post that gains an image stops matching \"posts with no featured image\".\n\n`stack_apply`, `blueprint_apply`, `application_install`, `plugin_install`, `plugin_update` and `theme_install` need `wp-cli`, which exists only on Zinn®'s own fleet — a site on a resold managed package has no shell and records `unsupported`, not `failed`, because nothing went wrong and no retry can help. `plugin_activate`, `plugin_deactivate`, `plugin_remove`, `core_update` and `wp_search_replace` work on managed hosting and on the fleet alike.\n\n`wp_search_replace` rewrites every occurrence of a string across each selected site's WordPress database — serialised options, post meta and post content alike. ⛔ It is the only operation here that **nothing on this platform can undo**: a removed plugin can be reinstalled, a rewritten database can be restored only from the customer's own backup. It therefore always requires the typed confirmation, however few sites are selected, and the caller should tell the customer to take a backup first. `search` must not be empty — an empty term's behaviour is undefined and its blast radius is every row — while an empty `replace` is accepted, because deleting a string across the estate (\"strip this tracking snippet out of every site\") is a real instruction and not a missing argument.\n\n`application_install` installs WordPress itself onto sites that have an account but no application, so a batch of bare sites comes up serving. It is safe to re-run: both fleet drivers short-circuit on `wp core is-installed`, so a site that is already serving is left exactly as it is. ⛔ It is fenced to the fleet for that reason and not merely for wp-cli — the platform's one-click installer is POSTed to unconditionally and what it does to a package that already has WordPress on it has never been measured here. It always requires the typed confirmation, however few sites are selected, because the act creates a database and an administrator account on every site it touches.\n\n`wp_auto_updates` sets WordPress's own automatic updates on every selected WordPress site through the same update-policy service `PUT /v1/sites/{id}/wordpress/update-policy` uses, so the bulk path stores, applies and re-reads exactly like one site at a time.\n\n**Site actions (V1 parity, row 122) work on every product line, not only WordPress.** Each is the per-site control the customer already has, run over a selection by this same durable job, and each demands exactly the permission(s) its single-site endpoint demands — `country_lock` needs both `hosting.cdn.manage` and `sites.panel_access`, as `SiteGeoRestrictionView` does. `site_delete` schedules deletion with the normal grace period (cancellable from the deleted-sites list) and always requires the typed confirmation; so do `country_lock` and `malware_clean`. `php_version` switches PHP sites to one of the line's allowed versions (`not_php` otherwise); `force_https` and `canonical_www` set the canonical-host plan; `cdn_purge` clears the CDN cache (`no_cdn` when the site has none); `malware_scan` queues a scan and `malware_clean` a clean (`needs_addon` when the cleaner add-on is not held).","enum":["stack_apply","blueprint_apply","application_install","plugin_install","plugin_activate","plugin_deactivate","plugin_remove","plugin_update","theme_install","core_update","wp_search_replace","featured_image_backfill","wp_auto_updates","site_delete","php_version","force_https","canonical_www","country_lock","cdn_purge","malware_scan","malware_clean","find_file","delete_file","site_create"],"example":"plugin_install"},"BulkSelector":{"type":"string","description":"Which sites a job targets.\n\n⛔ There is no `all`. A job belongs to exactly one organization and `all` would span every tenant on the platform; the fleet-wide act is a staff operation and stays on `startPluginRollout`. `product_line`, `org` and `group` are resolved **server-side**, which is the honest way to say \"everything matching\" — a client-side \"select all\" can only ever mean the rows it has loaded.\n\n⭐ `group` is a customer's own segment of their network (`/v1/site-groups`), and it is the selector a footprint-free operator actually thinks in: at PBN scale nobody acts on *a site*, they act on a segment. Resolving it here rather than in the client is what makes a group of any size actionable — a caller that had to enumerate the membership first is bounded by `listSiteGroupSites`' own page cap, and would silently cover a prefix of a large group.\n\n⭐ `filter` is *\"select all N sites matching this list filter\"*: `selector_value` is the `GET /v1/sites` query string (`status`, `product_line`, `group`, `server`, `search`, `org_id`; anything else, such as `ordering` or a cursor, is dropped). It is resolved server-side by the very function the list uses, so the job acts on the set the screen counted. A canonical filter longer than 200 characters is refused, never truncated — a truncated search is a different set of sites.","enum":["sites","product_line","org","group","filter"],"example":"sites"},"BulkSiteImportDefaults":{"type":"object","description":"\"Settings for all sites\": any of these `SiteCreate` fields, applied to every row that leaves the matching column blank. A row naming its own `site_type` drops the batch's stack-specific choices (blueprint, application, PHP, theme, plugins). `footprint_acknowledged` is the shared-footprint warning accepted for own-CDN rows on a platform-managed line. Any other key is ignored.","additionalProperties":true,"properties":{"stack_type":{"type":"string"},"source":{"type":"string"},"site_blueprint_id":{"$ref":"#/components/schemas/Uuid"},"php_version":{"type":"string"},"application":{"type":"string"},"subscription_id":{"$ref":"#/components/schemas/Uuid"},"region":{"type":"string"},"cdn_vendor":{"type":"string"},"dns_vendor":{"type":"string"},"use_own_dns":{"type":"boolean"},"cdn_tier":{"type":"string"},"cdn_account_id":{"type":"string"},"canonical_host":{"type":"string","enum":["apex","www"]},"force_https":{"type":"boolean"},"create_mailbox":{"type":"boolean"},"plugins":{"type":"array","items":{"type":"string"}},"theme":{"type":"string"},"random_theme":{"type":"boolean"},"deploy_target":{"type":"string"},"footprint_acknowledged":{"type":"boolean"}}},"BulkSiteImportPreview":{"type":"object","required":["rows","total","valid","invalid","quota","file_error"],"properties":{"rows":{"type":"array","items":{"type":"object","required":["row","domain","name","site_type","product_line","cdn","errors"],"properties":{"row":{"type":"integer","minimum":1},"domain":{"type":"string"},"name":{"type":"string"},"title":{"type":"string"},"site_type":{"type":"string"},"product_line":{"type":"string"},"cdn":{"type":"string","description":"The row's CDN vendor, `own` for the customer's own account, or empty for the line default."},"errors":{"type":"array","items":{"$ref":"#/components/schemas/BulkSiteImportRowError"}}}}},"total":{"type":"integer","minimum":0},"valid":{"type":"integer","minimum":0},"invalid":{"type":"integer","minimum":0},"quota":{"type":"array","items":{"type":"object","required":["product_line","rows","remaining","enough"],"properties":{"product_line":{"type":"string"},"rows":{"type":"integer","minimum":0},"remaining":{"type":["integer","null"],"description":"`null` = unlimited."},"enough":{"type":"boolean"}}}},"file_error":{"type":["string","null"],"enum":["file_empty","file_too_large","no_rows",null]}}},"BulkSiteImportRequest":{"type":"object","required":["csv"],"properties":{"csv":{"type":"string","maxLength":2097152,"description":"The rows' text. Comma, semicolon or tab separated; the first line is the header when it names a `domain` column, otherwise every line is a row in the template's order."},"defaults":{"$ref":"#/components/schemas/BulkSiteImportDefaults"},"org_id":{"description":"The account the sites belong to. Optional when you reach exactly one.","anyOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]},"product_line":{"type":"string","description":"The product line every row is created on (the deploy form's line)."},"note":{"type":"string","maxLength":500}}},"BulkSiteImportRowError":{"type":"object","required":["column","code"],"properties":{"column":{"type":"string"},"code":{"type":"string","enum":["domain_missing","domain_invalid","domain_duplicate","domain_exists","site_type_missing","unknown_site_type","unknown_cdn","cdn_account_missing","cdn_account_not_connected","cdn_needs_acknowledgement","title_needs_wordpress","invalid_value","over_plan_limit"]}}},"BulkSiteImportTemplate":{"type":"object","required":["columns","example_csv","max_file_bytes"],"properties":{"columns":{"type":"array","items":{"type":"object","required":["name","required","example","allowed"],"properties":{"name":{"type":"string"},"required":{"type":"boolean"},"example":{"type":"string"},"allowed":{"type":"array","items":{"type":"string"}}}}},"example_csv":{"type":"string"},"max_file_bytes":{"type":"integer"},"cdn_own_value":{"type":"string","description":"The `cdn` value meaning \"my own connected CDN account\" (named in `cdn_account`)."}}},"BulkSiteImportUpload":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"},"org_id":{"$ref":"#/components/schemas/Uuid"},"product_line":{"type":"string"},"defaults":{"type":"string","description":"`BulkSiteImportDefaults` as a JSON string."},"note":{"type":"string","maxLength":500}}},"BulkVendorOperationRequest":{"type":"object","additionalProperties":false,"required":["operation","site_ids"],"properties":{"operation":{"type":"string","description":"Which platform operation to run. ⛔ A closed set, not a passthrough — a client cannot name an upstream path. `block_country` and `delete` are deliberately absent and answer `422` with the reason if asked for.","enum":["block_ip","cache_purge","malware_scan","sitemap"]},"site_ids":{"type":"array","minItems":1,"maxItems":400,"description":"The sites to act on, in the caller's own organisation. ⚠️ Site ids only — never vendor package ids.","items":{"$ref":"#/components/schemas/Uuid"}}}},"BulkVendorOperationResult":{"type":"object","additionalProperties":false,"required":["operation","requested","succeeded","failed","skipped","vendor_calls"],"properties":{"operation":{"type":"string","description":"The operation that was run."},"requested":{"type":"integer","description":"How many sites were asked for. ⛔ `succeeded + failed + skipped` always equals this — the three lists are disjoint and complete, so a client can never quietly lose a site."},"succeeded":{"type":"array","items":{"$ref":"#/components/schemas/BulkVendorSiteResult"}},"failed":{"type":"array","description":"Asked for, and the platform did not confirm it.","items":{"$ref":"#/components/schemas/BulkVendorSiteResult"}},"skipped":{"type":"array","description":"Could not be asked about at all — not on a vendor hosting package, or no recorded package id. Neither a success nor a failure, and shown to the customer as its own outcome.","items":{"$ref":"#/components/schemas/BulkVendorSiteResult"}},"vendor_calls":{"type":"integer","description":"How many upstream calls this took. The whole point of the endpoint is that this is much smaller than `requested`."}}},"BulkVendorSiteResult":{"type":"object","additionalProperties":false,"required":["site_id","domain","ok","detail"],"properties":{"site_id":{"$ref":"#/components/schemas/Uuid"},"domain":{"type":"string","description":"The site's primary domain, or empty when the site was not readable."},"ok":{"type":"boolean","description":"The upstream platform's own acknowledgement for this site — never our optimism."},"detail":{"type":"string","description":"Why, when `ok` is false. Empty on success."},"result":{"nullable":true,"description":"Whatever the platform returned for this site — a malware report, a sitemap record, or `true`. ⚠️ Deliberately untyped: the shape differs per operation, and a union here would either drop fields or claim ones that are absent."}}},"BuyPanelLicenceRequest":{"type":"object","required":["product_code","currency"],"additionalProperties":false,"properties":{"product_code":{"type":"string"},"currency":{"type":"string","minLength":3,"maxLength":3},"target_kind":{"type":"string","enum":["ours","customer"],"default":"customer"},"server_id":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/Uuid"}],"description":"Required when `target_kind` is `ours`."},"bound_ip":{"type":"string","nullable":true,"description":"The machine's IP. ⛔ **Required when `target_kind` is `customer`** and refused rather than defaulted: a licence registered against a guessed address is bound to somebody else's server, at our expense, and unreleasable by us."}}},"CachePurgeRequest":{"type":"object","properties":{"urls":{"type":"array","description":"Absolute URLs to purge. Omit or empty to purge all cached content.","maxItems":100,"items":{"type":"string","maxLength":2048}}}},"CachePurgeResult":{"type":"object","required":["purged","urls"],"properties":{"purged":{"type":"boolean"},"urls":{"type":"integer","description":"How many URLs were targeted (0 = a full purge)."}}},"Campaign":{"type":"object","required":["id","org_id","name","template_id","purpose","channels","status","total_recipients","skipped","created_at"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"template_id":{"type":"string","format":"uuid"},"segment_id":{"type":"string","format":"uuid","nullable":true},"purpose":{"type":"string","enum":["marketing","transactional"]},"channels":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","scheduled","sending","paused","sent","cancelled","failed"]},"scheduled_for":{"type":"string","format":"date-time","nullable":true},"include_not_in_good_standing":{"type":"boolean"},"total_recipients":{"type":"integer"},"skipped":{"$ref":"#/components/schemas/CampaignSkipCounts"},"delivery":{"$ref":"#/components/schemas/CampaignDeliveryCounts"},"last_error":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time","nullable":true},"finished_at":{"type":"string","format":"date-time","nullable":true}}},"CampaignControlResult":{"allOf":[{"$ref":"#/components/schemas/Campaign"},{"type":"object","properties":{"signal_delivered":{"type":"boolean","description":"⛔ Reported honestly. `false` means the decision is recorded and the running workflow was not reachable — it will still stop on its next batch, but that is a real difference an operator should see rather than one we smooth over."}}}]},"CampaignDeliveryCounts":{"type":"object","description":"⛔ `sent` is NOT `delivered`. `sent` means a provider accepted the hand-off; `delivered` means the receiving server accepted it, which arrives later by webhook. A screen showing \"delivered\" the second a send finishes is reporting the first number under the second name. `clicked` (docs/1000 §3) counts recipients who clicked a link at least once (it is not a status: a clicker also counts as opened).","additionalProperties":{"type":"integer"}},"CampaignInput":{"type":"object","required":["name","template_id"],"additionalProperties":false,"properties":{"name":{"type":"string","maxLength":160},"template_id":{"type":"string","format":"uuid"},"segment_id":{"type":"string","format":"uuid","nullable":true},"channels":{"type":"array","items":{"type":"string","enum":["email","in_app","slack","telegram"]}},"scheduled_for":{"type":"string","format":"date-time","nullable":true},"include_not_in_good_standing":{"type":"boolean","description":"⚖️ Suspended and unpaid organisations are excluded by default (CLAUDE.md §2.46); this is the explicit per-campaign override that makes a win-back campaign possible. The skip is counted either way."},"org_id":{"type":"string","format":"uuid"}}},"CampaignPreview":{"type":"object","required":["subject","body_text","body_html","headers"],"additionalProperties":false,"properties":{"fallbacks":{"type":"boolean","description":"Whether this was rendered with fallbacks only, echoed so the composer can label the panel honestly."},"subject":{"type":"string"},"body_text":{"type":"string"},"body_html":{"type":"string"},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"RFC 8058 one-click unsubscribe headers on a marketing message; empty otherwise."}}},"CampaignSegment":{"type":"object","required":["id","org_id","scope","name","definition","status"],"properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid","description":"The segment's OWNER, not the orgs it selects."},"scope":{"type":"string","enum":["platform","reseller"]},"name":{"type":"string"},"description":{"type":"string"},"definition":{"$ref":"#/components/schemas/CampaignSegmentNode"},"status":{"type":"string","enum":["active","archived"]},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"CampaignSegmentCondition":{"type":"object","additionalProperties":false,"required":["field","operator"],"properties":{"field":{"type":"string","description":"A key from `GET /v1/campaigns/segments/fields`. Anything else is refused."},"operator":{"type":"string","enum":["in","not_in","gte","lte","between"]},"value":{"description":"A list of strings for `in`/`not_in`; a whole number for `gte`/`lte`; a two-element `[low, high]` for `between`; and for a `money` field an object `{currency, amount_minor}` — integer MINOR units and an ISO code, never a decimal."}}},"CampaignSegmentField":{"type":"object","required":["key","label","kind","operators"],"properties":{"key":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string","enum":["choice","int","money"]},"operators":{"type":"array","items":{"type":"string"}},"choices_source":{"type":"string","nullable":true,"description":"Which list in `choices` populates this field's value picker."},"hint":{"type":"string","description":"What the field means, in the operator's terms. Where an operator's plain meaning is not its name this is where that is said — \"did not renew in the last N days\" is spelled `days_since_last_payment >= N`."}}},"CampaignSegmentFields":{"type":"object","required":["fields","choices","merge_tags","scope","org_id"],"properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/CampaignSegmentField"}},"choices":{"type":"object","description":"Live value lists, restricted to your own population.","additionalProperties":{"type":"array","items":{"type":"object","required":["value","label"],"properties":{"value":{"type":"string"},"label":{"type":"string"}}}}},"merge_tags":{"type":"array","items":{"type":"string"},"description":"The magic tags a template may use. Every one resolves to a STRING for every recipient — never null, never absent, so no message can begin \"Hi ,\"."},"scope":{"type":"string","enum":["platform","reseller"]},"org_id":{"type":"string","format":"uuid"}}},"CampaignSegmentGroup":{"type":"object","additionalProperties":false,"required":["op","children"],"properties":{"op":{"type":"string","enum":["and","or","not"]},"children":{"type":"array","minItems":1,"description":"⛔ At least one. An empty group compiles to a tautology in every naive implementation, so a half-built segment would silently mean the entire estate.","items":{"$ref":"#/components/schemas/CampaignSegmentNode"}}}},"CampaignSegmentNode":{"description":"A filter tree. Two node shapes and no third: a GROUP (`op` with `children`) or a CONDITION (`field`/`operator`/`value`). `not` takes exactly one child — an n-ary `not` reads as \"none of these\" to one author and \"not all of these\" to the next, and the difference is a campaign sent to the wrong people.","oneOf":[{"$ref":"#/components/schemas/CampaignSegmentGroup"},{"$ref":"#/components/schemas/CampaignSegmentCondition"}]},"CampaignSegmentPreview":{"type":"object","required":["total","skipped_not_in_good_standing","skipped_no_marketing_consent","skipped_unsubscribed","skipped_channel_muted","skipped_no_destination","skipped_total","truncated","evaluated_at","scope","sample"],"properties":{"snapshot_id":{"type":"string","format":"uuid","nullable":true,"description":"The approval record's id when `record_approval` was set; `null` otherwise."},"total":{"type":"integer","description":"The TRUE recipient count — not the length of `sample`. Show this number, and show the skips beside it."},"skipped_not_in_good_standing":{"type":"integer"},"skipped_no_marketing_consent":{"type":"integer","description":"People the soft opt-in does not cover — a trial that never converted, an imported contact — who hold no explicit opt-in."},"skipped_unsubscribed":{"type":"integer"},"skipped_channel_muted":{"type":"integer"},"skipped_no_destination":{"type":"integer","description":"Accounts with no member carrying an address on this channel."},"skipped_total":{"type":"integer"},"truncated":{"type":"boolean","description":"True when `sample` is shorter than `total`."},"evaluated_at":{"type":"string","format":"date-time"},"scope":{"type":"string","enum":["platform","reseller"]},"sample":{"type":"array","items":{"type":"object","required":["org_id","address"],"properties":{"org_id":{"type":"string","format":"uuid"},"org_name":{"type":"string"},"address":{"type":"string"},"display_name":{"type":"string"},"locale":{"type":"string"},"plan_name":{"type":"string"},"country":{"type":"string"}}}}}},"CampaignSegmentPreviewRequest":{"type":"object","additionalProperties":false,"description":"Exactly one of `definition` or `segment_id`.","properties":{"definition":{"$ref":"#/components/schemas/CampaignSegmentNode"},"segment_id":{"type":"string","format":"uuid"},"channel":{"type":"string","default":"email"},"purpose":{"type":"string","enum":["marketing","transactional"],"default":"marketing","description":"`marketing` applies the consent fence and the suppression list; `transactional` applies neither — a service notice is not silenced by \"stop sending me offers\"."},"include_not_in_good_standing":{"type":"boolean","default":false,"description":"⚖️ Owner ruling 2026-08-26. Suspended and unpaid accounts are excluded by DEFAULT, because a send costs money (CLAUDE.md §2.46). Set this to reach them anyway — which is what a win-back campaign is for."},"limit":{"type":"integer","minimum":0,"maximum":100,"default":20},"record_approval":{"type":"boolean","default":false,"description":"Persist this resolution as an immutable **approval record** — what the operator saw and agreed to, stamped at the moment they agreed. Returns its id as `snapshot_id`.\n\n⛔ Requires `segment_id`: an approval has to name what was approved, and an unsaved definition has no name. Passing `definition` with this set is a 422.\n\n⭐ This is the source of the left-hand figure in a campaign's `planned · excluded when built · withheld at send` row. Delivery's own per-recipient rows are written AFTER enrolment, so they record who was mailed and cannot reconstruct the audience as it stood when it was approved."}}},"CampaignSegmentWrite":{"type":"object","description":"⛔ No `scope`. It is derived from the caller — staff get the platform scope, a reseller gets their own — and it is immutable after creation.","additionalProperties":false,"required":["name","definition"],"properties":{"name":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":2000},"definition":{"$ref":"#/components/schemas/CampaignSegmentNode"}}},"CampaignSkipCounts":{"type":"object","description":"⛔ Every skip counted separately and never silent, and **every one is present even when it is zero**. \"4,127 recipients, 312 skipped — not in good standing\" is rendered from these, never recomputed by the client: a total with no breakdown is indistinguishable from an audience nobody could see, and a counter that disappears at zero is indistinguishable from a fence that never ran.","required":["not_in_good_standing","unsubscribed","channel_muted","no_destination","no_marketing_consent"],"additionalProperties":false,"properties":{"not_in_good_standing":{"type":"integer"},"unsubscribed":{"type":"integer"},"channel_muted":{"type":"integer"},"no_destination":{"type":"integer"},"no_marketing_consent":{"type":"integer","description":"People the soft opt-in does not cover — a trial that never converted, an imported contact. ⛔ Its own counter rather than folded into `unsubscribed`: \"chose to leave\" and \"never qualified\" are different facts and only one is a marketing problem anybody can act on. Expect a large value with `total: 0` on a fresh estate — that is the fence working, not a failed query."}}},"CampaignSuppression":{"type":"object","required":["id","email","reason","purpose","scope"],"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"reason":{"type":"string","enum":["unsubscribed","bounced","complained","staff_blocked"]},"purpose":{"type":"string"},"note":{"type":"string"},"scope":{"type":"string","enum":["own","platform"],"description":"`platform` is a deliverability suppression that applies everywhere — a hard bounce or a spam complaint. `own` is somebody who left YOUR list."},"created_at":{"type":"string","format":"date-time","nullable":true}}},"CampaignTag":{"type":"object","description":"One magic tag an author may type. ⛔ `fallback` is the load-bearing field: an e-mail beginning \"Hi ,\" is the single thing this feature is judged on, so every tag that sits where a sentence needs a word renders its fallback rather than a blank.","required":["tag","label_key","fallback","example"],"additionalProperties":false,"properties":{"tag":{"type":"string","example":"customer.name"},"label_key":{"type":"string","description":"An i18n message key for the palette label."},"fallback":{"type":"string","example":"there"},"example":{"type":"string","example":"Neil Lock"}}},"CampaignTemplate":{"type":"object","required":["id","org_id","name","purpose","subject","body","channels","archived","created_at","updated_at"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"purpose":{"type":"string","enum":["marketing","transactional"]},"subject":{"type":"string"},"body":{"type":"string"},"channels":{"type":"array","items":{"type":"string"}},"archived":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CampaignTemplateInput":{"type":"object","description":"⛔ `body` is PLAIN TEXT, not HTML. The HTML body is derived by escaping it wholesale, which is what makes a customer-controlled merge value structurally unable to inject markup. An unknown magic tag is refused here rather than at send time.","required":["name","subject","body"],"additionalProperties":false,"properties":{"fallbacks":{"type":"boolean","description":"Preview only. Render with NO merge values, so every tag falls back and the author reads what a customer we know nothing about reads. It exists because a normal preview substitutes example values and therefore cannot show a wording collision between the copy and a fallback (\"your {{plan.name}} plan\" becomes \"your your plan plan\"), and the customers it breaks for are the least engaged and least likely to report it."},"name":{"type":"string","maxLength":160},"subject":{"type":"string","maxLength":300},"body":{"type":"string"},"purpose":{"type":"string","enum":["marketing","transactional"]},"channels":{"type":"array","items":{"type":"string","enum":["email","in_app","slack","telegram"]}},"org_id":{"type":"string","format":"uuid"}}},"CampaignTestSend":{"type":"object","required":["sent","provider","channel","to","from"],"additionalProperties":false,"properties":{"sent":{"type":"boolean"},"provider":{"type":"string"},"channel":{"type":"string","description":"The channel the test actually went out on."},"to":{"type":"string","description":"Where it went. ⛔ Not `format: email` — on a connected channel this is the destination (`#announcements`, a chat id), and declaring it an e-mail address would make a truthful response fail its own contract test."},"from":{"type":"string","description":"Empty on a connected channel, which has no From header."}}},"Cart":{"type":"object","required":["id","org_id","status","lines","subtotal","discount","total","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"org_id":{"$ref":"#/components/schemas/Uuid"},"status":{"type":"string","enum":["open","checking_out","converted","abandoned","expired"]},"currency":{"description":"Fixed when the cart is opened, from `CartCreate.currency` or the `X-Zinn-Currency` header, and then locked — every line must match it. Null only on a legacy cart created before carts carried one (the currency used to be set by whichever call site added the first line, which defaulted to USD however the customer had been quoted — #501).","anyOf":[{"$ref":"#/components/schemas/CurrencyCode"},{"type":"null"}]},"product_line":{"type":["string","null"]},"lines":{"type":"array","items":{"$ref":"#/components/schemas/CartLine"}},"subtotal":{"$ref":"#/components/schemas/MoneyAmount"},"discount":{"$ref":"#/components/schemas/MoneyAmount"},"total":{"$ref":"#/components/schemas/MoneyAmount"},"promo_code":{"type":["string","null"],"description":"The discount code typed into this basket (docs/1311), or null."},"coupon":{"description":"What the typed hosting/SEO coupon did to this basket, or null when no coupon code is typed (a domain promotion code is reported on its lines instead).","anyOf":[{"$ref":"#/components/schemas/CartCoupon"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CartAdopt":{"type":"object","description":"Claim an anonymous guest basket for the signed-in organization.","required":["token"],"properties":{"token":{"type":"string","maxLength":256,"description":"The guest cart's **raw** bearer token — never its digest. The caller proves possession of the credential that already lets them read and modify that cart, so adoption grants nothing new. It is hashed server-side and never stored."},"org_id":{"type":"string","format":"uuid","nullable":true,"description":"Required only when the caller manages billing for more than one organization."}}},"CartAdoptResult":{"type":"object","required":["cart_id","adopted"],"properties":{"cart_id":{"type":"string","description":"The organization cart the items now live in. Empty when the guest basket held nothing — which is a success with zero moved, not a failure."},"adopted":{"type":"integer","minimum":0,"description":"How many items were carried over."}}},"CartCoupon":{"type":"object","required":["code","applied","reason","discount"],"properties":{"code":{"type":"string"},"applied":{"type":"boolean","description":"True when it took something off this basket."},"reason":{"$ref":"#/components/schemas/CouponReason"},"message":{"type":["string","null"],"description":"The English sentence for `reason`."},"kind":{"type":["string","null"],"enum":["percent","fixed",null]},"percent_off":{"type":["integer","null"]},"amount_off_minor":{"type":["integer","null"]},"amount_off_currency":{"type":["string","null"]},"scope":{"type":["string","null"],"enum":["first_period",null]},"discount":{"$ref":"#/components/schemas/MoneyAmount"}}},"CartCreate":{"type":"object","properties":{"org_id":{"description":"Defaults to the caller's org; the caller must hold `billing.payment.manage` there.","anyOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]},"product_line":{"type":"string","maxLength":64,"example":"footprint_free"},"currency":{"description":"The currency to open the basket in — what the customer will be **billed** in. Omit it and the engine uses the `X-Zinn-Currency` header the dashboard already sends, falling back to the base currency. A currency we do not offer, or one no payment gateway can charge, is a `422` rather than a silent substitution (docs/44 §3): a basket that quietly changes currency is a customer agreeing to one number and being charged another.","anyOf":[{"$ref":"#/components/schemas/CurrencyCode"},{"type":"null"}]}}},"CartLine":{"type":"object","description":"One priced line in a cart. `registrar_cost` and a premium line's wholesale quote (both margin audit) are never exposed.","required":["id","kind","unit_amount_minor","currency","line_total_minor"],"properties":{"listed_amount_minor":{"type":["integer","null"],"description":"L66 (docs/82 §2-fx) — on a marketplace line CHARGED in EUR/GBP, the listed USD price (minor units) it was converted from at the locked rate; null on every other line."},"listed_currency":{"type":["string","null"],"description":"The listing currency (`USD`) when `listed_amount_minor` is set, else null."},"id":{"$ref":"#/components/schemas/Uuid"},"kind":{"$ref":"#/components/schemas/LineKind"},"domain_name":{"type":["string","null"]},"tld":{"type":["string","null"]},"period_years":{"type":["integer","null"],"minimum":1},"privacy":{"type":"boolean"},"auto_renew":{"type":"boolean"},"is_premium":{"type":"boolean","description":"This line is bound to a live per-name registrar quote rather than to the TLD catalogue. Its price expires with the availability token it was bought under, so a UI should treat it as time-limited and re-search rather than assume it can sit in a basket indefinitely."},"plan_version_id":{"anyOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]},"listing_package_id":{"description":"The marketplace package a `marketplace_package` line buys. Echoed so a basket can link back to the Zinn® it came from — the line's `description` is a snapshot taken at capture, this is the identity.","anyOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]},"extra_code":{"type":"string","maxLength":64,"description":"The service an `extra` line buys; `\"\"` on every other kind. Exposed for the reason `listing_package_id` is: `description` is a snapshot taken at capture and this is the identity, so a basket can link the row back to what it sells."},"unit_amount_minor":{"type":"integer","format":"int64"},"currency":{"$ref":"#/components/schemas/CurrencyCode"},"discount_minor":{"type":"integer","format":"int64"},"interval":{"type":"string","description":"The billing interval a plan-backed line recurs on — empty on a line that does not recur (every domain kind, which carries `period_years` instead). Exposed because a basket that cannot say whether a figure is per month or per year is asking the customer to guess."},"line_total_minor":{"type":"integer","format":"int64","description":"unit − discount + tax (tax is zero until checkout)."},"metadata":{"type":"object","additionalProperties":true}}},"CartLineCreate":{"type":"object","required":["kind"],"properties":{"kind":{"$ref":"#/components/schemas/SellableLineKind"},"domain_name":{"type":"string","maxLength":253,"description":"Required for a domain line — the FULL name including its extension (`example.com`, matching `tld`); a bare label is refused with `422`."},"tld":{"type":"string","maxLength":63,"description":"Required for a domain line."},"period_years":{"type":"integer","minimum":1,"maximum":10,"description":"Required for a register/transfer/renew line."},"held_line_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"LOCALPRES1114 (docs/1343). Only on a `local_presence_addon` line bought on its own: the HELD order line (same org, same `domain_name`) the registry refused for a non-local owner. Paying the add-on releases that line and retries it at once."},"privacy":{"type":"boolean","default":true},"auto_renew":{"type":"boolean","default":true},"availability_token":{"type":"string","maxLength":2048,"description":"The signed token from `searchDomains` for this exact name. Optional: an ordinary name prices from the TLD catalogue without one. It is **required to buy a premium name**, because a premium price is a live per-name registrar quote that exists nowhere but in the token — a premium name added without one is refused rather than sold at the catalogue rate."},"auth_code":{"type":"string","maxLength":255,"writeOnly":true,"description":"The EPP/authorization code issued by the registrar the domain is currently held at. **Required for a `domain_transfer` line** — no registry will initiate a transfer without it, so a line without one is refused rather than sold and then failed days later by a workflow polling a transfer nobody could have accepted.\n\nWrite-only and never echoed: it is a live credential that authorizes moving the domain, so it is written straight to the secret store and only an opaque reference is retained."},"registrar_route":{"allOf":[{"$ref":"#/components/schemas/RegistrationRouteKey"}],"description":"Which registrar buys the name, on a `domain_register` or `domain_transfer` line. Omit it for the organisation's own registrar, which is the behaviour every caller had before this field existed.\n\nAn unknown key, or a route this organisation has not connected, is refused with 422 — never silently downgraded to the default. A silent fall back would buy the name at a registrar the customer did not choose and *look* like it worked, because the default route is the permissive one; the customer would find out when they tried to move their DNS."},"plan_version_id":{"description":"Required for a `hosting_plan` line — the immutable plan version to bill.","anyOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]},"extra_code":{"type":"string","maxLength":64,"description":"The catalogue code of the service an `extra` line buys. Required for that kind and meaningless on any other.\n\nWhich addons a cart may buy is validated against **its own plan line**, not against anything the client says: eligibility is a fact about the basket (`Extra.product_lines`), so a PBN-only service cannot be bought on a mainstream basket by asking nicely."},"aged_domain_id":{"description":"Required for an `aged_domain` line (s1014 DOMAINS, docs/1107 §5) — an aged domain on sale (`listAgedDomains`). Priced at the catalogue's supplier list price, no markup; a USD price is charged in EUR/GBP at the marketplace's signed locked rate. A domain no longer for sale, above the self-serve ceiling (\"handled personally\") or a paused shop is a `422`. Placement additionally needs a FRESH live check (`checkAgedDomain`) — see `checkoutCart`'s 409 codes.","anyOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]},"aged_destination":{"type":"object","description":"Where the bought aged domain goes, asked in the checkout so staff never have to ask: `registrar` (pushed to your own account there — `registrar` and `account` required) or `zinn` (registered with us in your name).","required":["kind"],"properties":{"kind":{"type":"string","enum":["registrar","zinn"]},"registrar":{"type":"string","maxLength":100},"account":{"type":"string","maxLength":200}}},"listing_package_id":{"description":"Required for a `marketplace_package` line — the package on a **live** listing being bought. The price is the seller's and is re-read on every basket read, so a client-sent amount is ignored. A paused listing, an inactive package, a currency other than the basket's, or your own Zinn® are each a `422` naming the reason.","anyOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]},"interval":{"$ref":"#/components/schemas/BillingInterval","description":"How often a plan-backed line recurs. Defaults to `monthly`.\n\n⛔ Declaring it is the fix: this was read from `metadata.interval` by the repricer and by subscription creation, and written by nothing, because it was on neither this schema nor the serializer — and an undeclared key is dropped silently. So every cart-bought subscription was `monthly` by defaulted absence, and the annual prices published on `GET /v1/catalog/plans` could not be bought at all: a customer choosing \"annual\" was charged the monthly figure and given a monthly subscription, with no error at either end."},"region":{"type":"string","maxLength":32,"description":"The data centre this hosting is bought for — carried onto the resulting subscription and used as the default region for sites created against it (docs/370). Blank or omitted means no preference, and the customer chooses per site as before.\n\nOnly meaningful on a `hosting_plan` line; sent on any other kind it is ignored rather than stored, because a region nothing will ever read is worse carried than dropped.\n\n⛔ Refused with a `422` when it is not a data centre we can currently host in — the same set the create-site picker offers (`listHostingRegions`). A region we run with no capacity today carries error code `REGION_UNAVAILABLE`; a string that is not one of our regions stays `UNPROCESSABLE_ENTITY`. Accepting one we cannot honour would charge the customer for a choice that is then silently ignored on every site they create.\n\n⚠️ A **preference, not a guarantee.** It is captured at purchase and read possibly months later; if by then no box in that region can take the site, the site is placed normally and the preference is ignored rather than the create being refused."},"compute":{"$ref":"#/components/schemas/ComputeLineConfig","description":"Required for a `compute_server` line, and refused on any other kind rather than ignored."},"database":{"$ref":"#/components/schemas/DatabaseLineConfig","description":"Required for a `managed_database` line, and refused on any other kind rather than ignored."}}},"CartSummary":{"type":"object","description":"An open basket as the basket list shows it, not re-priced (`getCart` re-prices).","required":["id","org_id","currency","line_count","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"currency":{"type":["string","null"],"description":"ISO 4217 code the basket is priced in; null until its first line."},"line_count":{"type":"integer","minimum":1},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CartSummaryPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CartSummary"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"CatalogAddon":{"type":"object","required":["code","name","summary","category","interval","fulfilment","product_lines","all_lines","excluded_product_lines","prices"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"summary":{"type":"string"},"category":{"type":"string"},"interval":{"type":"string","enum":["one_off","monthly"]},"fulfilment":{"type":"string","enum":["automated","staff"]},"product_lines":{"type":"array","items":{"type":"string"},"description":"The product-line codes it is sold on; empty (with `all_lines: true`) means every line. When `excluded_product_lines` is non-empty this is the explicit list of lines it IS sold on, and `all_lines` is `false`."},"all_lines":{"type":"boolean"},"excluded_product_lines":{"type":"array","items":{"type":"string"},"description":"The product lines it is NOT sold on. A hosting or add-on order naming the add-on on one of these lines is refused with `addon_not_offered`. `?product_line=` applies the same rule."},"prices":{"type":"array","items":{"$ref":"#/components/schemas/CatalogAddonPrice"}}}},"CatalogAddonPrice":{"type":"object","required":["currency","amount_minor"],"properties":{"currency":{"type":"string"},"amount_minor":{"type":"integer"}}},"CatalogPlan":{"type":"object","required":["id","code","name","product_line","sort_order","entitlements","prices","plan_version_id","plan_version","recommended"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"code":{"type":"string","example":"pbn_25"},"name":{"type":"string","example":"PBN 25"},"product_line":{"type":"string","description":"The `code` of the owning product line.","example":"footprint_free"},"sort_order":{"type":"integer","minimum":0,"description":"Display order within the product line (ascending).","example":4},"entitlements":{"$ref":"#/components/schemas/Entitlements"},"prices":{"type":"array","description":"The plan's list prices, one per (interval, currency).","items":{"$ref":"#/components/schemas/CatalogPrice"}},"orderable":{"type":"boolean","description":"Whether a NEW order of this plan can be built right now — the same answer the partner hosting-order endpoint refuses on (`plan_not_fulfillable`)."},"database_mb_per_site":{"type":"integer","nullable":true,"description":"The database SIZE each site on this plan gets, in MB — the plan's own `database_mb` entitlement when it states one, else the product line's default (the same resolution provisioning uses). Per site, never pooled across a multi-site plan. `null` when neither states it. Plans with an unlimited database COUNT are capped by this size."},"terms":{"type":"array","description":"What each multi-month TERM of this plan costs, **present only when the request named a `currency`** (four terms across every currency would be four times the payload that parameter exists to remove). It is the figure the cart charges for that term, published so a caller READS the price rather than deriving it: a multi-month total computed by a client is a second adder, and the day the rates change it quotes a number we do not charge.","items":{"$ref":"#/components/schemas/CatalogTermPrice"}},"plan_version_id":{"allOf":[{"$ref":"#/components/schemas/Uuid"}],"description":"The **purchasable identifier**: the id of the plan's current sellable version, which is what a `hosting_plan` cart line pins in `plan_version_id`. This is NOT `id` — `id` is the plan's stable identity, while a price change mints a new version rather than mutating the sold one, so this value changes and `id` does not. Use it to buy: `POST /v1/carts` → `POST /v1/carts/{cartId}/lines` with `{kind: hosting_plan, plan_version_id}` → `POST /v1/carts/{cartId}/checkout`."},"plan_version":{"type":"integer","minimum":1,"description":"That version's ordinal, matching `SubscriptionPlanRef.version` — so a client can compare the plan a customer is on with the plan on offer without a second lookup.","example":2},"recommended":{"type":"boolean","description":"The plan staff marked for the public plan cards' \"Recommended\" badge (owner ruling 2026-10-26). Editorial, not a popularity figure. When no plan in a range shown together is marked, the public site badges the 2nd plan of a range of three or more."}}},"CatalogPlanList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogPlan"}}}},"CatalogPrice":{"type":"object","description":"One list price for a plan, in a single interval + currency. A plan carries one entry per (interval, currency): the authored **USD base** plus a derived, charm-rounded price for each enabled currency once the FX refresh has run (docs/29 §2). Before the first refresh only the USD entry appears (the frontend falls back to USD, never an error). The derived prices are stable between refreshes. A derived `annual` price for a plan whose USD annual follows the multi-month term ruling (12 months at 20% off) is derived from that currency's own `monthly` price and rounded DOWN, so it is always at least 20% below twelve local months and is exactly what an annual or 12-month purchase in that currency is charged.","required":["interval","currency","amount_minor"],"properties":{"interval":{"$ref":"#/components/schemas/BillingInterval"},"currency":{"$ref":"#/components/schemas/CurrencyCode"},"amount_minor":{"type":"integer","format":"int64","description":"The price in integer minor units of `currency` (CLAUDE.md §2.8).","example":3000}}},"CatalogTermPrice":{"type":"object","required":["term_months","interval","periods","amount_minor","currency","discount_bps"],"properties":{"term_months":{"type":"integer","enum":[1,3,6,12]},"interval":{"type":"string","description":"The billing interval the subscription this term buys runs on — `monthly` for a prepaid term, `annual` where the plan publishes an annual price that is cheaper."},"periods":{"type":"integer","description":"How many whole periods of `interval` the term pays for."},"amount_minor":{"type":"integer","description":"The total charged for the term, in integer minor units — the number an order of this term is charged, to the unit."},"currency":{"type":"string"},"discount_bps":{"type":"integer","description":"The multi-month discount applied, in basis points off the total (500 = 5%). `0` where a published price decided it. Stated so a saving can be shown — never so a client can recompute the total, which is `amount_minor`."}}},"CdnAccount":{"type":"object","required":["scope","label","vendor","credential_ok","missing_permissions","checked_at"],"description":"Which CDN account a site sits on — ⚖️ the owner's *\"the customer sees which account, and cannot move it\"* (2026-08-26). Rotation is staff-only, in the admin pool console.","properties":{"scope":{"type":"string","enum":["own","platform"],"description":"`own` is the customer's own (BYO) account; `platform` is one of our pool accounts."},"label":{"type":"string","description":"The account's name — populated for `own` ONLY, and empty for `platform`.\n\n⛔⛔ **The emptiness is a refusal, not missing data.** On a Footprint-Free line the pool account is precisely the clustering key the product exists to hide: the same label on two sites links them more reliably than any DNS record. `provider` is already blanked on a managed line for the weaker version of this reason (register #93), so serving the account label would undo that suppression and more. Also empty on a managed line even for an `own` account, where a customer's own account login is *more* identifying than a vendor name, not less."},"vendor":{"type":"string","description":"Driver registry name (`cloudflare`, `bunnycdn`, `cdn77`). Empty on a managed line, for the reason `label` gives."},"credential_ok":{"type":["boolean","null"],"description":"**Tri-state, and the null is the point (§2.44).** `true` = exercised and works. `false` = exercised and broken; the customer must act. `null` = **not checked, or no verdict could be obtained** — an unreachable vendor is not evidence about a token.\n\n⛔ A client that renders two states is wrong in one direction or the other: folding `null` into `true` shows an unchecked credential as healthy, and folding it into `false` shows a red banner to a customer whose credential is fine.\n\n⭐ Always `null` for a `platform` account. Our own pool credential's health is not something a customer can act on, and a red banner about our token on their screen is noise they cannot clear; staff see it in the admin pool console."},"missing_permissions":{"type":"array","items":{"type":"string"},"description":"Permission keys the last check proved ABSENT — what the customer has to go and grant at their vendor. ⛔ Keys only: never a credential, and never a vendor exception's own text, which can carry the request URL and with it the token."},"checked_at":{"type":["string","null"],"format":"date-time","description":"When the credential was last exercised, or null for never. ⛔ Null here and `credential_ok: null` are the same fact seen twice and a client should say \"not checked yet\", never leave a blank."}}},"CdnAiBotMode":{"type":"string","description":"How the edge treats AI crawlers. `disabled` leaves them alone. This is the control on the screen most able to cost a site traffic, in either direction: blocking AI answer engines removes a site from their citations, and allowing them lets a site be quoted without a click.","enum":["disabled","allow","block","managed_challenge"],"example":"disabled"},"CdnCacheLevel":{"type":"string","enum":["basic","simplified","aggressive"],"description":"How aggressively the edge treats query strings as distinct cached objects, least to most. Cloudflare's `bypass` is deliberately not offered: it is an emergency operator state, and a customer who selected it would see a site that is slower with the CDN on than off.","example":"basic"},"CdnCacheLevelReported":{"type":"string","enum":["basic","simplified","aggressive","by_parameters","provider_default"],"description":"What a provider may REPORT for `cache_level` — the writable vocabulary plus the read-only states. `by_parameters` means the edge caches by a **named list of query parameters** configured directly at the provider (CDN77's `query_string.ignore_type = list`, Gcore's `query_params_whitelist`/`blacklist`).\n\n⛔ It is reported and **never writable**, which is why this is a separate schema from `CdnCacheLevel` rather than three more values on it. This platform does not manage that parameter list and does not show it, so offering it as a choice would promise a control we cannot honour, and writing one of the other levels over it would silently discard an operator's configuration. `PUT` answers `422` for it, and it appears in no provider's `supported_values` by construction.\n\n`provider_default` means the provider reports **no** query-string option at all — nobody has set one, so the provider's own built-in default applies (Gcore answers `\"ignoreQueryString\": null`). It is deliberately not reported as `aggressive` or any other level: the platform has not measured that default and does not invent one. It is read-only for the same reason as `by_parameters`; choosing a writable level replaces it.\n\n⭐ A client renders the current value even when it is not selectable — as a disabled option — rather than showing a control whose value is missing from its own list.","example":"simplified"},"CdnConfig":{"type":"object","required":["site_id","product_line","managed","enabled","tier","provider","account","price_minor","currency","edge"],"properties":{"old_zone_removed":{"type":"boolean","description":"Only on a `switchSiteCdn` response, and always `false` there since that operation began starting a durable move (W43-06): nothing has been removed when the request answers. Whether the old zone was really deleted is `getSiteCdnSwap`'s `old_zone_removed`, once the move completes. ⛔ An observation, never an intention."},"swap":{"description":"Only on a `switchSiteCdn` response: the move that request started, or `null` when the site was already where it asked and nothing was started. Poll `getSiteCdnSwap` for its progress.","oneOf":[{"$ref":"#/components/schemas/CdnSwap"},{"type":"null"}]},"nameservers":{"type":"array","items":{"type":"string"},"description":"Only on a switch response, and always empty there now: the destination zone does not exist when the request answers. The nameservers to set at your registrar are `getSiteCdnSwap`'s `nameservers`.\n\n⛔ **The customer has to act on this.** Cloudflare assigns a nameserver pair per *account*, so moving a zone between accounts changes them. Until the registrar is updated every visitor still resolves through the old account's nameservers — the records are correct, the edge is live, and the traffic goes the old way."},"site_id":{"$ref":"#/components/schemas/Uuid"},"product_line":{"type":"string","description":"The site product line, which decides whether the CDN is managed."},"managed":{"type":"boolean","description":"True on the footprint-free line, where the CDN is platform-owned footprint machinery the customer neither configures nor sees."},"enabled":{"type":"boolean"},"tier":{"$ref":"#/components/schemas/CdnTier"},"provider":{"type":["string","null"],"description":"Display name of the active CDN, or **null when managed is true** — naming the CDN in front of a footprint-free site would leak the footprint the line exists to hide (register #93). Also null when off."},"account":{"allOf":[{"$ref":"#/components/schemas/CdnAccount"}],"description":"Which CDN account serves this site, and whether its credential still works. ⛔ Always present — never omitted for \"we do not know\", because an absent object is read by a client as \"nothing to show\" (§2.44). The unknown states are carried *inside* it."},"passthrough_target":{"type":"string","description":"Where a `passthrough` site's traffic is pointed — the edge hostname the customer's own CDN gave them, which we publish as this domain's answer. **Empty on every other tier**, where the answer lives in `account` and a second copy would be free to disagree.\n\n⛔ Not suppressed on the footprint-free line, and that is ruling G-3's own reasoning rather than an exception to it: register #93 hides **our pool's** identity from the customer, and this is the address they typed in themselves being read back to them. Blanking it would leave a Footprint-Free site on passthrough unable to see where its own traffic goes."},"passthrough_label":{"type":"string","description":"What the customer calls the CDN they run themselves. ⚠️ **Unverified** — we hold no credential for that edge, so this is their claim and a client must present it as theirs rather than as something the platform established. Empty on every other tier."},"zone_nameservers":{"type":"array","items":{"type":"string"},"description":"The nameservers the CDN provider assigned this site's zone — Cloudflare issues a pair per zone — stored when the zone was created. This is what the domain must be delegated to for the edge to serve it. Empty for a CNAME-fronted CDN (which takes no DNS authority) and when the site has no zone. ⚠️ An assignment, not an observation: whether the domain actually delegates there is `getDomainDelegation`."},"price_minor":{"type":"integer","minimum":0,"description":"Monthly premium-tier price in integer minor units (§2.8)."},"currency":{"type":"string","description":"ISO-4217 code the price_minor above is expressed in."},"edge":{"allOf":[{"$ref":"#/components/schemas/CdnEdge"}],"description":"Which edge is **actually** in front of this site, and which of the CDN screen's controls will do anything.\n\n⛔⛔ **`enabled` above is not the same question and the two disagree on a real, common case.** `enabled` is the state of *our* Cloudflare tier. A site on a resold hosting package is fronted by that vendor's edge as part of the package, so our tier reads `off` while an edge is serving. Measured on 2026-08-27, site `01a00ac1-…`, from the live product: `tier: off` beside `1,405 requests / 6 MB served from the edge in 24h` — **rendered on the same screen**, which is what the platform owner reported.\n\n`enabled` is retained because the tier picker and staff tooling need our own row's state. `edge.serving` is the field a customer-facing status should read."}}},"CdnCrawlerProtectionMode":{"type":"string","description":"Whether the edge challenges ordinary crawlers. **A two-value switch, not the four-mode AI-crawler vocabulary** — the provider answers `400` for `block`, `managed_challenge` and `allow` on this field, measured on a live zone 2026-09-15 (W43-131). It shared `CdnAiBotMode` until then, so the customer's CDN card offered two options the provider refuses outright.\n\n⛔ Blocking here can remove a site from search results, which is why it is the one control on that card the UI argues against rather than merely labels.","enum":["enabled","disabled"],"example":"disabled"},"CdnCredit":{"type":"object","required":["currency","balance_minor","spend_cap_minor","spent_period_minor","min_spend_cap_minor","auto_top_up","auto_top_up_amount_minor","state"],"properties":{"currency":{"type":"string","minLength":3,"maxLength":3},"balance_minor":{"type":"integer"},"spend_cap_minor":{"type":"integer","description":"The customer's own ceiling. Enforced, not advisory."},"spent_period_minor":{"type":"integer"},"min_spend_cap_minor":{"type":"integer","description":"The lowest cap the platform accepts."},"auto_top_up":{"type":"boolean","description":"On by default. Refills the balance so serving continues **below** the cap; it never raises the cap."},"auto_top_up_amount_minor":{"type":"integer"},"state":{"type":"string","enum":["active","paused_cap","paused_standing","paused_admin"]},"paused_reason":{"type":"string"},"worst_case_overshoot_minor":{"type":"integer","description":"How far past the cap spending can run before the next usage sample stops it. Reported rather than hidden: the cap cannot be exact, and a product promising a ceiling it cannot hold is worse than one that states the tolerance."}}},"CdnCreditUpdate":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"spend_cap_minor":{"type":"integer","minimum":0},"auto_top_up":{"type":"boolean"},"auto_top_up_amount_minor":{"type":"integer","minimum":0}}},"CdnEdge":{"type":"object","required":["kind","serving","tier","included_granted","zone_scope","controls"],"description":"The edge in front of one site (`engine.edge.line_capabilities.EdgeProfile`).","properties":{"kind":{"type":"string","enum":["platform","included","none"],"description":"`platform` — we own the edge (our Cloudflare pools); the tier picker is ours to offer and `off` genuinely means no edge.\n\n`included` — the hosting vendor fronts the package as part of what the customer bought. We did not choose it and cannot switch it off, so no tier picker; its optimisation, header and statistics controls are real.\n\n`none` — no edge at all.\n\n⛔ The distinction between `included` and `none` is the whole point. A single boolean collapses them, and that collapse is how a site serving 1,405 requests from an edge came to be described to its owner as having no CDN."},"serving":{"type":"boolean","description":"Whether an edge of that kind is in front of the site right now. On `included` this is true by construction — the vendor fronts every package it sells — and is deliberately **not** derived from a live traffic probe: a site with no visitors yet would otherwise report \"no CDN\", and zero requests is not zero edges.\n\n⛔ A capability answer, never a health one. Nothing alarms on it."},"tier":{"allOf":[{"$ref":"#/components/schemas/CdnTier"}],"description":"The tier on our own row. Meaningless on an `included` site — it describes an edge that is not the one serving — and reported anyway, because the row exists and staff read it."},"included_granted":{"type":"boolean","description":"Whether the plan grants the included CDN, so a client can say *included* rather than offering to sell something already bought."},"zone_scope":{"type":"string","enum":["own","platform"],"description":"Whose DNS zone the site's hostname lives in.\n\n`own` — the site's own domain; zone settings, rules and edge traffic are the customer's.\n\n`platform` — a hostname under a domain the platform operates (a preview address). The zone is the parent domain, shared by every such site, so `zone_settings`, `zone_rules` and `traffic_stats` are false and a client explains why, with the route to connecting a domain of their own (W43-38)."},"fronted":{"type":["boolean","null"],"description":"s1014 L04 (D42744). For a CNAME pull CDN, whether the domain's PUBLIC apex resolves to the edge (`true`), resolves elsewhere — straight at the server, so visitors are not going through the CDN (`false`) — or could not be judged (`null`: a lookup failed, no edge hostname, or a zone-owning CDN, judged elsewhere). `serving` is what was asked for; this is what visitors reach. Cached up to five minutes.","example":true},"fronted_reason":{"type":"string","description":"`points_to_origin` · `unresolved` · empty."},"controls":{"allOf":[{"$ref":"#/components/schemas/CdnEdgeControls"}],"description":"Which cards the CDN screen may render for this site."}}},"CdnEdgeControls":{"type":"object","required":["tier_picker","zone_settings","zone_rules","edge_optimisation","edge_security_headers","traffic_stats","server_cache"],"description":"⚖️ **Owner ruling 2026-08-27: hide what the line cannot use** — *\"no dead controls anywhere\"*. Each flag names a **card**, not an endpoint, deliberately: the endpoints already answered `supported: false` or `404` politely, and the customer went on staring at eleven cards. A polite refusal is not the same control as a card that is not on the page.","properties":{"tier_picker":{"type":"boolean","description":"The off/free/premium/BYO picker. Only where we own the edge."},"zone_settings":{"type":"boolean","description":"Cloudflare zone settings — cache level, development mode, Always Online, the edge-to-origin TLS mode, Brotli. A Cloudflare vocabulary with no equivalent behind a resold package's edge."},"zone_rules":{"type":"boolean","description":"Cloudflare security level, firewall rules and page rules."},"edge_optimisation":{"type":"boolean","description":"The hosting vendor's page-rewriting optimisations. Vendor-edge sites only — there is no platform equivalent, so a fleet site rendering this card would get one that `404`s."},"edge_security_headers":{"type":"boolean","description":"Response headers set at the vendor's edge. Vendor-edge sites only."},"traffic_stats":{"type":"boolean","description":"Requests and bytes served from the edge, whoever's edge it is."},"server_cache":{"type":"boolean","description":"The vendor's server-side cache and its purge. Vendor-edge sites only."}}},"CdnFirewallAction":{"type":"string","description":"What the rule does. Narrower than the provider's own list on purpose: `skip` is omitted, because a skip rule ahead of a block silently disables it and a bypass is not something to offer from a form whose ordering a customer drags.","enum":["block","managed_challenge","js_challenge","challenge","log"],"example":"block"},"CdnFirewallRule":{"type":"object","description":"One custom edge firewall rule.","required":["key","action","expression","description","enabled","foreign"],"properties":{"key":{"type":"string","description":"A stable identifier. Rules created here carry a `zinn-managed-` prefix; a rule written in the provider's own dashboard carries whatever it has, or its provider id. Plain ASCII, because it round-trips through the provider's API and exports.","example":"zinn-managed-1"},"action":{"$ref":"#/components/schemas/CdnFirewallAction"},"expression":{"type":"string","maxLength":4000,"description":"The provider's own matching syntax, passed through unchanged. A neutral matching language every adapter half-implemented would be a rule that silently matches nothing.","example":"(ip.geoip.country eq \"RU\")"},"description":{"type":"string","maxLength":500,"example":"Block Russia"},"enabled":{"type":"boolean","example":true},"foreign":{"type":"boolean","description":"`true` when the rule was written outside this dashboard. It changes the copy, not the permission — it is the customer's provider account and they may edit anything.","example":false}}},"CdnMinTlsVersion":{"type":"string","description":"The oldest TLS version the edge will negotiate. A string — `1.10` is not a version.","enum":["1.0","1.1","1.2","1.3"],"example":"1.2"},"CdnMoveOffer":{"type":"object","description":"An open \"Move it now\" offer (CDNMOVE-ASK): the site is suspended on your own CDN account and we will move it to your other one when you click.","additionalProperties":false,"required":["id","account_id","account_label","vendor","expires_at","available","reason","changes_nameservers","needs_footprint_ack"],"properties":{"id":{"type":"string","description":"The suspension episode the offer belongs to."},"account_id":{"type":"string","description":"The account we offer to move the site onto."},"account_label":{"type":"string","description":"Your own name for that account, as you typed it."},"vendor":{"type":"string","description":"The CDN that account is with."},"expires_at":{"type":"string","format":"date-time"},"available":{"type":"boolean","description":"The offer can be accepted right now."},"reason":{"type":"string","enum":["","target_suspended"],"description":"Why `available` is false; empty when it is true."},"changes_nameservers":{"type":"boolean","description":"The move needs the domain's nameservers changed at its registrar."},"needs_footprint_ack":{"type":"boolean","description":"A Footprint-Free site: moving onto one account of your own links it to every other site on that account."}}},"CdnMoveOfferAccept":{"type":"object","additionalProperties":false,"properties":{"token":{"type":"string","maxLength":512,"description":"The token from the e-mailed link; omit it from the banner's button."}}},"CdnPageRule":{"type":"object","description":"One legacy URL-pattern page rule.","required":["vendor_id","target","actions","priority","enabled"],"properties":{"vendor_id":{"type":"string","example":"9a1b2c3d4e5f"},"target":{"type":"string","example":"example.com/wp-admin/*"},"actions":{"type":"object","additionalProperties":{"type":"string"},"description":"The provider's action list flattened to `id → value`, values rendered as strings. Not typed per action: there are around thirty of them, most deprecated, and a partial mapping would silently drop the one a customer relies on.","example":{"cache_level":"bypass"}},"priority":{"type":"integer","example":1},"enabled":{"type":"boolean","example":true}}},"CdnSecurityLevel":{"type":"string","description":"The provider's own security-level vocabulary, passed through. **Not ordered the way it reads** — `essentially_off` sits between `off` and `low` — so nothing may treat it as a scale.","enum":["off","essentially_off","low","medium","high","under_attack"],"example":"medium"},"CdnSslMode":{"type":"string","enum":["off","full","strict"],"description":"The TLS leg between the edge and the origin. Cloudflare's `flexible` is deliberately absent — it leaves that leg in plaintext, and the platform's Cloudflare adapter refuses to be configured into it, so offering it here would produce a refusal from a layer that cannot name the field.","example":"full"},"CdnSwap":{"type":"object","additionalProperties":false,"required":["id","site_id","status","from_kind","from_label","to_kind","to_label","to_account_id","nameservers","nameservers_applied","delegation_observed_at","old_zone_removed","records_copied","records_source_read","detail","created_at","completed_at","in_flight","cancellable","site_offline"],"description":"A CDN move and what it is waiting for.","properties":{"id":{"type":"string","format":"uuid"},"site_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","creating","repointing","awaiting_delegation","completed","rolled_back","failed"],"description":"⭐ `awaiting_delegation` is the state to render carefully: the move is complete on our side, **both edges are serving the site**, and it is waiting on your registrar. ⛔ `rolled_back` and `failed` are different: the first means the site is back where it started and nobody need do anything; the second means a step of the rollback could not complete and somebody must look."},"from_kind":{"type":"string"},"from_label":{"type":"string"},"to_kind":{"type":"string"},"to_label":{"type":"string"},"to_account_id":{"type":["string","null"],"format":"uuid"},"nameservers":{"type":"array","items":{"type":"string"},"description":"The nameservers your domain must be delegated to. ⛔ **The field this operation exists to deliver**: without it the move never completes, and it does not fail either — it simply waits, with both edges serving, indefinitely."},"nameservers_applied":{"type":"boolean","description":"Whether **we** set them (the domain is registered with us, or with a registrar you have connected) or you must."},"delegation_observed_at":{"type":["string","null"],"format":"date-time","description":"When the new delegation was **observed answering** — never when it was requested. The source zone is not removed until this is set."},"old_zone_removed":{"type":"boolean","description":"An observation, not an intention. A source zone we could not delete leaves you being billed by that vendor for a site it no longer serves."},"records_copied":{"type":"integer","description":"How many of your OTHER DNS records were carried to the new zone. ⛔ Moving between two zone-owning CDNs re-delegates the **whole domain**, so your `MX`, `SPF`, `DMARC` and subdomain records live in the zone being left behind. Publishing only the apex would leave a site that works perfectly and a mailbox that quietly stops receiving."},"records_source_read":{"type":"boolean","description":"Whether your existing records could be read at all. ⛔ Read this **with** `records_copied`, never instead of it: `0` is the truthful answer for a domain that has nothing but an apex, and it is also what an unreadable source zone returns. When this is `false`, check your email and subdomain records after the delegation moves."},"detail":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"in_flight":{"type":"boolean","description":"⛔ `awaiting_delegation` counts as in flight. It is the state most likely to be read as finished — the site works, both edges serve it — and starting a second move from there would build a third zone and orphan two."},"cancellable":{"type":"boolean","description":"Whether `DELETE` can still put the site back. ⛔ Narrower than `in_flight`: false once the domain's nameservers have been changed or the new delegation has been seen answering, because a rollback cannot move the registrar back and removing the new zone would take the site offline. The move then finishes on its own."},"site_offline":{"type":"boolean","description":"True when this is the automatic move of a site whose CDN suspended it and the episode is still open: the old edge refuses the site, so it is offline until the move reaches the new edge (for a domain registered elsewhere, until its nameservers are changed). False once the new nameservers are observed delegated, and false for a move the customer chose, where both edges serve meanwhile."}}},"CdnSwapCheck":{"type":"object","description":"\"Check now\" for a CDN move waiting on the domain's nameservers (CDNMOVE): what the domain uses right now against what the move needs.","additionalProperties":false,"required":["waiting","delegated","nameservers","live_nameservers"],"properties":{"waiting":{"type":"boolean","description":"A move on this site is waiting on its nameservers."},"delegated":{"type":"boolean","description":"The domain already answers with the nameservers the move needs."},"nameservers":{"type":"array","items":{"type":"string"},"description":"The nameservers to set at the domain's registrar."},"live_nameservers":{"description":"The domain's nameservers right now; `null` if the lookup did not answer.","oneOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]}}},"CdnSwapRequest":{"type":"object","additionalProperties":false,"required":["to_kind"],"description":"Where to move this site's CDN.\n\n⛔ `to_kind` has no default, deliberately: a default here would be a destructive one reached by omission, which is the same reason `CdnSwitch.to_own` is required.","properties":{"to_kind":{"type":"string","enum":["platform","own","passthrough"]},"to_account_id":{"type":["string","null"],"format":"uuid","description":"Required when `to_kind` is `own`. ⛔ Must be one of **your own** connected accounts: an id naming a platform pool account is refused rather than honoured, because which pool account a site sits on is the footprint balancer's decision."},"footprint_acknowledged":{"type":"boolean","description":"Required to move a Footprint-Free site off our pool (owner ruling G-3)."},"passthrough_target":{"type":"string","maxLength":253,"description":"Required when `to_kind` is `passthrough` — the edge hostname your own CDN serves this site from. ⛔ Refused together with `to_account_id`: those are opposite operations and guessing which was meant is how a site ends up somewhere nobody chose."},"passthrough_label":{"type":"string","maxLength":64}}},"CdnSwitch":{"type":"object","additionalProperties":false,"required":["to_own"],"properties":{"to_own":{"type":"boolean","description":"`true` moves the site onto your own connected Cloudflare account; `false` returns it to Zinn®'s pool."},"footprint_acknowledged":{"type":"boolean","description":"Required to move a **Footprint-Free** site onto your own account (owner ruling G-3): every site on that account can be linked to every other one on it, which is the connection the line exists to prevent. ⭐ Not required to move back — that restores the line's default and warns nobody. ⚖️ Ruling AB-5 requires it for a move to `passthrough` too."},"passthrough_target":{"type":"string","maxLength":253,"description":"Present ⇒ move this site to **passthrough** (⚖️ ruling AB-5): publish this edge hostname as the domain's answer and remove our zone. Absent ⇒ `to_own` decides, exactly as before.\n\n⛔ `to_own: true` **together with** this field is refused rather than resolved. \"Move me onto my own connected account\" and \"publish this foreign edge hostname\" are opposite operations, and guessing which one a contradictory request meant is how a site ends up somewhere nobody chose.\n\n⭐ `to_own` stays **required** deliberately: making it optional would mean a client that forgot it silently moved the site to our pool — a destructive default reached by omission."},"passthrough_label":{"type":"string","maxLength":64,"description":"Optional free-text name for the CDN the customer runs themselves."}}},"CdnTarget":{"type":"object","additionalProperties":false,"required":["kind","account_id","label","vendor","available","reason","is_current","changes_nameservers","needs_footprint_ack","credential_status"],"description":"One place a site's CDN could be served from.\n\n⛔ `kind` is deliberately NOT a `CdnTier` value. A tier is what the edge *is* (`free`, `premium` and `enterprise` are all our pool); a target is *whose account it sits on*. Reusing the tier vocabulary would make \"move to my own account\" and \"upgrade to premium\" the same word.","properties":{"kind":{"type":"string","enum":["platform","own","passthrough"],"description":"`platform` is Zinn®'s pool — **one** row, never one per pool account: which account a pooled site lands on is the footprint balancer's decision, and enumerating the pool would leak its shape. `own` is one row **per account you have connected**. `passthrough` is an edge you run yourself."},"account_id":{"type":["string","null"],"format":"uuid","description":"The connected account this row names. `null` for the pool, for passthrough, and for the single explanatory row shown to a customer who has connected nothing."},"label":{"type":"string","description":"Your own name for the account. ⛔ **Not translated** — you typed it. Two rows both reading \"Cloudflare\" is not a choice; \"CF — client work\" and \"CF — personal\" is."},"vendor":{"type":"string"},"available":{"type":"boolean","description":"Whether a move to this target could be attempted right now."},"reason":{"type":"string","description":"Why not, as a machine key — `already_current`, `credential_unusable`, `account_disabled`, `no_own_account`, `line_is_platform_managed`, or `dns_not_proxied` (the pool row of a site whose domain's DNS is on our nameservers: no edge is in front of it yet, so it is neither current nor choosable; a support ticket moves it). Empty when `available`. ⛔ A key rather than a sentence, because the sentence is rendered in your language by the client."},"is_current":{"type":"boolean"},"changes_nameservers":{"type":"boolean","description":"Whether moving here changes the domain's **nameservers**, so your registrar must be updated (or we update it, when the domain is registered with us). ⭐ True for a zone-owning CDN even when the vendor is unchanged: Cloudflare assigns a nameserver pair per **account**."},"needs_footprint_ack":{"type":"boolean","description":"Whether `footprint_acknowledged` is required to move here — every site on one account can be linked to every other on it (owner ruling G-3)."},"credential_status":{"type":"string","description":"The account's last probe verdict, for a row that says it cannot be used. Empty for the pool and for passthrough — our pool's credential health is not something you can act on."}}},"CdnTier":{"type":"string","enum":["off","free","premium","byo","passthrough","enterprise"],"description":"`byo` runs the site CDN on a CDN account the customer has **connected** — we hold the credential and drive it, so purge, TLS and zone state all work from the dashboard.\n\n⛔⛔ `passthrough` is **not the same thing** and the distinction is the point (⚖️ owner ruling AB-5, 2026-08-27). There we hold nothing: the customer runs the CDN themselves, gives us the edge hostname, and we publish it as the domain's answer and get out of the way. We cannot purge it, cannot report its TLS, and cannot check its credential — because there is no credential. Collapsing the two would put a purge button on a screen that can never purge.\n\n⭐ It is the *\"any CDN, no driver\"* escape hatch `docs/19` §5.5 spec'd: a customer on a ninth vendor is never turned away.\n\n`premium` is the **platform-managed** tier: it is what a Footprint-Free site is provisioned onto and it is included in that line's price. `enterprise` — \"Enterprise edge\" — is the **metered** upsell, charged per gigabyte against prepaid credit (⚖️ owner ruling 2026-08-27).\n\n⛔ Those two are separate values because they are two products. Reusing `premium` for the metered tier would place every managed-line site on a metered tier and begin billing bandwidth their plan already includes, with nothing failing."},"CdnTrafficDay":{"type":"object","required":["date","requests","bytes","threats","uniques"],"properties":{"date":{"type":"string","example":"2026-08-22"},"requests":{"type":"integer","example":1821},"bytes":{"type":"integer","example":5642542},"threats":{"type":"integer","description":"Requests the edge classified as a threat and acted on.","example":8},"uniques":{"type":"integer","example":80}}},"CdnUpdate":{"type":"object","additionalProperties":false,"required":["tier"],"description":"The tier is the only input. There is no provider or account field — `byo` resolves the connected Cloudflare account server-side, so the client can never point a site at an account the org has not connected.\n\n⛔⛔ **`tier: passthrough` is REFUSED here** (`INVALID_TIER`), and that is not an asymmetry with `byo` to tidy up. This endpoint *records* a choice and moves nothing; for `byo` that is harmless because it writes only \"which account\" facts. Passthrough **is** a routing value — its `cname` is where a visitor's resolver ends up — so writing it without publishing the record would produce a row every screen agrees with and no DNS record supports. There is one door onto passthrough, `startSiteCdnSwap` with `to_kind: passthrough`, and it is the one that repoints the apex and removes our zone once the apex names your edge.","properties":{"tier":{"$ref":"#/components/schemas/CdnTier"},"footprint_acknowledged":{"type":"boolean","description":"The customer's explicit answer to \"your own CDN account is a shared footprint across every site you put on it\".\n\n**Required to move a Footprint-Free site to `byo`** (owner ruling G-3, 2026-08-14), and ignored on every other product line. Without it the endpoint answers `FOOTPRINT_ACKNOWLEDGEMENT_REQUIRED`.\n\n⛔ The risk is specific, not boilerplate: one deanonymised account links every site on it, which is the exact linkage the Footprint-Free line exists to prevent. The customer may accept that; they may not accept it by accident. The answer is recorded on the audit row, so \"was this customer told?\" is answerable months later from the log rather than inferred from a screen having once rendered a warning.\n\n⚖️ Ruling **AB-5** extends this to `passthrough`, which needs it MORE rather than less: under `byo` we can at least see whose account a site is on, and under `passthrough` we hold no credential and cannot inspect the edge at all — so the footprint the customer is accepting is one we could not report on if they asked."},"passthrough_target":{"type":"string","maxLength":253,"description":"⛔⛔ **Accepted by the schema and REFUSED by this endpoint, on every tier.** It is declared so the refusal can name what the caller did wrong rather than arriving as a generic unknown-field error.\n\nOn every tier this endpoint can set, the CNAME is *derived* from the zone our own driver created — so honouring a caller-supplied one would let a request repoint a site's DNS at an address of its choosing. And `passthrough` itself is refused here (see `tier`), so there is no tier on which this field is the right way to say anything.\n\n⭐ The move belongs to `startSiteCdnSwap`, which publishes the address AND removes our zone. This endpoint only records; a row saying traffic goes somewhere no DNS record points would agree with every screen and disagree with the world."},"passthrough_label":{"type":"string","maxLength":64,"description":"Accepted and ignored here for the same reason as `passthrough_target` — set it on `startSiteCdnSwap`, which is the operation that moves the site."}}},"CertificateOrder":{"type":"object","description":"One certificate ordered for this organisation.","required":["id","product_code","product_name","state","common_name","domains","period_years","price_minor","currency","validation_instructions","certificate_pem","chain_pem","message","ordered_at","issued_at","expires_at","days_until_expiry","renewable","free_alternative_exists","renewal_of","last_reminded_at"],"additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"product_code":{"type":"string","description":"The stable machine key (`positive_ssl`). ⛔ Match on this, never on `product_name` — the name is the certificate authority's marketing string and can be corrected without the product changing."},"product_name":{"type":"string","description":"What the customer reads — the authority's own product name (`PositiveSSL`, `S/MIME Personal`, `Unified Communications Certificate (UCC)`). ⛔ Never a translation key: these are trademarks and are identical in all 58 locales. Falls back to `product_code` for a product an operator added without a name, which reads as an unfilled identifier rather than as a plausible product name (D19055/D19058)."},"state":{"type":"string","enum":["pending","awaiting_validation","issued","cancelled","failed","expired"],"description":"⛔⛔ **`awaiting_validation` means PAID AND NOT ISSUED.** The authority charges at order time and then waits for the customer to prove they control the domain. It is deliberately not folded into `pending`, which would read as \"we are working on it\" — an order in this state resolves only when a **human acts**, so a client must surface it and show `validation_instructions` rather than spin on it."},"common_name":{"type":"string","description":"The primary domain on the certificate."},"domains":{"type":"array","items":{"type":"string"},"description":"Additional names (SANs). Empty for a single-domain product."},"period_years":{"type":"integer"},"price_minor":{"type":"integer","format":"int64","description":"What the customer is charged, frozen at order. A copy rather than a join, so an operator repricing the catalogue cannot move an existing bill."},"currency":{"type":"string","minLength":3,"maxLength":3},"validation_instructions":{"type":"string","description":"What the customer must still do, in the authority's own words. ⭐ Carried as text rather than parsed: every authority words it differently, and a half-parsed instruction is worse than none."},"certificate_pem":{"type":"string","description":"The issued certificate. ⭐ Public by nature — it is served to every visitor of the site — which is why it is returned here while its **private key never is**: a customer-generated CSR means the key never left their machine."},"chain_pem":{"type":"string"},"message":{"type":"string","description":"Why it failed or was cancelled, in a sentence the customer reads."},"ordered_at":{"type":"string","format":"date-time","nullable":true},"issued_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"days_until_expiry":{"type":"integer","nullable":true,"description":"Whole days until `expires_at`, negative once it has lapsed. ⛔ `null` and `0` are DIFFERENT answers and a client must not collapse them: `null` means we could not read an expiry back from the authority, and rendering that as \"expires today\" would be a fabrication."},"renewable":{"type":"boolean","description":"Whether to offer a re-order now — issued, inside the 30-day window, and with no renewal already in flight. ⛔ Computed here rather than left to a client to derive from `expires_at`: the \"already renewing\" half needs a query, and three clients deriving the window three ways is how one of them offers a second purchase.\n\n⭐ An **expired** certificate is still `renewable`. The obvious reading of the window would switch the button off at the moment the customer needs it most — the site is already showing a browser warning and a new certificate is the only thing they want. The window has a near edge and no far edge."},"free_alternative_exists":{"type":"boolean","description":"Whether Let's Encrypt issues this kind of certificate for nothing. Carried onto the renewal prompt for the same reason it is on the buy screen: say so **before** asking somebody to spend again."},"renewal_of":{"allOf":[{"$ref":"#/components/schemas/Uuid"}],"nullable":true,"description":"The order this one renews, so a client can show the chain."},"last_reminded_at":{"type":"string","format":"date-time","nullable":true,"description":"When the renewal sweep last REACHED this order — which is not the same as when it last emailed about it. ⛔ The sweep stamps this for every row it reaches **including the ones it refuses to spend on** for good standing (§2.46), so it is the only record that a suspended customer's certificate was seen at all. It answers the question a support conversation actually turns on — *\"you never told me\"* — with a date."}}},"CertificateProduct":{"type":"object","description":"One certificate a customer can buy. ⛔ **There is deliberately no cost field** — what the authority charges us lives on the catalogue row for the admin margin ledger, and rendered beside the sell price it is a margin leak.","required":["code","name","brand","category","validation_method","included_domains","max_period_years","supports_wildcard","warranty_minor","warranty_currency","free_alternative_exists","prices"],"additionalProperties":false,"properties":{"code":{"type":"string","description":"Stable catalogue key — `positive_ssl`, `ev_ssl`, `code_signing_ev`."},"name":{"type":"string"},"brand":{"type":"string","description":"The certificate authority — `Sectigo`."},"category":{"type":"string","enum":["domain_validation","organization_validation","extended_validation","wildcard","multi_domain"]},"validation_method":{"type":"string","description":"How the authority proves the customer is entitled to the certificate — `domain`, `organization` or `extended`. ⭐ This, not the category, is what separates a certificate Let's Encrypt could issue from one it never could."},"included_domains":{"type":"integer","description":"How many names the **price** covers. ⛔⛔ `-1` means a wildcard — one name matching unlimited hosts beneath it, **not** unlimited names. `0` means the product is not a website certificate at all (code signing, S/MIME). Neither is a small number, and a client that renders `-1` as \"minus one domains\" is describing the opposite product."},"max_period_years":{"type":"integer","description":"Longest term the authority sells, in YEARS (Sectigo sells 1 to 5)."},"supports_wildcard":{"type":"boolean"},"warranty_minor":{"type":"integer","format":"int64","description":"What the authority advertises it pays out on a mis-issuance, in minor units. `0` where it publishes none."},"warranty_currency":{"type":"string"},"free_alternative_exists":{"type":"boolean","description":"⭐⭐ **`true` means Let's Encrypt issues this kind of certificate for nothing**, and our own Plesk panels already do it. ⚖️ The owner chose on 2026-08-29 to sell all fifteen and let the customer decide — which is only honest if the screen says so, which is why this field exists. Five of the fifteen are `true`; the ten that are not (organisation- and extended-validation, code signing, S/MIME) cannot be got free anywhere."},"prices":{"type":"array","description":"One entry per term the product is sold for. ⛔ Terms are priced individually and are **not multiples** — Positive SSL is $6.99 for one year and $12.23 for two, not $13.98 — so a client must not derive a missing term.","items":{"type":"object","required":["period_years","amount_minor"],"additionalProperties":false,"properties":{"period_years":{"type":"integer"},"amount_minor":{"type":"integer","format":"int64"}}}}}},"ChangeSitePlanRequest":{"type":"object","description":"The plan to move to, and the figure the customer was shown.","required":["plan_version_id"],"additionalProperties":false,"properties":{"plan_version_id":{"allOf":[{"$ref":"#/components/schemas/Uuid"}],"description":"The priced plan version to move onto, exactly as `getSitePlanChoices` reported it."},"expected_total_minor":{"type":"integer","nullable":true,"minimum":0,"description":"⛔ **A money guard, not a convenience.** The figure the customer was actually shown, in minor units. The engine refuses `422` when its freshly-computed quote differs, so a price that moved between the page rendering and the button being pressed — an FX recompute, a catalogue edit, the period rolling — is never charged silently. Optional so a script may omit it deliberately; a dashboard always sends it."},"gateway":{"type":["string","null"],"description":"The payment rail the customer picked, from `getPaymentOptions`. Omit it (or send `null`) for \"no preference\", which follows the payment method the organization would be charged on anyway — the unchanged behaviour every script and the whole reseller path rely on.\n\n⛔ Its absence is why a customer upgrading before they had ever entered a card saw **\"Failed — no_payment_method\"**: with no rail the charge follows the organization's default, which is the card gateway even for an organization that holds no card, so nothing could ever settle. A rail this change cannot be settled on is a `422` naming the ones that can — validated against the same list the picker is built from, so a screen can never offer a method the charge refuses.","example":"paypal"}}},"ChatAgent":{"type":"object","description":"One site's AI chat agent (W42-L, `docs/594`). Everything a visitor sees is the customer's own branding — this product is white-label by default.","required":["id","name","status","public_key","allowed_origins","sources"],"properties":{"id":{"type":"string","format":"uuid"},"site_id":{"type":"string","format":"uuid","nullable":true},"name":{"type":"string","description":"What the agent calls itself to visitors. The customer's brand, not ours."},"greeting":{"type":"string"},"persona":{"type":"string","description":"Free text describing tone and what to say. ⛔ It cannot widen what the agent may read — retrieval decides that before the model sees anything."},"brand_colour":{"type":"string","example":"#2563eb"},"launcher_position":{"type":"string","enum":["left","right"]},"status":{"type":"string","enum":["active","paused"],"description":"`paused` stops it answering and keeps everything it has learned, so switching back on is instant rather than a re-index."},"handoff_enabled":{"type":"boolean","description":"Offer to pass the visitor to a person when the agent cannot answer."},"public_key":{"type":"string","description":"Carried in the embed snippet. It identifies the agent and authorises nothing a page's reader could not already do — the fence is `allowed_origins`."},"allowed_origins":{"type":"array","items":{"type":"string"},"description":"Origins the public endpoints will answer for. ⛔ **Empty refuses everything** — it means \"not installed yet\", never \"allow anything\"."},"monthly_message_cap":{"type":"integer","description":"Messages included per calendar month. Checked before each answer."},"messages_this_month":{"type":"integer"},"indexed_chunks":{"type":"integer","description":"Passages of the site currently searchable. Zero means it knows nothing yet."},"embed_snippet":{"type":"string","description":"The two lines to paste into any website."},"sources":{"type":"array","items":{"$ref":"#/components/schemas/ChatAgentSource"}}}},"ChatAgentAnswer":{"type":"object","required":["conversation_id","reply","citations","handoff_suggested"],"properties":{"conversation_id":{"type":"string","format":"uuid"},"reply":{"type":"string"},"citations":{"type":"array","description":"The pages of this site the answer was drawn from.","items":{"type":"object","properties":{"title":{"type":"string"},"locale":{"type":"string"}}}},"handoff_suggested":{"type":"boolean","description":"⛔ **Not an error.** `true` means the agent could not answer from this site's content and a person should take over. Rendering it as a fault would blame a vendor outage for an honest gap in the index."},"refusal":{"type":"string","nullable":true,"enum":["provider_outage","credential_problem","refused","unavailable"],"description":"Present only when the turn was refused rather than answered. `refused` is a deliberate decline of ours (a monthly cap reached, an agent switched off) and names no vendor; `unavailable` is our own fault and also names none. ⛔ On the public widget endpoint every refusal carries the same neutral `reply` — a visitor holds no key and pays no bill, so a key or credit instruction is never addressed to them (D25020)."},"failure":{"description":"The classified §2.57 failure behind a refusal — which vendor, whose key, which door. ⛔ Returned ONLY by the owner's preview endpoint; the public widget endpoint never carries it, because it names the vendor.","nullable":true,"allOf":[{"$ref":"#/components/schemas/VendorFailure"}]}}},"ChatAgentAsk":{"type":"object","required":["message"],"properties":{"message":{"type":"string","maxLength":1000},"conversation_id":{"type":"string","format":"uuid","description":"Continue an existing thread. Omit to start one."},"locale":{"type":"string","description":"The visitor's language. The agent answers in this, not in the site owner's language."},"page_url":{"type":"string","maxLength":500}}},"ChatAgentReindex":{"type":"object","required":["agent","runs"],"properties":{"agent":{"$ref":"#/components/schemas/ChatAgent"},"runs":{"type":"array","items":{"type":"object","properties":{"chunks":{"type":"integer"},"pages":{"type":"integer"},"path":{"type":"string","description":"Which route actually ran — `hosted_files` or `crawl`. ⛔ Reported rather than assumed: \"we read your files\" and \"we crawled you\" are different products, and only one of them is what a customer on our own fleet was sold."},"truncated":{"type":"string","nullable":true},"error":{"type":"string","nullable":true}}}}}},"ChatAgentSource":{"type":"object","description":"One place the agent's knowledge comes from, and how that last went.","required":["id","kind","state"],"properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["hosted_files","crawl","manual"],"description":"`hosted_files` reads the site's own files off the box we host it on — available only on our own fleet, and the reason this product knows pages a crawler cannot reach. `crawl` fetches over HTTP and works anywhere. `manual` is text you typed."},"title":{"type":"string"},"url":{"type":"string"},"state":{"type":"string","enum":["pending","ready","failed"],"description":"⛔ `pending` and `failed` are different facts. A source that was tried and could not be read says `failed` and carries `last_error`, so nobody waits for something that already stopped."},"chunk_count":{"type":"integer"},"last_indexed_at":{"type":"string","format":"date-time","nullable":true,"description":"Null means never attempted — not the same as attempted and found nothing."},"last_error":{"type":"string"}}},"ChatAgentSourceCreate":{"type":"object","required":["kind"],"properties":{"kind":{"type":"string","enum":["hosted_files","crawl","manual"]},"url":{"type":"string","description":"Required for `crawl` — the address to start from. Same-site links are followed."},"text":{"type":"string","description":"Required for `manual`."},"title":{"type":"string","description":"A label you will recognise on the screen."}}},"ChatAgentSourceRun":{"type":"object","required":["source"],"properties":{"source":{"$ref":"#/components/schemas/ChatAgentSource"},"pages_read":{"type":"integer"},"truncated":{"type":"string","nullable":true,"description":"⛔ Present only when indexing stopped at a ceiling rather than at the end of the site, and it says how far it got. A truncation nobody reports reads as a complete index."}}},"ChatAgentUpdate":{"type":"object","description":"Any subset of the agent's settings. Every field is optional.","properties":{"name":{"type":"string","maxLength":64},"greeting":{"type":"string","maxLength":280},"persona":{"type":"string"},"brand_colour":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"launcher_position":{"type":"string","enum":["left","right"]},"handoff_enabled":{"type":"boolean"},"status":{"type":"string","enum":["active","paused"]},"allowed_origins":{"type":"array","maxItems":20,"items":{"type":"string"}},"monthly_message_cap":{"type":"integer","minimum":0,"maximum":1000000}}},"ChatAiAllowance":{"type":"object","required":["tier","tier_label","used","included","period"],"properties":{"tier":{"type":"string"},"tier_label":{"type":"string"},"used":{"type":"integer"},"included":{"type":"integer","description":"AI replies this widget may spend our money on this month. Enforced at the point of spend by a single conditional UPDATE, not by a monthly reconciliation."},"period":{"type":"string","description":"`YYYY-MM`, UTC."}}},"ChatCannedReply":{"type":"object","required":["id","widget_id","shortcut","title","body"],"properties":{"id":{"type":"string","format":"uuid"},"widget_id":{"type":"string","format":"uuid","nullable":true},"shortcut":{"type":"string"},"title":{"type":"string"},"body":{"type":"string"}}},"ChatCannedReplyCreate":{"type":"object","required":["shortcut","body"],"properties":{"org_id":{"type":"string","format":"uuid"},"widget_id":{"type":"string","format":"uuid"},"shortcut":{"type":"string","maxLength":40},"title":{"type":"string","maxLength":120},"body":{"type":"string"}}},"ChatCannedReplyList":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ChatCannedReply"}}}},"ChatConversation":{"type":"object","required":["id","widget_id","state","visitor_name","visitor_email","page_url","page_title","referrer","country","locale","assigned_operator","cursor","started_at","last_message_at"],"properties":{"id":{"type":"string","format":"uuid"},"widget_id":{"type":"string","format":"uuid"},"state":{"type":"string","enum":["ai","waiting","open","offline","closed"]},"visitor_name":{"type":"string"},"visitor_email":{"type":"string"},"page_url":{"type":"string"},"page_title":{"type":"string"},"referrer":{"type":"string"},"country":{"type":"string","description":"Two-letter country, resolved at our edge from the connection. The visitor's IP address itself is never stored."},"locale":{"type":"string"},"assigned_operator":{"type":"string"},"cursor":{"type":"integer"},"started_at":{"type":"string","format":"date-time"},"last_message_at":{"type":"string","format":"date-time"}}},"ChatConversationDetail":{"$ref":"#/components/schemas/ChatConversationWithMessages"},"ChatConversationWithMessages":{"allOf":[{"$ref":"#/components/schemas/ChatConversation"},{"type":"object","required":["messages"],"properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/ChatMessage"}}}}]},"ChatInbox":{"type":"object","required":["items","waiting","has_more","poll_after_ms"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ChatConversationWithMessages"}},"waiting":{"type":"integer","description":"How many are waiting for a human right now."},"has_more":{"type":"boolean","description":"Whether more conversations exist than this page carries. Reported rather than silently truncated: \"50 conversations\" and \"50 of 84\" are different facts and only one of them tells the operator to go looking."},"poll_after_ms":{"type":"integer"}}},"ChatMessage":{"type":"object","required":["seq","author","author_name","body","citations","at"],"properties":{"seq":{"type":"integer","description":"Monotonic within the conversation. The poll cursor, and deliberately not a timestamp: two turns written in the same millisecond are indistinguishable by clock, so a time cursor either repeats one or loses one."},"author":{"type":"string","enum":["visitor","operator","assistant","system"]},"author_name":{"type":"string"},"body":{"type":"string"},"citations":{"type":"array","description":"For an assistant turn, the pages it answered from.","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string"}}}},"at":{"type":"string","format":"date-time"}}},"ChatReplyCreate":{"type":"object","required":["message"],"properties":{"message":{"type":"string","maxLength":4000}}},"ChatReplyResult":{"allOf":[{"$ref":"#/components/schemas/ChatConversation"},{"type":"object","properties":{"message":{"$ref":"#/components/schemas/ChatMessage"}}}]},"ChatSettingsChange":{"type":"object","required":["field","key","before","after"],"properties":{"field":{"type":"string","enum":["accent_colour","business_hours","greeting","hide_branding","position","team_name","logo","canned_reply"]},"key":{"type":"string","nullable":true,"description":"The saved reply's shortcut when `field` is `canned_reply`."},"before":{"nullable":true,"description":"The current value. For `logo` a sha256 or null; for `canned_reply` an object with `title` and `body`, or null when the reply does not exist yet."},"after":{"nullable":true,"description":"The value the copy or import writes, in the same shape as `before`."}}},"ChatSettingsCopyRequest":{"type":"object","properties":{"target_widget_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"target_site_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Sites to copy to. A site with no chat gets one, created switched off."},"dry_run":{"type":"boolean"}}},"ChatSettingsCopyResponse":{"type":"object","required":["source_widget_id","dry_run","results"],"properties":{"source_widget_id":{"type":"string","format":"uuid"},"dry_run":{"type":"boolean"},"results":{"type":"array","items":{"$ref":"#/components/schemas/ChatSettingsTransferResult"}}}},"ChatSettingsDocument":{"type":"object","required":["format","version","settings"],"properties":{"format":{"type":"string","enum":["zinn-chat-settings"]},"version":{"type":"integer","minimum":1},"settings":{"type":"object","required":["accent_colour","business_hours","canned_replies","greeting","hide_branding","logo","position","team_name"],"properties":{"accent_colour":{"type":"string"},"business_hours":{"type":"object","additionalProperties":true},"canned_replies":{"type":"array","maxItems":200,"items":{"type":"object","required":["body","shortcut","title"],"properties":{"body":{"type":"string","maxLength":4000},"shortcut":{"type":"string","maxLength":40},"title":{"type":"string","maxLength":120}}}},"greeting":{"type":"string","maxLength":200},"hide_branding":{"type":"boolean"},"logo":{"type":"object","nullable":true,"required":["content_type","data","sha256"],"properties":{"content_type":{"type":"string"},"data":{"type":"string","format":"byte"},"sha256":{"type":"string"}}},"position":{"type":"string","enum":["left","right"]},"team_name":{"type":"string","maxLength":120}}}}},"ChatSettingsTransferResult":{"type":"object","required":["widget_id","site_id","name","created","applied","tier","changes","waiting_for_premium"],"properties":{"widget_id":{"type":"string","format":"uuid","nullable":true,"description":"Null only for a chat a dry run would create."},"site_id":{"type":"string","format":"uuid","nullable":true},"name":{"type":"string"},"created":{"type":"boolean"},"applied":{"type":"boolean"},"tier":{"type":"string"},"changes":{"type":"array","items":{"$ref":"#/components/schemas/ChatSettingsChange"}},"waiting_for_premium":{"type":"array","items":{"type":"string","enum":["business_hours","hide_branding","logo"]},"description":"Changed settings that are stored on this chat and shown to visitors only once it is on Premium."}}},"ChatTransferCreate":{"type":"object","required":["operator"],"properties":{"operator":{"type":"string","description":"The colleague's user id."},"operator_name":{"type":"string"}}},"ChatWidget":{"type":"object","required":["id","site_id","name","public_key","enabled","install","allowed_origins","tier","tier_source","purchased_tier","greeting","team_name","accent_colour","position","hide_branding","logo_url","ai_enabled","offline_email","open_now","ai_allowance","limits","premium_extra_code"],"properties":{"id":{"type":"string","format":"uuid"},"site_id":{"type":"string","format":"uuid","nullable":true},"name":{"type":"string"},"public_key":{"type":"string"},"enabled":{"type":"boolean","description":"Whether the chat renders. Created FALSE always: the plugin ships in the deploy footprint of every WordPress site we host, so a widget may exist for a customer who never asked for one."},"install":{"type":"string","enum":["wordpress_managed","snippet"],"description":"How the chat reaches the site's pages (CHAT-UNIFY). `wordpress_managed`: a WordPress site we host, where the Zinn® Chat plugin is already installed and switching the chat on IS the install (the engine re-applies the site's managed constants on the `platform` queue). `snippet`: anything else; on a WordPress site hosted elsewhere the customer installs the plugin and pastes the key, on any other site the snippet."},"allowed_origins":{"type":"array","items":{"type":"string"},"description":"Origins the widget may be embedded on. An EMPTY list refuses every page rather than allowing any — this is the only control stopping somebody else's site opening conversations against this organisation."},"tier":{"type":"string","description":"The tier this widget is on. Since 2026-09-29 hosting includes no Premium, so this is the tier that was bought (the same value as `purchased_tier`)."},"tier_source":{"type":"string","enum":["free","purchase"],"description":"Why the widget is on that tier: `purchase` means the Premium extra was bought for this site, `free` means it was not. (`hosting` was retired on 2026-09-29 with the hosting inclusion.)"},"purchased_tier":{"type":"string","description":"The tier actually PAID for."},"greeting":{"type":"string"},"team_name":{"type":"string"},"accent_colour":{"type":"string"},"position":{"type":"string","enum":["left","right"]},"hide_branding":{"type":"boolean"},"logo_url":{"type":"string","description":"The uploaded logo, or empty. Shown here whatever the tier so the customer sees what is stored; visitors are served it only on Premium."},"ai_enabled":{"type":"boolean"},"offline_email":{"type":"string"},"business_hours":{"type":"object","additionalProperties":true},"open_now":{"type":"boolean","description":"Whether the chat currently reads as open. Opening hours are a Premium setting, so a free chat is always open whatever hours it has stored."},"ai_allowance":{"$ref":"#/components/schemas/ChatAiAllowance"},"limits":{"type":"object","required":["operator_seats","history_days","branding_removable","team_features"],"properties":{"operator_seats":{"type":"integer","nullable":true},"history_days":{"type":"integer","nullable":true},"branding_removable":{"type":"boolean"},"team_features":{"type":"boolean"}}},"premium_extra_code":{"type":"string","description":"The catalogue code to buy for the premium tier."}}},"ChatWidgetCreate":{"type":"object","required":["name"],"properties":{"org_id":{"type":"string","format":"uuid"},"site_id":{"type":"string","format":"uuid"},"name":{"type":"string","maxLength":120},"team_name":{"type":"string","maxLength":120},"allowed_origins":{"type":"array","items":{"type":"string"}}}},"ChatWidgetList":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ChatWidget"}}}},"ChatWidgetUpdate":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"enabled":{"type":"boolean"},"allowed_origins":{"type":"array","items":{"type":"string"}},"greeting":{"type":"string","maxLength":200},"team_name":{"type":"string","maxLength":120},"accent_colour":{"type":"string","maxLength":7},"position":{"type":"string","enum":["left","right"]},"hide_branding":{"type":"boolean"},"ai_enabled":{"type":"boolean"},"offline_email":{"type":"string"},"business_hours":{"type":"object","additionalProperties":true}}},"CheckedDomainPage":{"type":"object","required":["items","total"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/DomainSeoMetrics"}},"total":{"type":"integer","minimum":0}}},"CheckoutRequest":{"type":"object","properties":{"registrant":{"oneOf":[{"$ref":"#/components/schemas/Registrant"},{"type":"null"}],"description":"The owner of any domain this basket registers or transfers. Optional when the organization already has a complete default registrant (`getDefaultRegistrant`); when sent, it **becomes** that default, in the same transaction as the placement. Without either, a basket holding a `domain_register` or `domain_transfer` line is refused `422 REGISTRANT_REQUIRED` before anything is placed or charged. Ignored on an idempotent replay."},"registry_data":{"type":"object","description":"Q10 — `domain_name` → the fields that domain's registry demands beyond the registrant (`getTldRequirements` lists them per extension: ID / tax / company numbers, `.us` nexus, `.ca` legal type, registry acceptances …). Every `domain_register` / `domain_transfer` line is checked against its extension BEFORE anything is placed; a missing or invalid value is `422 REGISTRY_DATA_REQUIRED` with one `details[]` entry per problem (`domain`, `field`, `code`). Keys an extension does not declare are dropped. Write-only: never echoed on an order.","writeOnly":true,"additionalProperties":{"$ref":"#/components/schemas/RegistryData"}},"billing_country":{"type":["string","null"],"maxLength":2,"description":"ISO 3166-1 alpha-2 country for the tax jurisdiction.","example":"GB"},"availability_tokens":{"type":"object","additionalProperties":{"type":"string"},"description":"`domain_name` → the availability token issued by the domain search endpoint. Required for every `domain_register` line; each is re-verified at checkout and a stale one is a `409`."},"gateway":{"type":["string","null"],"maxLength":32,"description":"The payment rail the customer chose at checkout — one of the codes `getPaymentOptions` returned for this organization and currency. Omit it and the order is charged wallet-first on whichever rail the organization's stored mandate lives on, which is the behaviour every client had before a picker existed.\n\nWhen the chosen rail cannot settle the order **with nobody present** — the customer picked PayPal or crypto, or holds no stored mandate on that rail — the order is placed and **nothing is presented to a gateway**. It comes back `pending_payment` with no payment attempt against it, and the browser then drives that rail's own on-session flow (`payOrder` / `openOrderCustomerAction`, or PayPal's in-page approval). A refused charge is never recorded for a charge that was never asked for.","example":"paypal"},"payment_method_id":{"type":["string","null"],"format":"uuid","description":"Which of the organisation's **own saved cards** pays (row 1107#10, owner 2026-11-07: *\"they can save more than one card right so if so can they select it\"*). An `id` from `listPaymentMethods` that is active, confirmed, unexpired and on the chosen `gateway`. The charge is pinned to that card for this order only; the account's primary and backup roles are not changed. Omit it (or send `null`) and the primary is tried first, then the backup, as before. Any other id (another organisation's, a revoked or expired card, a card on another rail) is refused `422` with `details[0].field = payment_method_id` before any order is placed.","example":"0190f1a2-7c3e-7b1a-9a55-2f7c4e1d0b3a"},"accept_refund_terms":{"type":"boolean","description":"The customer's EXPRESS agreement that **refunds are issued as Zinn® credit** on their account, not to the original payment method (owner ruling 2026-10-26; Consumer Contracts Regulations 2013 reg 34(6)). Needed once per organisation and wording version: without it, and with no agreement on file, checkout is refused `422 REFUND_TERMS_REQUIRED` before anything is placed or charged — ask the customer, then retry the same request (same `Idempotency-Key`) with `true`. ⛔ No schema `default` (a defaulted property becomes REQUIRED in the generated TypeScript)."},"use_credit":{"type":"boolean","description":"Whether the organisation's **account credit pays first** (row 1106#49). Omitted or `true`: credit is debited before the chosen rail and the rail is charged only the remainder (card and crypto through the charge itself; PayPal opens its order for the remainder and the credit is debited just before capture, given back if the capture fails or the approval is abandoned). Credit that covers the whole total settles the order with no gateway. `false`: the balance is left untouched and the rail is charged the whole total. Either way the order is `paid` only when the whole total is settled, and the payment records the credit part in `wallet_applied_minor`."},"expected_total_minor":{"type":["integer","null"],"format":"int64","minimum":0,"description":"The order total the checkout page **displayed to the customer**, in minor units. Send it and checkout refuses with `422` when the basket no longer comes to that figure; omit it and the order is placed at whatever the basket prices to, which is the behaviour every client had before this field existed.\n\nThe basket is re-priced at the moment of placement — deliberately, because a basket that quotes last week's price and charges it is a dispute — so a page left open while a price **rises** would otherwise charge a total the customer never saw. The refusal happens **before the order row is created**, so nothing is placed, nothing is charged and there is nothing to reconcile: the client reloads the basket and shows the new figure.\nThe refusal is `422` with `details[0].field = expected_total_minor` and `details[0].code = TOTAL_CHANGED` (key `refusal.commerce.totalChanged`). A hosting/SEO coupon in the basket that stopped applying (docs/1311: a cap reached, an expiry, a deactivation) is refused whether or not this field is sent — `details[0].field = promo_code` — so the order is never placed at the full price silently.","example":5999}}},"ClaimComputeTrialCreditRequest":{"type":"object","properties":{"org_id":{"type":["string","null"],"format":"uuid","description":"Required only when the caller belongs to more than one organisation."}}},"ClientOtherFloat":{"type":"object","required":["id","reseller_org_id","currency","balance_minor","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"reseller_org_id":{"$ref":"#/components/schemas/Uuid"},"currency":{"type":"string","minLength":3,"maxLength":3},"balance_minor":{"type":"integer","minimum":0},"updated_at":{"type":"string","format":"date-time"}}},"ClientPortalLink":{"type":"object","required":["id","client_id","label","url","live","expires_at","revoked_at","views","last_viewed_at","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"client_id":{"type":"string","format":"uuid"},"label":{"type":"string"},"url":{"type":["string","null"],"format":"uri","description":"`null` once revoked or expired."},"live":{"type":"boolean"},"expires_at":{"type":["string","null"],"format":"date-time"},"revoked_at":{"type":["string","null"],"format":"date-time"},"views":{"type":"integer"},"last_viewed_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"ClientPortalLinkPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ClientPortalLink"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"ClientReport":{"type":"object","required":["id","client_id","client_name","period_start","period_end","locale","state","source","sections","headline","changes","narrative","narrative_note","failure","share_url","share_expires_at","revoked","views","emailed_at","emailed_to","created_at","finished_at"],"properties":{"id":{"type":"string","format":"uuid"},"client_id":{"type":"string","format":"uuid"},"client_name":{"type":"string"},"period_start":{"type":"string","format":"date"},"period_end":{"type":"string","format":"date"},"locale":{"type":"string"},"state":{"type":"string","enum":["building","ready","failed"]},"source":{"type":"string","enum":["manual","schedule"]},"sections":{"type":"array","items":{"$ref":"#/components/schemas/ClientReportSectionKey"}},"headline":{"type":"array","items":{"$ref":"#/components/schemas/ClientReportHeadline"}},"changes":{"type":"integer","description":"How many figures moved since the previous report."},"narrative":{"type":["string","null"],"description":"zs-541: the report's opening in plain words, in the client's language; `null` when there is none."},"narrative_note":{"type":["string","null"],"enum":["written","noSite","noCredit","notAllowed","failed",null],"description":"Why there is or is not an opening (for the agency, never printed): no connected site covers the report, no Zinn® credit, the site may not spend credit, or the writer failed."},"failure":{"description":"Why a failed report failed, or why a ready one could not be e-mailed.","oneOf":[{"$ref":"#/components/schemas/ClientReportFailure"},{"type":"null"}]},"share_url":{"type":["string","null"],"format":"uri","description":"`null` once revoked or expired."},"share_expires_at":{"type":["string","null"],"format":"date-time"},"revoked":{"type":"boolean"},"views":{"type":"integer"},"emailed_at":{"type":["string","null"],"format":"date-time"},"emailed_to":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"}}},"ClientReportAllowance":{"type":"object","required":["held","unlimited","clients","reports","brands","share_days","own_sender"],"properties":{"held":{"type":"boolean","description":"Whether the organisation has Client Reports at all. A pack on its own holds nothing."},"unlimited":{"type":"boolean"},"clients":{"$ref":"#/components/schemas/ClientReportMeter"},"reports":{"$ref":"#/components/schemas/ClientReportMeter"},"brands":{"$ref":"#/components/schemas/ClientReportMeter"},"share_days":{"type":"integer","description":"How long a new report's share link lives."},"own_sender":{"type":"boolean","description":"Whether a look may carry its own sender name and a confirmed reply-to (Pro and Agency)."}}},"ClientReportBrand":{"type":"object","required":["id","name","agency_name","website","logo_sha256","colour","accent","intro","footer","from_name","reply_to","reply_to_verified","is_default","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"agency_name":{"type":"string"},"website":{"type":"string"},"logo_sha256":{"type":"string"},"colour":{"type":"string"},"accent":{"type":"string"},"intro":{"type":"string"},"footer":{"type":"string"},"from_name":{"type":"string"},"reply_to":{"type":"string"},"reply_to_verified":{"type":"boolean"},"is_default":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"ClientReportBrandInput":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"agency_name":{"type":"string","maxLength":160},"website":{"type":"string","maxLength":255,"description":"Printed as text; never fetched."},"colour":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"accent":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"intro":{"type":"string","maxLength":2000},"footer":{"type":"string","maxLength":1000},"from_name":{"type":"string","maxLength":120},"reply_to":{"type":"string","format":"email"},"is_default":{"type":"boolean"}}},"ClientReportCadence":{"type":"string","enum":["weekly","monthly","quarterly","manual"]},"ClientReportClient":{"type":"object","required":["id","name","brand_id","domains","recipients","locale","sections","contact_name","logo_sha256","notes","cadence","send_email","narrative","active","next_run_at","last_run_at","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"brand_id":{"type":["string","null"],"format":"uuid"},"logo_sha256":{"type":"string","description":"The client's own mark (E5); empty when none."},"domains":{"type":"array","items":{"type":"string"}},"recipients":{"type":"array","items":{"type":"string"}},"locale":{"type":"string"},"sections":{"type":"array","items":{"$ref":"#/components/schemas/ClientReportSectionKey"}},"contact_name":{"type":"string"},"notes":{"type":"string"},"cadence":{"$ref":"#/components/schemas/ClientReportCadence"},"send_email":{"type":"boolean"},"narrative":{"type":"boolean","description":"zs-541: reports open with a summary in plain words."},"active":{"type":"boolean"},"next_run_at":{"type":["string","null"],"format":"date-time"},"last_run_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"ClientReportClientInput":{"type":"object","properties":{"name":{"type":"string","maxLength":160},"brand_id":{"type":["string","null"],"format":"uuid"},"domains":{"type":"array","maxItems":50,"items":{"type":"string"}},"recipients":{"type":"array","maxItems":10,"items":{"type":"string","format":"email"}},"locale":{"type":"string","description":"The client's language — any enabled language code."},"sections":{"type":"array","items":{"$ref":"#/components/schemas/ClientReportSectionKey"}},"contact_name":{"type":"string","maxLength":160},"notes":{"type":"string","maxLength":4000,"description":"Your own notes; never printed."},"cadence":{"$ref":"#/components/schemas/ClientReportCadence"},"send_email":{"type":"boolean"},"narrative":{"type":"boolean","description":"zs-541: open each report with a few paragraphs in plain words, written by AI in the client's language from the report's own figures. Paid from Zinn® credits through the connected Zinn® SEO site the report covers (the plugin-AI meter); a report covering no connected site is made without it."},"active":{"type":"boolean"}}},"ClientReportFailure":{"type":"object","required":["key","params","message"],"properties":{"key":{"type":"string","description":"A refusal key the screen renders in the reader's language."},"params":{"type":"object","additionalProperties":{"type":"string"}},"message":{"type":"string","description":"The English sentence","for a caller with no catalogue.":null}}},"ClientReportHeadline":{"type":"object","required":["section","key","value"],"properties":{"section":{"$ref":"#/components/schemas/ClientReportSectionKey"},"key":{"type":"string","description":"The figure's stable key, e.g. `rank_top10`."},"value":{"type":"number"},"of":{"type":["integer","null"]},"better":{"type":"string","enum":["up","down"]}}},"ClientReportMeter":{"type":"object","required":["cap","used","remaining"],"properties":{"cap":{"type":["integer","null"],"description":"`null` is unlimited (a staff organisation)."},"used":{"type":"integer"},"remaining":{"type":["integer","null"]},"resets_at":{"type":"string","format":"date-time","description":"Monthly axes only — when the count resets (the 1st","UTC).":null}}},"ClientReportSectionKey":{"type":"string","enum":["rank","ai_visibility","index","onpage","backlinks","mentions","work","authority"]},"ClientReportSink":{"type":"object","required":["id","client_id","kind","status","account_email","external_url","last_attempted_at","last_synced_at","last_report_id","failure","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"client_id":{"type":"string","format":"uuid"},"kind":{"$ref":"#/components/schemas/ClientReportSinkKind"},"status":{"type":"string","enum":["pending","active","needs_reconnect","revoked"]},"account_email":{"type":"string","description":"The Google account that granted access","as Google reported it.":null},"external_url":{"type":["string","null"],"description":"The spreadsheet or folder in that account."},"last_attempted_at":{"type":["string","null"],"format":"date-time"},"last_synced_at":{"type":["string","null"],"format":"date-time"},"last_report_id":{"type":["string","null"],"format":"uuid"},"failure":{"type":["object","null"],"description":"Why the last copy failed (`refusal.clientReportSinks.*`), cleared on success.","additionalProperties":true},"created_at":{"type":"string","format":"date-time"}}},"ClientReportSinkKind":{"type":"string","enum":["google_sheets","google_drive"]},"ClientReportSinkPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ClientReportSink"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"ClientReportSinkStart":{"type":"object","required":["sink","authorize_url"],"properties":{"sink":{"$ref":"#/components/schemas/ClientReportSink"},"authorize_url":{"type":"string","format":"uri","description":"Google's consent page; open it in the browser."}}},"ClientReportsOverview":{"type":"object","required":["allowance","sections","sections_with_data"],"properties":{"allowance":{"$ref":"#/components/schemas/ClientReportAllowance"},"sections":{"type":"array","description":"Every section a report can carry, in print order.","items":{"$ref":"#/components/schemas/ClientReportSectionKey"}},"sections_with_data":{"type":"array","items":{"$ref":"#/components/schemas/ClientReportSectionKey"}}}},"ClientWallet":{"type":"object","description":"A client's credit balance with their provider. ⛔ The money is the **provider's** float, not Zinn®'s — a liability on their books, settled into their payment account.","required":["org_id","currency","balance_minor","spendable_minor","entries","other_floats"],"properties":{"org_id":{"$ref":"#/components/schemas/Uuid"},"currency":{"type":"string","minLength":3,"maxLength":3},"balance_minor":{"type":"integer","minimum":0,"description":"What you are **owed** — the float your provider is holding for you."},"spendable_minor":{"type":"integer","minimum":0,"description":"What you can **spend today**. Lower than `balance_minor` when your provider's reseller programme is suspended: the deposit is still yours, but nobody is delivering service against it, so offering it to spend would be a promise nobody can keep."},"reseller_org_id":{"oneOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}],"description":"The provider whose float this is."},"entries":{"type":"array","items":{"$ref":"#/components/schemas/ClientWalletEntry"}},"other_floats":{"type":"array","description":"Balances a **previous** provider still holds for you. ⛔ Normally empty. A client who changed provider is still owed what the old one took; omitting it would make that money disappear from the only screen that reports it.","items":{"$ref":"#/components/schemas/ClientOtherFloat"}},"provider":{"type":"string","enum":["reseller","zinn"],"default":"reseller","description":"⭐ **Who is holding this money.** One screen serves both, because *\"credit you hold with your provider\"* is one question whose answer depends on the customer, not on the feature. It matters beyond wording: a `reseller` float can be sent back to the card it came from, while `zinn` credit is **never** refundable — not even on account closure (owner ruling 2026-08-22)."},"purses":{"type":"array","default":[],"description":"The owner's *\"one ledger, named purses\"* — a balance may be restricted to a kind of spending. ⛔ Empty for a reseller float, which has no purses. A purse whose authoritative store is elsewhere is **absent rather than zero**: a zero would be correct about the credit ledger and wrong about what the customer owns.","items":{"$ref":"#/components/schemas/WalletPurse"}}}},"ClientWalletAdjustment":{"type":"object","required":["amount_minor","reason"],"properties":{"amount_minor":{"type":"integer","description":"Signed minor units. ⛔ Cannot take the client below zero."},"reason":{"type":"string","minLength":3,"maxLength":255,"description":"Required, and the client sees it on their statement. An unexplained movement of somebody else's money is the first thing an audit asks about."}}},"ClientWalletEntry":{"type":"object","description":"One line of a client's statement of account. Append-only — a correction is a new line, never an edit, because editing one amount would silently falsify every running balance below it.","required":["id","kind","amount_minor","currency","balance_after_minor","reference","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"kind":{"type":"string","description":"⛔ `correction` is a STAFF correction of a credit grant, not a spend (⚖️ owner ruling 2026-09-08). It is its own kind because a customer reading `spend` is being told they bought something, and a correction is us taking back credit we granted by mistake. Adding a value here without its `wallet.kind.<value>` label renders the raw key to a customer on the money screen — `i18n/computedKeys.test.ts` derives that family from this enum and is what fails when one is missing. `refund` (s1014 AUTOREFUND, 2026-10-30) is a refund paid back as Zinn® credit — every refund is (owner ruling 2026-10-26), including the automatic one for an order line that failed and provably bought nothing.","enum":["topup","spend","spend_reversal","refund_out","adjustment","correction","refund"]},"amount_minor":{"type":"integer","description":"Signed minor units — positive added to the float, negative took from it."},"currency":{"type":"string","minLength":3,"maxLength":3},"balance_after_minor":{"type":"integer","minimum":0,"description":"The running balance after this line, written by the server under the wallet's row lock. ⛔ Not a client-side sum: a total the browser computes disagrees with the server the first time a page boundary or a filter hides a row."},"reference":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"ClientWalletHeldTotal":{"type":"object","required":["currency","amount_minor"],"properties":{"currency":{"type":"string","minLength":3,"maxLength":3},"amount_minor":{"type":"integer","minimum":0}}},"ClientWalletRefund":{"type":"object","description":"⛔ No `to_wallet` flag, deliberately — see the endpoint description.","properties":{"amount_minor":{"type":"integer","minimum":1,"description":"Omit to refund everything still refundable on the deposit."},"reason":{"type":"string","maxLength":255}}},"ClientWalletRow":{"type":"object","required":["id","client_org_id","currency","balance_minor","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"client_org_id":{"$ref":"#/components/schemas/Uuid"},"currency":{"type":"string","minLength":3,"maxLength":3},"balance_minor":{"type":"integer","minimum":0},"updated_at":{"type":"string","format":"date-time"}}},"ClientWalletSummary":{"type":"object","required":["wallets","held_totals","total","returned"],"properties":{"wallets":{"type":"array","items":{"$ref":"#/components/schemas/ClientWalletRow"}},"held_totals":{"type":"array","description":"⛔ A list, not a number. One figure summed across currencies is wrong in all of them, and it is the figure a reseller would put in their accounts.","items":{"$ref":"#/components/schemas/ClientWalletHeldTotal"}},"total":{"type":"integer","description":"How many floats exist. ⛔ `held_totals` is computed over ALL of them while `wallets` is a capped window, so a client reading the list without this would see a total that reconciles with nothing they can page through."},"returned":{"type":"integer","description":"How many `wallets` this response carries."}}},"ClientWalletTopUp":{"type":"object","description":"One attempt to add credit. Charged on the provider's own gateway for a reseller's client, and on Zinn®'s when bought directly.\n\n⭐ **Four money figures, not one, and the reason is the crypto rail.** `quoted_minor` is what was asked for; `settled_minor` is what actually arrived; `fee_minor` is what the provider kept out of that settlement; `credited_minor` is what went into the balance. On a card they agree. On crypto they do not, because the value of the coin moves between quote and confirmation — and Zinn® credits **what settled**, so the customer is owed a visible explanation of the gap rather than a balance that silently disagrees with their receipt.\n\n⛔ `settled_minor` and `fee_minor` are **nullable, and null means *not known yet*** — never zero. A pending crypto invoice has not settled, and a gateway that did not report a fee has not told us there was none.","required":["id","amount_minor","currency","status","refunded_minor","refundable_minor","created_at"],"properties":{"decline_class":{"description":"Zinn® credit only (`/v1/wallet/top-ups`): the class of a REFUSED top-up (PAYNOTICE, row 1108#29), so the screen says what happened and what to do. Empty when it did not fail, failed for a reason that is no decline, or predates the class.","oneOf":[{"$ref":"#/components/schemas/PaymentDeclineClass"},{"type":"string","enum":[""]}]},"quoted_minor":{"type":"integer","minimum":1,"description":"What the customer asked to add, and what the screen promised them."},"settled_minor":{"oneOf":[{"type":"integer","minimum":0},{"type":"null"}],"description":"What actually arrived. **`null` = not known yet**, never zero."},"fee_minor":{"oneOf":[{"type":"integer","minimum":0},{"type":"null"}],"description":"What the provider kept out of the settlement. **`null` = not known**, never zero — recording an unknown as `0` would credit the customer the shortfall."},"credited_minor":{"type":"integer","minimum":0,"description":"What went into the balance — `settled_minor - fee_minor`."},"shortfall_minor":{"oneOf":[{"type":"integer"},{"type":"null"}],"description":"`quoted_minor - credited_minor`. `null` until the top-up settles. Derived rather than stored: it is a difference between two recorded facts, and a stored copy is a second source of truth that drifts."},"purpose":{"type":"string","enum":["general","ai"]},"is_auto":{"type":"boolean","description":"Whether a standing instruction created this, rather than a person."},"action_url":{"type":"string","description":"Where the customer must go to finish paying — a crypto pay-link or an SCA challenge. Losing it strands a pending top-up with no way to complete it."},"id":{"$ref":"#/components/schemas/Uuid"},"amount_minor":{"type":"integer","minimum":1},"currency":{"type":"string","minLength":3,"maxLength":3},"status":{"type":"string","enum":["pending","requires_action","captured","failed"],"description":"⛔ Credit is written on `captured` only. `pending` (a crypto invoice confirming) and `requires_action` (3-D Secure, or a PayPal approval) both mean the money has not arrived yet."},"refunded_minor":{"type":"integer","minimum":0},"refundable_minor":{"type":"integer","minimum":0,"description":"What is left to send back to the card. Zero unless it captured."},"gateway":{"type":"string","description":"The provider's driver — `stripe`, `paypal`, `nowpayments`. ⛔ Never a credential and never a merchant-account reference: which account your provider banks with is their commercial information."},"error":{"type":"string","description":"The gateway's refusal, in words the customer can act on."},"created_at":{"type":"string","format":"date-time"},"captured_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"ClientWalletTopUpCreate":{"type":"object","required":["amount_minor","currency"],"properties":{"amount_minor":{"type":"integer","minimum":1,"maximum":5000000,"description":"Minor units. The ceiling is a fat-finger guard, not a business rule — your provider's own gateway applies the real limits."},"currency":{"type":"string","minLength":3,"maxLength":3},"idempotency_key":{"type":"string","maxLength":100,"description":"Your own replay key. Optional; when absent the server mints one, so a double-submit is at worst a second deliberate-looking top-up rather than a silent double charge."},"gateway":{"type":"string","maxLength":32,"description":"Which rail to take the money on — `stripe`, `paypal` or `nowpayments`. ⛔ Only meaningful when you buy directly from Zinn®: a reseller's client is always charged on their provider's connected gateway and has no choice to make, so this is ignored on that path rather than refused."}}},"ClientWalletTopUpList":{"type":"array","items":{"$ref":"#/components/schemas/ClientWalletTopUp"}},"ClosurePlan":{"type":"object","description":"What closing an organization would do, computed **before** anything is done and by the same function the closure runs.","required":["org_id","org_type","site_ids","reparented_org_ids","retained_domain_ids","outstanding_minor","outstanding_currency","blocked_by_balance","forfeited_credit_minor","forfeited_credit_currency"],"properties":{"org_id":{"$ref":"#/components/schemas/Uuid"},"org_type":{"type":"string"},"site_ids":{"type":"array","description":"Sites that will be torn down, through the ordinary teardown — so they land in `DeletedSite` and stay restorable for the whole retention window.","items":{"$ref":"#/components/schemas/Uuid"}},"reparented_org_ids":{"type":"array","description":"D-W15-11 — client orgs re-parented to Zinn®. Never torn down.","items":{"$ref":"#/components/schemas/Uuid"}},"retained_domain_ids":{"type":"array","description":"D-W15-12 — domains that keep renewing and stay the customer's. Reported so nobody discovers on an invoice what closing did not stop paying for.","items":{"$ref":"#/components/schemas/Uuid"}},"forfeited_credit_minor":{"type":"integer","minimum":0,"description":"⚖️ Wallet credit this organization holds and will **LOSE** on closure — *\"credit is not returnable ever, even on account closure etc.\"* (owner ruling, 2026-08-22).\n\n⛔ Reported for the same reason `retained_domain_ids` is: the consequence must be visible **before** the button, not discovered after it. ⛔⛔ And unlike `outstanding_minor` it does **not** block: that is money owed to us and refusing is right, this is money already paid to us. Refusing on it would trap a customer who wants to leave over a balance they cannot spend down; omitting it would take their money without telling them.\n\nZero for almost every organization. Non-zero is exactly the case that needs a sentence on the screen."},"forfeited_credit_currency":{"type":"string","description":"ISO-4217 code for `forfeited_credit_minor`."},"outstanding_minor":{"type":"integer","description":"Minor units owed (D-W15-13). Mixed currencies report the largest single-currency total, never a sum — adding minor units across currencies is the §2.8 error."},"outstanding_currency":{"type":"string","description":"ISO 4217 code for `outstanding_minor`; empty when nothing is owed."},"blocked_by_balance":{"type":"boolean","description":"True when the closure would be refused and the org suspended instead."}}},"ClosureResult":{"type":"object","description":"What one closure run actually did.","required":["org_id","sites_torn_down","orgs_reparented","domains_retained","renewals_stopped","trials_canceled","dns_zones_deleted","failures"],"properties":{"org_id":{"$ref":"#/components/schemas/Uuid"},"sites_torn_down":{"type":"array","items":{"$ref":"#/components/schemas/Uuid"}},"orgs_reparented":{"type":"array","items":{"$ref":"#/components/schemas/Uuid"}},"domains_retained":{"type":"array","items":{"$ref":"#/components/schemas/Uuid"}},"renewals_stopped":{"type":"array","description":"The organization's own subscriptions whose renewal the closure switched off (a PayPal agreement is also cancelled at PayPal). A closed organization is never charged again: the period already paid for runs out and the subscription expires. Nothing is refunded or prorated. Client organizations are re-parented and keep renewing.","items":{"$ref":"#/components/schemas/Uuid"}},"trials_canceled":{"type":"array","description":"The organization's own trials that were still active and were cancelled with it. A cancelled trial is final and its product line stays used, so closing an account never earns a second trial. Converted, expired and switched trials are left as they were.","items":{"$ref":"#/components/schemas/Uuid"}},"dns_zones_deleted":{"type":"array","description":"The organization's DNS zone records (our mirror of each zone, with its records) deleted with it. A zone the platform created for a site being torn down is kept until that site's teardown has removed the zone itself, then deleted too. DNS zones at the customer's own provider are not touched.","items":{"$ref":"#/components/schemas/Uuid"}},"failures":{"type":"array","description":"`[id, error_class]` pairs for sites whose teardown could not be armed and subscriptions whose renewal could not be stopped. ⛔ **Non-empty means the org is still OPEN** and the closure should be retried — it is never silently counted as done, because a closure reported complete over a live managed hosting package is a bill nobody looks at again.","items":{"type":"array","items":{"type":"string"}}}}},"CmsPreset":{"type":"object","description":"One headless CMS product we can publish to. ⛔ The capability sets genuinely differ: Ghost is the only one with a first-class canonical-url field, and Webflow claims almost nothing because a Webflow collection's fields are whatever the designer made them.","required":["key","label","auth_scheme","default_collection","setup_hint","capabilities"],"properties":{"key":{"type":"string","enum":["payload","strapi","directus","ghost","shopify","webflow","custom"]},"label":{"type":"string"},"auth_scheme":{"type":"string","enum":["bearer","payload_api_key","ghost_admin_jwt","shopify_token","header"]},"default_collection":{"type":"string"},"setup_hint":{"type":"string","description":"Where in that product's admin the customer finds their key."},"capabilities":{"type":"array","items":{"type":"string"}}}},"CmsTargetProbeResult":{"type":"object","description":"What a Test-connection press found. ⛔ A failure is a 200 carrying `reachable: false` and a reason, not an error status — \"we could not reach it\" is the answer to the question that was asked.","required":["site_id","reachable","identity","code","detail","suitability"],"properties":{"site_id":{"type":"string","format":"uuid"},"reachable":{"type":"boolean"},"identity":{"type":"string"},"code":{"type":"string"},"detail":{"type":"string"},"suitability":{"type":"string","enum":["ready","needs_setup","unknown","unsuitable","blocked"]}}},"CodeCareAllowance":{"type":"object","required":["period_start","resets_on","included_minutes","used_minutes","reserved_minutes","left_minutes","frozen"],"properties":{"period_start":{"type":"string","format":"date"},"resets_on":{"type":"string","format":"date"},"included_minutes":{"type":"integer"},"used_minutes":{"type":"integer"},"reserved_minutes":{"type":"integer"},"left_minutes":{"type":"integer"},"frozen":{"type":"boolean","description":"True while a fix invoice is unpaid or the account is not in good standing."}}},"CodeCareCancelResult":{"type":"object","required":["ends_on","min_term_ends_on"],"properties":{"ends_on":{"type":"string","format":"date"},"min_term_ends_on":{"type":"string","format":"date"}}},"CodeCareChoose":{"type":"object","additionalProperties":false,"required":["tier"],"properties":{"tier":{"type":"string","enum":["basic","standard","pro"]},"org_id":{"type":"string","format":"uuid"},"currency":{"type":"string","maxLength":3},"gateway":{"type":"string","maxLength":32}}},"CodeCareChooseResult":{"type":"object","required":["tier","scheduled"],"properties":{"tier":{"type":"string"},"scheduled":{"type":"boolean","description":"True when a downgrade was set for the renewal."},"switch":{"type":"object","additionalProperties":true},"purchase_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"amount_minor":{"type":"integer"},"currency":{"type":"string"}}},"CodeCarePlan":{"type":"object","required":["tier","code","name","price_minor","currency","included_minutes","discount_bps"],"properties":{"tier":{"type":"string","enum":["basic","standard","pro"]},"code":{"type":"string"},"name":{"type":"string"},"price_minor":{"type":"integer","description":"Monthly price in minor units","excl. VAT.":null},"currency":{"type":"string","minLength":3,"maxLength":3},"included_minutes":{"type":"integer"},"discount_bps":{"type":"integer","description":"Discount on extra time","basis points.":null}}},"CodeCareState":{"type":"object","required":["tier","plans","allowance","rate","may_request","terms_version"],"properties":{"tier":{"type":"string","nullable":true,"enum":["basic","standard","pro"]},"plans":{"type":"array","items":{"$ref":"#/components/schemas/CodeCarePlan"}},"allowance":{"allOf":[{"$ref":"#/components/schemas/CodeCareAllowance"}],"nullable":true},"min_term_ends_on":{"type":"string","format":"date","nullable":true},"renews_on":{"type":"string","format":"date","nullable":true},"ends_on":{"type":"string","format":"date","nullable":true},"rate":{"type":"object","required":["hourly_minor","currency","block_minutes","minimum_minutes"],"properties":{"hourly_minor":{"type":"integer"},"currency":{"type":"string"},"block_minutes":{"type":"integer"},"minimum_minutes":{"type":"integer"}}},"may_request":{"type":"boolean"},"terms_version":{"type":"string","description":"The current Development services & Code Care terms; an estimate approval sends it back as `terms_version`."}}},"ComputeAddOnAssignment":{"type":"object","description":"One machine's add-on — what was bought, what it costs, and where it has got to.\n\n⛔ **Never carries the licence key or the vendor's reference.** Key material belongs in Vault; a serial on a tenant-facing payload is a serial in every log line, every backup and every support screenshot.","required":["code","kind","applies_at","state","install_step","install_started_at","install_finished_at","price_minor","currency","message","activated_at","panel_connection_id","panel_login_step"],"additionalProperties":false,"properties":{"code":{"type":"string"},"panel_login_step":{"type":"string","description":"PLESK-SSO self-serve (`docs/1112` §6): `\"\"` idle, `enabling` while a customer-consented enable run holds their one-time access, otherwise the reason token the last run stopped on (`panel_unreachable`, `panel_key_refused`, `egress_not_pinned`, …). A token the client translates, never a sentence."},"panel_connection_id":{"type":"string","format":"uuid","nullable":true,"description":"PLESK-SSO (`docs/1112`): the panel connection behind **Open Plesk** on this machine. `null` until the platform's Plesk key is enrolled and the panel has proved it can mint a one-time login. The click calls `POST /v1/panels/connections/{id}/login-link` — single-use, audited. ⛔ An id, never a URL or a credential."},"kind":{"type":"string","enum":["none","licence_automated","licence_pooled","service"]},"applies_at":{"type":"string","enum":["build","running","running_reboot","any_time"],"description":"⭐ Sent so the screen can say what *happened* rather than inferring it from `state`: an add-on that restarted the machine and one that did not are different promises, and the customer needs the difference after the fact as well as before."},"state":{"type":"string","enum":["pending","queued","installing","active","failed","released"],"description":"⭐ `pending` is a real state and not a spinner: an IP-bound licence cannot be bought until the machine has an address, so a freshly ordered add-on is genuinely waiting for the build. `failed` means the vendor refused, or the install did not succeed — the machine is unaffected and `message` says why in a sentence the customer reads.\n\n`queued` means it is bought and **waiting for a licence** somebody has to free. ⚖️ Owner ruling 2026-08-31: an empty seat pool queues the order rather than refusing it, so the customer keeps their place. Nothing is charged in this state.\n\n`installing` means the install is running **on the machine right now**. A real state and not a spinner: a Plesk install is around fifteen minutes and a CloudLinux conversion restarts the box, so a customer refreshing the page must be told what is happening to their server. Cancelling is refused while this is true."},"install_step":{"type":"string","description":"Where the install run has got to — `preflight`, `licence`, `waiting_for_licence`, `install`, `reboot`, `verify`, `done`, or the reason it stopped (`panel_present`, `conflicting_stack`, `not_enough_memory`, `not_enough_disk`, `unsupported_os`, `no_network`, `install_failed`, `reboot_no_return`, `not_installed`, `unestablished`, `vendor_refused`, `refused`, `vendor_unavailable`, `error`). Empty before an install starts.\n\n⛔ **A machine-readable token, never a sentence.** The dashboard owns the wording in every locale it ships (§2.19); an English string here would reach a customer untranslated at the exact moment we are refusing them something they tried to buy.\n\n⛔ `unestablished` means the preflight ran and its answer could not be parsed — deliberately **not** collapsed into the nearest real reason. A refusal we cannot name has established nothing (§2.44)."},"install_started_at":{"type":"string","format":"date-time","nullable":true,"description":"When the install run began on the box. ⛔ Distinct from when it was bought and from `activated_at`: a queued order has been bought and has neither of the others, which is exactly the state a customer needs to see."},"install_finished_at":{"type":"string","format":"date-time","nullable":true},"price_minor":{"type":"integer","format":"int64","description":"What the customer is charged, in integer minor units, **frozen at purchase**. ⛔ A copy rather than a join: the catalogue price is editable in admin and a customer's bill must not move because an operator repriced the range."},"currency":{"type":"string","minLength":3,"maxLength":3},"message":{"type":"string","description":"Why it failed, in a sentence the customer reads, when `state` is `failed`.\n\n⛔⛤ **It is NOT empty on every other state, and a client that assumes so will hide the one thing a customer needs to act on.** On an **`active`** row it may carry a machine-readable NOTE about something that is not as good as it should be while the add-on still works — today `licence_key_unavailable` or `licence_key_refused` (#4645: the panel is installed and running on its own trial key because the licence we bought could not be applied). That is deliberately not a failure: the customer is being served, so it renders as a warning beside a working add-on rather than as an error. Render an unrecognised value as nothing rather than as raw text."},"activated_at":{"type":"string","format":"date-time","nullable":true}}},"ComputeAddOnOffer":{"type":"object","description":"One row of the add-on picker — what it is, what it costs the customer, and whether they can have it right now.\n\n⛔ **Carries `orderable` and `unavailable_reason` rather than simply omitting an unorderable row.** A tier that vanishes teaches a customer nothing; \"we have run out of licences\" is a sentence they can act on, and it is the difference between a product that looks broken and one that is honest about a supply constraint.\n\n⛔ **There is deliberately no cost field.** What the vendor charges us is on the catalogue row for the admin margin ledger; rendered beside the sell price it is a margin leak — the same reason `ComputeSpec` carries no price.","required":["code","kind","applies_at","amount_minor","currency","orderable","unavailable_reason","supported_images"],"additionalProperties":false,"properties":{"code":{"type":"string","description":"Stable catalogue key — `bare`, `cloudlinux`, `plesk_web_pro`, `managed`."},"kind":{"type":"string","enum":["none","licence_automated","licence_pooled","service"],"description":"How it is fulfilled, and the states differ. `licence_automated` is bought and released through a vendor API unattended; `licence_pooled` comes from a stock of spare serials because the vendor's release is manual in its own portal; `service` is a support promise with no software at all; `none` is bare."},"applies_at":{"type":"string","enum":["build","running","running_reboot","any_time"],"description":"⛔ **A product fact the customer must see before they buy, and the four values are four different promises about their disk.**\n\n`running` — installs over SSH on a machine that is already up, without a reboot and **without touching the data on it**. Plesk is this: the vendor's one-click installer takes around fifteen minutes on a live server.\n\n`running_reboot` — the same, and then the machine **restarts once**. CloudLinux is this: `cldeploy` converts the running system in place and swaps the kernel, and the data survives. The customer is told about the restart before they confirm.\n\n`any_time` — nothing has to be installed for it to be true (the managed service).\n\n`build` — genuinely installable **only** while the machine is being built, so adding it later needs a rebuild, which erases the disk. ⛔⛤ **Nothing in the catalogue is `build` today.** Until 2026-08-31 CloudLinux and both Plesk editions were, on the reasoning that cloud-init runs only at create — which is true of cloud-init and false of the products. See `docs/314`."},"amount_minor":{"type":"integer","format":"int64","description":"Sell price in integer minor units (§2.8). `0` for bare."},"currency":{"type":"string","minLength":3,"maxLength":3},"orderable":{"type":"boolean","description":"Whether it can be bought right now — a question about stock, not configuration."},"arm_supported_images":{"type":["array","null"],"items":{"type":"string"},"description":"s1014 VPS-RANGES r15. The image ids this add-on installs on an **Arm** size. `null` = not sold on Arm at all (CloudLinux, LiteSpeed, KernelCare); an empty array = any Arm image; Plesk = `[\"ubuntu-22.04\"]` (owner ruling 2026-10-23). The order screen hides a `null` add-on when an Arm size is chosen; the cart refuses it too."},"supported_images":{"type":"array","items":{"type":"string"},"description":"Exact operating-system image ids this add-on installs on. ⛔ **An EMPTY array means any**, not none — most add-ons install nothing and constrain nothing.\n\n⛔⛔ Without this a customer can buy CloudLinux on Debian: `cldeploy` converts RHEL-family systems only, and the range publishes Ubuntu, Debian, Fedora and openSUSE alongside AlmaLinux, Rocky and CentOS Stream. The licence would be bought and billed, the machine would build, and the cloud-init would run a script that cannot work — **a healthy server with the software simply absent and no error anywhere.** A client should narrow its OS picker by this; the engine refuses the pair independently, at add-to-cart and again at purchase."},"unavailable_reason":{"type":"string","enum":["","out_of_stock","unstocked"],"description":"Empty when orderable. ⛔ Present as an empty string rather than absent, so a client never has to write an existence check before a value check. `out_of_stock` resolves on its own when a serial is released; `unstocked` means no pool exists behind the row and needs an operator."}}},"ComputeAddonOffer":{"type":"object","description":"One paid option a machine can carry, at **our** price.\n\n⛔ `amount_minor` is an integer of minor units and `currency` is ISO-4217. There is no formatted string anywhere in this object: a client rendering three currencies cannot use a pre-formatted figure, and a float loses a penny per sale (money is never a float).\n\n⛔ The provider's cost to us is **absent** unless the caller is staff. It is an engine secret in the same class as a plan's cost, and a reseller's own margin screen shows what *they* pay us, never what we pay a vendor.","required":["id","kind","label","interval","amount_minor","currency","constraints"],"additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"kind":{"type":"string","enum":["cpanel","disk","backup","image","timeline"],"description":"What it is. The kind decides which provider operation buys it, not merely which icon to draw."},"label":{"type":"string"},"interval":{"type":"string","enum":["monthly","yearly"]},"amount_minor":{"type":"integer","format":"int64","description":"Our price, integer minor units of `currency`."},"currency":{"type":"string","minLength":3,"maxLength":3},"constraints":{"type":"object","additionalProperties":true,"description":"Facts about what the option needs or gives — `min_ram_mb` for cPanel and Windows, `disk_gb` for a disk, `max_sites` for a cPanel tier, `vps_type` for a size-specific backup row. Read them to explain a choice, never to re-derive whether it is offered: this endpoint has already filtered on them."},"vendor_cost_minor":{"type":"integer","format":"int64","description":"STAFF ONLY. What the provider charges us. Absent for a customer."},"margin_minor":{"type":"integer","format":"int64","description":"STAFF ONLY. What we keep."},"markup_percent":{"type":"number","nullable":true,"description":"STAFF ONLY. Our markup over cost. `null` — never `0` — when the provider charges us nothing, because \"markup over zero\" has no value and `0%` would read as \"sold at cost\", which is the opposite of the truth."}}},"ComputeAddonPurchase":{"type":"object","description":"One paid option a tenant actually bought against one machine.\n\n⛔ `status` is `cancelling`, not `ended`, after a removal. The thing is still running and still ours to pay for until its contract expires — the provider charges the term up front and refunds nothing. A screen that showed \"removed\" would be wrong in both directions at once.","required":["id","kind","label","status","amount_minor","currency","interval","created_at"],"additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"kind":{"type":"string","enum":["cpanel","disk","backup","image","timeline"]},"label":{"type":"string"},"status":{"type":"string","enum":["active","cancelling","ended"]},"amount_minor":{"type":"integer","format":"int64","description":"What the customer agreed to pay, captured at the moment of sale — not re-read from the catalogue, which may have been repriced since."},"currency":{"type":"string","minLength":3,"maxLength":3},"interval":{"type":"string","enum":["monthly","yearly"]},"created_at":{"type":"string","format":"date-time"},"vendor_addon_id":{"type":"string","description":"STAFF ONLY. The provider's id for the add-on contract."},"vendor_cost_minor":{"type":"integer","format":"int64","description":"STAFF ONLY."}}},"ComputeAddonPurchaseRequest":{"type":"object","required":["offer_id"],"additionalProperties":false,"properties":{"offer_id":{"allOf":[{"$ref":"#/components/schemas/Uuid"}],"description":"The offer to buy, from `getComputeServerPlan`'s `available` or `getVpsAddonOptions`. ⛔ There is deliberately no price field: a price sent by a client is not read, and the charge is always the catalogue's."}}},"ComputeAttachNetworkRequest":{"type":"object","required":["network_id"],"additionalProperties":false,"properties":{"network_id":{"$ref":"#/components/schemas/Uuid"}}},"ComputeBackupTier":{"type":"object","description":"A machine's backup tier and the price of moving it.\n\n⛔ `tier` is the provider's own word, verbatim (`normal` / `upgraded`), because rounding it to a boolean loses the difference between \"which tier am I on\" and \"are backups on\". The value a client SENDS is ours (`standard` / `pro`) — the provider's vocabulary is not a customer's, and \"normal\" reads as a judgement about the other choice.","required":["tier","upgrade_available","reason","amount_minor","currency","interval"],"additionalProperties":false,"properties":{"tier":{"type":"string"},"upgrade_available":{"type":"boolean"},"reason":{"type":"string","description":"Why not, when `upgrade_available` is false. Empty when it is true."},"amount_minor":{"type":"integer","format":"int64","description":"Our price for the upgrade, from the provider's live quote for **this** machine — not from a published percentage. The two disagree and the quote is what we pay."},"currency":{"type":"string","minLength":3,"maxLength":3},"interval":{"type":"string","enum":["monthly","yearly"]},"vendor_cost_minor":{"type":"integer","format":"int64","description":"STAFF ONLY."}}},"ComputeCatalogue":{"type":"object","description":"Everything the server order screen is built from. ⛔ Nothing about a provider, a zone, a size or an optimisation may be authored in a client: a combination a client invented is one the provider refuses *inside provisioning*, where all the customer sees is a machine that failed.","required":["data","tiers","can_order"],"additionalProperties":false,"properties":{"data":{"type":"array","description":"The platforms a machine can be placed on.","items":{"$ref":"#/components/schemas/ComputeProvider"}},"tiers":{"type":"array","description":"The tiers we sell on this range.","items":{"$ref":"#/components/schemas/ComputeTier"}},"can_order":{"type":"boolean","description":"Whether anything here can actually be ordered — any orderable tier, or any provider size. It exists so a screen can say *\"this cannot be ordered yet\"* instead of rendering a button that `422`s."},"available_targets":{"type":"array","description":"The compute ranges that have a provider account behind them — derived from the platform's provider-account pool, never listed by hand. An order screen offers only these. A range NOT in this list is answered with empty `data` and `can_order: false` rather than a `503`, so the screen is never left with nothing to switch to (W43-45).","items":{"$ref":"#/components/schemas/DeployTarget"}}}},"ComputeCluster":{"type":"object","description":"A k3s cluster on the organisation's own pay-by-the-hour machines (W43-49, `docs/689`). Every version and health figure is the cluster's own answer, read from it.","required":["id","name","deploy_target","zone","plan_code","image","worker_count","install_argocd","deploy_sample_app","status","message","kubernetes_version","argocd_version","ready_nodes","sample_app_health","api_address","network_id","nodes","created_at","ready_at"],"additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"name":{"type":"string"},"deploy_target":{"type":"string"},"zone":{"type":"string"},"plan_code":{"type":"string"},"image":{"type":"string"},"worker_count":{"type":"integer"},"install_argocd":{"type":"boolean"},"deploy_sample_app":{"type":"boolean"},"status":{"type":"string","enum":["pending","provisioning","bootstrapping","ready","failed","terminating","terminated"]},"message":{"type":"string"},"kubernetes_version":{"type":"string"},"argocd_version":{"type":"string"},"ready_nodes":{"type":"integer"},"sample_app_health":{"type":"string","description":"Argo CD's `sync/health` for the sample application, e.g. `Synced/Healthy`."},"api_address":{"type":"string","description":"The Kubernetes API's public address (port 6443)."},"network_id":{"type":"string"},"nodes":{"type":"array","items":{"$ref":"#/components/schemas/ComputeServer"}},"created_at":{"type":"string","format":"date-time"},"ready_at":{"type":["string","null"],"format":"date-time"}}},"ComputeClusterList":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ComputeCluster"}}}},"ComputeClusterQuote":{"type":"object","required":["nodes","node_monthly_price_minor","monthly_price_minor","currency","required_minor"],"additionalProperties":false,"properties":{"nodes":{"type":"integer"},"node_monthly_price_minor":{"type":"integer"},"monthly_price_minor":{"type":"integer","description":"Every machine for a whole month — the most a calendar month can cost."},"currency":{"type":"string"},"required_minor":{"type":"integer","description":"The balance needed before anything is built."}}},"ComputeClusterQuoteRequest":{"type":"object","required":["zone","plan_code","worker_count"],"additionalProperties":false,"properties":{"zone":{"type":"string","maxLength":64},"plan_code":{"type":"string","maxLength":64},"worker_count":{"type":"integer","minimum":0,"maximum":10},"org_id":{"oneOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]}}},"ComputeCreateClusterRequest":{"type":"object","required":["name","zone","plan_code","image","worker_count"],"additionalProperties":false,"properties":{"name":{"type":"string","maxLength":40,"pattern":"^[A-Za-z0-9-]+$"},"zone":{"type":"string","maxLength":64},"plan_code":{"type":"string","maxLength":64},"image":{"type":"string","maxLength":64},"worker_count":{"type":"integer","minimum":0,"maximum":10},"install_argocd":{"type":"boolean","default":true},"deploy_sample_app":{"type":"boolean","default":false,"description":"Deploy Argo CD's example application through Argo CD. Needs Argo CD."},"ssh_keys":{"type":"array","maxItems":25,"items":{"type":"string","maxLength":64},"description":"The ids of the authorised keys every node gets, from `listComputeSshKeys`. Every id must be one of the ordering organisation's own registered keys (`listComputeSshKeys` for that org); any other id — another organisation's key, a key name, an unregistered vendor id — is refused `422` `refusal.compute.sshKeyNotYours` and nothing is built."},"org_id":{"oneOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]}}},"ComputeCreateNetworkRequest":{"type":"object","required":["name","ip_range","server_id"],"additionalProperties":false,"properties":{"name":{"type":"string","maxLength":64},"ip_range":{"type":"string","maxLength":43,"description":"A private IPv4 block, like `10.10.0.0/16`."},"server_id":{"$ref":"#/components/schemas/Uuid"}}},"ComputeEligibility":{"type":"object","description":"Whether an organisation may buy a machine on our own infrastructure, and what is missing if not.","required":["state","blockers","email_verified","card_verified","has_owner","id_check_required","id_document_uploaded","standing","limits","usage","may_order","legal_name","country","company_number","abuse_contact_email","intended_use","rejection_reason","submitted_at","reviewed_at"],"additionalProperties":false,"properties":{"state":{"type":"string","enum":["not_requested","pending","verified","rejected"],"description":"The ID check's own state. ⛔ Four states, not a boolean: `not_requested` and `rejected` differ completely — one is \"tell us who you are\" (only when `id_check_required`), the other is \"we have decided, and here is why\"."},"blockers":{"type":"array","description":"What stands between the account and a server, in the order it can act on them. Empty exactly when `may_order` is true.","items":{"type":"string","enum":["no_owner","email_unverified","card_required","id_check_required","id_check_pending","id_check_rejected"]}},"email_verified":{"type":"boolean","description":"Whether an owner of the organisation has a verified email address."},"card_verified":{"type":"boolean","description":"Whether a card confirmed with the issuer (a succeeded setup) is on the account, in date and chargeable. A PayPal agreement or a crypto balance is not a card."},"has_owner":{"type":"boolean","description":"Whether the organisation has an owner membership at all. A platform or reseller-created organisation can have none, and the first-server steps are about an owner — so `no_owner` is its own blocker rather than a confusing \"confirm your email\"."},"id_check_required":{"type":"boolean","description":"Whether an ID check stands between the account and its next server. False for almost every account — it is raised only by a fraud signal or by staff."},"id_document_uploaded":{"type":"boolean","description":"Whether an identity document has been registered for the check."},"standing":{"type":"string","enum":["new","established","custom"],"description":"Which limits apply. `new` until the account is 30 days old and has paid for something; `custom` when staff set this account's limits."},"limits":{"$ref":"#/components/schemas/ComputeLimits"},"usage":{"$ref":"#/components/schemas/ComputeUsage"},"may_order":{"type":"boolean","description":"True exactly when `blockers` is empty. Read this rather than re-deriving it."},"legal_name":{"type":"string","description":"The legal name of whoever is responsible for the machines."},"country":{"type":"string","description":"ISO-3166-1 alpha-2 country of the person or the incorporation."},"company_number":{"type":"string","description":"Company registration number, or `\"\"` for an individual — a real answer."},"abuse_contact_email":{"type":"string","description":"A monitored address an abuse report can be forwarded to and answered from. We are the account holder of record, so a complaint reaches us first and has to reach the customer within hours."},"intended_use":{"type":"string","description":"What the customer says the machines are for, in their own words."},"rejection_reason":{"type":"string","description":"Shown to the customer **verbatim** when `state` is `rejected`."},"submitted_at":{"type":"string","format":"date-time","nullable":true},"reviewed_at":{"type":"string","format":"date-time","nullable":true}}},"ComputeEligibilityRequest":{"type":"object","required":["legal_name","country","abuse_contact_email"],"additionalProperties":false,"properties":{"legal_name":{"type":"string","minLength":1,"maxLength":300},"country":{"type":"string","minLength":2,"maxLength":2},"abuse_contact_email":{"type":"string","format":"email","maxLength":254},"company_number":{"type":"string","maxLength":64,"default":""},"intended_use":{"type":"string","maxLength":2000,"default":""}}},"ComputeFirewallRule":{"type":"object","description":"One inbound or outbound rule.\n\n⛔ `sources` is a list of CIDRs, never one string. A rule permitting a single address and one permitting the whole internet differ only in that field, and a client that joined them for display would make `0.0.0.0/0` look like a typo.","required":["direction","protocol","port","sources","description"],"additionalProperties":false,"properties":{"direction":{"type":"string","enum":["in","out"],"description":"Whether the rule governs traffic arriving or leaving."},"protocol":{"type":"string","enum":["tcp","udp","icmp","esp","gre"],"description":"The protocol the rule matches."},"port":{"type":"string","description":"A port or range (`\"22\"`, `\"8000-9000\"`). ⛔ Blank is valid and meaningful — ICMP, ESP and GRE have no ports, and sending one for them is a provider error rather than a harmless extra."},"sources":{"type":"array","items":{"type":"string"},"description":"The CIDRs the rule applies to."},"description":{"type":"string","description":"What the rule is for","or `\"\"`.":null}}},"ComputeFloatingIp":{"type":"object","description":"A floating address held on one of the organisation's machines (W43-49, `docs/689`).","required":["id","server_id","family","status","address","home_zone","monthly_price_minor","currency","message","created_at"],"additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"server_id":{"$ref":"#/components/schemas/Uuid"},"family":{"type":"string","enum":["ipv4","ipv6"]},"status":{"type":"string","enum":["pending","active","released","failed"]},"address":{"type":"string","description":"The address, or the routed /64 for IPv6. Blank until reserved."},"home_zone":{"type":"string"},"monthly_price_minor":{"type":"integer","description":"What the customer pays per month, in minor units of `currency`."},"currency":{"type":"string"},"message":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"ComputeFloatingIpList":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ComputeFloatingIp"}}}},"ComputeFloatingIpQuote":{"type":"object","required":["family","monthly_price_minor","currency"],"additionalProperties":false,"properties":{"family":{"type":"string"},"monthly_price_minor":{"type":"integer"},"currency":{"type":"string"}}},"ComputeFloatingIpRequest":{"type":"object","required":["family"],"additionalProperties":false,"properties":{"family":{"type":"string","enum":["ipv4","ipv6"]}}},"ComputeIdDocumentUpload":{"type":"object","required":["upload"],"additionalProperties":false,"properties":{"upload":{"type":"object","required":["url","method","headers","expires_at"],"additionalProperties":false,"properties":{"url":{"type":"string","description":"A credential until `expires_at`. Never log it."},"method":{"type":"string"},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Headers the upload must send for the signature to verify."},"expires_at":{"type":"string","format":"date-time"}}}}},"ComputeIdDocumentUploadRequest":{"type":"object","required":["content_type","size_bytes"],"additionalProperties":false,"properties":{"content_type":{"type":"string","enum":["image/jpeg","image/png","application/pdf"]},"size_bytes":{"type":"integer","minimum":1,"maximum":10485760}}},"ComputeImage":{"type":"object","description":"One thing a machine can be **built from** — an operating system or a ready-to-run application.\n\n⛔ Not an entry in `ComputeProvider.optimisations`, and the difference is not cosmetic: an optimisation is a profile applied to a stack the provider already installed, and an image is the disk the machine boots.","required":["id","label","kind","architecture","description","os_family"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"The provider's own token (`ubuntu-24.04`, `wordpress`) — what an order sends as `image`. ⛔ Match on this and never on `label`: the label is punctuated prose and changes without notice."},"label":{"type":"string","description":"The image's display name, e.g. \"Ubuntu 24.04\"."},"kind":{"type":"string","enum":["os","app"],"description":"A closed pair so a picker can group \"operating systems\" and \"one-click apps\" without deriving the grouping from a name — which is how `wordpress` ends up filed under Ubuntu."},"architecture":{"type":"string","description":"`x86` or `arm` as the provider states it; empty means it stated none, which is a real answer for a provider with one architecture and must **not** read as \"either\".\n\n⛔⛔ **Filter the picker on this.** The provider publishes x86 and ARM images as separate entries with the **same name**, and building an ARM machine from an x86 image is refused *after* the customer has paid."},"description":{"type":"string","description":"The provider's own longer description, where it gives one."},"os_family":{"type":"string","enum":["","windows"],"description":"`windows` for a Windows Server image (reached over Remote Desktop with the Administrator password, shown by `revealComputeServerAdministratorPassword`; no SSH key needed); `\"\"` otherwise. Must match the chosen size's `os_family`."},"os_slug":{"type":"string","description":"The catalogue slug for this image (`ubuntu-24.04`, `alma-9`), the token an add-on's `supported_images` lists. Equal to `id` on the cloud range; on a dedicated server `id` is the supplier's distribution name (\"Ubuntu 24.04 LTS base\"). ⛔ Match an add-on's `supported_images` against THIS, never `id`, or no add-on that lists systems can be chosen on a dedicated server. An image with no known slug (an app image) returns `id` unchanged and matches nothing."}}},"ComputeInstallMedia":{"type":"object","required":["id","name","architecture"],"additionalProperties":false,"properties":{"id":{"type":"string"},"name":{"type":"string","description":"The disc's human name","e.g. \"Ubuntu 24.04\".":null},"architecture":{"type":"string","description":"`x86` or `arm`."}}},"ComputeLimits":{"type":"object","description":"What one account may run at once on our cloud.","required":["max_servers","max_vcpus","max_monthly_spend_minor","currency"],"additionalProperties":false,"properties":{"max_servers":{"type":"integer"},"max_vcpus":{"type":"integer"},"max_monthly_spend_minor":{"type":"integer","description":"Committed monthly spend across every machine, in `currency` minor units."},"currency":{"type":"string","description":"ISO-4217."}}},"ComputeLineConfig":{"type":"object","description":"How one machine on a `compute_server` cart line is built.\n\nThe values are **not trusted from here**: the engine re-resolves the whole order against the live vendor before the line is priced, so a zone the provider does not have, a size it no longer offers, or a field it rejects is a 422 at add-to-cart — while the customer can still fix it, and before any money moves. That ordering is the point of the schema: the same refusals used to be reachable only from inside fulfilment, i.e. after the card had been captured.","required":["name","zone"],"properties":{"name":{"type":"string","maxLength":64,"description":"What the customer calls the machine. Theirs, shown back verbatim, and never sent to the vendor — on the managed platform a machine's name is the platform's own row id."},"plan_code":{"type":"string","maxLength":64,"description":"The catalogue plan (`cloud_20i_medium`) — **our** product, which is what carries a price. The vendor's spec token is resolved from it and is never accepted from a client.\n\n⛔ **One of `plan_code` or `spec` is required, and `plan_code` is authoritative**: if it is sent and names no plan we sell, the line is refused rather than falling back to `spec`. A configurator's spec ids are our plan codes only while the provider publishes no spec list of its own (`spec_source: \"catalogue\"`) — once it publishes one they become vendor tokens, so a client must send `spec` and add `plan_code` only when it genuinely resolved a catalogue tier, never as a copy of the size id."},"zone":{"type":"string","maxLength":64,"description":"The data centre. ⛔ Zone counts are wildly asymmetric between providers (Zinn® Cloud has 8 where AWS and GCP have dozens), so a picker must read the catalogue rather than imply parity."},"provider":{"type":"string","maxLength":32,"description":"`20i`, `aws` or `gcp` — ⛔ NOT `20icloud`. Optional: the engine picks the plan's only provider when there is one."},"spec":{"type":"string","maxLength":64,"description":"A size taken straight from the vendor's own published list, when the configurator showed one. Confirmed against that list — never used to invent a token, which is a guess that would only be contradicted after the charge."},"optimisation":{"type":"string","maxLength":64,"description":"The stack to tune for (PHP, WordPress, Magento, …)."},"disk":{"type":"string","maxLength":32,"description":"AWS/GCP only. ⛔ Zinn® Cloud derives disk from the machine size and **rejects** an explicit value, so sending one to it is refused with a sentence."},"bandwidth":{"type":"string","maxLength":32,"description":"AWS/GCP only, and pay-as-you-go rather than an allowance — a provisioning input, never a quota anything may meter against."},"image":{"type":"string","maxLength":64,"description":"The operating system or one-click application the machine boots, as `getComputeCatalogue` reported it in `ComputeProvider.images`.\n\n⛔ Required — `422` at add-to-cart — on any range that publishes images, and meaningless on one that does not. ⛔⛔ Check the image's `architecture` against the chosen size's: ARM and x86 images are separate entries with the **same name**, and a mismatch is refused *after* the customer has paid."},"ssh_keys":{"type":"array","maxItems":25,"items":{"type":"string","maxLength":64},"description":"The ids of the authorised keys to install, from `listComputeSshKeys`. Every id must be one of the ordering organisation's own registered keys (`listComputeSshKeys` for that org); any other id — another organisation's key, a key name, an unregistered vendor id — is refused `422` `refusal.compute.sshKeyNotYours` and nothing is built."},"blueprint":{"type":"string","enum":["","bare","docker","k3s","k3s_argocd"],"description":"W43-49 (`docs/689`). The software stack installed at first boot on a Zinn® Cloud machine. Refused at add-to-cart on a range whose first boot we do not write."},"managed_care":{"type":"boolean","description":"SERVERCARE-r1: order the machine Zinn® Managed (patching, monitoring, on-call) from day one (absent means self-managed). Priced from the live `managed` add-on row and added to the machine's line; refused at add-to-cart when the range or currency cannot take it. Coexists with `add_on`. Refused on a website's own server (`own_vps_site_id`) with `refusal.ownVps.managedCareNotOnMove`, at add-to-cart and again at checkout: that server is already run by us."},"add_on":{"type":"string","maxLength":64,"description":"The add-on to install while the machine is built — `cloudlinux`, `plesk_web_pro`, `plesk_web_host`, or omitted for a bare machine (W22-X, `docs/154`).\n\n⛔⛔ **This is the ONLY way a cloud-init add-on can be bought.** The provider runs `user_data` once at first boot and `POST /servers/{id}/rebuild` takes no user data, so adding CloudLinux or Plesk to a machine that already exists means rebuilding it and erasing the disk. The per-server endpoint refuses one for exactly that reason; this field is where the choice is made.\n\n⛔ Re-validated against live stock at checkout rather than trusted from the order screen's render: a pooled serial can be taken by another customer in between, and selling from a stale catalogue is how somebody pays for something no automation can deliver.\n\n⛔⛔ **Required on the Zinn® Private Cloud range, and the refusal is a security control.** That provider answers a build with no key by returning a **root password** in its response body — a credential that would then exist in our process, our logs and our exception reports. Refusing at add-to-cart is how it never exists."}}},"ComputeNetworkAttachment":{"type":"object","required":["network_id","ip"],"additionalProperties":false,"properties":{"network_id":{"$ref":"#/components/schemas/Uuid"},"ip":{"type":"string"}}},"ComputeOffer":{"type":"object","additionalProperties":false,"required":["plan_code","provider","spec","zone","city","label","ram_gb","disk_gb","monthly_minor","setup_minor","currency"],"properties":{"plan_code":{"type":"string","maxLength":64,"description":"The plan to order it under."},"provider":{"type":"string","maxLength":64,"description":"The platform id to send as the order's `provider`."},"spec":{"type":"string","maxLength":64,"description":"The offer's machine token."},"zone":{"type":"string","maxLength":64},"city":{"type":"string","maxLength":128},"label":{"type":"string","maxLength":512,"description":"The machine's own hardware lines."},"ram_gb":{"type":["integer","null"],"minimum":0},"disk_gb":{"type":["integer","null"],"minimum":0},"monthly_minor":{"type":"integer","minimum":0,"description":"Our monthly price, integer minor units of `currency`."},"setup_minor":{"type":"integer","minimum":0,"description":"The one-off setup fee, passed on at cost, minor units."},"currency":{"type":"string","minLength":3,"maxLength":3}}},"ComputeOfferList":{"type":"object","additionalProperties":false,"required":["data","lock_seconds"],"properties":{"data":{"type":"array","maxItems":10000,"items":{"$ref":"#/components/schemas/ComputeOffer"}},"lock_seconds":{"type":"integer","minimum":0,"description":"How long a basket holds an offer's quoted figure."}}},"ComputePowerRequest":{"type":"object","description":"What to do to the machine.","required":["action"],"additionalProperties":false,"properties":{"action":{"type":"string","enum":["start","stop","reboot"],"description":"Vendor-neutral by design — no provider's verb. The response carries the **transitional** power state, never the destination."}}},"ComputePrivateNetwork":{"type":"object","required":["id","name","ip_range","network_zone","status","cluster_id","members","created_at"],"additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"name":{"type":"string"},"ip_range":{"type":"string"},"network_zone":{"type":"string"},"status":{"type":"string","enum":["pending","active","deleted","failed"]},"cluster_id":{"type":"string","description":"The cluster that owns this network, or blank."},"members":{"type":"array","items":{"type":"object","required":["server_id","name","ip"],"additionalProperties":false,"properties":{"server_id":{"$ref":"#/components/schemas/Uuid"},"name":{"type":"string"},"ip":{"type":"string"}}}},"created_at":{"type":"string","format":"date-time"}}},"ComputePrivateNetworkList":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ComputePrivateNetwork"}}}},"ComputeProvider":{"type":"object","description":"One platform a machine can be placed on, with everything the configurator needs. ⛔ Zones and sizes hang off the provider and are never flattened into one list: the counts are wildly asymmetric, and a picker that implies parity misleads the customer before they have bought anything.","required":["id","label","zones","specs","images","optimisations","supports_disk_and_bandwidth","spec_source","private_network"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Our provider id."},"label":{"type":"string","description":"The provider's display name."},"zones":{"type":"array","description":"The data centres this provider offers.","items":{"$ref":"#/components/schemas/ComputeZone"}},"specs":{"type":"array","description":"The machine sizes this provider offers. See `spec_source` for where they came from.","items":{"$ref":"#/components/schemas/ComputeSpec"}},"images":{"type":"array","description":"What a machine here can be built from. **Empty** on a provider that builds every machine from one fixed managed image — the resold managed range, where the runtime is the product and the customer has no choice to make. An empty picker is the honest render there, not a defect.","items":{"$ref":"#/components/schemas/ComputeImage"}},"optimisations":{"type":"array","description":"Stack optimisation profiles as **provider tokens**. The customer-facing label for each is the client's i18n key, never this string.","items":{"type":"string"}},"supports_disk_and_bandwidth":{"type":"boolean","description":"Whether this provider takes explicit disk and bandwidth allocations. Carried as a fact so a form can change shape, rather than offering inputs the provider will refuse *after* the customer has configured everything."},"spec_source":{"type":"string","enum":["vendor","catalogue"],"description":"`vendor` when the provider published these sizes — a size it retires must stop being offered without a release. `catalogue` when it published none and our own sold tiers filled the list, in which case a size id **is** a plan code and the engine collapses the two at order time."},"private_network":{"type":"boolean","description":"Whether a machine here can join a private network, and so be a node of a Kubernetes cluster (`POST /v1/compute/clusters`). Answered by this data centre's own supplier: the cluster form offers only these data centres, and an order or quote for any other is refused."}}},"ComputeRebuildRequest":{"type":"object","description":"⛔ **Destructive.** `confirm` must be the server's exact name. It is checked server-side, not merely in a dialog: a confirmation a client alone enforces is a confirmation an API caller skips, and this one reinstalls the operating system over everything on the disk.","required":["operating_system","confirm"],"additionalProperties":false,"properties":{"operating_system":{"type":"string","minLength":1,"maxLength":64,"description":"Which image to install, as the provider names it. ⛔ Never a string a screen or a customer composed — an OS token we guessed would wipe the machine and reinstall the wrong thing, which is why no adapter advertises rebuild until the provider's own list is read."},"confirm":{"type":"string","minLength":1,"maxLength":64,"description":"The server's `name`, typed by the customer. Compared **case-sensitively** after surrounding whitespace and nothing else, so a client that forgave more would enable the button on input the engine then refuses."}}},"ComputeRegion":{"type":"object","description":"One region a Zinn® Cloud machine can be bought in. Never names a supplier.","required":["slug","country","continent","zone","provider"],"properties":{"slug":{"type":"string","description":"Our identifier for the city, e.g. `nuremberg`. The client translates it."},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code."},"continent":{"type":"string"},"zone":{"type":"string","description":"The data-centre token an order sends back."},"provider":{"type":"string","description":"The provider id an order sends back."}}},"ComputeRegionList":{"type":"object","required":["data"],"properties":{"closest":{"description":"The available region nearest the customer (`country`, `CF-IPCountry`, else the organisation's stored location), or `null` when that is unknown or nothing is available.","oneOf":[{"$ref":"#/components/schemas/ComputeRegionOption"},{"type":"null"}]},"data":{"type":"array","items":{"$ref":"#/components/schemas/ComputeRegion"}}}},"ComputeRegionOption":{"type":"object","required":["slug","country","continent","zone","provider","distance_km","latency_ms"],"properties":{"slug":{"type":"string"},"country":{"type":"string"},"continent":{"type":"string"},"zone":{"type":"string"},"provider":{"type":"string"},"distance_km":{"type":["integer","null"],"description":"Great-circle distance from the place asked for; `0` for an exact match, `null` for a whole country."},"latency_ms":{"type":["integer","null"],"description":"An estimated round trip from distance alone — never a measurement."}}},"ComputeRegionPlace":{"type":"object","required":["slug","country","continent"],"properties":{"slug":{"type":"string"},"country":{"type":"string"},"continent":{"type":"string"}}},"ComputeRegionResolution":{"type":"object","required":["status","requested","understood","match","alternatives","requires_confirmation"],"properties":{"status":{"type":"string","enum":["exact","nearest","country","unrecognised"]},"requested":{"type":"string","description":"The text as it was sent."},"understood":{"description":"The place the text was understood as, when it was.","oneOf":[{"$ref":"#/components/schemas/ComputeRegionPlace"},{"type":"null"}]},"match":{"description":"The region to build in — set only when `status` is `exact`.","oneOf":[{"$ref":"#/components/schemas/ComputeRegionOption"},{"type":"null"}]},"alternatives":{"type":"array","items":{"$ref":"#/components/schemas/ComputeRegionOption"}},"requires_confirmation":{"type":"boolean","description":"`true` for everything but `exact`: the customer must choose."}}},"ComputeRegionResolutionEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ComputeRegionResolution"}}},"ComputeRenewRequest":{"type":"object","description":"How much longer to buy.","required":["term_months"],"additionalProperties":false,"properties":{"term_months":{"type":"integer","minimum":1,"maximum":36,"description":"Months to add to the existing term. Outside 1…36 is refused `422` before the provider is called.","example":12}}},"ComputeResizeQuote":{"type":"object","description":"What a resize would cost, as the provider stated it. ⛔ `amount` is the provider's own **string**, unparsed, and there is deliberately **no currency field**: inventing one to fit a money type would put a number in front of a customer in the wrong currency (§2.8).","required":["spec","amount","detail","plan_code","price_minor","currency","interval"],"additionalProperties":false,"properties":{"spec":{"type":"string","description":"The size the figure is for."},"plan_code":{"type":"string","description":"The plan quoted, on an own-account range. `\"\"` on the resold range."},"price_minor":{"type":"integer","nullable":true,"description":"⛔ D24975 (W43-48). OUR price for the plan, in minor units, in the machine's own data centre at its own cadence. On an own-account range this is the only figure; `amount` and `detail` are blank, because the provider's figure there is our cost. `null` on the resold range."},"currency":{"type":"string","description":"ISO currency of `price_minor`, or `\"\"`."},"interval":{"type":"string","description":"`monthly` or `annual` — the machine's billing cadence — or `\"\"`."},"amount":{"type":"string","description":"The provider's figure, verbatim. Rendered as the provider stated it and labelled as the provider's estimate, never reformatted."},"detail":{"type":"string","description":"Whatever else the provider said about the change, or `\"\"`. Blank is common and is not an error."}}},"ComputeResizeRequest":{"type":"object","description":"The machine size to move to. Send `plan_code` on an own-account range (W43-48): several plans are built on one machine type there, so a type alone is refused when it is ambiguous. At least one of the two is required.","additionalProperties":false,"properties":{"spec":{"type":"string","maxLength":64,"description":"The target size, as `getComputeCatalogue` reported it."},"plan_code":{"type":"string","maxLength":64,"description":"The plan to move to, as `getComputeCatalogue`'s `tiers[].plan_code`."}}},"ComputeReverseDnsList":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ComputeReverseDnsRecord"}}}},"ComputeReverseDnsRecord":{"type":"object","description":"One public address and what its PTR currently says.\n\n⛔⛔ **A blank `hostname` means the address has NO PTR — it does not mean \"the supplier's default\".** Measured across every machine on our own account: each IPv4 carries a supplier default and each IPv6 carries nothing at all. A screen that rendered the two alike would tell a customer their IPv6 leaks when it does not, and hide the address that does.","required":["ip","hostname","leaks_supplier"],"additionalProperties":false,"properties":{"ip":{"type":"string","description":"The public address, IPv4 or IPv6, as the provider states it."},"hostname":{"type":"string","description":"The current PTR, or `\"\"` when the address has none."},"leaks_supplier":{"type":"boolean","description":"Whether this PTR still names the machine's **supplier** rather than the customer.\n\n⛔ Computed by the engine, never by pattern-matching in a client: the shape of a supplier default is a fact about the supplier, and a client-side regex goes stale in silence the day it changes — leaving a leaking machine rendered as clean."}}},"ComputeReverseDnsRequest":{"type":"object","required":["ip"],"additionalProperties":false,"properties":{"ip":{"type":"string","maxLength":64,"description":"Which address to set. ⛔ Required and never inferred: a machine has an IPv4 and an IPv6 with different default states, so \"set the PTR of this server\" is not a well-formed request. An address the machine does not hold is `422`."},"hostname":{"type":"string","maxLength":253,"default":"","description":"The name to point at. **Empty resets the address to the provider's own default**, which is a real thing to want and is not the same as leaving it alone.\n\n⛔ A non-empty name must already resolve forward to this address, and that is checked before anything is written. Receiving mail servers check forward-confirmed reverse DNS, so a PTR whose name does not point back looks configured and still fails delivery."}}},"ComputeServer":{"type":"object","description":"A machine we bought for an organisation. ⛔ Resolved from **our** rows, never from the provider's listing, which is the whole reseller account.","required":["id","image","suspended","suspension_reason","name","deploy_target","plan_code","provider","spec","zone","status","message","vendor_status","power_state","addresses","optimisation","term_months","renews_at","created_at","operable","capabilities","billing","login_user","blueprint","cluster_id","cluster_role"],"additionalProperties":false,"properties":{"management_mode":{"type":"string","enum":["self_managed","zinn_managed","zinn_managed_paused"],"description":"SERVERCARE-r1: who looks after this machine (`engine.compute.care`). `zinn_managed_paused` = care add-on held while the account is not in good standing (§2.46)."},"id":{"allOf":[{"$ref":"#/components/schemas/Uuid"}],"description":"**Ours**, and also the provisioning workflow's id and the machine's name at the provider — which is what makes the whole purchase path idempotent."},"name":{"type":"string","description":"What the customer called it. ⛔ At the provider a machine's name is its row id; confusing the two is a cross-tenant defect, so this is the customer's string and nothing else."},"deploy_target":{"type":"string","description":"Which compute range the machine belongs to."},"plan_code":{"type":"string","description":"The tier it was bought on, or `\"\"` when it was ordered by size alone."},"provider":{"type":"string","description":"Our provider id."},"spec":{"type":"string","description":"The machine size it currently runs."},"zone":{"type":"string","description":"The data centre it runs in."},"status":{"type":"string","enum":["pending","provisioning","active","failed","suspended","terminated","resizing","terminating"],"description":"How far the order got — **ours**, and a different fact from `power_state`. `pending` is a row with nothing bought and nothing charged; `failed` is the state whose `message` is the only thing on the screen worth reading. ⛔ Deliberately separate from `vendor_status`: rounding the provider's word into this enum would mean an unrecognised state silently became `active`, and `active` is what unlocks every control."},"message":{"type":"string","description":"Why the order failed, as an English sentence for staff, support and SDK readers. Blank unless `failed`. A client renders `message_code` instead when it is set."},"message_code":{"type":["string","null"],"enum":["build_retry_held","build_failed_no_ticket","build_failed_ticket",null],"description":"NIGHTFIX1114 FAILEDSRV: the half of `message` a client renders, as a stable code it translates (the platform ships in 58 languages; `message` is English). `build_failed_ticket` (we opened support ticket `message_params.ticket_id`), `build_failed_no_ticket` (the ticket could not be opened), `build_retry_held` (a retried rebuild failed again and we are on it). Null when `message` is blank or not one of these; the client then shows `message`."},"message_params":{"type":"object","additionalProperties":{"type":"string"},"description":"The values `message_code` interpolates; `ticket_id` for `build_failed_ticket`, otherwise empty."},"vendor_status":{"type":"string","description":"The provider's own word, verbatim and unrounded. Staff-facing detail; a customer client renders `status` and never this."},"power_state":{"type":"string","enum":["unknown","on","off","starting","stopping","rebooting"],"description":"What the machine is doing right now. ⛔ **Six values, not two, and the four extra ones are the point: a machine mid-transition is not \"on\".** `unknown` is the honest answer when the provider stated none and is never collapsed into `off`. A client polls on the three transitional values."},"addresses":{"type":"array","description":"Public addresses **if the provider states them**. Empty means *not stated*, never \"none\" — a machine rendered as having no address reads as broken.","items":{"type":"string"}},"optimisation":{"type":"string","description":"The stack optimisation profile it was built with, or `\"\"` for none."},"term_months":{"type":["integer","null"],"description":"The term it was bought on, or null when the provider states none."},"renews_at":{"type":["string","null"],"description":"⛔ **Always null today, and honestly so**: the provider publishes no renewal date, and one computed from the order plus the term would be our arithmetic rendered as the provider's fact."},"created_at":{"type":"string","description":"When the row was created, or `\"\"` when not stated."},"terminated_at":{"type":["string","null"],"format":"date-time","description":"When the machine was terminated; null while it exists. Owner decision D11 (2026-10-06): a terminated server leaves the servers list and the last five from the past 7 days appear in a collapsed \"recently deleted\" panel."},"operable":{"type":"boolean","description":"Whether the customer may act on this machine — power, resize, renew, rebuild. ⛔ Read rather than re-derived from `status`: the engine refuses every one of those on anything but `active`, **and on anything suspended**, so a screen computing its own answer would eventually offer a control the engine refuses."},"image":{"type":"string","description":"The provider image the machine was built from. Blank on the resold range, which installs one managed image and offers no choice."},"architecture":{"type":"string","enum":["x86","arm"],"description":"s1014 VPS-RANGES r15. The CPU family the machine was built on. An `arm` machine takes only the add-ons proven on Arm (`AddOnOffer.arm_supported_images`)."},"suspended":{"type":"boolean","description":"⛔⛔ **Whether WE stopped it, which is not the same fact as `power_state`.** A stopped machine is the customer's own choice and they may start it again; a suspended one is ours and every control refuses until an operator lifts it. A screen rendering only the power state would show a Start button that always fails, with no explanation available to the person pressing it."},"suspension_reason":{"type":"string","description":"Why, verbatim, so the customer reads the same sentence support wrote. Blank when the machine is in good standing."},"capabilities":{"type":"array","items":{"type":"string"},"description":"⭐⭐ **What this machine's provider can actually do** — capability tokens such as `compute:snapshots`, `compute:console`, `compute:firewall`, `compute:backups_manage` and `compute:limits`.\n\nThe two ranges are not alike and a client must not assume they are. The resold range exposes no backup verb, no snapshot verb, no firewall and no console; our own cloud exposes all four. A screen renders each optional control only when its token is present, which is what lets one server page serve both without offering a button that cannot work.\n\n⛔ An **empty array is a real answer**, not an error: we could not establish what this range supports, and every optional control should hide. It is never a failure of the request — one machine whose credential will not resolve must not take a customer's whole fleet listing down with it."},"billing":{"$ref":"#/components/schemas/ComputeServerBilling"},"login_user":{"type":"string","description":"The account to sign in as (W43-49, `docs/689`). `admin` — key-only, passwordless `sudo`, root login refused — on a Zinn® Cloud machine built under the access model; `root` on one built before it."},"blueprint":{"type":"string","enum":["","docker","k3s","k3s_argocd"],"description":"The software stack installed at first boot. Blank for none."},"cluster_id":{"type":"string","description":"The cluster this machine is a node of, or blank."},"cluster_role":{"type":"string","enum":["","server","agent"]}}},"ComputeServerBackups":{"type":"object","description":"A machine's automatic backup arrangement, as its provider actually offers it.\n\n⛔⛔ **`manageable` is the field that stops this lying, and it is not the same as `enabled`.** On the resold range the tier is readable and **not writable**: the provider states which Timeline tier the machine is on and exposes no reseller-API verb to change it. On our own cloud range it is a switch we own. A client that ignored this would put a working control in front of half the estate and a broken one in front of the other half.","required":["enabled","manageable","tier","window","retained","price_minor","price_currency"],"additionalProperties":false,"properties":{"enabled":{"type":"boolean","description":"Whether the provider takes automatic backups of this machine."},"manageable":{"type":"boolean","description":"Whether **we** can change that through an API. `false` means the customer has a real backup arrangement we can describe and cannot alter — render a statement, not a switch."},"tier":{"type":"string","description":"The provider's own name for the tier, verbatim and untranslated, or `\"\"`. ⛔ Never round it to a boolean: \"which tier am I on\" and \"are backups on\" are different questions, and an upgrade offer depends on the first."},"window":{"type":"string","description":"The daily window backups are taken in, as stated (`\"22-02\"`), or `\"\"`."},"retained":{"type":"integer","nullable":true,"description":"How many restore points are kept. `null` when unknown — never `0` as a guess, because \"we keep none\" is a different promise."},"price_minor":{"type":"integer","nullable":true,"description":"What **we** charge per month to keep this on, in integer minor units of `price_currency`.\n\n⛔⛔ `null` means *we cannot state a price for this machine* — the truth on the resold range, where automatic backups are not something we sell separately — and it is **not** the same as free. A client must render the figure when it is present and say plainly that it cannot quote when it is `null`; showing `0` or omitting the line both tell the customer their bill will not change, which is a promise this field does not make."},"price_currency":{"type":"string","description":"ISO-4217 code for `price_minor`, or `\"\"` exactly when that is `null`."}}},"ComputeServerBilling":{"type":"object","description":"How a machine is paid for (W43-47, `docs/687`). `term` machines are charged ahead by a per-machine subscription. `metered` machines are charged per started hour from the account balance, at the rate pinned when they were ordered, and a calendar month never costs more than `monthly_cap_minor`.","required":["mode","hourly_rate_minor","monthly_cap_minor","currency","hold"],"additionalProperties":false,"properties":{"mode":{"type":"string","enum":["term","metered"]},"hourly_rate_minor":{"type":["string","null"],"pattern":"^[0-9]+\\.[0-9]{6}$","description":"The hourly rate in minor units as a DECIMAL STRING with six places (`\"0.683562\"`). An hour costs a fraction of a cent, which an integer cannot carry and a float would round (§2.8). `null` on a term machine — never a zero that reads as free."},"monthly_cap_minor":{"type":["integer","null"],"description":"The pinned monthly price, which one calendar month of hours never exceeds."},"currency":{"type":"string","description":"ISO 4217 — the balance the hours are drawn from. Blank on a term machine."},"hold":{"type":"string","enum":["","funds","spend_cap","standing"],"description":"Why the meter stopped the machine, or blank. `funds` lifts within the hour of a top-up, `spend_cap` when the limit is raised or the month turns, `standing` when the account is restored. Starting a held machine is refused; stopping and deleting it are not."}}},"ComputeServerConsole":{"type":"object","description":"A short-lived out-of-band console onto a machine.\n\n⭐⭐ **Its whole value is that it works when SSH does not** — a bad firewall rule, a broken `sshd` config, a full disk, a kernel that will not boot. It is what turns \"my server is unreachable, open a ticket\" into something a customer fixes themselves.\n\n⛔⛔ **Everything here is a credential.** The URL embeds a token that reaches the machine's console as if sitting at its keyboard. It is minted per request, returned once, never stored and never logged.","required":["url","password","expires_at","kind","host","port","allowed_ips","ip_restricted"],"additionalProperties":false,"properties":{"url":{"type":"string","description":"The console address, for `kind: url` (a page a browser opens) and `kind: wss` (a WebSocket endpoint a VNC client connects to). ⛔ **Blank on a `vnc` console, and that is not a failure** — that range publishes no address at all.\n\n⛔⛔ **A `wss` console on a Zinn® Private Cloud machine is OUR address** (`wss://api.zinndigital.com/console/ws?ticket=…`, W43-49) and the ticket in it is **single-use** and lives five minutes. Open the console again for a second connection rather than reusing one — and treat the address as a credential, because it is one."},"password":{"type":"string","description":"The password the console asks for, when the provider issues one alongside the URL. `\"\"` when the URL alone authenticates."},"expires_at":{"type":"string","description":"When it stops working, ISO-8601, or `\"\"` when the provider does not say. ⛔ Blank does **not** mean \"never\" — these last minutes by design. A `url` and a `wss` console are both one-shot and expire; a `vnc` allow-list entry persists until it is cleared."},"kind":{"type":"string","enum":["url","wss","vnc"],"description":"⛔⛔ **THREE genuinely different consoles, not three spellings of one, and `wss` was missing** (W22-B, D10906). `url` is a page a browser opens. `wss` is a one-shot WebSocket endpoint for a VNC client — our own cloud returns one, it was classified `url`, and `window.open` on it produced a blank tab; there is no `https` twin to fall back on (the same URL over `https` answers 503, measured). `vnc` is a display, a password and an IP allow-list with **no address at all**, because that range expects a native client pointed at the machine.\n⛔ A client must test each member POSITIVELY. Branching `=== \"url\"` / `else` is what put a Launch button in front of a WebSocket endpoint, and it is how the next member added here would break the same screen again."},"host":{"type":"string","description":"The VNC host, for `kind: vnc`. ⛔ **May be blank, and that is a refusal rather than a gap**: where the only hostname a supplier states is its own branded one, we do not pass it on."},"port":{"type":"integer","description":"The VNC port, `0` when the provider does not state one."},"allowed_ips":{"type":"array","items":{"type":"string"},"description":"The addresses currently permitted to reach the console. ⛔⛔ **An empty list on an IP-restricted console means NOBODY may connect** — the exact opposite of the \"no restriction\" an empty list usually implies. Read `ip_restricted`; never infer from the length."},"ip_restricted":{"type":"boolean","description":"Whether the caller's address must be allow-listed before anything can connect. `false` means the credential alone is enough."}}},"ComputeServerCreateSnapshotRequest":{"type":"object","required":["description"],"additionalProperties":false,"properties":{"description":{"type":"string","maxLength":200,"description":"What to call it. Required and non-blank: an unnamed snapshot renders as a bare provider id, and a list of bare ids is one a customer cannot choose a restore point from."}}},"ComputeServerDdosProtection":{"type":"object","required":["available","enabled","price_minor","currency"],"properties":{"available":{"type":"boolean"},"enabled":{"type":"boolean"},"price_minor":{"type":["integer","null"],"description":"Monthly price while on, minor units of currency; null when not offered."},"currency":{"type":"string","minLength":3,"maxLength":3}}},"ComputeServerFirewall":{"type":"object","description":"The network filter in front of a machine.\n\n⛔⛔ **`attached: false` and `rules: []` are OPPOSITE facts and both look empty.** A machine with a firewall and no rules is fully exposed and we can act on it; a machine with no firewall at all is equally exposed and there is nothing to edit. Say \"no firewall is protecting this machine\" for the second — a warning — rather than \"0 rules\", which reads like a clean slate.","required":["id","name","attached","rules"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"The provider's firewall id","or `\"\"` when none.":null},"name":{"type":"string","description":"Its name at the provider","or `\"\"`.":null},"attached":{"type":"boolean","description":"Whether a firewall resource is actually applied to this machine."},"rules":{"type":"array","items":{"$ref":"#/components/schemas/ComputeFirewallRule"}}}},"ComputeServerHealth":{"type":"object","description":"What the machine is made of and how hard it is working, read live from the provider.\n\n⛔⛔ **Every usage figure is `null` when the provider did not answer, and it used to be `-1`.** That is **not** zero: a gauge that renders an unknown as `0%` tells the customer their machine is idle when the truth is that we could not ask. Memory and disk carry both halves of the ratio as byte counts so a screen can state \"224 MB of 1 GB\" and not only a percentage.\n\nThe change from `-1` to `null` closes a collision rather than tidying a style. `-1` is this platform's ratified sentinel for **unlimited** (#379) and the entitlement seam treats any negative integer as unlimited, so an unreadable gauge was one consumer away from meaning \"no ceiling\". The convention across every allowance on this API is now: **`null` not stated, `-1` unlimited, `>= 0` a real quantity — three states, never two.** Only `bandwidth_allowance_gb` can legitimately be `-1`: an allowance may have no ceiling, a measurement cannot.\n\nThere is deliberately **no hostname here**. The provider also states the guest hostname and the physical host it runs on; both name our supplier and neither is ever shown to a customer.","required":["cores","ram_mb","disk_gb","os_name","ram_used_bytes","ram_total_bytes","disk_used_bytes","disk_total_bytes","cpu_percent","bandwidth_used_gb","bandwidth_allowance_gb","bandwidth_overage_gb","power_state"],"additionalProperties":false,"properties":{"cores":{"type":"integer","description":"Virtual CPU cores the machine is sold with."},"ram_mb":{"type":"integer","description":"Memory the machine is sold with, in megabytes."},"disk_gb":{"type":"integer","description":"Primary disk the machine is sold with, in gigabytes."},"os_name":{"type":"string","description":"The provider's own name for the operating system image, or `\"\"`."},"ram_used_bytes":{"type":"integer","nullable":true,"description":"Memory in use, in bytes. `null` when the provider did not say."},"ram_total_bytes":{"type":"integer","nullable":true,"description":"Total memory, in bytes. `null` when the provider did not say."},"disk_used_bytes":{"type":"integer","nullable":true,"description":"Disk in use, in bytes. `null` when the provider did not say."},"disk_total_bytes":{"type":"integer","nullable":true,"description":"Total disk, in bytes. `null` when the provider did not say."},"cpu_percent":{"type":"number","format":"double","nullable":true,"description":"Processor in use, 0-100. `null` when the provider did not say.\n\n⛔ **Normalised to a real percentage at the boundary, on every range.** One provider reports every non-idle CPU class summed (it publishes no idle series); another reports a figure summed across cores, which reaches 746 on an 8-core machine and 260 on a 4-core one — measured on two live machines of different widths, because one machine cannot show the scaling. A client receives 0-100 and never has to know which range it is looking at."},"bandwidth_used_gb":{"type":"number","format":"double","nullable":true,"description":"This month's transfer, in gigabytes. `null` when not stated."},"bandwidth_allowance_gb":{"type":"number","format":"double","nullable":true,"description":"The monthly transfer allowance, in gigabytes. ⭐ **The one field on this schema that may be `-1`**, meaning the allowance has no ceiling; `null` means the provider did not state one. A client renders three branches, never two — an unlimited allowance shown as \"not stated\" is a different and wrong sentence."},"bandwidth_overage_gb":{"type":"number","format":"double","nullable":true,"description":"Transfer used beyond the allowance this month, in gigabytes, as the provider states it — the figure overage charges are computed from. `null` when not stated, and a client must render that as \"not stated\" rather than as `0`: an unknown shown as zero tells the customer they owe nothing when we simply could not ask.\n\n⛔ It is never `-1`. \"Unlimited overage\" is not a sentence, and the meter refuses a negative here rather than reading it as no ceiling."},"power_state":{"type":"string","description":"The provider's own word for the machine's state (`running`, `shut off`), verbatim and never rounded to a boolean, or `\"\"`."}}},"ComputeServerLimits":{"type":"object","description":"What a machine may HOLD — ceilings, not measurements.\n\n⭐ Separate from `ComputeServerHealth` on purpose. Health answers \"how hard is it working now\" and is never cached; a limit answers \"what did you sell me\" and changes only when the contract does.\n\n⛔ **Three states on one integer, and a client must render all three.** `null` the provider did not say, `-1` **unlimited**, `>= 0` a real count. The platform's one genuinely uncapped compute quantity lives here: the resold range answers `\"INF\"` for the number of websites a machine may hold, and until this schema existed that fact was written only in a code comment and reachable by no screen at all.","required":["packages"],"additionalProperties":false,"properties":{"packages":{"type":"integer","nullable":true,"description":"How many hosting packages (websites) may live on the machine. `null` not stated, `-1` unlimited, otherwise the count."}}},"ComputeServerList":{"type":"object","description":"The servers in scope.","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","description":"The machines, across every organisation the caller can read.","items":{"$ref":"#/components/schemas/ComputeServer"}}}},"ComputeServerMetricsHistory":{"type":"object","description":"How hard a machine has worked across a window, as the provider stated it. Rates, never counters. Series keys: `cpu_percent` (0-100 across all cores), `network_in_bps`, `network_out_bps`, `disk_read_bps`, `disk_write_bps` (bytes per second).","required":["window","step_seconds","series"],"additionalProperties":false,"properties":{"window":{"type":"string","enum":["1h","24h","7d","30d"]},"step_seconds":{"type":"integer","description":"The spacing between samples, as the provider answered it."},"series":{"type":"array","description":"⛔ A quantity this range does not measure is absent, not empty.","items":{"type":"object","required":["key","points"],"additionalProperties":false,"properties":{"key":{"type":"string","enum":["cpu_percent","network_in_bps","network_out_bps","disk_read_bps","disk_write_bps"]},"points":{"type":"array","items":{"type":"object","required":["at","value"],"additionalProperties":false,"properties":{"at":{"type":"integer","description":"Unix seconds, UTC."},"value":{"type":"number","nullable":true,"description":"⛔ `null` is a gap — the provider had no sample — never zero."}}}}}}}}},"ComputeServerOverage":{"type":"object","description":"What one machine owes for bandwidth beyond its allowance in the current metering period, and what has already been charged for it.","required":["period","overage_gb","accrued_minor","settled_minor","currency","next_threshold_minor","hard_ceiling_minor","last_known_at","charges","price_per_tb"],"additionalProperties":false,"properties":{"price_per_tb":{"type":"object","nullable":true,"required":["amount_minor","currency"],"additionalProperties":false,"description":"⚖️ Owner decision D73: what one TB beyond the included traffic costs THIS customer (their price, never our cost), for a machine on our own cloud — the rate the period is pinned to once metering has started, else the one it would be priced at. `null` for a machine on another range, or one whose location the ladder does not price (the meter counts that and charges nothing).","properties":{"amount_minor":{"type":"integer","format":"int64"},"currency":{"type":"string","minLength":3,"maxLength":3}}},"period":{"type":"string","maxLength":7,"description":"The **provider's** metering month, `YYYY-MM` in UTC — not the subscription's billing period. The provider resets the counter at their month boundary and the two disagree for anyone who bought mid-month."},"overage_gb":{"type":"number","format":"double","description":"The highest overage reading seen this period, in gigabytes. A high-water mark, not a sum: the provider states the month to date, so adding successive readings would count the same gigabyte once per poll."},"accrued_minor":{"type":"integer","description":"What that traffic costs the customer, in minor units of `currency`."},"settled_minor":{"type":"integer","description":"How much of it has actually been **captured**. The gap up to `accrued_minor` is what the next threshold charges for."},"currency":{"type":"string","maxLength":3,"description":"ISO 4217, or `\"\"` when nothing has been metered this period."},"next_threshold_minor":{"type":"integer","nullable":true,"description":"The next accrued total at which a charge is raised, or `null` when the ladder's rungs are all settled or none is configured."},"hard_ceiling_minor":{"type":"integer","nullable":true,"description":"The accrued total at which this machine is stopped regardless of payment, or `null` before the period has been priced."},"last_known_at":{"type":"string","format":"date-time","nullable":true,"description":"When a reading was last actually obtained. ⛔ `null` beside a zero accrual means we have never had a number this period — **not** that the machine owes nothing. The same distinction the usage gauges make between `0` and \"the provider did not say\"."},"charges":{"type":"array","items":{"$ref":"#/components/schemas/OverageChargeAttempt"},"description":"Every threshold already raised this period, ascending."}}},"ComputeServerPlan":{"type":"object","description":"What a machine costs today, what else it could carry, and what may change.","required":["deploy_target","size","resizable","resize_reason","addons_removable","addons_removal_reason","purchased","available"],"additionalProperties":false,"properties":{"deploy_target":{"type":"string"},"size":{"type":"string","description":"The provider's machine token."},"resizable":{"type":"boolean","description":"Whether the machine's processor and memory can change after purchase. `false` on the resold VPS range — the provider publishes no such operation at all."},"resize_reason":{"type":"string","description":"The sentence to show when `resizable` is false. Empty when it is true."},"addons_removable":{"type":"boolean","description":"Whether a bought option can be stopped. `false` on the VPS range: the provider offers no way to cancel one, in their API or in their own panel."},"addons_removal_reason":{"type":"string"},"purchased":{"type":"array","items":{"$ref":"#/components/schemas/ComputeAddonPurchase"}},"available":{"type":"array","items":{"$ref":"#/components/schemas/ComputeAddonOffer"}}}},"ComputeServerRecovery":{"type":"object","required":["rescue_supported","install_media_supported","rescue_enabled","install_media","available_install_media"],"additionalProperties":false,"properties":{"rescue_supported":{"type":"boolean"},"install_media_supported":{"type":"boolean"},"rescue_enabled":{"type":"boolean"},"install_media":{"oneOf":[{"$ref":"#/components/schemas/ComputeInstallMedia"},{"type":"null"}]},"available_install_media":{"type":"array","items":{"$ref":"#/components/schemas/ComputeInstallMedia"}}}},"ComputeServerRenameRequest":{"type":"object","required":["name"],"additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":37,"description":"The machine's new display name. 37 characters is the provider's own limit, mirrored here so the refusal comes from this form rather than from the supplier."}}},"ComputeServerRenewal":{"type":"object","description":"What happens to one machine when its term ends: the provider's contract for it, with **Zinn®'s** renewal switch, charge date and price over the top.\n\nTwo clocks live here on purpose and they are not interchangeable. `renews_at` is the provider's: the date the machine LAPSES at them if nobody renews it. `charge_at` is ours: the date the customer's card is actually charged (`Subscription.current_period_end`, the only column the rebill sweep selects on). They drift apart by arithmetic - a monthly subscription period advances by a flat 30 days while the provider advances by a calendar month - so a client that renders the provider's date as \"we will charge you on\" states the wrong day.\n\nThe provider's own `expectedRenewalPrice` is deliberately **not** here. It is what the provider charges Zinn® - wholesale, ex-VAT and in no stated currency - so it is neither the customer's price nor a figure any currency could be attached to. `price_amount_minor` + `price_currency` are what the customer will be charged.","required":["contract_id","auto_renew","subscription_id","renews_at","charge_at","price_amount_minor","price_currency","period"],"additionalProperties":false,"properties":{"contract_id":{"type":"string","description":"The provider's contract identifier."},"auto_renew":{"type":"boolean","description":"Whether **Zinn®** will charge for this machine again — `Subscription.auto_renew` for the subscription that pays for it, reached through the paid order line. It is **not** the provider's flag: that is pinned to \"hold\" for the life of every machine and is never exposed to a customer, because it is a different company's decision about a contract between them and us. `false` when the machine has no Zinn® subscription at all, which is the honest answer — nothing will renew it."},"subscription_id":{"type":"string","description":"The subscription whose switch `auto_renew` reports, to send the customer to `POST /v1/subscriptions/{subscriptionId}/auto-renew`. `\"\"` when the machine was provisioned outside a paid order (staff, comp, migration): there is then no switch to offer, and a client MUST say so rather than render a dead toggle."},"renews_at":{"type":"string","description":"**The provider's date** - when the machine lapses at them, as they state it, or `\"\"` when they state none. Blank means \"not stated\" - never \"never\". It is what the \"runs until X, powered off a day later, deleted six days after that\" sentences are about, and it is **not** the date the customer is charged - use `charge_at` for that."},"charge_at":{"type":"string","description":"**Zinn®'s date** - when the customer's card is charged next, ISO-8601, or `\"\"` when the machine has no Zinn® subscription. This is `Subscription.current_period_end`: the rebill sweep selects on it and nothing else, and a switched-off subscription expires on it. It is a different clock from `renews_at` and drifts further from it every period, so the two are never substituted for one another."},"price_amount_minor":{"type":["integer","null"],"format":"int64","description":"What the customer will be charged at `charge_at`, in **integer minor units** of `price_currency`, taken from the subscription's captured price (a live subscriber keeps the price they were sold). `null` when the machine has no subscription - nothing will charge for it, so there is no figure, and a client must say so rather than render a zero."},"price_currency":{"type":"string","description":"The ISO-4217 code `price_amount_minor` is denominated in, or `\"\"` when there is no subscription. Never rendered apart from the amount, and the amount never without it."},"period":{"type":"string","description":"The renewal cadence as the provider spells it, or `\"\"`."}}},"ComputeServerService":{"type":"object","description":"One service unit running inside a machine.","required":["name","unit","state","status","loaded"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"The provider's human description, e.g. `Apache HTTP Service`."},"unit":{"type":"string","description":"The unit's own name, e.g. `httpd.service`."},"state":{"type":"string","description":"Whether the unit is active at all, e.g. `active` or `inactive`. This is the field to judge \"is it meant to be running\"; `status` is the finer detail underneath it."},"status":{"type":"string","description":"The finer sub-state, e.g. `running`, `dead`, `exited`. Deliberately a separate field from `state` and not folded into it: a unit can be `active` and yet not `running`, and collapsing the two reports a stopped service as healthy."},"loaded":{"type":"boolean","description":"Whether the provider could load the unit's definition at all. `false` means the unit file is missing, masked or broken - a different fault from \"stopped\", and one a restart will not fix."}}},"ComputeServerServices":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ComputeServerService"}}}},"ComputeServerSetBackupsRequest":{"type":"object","description":"⛔⛔ **Chargeable in one direction and destructive in the other.** Enabling automatic backups costs a percentage of the machine's price for as long as it is on; disabling **deletes the existing restore points** at the provider, irreversibly. Both belong behind a confirmation that says which.","required":["enabled"],"additionalProperties":false,"properties":{"enabled":{"type":"boolean","description":"Whether automatic backups should run."}}},"ComputeServerSetFirewallRequest":{"type":"object","description":"⛔ **Whole-set replacement, never add or remove.** The provider's write is atomic, and a per-rule surface layered over an atomic replace is how two people editing at once silently discard each other's rule while both requests report success.\n\n⛔⛔ **This can lock a customer out of their own machine.** A set with no inbound SSH is applied exactly as asked; the out-of-band console is the way back in.","required":["rules"],"additionalProperties":false,"properties":{"rules":{"type":"array","items":{"$ref":"#/components/schemas/ComputeFirewallRule"}}}},"ComputeServerSnapshot":{"type":"object","description":"One on-demand image of a machine's disk.\n\n⛔ Distinct from `ComputeServerBackups`, which is the provider's automatic schedule. A snapshot is the customer's own act — taken before an upgrade, kept until deleted, and **billed for storage while it exists**. Conflating the two is how a customer ends up paying for something they believe is included.","required":["id","description","created_at","size_gb","ready","price_minor","price_currency"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"The provider's identifier for the image."},"description":{"type":"string","description":"What the customer called it, or `\"\"`."},"created_at":{"type":"string","description":"When it was taken, ISO-8601 as the provider states it, or `\"\"`."},"size_gb":{"type":"number","format":"double","nullable":true,"description":"Billable size. `null` while the provider is still measuring it — which it is for the first seconds after creation. ⛔ \"Not measured yet\" and \"takes no space\" are different claims and the second is about the customer's bill."},"ready":{"type":"boolean","description":"`false` while the provider is still writing it. ⛔ A restore offered on an unfinished snapshot restores an incomplete disk, and the provider will start it."},"price_minor":{"type":"integer","nullable":true,"description":"What **we** charge per month to keep this snapshot, in integer minor units of `price_currency`.\n\n⛔ `null` exactly while `size_gb` is `null`: the provider has not finished measuring the image, so there is nothing to price and any figure would be invented. Render \"still measuring\", never `0.00` — the second is a claim about the customer's bill."},"price_currency":{"type":"string","description":"ISO-4217 code for `price_minor`, or `\"\"` exactly when that is `null`."}}},"ComputeServerSnapshots":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ComputeServerSnapshot"}}}},"ComputeServerSoftware":{"type":"object","description":"One entry in a machine's software catalogue.","required":["id","name","version","description","website","installed"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"The provider's software identifier."},"name":{"type":"string","description":"The software's name, e.g. `NodeJS`."},"version":{"type":"string","description":"The version the provider offers","or `\"\"`.":null},"description":{"type":"string","description":"The provider's blurb","or `\"\"`.":null},"website":{"type":"string","description":"The project's home page","or `\"\"`.":null},"installed":{"type":"boolean","description":"Whether this machine already has it. Derived by testing for the provider's single \"available but not yours\" token rather than by listing the installed spellings, because the installed side of that field carries version detail and an allow-list would report software the customer already has as missing."}}},"ComputeServerSoftwareList":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ComputeServerSoftware"}}}},"ComputeServerUsage":{"type":"object","description":"One machine's metered usage for one month, with its ledger check.","required":["period","hours","rated_minor","settled_minor","unsettled_minor","currency","settlements","reconciles","discrepancies"],"additionalProperties":false,"properties":{"period":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}$"},"hours":{"type":"integer","description":"Started hours rated in the month."},"rated_minor":{"type":"integer","description":"Whole minor units rated. A sub-unit remainder is carried, never rounded up."},"settled_minor":{"type":"integer","description":"Net of tax","paid from the balance.":null},"unsettled_minor":{"type":"integer","description":"Rated and not yet paid."},"currency":{"type":"string"},"settlements":{"type":"array","items":{"$ref":"#/components/schemas/ComputeUsageSettlement"}},"reconciles":{"type":"boolean","description":"Whether hours, settlements, their orders and the balance draws all agree. It is computed from four independently written records, never a figure against itself."},"discrepancies":{"type":"array","items":{"type":"string"},"description":"Every disagreement found, in words. Empty when `reconciles` is true."}}},"ComputeServiceActionRequest":{"type":"object","description":"What to do to one service inside the machine.","required":["unit","action"],"additionalProperties":false,"properties":{"unit":{"type":"string","maxLength":255,"description":"The service unit to act on, exactly as `listComputeServerServices` reports it (`httpd.service`, `mariadb.service`, `proftpd.service`).\n\n⛔ Must be a unit the machine is **currently running**. The engine checks this against the live list before acting, so a unit the customer was never shown - `sshd.service`, a firewall - is refused rather than stopped.","example":"httpd.service"},"action":{"type":"string","enum":["start","stop","restart"],"description":"⛔ A closed vocabulary. `reload`, `enable` and `disable` are deliberately absent: they have never been proven against a provider, and a verb we have not proven is a button that may do nothing."}}},"ComputeServiceActionResult":{"type":"object","description":"The outcome of a service action.","required":["message"],"additionalProperties":false,"properties":{"message":{"type":"string","description":"The provider's own confirmation sentence — *\"Service proftpd.service was stopped successfully.\"* — passed through verbatim, because it is more specific than anything we would substitute for it.","example":"Service httpd.service was restarted successfully."}}},"ComputeSetBackupTierRequest":{"type":"object","required":["tier"],"additionalProperties":false,"properties":{"tier":{"type":"string","enum":["standard","pro"],"description":"⛔ Ours, not the provider's. `standard` maps to their `normal` and `pro` to their `upgraded`; the mapping lives in the engine so a client never learns a vendor word."}}},"ComputeSpec":{"type":"object","description":"One purchasable machine size. ⛔ **No price field, ever** — retail price is catalogue data the customer sees on the plan, the provider's own figure is cost, and a cost rendered beside a size is a margin leak.","required":["id","label","cores","ram_mb","disk_gb","bandwidth_gb","architecture","os_family"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"The size's id, and what an order names. When the provider published no sizes, our own sold tiers fill the list and this id **is** a plan code."},"label":{"type":"string","description":"The size's display name."},"cores":{"type":"integer","nullable":true,"description":"vCPU count, or null when not stated. ⛔ A null stays null: a size rendered as \"0 cores\" reads as a broken product where a blank reads as \"not stated\", which is what it is."},"ram_mb":{"type":"integer","nullable":true,"description":"Memory in mebibytes, or null when not stated."},"disk_gb":{"type":"integer","nullable":true,"description":"Disk in gibibytes, or null when not stated."},"bandwidth_gb":{"type":"integer","nullable":true,"description":"Included transfer in gibibytes, or null when not stated."},"architecture":{"type":"string","description":"`x86` or `arm` as the provider states it; `\"\"` when it states none, which is a real answer for a provider with one architecture and must **not** read as \"either\".\n\n⛔⛔ **An image picker MUST filter on this.** A provider publishing both families ships x86 and ARM images as separate `ComputeImage` entries with the **same name**, so a picker that ignores it offers every image on every size and is wrong half the time — and the provider says so with a `400` *after* the customer has paid."},"os_family":{"type":"string","enum":["","windows"],"description":"`windows` for a size sold with a Windows Server licence included; `\"\"` for any other. ⛔⛔ A picker MUST match it to `ComputeImage.os_family`: Windows images go on Windows sizes only and Windows sizes take Windows images only (the order is refused otherwise, before anything is charged)."}}},"ComputeSpendCap":{"type":"object","required":["monthly_cap_minor","currency","month_to_date_minor","metered_minor","bandwidth_overage_minor"],"additionalProperties":false,"properties":{"monthly_cap_minor":{"type":["integer","null"],"minimum":0,"description":"The organisation's monthly limit on server usage (pay-by-the-hour hours plus traffic over a server's allowance). `null` = no limit."},"currency":{"type":"string","description":"The organisation's billing currency."},"month_to_date_minor":{"type":"integer","description":"What the organisation's servers have used so far this month, in `currency` — the figure the limit is compared against. Equals `metered_minor` + `bandwidth_overage_minor`."},"metered_minor":{"type":"integer","description":"Pay-by-the-hour usage rated so far this month, in `currency`."},"bandwidth_overage_minor":{"type":"integer","description":"Traffic over the servers' monthly allowances so far this month, in `currency` (accrued, whether or not a charge has been taken for it yet)."}}},"ComputeSshKey":{"type":"object","description":"One public key an organisation has registered.","required":["id","name","fingerprint","public_key"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"The provider's id — what an order sends in `ssh_keys`."},"name":{"type":"string","description":"What the customer calls it."},"fingerprint":{"type":"string","description":"The **provider's** fingerprint, verbatim. ⛔ Never recompute it: ours disagreeing with theirs is indistinguishable, on a screen, from the customer having uploaded the wrong key."},"public_key":{"type":"string","description":"The public half, as registered. The private half never reaches us."}}},"ComputeSshKeyCreateRequest":{"type":"object","required":["name","public_key"],"additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":120,"description":"What to call it. Unique within the organisation."},"public_key":{"type":"string","minLength":1,"maxLength":16384,"description":"The **public** half — the one-line file ending `.pub`. ⛔ A private key is refused `422` with a sentence telling the customer to treat it as compromised and rotate it, rather than quietly stripped."}}},"ComputeSshKeyList":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ComputeSshKey"}}}},"ComputeTerminalAccess":{"type":"object","required":["enabled","public_key","fingerprint"],"additionalProperties":false,"properties":{"enabled":{"type":"boolean"},"public_key":{"type":"string","description":"The one line to add to `authorized_keys` on a machine built before the terminal was turned on. Public by definition — not a secret. `\"\"` when the terminal was never on."},"fingerprint":{"type":"string"}}},"ComputeTerminalTicket":{"type":"object","description":"⛔⛔ `ticket` is a credential — single use, sixty seconds.","required":["ticket","path","expires_at","host","username"],"additionalProperties":false,"properties":{"ticket":{"type":"string"},"path":{"type":"string","description":"The gateway path on this API's host — connect to `wss://<host><path>`."},"expires_at":{"type":"integer","description":"Unix seconds."},"host":{"type":"string","description":"The machine address the gateway will connect to."},"username":{"type":"string"}}},"ComputeTier":{"type":"object","description":"One tier we sell, published beside the provider's own sizes.","required":["plan_code","vendor_spec","name","deploy_target","cores","ram_gb","disk_gb","bandwidth_tb","orderable","price_minor","currency","prices","zone_prices","zoned","bandwidth_tb_by_zone","plan_version_id","sold_out","sold_out_zones","zone_specs","alternative"],"additionalProperties":false,"properties":{"plan_code":{"type":"string","description":"The tier's plan code in our catalogue."},"product_line":{"type":"string","description":"The `ProductLine.code` this tier's plan belongs to. A machine paid for by a subscription resizes only within its plan's product line; a move across lines is a new purchase and is refused, so a resize picker offers only this line's plans."},"vendor_spec":{"type":"string","description":"The provider's own token for this size (the platform's `micro`), or empty when our catalogue names none. A client joins a chosen size to its price on THIS field first, falling back to `plan_code` — the ids in `ComputeProvider.specs` are vendor tokens whenever `spec_source` is `vendor` and plan codes whenever it is `catalogue`, and both states occur. Joining on `plan_code` alone made every Zinn® Cloud size unbuyable when the vendor began publishing its spec list. An empty value must never match an empty spec id."},"name":{"type":"string","description":"The tier's name as the catalogue publishes it."},"deploy_target":{"type":"string","description":"Which compute range the tier belongs to."},"cores":{"type":"integer","nullable":true,"description":"vCPU count, or null when the plan does not state one."},"ram_gb":{"type":"integer","nullable":true,"description":"Memory in gibibytes, or null when the plan does not state one."},"disk_gb":{"type":"integer","nullable":true,"description":"Disk in gibibytes, or null when the plan does not state one."},"bandwidth_tb":{"type":"integer","nullable":true,"description":"Included transfer in tebibytes, or null when the plan does not state one."},"orderable":{"type":"boolean","description":"False when neither the plan nor the provider names a machine size for this tier — the honest \"not yet\", so a screen can explain instead of offering a button that `422`s."},"price_minor":{"type":["integer","null"],"format":"int64","description":"**Our** sell price for this tier, in minor units, per month. `null` when the catalogue names no price at that cadence — render that as \"not available\", never as free.\n\n⛔ This is not the vendor's cost figure, which never reaches a customer: a `ComputeSpec` deliberately carries no price for exactly that reason. This is the price we publish, editable in admin, and a configurator that cannot show it sends the customer to a checkout to discover what they will pay."},"currency":{"$ref":"#/components/schemas/CurrencyCode","description":"The currency `price_minor` is quoted in."},"prices":{"type":"array","items":{"$ref":"#/components/schemas/ComputeTierPrice"},"description":"Every billing cadence this size can be **bought** at, with the figure for each, in the order a term picker should render them.\n\n⛔ **Build a term picker from this and from nothing else.** Offering \"yearly\" for a tier absent from this list is the defect the field exists to prevent: the choice looks live, `POST /v1/carts/{cartId}/lines` answers `422`, and — because a cart re-prices on every read — the basket then cannot be displayed at all until it is emptied. `price_minor` above is the headline monthly figure derived from this same list, so the two cannot disagree.\n\nThe `interval` value here is exactly what the client sends back as `CartLineCreate.interval`, so the customer's choice reaches the cart verbatim rather than through a mapping either side could get wrong."},"zone_prices":{"type":"array","items":{"$ref":"#/components/schemas/ComputeZonePrice"},"description":"Every data centre this size is sold in, with the figure for each cadence.\n\n⛔⛔ **When this is non-empty it is the ONLY charge basis, and `price_minor` above becomes a \"from\" figure.** Collect the data centre before quoting: the engine refuses an order that names none, because \"pick the first one\" is picking a price on the customer's behalf out of whatever order the provider happened to list its locations in.\n\n⛔ It is also the **availability** list. Not every size exists in every data centre — the ARM sizes are European only — and a size absent from a zone here is one the provider refuses *after* the customer has paid."},"zoned":{"type":"boolean","description":"Whether this size is priced per data centre, i.e. whether `price_minor` is a \"from\" figure and a zone must be chosen before anything can be quoted.\n\n⛔ Published rather than derived from `zone_prices` being non-empty, for the same reason `ComputeServer.operable` is published: a client that computes its own answer will eventually compute a different one, and this one decides whether the word \"from\" appears next to a price."},"bandwidth_tb_by_zone":{"type":"array","description":"⚖️ Q342 (2026-10-08): the traffic this size includes each month in each data centre, in TB of 2^40 bytes — the network provider's own included traffic for this machine type there, which is where the bandwidth overage starts. Empty when the provider's rate card cannot be read (never a guess) and on a range not priced per data centre. `bandwidth_tb` is the plan's single legacy figure, not this.","items":{"type":"object","required":["zone","tb"],"additionalProperties":false,"properties":{"zone":{"type":"string","description":"The data centre","as in `zone_prices`.":null},"tb":{"type":"number","description":"Terabytes included per month."}}}},"setup_fee_by_zone":{"type":"array","description":"s1014 SUPPLIERS-SETUPFEE: the one-off setup fee this size carries in each data centre, passed on at cost and added to the basket as its own `setup_fee` line, so the order review can state the real first payment. Listed only where there is a fee; empty on a range priced without one.","items":{"type":"object","required":["zone","amount_minor","currency"],"additionalProperties":false,"properties":{"zone":{"type":"string","description":"The data centre","as in `zone_prices`.":null},"amount_minor":{"type":"integer","minimum":0,"description":"The fee","minor units.":null},"currency":{"type":"string","description":"ISO 4217 code of `amount_minor`."}}}},"zone_specs":{"type":"array","description":"Region price (2026-10-29): one plan can be built on a different machine in different data centres (Zinn® Cloud Grow is Arm in the EU and x86 elsewhere). The machine each in-stock data centre builds this plan on now, and the traffic that machine includes there per month (TB of 2^40 bytes, the supplier's own published figure; `null` when unknown — never a guess). Empty when stock is unknown or the range is not priced per data centre.","items":{"type":"object","required":["zone","spec","traffic_tb"],"additionalProperties":false,"properties":{"zone":{"type":"string","description":"The data centre","as in `zone_prices`.":null},"spec":{"type":"string","description":"The supplier machine built there now."},"traffic_tb":{"type":["number","null"],"description":"Terabytes of traffic that machine includes per month there."}}}},"plan_version_id":{"type":"string","description":"The plan version the price was read from. A cart line names the `plan_code` and the engine re-pins the version itself; this lets a basket notice that the catalogue moved underneath it."},"sold_out":{"type":"boolean","description":"True when no data centre can supply this plan right now. The plan is still listed so the customer sees it is sold out rather than gone; `orderable` is then false, and it reopens by itself the moment the supplier has stock again."},"sold_out_zones":{"type":"array","items":{"type":"string"},"description":"Availability is per region. The data centres (as in `zone_prices`) this plan is priced in but cannot be supplied in right now. A plan sold out in some regions stays orderable in the others (`zone_prices` lists only those); the order screen shows these as sold out. A region kept off sale by our margin floor is never listed: it is not offered at all. On a `sold_out` plan, every region it is sold out in."},"alternative":{"type":["object","null"],"description":"On a sold-out plan, the closest plan a customer can order right now instead (same product line, GPU only for GPU, the same range first); null otherwise.","required":["deploy_target","plan_code","name"],"additionalProperties":false,"properties":{"deploy_target":{"type":"string"},"plan_code":{"type":"string"},"name":{"type":"string"}}}}},"ComputeTierPrice":{"type":"object","description":"One tier's published price at one billing cadence. ⛔ The vendor is paid its `periodMonths` UP FRONT and auto-renews at that period, so the cadence a customer buys at is also the term we buy the machine for — which is why a cadence with no entry here cannot be offered at all.","required":["interval","amount_minor","currency"],"additionalProperties":false,"properties":{"interval":{"$ref":"#/components/schemas/BillingInterval","description":"The cadence. Sent straight back as `CartLineCreate.interval` to buy at it."},"amount_minor":{"type":"integer","format":"int64","description":"**Our** sell price at this cadence, in integer minor units."},"currency":{"$ref":"#/components/schemas/CurrencyCode"}}},"ComputeTrialCredit":{"type":"object","required":["eligible","reason","claimed","offer_minor","remaining_minor","currency","used_up"],"properties":{"eligible":{"type":"boolean"},"reason":{"type":"string","description":"Why the credit cannot be claimed, empty when it can. email_not_verified and no_card are steps the customer can take.","enum":["","already_granted","no_policy","not_customer","reseller_client","not_in_good_standing","email_not_verified","no_card","paid_before","used_elsewhere","card_used_elsewhere","no_fx_rate"]},"claimed":{"type":"boolean"},"offer_minor":{"type":["integer","null"],"description":"The credit a claim gives now, minor units of currency."},"remaining_minor":{"type":["integer","null"],"description":"What is left of a claimed credit, minor units of currency."},"currency":{"type":"string","minLength":3,"maxLength":3},"used_up":{"type":"boolean"}}},"ComputeUsage":{"type":"object","description":"What the account runs now, measured the way `ComputeLimits` bounds it.","required":["servers","vcpus","monthly_spend_minor","unmeasured"],"additionalProperties":false,"properties":{"servers":{"type":"integer"},"vcpus":{"type":"integer"},"monthly_spend_minor":{"type":"integer"},"unmeasured":{"type":"integer","description":"Machines whose size or price could not be read. Reported rather than counted as zero — an estate of unmeasurable machines looks exactly like an empty one."}}},"ComputeUsageSettlement":{"type":"object","required":["id","hours","net_minor","tax_minor","total_minor","currency","outcome","created_at"],"additionalProperties":false,"properties":{"id":{"type":"string"},"hours":{"type":"integer"},"net_minor":{"type":"integer"},"tax_minor":{"type":"integer"},"total_minor":{"type":"integer"},"currency":{"type":"string"},"outcome":{"type":"string","enum":["paid","insufficient_funds","untaxed"],"description":"`paid` — a taxed order paid in full from the balance. `insufficient_funds` — nothing was taken and the machine is held. `untaxed` — tax could not be computed, so no order exists and nothing was taken."},"created_at":{"type":"string","format":"date-time"}}},"ComputeVpsOptions":{"type":"object","description":"The paid options a VPS of one size can carry, grouped by kind.","required":["size","cpanel","backup","disk","image","resizable","resize_reason"],"additionalProperties":false,"properties":{"size":{"type":"string"},"cpanel":{"type":"array","items":{"$ref":"#/components/schemas/ComputeAddonOffer"}},"backup":{"type":"array","items":{"$ref":"#/components/schemas/ComputeAddonOffer"}},"disk":{"type":"array","items":{"$ref":"#/components/schemas/ComputeAddonOffer"}},"image":{"type":"array","description":"Only the operating systems that carry a price. A free image needs no row.","items":{"$ref":"#/components/schemas/ComputeAddonOffer"}},"resizable":{"type":"boolean"},"resize_reason":{"type":"string"}}},"ComputeVpsQuote":{"type":"object","description":"One configured VPS, itemised. Every figure is integer minor units of `currency`; `total_minor` is the sum and is the number to show the customer.","required":["currency","interval","machine_minor","image_minor","cpanel_minor","backup_minor","disk_minor","total_minor"],"additionalProperties":false,"properties":{"currency":{"type":"string","minLength":3,"maxLength":3},"interval":{"type":"string","enum":["monthly","yearly"]},"machine_minor":{"type":"integer","format":"int64","description":"The machine itself, from its **plan** — never from the add-on catalogue."},"image_minor":{"type":"integer","format":"int64"},"cpanel_minor":{"type":"integer","format":"int64"},"backup_minor":{"type":"integer","format":"int64"},"disk_minor":{"type":"integer","format":"int64"},"total_minor":{"type":"integer","format":"int64"}}},"ComputeZone":{"type":"object","description":"One data centre a machine can be placed in.","required":["id","label"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"The zone's id at the provider, and what an order names."},"label":{"type":"string","description":"The zone's own display name, as the provider publishes it."}}},"ComputeZonePrice":{"type":"object","description":"One tier's published price **in one data centre**.\n\n⛔⛔ **A different fact from `ComputeTierPrice`, not a refinement of it.** On the Zinn® Private Cloud range the same machine is $14.99/month in Falkenstein and $51.99 in Ashburn, because that is what it costs us. A client that rendered one of these where it meant the other would be wrong by $37 a month, with nothing to warn it.","required":["zone","interval","amount_minor","currency"],"additionalProperties":false,"properties":{"zone":{"type":"string","description":"The data-centre id — the same value sent back as the order's `zone` and as `ComputeLineConfig.zone`, so the choice a customer made is the choice that is priced."},"interval":{"$ref":"#/components/schemas/BillingInterval"},"amount_minor":{"type":"integer","format":"int64","description":"**Our** sell price in this data centre at this cadence, in minor units."},"currency":{"$ref":"#/components/schemas/CurrencyCode"}}},"ConnectExternalBackupRequest":{"type":"object","required":["channel"],"properties":{"channel":{"$ref":"#/components/schemas/ExternalBackupChannel"},"ssh_host":{"type":"string","maxLength":255,"description":"Required when `channel` is `ssh`."},"ssh_port":{"type":"integer","format":"int32","minimum":1,"maximum":65535,"default":22},"ssh_username":{"type":"string","maxLength":64,"description":"Required when `channel` is `ssh`."},"remote_path":{"type":"string","maxLength":512,"description":"The document root, required when `channel` is `ssh`. Refused at configuration time rather than at 03:00 when the sweep runs."},"ssh_secret":{"type":"string","writeOnly":true,"description":"The private key (PEM) or password. Written to our secret store and never returned. Omit it to keep the credential already stored."},"extra_paths":{"type":"array","maxItems":10,"items":{"type":"string","maxLength":512},"description":"`ssh` only. Extra folders to include in every backup: absolute paths, no `..`, never `/`. Omit it to keep the saved list. A folder the SSH user cannot read in full makes the backup fail with that folder named, never a backup that silently lacks it."}}},"ConnectPanelRequest":{"type":"object","description":"⛔ Either `api_key`, or `username` **and** `password`. An API key is preferred: it is scoped and can be revoked inside Plesk without changing the administrator's password, which the customer uses for everything else.","required":["host"],"additionalProperties":false,"properties":{"host":{"type":"string","maxLength":255},"port":{"type":"integer","default":8443,"minimum":1,"maximum":65535},"label":{"type":"string","maxLength":120},"licence_id":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/Uuid"}]},"verify_tls":{"type":"boolean","default":true},"api_key":{"type":"string","description":"A Plesk API key. Stored in Vault, never in a row."},"username":{"type":"string"},"password":{"type":"string","format":"password","description":"The administrator's password. Stored in Vault, never in a row."}}},"ConnectTokenRequest":{"type":"object","additionalProperties":false,"description":"Supply **either** `token` or `credentials`. ⛔ `token` is no longer required, because two of the six BYO DNS vendors have no single-token credential to put there: ClouDNS needs `auth_id` and `auth_password`, Azure needs five fields. Call `listConnectionProviders` for the exact field names a provider takes.","anyOf":[{"required":["token"]},{"required":["credentials"]}],"properties":{"token":{"type":"string","minLength":1,"description":"The provider access token, for the providers whose credential is a single string. Written to Vault, never to a database row, a log line, an audit entry or an error message (CLAUDE.md §2.4)."},"credentials":{"type":"object","additionalProperties":{"type":"string"},"description":"Driver setting key to value, for providers whose credential has more than one part. The keys are the vendor's own, exactly as `listConnectionProviders` reports them. Treated identically to `token` for storage: Vault only, never echoed."},"validate_only":{"type":"boolean","description":"Check the credential and return the result without storing anything."},"also_dns":{"type":"boolean","description":"Use this one account for the provider's **second** driver category as well — on Cloudflare, *\"use the CDN as the DNS\"*.\n\n⭐ On a zone-owning CDN this is not a convenience: the same Cloudflare zone both answers DNS queries and fronts the origin, so one account genuinely serves both roles. Without this a customer would paste the same token twice, under two provider names, to describe one account.\n\nIt writes a second connection in the DNS category pointing at the **same** stored credential — one thing to rotate, not two that drift apart.\n\n⛔ Never implied. Connecting a Cloudflare account for your CDN does not consent to moving your domain's DNS authority, which is a bigger and more disruptive change than putting a CDN in front of a site."},"zone_hint":{"type":"string","maxLength":253,"description":"The domain to test the zone-scoped permissions against, so the answer is about the zone we will actually drive. Optional: without it the account's first zone is used, and an account with no zones at all reports those rows as `unknown` rather than guessing — connecting a credential before adding the domain is the normal first step, not an error."},"target":{"type":"string","enum":["cdn","pages"],"description":"What the credential is connected FOR. Only Cloudflare offers a narrower target: `pages` = host sites on Cloudflare Pages only. The credential is then judged on Cloudflare Pages access alone (`pages_edit`), no zone is listed or written, and `credentials.account_id` is required. Omitted (or `cdn`) = the provider's full check. Cannot be combined with `also_dns`. Other providers ignore it."}}},"ConnectedDomain":{"description":"A newly connected domain, plus the delegation to set at its registrar.","allOf":[{"$ref":"#/components/schemas/Domain"},{"type":"object","required":["delegation"],"properties":{"delegation":{"$ref":"#/components/schemas/Delegation"}}}]},"Connection":{"type":"object","required":["id","provider","account_login","scopes","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"provider":{"$ref":"#/components/schemas/ConnectionProvider"},"account_login":{"type":"string","description":"The account the token was found to authenticate as."},"scopes":{"type":"array","items":{"type":"string"},"description":"Scopes the token was found to carry. May be empty for a token whose permissions the provider does not enumerate."},"created_at":{"type":"string","format":"date-time"},"permissions":{"oneOf":[{"$ref":"#/components/schemas/PermissionReport"},{"type":"null"}],"description":"The last per-permission checklist taken for this connection, or `null` when it has never been tested. ⛔ `null` means **never checked**, which is a different fact from \"checked, and everything passed\" — do not render it as a tick. When present it always carries `checked_at`, because it is a measurement frozen at that moment and the customer can revoke a permission at their vendor a second later."}}},"ConnectionList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Connection"}}}},"ConnectionProbeRequest":{"type":"object","additionalProperties":false,"properties":{"zone_hint":{"type":"string","maxLength":253,"description":"The domain to test the zone-scoped permissions against. Optional — see `ConnectTokenRequest.zone_hint`."}}},"ConnectionProvider":{"type":"string","enum":["cloudflare","github","gitlab","netlify","vercel","dns_cloudflare","dns_desec","dns_hetzner","dns_cloudns","dns_bunny","dns_azure","cdn_cloudflare","cdn_bunny","cdn_cdn77","cdn_keycdn","cdn_fastly","cdn_gcore","cdn_cloudfront","cdn_akamai","dns_route53","dns_digitalocean","seo_majestic","seo_ahrefs","seo_moz","seo_dataforseo","dns_gcore","streaming_gcore","waap_gcore","inference_gcore","registrar_godaddy","registrar_namecheap","registrar_porkbun","registrar_namecom","registrar_gandi","registrar_spaceship","registrar_namesilo","registrar_hostinger","registrar_ovh","bitbucket","render","azure_swa","aws_amplify"],"description":"A third-party account a customer can connect. `bitbucket` is source control; `render`, `azure_swa` and `aws_amplify` are edge hosts a site can be deployed to on the customer's own account (`aws_amplify`, like `vercel`, is bring-your-own only). `cloudflare` and `github` each serve two driver categories with one token (cloud account / source control, plus their Pages edge host); `gitlab` serves source control and GitLab Pages; `netlify` and `vercel` are edge hosts only.\n\nThe `registrar_*` values are a customer's own **domain registrar** account, and what they grant is deliberately narrow: we read the account's domains and we set a domain's nameservers. Nothing may transfer, renew, unlock, delete or re-contact a name, and that is enforced by the adapter rather than by policy — every other operation raises. A credential that controls a customer's whole domain portfolio is held for one job, so the blast radius of a defect is their website and never their business.\n\nConnecting one is what lets the platform point a domain at a new site by itself when that site is deployed. Without it the domain screen still shows the exact nameservers to set, and the customer sets them at their registrar.\n\nThe nine `dns_*` values are the **bring-your-own DNS** providers (owner ruling G-2, 2026-08-14, plus AB-4 and W30-F below). ⛔ `dns_cloudflare` is deliberately distinct from `cloudflare`: the same customer may bring one Cloudflare account for their CDN and a different one for DNS, and the two are stored under different paths and resolved for different driver categories. Collapsing them would make the second connect silently overwrite the first.\n\nThe eight `cdn_*` values are the **bring-your-own CDN** providers. ⚖️ Owner ruling 2026-08-26 took the first three (*\"all three we hold drivers for\"*); ⚖️ owner ruling **AB-1, 2026-08-27** added the five `docs/19` §5.5 had spec'd as tier-1 and nobody had built — `cdn_keycdn`, `cdn_fastly`, `cdn_gcore`, `cdn_cloudfront`, `cdn_akamai`. Asked whether to answer those with tier-2 passthrough instead, he chose real drivers: *\"why can we not build the pairs for all of these so they can purge it and manage it from inside our panel in full.\"* ⛔⛔ They were not merely absent — the **live marketing site** has been selling them as driven-by-us (*\"Cloudflare, BunnyCDN, CDN77, KeyCDN, Fastly, Amazon CloudFront, Akamai and more\"*) while the engine held three: a consumer with no producer, one layer further out than D14090's.\n\n⚠️ `cdn_akamai` advertises a deliberately **smaller** capability set than the other seven — no `cdn:zones` — because Akamai has no create-a-pull-zone call. It adopts a property the customer already built (owner ruling G-1's principle) and drives purge, which is the operation they reach for daily.\n\nThe four `seo_*` values are the **bring-your-own SEO data** providers (⚖️ owner ruling 2026-08-28: *\"customers connect their own Ahrefs / Moz / Majestic API keys\"*, and the reseller half — their own keys free, or a paid monthly add-on to use ours). ⛔⛔ They were in the engine's `PROVIDER_MAP` and **absent from this enum**, which is D14090's defect exactly: a provider the engine can connect and this enum cannot name is unreachable to every generated SDK, to the CLI, and to the dashboard picker — whose provider list, group map and scope hints are all `Record<ConnectionProvider, …>`. The visible symptom was a **dead end in the product**: the site SEO card tells a customer with no key *\"connect one\"* and links to `/connections`, where no SEO provider could be offered.\n\n⭐ `seo_dataforseo` resolves the vendor `dataforseo_backlinks` — the driver's own registry name, not the brand — and that ONE account also serves keyword research, product data and rank tracking (D15478). One key, one Vault secret, four seams.\n\nThe nine `dns_*` values are the **bring-your-own DNS** providers: six from ruling G-2, `dns_route53` + `dns_digitalocean` from ⚖️ **ruling AB-4, 2026-08-27**, and `dns_gcore` from ⚖️ **W30-F, 2026-08-28**. ⚠️ This paragraph said \"eight\" while the one above it said \"six\" — of the same list, in the same block — from the moment AB-4 landed. Two counts for one set in one document is the failure `CLAUDE.md` §5 records against its own merge-queue numbers: **when you change a value, grep the whole file for the OLD one**, because the stale copy is never where you just edited. ⛔ `docs/19` §7.2's *\"Route 53 stays dropped\"* is untouched by this and must not be cited against it — that decision priced **our own pool** at ~$0.50/zone/month across 90k zones. On a BYO account the fee is the customer's, so the reason does not transfer; reading it as a decision about BYO is a §2.43 *population* error, and the owner confirmed the distinction when it was put to him.\n\n⚖️ **`streaming_gcore`, `waap_gcore` and `inference_gcore` are W30-F, 2026-08-28**, with `dns_gcore`: the rest of the Gcore catalogue, asked for as *\"you need to build all of them end to end and test it, we need it ALL and adding properly\"* and ruled **BYO only** in the same answer. ⛔⛔ That ruling is load-bearing rather than a preference: Gcore's MSA §17.4 forbids reselling its services to a third party without written permission, and a **BYO connection resells nothing** — the account, the capacity and the invoice are the customer's. A published Gcore *Reseller Agreement* does exist and would permit white-labelling, and the owner declined it; do not re-propose it without a new ruling. Full finding: `docs/242` §1.\n\n⛔ `inference_gcore` is the only provider in this enum whose credential is **not one string**: Gcore's inference paths are project-scoped, so it takes `api_token` **and** `project_id`. Read the form from `/v1/connections/providers` rather than assuming a single token field, which is exactly what that endpoint exists for.\n\n⛔ `cdn_cloudflare` is distinct from both `cloudflare` and `dns_cloudflare` for the reason the paragraph above gives, and the distinction was load-bearing rather than tidy: until W29-J there was **no CDN entry of any kind**, so `build_org_driver(CDN, …)` — which resolves strictly on the `cdn` category — could never find a customer's account, while the BYO guards asked about a `cloud_account` row instead. A customer was admitted to `tier=byo`, the CDN resolution found nothing of theirs, and the zone was created on the **platform pool** and billed to us while the screen said it was on their account (D14090/D14091).\n\n⭐ This enum types the `{provider}` path segment for every operation on this surface, so leaving it at five while `PROVIDER_MAP` had eleven meant generated SDKs and the CLI could not address a DNS connection at all, and a stored DNS row's response was spec-invalid. The dashboard declares its own local union, so `tsc` could not see the drift — which is exactly why it has to be right here."},"ConnectionProviderDescriptor":{"type":"object","required":["provider","category","vendor","shapes","permissions","required_permissions","allow_list_address","allow_list_reason"],"properties":{"provider":{"type":"string"},"category":{"type":"string","description":"The driver category this connection is stored and resolved under."},"vendor":{"type":"string"},"shapes":{"type":"array","items":{"type":"array","items":{"$ref":"#/components/schemas/CredentialField"}},"description":"**Alternative** credential forms — render the first and offer the rest. Cloudflare is the live case: a scoped API token, or the account email plus its Global API Key."},"permissions":{"type":"array","items":{"type":"string"},"description":"The permission keys this provider is tested for, in checklist order. Empty means we have no permission model for it — ⛔ render that as \"we cannot test this provider\", never as a satisfied checklist."},"required_permissions":{"type":"array","items":{"type":"string"},"description":"A subset of `permissions`. The rest are reported for information and can never make a credential unusable."},"allow_list_address":{"type":"string","readOnly":true,"description":"The source address a customer must add to this vendor's own allow-list, or `\"\"` when we cannot honestly give one. **Derived from the MEASURED exit address of the proxy this vendor's egress is pinned to** — never the proxy's host (a proxy may exit from an address it does not listen on) and never a constant in copy, which would be wrong the day the pool changes with nothing to notice.\n⛔ Do not substitute anything when it is empty. A plausible wrong address is worse than none: the customer pastes it into their registrar, every call is refused, and it reads as our fault. Render `allow_list_reason` instead."},"allow_list_reason":{"type":"string","readOnly":true,"enum":["ok","not_applicable","not_pinned","not_measured"],"description":"Why `allow_list_address` is what it is. A blank address has three different meanings and a screen that renders them identically tells the customer nothing they can act on:\n`ok` — a measured address; show it. `not_applicable` — this vendor does not allow-list source addresses; show nothing. `not_pinned` — it does, and no proxy is pinned for it yet (staff action). `not_measured` — pinned, but the health probe has not yet observed an exit address."},"targets":{"type":"array","items":{"type":"string","enum":["cdn","pages"]},"description":"The connection targets the customer may pick, default first; `[]` when there is nothing to pick. Cloudflare serves `[cdn, pages]`: `pages` connects the account only to host sites on Cloudflare Pages, so it is judged on `pages_edit` alone and no zone is touched. Send the pick as `ConnectTokenRequest.target`."},"also_serves":{"type":"string","description":"The **second** driver category this one account can also serve, or `\"\"`. On Cloudflare that is `dns` — *\"use the CDN as the DNS\"*, because the same zone both answers queries and fronts the origin.\n\n⛔ Served rather than hardcoded per client: the rule has one home in the engine, and a client testing for a provider name would be a second copy free to drift."}}},"ConnectionProviderList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConnectionProviderDescriptor"}}}},"ConnectorBackupCompletion":{"type":"object","required":["job_id","status"],"properties":{"job_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["uploaded","failed"]},"size_bytes":{"type":"integer","format":"int64","minimum":0,"description":"The plugin's own figure. A cross-check only — the recorded size comes from HEAD-ing the stored object."},"detail":{"type":"string","maxLength":2000,"description":"Why it failed. Kept for staff and never rendered to the customer: untranslated English that can carry a path from their server."}}},"ConnectorBackupJob":{"type":"object","description":"A backup for the connector plugin to run, or an empty object when nothing is due. Both `job_id` and `upload_url` are present together or not at all.","properties":{"job_id":{"type":"string","format":"uuid","description":"The backup row this upload settles."},"upload_url":{"type":"string","format":"uri","description":"A short-lived presigned PUT. ⛔ A bearer credential — whoever holds it can write that object — so the plugin never logs it, stores it, or shows it in an admin notice. It grants exactly one derived object key and nothing else."}}},"ContentCampaign":{"type":"object","required":["campaign_id","brief","total","pending","done","failed","paused","cancelled","site_count","runs"],"properties":{"campaign_id":{"type":"string"},"brief":{"type":"string"},"total":{"type":"integer"},"pending":{"type":"integer"},"done":{"type":"integer"},"failed":{"type":"integer"},"paused":{"type":"integer"},"cancelled":{"type":"integer"},"next_at":{"type":"string","format":"date-time","nullable":true},"last_at":{"type":"string","format":"date-time","nullable":true},"site_count":{"type":"integer"},"runs":{"type":"array","items":{"$ref":"#/components/schemas/ContentCampaignRun"}}}},"ContentCampaignActionResult":{"type":"object","required":["affected","campaign"],"properties":{"affected":{"type":"integer","description":"How many articles the action actually touched. A campaign of twelve with four already written reports `8` for a pause, so a screen can say *\"paused 8 of 12\"* rather than a silent success that does not match what the customer sees."},"campaign":{"$ref":"#/components/schemas/ContentCampaign"}}},"ContentCampaignPage":{"type":"object","required":["items","total"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ContentCampaign"}},"total":{"type":"integer"}}},"ContentCampaignPlan":{"type":"object","required":["campaign_id","targets","posts","total_articles","total_placements"],"properties":{"campaign_id":{"type":"string"},"targets":{"$ref":"#/components/schemas/ContentCampaignTargets"},"posts":{"type":"array","items":{"$ref":"#/components/schemas/ContentCampaignPlannedPost"}},"total_articles":{"type":"integer","description":"Articles written. One per topic."},"total_placements":{"type":"integer","description":"Individual publications — articles times sites. The number that reads as *\"how much am I about to do\"*, and the one the spend estimate is built on."},"first_at":{"type":"string","format":"date-time","nullable":true},"last_at":{"type":"string","format":"date-time","nullable":true}}},"ContentCampaignPlannedPost":{"type":"object","required":["index","topic","starts_at"],"properties":{"index":{"type":"integer"},"topic":{"type":"string"},"starts_at":{"type":"string","format":"date-time"}}},"ContentCampaignRun":{"type":"object","required":["id","topic","state","sites","editable"],"properties":{"id":{"type":"string"},"topic":{"type":"string"},"state":{"$ref":"#/components/schemas/ContentRunState"},"starts_at":{"type":"string","format":"date-time","nullable":true},"sites":{"type":"integer"},"editable":{"type":"boolean","description":"Whether this article can still be moved or cancelled. False once it has started — its copy exists and its placements carry their own times."}}},"ContentCampaignTargets":{"type":"object","required":["kind","site_ids","domains","skipped_not_publishable"],"properties":{"kind":{"type":"string","enum":["sites","site_group"]},"group_id":{"type":"string","nullable":true},"site_ids":{"type":"array","items":{"type":"string"}},"domains":{"type":"array","items":{"type":"string"},"description":"The sites that will receive posts, for the confirm step."},"skipped_not_publishable":{"type":"integer","description":"In the group or the id list, but not in a state that can receive a post. Always present, including at zero: *\"12 sites\"* and *\"12 of your 40\"* need different actions from the customer, and a field that appeared only when non-zero would make those two render identically."}}},"ContentCampaignWrite":{"type":"object","additionalProperties":false,"required":["brief","posts"],"description":"Exactly one of `site_ids` or `site_group_id` must be given. Both, or neither, is refused with one sentence — from the customer's chair they are the same mistake: they have not said where to post.","properties":{"brief":{"type":"string","maxLength":4000,"description":"The standing instruction — voice, audience, what the sites are about."},"posts":{"type":"integer","minimum":1,"maximum":200,"description":"How many ARTICLES to write. Each is placed on every target site, so the number of publications is this times the site count."},"topics":{"type":"array","maxItems":200,"items":{"type":"string","maxLength":300},"description":"One subject per article, so N articles are N articles rather than N paraphrases. A shorter list cycles; an empty one means the brief alone.","x-zinn-note":"This is why a campaign is N runs rather than one run asking for N posts — the writer caps a single brief at ten articles precisely because more than that from one brief produces near-identical copy, which is the footprint this product line exists to avoid."},"site_ids":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"string","format":"uuid"}},"site_group_id":{"type":"string","format":"uuid","nullable":true,"description":"A site group, **resolved when the campaign is created** rather than copied. A recurring schedule pointed at a group re-resolves it on every firing, so sites added later are included; an in-flight campaign keeps the sites it started with, so what was shown on the confirm step is what happens."},"drip_days":{"type":"integer","minimum":0,"maximum":365,"default":0,"description":"Spread the articles across this many days. `0` publishes them together."},"drip_jitter_minutes":{"type":"integer","minimum":0,"maximum":720,"default":90,"description":"Randomise each moment by up to this many minutes either way. Perfectly even spacing is more detectable than posting all at once — nothing a person does is that regular — so this is part of the product rather than a refinement."},"anchors":{"type":"array","items":{"$ref":"#/components/schemas/ContentRunAnchor"}},"category":{"type":"string","maxLength":200},"publish_policy":{"$ref":"#/components/schemas/ContentRunPublishPolicy"},"recipe_id":{"type":"string","format":"uuid","nullable":true}}},"ContentHash":{"type":"string","description":"SHA-256 (hex) of the source text. The cache key and the change detector — an unchanged hash makes registration a no-op.","pattern":"^[0-9a-f]{64}$","example":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"},"ContentPost":{"type":"object","description":"A customer-owned content item — V1's `Post`. It publishes nowhere until it is given a placement.","required":["id","title","body_html","notes","status","placement_count","published_count","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string","maxLength":300},"body_html":{"type":"string","description":"The post body as HTML, exactly as the customer wrote it. The `<a>` tags in it are the anchors; the platform never rewrites them, on the way in or the way out."},"notes":{"type":"string","description":"The customer's own notes — V1's `Post.notes`. Never published."},"status":{"type":"string","enum":["draft","ready"]},"placement_count":{"type":"integer","minimum":0,"description":"Sites this post is scheduled or live on."},"published_count":{"type":"integer","minimum":0},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ContentPostCreate":{"type":"object","required":["title"],"properties":{"title":{"type":"string","minLength":1,"maxLength":300},"body_html":{"type":"string","default":""},"notes":{"type":"string","default":""}}},"ContentPostGenerate":{"type":"object","required":["brief"],"properties":{"brief":{"type":"string","maxLength":4000,"description":"What the article should be about, in the language you want it written in. A tighter brief produces better articles than a longer one."},"count":{"type":"integer","minimum":1,"maximum":10,"default":1,"description":"How many articles to write. ⛔ Capped at 10: more than that from one brief produces near-identical copy across a network, which is the footprint the Footprint-Free line exists to avoid."},"anchors":{"type":"array","maxItems":5,"description":"The links to place, each exactly once per article, using the given text verbatim. More than five in one article is a spam signal.","items":{"type":"object","required":["url","text"],"properties":{"url":{"type":"string"},"text":{"type":"string","description":"The visible link text, used exactly as given."}}}}}},"ContentPostPage":{"type":"object","required":["items","total","offset","limit","has_more"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ContentPost"}},"total":{"type":"integer","minimum":0},"offset":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1},"has_more":{"type":"boolean"}}},"ContentRun":{"type":"object","required":["id","state","publish_policy","brief","attempt","totals","resumable","created_at","items"],"properties":{"id":{"type":"string","format":"uuid"},"state":{"$ref":"#/components/schemas/ContentRunState"},"publish_policy":{"$ref":"#/components/schemas/ContentRunPublishPolicy"},"recipe_id":{"type":"string","format":"uuid","nullable":true},"brief":{"type":"string"},"category":{"type":"string"},"post_id":{"type":"string","format":"uuid","nullable":true,"description":"The article this run wrote. Written once and reused for every site, so a resumed run places the SAME copy rather than paying for a second generation."},"attempt":{"type":"integer","minimum":0,"description":"Which pass over the failures this is. 0 is the original run."},"workflow_id":{"type":"string"},"totals":{"$ref":"#/components/schemas/ContentRunTotals"},"reason":{"allOf":[{"$ref":"#/components/schemas/ContentRunFailureReason"}],"nullable":true},"provider":{"type":"string","nullable":true},"message":{"type":"string","nullable":true,"description":"An English sentence for the customer. Clients should render their own localised text from `reason` and fall back to this only for a code they do not know."},"resumable":{"type":"boolean","description":"Whether a resume would actually do anything. False on a paused run with nothing failed — do not offer the button when this is false."},"started_at":{"type":"string","format":"date-time","nullable":true},"finished_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"items":{"type":"array","items":{"$ref":"#/components/schemas/ContentRunItem"}}}},"ContentRunAnchor":{"type":"object","description":"A link to weave into the article. The URL and the exact anchor text are placed verbatim and verified after generation.","required":["url","text"],"properties":{"url":{"type":"string","format":"uri"},"text":{"type":"string","minLength":1,"maxLength":300}}},"ContentRunCreate":{"type":"object","required":["brief","site_ids"],"properties":{"brief":{"type":"string","minLength":1,"maxLength":4000},"site_ids":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"string","format":"uuid"}},"anchors":{"type":"array","maxItems":5,"items":{"$ref":"#/components/schemas/ContentRunAnchor"}},"category":{"type":"string","maxLength":200},"publish_policy":{"allOf":[{"$ref":"#/components/schemas/ContentRunPublishPolicy"}],"default":"draft_only"},"recipe_id":{"type":"string","format":"uuid","nullable":true}}},"ContentRunFailureReason":{"type":"string","description":"Why something stopped, as a stable code. Clients render their own localised sentence from this; the `message` field beside it is the English fallback for a code a client does not know yet.\n\n`provider_outage` — the model provider is down or timing out; retries, and resumes by itself.\n\n`rate_limited` — the provider asked us to slow down; the whole queue backs off for that provider and carries on.\n\n`credential_invalid` — the saved API key was refused. Never retried. Replace the key and the run continues from where it stopped.\n\n`provider_billing` — the customer's own account with the provider has no credit. Distinct from a bad key because the remedy is different, and distinct from a rate limit because some providers deliver it as a 429.\n\n`entitlement_exhausted` — their Zinn® allowance or credit pack is spent. The default funding route, so this is the commonest reason a run stops.\n\n`target_unreachable` — that one site could not be reached. Skipped; the rest of the run continues.\n\n`permanent` — retrying will not change the answer (the site is suspended, has no CMS, or has moved to another account).","enum":["provider_outage","rate_limited","credential_invalid","provider_billing","entitlement_exhausted","target_unreachable","permanent"]},"ContentRunItem":{"type":"object","description":"One site's outcome inside a run.","required":["id","site_id","site_domain","state","attempts"],"properties":{"id":{"type":"string","format":"uuid"},"site_id":{"type":"string","format":"uuid"},"site_domain":{"type":"string"},"state":{"type":"string","enum":["pending","running","succeeded","failed","skipped"]},"reason":{"allOf":[{"$ref":"#/components/schemas/ContentRunFailureReason"}],"nullable":true},"error_code":{"type":"string","nullable":true,"description":"The narrower machine code from the layer that failed."},"detail":{"type":"string","nullable":true},"provider":{"type":"string","nullable":true},"attempts":{"type":"integer","minimum":0},"post_url":{"type":"string","nullable":true,"description":"Where the post landed. Null until it publishes."},"finished_at":{"type":"string","format":"date-time","nullable":true}}},"ContentRunPage":{"type":"object","required":["items","total","offset","limit","has_more"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ContentRun"}},"total":{"type":"integer","minimum":0},"offset":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1},"has_more":{"type":"boolean"}}},"ContentRunPublishPolicy":{"type":"string","description":"How far a run may go on its own. `draft_only` is the default and puts nothing live.","enum":["draft_only","draft_and_schedule","unattended"]},"ContentRunSchedule":{"type":"object","required":["id","enabled","interval_hours","next_run_at","brief","publish_policy","site_ids"],"properties":{"id":{"type":"string","format":"uuid"},"enabled":{"type":"boolean"},"interval_hours":{"type":"integer","minimum":1},"next_run_at":{"type":"string","format":"date-time"},"last_run_at":{"type":"string","format":"date-time","nullable":true},"last_run_id":{"type":"string","format":"uuid","nullable":true},"brief":{"type":"string"},"category":{"type":"string"},"publish_policy":{"$ref":"#/components/schemas/ContentRunPublishPolicy"},"site_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"recipe_id":{"type":"string","format":"uuid","nullable":true}}},"ContentRunSchedulePage":{"type":"object","required":["items","total"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ContentRunSchedule"}},"total":{"type":"integer","minimum":0}}},"ContentRunScheduleWrite":{"type":"object","description":"Create or update a cadence. On create, `brief` and `site_ids` are required; on update every field is optional.","properties":{"brief":{"type":"string","minLength":1,"maxLength":4000},"site_ids":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"string","format":"uuid"}},"anchors":{"type":"array","maxItems":5,"items":{"$ref":"#/components/schemas/ContentRunAnchor"}},"category":{"type":"string","maxLength":200},"publish_policy":{"$ref":"#/components/schemas/ContentRunPublishPolicy"},"interval_hours":{"type":"integer","minimum":1,"maximum":720},"enabled":{"type":"boolean"},"recipe_id":{"type":"string","format":"uuid","nullable":true}}},"ContentRunState":{"type":"string","description":"Where a run got to. `partial` is a real, honest, terminal answer and not a euphemism: some sites published and some did not, nothing is left to try, and the failures can be resumed without touching the successes.","enum":["pending","generating","publishing","succeeded","partial","failed","paused","cancelled"]},"ContentRunTotals":{"type":"object","required":["sites","succeeded","failed","skipped","pending"],"properties":{"sites":{"type":"integer","minimum":0},"succeeded":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"skipped":{"type":"integer","minimum":0},"pending":{"type":"integer","minimum":0}}},"ContentTargetFacetCount":{"type":"object","required":["value","label","count"],"properties":{"value":{"type":"string"},"label":{"type":"string"},"count":{"type":"integer","minimum":0}}},"ContentTargetFacets":{"type":"object","description":"Filter counts over the whole matching set. ⛔ The `unknown` suitability count includes every site that has never been probed — a facet counting only stored rows would report `unknown: 0` on an estate where nothing had been checked.","required":["total","suitability","product_line","cms","group"],"properties":{"total":{"type":"integer","minimum":0},"suitability":{"type":"array","items":{"$ref":"#/components/schemas/ContentTargetFacetCount"}},"product_line":{"type":"array","items":{"$ref":"#/components/schemas/ContentTargetFacetCount"}},"cms":{"type":"array","items":{"$ref":"#/components/schemas/ContentTargetFacetCount"}},"group":{"type":"array","items":{"$ref":"#/components/schemas/ContentTargetFacetCount"}}}},"ConvertedPurse":{"type":"object","required":["purpose","from_amount_minor","from_currency","to_amount_minor","to_currency"],"description":"One wallet purse moved across. ⛔ Purses convert independently and a restricted purse stays restricted — converting `ai` credit into `general` would quietly widen what the customer may spend it on.","properties":{"purpose":{"type":"string","description":"The purse (`general`, `ai`).","example":"general"},"from_amount_minor":{"type":"integer","format":"int64","description":"What was debited, in minor units of `from_currency` (§2.8)."},"from_currency":{"type":"string","minLength":3,"maxLength":3},"to_amount_minor":{"type":"integer","format":"int64","description":"What was granted, in minor units of `to_currency`."},"to_currency":{"type":"string","minLength":3,"maxLength":3}}},"CouponQuote":{"type":"object","required":["code","valid","reason","currency","items","discount_total_minor"],"properties":{"code":{"type":"string"},"valid":{"type":"boolean"},"reason":{"$ref":"#/components/schemas/CouponReason"},"message":{"type":["string","null"]},"kind":{"type":["string","null"],"enum":["percent","fixed",null]},"percent_off":{"type":["integer","null"]},"amount_off_minor":{"type":["integer","null"]},"amount_off_currency":{"type":["string","null"]},"scope":{"type":["string","null"],"enum":["first_period",null]},"currency":{"type":"string"},"items":{"type":"array","items":{"type":"object","required":["ref","discount_minor"],"properties":{"ref":{"type":"string"},"discount_minor":{"type":"integer"}}}},"discount_total_minor":{"type":"integer"}}},"CouponQuoteItem":{"type":"object","required":["ref","kind","amount_minor"],"properties":{"ref":{"type":"string","maxLength":64,"description":"The caller's own id for the item."},"kind":{"type":"string","enum":["hosting_plan","extra"]},"amount_minor":{"type":"integer","minimum":0,"description":"What the item would cost this period before the code, in minor units."},"plan_code":{"type":"string","maxLength":64},"extra_code":{"type":"string","maxLength":64}}},"CouponQuoteRequest":{"type":"object","required":["code","currency","items"],"properties":{"code":{"type":"string","maxLength":64},"currency":{"$ref":"#/components/schemas/CurrencyCode"},"org_id":{"$ref":"#/components/schemas/Uuid"},"items":{"type":"array","minItems":1,"maxItems":50,"items":{"$ref":"#/components/schemas/CouponQuoteItem"}}}},"CouponReason":{"type":["string","null"],"description":"Why a code does not apply (null when it does). Stable values the surfaces translate.","enum":["not_found","inactive","not_started","expired","exhausted","already_used","not_eligible","currency_mismatch",null]},"CrawlerBlock":{"type":"object","required":["site_id","blocked_bots","available_bots"],"properties":{"site_id":{"$ref":"#/components/schemas/Uuid"},"blocked_bots":{"type":"array","items":{"type":"string"},"description":"Crawler keys currently blocked at the server level."},"available_bots":{"type":"array","items":{"type":"string"},"description":"The crawlers the customer may block. Contains no search engine, which is what makes de-indexing yourself impossible through this surface."},"enforcement":{"$ref":"#/components/schemas/CrawlerEnforcement"}}},"CrawlerBlockUpdate":{"type":"object","additionalProperties":false,"required":["blocked_bots"],"properties":{"blocked_bots":{"type":"array","items":{"type":"string"}}}},"CrawlerCatalogEntry":{"type":"object","required":["key","name"],"properties":{"key":{"type":"string","example":"ahrefs"},"name":{"type":"string","example":"Ahrefs (AhrefsBot)"}}},"CrawlerEnforcement":{"type":"object","required":["supported","applied","reason"],"description":"Whether the stored crawler policy is actually a rule on a web server, and if not why not (#1954, D8300).\n\n⛔ These are two different questions and collapsing them is the defect this schema exists to prevent. `supported` is a property of the site's PLATFORM and is answerable without contacting anything; `applied` is a claim only a successful WRITE can make, so it is `false` on a read unless a previous write recorded success on the policy row. Inferring \"enforced\" from \"a policy row exists\" is precisely how nine backlink crawlers were reported blocked while every one of them was served a `200`.","properties":{"supported":{"type":"boolean","description":"Whether this site's platform can carry server-level crawler rules."},"applied":{"type":"boolean","description":"Whether the rules are currently written to the site's web server."},"reason":{"type":"string","description":"Empty when supported and applied; otherwise why the stored policy is not a rule on a server. `pending` (D30500) is what a save answers on a supported platform: the policy is stored and a background workflow is writing it to the server now; re-read the policy until the reason changes to `\"\"` (enforced) or to the failure the workflow recorded. A save never waits for the server.","enum":["","vendor_platform","external_host","edge_host","unsupported_driver","failed","never_applied","pending"]}}},"CrawlerPolicy":{"type":"object","required":["blocked","robots_txt","ip_deny","is_override","is_pbn_line"],"properties":{"blocked":{"type":"array","description":"The blocked SEO-crawler keys (never a search engine).","items":{"type":"string"},"example":["ahrefs","semrush"]},"robots_txt":{"type":"boolean","description":"Whether a robots.txt Disallow is also published for the blocked crawlers."},"ip_deny":{"type":"boolean","description":"Whether the optional known-IP/ASN deny tier is enabled."},"is_override":{"type":"boolean","description":"True if these are a stored override; false if the computed line default."},"is_pbn_line":{"type":"boolean","description":"Whether the site is on the PBN (footprint) line."}}},"CrawlerPolicyRendered":{"type":"object","description":"The rendered rule artifacts for the worker / Zinn® plugin to write.","properties":{"robots_txt":{"type":"string"},"apache":{"type":"string"},"nginx":{"type":"string"}}},"CrawlerPolicyResponse":{"type":"object","required":["site_id","policy","available_crawlers","rendered"],"properties":{"site_id":{"$ref":"#/components/schemas/Uuid"},"policy":{"$ref":"#/components/schemas/CrawlerPolicy"},"available_crawlers":{"type":"array","items":{"$ref":"#/components/schemas/CrawlerCatalogEntry"}},"rendered":{"$ref":"#/components/schemas/CrawlerPolicyRendered"},"enforcement":{"$ref":"#/components/schemas/CrawlerEnforcement"}}},"CrawlerPolicyWrite":{"type":"object","required":["blocked"],"properties":{"blocked":{"type":"array","description":"Crawler keys to block (from the catalog's `available_crawlers`). An unknown key is a 422; a search engine has no key and can never be blocked.","items":{"type":"string","maxLength":64},"example":["ahrefs","semrush"]},"robots_txt":{"type":"boolean","default":true},"ip_deny":{"type":"boolean","default":false}}},"CreateCertificateOrderRequest":{"type":"object","required":["product_code","common_name","currency"],"additionalProperties":false,"properties":{"product_code":{"type":"string"},"common_name":{"type":"string","maxLength":255,"description":"The primary domain. A leading `*.` is a wildcard and is refused on a product that does not cover one — the authority would accept it at order time and refuse it at issuance, after charging."},"currency":{"type":"string","minLength":3,"maxLength":3},"period_years":{"type":"integer","default":1,"minimum":1,"maximum":5},"domains":{"type":"array","items":{"type":"string","maxLength":255},"description":"Additional names. ⛔ Capped by the product's `included_domains` — what the **price** covers — not by what the authority would technically allow, because it bills names beyond the included count separately."}}},"CreateSiteTransfer":{"allOf":[{"$ref":"#/components/schemas/SiteTransferProposal"},{"type":"object","required":["recipient_email"],"properties":{"recipient_email":{"type":"string","format":"email","maxLength":254,"description":"Where to notify the recipient, and the record of who the sender meant to send it to. **Not** how the receiving organization is resolved — that is `target_org_id`."},"message":{"type":"string","maxLength":500,"description":"A note shown to the receiver. Never interpreted."}}}]},"CredentialField":{"type":"object","required":["key","secret"],"properties":{"key":{"type":"string","description":"The driver setting name, which is also the key it is stored under. Form, bundle and driver share one vocabulary, so there is no translation table to get wrong."},"secret":{"type":"boolean","description":"Whether to mask the input and treat it as write-only. ⛔ Account identifiers (`subscription_id`, `resource_group`) are deliberately **not** secret — masking them means a customer cannot check the field they are most likely to mistype."}}},"CryptoAutoRenewRequest":{"type":"object","required":["enabled"],"properties":{"enabled":{"type":"boolean"},"email":{"type":"string","format":"email","maxLength":254,"description":"Where NOWPayments sends the payment links. Defaults to the billing e-mail."}}},"CryptoAutoRenewState":{"type":"object","required":["available","enabled","status","subscription_id"],"properties":{"available":{"type":"boolean","description":"Whether customers can choose crypto auto-renew right now."},"enabled":{"type":"boolean"},"status":{"type":"string","enum":["off","scheduled","active"],"description":"`scheduled` — chosen; the first link is e-mailed at the next renewal. `active` — NOWPayments is sending links each period."},"subscription_id":{"$ref":"#/components/schemas/Uuid"},"email":{"type":"string"},"amount_minor":{"type":["integer","null"],"description":"The renewal amount each link asks for, tax included, in minor units."},"currency":{"type":["string","null"]},"interval_days":{"type":["integer","null"]},"vendor_status":{"type":"string","description":"The processor's last status (WAITING_PAY, PAID, PARTIALLY_PAID, EXPIRED) or empty."},"last_paid_at":{"type":["string","null"],"format":"date-time"}}},"CurrencyCode":{"type":"string","description":"ISO 4217 currency code (money is minor units + this code — CLAUDE.md §2.8).","pattern":"^[A-Z]{3}$","example":"USD"},"DataCentreLocation":{"type":"object","description":"One data centre the platform has activated and can create sites in. Carries no display name on purpose: the customer-facing city and country are translated strings the client resolves from `code`, and a flag is decorative — never the accessible name (docs/62 §3.5).","required":["code","country"],"additionalProperties":false,"properties":{"code":{"type":"string","description":"The lowercase vendor location code, and the i18n key suffix.","example":"lhr"},"country":{"type":"string","description":"ISO-3166 alpha-2, or empty when unknown. Empty is honest — the client renders no flag rather than a wrong one.","example":"GB"}}},"DatabaseLineConfig":{"type":"object","description":"The managed database a `managed_database` cart line buys (`docs/497` §8).\n\nThe values are **not trusted from here**: the engine re-resolves the whole purchase through the same validator fulfilment will use, so a size that is not on sale, a version we do not run, an engine/size mismatch, a name the organisation already uses or an account out of good standing is a `422` at add-to-cart — while the customer can still fix it, and before any money moves.","required":["label","size"],"properties":{"label":{"type":"string","maxLength":64,"description":"What the customer calls the database. Theirs, shown back verbatim, and never sent to the infrastructure — the cluster is named from the row's own id."},"size":{"type":"string","maxLength":32,"description":"A size code from `GET /v1/databases/catalogue` (`db_pg_s`, `db_my_m`). It is also the catalogue plan code that carries the price, so the two can never disagree."},"engine":{"type":"string","enum":["postgres","mysql"],"description":"Omitted uses the default engine. Must match the engine the `size` belongs to."},"engine_version":{"type":"string","maxLength":8,"description":"The engine major (`\"18\"`, `\"8.4\"`). Omitted resolves to the newest we offer for that engine, excluding any past-end-of-life carve-out, and the resolved value is pinned onto the line so the invoice and the built cluster agree."}}},"DefaultRegistrantEnvelope":{"type":"object","required":["registrant","complete","missing"],"properties":{"registrant":{"oneOf":[{"$ref":"#/components/schemas/Registrant"},{"type":"null"}],"description":"The organization's default registrant, or `null` when none is set."},"complete":{"type":"boolean","description":"Whether a registrar would accept it. A checkout that registers or transfers a domain needs `true` here or a `registrant` in its own body."},"missing":{"type":"array","items":{"type":"string"},"description":"The required fields that are blank. Empty when `complete`."}}},"DelegatedAccessRevoke":{"type":"object","required":["email"],"additionalProperties":false,"properties":{"email":{"type":"string","format":"email","maxLength":320},"site_ids":{"type":"array","minItems":1,"description":"Omitted revokes every site; given, only these.","items":{"type":"string","format":"uuid"}}}},"DelegatedAccessRevokeResult":{"type":"object","required":["revoked","membership_removed","wp_admin_sites","wp_admin_sites_stale_plugin"],"additionalProperties":false,"properties":{"revoked":{"type":"integer"},"membership_removed":{"type":"boolean"},"wp_admin_sites":{"type":"integer","description":"Sites where this person had opened WordPress admin from the dashboard recently enough for a live session to still exist, and where one is therefore being ended. Ending it happens on the site itself and only ever touches sessions the platform opened — never the owner's own WordPress logins."},"wp_admin_sites_stale_plugin":{"type":"integer","description":"How many of `wp_admin_sites` are running a Zinn® plugin older than the release that can end a live session. On those the person keeps WordPress admin until WordPress ends the session itself. Only sites whose plugin version was actually read are counted, so this is never a guess; the outcome for every site appears in that site's WordPress activity."}}},"DelegatedAccessSet":{"type":"object","required":["email","sites"],"additionalProperties":false,"properties":{"email":{"type":"string","format":"email","maxLength":320},"sites":{"type":"array","minItems":1,"description":"The EXACT sites the person should hold after the call.","items":{"type":"object","required":["site_id","role"],"additionalProperties":false,"properties":{"site_id":{"type":"string","format":"uuid"},"role":{"$ref":"#/components/schemas/SiteCollaboratorRole"}}}},"reason":{"type":"string","maxLength":300,"description":"Why this person is being given these sites. Required when the call writes a new grant for somebody with no reason on record; otherwise the reason on record is kept."},"expires_at":{"type":["string","null"],"format":"date-time","description":"Omitted leaves every end date as it is; null means until revoked, for every site."}}},"DelegatedPerson":{"type":"object","description":"One person and every unrevoked site they hold in this organisation. `status` is `active` when any site is in force, else `pending` when any waits for them to accept, else `expired`.","required":["email","user_id","name","status","site_count","reason","invited_at","accepted_at","invitation_expires_at","last_active_at","sites"],"additionalProperties":false,"properties":{"email":{"type":"string","format":"email"},"user_id":{"type":["string","null"],"format":"uuid","description":"Null for somebody who has only been invited."},"name":{"type":"string"},"status":{"type":"string","enum":["active","pending","expired"]},"site_count":{"type":"integer","description":"Sites in force or awaiting acceptance."},"reason":{"type":"string","description":"The most recent reason recorded for sharing with this person."},"invited_at":{"type":"string","format":"date-time"},"accepted_at":{"type":["string","null"],"format":"date-time","description":"When they accepted — or, shared with somebody already in the organisation, when access began. Null while pending."},"invitation_expires_at":{"type":["string","null"],"format":"date-time","description":"When a pending invitation stops being acceptable. Saving the person sends a lapsed one again."},"last_active_at":{"type":["string","null"],"format":"date-time"},"sites":{"type":"array","items":{"$ref":"#/components/schemas/DelegatedSite"}}}},"DelegatedSite":{"type":"object","description":"One site a person holds, as the delegated-access list reports it.","required":["grant_id","site_id","site_name","primary_domain","role","status","expires_at","created_at","last_used_at"],"additionalProperties":false,"properties":{"grant_id":{"type":"string","format":"uuid"},"site_id":{"type":"string","format":"uuid"},"site_name":{"type":"string"},"primary_domain":{"type":"string"},"role":{"$ref":"#/components/schemas/SiteCollaboratorRole"},"status":{"type":"string","enum":["pending","active","expired","revoked"],"description":"The engine's word for this grant, never recomputed by a client."},"expires_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"last_used_at":{"type":["string","null"],"format":"date-time","description":"The person's last request while this grant was live, to five minutes."}}},"Delegation":{"type":"object","required":["expected","nameservers","detected","live","state","answered_by","checked_at","last_delegated_at","next_check_at","drifted"],"description":"Where a domain's DNS delegation actually points. Several observations, not one boolean, because they answer different questions and collapsing them hides the only one that means the domain is live.\n\n⛔ **Key off `state`, not `detected`.** `detected` is a boolean and therefore cannot express \"we could not tell\", which is a real and common third answer that leads a customer to the opposite action from \"not delegated\". `detected` and `live` are kept for existing clients and mean exactly what they always did.","properties":{"expected":{"type":"array","description":"The delegation we ask the customer to set at their registrar. Resolved **per domain**, from the zone's own nameservers where the provider assigns them — Cloudflare issues each zone its own pair, so this is not a platform constant.","items":{"type":"string","maxLength":253},"example":["ns1.zinndigital.com","ns2.zinndigital.com"]},"nameservers":{"type":"array","description":"Where the domain delegates right now, as the public internet sees it — which is what the customer compares against `expected` to know what to change.","items":{"type":"string","maxLength":253},"example":["ns1.zinndigital.com","ns2.zinndigital.com"]},"detected":{"type":"boolean","description":"Whether the domain's **public** NS records include the nameservers we asked for, resolved from a public recursive resolver. This — not our configuration and not the DNS vendor's own flag — is what \"live\" means (docs/72 D243)."},"live":{"type":"boolean","description":"Whether the domain is being served by us right now."},"state":{"type":"string","enum":["delegated","not_delegated","external","unknown"],"description":"The four-valued answer, and the field a client should render from. `delegated` — every nameserver we asked for is present. `not_delegated` — we hold this domain's zone, we got a real answer, and our nameservers are not in it (an unregistered name counts); this is the one state that IS an instruction to go and change something. `external` — the domain resolves to real nameservers that are not the pair we predicted, **and the pair we predicted was a guess** because we hold no zone of our own for this name; its DNS is somewhere else on purpose, so render it as information plus an offer to move it, never as a fault. `unknown` — nobody would tell us; this is **never** an instruction to change anything, and a `200` carries it only when a domain last seen delegated could not be re-checked.\n\n⛔ `external` exists because `not_delegated` was being reported for correctly delegated domains: our own Cloudflare-served zones were compared against the platform nameserver constant, which they can never match, and the screen then instructed the customer to replace working nameservers (W41-N, docs/72 D22362)."},"answered_by":{"type":"string","enum":["resolver","registry","none"],"description":"Who answered. `resolver` is a public recursive resolver — what the internet sees. `registry` is the registry's own RDAP record, used as a fallback when the resolver says nothing and as corroboration before we ever tell a customer their domain has left us."},"checked_at":{"type":"string","format":"date-time","nullable":true,"description":"When this reading was taken."},"last_delegated_at":{"type":"string","format":"date-time","nullable":true,"description":"When we last saw this domain delegated to us. Null means it never has been — which is what separates \"waiting for you\" from \"this stopped working\"."},"next_check_at":{"type":"string","format":"date-time","nullable":true,"description":"When the background poller will look again, so a client can wait rather than poll blind. Null once the domain is live or the poller has given up."},"drifted":{"type":"boolean","description":"This domain was delegated to us and positively is not any more. A warning about something that broke, not a step still to do."},"served_by_us":{"type":["boolean","null"],"description":"Whether a one-time token placed in the site's files on our servers came back when fetched through the domain's PUBLIC name — the only reading that can say the domain reaches us from behind the customer's own CDN proxy, where nameservers and addresses hide the origin. `null` means not asked: the domain has no site, the site is not on our servers, or it is delegated to our own zone (where `state` already answers). ⛔ Never inferred from a matching page title."},"served_checked_at":{"type":["string","null"],"format":"date-time","description":"When `served_by_us` was last measured, or null for never."},"www_resolves":{"type":["boolean","null"],"description":"Whether `www.` in front of the domain has any public address. `null` means the lookup did not answer, never that the name is missing."},"dns_actions":{"type":"array","description":"Records the customer must add at THEIR DNS provider, exactly as written — only for a domain whose DNS we do not run (in a zone delegated to us, the platform publishes the record itself). Empty when nothing is needed.","items":{"type":"object","required":["type","name","value","reason"],"properties":{"type":{"type":"string","enum":["CNAME"]},"name":{"type":"string","description":"The full hostname to add."},"value":{"type":"string","description":"What the record points to."},"reason":{"type":"string","enum":["www_missing"]}}}},"mail_measured":{"type":"boolean","description":"Whether the domain's published mail (MX, SPF) has been read yet. While false, a `mail_mismatch` of `null` means NOT CHECKED, not \"matches\" — a client shows that beside any nameserver instruction rather than presenting it as verified."},"mail_mismatch":{"description":"Present when the mail our copy of this domain's DNS would serve differs from the mail the domain publishes today — so changing nameservers to `expected` would change where its mail goes. A client must NOT tell the customer to change nameservers while this is set. `null` when they agree, when the domain is already delegated to us, or when the published mail has not been measured yet. `zone_mx`/`zone_spf` include a record the customer created, changed or deleted through `/v1/domains/{domainId}/dns/records` (or the `dns_record_*` MCP tools) as soon as that write returns, not after the next reconcile.","oneOf":[{"type":"null"},{"type":"object","required":["published_mx","zone_mx","published_spf","zone_spf"],"properties":{"published_mx":{"type":"array","items":{"type":"string"}},"zone_mx":{"type":"array","items":{"type":"string"}},"published_spf":{"type":"string"},"zone_spf":{"type":"string"}}}]},"dns_advice":{"type":"string","enum":["keep_dns","records","nameservers"],"description":"Whether the customer may be told to change this domain's nameservers to `expected` at all (Q464). `keep_dns`: a partner moved the site here and the domain's DNS stays where it is for good, so a client must never ask for, or offer, a nameserver change. `records`: our copy of the zone is not ready to take the domain over (it would move the domain's mail, or it holds no record that would serve the domain), so a client must not ask for a nameserver change yet. `nameservers`: the instruction may be given. Decided by the engine on every read, from local state only."},"expected_ready":{"type":"boolean","nullable":true,"description":"D43760. `false` when the nameserver pair we hold for this domain serves no zone for it: the DNS provider dropped a zone that was never activated. `expected` is then empty and `dns_advice` is `records`, so a dead pair is never shown. Offer `POST /v1/domains/{domainId}/delegation/fresh-nameservers` instead. `null` when the domain is delegated to us, has no pair, or has not been measured."},"zone_removed_at":{"type":"string","format":"date-time","nullable":true,"description":"Owner order 1107#22. When our DNS zone for this domain was REMOVED because the domain was never delegated to it within the grace period (30 days; the daily `zinn-dns-zone-gc` sweep re-checks the public nameservers right before each delete). `expected_ready` is then `false` and `expected` empty. Our copy of the zone's records is kept: offer \"Regenerate DNS zone\", which is `POST /v1/domains/{domainId}/delegation/fresh-nameservers` (it re-creates the zone with those records and answers the new pair). `null` when the zone is live."}}},"DelegationVerdict":{"type":"object","description":"One press of the verify button on a signed-in domain's instruction card. The authenticated twin of `PublicNameserverCheck`'s verdict fields — same four outcomes, classified by the same code, so the two surfaces cannot drift.","additionalProperties":false,"required":["outcome","expected","observed","recheck_after_seconds"],"properties":{"outcome":{"type":"string","enum":["delegated","propagating","not_delegated","unknown"],"description":"`delegated` = done. `propagating` = the registry has our pair and public DNS has not caught up; the customer did it right and must simply wait. `not_delegated` = a real reading that it points elsewhere or nowhere. `unknown` = we could not find out. ⛔ `unknown` is not `not_delegated`, and `propagating` is not a failure."},"expected":{"type":"array","items":{"type":"string","maxLength":253},"description":"The pair to set, resolved **per domain** from the zone's own nameservers where the provider assigns them — never a platform constant (D1034)."},"observed":{"type":"array","items":{"type":"string","maxLength":253},"description":"Where it points right now — public DNS where that answered, the registry's record otherwise. Empty means the reading was positive and there was nothing there, not that the reading failed."},"recheck_after_seconds":{"type":"integer","nullable":true,"description":"Roughly how long to wait before pressing again, or `null` when there is nothing to wait for. A hint about the interface, not a claim about DNS propagation."}}},"DeletedSite":{"type":"object","description":"A site that has been deleted, and everything needed to decide whether it can come back. The record **outlives the site**, so it is still readable after the data itself has been destroyed — which is what lets a customer see that a site existed and when it became unrecoverable.","required":["id","site_id","org_id","primary_domain","reason","deleted_at","restorable","reason_code"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"site_id":{"allOf":[{"$ref":"#/components/schemas/Uuid"}],"description":"The site this was. May no longer exist as a row."},"org_id":{"$ref":"#/components/schemas/Uuid"},"primary_domain":{"type":"string","maxLength":253},"reason":{"type":"string","enum":["dunning","customer","staff","abuse","abandoned"],"description":"Why it was deleted. `abuse` is restorable by staff only — a one-click customer restore of a site removed for terms enforcement would undo the enforcement."},"deleted_at":{"type":"string","format":"date-time","description":"Soft delete — removed from serving. The data is still here."},"deleted_by":{"type":"string","maxLength":128},"purge_due_at":{"type":"string","format":"date-time","nullable":true,"description":"**When the backup is purged and the site becomes permanently unrecoverable.** ⛔ Computed by the engine from the live retention policy, by the same function the purge sweep selects on. Never recompute it client-side."},"purged_at":{"type":"string","format":"date-time","nullable":true,"description":"Hard delete. Non-null means the data is gone and no restore is possible."},"restored_at":{"type":"string","format":"date-time","nullable":true},"restorable":{"type":"boolean","description":"Whether a restore would succeed **right now**. Reflects a real check that the backup object exists in storage — not a status column."},"reason_code":{"type":"string","description":"Empty when restorable. Otherwise one of `no_backup`, `purged`, `domain_in_use`, `already_restored`, `abuse_hold`. ⛔ A **code**, rendered by the client through its own catalogue — never a sentence from the engine, which would be English for ever.","enum":["","no_backup","purged","domain_in_use","already_restored","abuse_hold"]}}},"DeletedSitePage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DeletedSite"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"DemoBudgetReport":{"type":"object","required":["demo","limit","period","spent","cap"],"properties":{"demo":{"type":"string","enum":["tranzly","chat","pbs","seo"],"description":"Which hands-on demo: `tranzly` (demo.tranzly.io), `chat` (demo.zinnchat.com), `pbs` (demo.pagebuildersandwich.com) or `seo` (demo.zinnseo.com). Visitors spend no AI on `pbs` and `seo`, so those two report the `ops_*` limits only."},"limit":{"type":"string","enum":["day_count","day_usd","month_usd","month_requests","day_calls","visitor_month_usd","ops_day_usd","ops_day_calls"],"description":"Which budget ran out. Not every demo has every limit (a pair the platform does not know answers `422`): `day_count`, `day_usd` and `day_calls` are the visitors' daily budgets on `tranzly` and `chat`; `month_usd` is the plugin's own monthly spending cap on those two; `month_requests` and `visitor_month_usd` are the chat demo's only; `ops_day_usd` and `ops_day_calls` are the site's own background work (translation, indexing, scheduled jobs) on every demo and never stop a visitor."},"period":{"type":"string","description":"`YYYY-MM-DD` for a `day_*` limit, `YYYY-MM` for a `month_*` limit (UTC)."},"spent":{"type":"number","minimum":0,"maximum":1000000},"cap":{"type":"number","minimum":0,"maximum":1000000},"count":{"type":"integer","minimum":0,"maximum":10000000,"description":"Visitor actions today, for the e-mail."}}},"DemoBudgetReportResult":{"type":"object","required":["event_id","duplicate"],"properties":{"event_id":{"type":"string","format":"uuid"},"duplicate":{"type":"boolean","description":"This budget was already reported for this period — nothing more was sent."}}},"DeployAndMigrate":{"allOf":[{"$ref":"#/components/schemas/MigrationCredentials"},{"type":"object","required":["site","ownership_attested"],"properties":{"ownership_attested":{"type":"boolean","default":false,"description":"⚠️ As on `SiteMigrationCreate`: recorded because it cannot be reconstructed afterwards, required, and not a legal control."},"site":{"type":"object","required":["primary_domain","product_line","stack_type"],"description":"The site to create. ⛔ **Nested rather than flattened**, and the nesting is load-bearing: `MigrationCredentials` already has a `host` (the server we are migrating *from*) and this needs `primary_domain` (the address we are migrating *to*). Side by side in one body, a customer — and a future reader — reads them as the same thing. Every field is forwarded verbatim to the same validation `POST /v1/sites` uses.","properties":{"primary_domain":{"type":"string","maxLength":253},"product_line":{"type":"string","maxLength":64},"stack_type":{"type":"string","maxLength":32,"description":"⛔ **Required.** `POST /v1/sites` refuses a create with no `stack_type` when no blueprint is named, so an optional field here is a `422` for every caller. It is deliberately not defaulted server-side: the migration applies the source's files and database onto whatever stack the site was created with, so guessing WordPress for a plain PHP site lands the estate on the wrong runtime with no error anywhere."},"plan_id":{"type":"string"},"name":{"type":"string","maxLength":200},"region":{"type":"string","maxLength":32},"org_id":{"type":"string"}}}}}]},"DeployStatus":{"type":"string","enum":["idle","queued","building","live","failed"],"description":"`idle` means the site has never been deployed. It is reported, never stored — a stored idle would be a second way to say \"no deployments\" that could contradict the first."},"DeployTarget":{"type":"string","enum":["fleet","cf_pages","github_pages","gitlab_pages","netlify","vercel","render","azure_swa","aws_amplify","external","twentyi_shared","twentyi_vps","twentyi_cloud","own_cloud","aws_cloud","gcp_cloud","plesk"],"description":"Where the site is published from. `fleet` is our own managed fleet; the rest are managed edge hosts, deployed to from a pooled account of ours or the customer's own connected one. A machine identifier the client localises, never rendered raw.\n\n`vercel` is reachable **only** with a connected Vercel account: its free tier is licensed for non-commercial use, so a site is refused rather than hosted on ours.\n\n`plesk` is a **third kind of place**, and it is neither of the two above: the site is a Plesk *subscription* on a box reached through a connected control panel (`GET /v1/panels/connections`). It is not fleet-placed — there is no box of ours to allocate — and unlike every other off-fleet target **we are still the DNS authority** for it, because the panel is a machine we or the customer operate rather than a hosting vendor that runs its own nameservers. A `plesk` site is the one target that carries `panel_connection_id`, and it is required: the connection is the only thing that says *which* box the site lives on, so a `plesk` site without one is not degraded, it is unreachable."},"DeployTrigger":{"type":"string","enum":["manual","push","rollback","provision"],"description":"What caused the deploy. Stored because `requested_by` cannot answer it for a push — the actor there is a webhook delivery, not a person."},"DeployablePlan":{"type":"object","description":"One plan the customer already holds that a site can be deployed into, plus the product lines it can take. Every field `SiteCapacity` defines means the same thing here and is disclosed under the same two gates; the fields below are what turns a capacity answer into somewhere a customer can actually click.\n\n⛔ A **card is a plan, not a line.** A single agency or reseller plan covers every line it can deploy to, so rendering one tile per line would put the customer back in front of the flat catalogue this endpoint exists to replace.","allOf":[{"$ref":"#/components/schemas/SiteCapacity"},{"type":"object","required":["product_line","covers_all_lines","lines"],"properties":{"product_line":{"type":"string","description":"The product line this entry's figures were resolved for — the plan's own line. Empty only for a staff grant, which has no plan.","example":"footprint_free"},"covers_all_lines":{"type":"boolean","description":"Whether this grant covers every site-hosting line rather than just its own. True for a staff organization and for an agency/reseller plan, whose whole purpose is hosting other people's sites — a reseller's client organizations hold no plan of their own, so a plan that covered only its own line would refuse every client site. Derived from the plan's `client_orgs` grant, never from a list of line codes.","example":false},"plan_code":{"type":"string","nullable":true,"description":"The plan's catalogue code. Null for a staff grant or a trial.","example":"pbn_25"},"plan_name":{"type":"string","nullable":true,"description":"The plan's name, as the customer knows it. This is what a Deploy card is titled and what a refusal names, so the customer knows which plan to upgrade rather than being told \"your plan\" when they hold several.","example":"PBN 25"},"subscription_id":{"allOf":[{"$ref":"#/components/schemas/Uuid"}],"nullable":true,"description":"The subscription being spent, so a deploy can be attributed to it. Null for a staff grant or a trial, neither of which has one."},"slot_addon":{"type":"string","nullable":true,"description":"The catalogue code of the add-on that buys one more website slot on this plan (`POST /v1/extras/{code}/purchase`), priced from the plan's own ladder. Null when the figures are undisclosed, the plan is uncapped, the plan belongs to a parent organization, or the line's ladder has no slot gap to price.","example":"site_slot_footprint_free"},"lines":{"type":"array","description":"The product lines a site may be created on against this plan. Never empty — a grant that can take a site on no line at all is not a deploy target and is omitted from `data` entirely.","items":{"type":"object","required":["code","name"],"properties":{"code":{"type":"string","example":"footprint_free"},"name":{"type":"string","example":"Footprint-Free Hosting"},"description":{"type":"string","example":"Bulk hosting for PBNs, built to leave no footprint."}}}}}}]},"DevRequest":{"type":"object","required":["id","reference","org_id","title","kind","status","created_at","work_logs"],"properties":{"id":{"type":"string","format":"uuid"},"reference":{"type":"string"},"org_id":{"type":"string","format":"uuid"},"site_id":{"type":"string","format":"uuid","nullable":true},"ticket_id":{"type":"string","format":"uuid","nullable":true},"title":{"type":"string"},"description":{"type":"string"},"kind":{"$ref":"#/components/schemas/DevRequestKind"},"status":{"$ref":"#/components/schemas/DevRequestStatus"},"access_consent":{"type":"boolean"},"estimate_note":{"type":"string"},"estimate_source":{"type":"string","nullable":true,"enum":["ai","ai_approved","staff"]},"quote":{"allOf":[{"$ref":"#/components/schemas/DevRequestQuote"}],"nullable":true},"approved_at":{"type":"string","format":"date-time","nullable":true},"logged_minutes":{"type":"integer"},"billed_covered_minutes":{"type":"integer"},"billed_extra_minutes":{"type":"integer"},"extra_amount_minor":{"type":"integer"},"currency":{"type":"string","nullable":true},"backup_at":{"type":"string","format":"date-time","nullable":true},"ready_at":{"type":"string","format":"date-time","nullable":true},"completed_at":{"type":"string","format":"date-time","nullable":true},"site_suspended":{"type":"boolean","description":"The site is suspended because this request's invoice is unpaid."},"created_at":{"type":"string","format":"date-time"},"work_logs":{"type":"array","items":{"type":"object","properties":{"minutes":{"type":"integer"},"note":{"type":"string"},"logged_at":{"type":"string","format":"date-time"}}}},"ai_draft":{"type":"object","nullable":true,"additionalProperties":true,"description":"Staff only."},"flagged_large":{"type":"boolean","description":"Staff only. Over 2 hours."},"auto_sent":{"type":"boolean","description":"Staff only."},"estimated_by":{"type":"string","description":"Staff only."}}},"DevRequestApprove":{"type":"object","additionalProperties":false,"required":["terms_version"],"properties":{"terms_version":{"type":"string","maxLength":32}}},"DevRequestCreate":{"type":"object","additionalProperties":false,"required":["title","description","kind","access_consent"],"properties":{"title":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":20000},"kind":{"$ref":"#/components/schemas/DevRequestKind"},"site_id":{"type":"string","format":"uuid","nullable":true},"access_consent":{"type":"boolean"},"org_id":{"type":"string","format":"uuid"},"currency":{"type":"string","maxLength":3}}},"DevRequestKind":{"type":"string","enum":["bug_fix","error","plugin","theme_code","version_breakage","small_tweak"]},"DevRequestList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DevRequest"}}}},"DevRequestNote":{"type":"object","additionalProperties":false,"required":["note"],"properties":{"note":{"type":"string","maxLength":5000}}},"DevRequestQuote":{"type":"object","properties":{"estimate_minutes":{"type":"integer"},"covered_minutes":{"type":"integer"},"extra_minutes":{"type":"integer"},"hourly_rate_minor":{"type":"integer"},"discount_bps":{"type":"integer"},"extra_amount_minor":{"type":"integer"},"currency":{"type":"string"},"code_care_saving":{"type":"array","nullable":true,"description":"Without Code Care, what each tier would have saved on this job.","items":{"type":"object","properties":{"tier":{"type":"string"},"saving_minor":{"type":"integer"}}}}}},"DevRequestStatus":{"type":"string","enum":["submitted","estimated","approved","in_progress","ready_for_check","completed","declined","cancelled"]},"DirectInvoicePaymentStart":{"type":"object","description":"What the pay page needs to finish, whichever rail was chosen. Exactly one of `client_token` / `redirect_url` is set on a live payment; `settled` is true for a zero-total document that completed with no gateway at all.","required":["status","settled","amount_minor","currency"],"properties":{"status":{"type":"string"},"settled":{"type":"boolean"},"amount_minor":{"type":"integer","format":"int64"},"currency":{"type":"string","minLength":3,"maxLength":3},"client_token":{"type":"string","description":"A card intent's client secret, for the browser SDK. It authorises confirming this one intent and nothing else."},"redirect_url":{"type":"string","description":"An approval page to send the payer to (PayPal, a crypto invoice)."},"action_kind":{"type":"string","description":"`setup` means no card is on file and `client_token` is a **SetupIntent** secret — confirm it, then call `/confirm`. Anything else is a live charge's own action."},"setup_intent_id":{"type":"string","description":"The SetupIntent the card form is mounted against, echoed back for the `/confirm` call. An id, not a secret: the server re-reads it from the gateway and refuses it unless the gateway says it belongs to this invoice's payer."}}},"DirectInvoicePortal":{"type":"object","description":"One invoice as the person paying it reads it. Every string is already in their language; the page that renders this holds no copy of its own.\n\n⛔ It carries no `internal_note`, no `created_by` and no `created_reason` — those are what we wrote about the recipient and who wrote it.","required":["reference","status","currency","issue_date","buyer","lines","subtotal","tax_total","total","amount_due","amount_due_minor","labels","direction","payable","rails"],"properties":{"reference":{"type":"string"},"status":{"type":"string","enum":["sent","paid"]},"currency":{"type":"string","minLength":3,"maxLength":3},"rails":{"type":"array","items":{"type":"string"},"description":"The payment methods this invoice may be settled on, in the order to show them, and filtered by its currency. Pass the chosen one back as `gateway` on the checkout call. Never empty — a registry that could not be read still offers the default, because \"we could not read the providers\" and \"there is no way to pay this\" are different things to tell somebody holding a bill."},"issue_date":{"type":"string","format":"date"},"due_date":{"type":"string","format":"date","nullable":true},"due_date_display":{"type":"string","description":"The due date in the reader's own convention, already formatted."},"buyer":{"type":"object","additionalProperties":{"type":"string"}},"lines":{"type":"array","items":{"type":"object","required":["description","quantity","unit_price","total"],"properties":{"description":{"type":"string"},"quantity":{"type":"string"},"unit_price":{"type":"string"},"total":{"type":"string"},"tax_note":{"type":"string","description":"The tax sentence for this line, in the reader's language. A staff member's own outside-scope reason is rendered verbatim and untranslated — machine-translating a tax position is not something there is a safe version of."}}}},"subtotal":{"type":"string"},"tax_total":{"type":"string"},"total":{"type":"string"},"total_minor":{"type":"integer","format":"int64"},"amount_due":{"type":"string","description":"Zero once paid. Computed, never stored — a page saying money is due beside a Paid badge is the worst thing this can render."},"amount_due_minor":{"type":"integer","format":"int64"},"notes":{"type":"string"},"labels":{"type":"object","description":"Every label on the document, in the reader's language.","additionalProperties":{"type":"string"}},"locale":{"type":"string"},"direction":{"type":"string","enum":["ltr","rtl"]},"payable":{"type":"boolean"}}},"DnsHolderMixHostname":{"type":"object","required":["name","host","holder_records","site_records"],"properties":{"name":{"type":"string","description":"The record name in the zone (`@`, `www`)."},"host":{"type":"string","example":"www.example.com"},"holder_records":{"type":"array","items":{"$ref":"#/components/schemas/DnsHolderMixRecord"}},"site_records":{"type":"array","items":{"$ref":"#/components/schemas/DnsHolderMixRecord"}}}},"DnsHolderMixRecord":{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","example":"A"},"value":{"type":"string","example":"203.0.113.10"}}},"DnsHolderRowsRemoved":{"type":"object","required":["domain_id","removed"],"properties":{"domain_id":{"type":"string","format":"uuid"},"removed":{"type":"array","description":"The holder rows deleted at the provider. Empty when nothing was mixed.","items":{"type":"object","required":["name","type","value"],"properties":{"name":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"}}}}}},"DnsRecord":{"type":"object","description":"A DNS resource record in a domain's hosted zone.","required":["id","name","type","value","ttl","owner"],"properties":{"id":{"type":"string","description":"The provider-assigned record id."},"name":{"type":"string","description":"The record name — `@` for the apex, or a relative/absolute host.","example":"www"},"type":{"$ref":"#/components/schemas/DnsRecordType"},"value":{"type":"string","description":"The record value (target/content).","example":"203.0.113.10"},"ttl":{"type":"integer","minimum":60,"maximum":604800,"description":"Time-to-live in seconds."},"priority":{"type":["integer","null"],"minimum":0,"maximum":65535,"description":"Priority for MX (preference), SRV (priority) and SVCB/HTTPS (SvcPriority, `0` = alias mode); null otherwise."},"proxied":{"type":["boolean","null"],"description":"Whether this record is served through the provider's HTTP proxy — Cloudflare's **orange cloud**. Applies to `A` and `AAAA`; providers without a proxy ignore it.\n\n⛔⛔ **Three states, and `null` is not \"off\".** `null` means *no per-record opinion* — the organisation's default applies — and it is what every record created before this field existed means. `true`/`false` is a decision about this record, and an explicit `false` is honoured even when the organisation's default is on, so *\"leave this one grey\"* cannot be silently overruled.\n\n⭐ This is what lets one zone mix proxied and unproxied `A` records. It matters most for **footprint-free hosting**: an unproxied record publishes the shared origin IP of the box the site sits on, which is the footprint the product line exists to remove — while a *proxied* mail host is undeliverable, because the proxy carries HTTP and HTTPS only.\n\n⚠️ **A record that an `MX` in the same zone points at is never proxied**, whatever is requested here, and the response will show `false` for it. That refusal is deliberate: orange-clouding a mail host does not degrade delivery, it ends it."},"owner":{"$ref":"#/components/schemas/DnsRecordOwner"},"drift":{"$ref":"#/components/schemas/DnsRecordDrift"}}},"DnsRecordCheck":{"allOf":[{"$ref":"#/components/schemas/DnsRecordPlan"},{"type":"object","required":["observed","ok","answered"],"properties":{"observed":{"type":"array","nullable":true,"items":{"type":"string"},"description":"What a public resolver answers for this name and type. `null` means the resolver did not answer at all (SERVFAIL, REFUSED, a transport failure); `[]` means it answered that nothing is published there. These are NOT the same and a client must not render both as a failure — the first is unknown."},"ok":{"type":"boolean","description":"Whether the wanted value is live. False when the resolver did not answer, so read `answered` first."},"answered":{"type":"boolean","description":"Whether the resolver gave any answer, including NXDOMAIN."}}}]},"DnsRecordDrift":{"type":"string","nullable":true,"enum":["changed","deleted"],"description":"What the last reconcile found about a **platform-owned** record at the provider,\nor `null` when the provider agrees with us (the overwhelmingly common case).\n\n`changed` — a record with this name and type is at the provider with a different\nvalue. `deleted` — nothing with this name and type is at the provider any more.\n\n⛔ Reported, **never auto-healed** (`docs/89` §1). A platform record a human\ndeliberately changed at the provider is a decision to surface to the customer or\noperator; silently converging it back is the same defect in the opposite\ndirection. Only platform-owned records can drift by construction — a customer\nrecord changing is not divergence, it is the customer using their own DNS.\n"},"DnsRecordList":{"type":"object","required":["data","page"],"description":"A **page** of a zone's records. This was the platform's last unbounded collection (issue #466): the whole zone came back in one response and the dashboard rendered it unvirtualised, so a 5,000-record zone was 5,000 DOM rows. Walk `page.next_cursor` until `page.has_more` is false — a client that reads only the first page has read only the first page.","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DnsRecord"}},"page":{"$ref":"#/components/schemas/PageMeta"},"hosted":{"type":"boolean","description":"Whether this platform hosts the domain's zone. `false` only on a `?not_hosted=empty` answer, where the empty `data` means \"no zone here\", not \"no records\"."},"supported_types":{"type":"array","description":"The record types this zone's DNS provider can hold, in a stable order — what an editor should offer. A write of any other type is refused with `422` (`refusal.dns.typeNotSupported`).","items":{"$ref":"#/components/schemas/DnsRecordType"},"example":["A","AAAA","CNAME","MX","TXT","SRV","CAA","NS","PTR","TLSA","SVCB","HTTPS"]}}},"DnsRecordOwner":{"type":"string","enum":["platform","customer"],"description":"Who may change this record. `platform` means the platform created it and converges it — the A/AAAA record at the apex or `www` that points the domain at the hosting we run for it. Editing one would point the domain away from the hosting the customer is paying for and deleting one would take the site offline, so both are refused with `409 PLATFORM_RECORD`; a client should render the record read-only rather than offering an action that will be refused.\n\nOn a **parked** domain (no site attached) the apex and `www` carry only the holding page, and only a record pointing at a holding-page address is `platform`. The customer may edit it to their own IP or add their own A/AAAA at that name — the holding-page records there are then removed — but deleting it is refused with `409 PLATFORM_RECORD`, because the holding page would only return.\n\n`customer` means the record is theirs — created at the provider or in our dashboard. We read it, we display it, and we never rewrite or delete it. **Anything we did not create is `customer`**, which is the safe direction: guessing the other way is how a reconcile deletes a customer's `MX`.\n\nOn the Footprint-Free line the platform's address records are not returned at all (they publish the shared fleet IP, the strongest footprint signal), so a client on that line will only ever see `customer`.","example":"customer"},"DnsRecordPlan":{"type":"object","description":"One record the customer's zone must carry for this hostname to serve.","required":["name","type","value","ttl"],"properties":{"name":{"type":"string"},"type":{"type":"string","enum":["A","AAAA","CNAME","TXT"]},"value":{"type":"string"},"ttl":{"type":"integer"}}},"DnsRecordType":{"type":"string","description":"A DNS resource-record type the shared editor supports (docs/31 §5.2). Not every provider holds every type: the record list's `supported_types` names the ones this zone's provider can hold, and a write of any other type is refused with `422` (`refusal.dns.typeNotSupported`). `DS` is not here because it lives in the parent zone (the registrar's DNSSEC call); `SOA` is the provider's own.\n\nValue grammar for the structured types (stored in one canonical spelling): `SRV` `weight port target` with `priority`; `CAA` `flags tag \"value\"` (tag `issue`, `issuewild`, `iodef`, `issuemail`, `issuevmc`, `contactemail`, `contactphone`); `TLSA` `usage selector matching-type hex`; `PTR` a host name; `SVCB`/`HTTPS` `target key=value …` with `priority` as the SvcPriority (`0` = alias mode, target only; `.` = the owner name itself).","enum":["A","AAAA","CNAME","MX","TXT","SRV","CAA","NS","PTR","TLSA","SVCB","HTTPS"]},"DnsRecordWrite":{"type":"object","description":"Create/replace a DNS record. Priority is required for MX/SRV/SVCB/HTTPS and rejected otherwise. The value of a structured type (SRV, CAA, TLSA, PTR, SVCB, HTTPS) must fit its grammar (see `DnsRecordType`) or the write is a `422` naming the field; it is stored in the canonical spelling. A value the provider itself refuses is a `422` (`refusal.dns.recordRejected`).","required":["name","type","value"],"properties":{"name":{"type":"string","maxLength":253,"description":"The record name — `@`/empty for the apex, or a relative/absolute host.","example":"www"},"type":{"$ref":"#/components/schemas/DnsRecordType"},"value":{"type":"string","maxLength":2048,"example":"203.0.113.10"},"ttl":{"type":"integer","minimum":60,"maximum":604800,"default":3600},"priority":{"type":["integer","null"],"minimum":0,"maximum":65535},"proxied":{"type":["boolean","null"],"description":"Serve this record through the provider's HTTP proxy — Cloudflare's orange cloud. **`A` and `AAAA` only**; sending it on any other type is a `422` rather than a silent drop, because a request we can never satisfy must not leave the caller believing their origin is hidden.\n\n⛔ **Omitting it means *no per-record opinion*, NOT \"off\".** The organisation's default then applies, which is what every record created before this field existed already does. A client that has never heard of proxying therefore keeps behaving exactly as it did — where a `false` default would have it un-proxy every record it touched, publishing origin IPs one edit at a time.\n\nAn explicit `false` is honoured even when the organisation's default is on. ⚠️ An explicit `true` is **not** honoured for a record an `MX` in the same zone points at: the proxy carries HTTP and HTTPS only, so orange-clouding a mail host ends delivery rather than degrading it."}}},"DnsSoa":{"type":"object","required":["nameservers","soa"],"description":"A zone's SOA as its authoritative nameservers serve it (read-only).","properties":{"nameservers":{"type":"array","description":"The nameservers that were asked.","items":{"type":"string"},"example":["ns1.zinndigital.com","ns2.zinndigital.com"]},"soa":{"oneOf":[{"$ref":"#/components/schemas/DnsSoaRecord"},{"type":"null"}]}}},"DnsSoaRecord":{"type":"object","required":["primary_nameserver","hostmaster","serial","refresh","retry","expire","minimum_ttl"],"properties":{"primary_nameserver":{"type":"string","example":"ns1.zinndigital.com"},"hostmaster":{"type":"string","description":"The zone administrator's mailbox (the SOA RNAME as an address).","example":"hostmaster@zinndigital.com"},"serial":{"type":"integer","format":"int64","example":2026102001},"refresh":{"type":"integer","description":"Seconds","example":7200},"retry":{"type":"integer","description":"Seconds","example":900},"expire":{"type":"integer","description":"Seconds","example":1209600},"minimum_ttl":{"type":"integer","description":"Seconds a resolver may cache a \"no such record\" answer.","example":300}}},"DnsSyncResult":{"type":"object","required":["synced","record_count","event_emitted"],"properties":{"synced":{"type":"boolean"},"record_count":{"type":"integer","description":"The number of records visible to this product line at sync time (on the PBN line the hidden platform IP records are excluded — register #93)."},"event_emitted":{"type":"boolean","description":"Whether the domain.dns_changed propagation event was published."}}},"Domain":{"type":"object","description":"A registered or connected domain. The registrar reference, credential connection and auth-code are engine secrets and are never returned (§2.4).","required":["id","org_id","fqdn","sld","tld","ownership_mode","status","auto_renew","renew_years","nameservers","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"org_id":{"$ref":"#/components/schemas/Uuid"},"fqdn":{"$ref":"#/components/schemas/Hostname"},"sld":{"type":"string","example":"acme"},"tld":{"type":"string","example":"com"},"product_line":{"type":"string","description":"The product line this domain was created on. **Not decoration** — it is what decides whether the shared fleet A/AAAA records are hidden from the customer (register #93), so the dashboard gates its record editor on it and **fails closed when it is absent**. Omitted for weeks, which meant a connected domain with no linked site could never resolve a line and the editor refused to offer A/AAAA at all — on exactly the customers who came to point a domain at their server.","example":"mainstream"},"ownership_mode":{"type":"string","enum":["registered","connected","transferring_in"]},"status":{"$ref":"#/components/schemas/DomainStatus"},"registered_at":{"type":["string","null"],"format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time"},"auto_renew":{"type":"boolean"},"renew_years":{"type":"integer","minimum":1},"registrar_lock":{"type":"boolean"},"privacy_enabled":{"type":"boolean"},"nameservers":{"type":"array","items":{"type":"string"},"description":"On a `connected` domain this is the nameserver pair we EXPECT the customer to set at their registrar, not what the registry answers; `delegation_state` is the observed answer."},"dnssec_enabled":{"type":"boolean"},"site_id":{"description":"The site this domain points at, if any.","anyOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]},"delegation_state":{"description":"What we last observed about where this domain delegates (`delegated`, `not_delegated`, `pending`, `unknown`, ...), or null when it has never been checked.","anyOf":[{"type":"string"},{"type":"null"}]},"site_serves":{"type":"boolean","description":"True when the linked site really answers on this name (its primary domain or an alias). False for an unlinked domain, and for one whose move onto the site has not completed."},"origin_served":{"description":"Whether the public name reached our origin on the last reach probe (a nonce in the site's docroot fetched through the name). `site_serves` is the site's configuration; this is a visitor's reach. Null when never asked (no site, or delegated to our own zone, where delegation already answers it).","anyOf":[{"type":"boolean"},{"type":"null"}]},"attach_state":{"$ref":"#/components/schemas/DomainAttachState"},"observed_nameservers":{"description":"The delegation the public DNS answered at the last probe, or null when never read. `nameservers` is the pair we asked for; this is the pair in use.","anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"DomainAlertSearch":{"type":"object","description":"A saved aged-domain search (Q321).","required":["id","name","params","active","paused_reason","matches_now","new_total","last_run_at","last_sent_at","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"params":{"type":"object","description":"The normalised aged-domain list filters this search matches.","additionalProperties":true},"active":{"type":"boolean"},"paused_reason":{"type":["string","null"],"enum":["by_you","over_plan",null],"description":"`over_plan` — paused by the daily run because a plan ended; resume within the allowance."},"matches_now":{"type":"integer","description":"Domains on sale matching it at its last run."},"new_total":{"type":"integer","description":"New domains announced since it was saved."},"last_run_at":{"type":["string","null"],"format":"date-time"},"last_sent_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"DomainAlerts":{"type":"object","required":["allowed","unlimited","free","active","hard_max","plans","searches"],"properties":{"allowed":{"type":["integer","null"],"description":"Active searches allowed; null when unlimited."},"unlimited":{"type":"boolean"},"free":{"type":"integer","description":"Active searches every organisation keeps with no plan."},"active":{"type":"integer"},"hard_max":{"type":"integer","description":"Saved searches an organisation may keep at all","paused included.":null},"plans":{"type":"array","items":{"type":"object","required":["code","searches"],"properties":{"code":{"type":"string"},"searches":{"type":"integer"}}}},"searches":{"type":"array","items":{"$ref":"#/components/schemas/DomainAlertSearch"}}}},"DomainAttachState":{"type":"string","description":"The one state a customer is shown for a domain (engine `domains.attach_state`, docs/823 §13), in ladder order: `not_attached` (no site serves the name, none has it added, and no running domain change is attaching it), `getting_certificate` (attached AND this site's own probe token came back through the name, measured per site and name; a DNS answer alone, such as a Cloudflare address, never counts: a certificate is the only step left) or `live` (that probe plus a verifying TLS handshake), `nameservers_elsewhere` (we gave it our nameservers and the real public delegation is another provider's), `no_address_record` (the resolver answered, NXDOMAIN or empty, and no A/AAAA record lands on us), `unknown` (a leg could not be read, including a failed DNS lookup; never a verdict). A name a running domain change is attaching has the same state here as in `getSiteRenameStatus.domain_state`.","enum":["not_attached","nameservers_elsewhere","no_address_record","getting_certificate","live","unknown"]},"DomainCheckRequest":{"type":"object","required":["fqdn"],"properties":{"fqdn":{"type":"string","description":"The domain to check. A pasted URL is accepted and normalised down to the hostname; `www.` is stripped, because it and the apex are one domain to every metrics provider and showing two figures for one asset would mislead a purchase."},"force":{"type":"boolean","default":false,"description":"Fetch even if a fresh cached reading exists. ⛔ Spends a billed unit — leave it false unless the customer explicitly asked for a new number."}}},"DomainCheckResult":{"description":"A checked domain's reading, plus the research allowance as it stands after the call. The metric half is identical to `DomainSeoMetrics`; the two extra fields exist so a client can render the meter without a second round trip and can tell the customer whether this particular answer cost them anything.","allOf":[{"$ref":"#/components/schemas/DomainSeoMetrics"},{"type":"object","required":["spent_lookup","quota"],"properties":{"spent_lookup":{"type":"boolean","description":"False when the answer came from a recent stored reading and cost nothing."},"quota":{"$ref":"#/components/schemas/SeoLookupQuota"}}}]},"DomainConnectRequest":{"type":"object","required":["fqdn"],"properties":{"fqdn":{"type":"string","maxLength":253,"description":"The domain to host DNS for. Must be a zone apex, not a subdomain.","example":"example.com"},"org_id":{"allOf":[{"$ref":"#/components/schemas/Uuid"}],"nullable":true,"description":"The organization to connect it in. Optional when the caller holds `domains.dns.manage` in exactly one org; required otherwise."}}},"DomainContact":{"type":"object","required":["first","last","email","phone","street","city","postcode","country"],"description":"An ICANN registrant contact. Every field is required on write — a registrant change is one record, not a set of independently patchable fields.","properties":{"first":{"type":"string","maxLength":128},"last":{"type":"string","maxLength":128},"org_name":{"type":"string","maxLength":200},"email":{"type":"string","format":"email"},"phone":{"type":"string","maxLength":32,"description":"E.164-ish. Validated permissively on purpose — the registry is the authority on what it accepts, and a client-side rule that refused a legitimate international number would be a bug a customer cannot work around."},"street":{"type":"array","minItems":1,"maxItems":3,"items":{"type":"string","maxLength":255}},"city":{"type":"string","maxLength":128},"state":{"type":"string","maxLength":128,"description":"May be blank — most of the world has no state. The Cloudflare adapter substitutes the city where its API demands one."},"postcode":{"type":"string","maxLength":32},"country":{"type":"string","minLength":2,"maxLength":2}}},"DomainContactEnvelope":{"type":"object","required":["contact","editable"],"properties":{"contact":{"oneOf":[{"$ref":"#/components/schemas/DomainContact"},{"type":"null"}]},"editable":{"type":"boolean","description":"Whether this domain's registrar publishes a contact-update path. `false` on the Cloudflare route; the console renders the panel read-only rather than offering a control that answers 422."}}},"DomainEmailRouting":{"type":"object","required":["domain_id","fqdn","supported","enabled","status","dns_ready","plan","rules","catch_all","addresses","addresses_readable","rules_readable","status_readable","impact"],"properties":{"domain_id":{"$ref":"#/components/schemas/Uuid"},"fqdn":{"type":"string","example":"example.com"},"supported":{"type":"boolean","example":true},"enabled":{"type":"boolean","example":false},"status":{"type":"string","description":"The provider's own word for the zone's state. Displayed, never branched on.","example":"unconfigured"},"dns_ready":{"type":"boolean","description":"Whether the provider reports the required DNS actually live. Distinct from `enabled` — a zone can be switched on with its `MX` not yet resolving.","example":false},"plan":{"type":"array","items":{"$ref":"#/components/schemas/DomainEmailRoutingDnsRecord"}},"rules":{"type":"array","items":{"$ref":"#/components/schemas/DomainEmailRoutingRule"}},"catch_all":{"allOf":[{"$ref":"#/components/schemas/DomainEmailRoutingRule"}],"nullable":true},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/DomainEmailRoutingAddress"}},"addresses_readable":{"type":"boolean","description":"`false` when the credential could not list destination addresses — a scope a customer's own token may legitimately lack. Separate from an empty `addresses` list, because an empty list means both and only one of them is actionable.","example":true},"rules_readable":{"type":"boolean","description":"`false` when the credential could not list the forwarding rules. `Zone → Email Routing Rules` is a **separate** Cloudflare permission from the one that reads the zone's routing status and its DNS plan, so a token can legitimately answer this endpoint with a complete `status`, a complete `plan` and no `rules` at all.\n\n⛔ Separate from an empty `rules` array for the same reason `addresses_readable` is, and it matters more here: \"this domain forwards no mail\" is exactly what a customer would conclude before switching routing off. When this is `false` the `rules` and `catch_all` fields carry no information and must not be rendered as an empty rule set.","example":true},"status_readable":{"type":"boolean","description":"`false` when the credential could not read the zone's routing **settings** — the half that supplies `enabled`, `status`, `dns_ready` and `plan`. On Cloudflare this is a different permission from the one that lists forwarding rules, measured 2026-08-31: a token holding only the rules group reads the rule list on every attempt and the settings endpoint on none.\n\n⛔ When this is `false`, `enabled` is `false` because it is **unknown**, not because routing is off, and `plan` is empty because it could not be read rather than because nothing would change. A client must render \"we could not read this\" and must not offer the enable action as safe — `impact` is `unreadable` in this state for exactly that reason, so enabling still requires the typed confirmation.","example":true},"impact":{"$ref":"#/components/schemas/DomainEmailRoutingImpact"}}},"DomainEmailRoutingAddress":{"type":"object","description":"A destination a rule may forward to. **Account-scoped at the provider**, so one address book serves every domain on the account.","required":["address_id","email","verified","created"],"properties":{"address_id":{"type":"string"},"email":{"type":"string","format":"email"},"verified":{"type":"boolean","description":"A fact about the **recipient's** action, never ours: the provider emails a verification link and will not deliver until it is clicked.","example":false},"created":{"type":"string"}}},"DomainEmailRoutingAddressWrite":{"type":"object","additionalProperties":false,"required":["email"],"properties":{"email":{"type":"string","format":"email","description":"**The provider emails this address a verification link.** It is a write that reaches a third party, so it is permissioned and audit-logged accordingly.","example":"owner@example.com"}}},"DomainEmailRoutingCatchAllWrite":{"type":"object","additionalProperties":false,"required":["destinations"],"properties":{"destinations":{"type":"array","maxItems":20,"items":{"type":"string","format":"email"}},"action":{"$ref":"#/components/schemas/EmailRoutingAction"},"enabled":{"type":"boolean","default":true}}},"DomainEmailRoutingDnsRecord":{"type":"object","description":"One record the provider says it would publish to make routing work. Read from the provider on every call, never composed here: the set changes, and a stale copy would under-report what a customer is about to lose.","required":["name","type","value"],"properties":{"name":{"type":"string","example":"example.com"},"type":{"type":"string","example":"MX"},"value":{"type":"string","example":"route1.mx.cloudflare.net."},"priority":{"type":"integer","nullable":true,"example":33}}},"DomainEmailRoutingEnable":{"type":"object","additionalProperties":false,"properties":{"confirm_domain":{"type":"string","description":"The domain's own name, typed. Required only when `impact.safe` is `false`. A string rather than a boolean deliberately: a boolean would be settable by a client that never showed the customer what they were about to lose.","example":"example.com"}}},"DomainEmailRoutingImpact":{"type":"object","description":"What turning routing on would replace, measured against the zone's live records.","required":["safe","reason","existing_apex_mx","foreign_mx","foreign_spf_includes","would_delete","zone_unreadable","warnings"],"properties":{"safe":{"type":"boolean","description":"`false` both when the zone already receives mail elsewhere **and** when the zone could not be read. \"We could not look\" must never render as \"nothing would be lost\", so it is never `true` by default.","example":true},"reason":{"type":"string"},"existing_apex_mx":{"type":"array","items":{"type":"string"},"description":"Every apex `MX` currently published, in the order the provider returned them."},"foreign_mx":{"type":"array","items":{"type":"string"},"description":"The apex `MX` targets that are not the routing provider's — the reason for a refusal."},"foreign_spf_includes":{"type":"array","items":{"type":"string"},"description":"`include:` mechanisms in the current apex SPF that the new record would drop. Any service sending as this domain through those needs adding again afterwards."},"would_delete":{"type":"array","items":{"type":"string"},"description":"The records enabling would remove or replace, as `NAME TYPE VALUE`."},"zone_unreadable":{"type":"boolean","description":"Reported separately from `safe` because the two need completely different copy — one is \"fix your delegation\", the other is \"you will lose Google Workspace\".","example":false},"warnings":{"type":"array","items":{"type":"string"}}}},"DomainEmailRoutingRule":{"type":"object","required":["rule_id","matcher","destinations","action","name","enabled","catch_all","unsupported"],"properties":{"rule_id":{"type":"string","example":"19ba9b05a8494aa5bc1d0f7fed03077f"},"matcher":{"type":"string","description":"The address this rule applies to. Empty for the catch-all.","example":"sales@example.com"},"destinations":{"type":"array","items":{"type":"string","format":"email"}},"action":{"$ref":"#/components/schemas/EmailRoutingAction"},"name":{"type":"string","example":"Sales"},"enabled":{"type":"boolean","example":true},"catch_all":{"type":"boolean","example":false},"unsupported":{"type":"boolean","description":"`true` when the provider's rule uses a shape this API cannot express — a Worker target, say. Such a rule is shown read-only rather than hidden: hiding it would make this screen disagree with the customer's own provider dashboard, and rewriting it would destroy something we do not understand.","example":false}}},"DomainEmailRoutingRuleWrite":{"type":"object","additionalProperties":false,"required":["matcher","destinations"],"properties":{"matcher":{"type":"string","maxLength":320,"example":"sales@example.com"},"destinations":{"type":"array","maxItems":20,"items":{"type":"string","format":"email"}},"action":{"$ref":"#/components/schemas/EmailRoutingAction"},"name":{"type":"string","maxLength":200},"enabled":{"type":"boolean","default":true}}},"DomainIndexCheck":{"type":"object","description":"A domain's search-index reading, or an explicit statement that there is not one. `state` is the field to branch on — **never infer \"not indexed\" from a null**.","required":["fqdn","state","is_stale"],"properties":{"fqdn":{"type":"string"},"state":{"type":"string","enum":["indexed","not_indexed","unknown","never_checked"],"description":"`indexed` — the provider answered and the search engine has this site. `not_indexed` — the provider answered and the search engine has nothing. A real measurement, and the one state worth alerting a customer about. `unknown` — the provider was asked and could not tell us (outage, allowance, or credential). This is a statement about **us**, not about the site, and must never be rendered like `not_indexed`. `never_checked` — no check has been run yet."},"checked_at":{"type":"string","format":"date-time","nullable":true,"description":"When the stored check ran. Null when never checked."},"is_stale":{"type":"boolean","description":"True when the reading is older than the 7-day monitoring window, or absent entirely. A hint that a fresh check is worth its allowance — not an indication the result is wrong."},"estimated_indexed_pages":{"type":"integer","format":"int64","nullable":true,"minimum":0,"description":"The search engine's own loose upper bound for how many pages of this site it holds. **An estimate, not an authoritative count** — it routinely differs from Search Console by several times over. Null when the provider supplied no figure; `0` is a measured zero. Render it as a trend, never as \"N pages indexed\"."},"sample_urls":{"type":"array","description":"A few URLs the search engine returned, so a customer can confirm the right site was matched. Evidence, not a sitemap — capped at five.","items":{"type":"string"}},"next_check_at":{"type":"string","format":"date-time","nullable":true,"description":"When this domain is next due for an automatic check. Indexed sites are re-checked monthly, missing ones daily, and unknown ones within hours."}}},"DomainIndexCheckHistory":{"type":"object","description":"Recent checks for one domain, newest first. The transition between states is the point — a single current value cannot express \"dropped out of the index on the 14th\".","required":["fqdn","checks"],"properties":{"fqdn":{"type":"string"},"checks":{"type":"array","items":{"type":"object","required":["state","checked_at"],"properties":{"state":{"type":"string","enum":["indexed","not_indexed","unknown"]},"checked_at":{"type":"string","format":"date-time"},"estimated_indexed_pages":{"type":"integer","format":"int64","nullable":true}}}}}},"DomainNameserverResync":{"type":"object","additionalProperties":false,"required":["domain_id","fqdn","holder","has_site","has_zone","dns_copy","nameservers","last_synced_at","last_outcome","last_trigger"],"properties":{"domain_id":{"type":"string","format":"uuid"},"fqdn":{"type":"string"},"holder":{"type":"string","description":"`zinn`, `locked`, `connected_unknown`, `none`, or the vendor slug of the linked registrar account holding the domain (`godaddy`, `namecheap`, `porkbun`, `namecom`, `gandi`, `spaceship`, `namesilo`, `hostinger`, `ovh`)."},"has_site":{"type":"boolean"},"has_zone":{"type":"boolean","description":"Whether we hold a DNS zone for this domain (docs/844). For a domain with no site the `POST` PREPARES that zone when this is `false` (a copy of what the domain publishes today, changing nothing at the registrar) and switches the domain to it when `true`."},"dns_copy":{"type":"object","nullable":true,"additionalProperties":false,"required":["copied_at","copied","unsupported"],"description":"What we copied of the domain's live DNS into our zone (a transfer-in, or the first \"use our nameservers\" press). `null` means never copied. `unsupported` lists records we SAW at the old DNS but could not copy (`CAA`, `SRV`, a record the provider refused), as `\"<TYPE> <name> <value>\"` — the customer adds these by hand before switching.","properties":{"copied_at":{"type":"string","format":"date-time"},"copied":{"type":"integer","minimum":0},"unsupported":{"type":"array","items":{"type":"string"}}}},"nameservers":{"type":"array","items":{"type":"string"},"description":"The last delegation we applied or read (a cache; the registrar is the truth)."},"last_synced_at":{"type":"string","format":"date-time","nullable":true},"last_outcome":{"type":"string","nullable":true,"enum":["aligned","already","byo","no_registrar","unknown","failed","locked","no_site","missing","zone_prepared","zone_not_answering","kept_dns","deferred"],"description":"`null` means never resynced. `aligned` moved it; `already` it was right; `byo` no connected registrar could move it; `failed` the registrar refused; `unknown` the authority could not be read, so nothing was written; `zone_prepared` a domain with no site had its zone on our DNS prepared and nothing moved at the registrar yet; `zone_not_answering` our zone was not yet seen answering on its own nameservers, so the delegation was NOT switched (a live site must not go dark); `kept_dns` (Q464) a partner moved the site here, so its DNS stays where it is and nothing was moved; `deferred` (D75228) the new nameservers could not be asked whether they publish the apex, so nothing moved (the site keeps serving) and the move is retried with backoff."},"last_trigger":{"type":"string","nullable":true,"enum":["manual","site_provisioned","site_renamed","cdn_changed","dns_provider_changed","plan_changed","site_transferred","site_moved","registrar_connected","authority_moved","registration","transfer_in"]},"started":{"type":"boolean","description":"Present on the `POST` response only."}}},"DomainPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Domain"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"DomainSearchRequest":{"type":"object","required":["query"],"properties":{"query":{"type":"string","minLength":1,"maxLength":253,"description":"A bare name (`acme`) checked across `tlds`, or a full FQDN (`acme.com`).","example":"acme"},"tlds":{"type":"array","description":"TLDs to check a bare name against. Ignored for a dotted query. Omitted, a bare name expands to the catalogue's most popular extensions — the top ten on the public endpoint and the top twenty-five on this one — and NOT to every offered extension, which is 2,000+ and exceeds the per-request candidate cap.","items":{"type":"string","maxLength":63},"example":["com","net","io"]}}},"DomainSearchResult":{"type":"object","required":["fqdn","available","is_premium"],"properties":{"allowed_years":{"type":"object","nullable":true,"required":["min","max"],"description":"s1014 DOMAINS: the registration terms (years) this name can be bought for — the extension's own range (one year for a premium quote). Null on a row that cannot be bought. The dashboard's and the basket's term pickers read it; nothing is typed.","properties":{"min":{"type":"integer"},"max":{"type":"integer"}}},"fqdn":{"type":"string","example":"acme.com"},"available":{"type":"boolean"},"is_premium":{"type":"boolean","description":"The registrar prices this exact name individually rather than from the TLD's catalogue. A premium name is **sellable**: its `price` is the live registrar quote plus our margin, and it is bound only for the `token`'s 5-minute TTL — after that the name must be searched again. Premium prices are never cached."},"reason":{"type":["string","null"],"description":"Why it is unavailable/unsellable (e.g. `taken`, `not_offered`, `not_registrable`, `price_unavailable`, `manual_only` — the registry needs documents, a token or a licence that cannot be taken online, or is closed to new registrations; `getTldRequirements` says which); null when the name can be bought. `availability_unknown` is the THIRD state and is not a refusal: no source could say whether the name is registered (no registrar reachable, no RDAP service for that extension, a vendor timeout). It carries `available: false` and no `token`, so it can never enter a cart — but a client MUST render it as \"we could not check, try again\" and never as \"taken\", because a visitor told their name is gone abandons a name that may be free. `premium_quote_unavailable` means the registrar flagged the name premium but returned no figure — we decline rather than fall back to the catalogue price, which would sell a premium name at the ordinary rate."},"price":{"description":"The 1-year register sell price. For a premium name this is the registrar's live per-name quote plus margin, not a catalogue price. Null only when the name cannot be sold, in which case `reason` says why.","anyOf":[{"$ref":"#/components/schemas/MoneyAmount"},{"type":"null"}]},"token":{"type":["string","null"],"description":"The signed availability token to attach to a `domain_register` cart line. Present only for an available name in a TLD we offer. For a premium name it also carries the quote the price was bound to, which checkout re-verifies: a quote that has moved is a `409` and no charge, never a silent re-price."},"privacy_price":{"description":"The WHOIS-privacy extra for this name's TLD, priced through the same overlay chain as the registration. Null where the registry sells no privacy product (Nominet's `.co.uk`), so a basket never offers a line item the registrar can only reject. Present on the search response rather than behind a second call because the buy decision and the extras decision are made on one screen — and a client must never invent an add-on price of its own (CLAUDE.md §2.8).","anyOf":[{"$ref":"#/components/schemas/MoneyAmount"},{"type":"null"}]},"suggestion_kind":{"type":["string","null"],"description":"Why this name is being offered, set only on a row from `suggestDomains`. One of `brand_protection`, `regional`, `similar`, `popular`, or `null` on an ordinary search row. Described rather than declared as an `enum` because a nullable enum is the one shape Spectral's OAS ruleset cannot read. `brand_protection` — somebody else holding it could pass for you; `regional` — the extension that reads as local in the visitor's country; `similar` — the same commercial intent as the name they searched; `popular` — filler when the reasoned tiers do not fill the grid. A machine value: every surface renders its own localized sentence, because a grid of unexplained alternatives is a list, not an upsell."}}},"DomainSearchResults":{"type":"object","required":["results"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/DomainSearchResult"}}}},"DomainSeoMetrics":{"type":"object","description":"A domain's authority reading, or an explicit statement that there is not one. `state` is the field to branch on — never infer \"no authority\" from null metrics.","required":["fqdn","state","is_stale"],"properties":{"fqdn":{"type":"string"},"state":{"type":"string","enum":["measured","not_in_index","never_fetched"],"description":"`measured` — the provider returned figures (which may be zero, a real measurement). `not_in_index` — the provider answered and has never crawled this domain. `never_fetched` — no reading has been requested yet."},"measured_at":{"type":"string","format":"date-time","nullable":true,"description":"When the stored reading was taken. Null when never fetched."},"is_stale":{"type":"boolean","description":"True when the reading is older than the 24h refresh window, or absent entirely. A hint that a refresh is worth its allowance — not an indication the figures are wrong."},"metrics":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/SeoAuthorityMetrics"}]}}},"DomainSettings":{"type":"object","required":["registrar","auto_renew","transfer_lock","dnssec_enabled","privacy_enabled"],"properties":{"registrar":{"type":"string","description":"The registrar driver holding this domain (a driver name, never a vendor id)."},"auto_renew":{"type":"boolean","description":"Whether we renew it before expiry. Ours, not the registrar's."},"transfer_lock":{"type":"boolean","description":"Registrar transfer lock (`clientTransferProhibited`) — blocks an outbound transfer."},"dnssec_enabled":{"type":"boolean"},"privacy_enabled":{"type":"boolean","description":"WHOIS privacy / registrant redaction, where the TLD supports it."}}},"DomainSettingsUpdate":{"type":"object","description":"A partial change. An omitted field is left as it is — it is never treated as `false`, so a client sending one toggle cannot silently clear another.","properties":{"auto_renew":{"type":"boolean"},"transfer_lock":{"type":"boolean"},"dnssec_enabled":{"type":"boolean"},"privacy_enabled":{"type":"boolean"}}},"DomainStatus":{"type":"string","description":"A domain's lifecycle state (docs/31 §4.10).","enum":["pending_registration","registering","active","connected","pending_transfer_in","transferring_in","expiring","expired_grace","redemption","pending_delete","deleted","transferred_out","registration_failed","transfer_failed","suspended"]},"DomainSuggestRequest":{"type":"object","required":["query"],"properties":{"query":{"type":"string","minLength":1,"maxLength":253,"description":"The name the visitor searched — bare (`acme`) or full (`acme.com`)."},"country":{"type":"string","minLength":2,"maxLength":2,"description":"ISO-3166 alpha-2 **hint**, used only when the edge did not state the visitor's country. The `CF-IPCountry` header wins whenever it is present: it is set by the edge and cannot be forged by the browser, whereas this can."},"exclude":{"type":"array","maxItems":64,"items":{"type":"string","maxLength":253},"description":"Names the primary search already answered. Each suggestion costs a paid registrar call, so re-checking a name already on the visitor's screen is money spent to tell them what they can see."},"limit":{"type":"integer","minimum":1,"maximum":8,"default":8,"description":"Grid size. The maximum is the hard cap on anonymous vendor spend per request."}}},"DomainVetBulkRequested":{"type":"object","required":["reports","created","reused"],"properties":{"reports":{"type":"array","items":{"$ref":"#/components/schemas/DomainVetSummary"}},"created":{"type":"integer","description":"New reports started (each took one credit)."},"reused":{"type":"integer","description":"Recent reports returned free."}}},"DomainVetReason":{"type":"object","required":["code","weight","area","params"],"properties":{"code":{"type":"string","description":"A stable reason code; the screen renders `domainVetting.reason.<code>`."},"weight":{"type":"integer","description":"Points this reason took off (negative) or added (positive)."},"area":{"type":"string"},"params":{"type":"object","additionalProperties":true}}},"DomainVetReport":{"allOf":[{"$ref":"#/components/schemas/DomainVetSummary"},{"type":"object","required":["reasons","parts","missing","credits","error_code","started_at"],"properties":{"reasons":{"type":"array","items":{"$ref":"#/components/schemas/DomainVetReason"}},"parts":{"type":"object","additionalProperties":true,"description":"The evidence, keyed by part (`links`, `history`, `anchors`, `refdomains`, `overview`, `organic`, `lost`, `traffic`, `index`, `whois` — the registry's own RDAP record — and `archive`)."},"missing":{"type":"array","items":{"type":"string"}},"credits":{"type":"integer"},"error_code":{"type":"string","nullable":true},"started_at":{"type":"string","format":"date-time","nullable":true}}}]},"DomainVetRequest":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","maxLength":300,"description":"A domain name; a pasted URL is reduced to its host."},"location_code":{"type":"integer","default":2840,"description":"The search market the organic parts are read for (see `markets`)."}}},"DomainVetRequested":{"type":"object","required":["report","created"],"properties":{"report":{"$ref":"#/components/schemas/DomainVetSummary"},"created":{"type":"boolean"}}},"DomainVetSummary":{"type":"object","required":["id","domain","location_code","status","score","verdict","created_at","finished_at"],"properties":{"id":{"type":"string","format":"uuid"},"domain":{"type":"string"},"location_code":{"type":"integer"},"status":{"type":"string","enum":["queued","running","complete","partial","failed","refused"]},"score":{"type":"integer","nullable":true,"minimum":0,"maximum":100},"verdict":{"type":["string","null"],"enum":["clean","care","risk",null]},"created_at":{"type":"string","format":"date-time"},"finished_at":{"type":"string","format":"date-time","nullable":true}}},"DomainVetting":{"type":"object","required":["credits","unlimited","packs","markets","reuse_days","reports","ledger"],"properties":{"credits":{"type":"integer"},"unlimited":{"type":"boolean"},"packs":{"type":"array","items":{"type":"object","required":["code","reports"],"properties":{"code":{"type":"string"},"reports":{"type":"integer"}}}},"markets":{"type":"array","items":{"type":"integer"}},"reuse_days":{"type":"integer"},"reports":{"type":"array","items":{"$ref":"#/components/schemas/DomainVetSummary"}},"ledger":{"type":"array","items":{"type":"object","required":["kind","delta","balance_after","note","at"],"properties":{"kind":{"type":"string","enum":["purchase","use","refund","adjust"]},"delta":{"type":"integer"},"balance_after":{"type":"integer"},"note":{"type":"string"},"at":{"type":"string","format":"date-time"}}}}}},"DomainWatch":{"type":"object","description":"One domain on a customer's watchlist, with the registry's last answer.","required":["id","fqdn","source","muted","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"fqdn":{"type":"string","description":"Normalised lowercase punycode."},"source":{"type":"string","enum":["registered","hosting","manual"],"description":"How it came to be watched. `registered` — we hold it. `hosting` — it is attached to a hosting account with us, whoever registered it. `manual` — the customer added it. ⛔ A domain that is several of these is ONE row carrying the strongest claim, not several rows: two rows would alert twice and could disagree about the mute."},"domain_id":{"type":"string","format":"uuid","nullable":true,"description":"The `Domain` row, when the watched name is one of ours."},"site_id":{"type":"string","format":"uuid","nullable":true},"muted":{"type":"boolean","description":"Whether alerts are currently suppressed."},"muted_until":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true,"description":"⛔ `null` is **\"the registry did not say\"**, never \"it does not expire\". Render it as unknown; a client that treats it as a far-future date shows a customer a reassuring answer we never received."},"days_until_expiry":{"type":"integer","nullable":true,"description":"Whole days, or `null` when `expires_at` is unknown."},"registrar":{"type":"string","description":"As the registry reports it. Empty when redacted or not yet read."},"nameservers":{"type":"array","items":{"type":"string"}},"status":{"type":"array","items":{"type":"string"},"description":"The EPP status set — `clientHold`, `redemptionPeriod`, `pendingDelete`, …"},"last_checked_at":{"type":"string","format":"date-time","nullable":true,"description":"When the registry last answered. ⛔ Every value on this row is a snapshot of the outside world taken at this instant, so it is never rendered without this beside it (§2.36)."},"created_at":{"type":"string","format":"date-time"}}},"DomainWatchCreate":{"type":"object","required":["fqdn"],"properties":{"fqdn":{"type":"string","maxLength":253,"description":"Any registrable domain, including one registered elsewhere."},"org_id":{"type":"string","format":"uuid","description":"The organisation to watch it for. Defaults to the caller's own."}}},"DomainWatchMute":{"type":"object","properties":{"until":{"type":"string","format":"date-time","nullable":true,"description":"Suppress alerts until this instant. `null` un-mutes."}}},"DomainWatchPage":{"type":"object","required":["items","total"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/DomainWatch"}},"total":{"type":"integer","description":"The full match, so the screen can page all of it."}}},"DunningPolicyVersion":{"type":"object","description":"An immutable snapshot of one ladder's rungs.","required":["version","is_active","steps"],"properties":{"id":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Null only on the reseller surface's synthesised platform-default view, which describes rungs that are in force without being the caller's row."},"version":{"type":"integer"},"is_active":{"type":"boolean","description":"Whether NEW runs start on this version. Retiring one never rewrites it."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/DunningStep"}},"published_by":{"type":"string","description":"The principal that published it, e.g. `user:<id>`. Never client-supplied."},"publish_reason":{"type":"string"},"created_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"DunningStep":{"type":"object","description":"One rung of a dunning ladder. Validated server-side by `billing.dunning.validate_steps` on every write path — this schema establishes the field names, not the rules.","required":["action","after_days","event_type"],"properties":{"action":{"type":"string","description":"What this rung does. One of the platform's dunning actions.","maxLength":32},"after_days":{"type":"integer","minimum":0,"description":"Days after the PREVIOUS rung, not after the start. The ladder's total is bounded server-side so a mis-typed figure cannot chase someone for years."},"grace_days":{"type":"integer","minimum":0,"default":0,"description":"Extra days the customer is told they have. Must not exceed the gap to the next rung, or the deadline the customer is given is not the deadline."},"event_type":{"type":"string","description":"The event this rung emits. Must exist in the event catalog **and** have a notification template — otherwise the rung fires and the customer is told nothing.","maxLength":100},"note":{"type":"string","maxLength":500,"description":"A reseller's own words for this rung, rendered as its own paragraph in the email. Deliberately NOT translated - it is the reseller writing to their own customers, in the language they do business in, and the surrounding copy stays localized into all 58 locales. What a reseller cannot do is rewrite the sentence that states what the system will actually do."}}},"EmailMarketingAbResult":{"type":"object","required":["metric","winner","decided_at","a","b"],"properties":{"metric":{"type":"string","enum":["opens","clicks"]},"winner":{"type":"string","enum":["a","b"],"nullable":true},"decided_at":{"type":"string","format":"date-time","nullable":true},"a":{"$ref":"#/components/schemas/EmailMarketingAbVariant"},"b":{"$ref":"#/components/schemas/EmailMarketingAbVariant"}}},"EmailMarketingAbVariant":{"type":"object","required":["subject","sent","opened","clicked"],"properties":{"subject":{"type":"string"},"sent":{"type":"integer"},"opened":{"type":"integer","description":"Unique opens."},"clicked":{"type":"integer","description":"Unique clicks."}}},"EmailMarketingAiDraft":{"type":"object","required":["subject_a","subject_b","preheader","html","model"],"properties":{"subject_a":{"type":"string"},"subject_b":{"type":"string","description":"A second subject line for an A/B test."},"preheader":{"type":"string"},"html":{"type":"string","description":"The body","sanitised to p":null,"h2":null,"h3":null,"lists":null,"links":null,"strong":null,"em and br.":null},"model":{"type":"string"}}},"EmailMarketingAiWriteRequest":{"type":"object","required":["brief"],"properties":{"brief":{"type":"string","maxLength":2000,"description":"What the email is about","in the customer's words.":null},"locale":{"type":"string","maxLength":16,"description":"The language to write in (a BCP 47 tag); defaults to en."},"tone":{"type":"string","enum":["friendly","professional","playful","urgent","calm"],"default":"friendly"}}},"EmailMarketingBrandKit":{"type":"object","required":["source_url","name","logo_url","primary_color","accent_color","font","voice","apply_to_emails","status","status_code","read_at","updated_at"],"properties":{"source_url":{"type":"string","description":"The website the kit was last read from."},"name":{"type":"string","maxLength":80},"logo_url":{"type":"string","description":"An absolute https:// address, or empty."},"primary_color":{"type":"string","description":"#rrggbb, or empty."},"accent_color":{"type":"string","description":"#rrggbb, or empty."},"font":{"type":"string","maxLength":40},"voice":{"type":"string","maxLength":500,"description":"How the business writes; given to the AI writer."},"apply_to_emails":{"type":"boolean"},"status":{"type":"string","enum":["manual","reading","ready","failed"]},"status_code":{"type":"string","description":"Why a read failed (siteUnreadable), else empty."},"read_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}}},"EmailMarketingBrandKitWrite":{"type":"object","properties":{"source_url":{"type":"string","maxLength":500},"name":{"type":"string","maxLength":80},"logo_url":{"type":"string","maxLength":500},"primary_color":{"type":"string","maxLength":7},"accent_color":{"type":"string","maxLength":7},"font":{"type":"string","maxLength":40},"voice":{"type":"string","maxLength":500},"apply_to_emails":{"type":"boolean"}}},"EmailMarketingCampaign":{"type":"object","required":["id","name","list_id","sender_id","from_name","reply_to","subject","preheader","html","text","template","postal_address","subject_b","ab_test_pct","ab_wait_minutes","ab_metric","ab_winner","ab_decided_at","send_time_mode","source_locale","zerobounce_mode","status","refusal_code","refusal_message","recipients_total","started_at","finished_at","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"list_id":{"type":"string","format":"uuid","nullable":true},"sender_id":{"type":"string","format":"uuid","nullable":true},"from_name":{"type":"string"},"reply_to":{"type":"string"},"subject":{"type":"string"},"preheader":{"type":"string"},"html":{"type":"string"},"text":{"type":"string"},"template":{"type":"string","enum":["basic","raw","blocks"]},"blocks":{"type":"array","nullable":true,"description":"F32 block designer layout (cleaned); null when the campaign was never designed in blocks.","items":{"$ref":"#/components/schemas/EmailMarketingCampaignBlock"}},"postal_address":{"type":"string"},"subject_b":{"type":"string"},"ab_test_pct":{"type":"integer"},"ab_wait_minutes":{"type":"integer"},"ab_metric":{"type":"string","enum":["opens","clicks"]},"ab_winner":{"type":"string","enum":["a","b"],"nullable":true},"ab_decided_at":{"type":"string","format":"date-time","nullable":true},"send_time_mode":{"type":"string","enum":["now","optimised"]},"source_locale":{"type":"string"},"zerobounce_mode":{"type":"string","enum":["off","invalid","risky"]},"status":{"type":"string","enum":["draft","sending","paused","sent","refused"]},"refusal_code":{"type":"string","nullable":true,"enum":["not_open","account_on_hold","not_included","incomplete","pool_warming","sender_unverified","domain_auth","paused","quota","review","empty","zerobounce_key","zerobounce_outage"]},"refusal_message":{"type":"string","nullable":true},"recipients_total":{"type":"integer"},"started_at":{"type":"string","format":"date-time","nullable":true},"finished_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"EmailMarketingCampaignBlock":{"type":"object","description":"One F32 designer block. `heading` (text, level 1-3), `text` (text; a blank line starts a paragraph), `button` (label, url https or mailto, color #rrggbb or blank for the brand colour), `image` (src https, alt, url, width 40-552), `divider`, `spacer` (size). `align` is `start` (follows the language direction) or `center`.","required":["type"],"properties":{"type":{"type":"string","enum":["heading","text","button","image","divider","spacer"]},"text":{"type":"string","maxLength":5000},"level":{"type":"integer","enum":[1,2,3]},"label":{"type":"string","maxLength":200},"url":{"type":"string","maxLength":2000},"color":{"type":"string","maxLength":16},"src":{"type":"string","maxLength":2000},"alt":{"type":"string","maxLength":200},"width":{"type":"integer","minimum":40,"maximum":552},"size":{"type":"integer","enum":[8,16,24,32,48,64]},"align":{"type":"string","enum":["start","center"]}}},"EmailMarketingCampaignPage":{"type":"object","required":["data","next_after"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailMarketingCampaign"}},"next_after":{"type":"string","format":"uuid","nullable":true}}},"EmailMarketingCampaignReport":{"type":"object","required":["campaign_id","status","recipients","by_status","sent","delivered","bounced","complained","opened","clicked","unsubscribed","bounce_rate_bps","complaint_rate_bps","open_rate_bps","click_rate_bps"],"properties":{"campaign_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["draft","sending","paused","sent","refused"]},"recipients":{"type":"integer"},"by_status":{"type":"object","additionalProperties":{"type":"integer"}},"sent":{"type":"integer"},"delivered":{"type":"integer"},"bounced":{"type":"integer"},"complained":{"type":"integer"},"opened":{"type":"integer"},"clicked":{"type":"integer"},"unsubscribed":{"type":"integer"},"bounce_rate_bps":{"type":"integer"},"complaint_rate_bps":{"type":"integer"},"open_rate_bps":{"type":"integer"},"click_rate_bps":{"type":"integer"},"ab":{"nullable":true,"description":"The A/B subject test, or null when the campaign is not a test.","allOf":[{"$ref":"#/components/schemas/EmailMarketingAbResult"}]},"verification":{"description":"F41: what the ZeroBounce check did for this campaign.","allOf":[{"$ref":"#/components/schemas/EmailMarketingZeroBounceVerification"}]}}},"EmailMarketingCampaignTranslateResult":{"allOf":[{"$ref":"#/components/schemas/EmailMarketingCampaignTranslations"},{"type":"object","required":["started"],"properties":{"started":{"type":"boolean"}}}]},"EmailMarketingCampaignTranslations":{"type":"object","required":["campaign_id","source_locale","locales"],"properties":{"campaign_id":{"type":"string","format":"uuid"},"source_locale":{"type":"string","description":"The language the campaign is written in."},"locales":{"type":"array","items":{"type":"object","required":["locale","state","wanted","translated_at"],"properties":{"locale":{"type":"string"},"state":{"type":"string","enum":["current","stale","missing"]},"wanted":{"type":"boolean","description":"Whether a subscribed contact of the list uses this language."},"translated_at":{"type":"string","format":"date-time","nullable":true}}}}}},"EmailMarketingCampaignWrite":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"list_id":{"type":"string","format":"uuid","nullable":true},"sender_id":{"type":"string","format":"uuid","nullable":true},"from_name":{"type":"string","maxLength":80},"reply_to":{"type":"string","maxLength":254},"subject":{"type":"string","maxLength":200},"preheader":{"type":"string","maxLength":200},"html":{"type":"string"},"text":{"type":"string"},"template":{"type":"string","enum":["basic","raw","blocks"],"description":"`basic` wraps the body in our layout; `raw` sends the HTML as written; `blocks` (F32 designer) is `basic` with `html` and `text` COMPILED by the server from `blocks` on every save (any `html`/`text` sent with it is ignored)."},"blocks":{"type":"array","nullable":true,"maxItems":60,"description":"F32 block designer layout. Cleaned on save: an unknown type, an empty block or an unsafe address is dropped, at most 60 kept.","items":{"$ref":"#/components/schemas/EmailMarketingCampaignBlock"}},"postal_address":{"type":"string","maxLength":300},"subject_b":{"type":"string","maxLength":200,"description":"A/B test: the second subject line. Blank = no test."},"ab_test_pct":{"type":"integer","minimum":0,"maximum":50,"description":"A/B test: the share of the audience (%) split between A and B; the rest gets the winner. 0 = no test. Clamped to 0-50."},"ab_wait_minutes":{"type":"integer","minimum":30,"maximum":2880,"description":"A/B test: minutes from the start before the winner is chosen. Clamped to 30-2880."},"ab_metric":{"type":"string","enum":["opens","clicks"],"description":"A/B test: what the winner is measured on (unique opens or unique clicks per sent)."},"send_time_mode":{"type":"string","enum":["now","optimised"],"description":"`optimised` holds each recipient until their own best hour (from past opens and clicks, Apple proxy opens discounted), within 24 hours of the start."},"source_locale":{"type":"string","maxLength":16,"description":"The language the campaign is written in (one of the 58 platform languages; anything else keeps the old one). Default en."},"zerobounce_mode":{"type":"string","enum":["off","invalid","risky"],"description":"F41: check the list with the organisation's own ZeroBounce key before sending. `invalid` skips invalid, spamtrap, abuse and do_not_mail; `risky` also skips catch-all and unknown. Needs a connected key (`/v1/email-marketing/zerobounce`). Default off."}}},"EmailMarketingColdCountry":{"type":"object","required":["country","default_rule","rule"],"properties":{"country":{"type":"string"},"default_rule":{"type":"string","enum":["refused","b2b_only","allowed"]},"basis":{"type":"string"},"override_rule":{"type":"string","enum":["refused","b2b_only","allowed"],"nullable":true},"rule":{"type":"string","enum":["refused","b2b_only","allowed"]},"acknowledged_at":{"type":"string","format":"date-time","nullable":true}}},"EmailMarketingColdCountryList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailMarketingColdCountry"}}}},"EmailMarketingColdCountrySet":{"type":"object","required":["rule"],"properties":{"rule":{"type":"string","enum":["refused","b2b_only","allowed"]},"acknowledged":{"type":"boolean","description":"Required (true) for any rule other than the default."}}},"EmailMarketingColdEnrolRequest":{"type":"object","properties":{"lead_ids":{"type":"array","maxItems":10000,"items":{"type":"string","format":"uuid"}},"import_id":{"type":"string","format":"uuid"}}},"EmailMarketingColdEnrolResult":{"type":"object","required":["added","already_enrolled","suppressed"],"properties":{"added":{"type":"integer"},"already_enrolled":{"type":"integer"},"suppressed":{"type":"integer"}}},"EmailMarketingColdImport":{"type":"object","required":["id","status","rows_total","rows_checked","rows_added","rows_updated","rows_refused","verdict_counts","refused","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","running","done","failed"]},"source_name":{"type":"string"},"attested_by":{"type":"string"},"rows_total":{"type":"integer"},"rows_checked":{"type":"integer"},"rows_added":{"type":"integer"},"rows_updated":{"type":"integer"},"rows_refused":{"type":"integer"},"verdict_counts":{"type":"object","additionalProperties":{"type":"integer"},"description":"One count per verdict."},"refused":{"type":"array","items":{"$ref":"#/components/schemas/EmailMarketingColdImportVerdict"}},"created_at":{"type":"string","format":"date-time"},"finished_at":{"type":"string","format":"date-time","nullable":true}}},"EmailMarketingColdImportCreate":{"type":"object","required":["attested","leads"],"properties":{"attested":{"type":"boolean","description":"Must be true; confirms the attestation statement shown by the overview."},"source_name":{"type":"string","maxLength":200},"leads":{"type":"array","items":{"$ref":"#/components/schemas/EmailMarketingColdLeadRow"}}}},"EmailMarketingColdImportPage":{"type":"object","required":["data","next_after"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailMarketingColdImport"}},"next_after":{"type":"string","format":"uuid","nullable":true}}},"EmailMarketingColdImportVerdict":{"type":"object","required":["row","email","verdict","country"],"properties":{"row":{"type":"integer","description":"The row's position in the file","from 0.":null},"email":{"type":"string"},"verdict":{"type":"string","enum":["countryRefused","notBusinessAddress","suppressed","invalid","duplicate","overAllowance"],"description":"Why the row was refused. `overAllowance` = a NEW lead past the Cold Outreach plan's active-lead allowance (`cold_leads`); updates to leads already held are never refused."},"country":{"type":"string"}}},"EmailMarketingColdLead":{"type":"object","required":["id","email","domain","country","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"title":{"type":"string"},"domain":{"type":"string"},"country":{"type":"string","description":"ISO 3166-1 alpha-2","or ZZ for unknown.":null},"attributes":{"type":"object","additionalProperties":{"type":"string"}},"import_id":{"type":"string","format":"uuid","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"EmailMarketingColdLeadPage":{"type":"object","required":["data","next_after"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailMarketingColdLead"}},"next_after":{"type":"string","format":"uuid","nullable":true}}},"EmailMarketingColdLeadRow":{"type":"object","required":["email"],"properties":{"email":{"type":"string","maxLength":320},"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"title":{"type":"string"},"country":{"type":"string","description":"Two-letter country code; else the domain decides."},"attributes":{"type":"object","additionalProperties":{"type":"string"}}}},"EmailMarketingColdMailbox":{"type":"object","required":["id","provider","email","domain","status","daily_cap","min_gap_seconds","paused","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"provider":{"type":"string"},"email":{"type":"string"},"domain":{"type":"string"},"display_name":{"type":"string"},"smtp_host":{"type":"string"},"smtp_port":{"type":"integer"},"smtp_tls":{"type":"string"},"imap_host":{"type":"string"},"imap_port":{"type":"integer"},"username":{"type":"string"},"status":{"type":"string","enum":["unverified","verifying","verified","failing"]},"status_code":{"type":"string","description":"Why the last check failed, as a refusal key (`refusal.campaigns.cold*` or a connection refusal) the dashboard translates, or empty."},"verified_at":{"type":"string","format":"date-time","nullable":true},"daily_cap":{"type":"integer"},"min_gap_seconds":{"type":"integer","minimum":60,"maximum":3600},"paused":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"dns_health":{"description":"The newest SPF / DKIM / DMARC reading of the mailbox's domain, taken by every check (on connect and \"Check\"), with the exact record to publish for anything missing; expected values follow the provider the mailbox was connected with. Blocklists are not looked up here. `null` until the first check has run.","nullable":true,"allOf":[{"$ref":"#/components/schemas/EmailMarketingSenderHealth"}]}}},"EmailMarketingColdMailboxCreate":{"type":"object","required":["email","password","smtp_host","imap_host"],"properties":{"provider":{"type":"string","enum":["imap_smtp","gmail","zoho","yahoo","icloud","fastmail"],"default":"imap_smtp","description":"The `sender-providers` mailbox row the servers came from (its DKIM selectors and SPF include decide the DNS records the mailbox is told to publish), or `imap_smtp` for any other mailbox. Only providers that accept a password or an app password over SMTP and IMAP: Microsoft 365 and Outlook.com take only Microsoft sign-in and cannot connect."},"email":{"type":"string","format":"email","maxLength":254},"display_name":{"type":"string","maxLength":80},"smtp_host":{"type":"string","maxLength":253},"smtp_port":{"type":"integer","enum":[25,465,587,2525],"default":587},"smtp_tls":{"type":"string","enum":["starttls","implicit"]},"imap_host":{"type":"string","maxLength":253},"imap_port":{"type":"integer","enum":[993],"default":993},"username":{"type":"string","description":"Defaults to `email`."},"password":{"type":"string","format":"password","writeOnly":true}}},"EmailMarketingColdMailboxList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailMarketingColdMailbox"}}}},"EmailMarketingColdMailboxUpdate":{"type":"object","properties":{"display_name":{"type":"string","maxLength":80},"daily_cap":{"type":"integer","minimum":1},"min_gap_seconds":{"type":"integer","minimum":60,"maximum":3600},"paused":{"type":"boolean"}}},"EmailMarketingColdOverview":{"type":"object","required":["open","cap_ceiling","mailboxes","attestation","max_import_rows"],"properties":{"attestation":{"type":"string","description":"The statement an import confirms (`attested`)."},"max_import_rows":{"type":"integer","description":"The most leads one import request takes."},"open":{"type":"boolean","description":"Whether Cold Outreach may be used by the organisation."},"cap_ceiling":{"type":"integer","description":"The highest daily cap a mailbox may be set to."},"mailboxes":{"type":"integer","description":"How many mailboxes the organisation has connected."}}},"EmailMarketingColdReply":{"type":"object","required":["id","mailbox_id","kind","from_email","received_at","read","label","answer_status","answer_detail","answered_at"],"properties":{"id":{"type":"string","format":"uuid"},"mailbox_id":{"type":"string","format":"uuid"},"sequence_id":{"type":"string","format":"uuid","nullable":true},"lead_id":{"type":"string","format":"uuid","nullable":true},"kind":{"type":"string","enum":["reply","auto_reply","bounce","unsubscribe"]},"from_email":{"type":"string"},"from_name":{"type":"string"},"subject":{"type":"string"},"snippet":{"type":"string","description":"The reply's own words","without the quoted original.":null},"received_at":{"type":"string","format":"date-time"},"read":{"type":"boolean"},"label":{"type":"string","enum":["","interested","not_interested","meeting","later","wrong_person"]},"answer_status":{"type":"string","enum":["","queued","sent","failed"],"description":"The customer's answer to this reply from the Unibox: empty when none was written, `queued` while it is being sent, `sent`, or `failed` (it may be sent again)."},"answer_detail":{"type":"string","description":"Why a `failed` answer failed: `mailbox` (the mailbox cannot send), `unavailable` (it could not be started; nothing was sent), `auth_<code>`, `smtp_<code>` or `network_<error>` from the mailbox's own mail server. Empty otherwise."},"answered_at":{"type":"string","format":"date-time","nullable":true}}},"EmailMarketingColdReplyAnswer":{"type":"object","required":["body"],"properties":{"body":{"type":"string","minLength":1,"maxLength":20000,"description":"The answer, plain text. Leading and trailing spaces are dropped."}}},"EmailMarketingColdReplyList":{"type":"object","required":["data","next_cursor","unread"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailMarketingColdReply"}},"next_cursor":{"type":"string","nullable":true},"unread":{"type":"integer"}}},"EmailMarketingColdReplyUpdate":{"type":"object","properties":{"read":{"type":"boolean"},"label":{"type":"string","enum":["","interested","not_interested","meeting","later","wrong_person"]}}},"EmailMarketingColdSequence":{"type":"object","required":["id","name","status","locale","time_zone","window_days","postal_address","mailbox_ids","enrolments","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","completed"]},"locale":{"type":"string"},"time_zone":{"type":"string"},"window_days":{"type":"array","items":{"type":"integer"}},"window_start_hour":{"type":"integer"},"window_end_hour":{"type":"integer"},"stop_on_company_reply":{"type":"boolean"},"track_opens":{"type":"boolean"},"track_clicks":{"type":"boolean"},"postal_address":{"type":"string"},"mailbox_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"launched_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"enrolments":{"type":"object","description":"Leads per enrolment status.","additionalProperties":{"type":"integer"}},"eta_days":{"type":"number","nullable":true,"description":"Days to finish at the current caps (leads x steps / summed daily caps)."},"steps":{"type":"array","description":"Only on the single-sequence answers.","items":{"$ref":"#/components/schemas/EmailMarketingColdStep"}}}},"EmailMarketingColdSequenceInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"locale":{"type":"string","description":"The language of the footer the sender adds."},"time_zone":{"type":"string","description":"IANA zone the window is read in."},"window_days":{"type":"array","items":{"type":"integer","minimum":1,"maximum":7},"description":"ISO weekdays, 1 = Monday."},"window_start_hour":{"type":"integer","minimum":0,"maximum":23},"window_end_hour":{"type":"integer","minimum":1,"maximum":24},"stop_on_company_reply":{"type":"boolean"},"track_opens":{"type":"boolean","description":"Must be false for now."},"track_clicks":{"type":"boolean","description":"Must be false for now."},"postal_address":{"type":"string","maxLength":300},"mailbox_ids":{"type":"array","items":{"type":"string","format":"uuid"}}}},"EmailMarketingColdSequenceList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailMarketingColdSequence"}}}},"EmailMarketingColdSequenceReport":{"type":"object","required":["sequence_id","enrolments","steps"],"properties":{"sequence_id":{"type":"string","format":"uuid"},"enrolments":{"type":"object","additionalProperties":{"type":"integer"}},"steps":{"type":"array","items":{"type":"object","required":["position","wait_days","variants"],"properties":{"position":{"type":"integer"},"wait_days":{"type":"integer"},"variants":{"type":"array","items":{"type":"object","required":["label","sent","replies","reply_rate","bounces","unsubscribes"],"properties":{"label":{"type":"string"},"subject":{"type":"string"},"sent":{"type":"integer"},"replies":{"type":"integer"},"reply_rate":{"type":"number","description":"Percent of sent."},"bounces":{"type":"integer"},"unsubscribes":{"type":"integer"}}}}}}}}},"EmailMarketingColdStep":{"type":"object","required":["variants"],"properties":{"position":{"type":"integer"},"wait_days":{"type":"integer","minimum":0,"maximum":90},"variants":{"type":"array","minItems":1,"maxItems":5,"items":{"$ref":"#/components/schemas/EmailMarketingColdVariant"}}}},"EmailMarketingColdSteps":{"type":"object","required":["steps"],"properties":{"steps":{"type":"array","minItems":1,"maxItems":10,"items":{"$ref":"#/components/schemas/EmailMarketingColdStep"}}}},"EmailMarketingColdVariant":{"type":"object","required":["body"],"properties":{"label":{"type":"string","description":"A to E (set by the server from the order)."},"subject":{"type":"string","maxLength":200},"body":{"type":"string","maxLength":20000},"weight":{"type":"integer","minimum":1,"maximum":100}}},"EmailMarketingContact":{"type":"object","required":["id","email","phone","locale","status","attributes","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"phone":{"type":"string","description":"E.164 mobile number, or empty."},"locale":{"type":"string"},"status":{"type":"string","enum":["subscribed","pending","unsubscribed","bounced","complained"]},"attributes":{"type":"object","additionalProperties":true},"created_at":{"type":"string","format":"date-time"}}},"EmailMarketingContactPage":{"type":"object","required":["data","next_after"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailMarketingContact"}},"next_after":{"type":"string","format":"uuid","nullable":true}}},"EmailMarketingDeliverabilitySettings":{"type":"object","additionalProperties":false,"required":["org_id","effective","overridden","platform","staff_locked","min_sample"],"properties":{"org_id":{"type":"string","format":"uuid"},"effective":{"$ref":"#/components/schemas/EmailMarketingThresholdValues"},"overridden":{"type":"array","description":"The fields this organisation overrides; every other one follows `platform`.","items":{"type":"string","enum":["bounce_pause_enabled","bounce_pause_bps","complaint_pause_enabled","complaint_pause_bps"]}},"platform":{"$ref":"#/components/schemas/EmailMarketingThresholdValues"},"staff_locked":{"type":"boolean","description":"Staff locked the thresholds; only staff can change them."},"min_sample":{"type":"integer","description":"Sends a campaign needs before any rate is judged."}}},"EmailMarketingDeliverabilityWrite":{"type":"object","additionalProperties":false,"description":"Only the fields sent change; `null` clears an override (back to the platform default).","properties":{"bounce_pause_enabled":{"type":"boolean","nullable":true},"bounce_pause_bps":{"type":"integer","nullable":true,"minimum":1,"maximum":10000},"complaint_pause_enabled":{"type":"boolean","nullable":true},"complaint_pause_bps":{"type":"integer","nullable":true,"minimum":1,"maximum":10000}}},"EmailMarketingFlow":{"type":"object","required":["id","name","list_id","sender_id","from_name","reply_to","postal_address","trigger","date_field","status","activated_at","last_refusal_code","last_refusal_key","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"list_id":{"type":"string","format":"uuid"},"sender_id":{"type":"string","format":"uuid","nullable":true},"from_name":{"type":"string"},"reply_to":{"type":"string"},"postal_address":{"type":"string"},"trigger":{"type":"string","enum":["list_join","date","cart_abandoned","product_viewed","post_purchase"]},"date_field":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused"]},"activated_at":{"type":"string","format":"date-time","nullable":true},"last_refusal_code":{"type":"string","nullable":true,"description":"Why the last due step was not sent (it is retried hourly); null while sending normally."},"last_refusal_key":{"type":"string","nullable":true,"description":"The refusal catalogue key behind last_refusal_code, to render in the reader's language."},"created_at":{"type":"string","format":"date-time","nullable":true},"steps":{"type":"array","items":{"$ref":"#/components/schemas/EmailMarketingFlowStep"}},"report":{"$ref":"#/components/schemas/EmailMarketingFlowReport"}}},"EmailMarketingFlowPage":{"type":"object","required":["data","next_after"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailMarketingFlow"}},"next_after":{"type":"string","format":"uuid","nullable":true}}},"EmailMarketingFlowReport":{"type":"object","required":["enrolled","in_progress","steps"],"properties":{"enrolled":{"type":"integer"},"in_progress":{"type":"integer"},"steps":{"type":"array","items":{"type":"object","required":["position","runs","recipients"],"properties":{"position":{"type":"integer"},"runs":{"type":"integer"},"recipients":{"type":"object","additionalProperties":{"type":"integer"},"description":"Recipients by status."}}}}}},"EmailMarketingFlowStep":{"type":"object","required":["position","delay_minutes","subject","preheader","html","text","template"],"properties":{"position":{"type":"integer","minimum":0},"delay_minutes":{"type":"integer","minimum":0,"maximum":525600,"description":"Minutes after the previous step (after the trigger for the first)."},"subject":{"type":"string","maxLength":200},"preheader":{"type":"string","maxLength":200},"html":{"type":"string"},"text":{"type":"string"},"template":{"type":"string","enum":["basic","raw"]}}},"EmailMarketingFlowStepWrite":{"type":"object","required":["subject"],"properties":{"delay_minutes":{"type":"integer","minimum":0,"maximum":525600},"subject":{"type":"string","maxLength":200},"preheader":{"type":"string","maxLength":200},"html":{"type":"string"},"text":{"type":"string"},"template":{"type":"string","enum":["basic","raw"]}}},"EmailMarketingFlowWrite":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"list_id":{"type":"string","format":"uuid"},"sender_id":{"type":"string","format":"uuid","nullable":true},"from_name":{"type":"string","maxLength":80},"reply_to":{"type":"string","maxLength":254},"postal_address":{"type":"string","maxLength":300},"trigger":{"type":"string","enum":["list_join","date","cart_abandoned","product_viewed","post_purchase"]},"date_field":{"type":"string","maxLength":64,"pattern":"^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$"},"steps":{"type":"array","maxItems":20,"items":{"$ref":"#/components/schemas/EmailMarketingFlowStepWrite"}}}},"EmailMarketingForm":{"type":"object","required":["id","list_id","public_id","title","intro","button_label","consent_text","sender_name","locale","redirect_url","enabled","hosted_url","embed_html","pending","confirmed","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"list_id":{"type":"string","format":"uuid"},"public_id":{"type":"string"},"title":{"type":"string"},"intro":{"type":"string"},"button_label":{"type":"string"},"consent_text":{"type":"string"},"sender_name":{"type":"string"},"locale":{"type":"string"},"redirect_url":{"type":"string"},"enabled":{"type":"boolean"},"hosted_url":{"type":"string"},"embed_html":{"type":"string"},"pending":{"type":"integer"},"confirmed":{"type":"integer"},"created_at":{"type":"string","format":"date-time","nullable":true}}},"EmailMarketingFormPage":{"type":"object","required":["data","next_after"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailMarketingForm"}},"next_after":{"type":"string","format":"uuid","nullable":true}}},"EmailMarketingFormWrite":{"type":"object","description":"On create `list_id`, `title`, `consent_text` and `sender_name` are required.","properties":{"list_id":{"type":"string","format":"uuid"},"title":{"type":"string","maxLength":120},"intro":{"type":"string","maxLength":500},"button_label":{"type":"string","maxLength":40},"consent_text":{"type":"string","maxLength":500},"sender_name":{"type":"string","maxLength":80},"locale":{"type":"string","maxLength":16},"redirect_url":{"type":"string","maxLength":500,"description":"https:// only; empty for our page."},"enabled":{"type":"boolean"}}},"EmailMarketingImport":{"type":"object","required":["id","source_name","basis","attestation","attested_by","rows_total","rows_added","rows_updated","rows_suppressed","rows_rejected","rejected_sample","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"source_name":{"type":"string"},"basis":{"type":"string","enum":["consent","soft_opt_in"]},"attestation":{"type":"string"},"attested_by":{"type":"string"},"rows_total":{"type":"integer"},"rows_added":{"type":"integer"},"rows_updated":{"type":"integer"},"rows_suppressed":{"type":"integer"},"rows_rejected":{"type":"integer"},"rejected_sample":{"type":"array","items":{"type":"object","required":["row","reason"],"properties":{"row":{"type":"integer"},"reason":{"type":"string"}}}},"created_at":{"type":"string","format":"date-time"}}},"EmailMarketingImportCreate":{"type":"object","required":["basis","attestation","contacts"],"properties":{"basis":{"type":"string","enum":["consent","soft_opt_in"]},"attestation":{"type":"string","minLength":20,"maxLength":4000,"description":"How these people agreed to receive the customer's emails."},"source_name":{"type":"string","maxLength":200},"contacts":{"type":"array","maxItems":1000,"items":{"$ref":"#/components/schemas/EmailMarketingImportRow"}},"channels":{"type":"array","minItems":1,"description":"What these people agreed to receive. Consent is recorded per channel; SMS and WhatsApp consent is only recorded for contacts with a phone number. Defaults to email.","items":{"type":"string","enum":["email","sms","whatsapp"]}}}},"EmailMarketingImportPage":{"type":"object","required":["data","next_after"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailMarketingImport"}},"next_after":{"type":"string","format":"uuid","nullable":true}}},"EmailMarketingImportRow":{"type":"object","required":["email"],"properties":{"email":{"type":"string","maxLength":320},"phone":{"type":"string","maxLength":24,"description":"Mobile number in international format (+447700900123), for SMS and WhatsApp."},"locale":{"type":"string","maxLength":16},"consented_at":{"type":"string","description":"When the person gave consent (ISO 8601), if the customer's records say."},"attributes":{"type":"object","additionalProperties":true}}},"EmailMarketingLint":{"type":"object","required":["campaign_id","findings","errors","warnings","infos"],"properties":{"campaign_id":{"type":"string","format":"uuid"},"findings":{"type":"array","items":{"$ref":"#/components/schemas/EmailMarketingLintFinding"}},"errors":{"type":"integer","minimum":0},"warnings":{"type":"integer","minimum":0},"infos":{"type":"integer","minimum":0}}},"EmailMarketingLintFinding":{"type":"object","required":["code","severity","field","params"],"properties":{"code":{"type":"string","enum":["subject_missing","subject_long","subject_shouting","subject_punctuation","subject_fake_reply","body_missing","postal_address_missing","preheader_missing","text_part_generated","tag_stripped","html_clipped","links_many","link_invalid","link_ip_address","link_shortener","link_insecure","link_text_mismatch","image_alt_missing","image_text_ratio","trigger_phrases"]},"severity":{"type":"string","enum":["error","warning","info"]},"field":{"type":"string","description":"The campaign field the finding is about (subject, subject_b, preheader, html, text, postal_address)."},"params":{"type":"object","additionalProperties":true,"description":"Values the message needs (length, max, host, tag, count, phrases, images, words, min_words, bytes)."}}},"EmailMarketingList":{"type":"object","required":["id","name","subscribed","unsubscribed","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"subscribed":{"type":"integer"},"unsubscribed":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}},"EmailMarketingListPage":{"type":"object","required":["data","next_after"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailMarketingList"}},"next_after":{"type":"string","format":"uuid","nullable":true}}},"EmailMarketingMessage":{"type":"object","required":["id","channel","contact_id","country","parts","price_usd_micros","status","delivery","delivery_error","delivery_at","created_at"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"channel":{"type":"string","enum":["sms","whatsapp"]},"contact_id":{"type":"string","format":"uuid","nullable":true},"country":{"type":"string"},"parts":{"type":"integer","minimum":1},"price_usd_micros":{"type":"integer","minimum":0},"status":{"type":"string","enum":["reserved","sent","refunded"]},"delivery":{"type":"string","enum":["","delivered","failed","unconfirmed"],"description":"The carrier's delivery receipt for a sent message. Empty while no receipt has arrived; `failed` = the carrier or handset refused it; `unconfirmed` = the carrier gave no final answer. A failed delivery is not refunded: the carrier charged for the attempt."},"delivery_error":{"type":"string","description":"The carrier's error code on a failed delivery (for example `40008`), else empty."},"delivery_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"EmailMarketingMessagePage":{"type":"object","required":["data","next_after"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailMarketingMessage"}},"next_after":{"type":"string","format":"uuid","nullable":true}}},"EmailMarketingOverview":{"type":"object","required":["open","contacts_by_status","sender_count","max_import_rows"],"properties":{"open":{"type":"boolean"},"contacts_by_status":{"type":"object","additionalProperties":{"type":"integer"}},"sender_count":{"type":"integer"},"max_import_rows":{"type":"integer"}}},"EmailMarketingOwnSenders":{"type":"object","description":"The organisation's OWN sending identities (owner ruling 2026-11-08): SMS and WhatsApp go out under the customer's name and WhatsApp Business Account, never Zinn®'s.","required":["sender_id","sender_id_countries","whatsapp_connected","whatsapp_display_phone","whatsapp_health","sender_request_countries","sender_requests","whatsapp_signup"],"additionalProperties":false,"properties":{"sender_request_countries":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"},"description":"Countries that open once this organisation's own sender name is registered there (`POST /v1/email-marketing/sms/sender-requests`). Approvals can take a few days."},"sender_requests":{"type":"array","items":{"$ref":"#/components/schemas/EmailMarketingSenderRequest"},"description":"The latest request per country."},"sender_id":{"type":"string","maxLength":11,"description":"The alphanumeric SMS sender ID (\"\" when not set)."},"sender_id_countries":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"},"description":"Countries where `sender_id` is used. Others need a registered number."},"whatsapp_connected":{"type":"boolean","description":"The organisation's own WhatsApp Business Account is connected."},"whatsapp_display_phone":{"type":"string"},"whatsapp_health":{"$ref":"#/components/schemas/EmailMarketingWhatsappHealth"},"whatsapp_signup":{"type":["object","null"],"description":"What the browser needs to open Meta's Embedded Signup window (our app id and its signup configuration id); null when WhatsApp signup is not offered yet.","required":["app_id","config_id"],"additionalProperties":false,"properties":{"app_id":{"type":"string"},"config_id":{"type":"string"}}}}},"EmailMarketingSender":{"type":"object","required":["id","kind","name","host","port","tls","username","from_address","status","status_detail","status_detail_refusal","verified_at","created_at","dkim_record","provider","settings","health","managed"],"properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["pool","smtp","ses","resend","mailgun","sendgrid","postmark","sparkpost","brevo","mailjet","elasticemail","smtp2go","managed"]},"provider":{"type":"string","description":"The catalogue slug; empty for a connection made before the catalogue."},"managed":{"type":"object","nullable":true,"description":"`kind: managed` only (docs/1052 §3.2e): the sending domain at our provider, the DNS records to publish, and its warm-up ramp. `held` = the EU route is waiting for approval; the domain is saved and nothing is sent until it opens. Null for every other kind.","required":["domain","provider","data_location","location_source","status","held","records","reputation_band","ramp","verified_at"],"properties":{"domain":{"type":"string"},"provider":{"type":"string","enum":["telnyx","ses"]},"data_location":{"type":"string","enum":["eu","global"]},"location_source":{"type":"string","description":"`auto` (billing country) or `customer` (chosen)."},"status":{"type":"string","enum":["pending","verified","failed","degraded","suspended"]},"held":{"type":"boolean"},"records":{"type":"array","items":{"type":"object","required":["name","type","value","purpose","required"],"properties":{"name":{"type":"string"},"type":{"type":"string","enum":["TXT","CNAME","MX"]},"value":{"type":"string"},"purpose":{"type":"string","description":"ownership, spf, dkim, dmarc, return_path, or the provider's own label."},"required":{"type":"boolean"}}}},"reputation_band":{"type":"string"},"ramp":{"type":"object","required":["day","cap_today","sent_today","room_today"],"properties":{"day":{"type":"integer","minimum":1},"cap_today":{"type":"integer","nullable":true,"description":"Null once the ramp has no ceiling."},"sent_today":{"type":"integer"},"room_today":{"type":"integer","nullable":true}}},"verified_at":{"type":"string","format":"date-time","nullable":true}}},"settings":{"type":"object","description":"The provider's non-secret settings (`region`, `domain`, `message_stream`); never a secret.","additionalProperties":{"type":"string"}},"health":{"allOf":[{"$ref":"#/components/schemas/EmailMarketingSenderHealth"}],"nullable":true,"description":"The sending domain's latest DNS + reputation reading; null for pool and before the first check."},"name":{"type":"string"},"host":{"type":"string"},"port":{"type":"integer"},"tls":{"type":"string"},"username":{"type":"string"},"from_address":{"type":"string"},"status":{"type":"string","enum":["unverified","verifying","verified","failing"]},"status_detail":{"type":"string"},"status_detail_refusal":{"type":"object","nullable":true,"description":"The catalogue form of `status_detail` when the sender check wrote it: a `refusal.campaigns.verify*` `key` plus its `params`, so the dashboard renders the sentence in the reader's language. Null when `status_detail` is empty or not a sentence the check writes; show `status_detail` as given then.","required":["key","params"],"additionalProperties":false,"properties":{"key":{"type":"string","example":"refusal.campaigns.verifyDkim"},"params":{"type":"object","additionalProperties":{"type":"string"},"example":{}}}},"verified_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"dkim_record":{"type":"object","nullable":true,"description":"Pool senders only (kind pool, docs/1052 §10b): the TXT record the From domain publishes so Zinn® sending can DKIM-sign as that domain. The selector is per organisation. Null for your own SMTP, or when the key could not be read.","required":["name","type","value"],"properties":{"name":{"type":"string"},"type":{"type":"string","enum":["TXT"]},"value":{"type":"string"}}}}},"EmailMarketingSenderCreate":{"type":"object","description":"Send `provider` (a `sender-providers` slug) and the fields its catalogue row lists in `fields`; the row decides `kind`, and a mailbox provider's SMTP host, port and TLS come from the row. Without `provider`, `kind` is `pool` (name and from address only) or `smtp` (`host`, `username` and `password` required). A missing or malformed field for the chosen provider is refused by name (`refusal.campaigns.providerField`). Every secret (`password`, `api_key`, `api_secret`, `access_key_id`, `secret_access_key`) goes to the secret store and is never returned; `region`, `domain` and `message_stream` are kept as the connection's `settings`. `kind: managed` (Zinn® managed delivery, docs/1052 §3.2e) needs only `name` and `from_address`: the From domain is created at our sending provider and its records are returned on the sender's `managed` object; `data_location` picks EU (held until the EU route opens) or Global, and defaults to the billing country's. Refused with `refusal.campaigns.managedNotOpen` when the line is not open to the organisation and `refusal.campaigns.managedDataLocation` for any other location.","required":["name","from_address"],"properties":{"data_location":{"type":"string","enum":["eu","global"],"description":"Managed senders only."},"kind":{"type":"string","enum":["pool","smtp","ses","resend","mailgun","sendgrid","postmark","sparkpost","brevo","mailjet","elasticemail","smtp2go","managed"]},"provider":{"type":"string","maxLength":32,"description":"A slug from GET /v1/email-marketing/sender-providers."},"name":{"type":"string","maxLength":80},"from_address":{"type":"string","maxLength":254},"host":{"type":"string","maxLength":253},"port":{"type":"integer","enum":[25,465,587,2525],"default":587},"tls":{"type":"string","enum":["starttls","implicit"]},"username":{"type":"string","maxLength":320},"password":{"type":"string","maxLength":1000,"writeOnly":true},"region":{"type":"string","maxLength":16},"domain":{"type":"string","maxLength":253},"message_stream":{"type":"string","maxLength":100},"api_key":{"type":"string","maxLength":500,"writeOnly":true},"api_secret":{"type":"string","maxLength":500,"writeOnly":true},"access_key_id":{"type":"string","maxLength":500,"writeOnly":true},"secret_access_key":{"type":"string","maxLength":500,"writeOnly":true}}},"EmailMarketingSenderDnsChange":{"type":"object","required":["name","type","action","value","current"],"properties":{"name":{"type":"string","description":"The fully qualified record name."},"type":{"type":"string","enum":["TXT","CNAME","MX"]},"action":{"type":"string","enum":["create","replace"]},"value":{"type":"string"},"current":{"type":"array","items":{"type":"string"},"description":"What a `replace` overwrites."},"priority":{"type":"integer","description":"MX records only."}}},"EmailMarketingSenderDnsPlan":{"type":"object","required":["domain","zone","writable","refusal","changes"],"properties":{"domain":{"type":"string"},"zone":{"type":"string"},"writable":{"type":"boolean","description":"Whether we serve this zone's DNS and can write it."},"refusal":{"type":"object","nullable":true,"description":"Why it is not writable, as a catalogue key the dashboard renders.","required":["key","params"],"properties":{"key":{"type":"string","example":"refusal.campaigns.dnsNotOurs"},"params":{"type":"object","additionalProperties":{"type":"string"}}}},"changes":{"type":"array","items":{"$ref":"#/components/schemas/EmailMarketingSenderDnsChange"}}}},"EmailMarketingSenderHealth":{"type":"object","description":"One DNS + reputation check of a sending domain (SPF, DKIM, DMARC, MX, PTR, BIMI, MTA-STS, TLS-RPT, DNS blocklists; docs/1052 §3.2c). `blind` means we could not ask and is never read as healthy.","required":["domain","provider","status","findings","blocklisted_on","checked_at"],"properties":{"domain":{"type":"string"},"provider":{"type":"string"},"status":{"type":"string","enum":["ok","warn","fail","blind"]},"findings":{"type":"array","items":{"type":"object","required":["code","severity","record"],"properties":{"code":{"type":"string"},"severity":{"type":"string","enum":["fail","warn","info"]},"record":{"type":"string","enum":["SPF","DKIM","DMARC","MX","PTR","BIMI","MTA-STS","TLS-RPT","DNSBL"]},"name":{"type":"string"},"expected":{"type":"string"},"found":{"type":"string"}}}},"blocklisted_on":{"type":"array","items":{"type":"string"}},"checked_at":{"type":"string","format":"date-time","nullable":true}}},"EmailMarketingSenderList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailMarketingSender"}},"pool_offered":{"type":"boolean","description":"Whether `kind: pool` (Zinn® sending) may be connected. `false` for a white-labelled organisation (a reseller and its clients), which sends through its own server only, because a pool message names our relay in its headers."},"managed_offered":{"type":"boolean","description":"Whether `kind: managed` (Zinn® managed delivery) may be connected now."},"managed_locations":{"type":"array","description":"Each data location the connect form offers, its provider, and whether its route is held (waiting for approval).","items":{"type":"object","required":["location","provider","held"],"properties":{"location":{"type":"string","enum":["eu","global"]},"provider":{"type":"string","enum":["telnyx","ses"]},"held":{"type":"boolean"}}}},"managed_default_location":{"type":"string","nullable":true,"enum":["eu","global"],"description":"The location the billing country picks; null when managed delivery is not offered."}}},"EmailMarketingSenderProvider":{"type":"object","description":"One sender catalogue row (docs/1052 §3.2b).","required":["slug","name","family","auth","connectable","modes","fields","regions","webhook_scheme"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"family":{"type":"string","enum":["esp_api","mailbox"]},"auth":{"type":"array","items":{"type":"string"}},"connectable":{"type":"boolean","description":"Whether an adapter exists for at least one of its auth methods."},"modes":{"type":"array","items":{"type":"string"}},"fields":{"type":"array","items":{"type":"string"},"description":"The create fields this provider needs."},"regions":{"type":"array","items":{"type":"string"}},"website":{"type":"string"},"setup_url":{"type":"string"},"brand_color":{"type":"string"},"smtp":{"type":"object","nullable":true,"additionalProperties":true},"imap":{"type":"object","nullable":true,"additionalProperties":true},"dkim_selectors":{"type":"array","items":{"type":"string"}},"spf_include":{"type":"string"},"webhook_scheme":{"type":"string","description":"How delivery events arrive: `svix`, `mailgun_hmac`, `url_token` or `sns` (a webhook endpoint), `imap` (a mailbox, read for bounces), or `none`."},"daily_limit":{"type":"integer","nullable":true}}},"EmailMarketingSenderRequest":{"type":"object","description":"A request to register this organisation's own SMS sender name in a country that needs one (`docs/1052` §3.5d). `pending` until our team has the carrier's answer, which can take a few days; `approved` opens the country for this organisation alone.","required":["id","country","sender_id","status","reason","created_at","decided_at"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"country":{"type":"string","pattern":"^[A-Z]{2}$"},"sender_id":{"type":"string","maxLength":11},"status":{"type":"string","enum":["pending","approved","rejected"]},"reason":{"type":"string","description":"The carrier's reason when rejected."},"created_at":{"type":"string","format":"date-time"},"decided_at":{"type":"string","format":"date-time","nullable":true}}},"EmailMarketingSms":{"type":"object","required":["open","paused","credit_balance_usd_micros","max_characters","prices","sender_id","sender_id_countries","whatsapp_connected","whatsapp_display_phone","whatsapp_health","sender_request_countries","sender_requests","whatsapp_signup","whatsapp_open","whatsapp_paused"],"additionalProperties":false,"properties":{"whatsapp_open":{"type":"boolean","description":"WhatsApp sending is open to this organisation (line, account and switch)."},"whatsapp_paused":{"type":"boolean","description":"WhatsApp sending is paused for this organisation (its own spike pause)."},"sender_request_countries":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"}},"sender_requests":{"type":"array","items":{"$ref":"#/components/schemas/EmailMarketingSenderRequest"}},"open":{"type":"boolean"},"paused":{"type":"boolean"},"credit_balance_usd_micros":{"type":"integer","description":"The Zinn® credit a text can spend now (bought credit; plan-included AI credit is excluded), the same number the send is gated on and the US registration shows."},"max_characters":{"type":"integer"},"prices":{"type":"array","items":{"type":"object","required":["country","price_usd_micros_per_part"],"additionalProperties":false,"properties":{"country":{"type":"string","pattern":"^[A-Z]{2}$"},"price_usd_micros_per_part":{"type":"integer","minimum":0}}}},"sender_id":{"type":"string","maxLength":11},"sender_id_countries":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"}},"whatsapp_connected":{"type":"boolean"},"whatsapp_display_phone":{"type":"string"},"whatsapp_health":{"$ref":"#/components/schemas/EmailMarketingWhatsappHealth"},"whatsapp_signup":{"type":["object","null"],"description":"Embedded Signup's app and configuration ids; null when not offered yet.","required":["app_id","config_id"],"additionalProperties":false,"properties":{"app_id":{"type":"string"},"config_id":{"type":"string"}}}}},"EmailMarketingTestResult":{"type":"object","required":["outcome","detail"],"properties":{"outcome":{"type":"string","enum":["accepted","rejected","deferred"]},"detail":{"type":"string"}}},"EmailMarketingThresholdValues":{"type":"object","additionalProperties":false,"required":["bounce_pause_enabled","bounce_pause_bps","complaint_pause_enabled","complaint_pause_bps","bounce_warn_bps","complaint_warn_bps"],"properties":{"bounce_pause_enabled":{"type":"boolean"},"bounce_pause_bps":{"type":"integer","description":"Basis points (500 = 5%)."},"complaint_pause_enabled":{"type":"boolean"},"complaint_pause_bps":{"type":"integer","description":"Basis points (30 = 0.3%)."},"bounce_warn_bps":{"type":"integer","description":"Soft guard line (staff alert","never a pause).":null},"complaint_warn_bps":{"type":"integer","description":"Soft guard line (staff alert","never a pause).":null}}},"EmailMarketingUsRegistration":{"type":"object","required":["id","country","status","test","brand_name","usecase","reason_code","vendor_reason","phone_number","price_usd_micros","refunded_usd_micros","paid_through","created_at","updated_at"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"country":{"type":"string","enum":["US"]},"status":{"type":"string","enum":["submitting","pending","approved","rejected","lapsed"],"description":"`submitting` and `pending` are shown as waiting; `approved` means US is open to this organisation from `phone_number`; `rejected` and `lapsed` carry a `reason_code`."},"test":{"type":"boolean","description":"A test registration (free, never sent to the carriers, never opens US)."},"brand_name":{"type":"string"},"usecase":{"type":"string"},"reason_code":{"type":"string","nullable":true,"enum":["details_invalid","brand_identity","campaign_rejected","carrier_rejected","suspended","renewal_unpaid"]},"vendor_reason":{"type":"string","nullable":true,"description":"The provider's own sentence (English), shown as a quotation."},"phone_number":{"type":"string","nullable":true},"price_usd_micros":{"type":"integer","minimum":0},"refunded_usd_micros":{"type":"integer","minimum":0},"paid_through":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"EmailMarketingUsRegistrationState":{"type":"object","required":["credit_balance_usd_micros","credit_topup_path","test_mode","quote","registration","usecases","entity_types","verticals"],"additionalProperties":false,"properties":{"credit_balance_usd_micros":{"type":"integer","nullable":true,"description":"The Zinn® credit the registration is paid from, as spendable now (bought credit; plan-included AI credit cannot pay for SMS). The page shows it beside the quote, with the shortfall and a top-up, so a submit is never made into a `no_credit` refusal (WALLETBILL1113). Null when no organisation is in scope."},"credit_topup_path":{"type":"string","description":"Dashboard path where Zinn® credit is bought."},"test_mode":{"type":"boolean"},"quote":{"type":"object","nullable":true,"required":["upfront_price_usd_micros","nonrefundable_price_usd_micros","monthly_price_usd_micros","upfront_months"],"additionalProperties":false,"properties":{"upfront_price_usd_micros":{"type":"integer","minimum":0},"nonrefundable_price_usd_micros":{"type":"integer","minimum":0,"description":"The part of the upfront price that cannot be refunded once submitted (the registration fee, the carriers' review fee and the campaign's first months, which the carriers bill up front even when they reject it). Shown before paying and acknowledged with `fees_acknowledged`."},"monthly_price_usd_micros":{"type":"integer","minimum":0},"upfront_months":{"type":"integer","minimum":1}}},"registration":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/EmailMarketingUsRegistration"}]},"usecases":{"type":"array","items":{"type":"string"}},"entity_types":{"type":"array","items":{"type":"string"}},"verticals":{"type":"array","items":{"type":"string"}}}},"EmailMarketingWhatsappHealth":{"type":"object","description":"Whether Meta lets the organisation's OWN WhatsApp Business Account send (docs/1052 §3.5j), as last read (`checked_at`). `blocked`: Meta refuses its messages and our sends are refused with `whatsapp_cannot_send` until every blocking reason is fixed. `limited`: sends go out, capped. `unknown`: Meta could not be read yet (not blocked by us). `not_connected`: no account. Each reason says where it is fixed: `meta` = a Meta Business page (open in a new tab), `app` = a dashboard path.","required":["state","reasons","checked_at"],"properties":{"state":{"type":"string","enum":["ready","limited","blocked","unknown","not_connected"]},"reasons":{"type":"array","items":{"type":"object","required":["code","blocking","fix_where","fix_url","meta_code"],"additionalProperties":false,"properties":{"code":{"type":"string","enum":["payment_method","business_verification","no_approved_template","phone_not_connected","display_name_pending","display_name_rejected","token_expired","meta_other"]},"blocking":{"type":"boolean"},"fix_where":{"type":"string","enum":["meta","app"]},"fix_url":{"type":"string"},"meta_code":{"type":"integer","description":"Meta's numeric code (0 when none)."}}}},"templates_approved":{"type":["integer","null"]},"messaging_limit_tier":{"type":"string"},"check_error":{"type":"string","description":"\"unavailable\" when the last read failed (the verdict shown is the one before)."},"checked_at":{"type":["string","null"],"format":"date-time"}}},"EmailMarketingWhatsappTemplate":{"type":"object","required":["name","language","status","category"],"additionalProperties":false,"properties":{"name":{"type":"string"},"language":{"type":"string"},"status":{"type":"string","description":"Meta's review status: APPROVED, PENDING, REJECTED, PAUSED, ..."},"category":{"type":"string"}}},"EmailMarketingZeroBounce":{"type":"object","required":["connected","key_hint","connected_at","modes"],"properties":{"connected":{"type":"boolean"},"key_hint":{"type":"string","nullable":true,"description":"The key's last four characters; null when none is connected."},"connected_at":{"type":"string","format":"date-time","nullable":true},"modes":{"type":"array","items":{"type":"string","enum":["off","invalid","risky"]}},"credits":{"type":"integer","description":"Only on `PUT`: the credit balance ZeroBounce reported for the key."}}},"EmailMarketingZeroBounceConnect":{"type":"object","required":["api_key"],"properties":{"api_key":{"type":"string","minLength":1,"maxLength":200,"description":"The API key from the organisation's own ZeroBounce account. Write-only."}}},"EmailMarketingZeroBounceVerification":{"type":"object","required":["mode","checked","reused","skipped","skipped_by_verdict"],"properties":{"mode":{"type":"string","enum":["off","invalid","risky"]},"checked":{"type":"integer","description":"Addresses sent to ZeroBounce for this campaign (one credit each","except `unknown`).":null},"reused":{"type":"integer","description":"Addresses whose verdict from the last 90 days was reused: no credit spent."},"skipped":{"type":"integer","description":"Recipients not sent to because of their verdict."},"skipped_by_verdict":{"type":"object","additionalProperties":{"type":"integer"},"description":"Skipped recipients per ZeroBounce status (invalid, spamtrap, abuse, do_not_mail, catch-all, unknown)."}}},"EmailRoutingAction":{"type":"string","description":"`drop` is a chosen behaviour — it is how a catch-all silently discards spam — and is never inferred from an empty destination list.","enum":["forward","drop"],"example":"forward"},"EmailWarning":{"type":"object","required":["code","provider"],"description":"MAILQUOTA (owner ruling 2026-11-11): the address is a REAL mailbox that cannot take mail right now, so messages we send it may bounce. Never a refusal: the buyer is told and carries on or changes the address. `code` is `mailbox_full`; `provider` names the mailbox provider (\"Gmail\", \"Outlook\") or is empty when it is not one we recognise.","properties":{"code":{"type":"string","enum":["mailbox_full"]},"provider":{"type":"string","example":"Gmail"}}},"EntitlementAllowance":{"type":"object","description":"One counted entitlement: the cap the plan sold, and how much of it is spent.","required":["key","label","used","limit","unlimited","enforced","remaining"],"properties":{"key":{"type":"string","description":"The registry key, e.g. `team_seats`.","example":"team_seats"},"label":{"type":"string","description":"The registry's human label for the key.","example":"Team member seats"},"used":{"type":"integer","description":"Current consumption, counted across the entitling organization's whole subtree — a reseller's plan pays for its clients, so their usage is inside its allowance, exactly as `max_sites` is counted.","example":3},"limit":{"type":"integer","nullable":true,"description":"`-1` unlimited, `>= 0` a real cap, **`null` when the plan states no cap**. Null is not zero and must never be rendered as one.","example":10},"unlimited":{"type":"boolean","description":"The plan sold \"unlimited\" explicitly (`limit` is `-1`)."},"enforced":{"type":"boolean","description":"A real number governs this allowance. False for both unlimited and unstated — branch on this to decide whether to draw a usage bar."},"remaining":{"type":"integer","nullable":true,"description":"Slots left, never negative; `null` when not enforced. Clamped at zero because a downgrade does not delete what the customer already has.","example":7}}},"EntitlementFeature":{"type":"object","description":"One boolean entitlement, and where in the product it is spent.","required":["key","label","included","where"],"properties":{"key":{"type":"string","example":"git_version_control"},"label":{"type":"string","example":"Git version control"},"included":{"type":"boolean"},"where":{"type":"string","description":"The screen this grant is spent on, so \"included\" is actionable. A customer told they have git deploys and unable to find them has a fact, not a feature.","example":"Integrations"}}},"EntitlementUsage":{"type":"object","description":"Everything an organization bought and how much of it is used (#2726).","required":["entitling_org_id","source","plan_name","has_plan","allowances","features"],"properties":{"entitling_org_id":{"allOf":[{"$ref":"#/components/schemas/Uuid"}],"nullable":true,"description":"The organization whose plan grants these — the caller's own org or an ancestor. Null when nothing in the chain grants anything."},"source":{"type":"string","enum":["staff","subscription","none"],"description":"Where the grant came from. The customer's next move differs: a `staff` grant is not upgradable, a `subscription` one is, and `none` means there is nothing to upgrade *from* — buy a plan rather than change tier."},"plan_name":{"type":"string","nullable":true,"example":"Reseller Launch"},"has_plan":{"type":"boolean"},"allowances":{"type":"array","items":{"$ref":"#/components/schemas/EntitlementAllowance"}},"features":{"type":"array","items":{"$ref":"#/components/schemas/EntitlementFeature"}}}},"Entitlements":{"type":"object","description":"The effective grants for a plan — feature flags (`bool`), quotas (`int`) and tier codes (`string`), keyed by the entitlement catalogue codes (docs/18). A free-form map by design: the key set is the entitlement catalogue, which versions independently of this API.\n\nA quota value of `-1` is the canonical **unlimited** sentinel (no cap) — never the string `\"unlimited\"`; consumers treat any negative quota as unbounded. Trial-eligible plans also carry a derived `trial_days` quota (the plan's free trial length in days); it is absent on plans that do not offer a trial, which a consumer reads as `0`.","additionalProperties":true,"example":{"footprint_free":true,"max_sites":25,"backup_retention_days":30,"trial_days":7}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code (SCREAMING_SNAKE_CASE).","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable summary, in ENGLISH. ⛔⛔ This said \"localizable\" for a year and nothing localized it: every refusal on the estate was composed in English at the point it was raised, and 255 of them reached a reader as a sentence (W43-138). The localized half is `refusal` below — this field is the fallback and the SDK/CLI answer, not a translated string.","example":"The requested organization does not exist or is not in scope."},"details":{"type":"array","description":"Field-level validation problems, when applicable.","items":{"$ref":"#/components/schemas/ErrorDetail"}},"request_id":{"type":"string","description":"Correlation ID; quote it in support requests.","example":"req_0190f1a23b4c"},"failure":{"allOf":[{"$ref":"#/components/schemas/VendorFailure"}],"description":"`CLAUDE.md` §57 — present only when an AI path, or a vendor the customer connected with their own key (the SEO data sources, `connectSeoDataKey`), classified the failure behind this refusal: whether the provider is down, whether the CUSTOMER's own key or account with that provider needs attention, or whether it is our fault. Absent (never `null`) on every other error, so a client that renders a notice whenever the field is present is never handed an empty one. Built only by `engine.drivers.vendor_errors.for_customer` (directly, or through `engine.ai.failure_surface.refusal_in_use` at the AI seam); a hand-built copy at a call site is a second taxonomy and is not allowed."},"refusal":{"allOf":[{"$ref":"#/components/schemas/Refusal"}],"description":"`CLAUDE.md` §2.19 — present when the engine refused with a message KEY rather than an English sentence, so a console can render it in the reader's own language. Absent (never `null`) otherwise, and a client that has no copy for the key falls back to `message` — so an unknown key never reaches a customer raw. ⛔ `message` above stays English and stays authoritative for the SDK, the CLI and any direct caller, which have no catalogue to render a key from."},"payment":{"allOf":[{"$ref":"#/components/schemas/PaymentStep"}],"description":"Q225 — present only on a `PAYMENT_METHOD_REQUIRED` refusal from a one-click purchase that was PLACED and waits for the customer to pay it on-session. Absent (never `null`) on every other error."}}}}},"ErrorDetail":{"type":"object","required":["field","code"],"properties":{"field":{"type":"string","description":"JSON path to the offending field.","example":"default_currency"},"code":{"type":"string","example":"INVALID"},"message":{"type":"string","example":"Must be a supported ISO 4217 currency code."},"fresh_total_minor":{"type":"integer","format":"int64","minimum":0,"description":"Only on a `TOTAL_CHANGED` refusal from `POST /v1/public/checkout` (docs/1311): the order total (tax included, minor units) the checkout WILL place or resume at. A resumed order is frozen, so after a billing-country or price change the basket's re-quote never equals it; the page shows this figure and sends it back as `expected_total_minor` on the next press. Equality is still required: a stale, lower or higher figure is refused again and never paid.","example":960},"provider":{"type":"string","description":"Only on an `EMAIL_MAILBOX_FULL` detail from `POST /v1/public/checkout` (MAILQUOTA): the mailbox provider whose inbox is full (\"Gmail\", \"Outlook\"), or empty when unknown.","example":"Gmail"},"suggestion":{"type":"string","maxLength":320,"description":"Only on an `EMAIL_POSSIBLE_TYPO` detail of a `403 SIGNUP_EMAIL_REFUSED` (EMAILTYPO): the address as typed with its domain replaced by the one the e-mail validator suggested. A page may put it in the e-mail field for the buyer to confirm.","example":"ann@gmail.com"}}},"EspConnection":{"type":"object","description":"A tenant's own e-mail provider account. ⚖️ Owner ruling 2026-08-26 — a reseller sends through their own account, and one that is missing or unverified is REFUSED rather than quietly served from the platform key. ⛔ `status` distinguishes three states because the fix differs in each; one collapsed message tells the operator nothing they can act on. ⭐ The platform's own staff org is the one exception: with no account of its own it sends through the platform account, and reads `platform` (with the From and Reply-To that account sends as) — or `platform_key_missing` when the platform key is absent from this environment, the one case where a staff campaign is refused. A customer or reseller org never reads either.","required":["connected","status","provider"],"additionalProperties":false,"properties":{"connected":{"type":"boolean"},"id":{"type":"string","format":"uuid"},"provider":{"type":"string"},"status":{"type":"string","enum":["not_connected","unverified","verified","rejected","platform","platform_key_missing"]},"from_address":{"type":"string"},"marketing_from_address":{"type":"string","description":"Platform account only (`status: platform`): the From a MARKETING campaign sends as, on the separate marketing sending domain. `from_address` is every other purpose."},"from_local_part":{"type":"string"},"from_display_name":{"type":"string"},"sending_domain":{"type":"string"},"reply_to":{"type":"string"},"verified_domains":{"type":"array","items":{"$ref":"#/components/schemas/EspVerifiedDomain"}},"last_verified_at":{"type":"string","format":"date-time","nullable":true},"last_error":{"type":"string"},"stats":{"$ref":"#/components/schemas/CampaignDeliveryCounts"}}},"EspConnectionInput":{"type":"object","description":"⛔ `api_key` is write-only. It is accepted once, written to Vault, and never echoed by any endpoint, log line or audit record.","required":["api_key"],"additionalProperties":false,"properties":{"api_key":{"type":"string","writeOnly":true},"from_local_part":{"type":"string","maxLength":64},"from_display_name":{"type":"string","maxLength":120},"sending_domain":{"type":"string","maxLength":253},"reply_to":{"type":"string","maxLength":320},"org_id":{"type":"string","format":"uuid"}}},"EspVerifiedDomain":{"type":"object","required":["name","status"],"additionalProperties":false,"properties":{"name":{"type":"string"},"status":{"type":"string"},"region":{"type":"string"}}},"ExamBoostBooking":{"type":"object","description":"One Exam Boost booking for a site.","required":["id","status","free","starts_at","ends_at","applied_at","reverted_at","ended_early_at","refund_credit","boosted_resources","plan_resources"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["awaiting_payment","scheduled","active","ended","cancelled","lapsed"]},"free":{"type":"boolean"},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"},"applied_at":{"type":"string","format":"date-time","nullable":true},"reverted_at":{"type":"string","format":"date-time","nullable":true},"ended_early_at":{"type":"string","format":"date-time","nullable":true},"refund_credit":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ExamBoostMoney"}]},"boosted_resources":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ExamBoostLimits"}]},"plan_resources":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ExamBoostLimits"}]}}},"ExamBoostLimits":{"type":"object","description":"CloudLinux LVE limits as `lvectl` flags (speed, pmem, io, iops, maxEntryProcs, nproc).","additionalProperties":{"type":"string"}},"ExamBoostMoney":{"type":"object","description":"An amount in integer minor units with its ISO currency (§2.8).","required":["amount_minor","currency"],"properties":{"amount_minor":{"type":"integer"},"currency":{"type":"string","minLength":3,"maxLength":3}}},"ExternalBackupChannel":{"type":"string","description":"How we reach a site we do not host. `connector` is the Zinn® Connector plugin (outbound-only, backup but no restore); `ssh` is SSH/SFTP, the only channel that can push a site back when the site itself is down.","enum":["connector","ssh"]},"ExternalBackupConnection":{"type":"object","description":"The backup channel configured for an externally hosted site. Carries no credential, ever.","required":["configured","channel","enabled","can_restore","summary","ssh_host","ssh_port","ssh_username","remote_path","credential_present","last_verified_at","last_verified_ok","last_verify_detail","extra_paths","detected_data_paths","missing_data_paths"],"properties":{"configured":{"type":"boolean","description":"False when nobody has connected this site yet. The rest of the object is still present and empty — a screen must not have to tell \"not set up\" from \"failed to load\" by the absence of fields."},"channel":{"oneOf":[{"$ref":"#/components/schemas/ExternalBackupChannel"},{"type":"string","enum":[""]}],"description":"Empty string when `configured` is false."},"enabled":{"type":"boolean","description":"A disabled connection is paused, not deleted — the set-up survives."},"can_restore":{"type":"boolean","description":"Whether we can push a backup back down this channel. **False for `connector`**, and that is not a limitation to route around: a WordPress plugin cannot run inside a WordPress too broken to load, which is exactly the site being restored. Gate any restore button on this field rather than on `configured`."},"summary":{"type":"string","description":"One sentence stating what this connection can and cannot do, composed server-side so every surface says the same thing about the backup/restore asymmetry."},"ssh_host":{"type":"string","description":"Empty on a `connector` connection."},"ssh_port":{"type":"integer","format":"int32","minimum":1,"maximum":65535},"ssh_username":{"type":"string"},"remote_path":{"type":"string","description":"The site's document root — what we archive, and what we restore into."},"credential_present":{"type":"boolean","description":"Whether a credential is stored in our secret store. The credential itself is never returned by any endpoint."},"last_verified_at":{"type":"string","format":"date-time","nullable":true,"description":"Null when the connection has never been checked."},"last_verified_ok":{"type":"boolean","nullable":true,"description":"Null means never checked, which is not the same as failing — the absence of a measurement is not a measurement."},"last_verify_detail":{"type":"string"},"extra_paths":{"type":"array","maxItems":10,"items":{"type":"string"},"description":"Folders outside the document root the customer added to every backup (absolute paths). Empty on a connector connection."},"detected_data_paths":{"type":"array","items":{"$ref":"#/components/schemas/ExternalBackupDataPath"},"description":"Every folder outside the document root that the LAST backup carried: read from the application's own configuration (Moodle `dataroot`, Nextcloud/ownCloud `datadirectory`, Drupal `file_private_path`) or added by the customer. A restore writes back only to these folders and `extra_paths`."},"missing_data_paths":{"type":"array","items":{"$ref":"#/components/schemas/ExternalBackupDataPath"},"description":"Folders named by the application's configuration or the customer that did not exist at the last backup, so are NOT in it."},"job_token":{"type":"string","nullable":true,"description":"Present **only** on the response to `PUT` with `channel: connector`, and only that once. The token the Zinn® Connector plugin presents when it asks for a backup job — paste it into the plugin's Backups tab (\"Backup token\"). We keep only its hash, so it cannot be read again: a lost token is replaced by connecting again, which also invalidates the old one. `null` on an `ssh` connection, and absent from `GET`."}}},"ExternalBackupDataPath":{"type":"object","required":["kind","path"],"properties":{"kind":{"type":"string","description":"`moodle`, `nextcloud` (also ownCloud) or `drupal` when read from the application's configuration; `wordpress-config` for a WordPress `wp-config.php` kept one level above the document root (a single file, only its path is ever returned); `custom` when the customer added it."},"path":{"type":"string"}}},"ExternalSite":{"type":"object","required":["site_id","primary_domain","name","is_external","base_url","backup"],"properties":{"site_id":{"type":"string","format":"uuid"},"primary_domain":{"type":"string"},"name":{"type":"string"},"is_external":{"type":"boolean","description":"Always true here. The same site appears in `/v1/sites` badged External."},"base_url":{"type":"string","description":"The address we publish to, including any path (e.g. `https://example.com/blog`)."},"reachable":{"type":"boolean","nullable":true,"description":"What the last check found. **`null` means we have not checked**, which is not the same as \"it does not work\" — an unchecked site is never rendered as broken."},"checked_at":{"type":"string","format":"date-time","nullable":true},"detail":{"type":"string","description":"What the site said last time, verbatim. Shown on the site's own screen."},"detected_identity":{"type":"string"},"backup":{"type":"object","description":"Whether we can back this site up, and whether we can put it back. Served on the list so a screen showing a customer's whole external estate makes one request rather than one per row.","required":["configured","channel","enabled","can_restore"],"properties":{"configured":{"type":"boolean","description":"Whether a backup channel has been set up for this site at all."},"channel":{"type":"string","enum":["","connector","ssh"],"description":"How we reach it. Empty when nothing is configured."},"enabled":{"type":"boolean"},"can_restore":{"type":"boolean","description":"Whether a restore can be **pushed back** down this channel. `false` for `connector`, and that is a product fact rather than a missing feature: a WordPress plugin cannot run inside a WordPress too broken to load, which is precisely the site somebody is restoring. Gate any restore affordance on this, never on `configured`."}}}}},"ExternalSiteRemoval":{"type":"object","required":["site_id","primary_domain","charges_stopped","backups_kept_until"],"properties":{"site_id":{"type":"string","format":"uuid"},"primary_domain":{"type":"string"},"charges_stopped":{"type":"integer","description":"Monthly add-on charges for this site that were stopped."},"backups_kept_until":{"type":"string","format":"date-time","nullable":true,"description":"When the newest archive we hold for the site is deleted by retention; null if none."}}},"Extra":{"type":"object","required":["id","code","name","description","category","fulfilment_type","interval","price","sla_hours","product_lines","is_active","requires_site","scope","sort_order","cadence_days"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"code":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"fulfilment_type":{"$ref":"#/components/schemas/ExtraFulfilmentType"},"interval":{"$ref":"#/components/schemas/ExtraInterval"},"price":{"$ref":"#/components/schemas/MoneyAmount"},"sla_hours":{"type":["integer","null"]},"product_lines":{"type":"array","description":"Product-line codes this extra is offered on; empty = all lines.","items":{"type":"string"}},"is_active":{"type":"boolean"},"requires_site":{"type":"boolean","description":"Whether this extra acts on **one site** and therefore cannot be fulfilled unless the purchase names a `site_id`. A storefront must ask which site *before* charging: the fulfilment handler refuses a purchase with no site, so buying one account-level takes the money and refunds it minutes later.\n\nDerived from the fulfilment driver registry, so it cannot drift from what the handler actually requires.","example":true},"scope":{"type":["string","null"],"enum":["account","site","domain",null],"description":"What the add-on is bought **by** — the unit of sale. `account` means one per organisation, so owning it once means it cannot be bought again. `site` means one per hosted site: owning it for one site says nothing about another, and the customer may buy it again. `domain` means one per zone (Premium DNS).\n\n⛔ NOT a synonym for `requires_site`, and the two disagree on purpose. That flag answers a charge-safety question — \"will this refund if nobody names a site?\" — and is read from the fulfilment registry, so it is `false` for every staff-fulfilled row including Malware Cleanup, SSL Setup and Managed Migration, all of which are sold per site. It is also `true` for Premium DNS, which is sold per domain. Neither direction of the implication holds.\n\nA storefront needs this to answer \"do they already own it?\", because an org-wide ownership check is wrong for every row that is not `account`-scoped: it hides the upsell and the customer cannot buy a thing they want for a second site.\n\n`null` for a category the platform has not classified. Serialised rather than omitted so a client can tell \"account-scoped\" from \"we do not know\" and degrade honestly rather than assuming.","example":"site"},"sort_order":{"type":"integer","description":"The operator's merchandising order for this add-on within its category, set in the staff console. Lower sorts first; ties fall back to price ascending, then name.\n\nA storefront must honour this rather than sorting by price, because a category can hold a base product AND a top-up that extends it: `private_network` holds a $24 network and a $10 five-seat pack, so price-ascending advertises the seats above the thing they are seats for. `premium_dns` holds retail, fleet and reseller pricing for one product, and price-ascending shows the reseller wholesale rate first to everybody.","example":35},"cadence_days":{"type":["integer","null"],"description":"For a recurring product that RUNS on a schedule, how many days pass between automatic runs. This is what lets a storefront answer \"how often does it run for that price\" *before* anybody buys, rather than only after a subscription exists.\n\n`null` for everything without a schedule, which is most of the catalogue: a one-off job has no cadence, and a monthly *entitlement* such as Priority Support is not something that runs. A default would put a confident, wrong frequency on rows nobody has considered.\n\nRead from the same constant the sweep honours, so a card cannot advertise a cadence the engine does not keep.","example":30},"seo_terms":{"description":"The yearly price and 3-tool bundle of an **SEO tool**, priced by the engine so no screen types a percentage. `null` on every row that is not an SEO tool.","anyOf":[{"$ref":"#/components/schemas/ExtraSeoTerms"},{"type":"null"}]}}},"ExtraFulfilmentType":{"type":"string","description":"How an extra is delivered.","enum":["automated","staff"]},"ExtraInterval":{"type":"string","description":"One-off charge or a recurring subscription. `annual` is a PURCHASE term only — an SEO tool bought twelve months at a time at V1's yearly saving (D19, 2026-09-25). No catalogue row carries it.","enum":["one_off","monthly","annual"]},"ExtraList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Extra"}}}},"ExtraPurchase":{"type":"object","required":["id","org_id","extra_id","status","category","fulfilment_type","interval","price","recurrence","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"org_id":{"$ref":"#/components/schemas/Uuid"},"extra_id":{"$ref":"#/components/schemas/Uuid"},"site_id":{"type":["string","null"],"format":"uuid"},"domain_id":{"type":["string","null"],"format":"uuid"},"order_id":{"type":["string","null"],"format":"uuid","description":"The order this purchase was charged on — or, while `awaiting_payment` (Q225), is waiting to be paid on: settle it with `payOrder`. `null` for a staff comp or a purchase paid from AI credit, which have no order."},"status":{"$ref":"#/components/schemas/ExtraPurchaseStatus"},"category":{"type":"string"},"fulfilment_type":{"$ref":"#/components/schemas/ExtraFulfilmentType"},"interval":{"$ref":"#/components/schemas/ExtraInterval"},"price":{"$ref":"#/components/schemas/MoneyAmount"},"recurrence":{"description":"Whether the recurrence behind this purchase is still live. `none` = it never recurred (a one-off); `active` = a scheduled charge exists; `ended` = it recurred and no longer does. Three values rather than a boolean because a one-off and a lapsed subscription are opposite facts that `recurring: false` would report identically — only `ended` belongs in an expired section.","type":"string","enum":["none","active","ended"]},"next_renewal_on":{"description":"The next charge date, or `null`. Also `null` for a live charge that has no date scheduled yet, so read `recurrence` — not this field — to decide whether a purchase renews at all.","type":["string","null"],"format":"date"},"renews_as":{"description":"Q321 — the smaller tier of the same SEO tool chosen for the next renewal (`scheduleExtraTierSwitch`), or `null` when the purchase renews as itself.","oneOf":[{"type":"null"},{"type":"object","required":["code","name"],"properties":{"code":{"type":"string"},"name":{"type":"string"}}}]},"arrears":{"description":"s1014 R40 GAP-5/6/7 (docs/747 §2b, V1 parity). `null`, or this add-on's unpaid renewal: `grace` — it keeps working until `freezes_on` (3 days after the renewal fell due); `frozen` — it is paused. `amount_owed` is the total of the unpaid renewal `orders` (tax included); paying all of them is paying in full, and a paused add-on then comes back automatically within minutes.","oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ExtraPurchaseArrears"}]},"sla_due_at":{"type":["string","null"],"format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"failure_reason":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ExtraPurchaseArrears":{"type":"object","required":["state","freezes_on","frozen_at","amount_owed","orders"],"properties":{"state":{"type":"string","enum":["grace","frozen"]},"freezes_on":{"type":"string","format":"date"},"frozen_at":{"type":["string","null"],"format":"date-time"},"amount_owed":{"$ref":"#/components/schemas/MoneyAmount"},"orders":{"type":"array","items":{"type":"object","required":["order_id","human_ref","due_on","total"],"properties":{"order_id":{"type":"string","format":"uuid"},"human_ref":{"type":"string"},"due_on":{"type":"string","format":"date"},"total":{"$ref":"#/components/schemas/MoneyAmount"}}}}}},"ExtraPurchaseCreate":{"type":"object","description":"Optional body for purchasing an extra — the price + fulfilment path are server-decided.","properties":{"org_id":{"$ref":"#/components/schemas/Uuid"},"term":{"type":"string","enum":["","monthly","annual"],"description":"`annual` pays an **SEO tool** twelve months at a time at V1's yearly saving (16.67%, D19) and renews yearly. Blank or `monthly` buys the row's own interval. A `422` on any row with no yearly term — never silently bought monthly."},"site_id":{"type":["string","null"],"format":"uuid"},"domain_id":{"type":["string","null"],"format":"uuid","description":"The domain a **domain-scoped** extra is bought for. Premium DNS (`premium_dns`) is the first: it is applied at the registrar, per zone, on a name held in our registrar account.\n\nNot interchangeable with `site_id`. Most domains on this estate are connected to no site at all, so scoping a per-domain product through a site would make it unbuyable for nearly all of them — and would force the UI to say \"connect a site first\", which is a false explanation, since the product has nothing to do with any site. A domain the caller cannot see is a `404`, exactly as a site is: that is the tenancy check, and the product line it decides eligibility against is read from the domain rather than defaulting to line-agnostic."},"currency":{"description":"The currency the customer was quoted in on the catalogue screen. Omit it and the engine uses the `X-Zinn-Currency` header. `Extra` rows are stored in the base currency only, so the charge converts per request off the cached FX rates and **captures the converted amount immutably** on the purchase — which is why this must match what `listExtras` returned: showing one number and charging another is a different price, not a display bug. A currency we do not offer, or one no gateway can charge, is a `422` rather than a silent substitution.","anyOf":[{"$ref":"#/components/schemas/CurrencyCode"},{"type":"null"}]},"gateway":{"type":["string","null"],"description":"The payment rail the customer picked, from `getPaymentOptions`. Omit it (or send `null`) for \"no preference\", which follows the payment method the organization would be charged on anyway — that is the unchanged behaviour every script and every unattended sweep relies on.\n\n⛔ Its absence is why a first-time buyer used to see **\"Failed — no_payment_method\"**: with no rail the charge follows the organization's default, which is the card gateway even for an organization that holds no card, so nothing could ever settle. A rail this purchase cannot be settled on is a `422` naming the ones that can — validated against the same list the picker is built from, so a screen can never offer a method the charge then refuses.","example":"paypal"},"pay_with":{"type":"string","enum":["card","credit"],"default":"card","description":"Where the money comes from. Owner ruling 2026-08-24: *\"Credit pays, or card — customer picks\"*.\n\nOnly the AI products (`ai_webmaster`, `ai_update_guard` and any other row in those categories) accept `credit`; anything else is a `422`. That restriction is not a feature flag — the AI credit purse is a **single-purpose voucher taxed at issue** (docs/34 §2.6), and its tax character is bought by exactly this limit on what it may buy.\n\nA credit-funded purchase mints **no order, no invoice and no tax line**: the VAT was accounted for when the pack was bought, so redeeming it is not a second supply. The default is `card`, so a client that has never heard of this field keeps the behaviour it has always had."}}},"ExtraPurchasePage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ExtraPurchase"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"ExtraPurchaseStatus":{"type":"string","description":"An extra purchase's lifecycle state. `awaiting_payment` (Q225): placed by a one-click buy with nothing on file to charge, waiting for the customer to pay its order on-session — never charged, never a failure, and not a product the customer holds until it moves to `fulfilling`. `superseded` (Q321): an SEO tool tier replaced by an upgrade of the same tool — paid for the periods it covered, its renewal stopped, and it no longer grants anything.","enum":["pending","awaiting_payment","fulfilling","awaiting_staff","completed","failed","refunded","superseded"]},"ExtraSeoPrice":{"type":"object","required":["list_minor","amount_minor","annual_discount_minor","bundle_discount_minor","without_bundle_minor"],"properties":{"list_minor":{"type":"integer","format":"int64","description":"One term at the monthly price (twelve of them for `yearly`), before any saving."},"amount_minor":{"type":"integer","format":"int64","description":"What this purchase would be charged now, with every saving that applies."},"annual_discount_minor":{"type":"integer","format":"int64"},"bundle_discount_minor":{"type":"integer","format":"int64"},"without_bundle_minor":{"type":"integer","format":"int64","description":"The price with the yearly saving only — what a customer below three tools pays."}}},"ExtraSeoTerms":{"type":"object","description":"⚖️ D19 (2026-09-25): V1's SEO pricing rules. Three or more SEO tools held (V2-only SEO SKUs count) take **20%** off every one of them; paying twelve months at once takes **16.67%** off the remainder, half-up to the minor unit. The bundle is a holding: it is added at the third tool and removed from renewals when a cancellation takes the organisation below three. Figures are in `currency`, converted live from USD.","required":["tool","currency","yearly_offered","monthly","yearly","tools_held","bundle_applies","bundle_min_tools","bundle_bps","annual_bps"],"properties":{"tool":{"type":"string","description":"The SEO tool this row belongs to; a pack shares its tool's key.","example":"rank"},"currency":{"$ref":"#/components/schemas/CurrencyCode"},"yearly_offered":{"type":"boolean"},"monthly":{"$ref":"#/components/schemas/ExtraSeoPrice"},"yearly":{"anyOf":[{"$ref":"#/components/schemas/ExtraSeoPrice"},{"type":"null"}]},"tools_held":{"type":"integer","description":"How many distinct SEO tools the organisation pays for today."},"bundle_applies":{"type":"boolean","description":"Whether buying this row now takes the organisation to three or more tools."},"bundle_min_tools":{"type":"integer","example":3},"bundle_bps":{"type":"integer","description":"The bundle saving in basis points.","example":2000},"annual_bps":{"type":"integer","description":"The yearly saving in basis points.","example":1667}}},"ExtraTierChange":{"type":"object","description":"Q321 — another tier of an SEO tool the organisation holds (`docs/26` §18).","required":["kind","from_code","from_name","currency","charge_now_minor","waived_minor","renewal_minor","current_renewal_minor","renews_on","interval","days_left","days_total","scheduled","scheduled_code"],"properties":{"kind":{"type":"string","enum":["upgrade","downgrade"],"description":"`upgrade` is bought now (prorated); `downgrade` is chosen for the renewal and charged nothing now."},"from_code":{"type":"string"},"from_name":{"type":"string"},"currency":{"type":"string"},"charge_now_minor":{"type":"integer","description":"Charged now — always 0 for a downgrade."},"waived_minor":{"type":"integer"},"renewal_minor":{"type":"integer","description":"What this tier renews at, per period, net of SEO savings."},"current_renewal_minor":{"type":"integer"},"renews_on":{"type":"string","format":"date"},"interval":{"type":"string"},"days_left":{"type":"integer"},"days_total":{"type":"integer"},"scheduled":{"type":"boolean","description":"This tier is already chosen for the renewal."},"scheduled_code":{"type":["string","null"],"description":"The tier the held one is set to renew as, if any."}}},"ExtraTierChangeEnvelope":{"type":"object","required":["tier_change"],"properties":{"tier_change":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ExtraTierChange"}]}}},"FeatureFlagsResponse":{"type":"object","description":"⛔ `available: false` is NOT `flags: {}`. An empty map and \"every flag is off\" are the same value, and every consumer reads a missing key as off.","required":["available","reason","flags"],"properties":{"available":{"type":"boolean"},"reason":{"type":"string","enum":["","unconfigured","unreachable","refused","not_found","malformed"]},"flags":{"type":"object","description":"`true` for a boolean flag; the variant name for an experiment.","additionalProperties":{"oneOf":[{"type":"boolean"},{"type":"string"}]}}}},"FirstRunItem":{"type":"object","required":["key","source","ref","kind","done","next_path","ai_path","kb_slug","product_line","plan_code","plan_name","used","allowed","days_left"],"properties":{"key":{"type":"string","description":"The product: a product-line code, an add-on category or a sign-up key."},"source":{"type":"string","enum":["trial","subscription","addon","signup"]},"ref":{"type":"string","description":"The trial, subscription or add-on purchase id (the sign-up key for `signup`)."},"kind":{"type":"string","enum":["site","feature","site_addon","service","ready"],"description":"`site` — done when a site exists on the line; `feature` — when the product's first object exists (a board, monitor, tracked domain…); `site_addon` — when the purchase is attached to a site; `service` — when the staff-fulfilled request is with us; `ready` — nothing to set up."},"done":{"type":"boolean"},"next_path":{"type":"string","description":"The dashboard path of the one next step, plan and line preselected."},"ai_path":{"type":"string","nullable":true,"description":"The \"Build it with AI\" alternative, when there is one."},"kb_slug":{"type":"string","description":"The KB guide for this product (`/help?article=<slug>`)."},"product_line":{"type":"string","description":"The product-line code, empty for add-ons and sign-up products."},"plan_code":{"type":"string"},"plan_name":{"type":"string"},"app":{"type":"string","description":"s1014 APPTRIAL — the app picked at trial start (`node`, `python`, `php`, `joomla`…), empty when none was."},"used":{"type":"integer","nullable":true,"description":"Sites used on the line (`site` kind only)."},"allowed":{"type":"integer","nullable":true,"description":"The line's site allowance; null when unlimited or not a site product."},"days_left":{"type":"integer","nullable":true,"description":"Days left on a free trial; null otherwise."}}},"FirstRunList":{"type":"object","required":["data","all_done","reminders"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FirstRunItem"}},"all_done":{"type":"boolean","description":"Every held product has reached its first success moment."},"reminders":{"type":"boolean","description":"Whether the Overview home card and the trial reminder banner may show (BRIEF 28 switch)."}}},"FleetApplication":{"type":"object","description":"One application the platform installs on its own fleet (docs/139). Distinct from `SiteApplication`, which is a **vendor** catalogue entry read live from the resold platform: this one is ours, so it carries our own copy rather than third-party marketing prose, and it names the stack it answers.","required":["key","name","stack_type","summary","admin_path","needs_database","needs_licence","php_versions","runtime","category"],"additionalProperties":false,"properties":{"category":{"$ref":"#/components/schemas/FleetApplicationCategory"},"needs_licence":{"type":"boolean","description":"Whether the application's installer needs the customer's own licence key (WHMCS). When `true`, creating a site with it requires `application_licence_key`."},"licence_offer":{"type":["object","null"],"additionalProperties":false,"required":["tier","price_monthly_minor","currency"],"description":"The licence we sell with this application (create the site with `application_licence_source: zinn`), or `null` when it takes no licence or we are not selling one to the acting organisation just now (the sale has a launch switch; until it is on, only its pilot organisations are offered it). The price is per month, net of tax, in integer minor units.","properties":{"tier":{"type":"string","maxLength":80,"example":"WHMCS Starter"},"price_monthly_minor":{"type":"integer","minimum":0,"example":1595},"currency":{"type":"string","minLength":3,"maxLength":3,"example":"USD"}}},"php_versions":{"type":"array","maxItems":16,"items":{"type":"string","maxLength":8,"example":"8.4"},"description":"The PHP versions the application's vendor supports, oldest first. Empty means any version the product line offers. A site created with no `php_version` gets the last (newest) entry; any other version is refused with a 422 on `php_version`."},"key":{"type":"string","maxLength":64,"description":"The identifier sent back when creating a site, e.g. `strapi`.","example":"strapi"},"name":{"type":"string","maxLength":128,"description":"The project's own name, as a proper noun. Not translated.","example":"Strapi"},"stack_type":{"$ref":"#/components/schemas/StackType"},"runtime":{"$ref":"#/components/schemas/Runtime"},"summary":{"type":"string","maxLength":512,"description":"One sentence of **our** copy describing what it is for. Localised through the frontend catalogue; this is the English reference."},"vendor_url":{"type":"string","maxLength":512,"description":"The project's own site. Rendered as a link, never followed by us."},"admin_path":{"type":"string","maxLength":128,"description":"Where the customer signs in, relative to the site root.","example":"/admin"},"needs_database":{"type":"boolean","description":"Whether the install uses the account's MariaDB database. `false` for Payload, which has no MySQL adapter upstream and is wired to SQLite inside the account."},"product_lines":{"type":"array","maxItems":64,"items":{"type":"string","maxLength":64},"description":"Only on `listCatalogApplications`: the active product lines whose application policy offers this application — the public site's one source for \"which plans can install it\" (D32723). A line with no policy row offers nothing (fails closed)."}}},"FleetApplicationCategory":{"type":"string","description":"What kind of software an application is (s1006 Q305): the buy screen groups the catalogue by it and offers each goal (\"a website\", \"an online shop\", \"a ready-made app\", \"my own code\", \"online courses\") every application of the categories that goal serves. A closed set — `other` is the engine's answer for an application it has not classified, and a client must still offer it (as a ready-made app).","enum":["cms","headless_cms","shop","community","wiki","gallery","learning","business","marketing","analytics","files","framework","other"]},"FootprintFinding":{"type":"object","required":["code","severity","owner","domains","count","fix_action","params"],"properties":{"code":{"type":"string","description":"An opaque finding identifier the dashboard renders."},"severity":{"type":"string","enum":["critical","high","medium","low","info","good"]},"owner":{"type":"string","enum":["customer","platform"]},"domains":{"type":"array","items":{"type":"string"},"description":"The organisation's own sites this finding covers."},"count":{"type":"integer"},"fix_action":{"type":"string","description":"A suggested next step the dashboard can link; may be empty."},"params":{"type":"object","additionalProperties":{"type":"integer"}}}},"FootprintOverview":{"type":"object","required":["enabled","cadence_days","external_allowance","external_used","checks_allowance","checks_used","hosted_count","checkable_sites","sites","trend","managed_footprints"],"properties":{"enabled":{"type":"boolean"},"managed_footprints":{"type":"object","description":"The footprints the Footprint-Free line manages automatically: `sold` is the `managed_footprints` entitlement the account's plans grant (0 when none does), `measured` is how many the platform's code measurably manages, by `groups` (`wordpress` stripped by Zinn® Footprint, `crawler` SEO crawler families shut out, `edge` per-site placements, `watched` cross-site signals the checker reads).","required":["sold","measured","groups"],"properties":{"sold":{"type":"integer"},"measured":{"type":"integer"},"groups":{"type":"object","additionalProperties":{"type":"integer"}}}},"cadence_days":{"type":"integer","description":"How often every site is checked automatically; 0 when off."},"external_allowance":{"type":"integer","description":"Sites hosted elsewhere allowed; -1 is unlimited."},"external_used":{"type":"integer"},"external_remaining":{"type":"integer","nullable":true},"checks_allowance":{"type":"integer","description":"On-demand checks a month; -1 is unlimited."},"checks_used":{"type":"integer"},"checks_remaining":{"type":"integer","nullable":true},"hosted_count":{"type":"integer","description":"Sites hosted with us — always included."},"checkable_sites":{"type":"array","description":"Every site a check started now would cover — hosted with us or added as hosted elsewhere — in name order. The sites a `site` or `custom` check may name. Empty while the checker is not on the account.","items":{"type":"object","required":["domain","hosted"],"properties":{"domain":{"type":"string"},"hosted":{"type":"boolean","description":"Hosted with us (`false` = added as hosted elsewhere)."}}}},"next_run_at":{"type":"string","format":"date-time","nullable":true},"sites":{"type":"array","items":{"$ref":"#/components/schemas/FootprintSite"}},"latest":{"allOf":[{"$ref":"#/components/schemas/FootprintRunSummary"}],"nullable":true},"running":{"allOf":[{"$ref":"#/components/schemas/FootprintRunSummary"}],"nullable":true},"trend":{"type":"array","items":{"type":"object","required":["at","score"],"properties":{"at":{"type":"string","format":"date-time"},"score":{"type":"integer"}}}}}},"FootprintPair":{"type":"object","required":["a","b","weight","codes"],"properties":{"a":{"type":"string"},"b":{"type":"string"},"weight":{"type":"integer"},"codes":{"type":"array","items":{"type":"string"}}}},"FootprintRunCreate":{"type":"object","properties":{"scope":{"type":"string","enum":["account","group","site","custom"],"default":"account"},"group_id":{"type":"string","format":"uuid","nullable":true,"description":"Required when `scope` is `group`."},"domains":{"type":"array","items":{"type":"string","maxLength":300},"description":"The organisation's own sites to check — hosted with us or added as hosted elsewhere. Exactly one for `scope: site`; two or more for `scope: custom`, which compares the chosen sites with each other. Ignored for the other scopes. There is no upper limit."}}},"FootprintRunDetail":{"type":"object","required":["run","findings","pairs","sites"],"properties":{"run":{"$ref":"#/components/schemas/FootprintRunSummary"},"findings":{"type":"array","items":{"$ref":"#/components/schemas/FootprintFinding"}},"pairs":{"type":"object","required":["total","pairs","account_wide"],"properties":{"total":{"type":"integer","description":"Every linked pair","not only those listed.":null},"pairs":{"type":"array","items":{"$ref":"#/components/schemas/FootprintPair"}},"account_wide":{"type":"array","description":"Findings so wide every pair of sites shares them.","items":{"type":"object","required":["code","severity","count"],"properties":{"code":{"type":"string"},"severity":{"type":"string"},"count":{"type":"integer"}}}}}},"sites":{"type":"array","items":{"type":"object","required":["domain","hosted","measured","reachable","https"],"properties":{"domain":{"type":"string"},"hosted":{"type":"boolean"},"measured":{"type":"boolean"},"reachable":{"type":"boolean"},"https":{"type":"boolean"}}}}}},"FootprintRunList":{"type":"object","required":["results"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/FootprintRunSummary"}}}},"FootprintRunStarted":{"type":"object","required":["run","already_running"],"properties":{"run":{"$ref":"#/components/schemas/FootprintRunSummary"},"already_running":{"type":"boolean"}}},"FootprintRunSummary":{"type":"object","required":["id","state","source","scope","sites_count","hosted_count","reachable_count","risk_count","started_at"],"properties":{"id":{"type":"string","format":"uuid"},"state":{"type":"string","enum":["running","done","failed"]},"source":{"type":"string","enum":["auto","manual"]},"scope":{"type":"string","enum":["account","group","site","custom"]},"group_id":{"type":"string","format":"uuid","nullable":true},"score":{"type":"integer","nullable":true,"minimum":0,"maximum":100,"description":"100 means nothing publicly ties the sites together. `null` until done."},"grade":{"type":"string","description":"A to E; empty until done."},"prev_score":{"type":"integer","nullable":true},"sites_count":{"type":"integer"},"hosted_count":{"type":"integer"},"reachable_count":{"type":"integer"},"risk_count":{"type":"integer","description":"Findings that tie sites together and are yours to act on."},"started_at":{"type":"string","format":"date-time"},"finished_at":{"type":"string","format":"date-time","nullable":true}}},"FootprintSite":{"type":"object","required":["id","domain","label","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"domain":{"type":"string","description":"The bare host."},"label":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"FootprintSiteCreate":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","maxLength":300,"description":"A domain or URL; normalised to its bare host."},"label":{"type":"string","maxLength":120}}},"FootprintSiteHistory":{"type":"object","required":["domain","results"],"properties":{"domain":{"type":"string"},"results":{"type":"array","description":"The finished checks that covered this site, newest first (up to 30).","items":{"type":"object","required":["run_id","scope","source","sites_count","hosted","reachable","https","findings"],"properties":{"run_id":{"type":"string","format":"uuid"},"scope":{"type":"string","enum":["account","group","site","custom"]},"source":{"type":"string","enum":["auto","manual"]},"score":{"type":"integer","nullable":true,"description":"The whole check's score."},"grade":{"type":"string"},"sites_count":{"type":"integer"},"finished_at":{"type":"string","format":"date-time","nullable":true},"hosted":{"type":"boolean"},"reachable":{"type":"boolean"},"https":{"type":"boolean"},"findings":{"type":"array","description":"The check's findings that named this site.","items":{"type":"object","required":["code","severity","owner","count","fix_action"],"properties":{"code":{"type":"string","description":"An opaque finding identifier the dashboard renders."},"severity":{"type":"string","enum":["critical","high","medium","low","info","good"]},"owner":{"type":"string","enum":["customer","platform"]},"count":{"type":"integer","description":"How many sites the finding covered."},"fix_action":{"type":"string"}}}}}}}}},"FootprintSiteLinks":{"type":"object","required":["domain","links"],"properties":{"domain":{"type":"string"},"links":{"type":"array","items":{"type":"object","required":["domain","severity","weight","codes"],"properties":{"domain":{"type":"string"},"severity":{"type":"string"},"weight":{"type":"integer"},"codes":{"type":"array","items":{"type":"string"}}}}}}},"FxRate":{"type":"object","description":"One currency's current exchange rate vs the USD base (docs/29 §1). Platform reference data — the rate the stored per-currency prices were derived from.","required":["currency","base","rate_vs_usd","fetched_at","decimals","rounding"],"properties":{"currency":{"$ref":"#/components/schemas/CurrencyCode"},"base":{"allOf":[{"$ref":"#/components/schemas/CurrencyCode"}],"description":"The base the rate is expressed against — USD (docs/29 §1)."},"rate_vs_usd":{"type":"string","description":"How many units of `currency` one unit of `base` buys — a **string** decimal, never a JSON float, so no floating-point value represents the rate (§2.8).","example":"0.9200000000"},"provider":{"type":"string","description":"The FX feed that produced this rate (e.g. `exchangerate_api`, `frankfurter`).","example":"exchangerate_api"},"fetched_at":{"type":"string","format":"date-time","description":"When the feed produced this rate — the \"as of\" a price locks against."},"decimals":{"type":"integer","minimum":0,"maximum":4,"description":"ISO-4217 minor-unit digits for `currency` — 2 for USD/EUR, 0 for JPY/KRW/VND. From the currency registry, **not** the feed. Drives integer minor-unit maths (§2.8) on both sides: a client that hardcodes `/100` over-states a JPY price 100×. (ISO also defines 3-digit currencies — BHD/KWD/OMR/… — and two 4-digit index units, hence the range; none are enabled for sale today.)","example":2},"rounding":{"type":"string","enum":["charm_99","nearest_1","nearest_10","nearest_100","nearest_1000","exact"],"description":"The charm-rounding rule to apply to a converted price so it stays stable and \"nice\" (docs/29 §2). Mirrors `engine.registries.currency.RoundingRule` exactly — one spelling, both sides (docs/45 §3.1).\n\nThis is the rule the engine applies when converting a USD base price **into** `currency`, which is not always the same as that currency's catalogue charm-rounding style: for the base currency itself the engine applies none, so USD publishes `exact` here while its registry entry stays `charm_99` for domain/TLD sell pricing. See docs/45 §3.1-a.\n\n**The exact algorithm, because a client that guesses it will disagree with the engine on real prices.** Given a USD base amount in minor units `usd_minor`, compute `major = (usd_minor / 100) * rate_vs_usd` as an exact decimal (never a float, §2.8), then:\n\n1. **If `major <= 0`, the result is 0** — for *every* rule, including `charm_99`. A free or fully-discounted line stays free. Skipping this clamp is the single most likely divergence: naive charm-rounding turns `0.00` into `0.99`, printing a charge on a free item.\n2. `exact` — use `major` unchanged.\n3. `charm_99` — round `major` half-up to a whole number; **if that is less than 1, use 1**; then subtract `0.01`. (So a positive amount never charm-rounds below `0.99`.)\n4. `nearest_N` (`N` = 1, 10, 100, 1000) — round `major / N` half-up to a whole number and multiply back by `N`; **if the result is less than `N`, use `N`**. (So a positive amount never rounds down to zero.)\n5. Finally multiply by `10 ** decimals` and round half-up to an integer — that is the price in `currency`'s minor units.\n\nBoth clamps in 3 and 4 exist so a tiny converted amount can never round down to nothing and be given away. Round **half-up** throughout, not banker's rounding.","example":"charm_99"}}},"FxRateList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FxRate"}}}},"GatewayProbe":{"type":"object","required":["healthy","detail"],"description":"The verdict of a real authenticated call to the provider. Returned with 200 even when `healthy` is false under `validate_only`: whether a credential is good is the answer being asked for, not a failed request.","properties":{"healthy":{"type":"boolean"},"detail":{"type":"string"}}},"GeneratePostImages":{"type":"object","description":"The image policy for one generation run — the same shape a recipe carries.","properties":{"featured":{"type":"boolean","default":true},"inline_count":{"type":"integer","minimum":0,"maximum":4,"default":1,"description":"⛔ Bounded at 4. A hundred near-identical stock-looking images across a network **is a footprint**, which is the one thing the Footprint-Free line exists to avoid."},"style":{"type":"string","maxLength":200,"description":"Woven into every prompt — \"photographic, no text overlay, muted palette\"."},"provider":{"description":"Leave empty to let the platform choose.","oneOf":[{"$ref":"#/components/schemas/AiImageProvider"},{"type":"string","enum":[""]}]},"model":{"type":"string","maxLength":120,"description":"A specific `model_id` to pin, or empty to follow the provider's default."},"target_locale":{"type":"string","maxLength":12,"description":"The language the post will be published in, so alt text is localised to the **site** rather than to the dashboard's UI locale."},"org_id":{"$ref":"#/components/schemas/Uuid"}}},"GenerateStandaloneImages":{"type":"object","description":"One standalone generation request — the customer's own words.","required":["prompt"],"properties":{"prompt":{"type":"string","maxLength":1000,"description":"Used **as written**, not rewritten into a template. The only thing added is an instruction to draw no lettering, because all three providers render garbled text when asked for words."},"shape":{"type":"string","enum":["wide","standard","square"],"default":"wide","description":"⛔ A word, not a pixel pair, and that is a portability property rather than a simplification: Google takes an aspect ratio and a size *bucket* and cannot be given `1536x864`; OpenAI takes pixels and has no notion of `16:9`. A request in one provider's vocabulary is one the other two must guess at, and guessing is how a customer asks for a wide image and quietly gets a square one."},"count":{"type":"integer","minimum":1,"maximum":4,"default":1,"description":"⛔ Bounded at 4 so one press cannot spend an unbounded amount of a customer's credit. Four is already more variations than anybody picks between."},"style":{"type":"string","maxLength":200,"description":"Appended to the prompt — \"photographic, muted palette\"."},"provider":{"description":"Leave empty to let the platform choose.","oneOf":[{"$ref":"#/components/schemas/AiImageProvider"},{"type":"string","enum":[""]}]},"model":{"type":"string","maxLength":120,"description":"A specific `model_id` to pin, or empty to follow the provider's default."},"org_id":{"$ref":"#/components/schemas/Uuid"}}},"GeneratedImage":{"type":"object","description":"One image generated for a content post.","required":["id","purpose","provider","model_id","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"post_id":{"$ref":"#/components/schemas/Uuid"},"purpose":{"type":"string","enum":["featured","inline","standalone"],"description":"`standalone` is an image the customer asked for directly, from their own prompt, with no post anywhere near it. ⛔ It is not a third kind of post image: its bytes live under a different storage prefix with a longer life (90 days, against 14 for a post image staged on its way to WordPress), and it is reached through `/v1/ai/images/library` rather than through a post."},"provider":{"$ref":"#/components/schemas/AiImageProvider"},"model_id":{"type":"string"},"prompt":{"type":"string"},"revised_prompt":{"type":"string","description":"What the provider says it actually drew from, when it tells us. Kept because all three may rewrite a prompt and xAI always does — a customer looking at an image that does not match their words needs to see what was really asked."},"alt_text":{"type":"string","description":"The alt text in the language it was authored in. Localised to the destination site's language at publish time (§2.19), not here."},"alt_locale":{"type":"string","maxLength":12},"filename":{"type":"string","description":"The filename the site stores it under. Derived from the post title, not the image id: WordPress uses it as the media slug and it appears in the public image URL."},"content_type":{"type":"string"},"byte_size":{"type":"integer"},"width":{"type":["integer","null"],"description":"The pixel width **as returned**, read from the image's own header — not what was requested. ⛔ A `200` is a claim that the request was accepted, never that a parameter was honoured: a provider that silently ignores the aspect ratio returns a perfectly good image of the wrong shape, and this is what makes that visible.\n\n⛔ `null` means we could not measure the container — NOT that the image is empty. A `0` would read as a measurement, which is the reassuring half of an ambiguity."},"height":{"type":["integer","null"],"description":"The pixel height as returned. See `width`."},"published_at":{"type":["string","null"],"format":"date-time","description":"When it reached the site. `null` while it is only staged with us."},"remote_media_id":{"type":"string","description":"The media id the site gave it. ⭐ What makes a retry safe — a second attempt can see the image is already there instead of uploading a duplicate into the customer's media library."},"created_at":{"type":"string","format":"date-time"}}},"GeneratedImageList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GeneratedImage"}}}},"GeneratedImageResult":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GeneratedImage"}},"unmet":{"type":"array","description":"What the chosen provider could not honour, in words for the customer. ⛔ Present and empty rather than absent when everything was honoured, so a client can tell \"nothing was dropped\" from \"this response predates the field\".","items":{"type":"string"}},"body_html":{"type":"string","description":"The post body with the generated images' placeholders written into it."}}},"GeoRestrictionLayer":{"type":"object","description":"What ONE enforcement layer can do, and what it is doing right now. Four fields rather than one flag because \"this provider cannot do it\" and \"it failed this morning\" need different actions from the customer and would otherwise render identically.","required":["present","supported","enforcing","detail","detail_key"],"properties":{"present":{"type":"boolean","description":"Whether this layer exists for this site. A site with no CDN has no edge.","example":true},"supported":{"type":"boolean","description":"Whether this layer can express the requested direction.","example":true},"enforcing":{"type":"boolean","description":"Whether the rule is live here **now**, read from the provider rather than from our record. `false` with a `detail` means this layer is not protecting the site.","example":true},"detail":{"type":"string","description":"Why it is not, in the customer's terms. Empty when there is nothing to say.","example":""},"detail_key":{"type":"string","description":"The message key for `detail` (`geo.detail.*`) so a client shows the sentence in the reader's language; empty when `detail` is empty or has no key (show `detail` then).","example":""}}},"GitHubAuthKind":{"type":"string","enum":["app","pat"],"description":"`app` is the Zinn® GitHub App installation — per-repository scope the customer chooses on GitHub's own screen, revocable by them in one click, belonging to their organisation rather than to whichever person minted a token. `pat` is a fine-grained personal access token, kept only because a customer whose organisation forbids app installs otherwise has no way in at all."},"GitHubNoticeDelivery":{"type":"string","description":"Where a connection's overdue / gone-quiet / over-WIP notices are allowed to go. Both values raise the same notices and both render them on the board — the difference is delivery, never detection. `in_app` is the default: connecting a project must not mail anybody, because a busy project linked on a Monday can be a fortnight behind on twenty items, and twenty e-mails on the strength of *\"I linked a board\"* is how a customer turns notifications off altogether.","enum":["in_app","routed"],"x-enum-descriptions":{"in_app":"On the board only. Nothing leaves the platform.","routed":"Also delivered wherever this organisation already gets alerts."}},"GitHubProjectConflict":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"item_id":{"type":"string","format":"uuid"},"item_title":{"type":"string","description":"The item's title. Returned beside `item_id` because this row is rendered to a customer asking what happened to their change, and an id answers nothing."},"field_name":{"type":"string"},"winner":{"type":"string","enum":["github","zinn"]},"kept":{"type":"string"},"discarded":{"type":"string"},"github_updated_at":{"type":"string","format":"date-time","nullable":true},"local_updated_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"GitHubProjectConflictPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GitHubProjectConflict"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"GitHubProjectConnect":{"type":"object","required":["project_node_id","project_number","owner_login"],"properties":{"project_node_id":{"type":"string","maxLength":64},"project_number":{"type":"integer","minimum":1},"owner_login":{"type":"string","maxLength":255},"owner_type":{"type":"string","enum":["organization","user"]},"auth_kind":{"$ref":"#/components/schemas/GitHubAuthKind"},"installation_id":{"type":"string","maxLength":32},"token":{"type":"string","writeOnly":true},"board_id":{"type":"string","format":"uuid","nullable":true,"description":"Optional. A project may be connected purely for the roll-up and never attached to client work."},"title":{"type":"string","maxLength":300},"org_id":{"type":"string","format":"uuid"}}},"GitHubProjectDiscovery":{"type":"object","required":["owner_login"],"properties":{"owner_login":{"type":"string","maxLength":255},"auth_kind":{"$ref":"#/components/schemas/GitHubAuthKind"},"installation_id":{"type":"string","maxLength":32},"token":{"type":"string","writeOnly":true,"description":"A fine-grained token, for `auth_kind: pat`. Write-only and never echoed — a response carrying it would put a live GitHub credential in the browser's network tab and in any log that captures a response body."},"org_id":{"type":"string","format":"uuid"}}},"GitHubProjectDiscoveryResult":{"type":"object","properties":{"owner_login":{"type":"string"},"count":{"type":"integer","description":"Returned beside the list on purpose. An owner with genuinely no projects and a credential that cannot see any would otherwise be the same empty array."},"projects":{"type":"array","items":{"$ref":"#/components/schemas/GitHubProjectSummary"}}}},"GitHubProjectField":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"field_node_id":{"type":"string"},"name":{"type":"string"},"data_type":{"$ref":"#/components/schemas/GitHubProjectFieldType"},"position":{"type":"integer"},"options":{"type":"array","description":"The select's options, or the iteration's sprints. Completed iterations are kept and marked rather than dropped — a sprint board whose finished sprints vanish cannot show a burn-down or a roadmap.","items":{"type":"object","additionalProperties":true}},"wip_limits":{"type":"object","additionalProperties":{"type":"integer"},"description":"Advisory cap per single-select option, keyed by option id. Ours, not GitHub's."},"writable":{"type":"boolean","description":"Computed server-side from the type, so the UI never keeps its own copy of which types GitHub will accept. Two lists would drift, and the drift shows up as an editable control whose save silently does nothing."}}},"GitHubProjectFieldType":{"type":"string","description":"Every field type Projects v2 exposes, spelled as GitHub spells it. The full set, not the four that are easy: a board that rendered TEXT/NUMBER/DATE/SELECT and silently dropped ITERATION would show an agency a sprint board with no sprint on it, and the omission is invisible because the column simply is not there to be missed.","enum":["TITLE","TEXT","NUMBER","DATE","SINGLE_SELECT","ITERATION","ASSIGNEES","LABELS","MILESTONE","REPOSITORY","REVIEWERS","LINKED_PULL_REQUESTS","PARENT_ISSUE","SUB_ISSUES_PROGRESS","CREATED","UPDATED","CLOSED"]},"GitHubProjectFieldValue":{"type":"object","required":["field_node_id"],"properties":{"field_node_id":{"type":"string","maxLength":64},"value":{"nullable":true,"description":"`null` CLEARS the field, through a different GitHub mutation. An empty string would set the field to the empty string."}}},"GitHubProjectItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"item_node_id":{"type":"string"},"item_type":{"type":"string","enum":["ISSUE","PULL_REQUEST","DRAFT_ISSUE","REDACTED"]},"content_number":{"type":"integer","nullable":true},"repository":{"type":"string"},"title":{"type":"string"},"body":{"type":"string"},"url":{"type":"string"},"state":{"type":"string"},"is_archived":{"type":"boolean"},"field_values":{"type":"object","additionalProperties":true,"description":"Keyed by the field's **node id**, never its name. A project owner renaming a field would otherwise orphan every stored value at once, and the next sync would read it as \"every item cleared that field\"."},"github_updated_at":{"type":"string","format":"date-time","nullable":true},"local_updated_at":{"type":"string","format":"date-time","nullable":true,"description":"When WE last changed this item. Set only by a local edit, never by a sync — a sync that stamped it would make every imported item look locally-edited and hand every subsequent conflict to our side."},"card_id":{"type":"string","format":"uuid","nullable":true}}},"GitHubProjectItemArchive":{"type":"object","required":["archived"],"properties":{"archived":{"type":"boolean","description":"Required, with no default. A default would make a request that lost its body mean *archive*, so a restore would silently do the opposite of what was asked."}}},"GitHubProjectItemCardLink":{"type":"object","properties":{"card_id":{"type":"string","format":"uuid","nullable":true}}},"GitHubProjectItemCreate":{"type":"object","required":["title"],"properties":{"title":{"type":"string","maxLength":300},"body":{"type":"string"},"field_values":{"type":"object","additionalProperties":true,"description":"Keyed by field node id."}}},"GitHubProjectItemPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GitHubProjectItem"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"GitHubProjectLink":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"board_id":{"type":"string","format":"uuid","nullable":true},"auth_kind":{"$ref":"#/components/schemas/GitHubAuthKind"},"installation_id":{"type":"string","description":"Public — it appears in the customer's own install URL — and showing it is what lets them confirm on GitHub that they are looking at the right installation."},"has_stored_token":{"type":"boolean","description":"Whether a token is held in Vault for this connection. The token itself is never returned."},"project_node_id":{"type":"string"},"project_number":{"type":"integer"},"owner_login":{"type":"string"},"owner_type":{"type":"string"},"title":{"type":"string"},"short_description":{"type":"string"},"closed":{"type":"boolean"},"public":{"type":"boolean"},"direction":{"$ref":"#/components/schemas/GitHubSyncDirection"},"notice_delivery":{"$ref":"#/components/schemas/GitHubNoticeDelivery"},"views":{"type":"array","description":"The project's saved views on GitHub, replaced whole on every read so a view deleted there disappears here rather than lingering as a link GitHub answers with a 404. Rendered as links built from the project number and the view number, which is the shape GitHub's own browsable URLs use.","items":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"integer","nullable":true},"name":{"type":"string"},"layout":{"type":"string"}}}},"url":{"type":"string"},"webhook_state":{"$ref":"#/components/schemas/GitHubWebhookState"},"last_synced_at":{"type":"string","format":"date-time","nullable":true,"description":"When a sync last SUCCEEDED. What the staleness alarm fires off."},"last_attempted_at":{"type":"string","format":"date-time","nullable":true,"description":"When a sync was last ATTEMPTED, stamped for every connection the sweep reaches before the result is read. Two columns rather than one: a cursor only a successful pass advanced would re-select a failing connection first on every fire for ever, and advancing the success column instead would silence the alarm."},"last_error":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/GitHubProjectField"},"description":"The project's fields, with their single-select options and any work-in-progress limits set on them. Returned with the connection rather than fetched separately, because a board cannot lay out a single column without them and a second round trip before the first paint is a second chance to render an empty board."}}},"GitHubProjectLinkDetail":{"allOf":[{"$ref":"#/components/schemas/GitHubProjectLink"},{"type":"object","properties":{"wip":{"type":"array","items":{"$ref":"#/components/schemas/GitHubProjectStatusCount"}},"notices":{"type":"array","items":{"$ref":"#/components/schemas/GitHubProjectNotice"}}}}]},"GitHubProjectLinkPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GitHubProjectLink"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"GitHubProjectLinkUpdate":{"type":"object","properties":{"direction":{"$ref":"#/components/schemas/GitHubSyncDirection"},"notice_delivery":{"$ref":"#/components/schemas/GitHubNoticeDelivery"},"board_id":{"type":"string","format":"uuid","nullable":true}}},"GitHubProjectNotice":{"type":"object","properties":{"kind":{"type":"string","enum":["overdue","stale","wip_exceeded"]},"link_id":{"type":"string","format":"uuid"},"project_title":{"type":"string"},"item_node_id":{"type":"string"},"title":{"type":"string"},"url":{"type":"string"},"detail":{"type":"string"}}},"GitHubProjectRoadmap":{"type":"object","properties":{"count":{"type":"integer"},"items_without_dates":{"type":"integer","description":"Omitted from the timeline and counted here. A chart that invented a date for undated work would be a chart of our guesses."},"coverage_is_complete":{"type":"boolean"},"entries":{"type":"array","items":{"$ref":"#/components/schemas/GitHubProjectRoadmapEntry"}}}},"GitHubProjectRoadmapEntry":{"type":"object","properties":{"link_id":{"type":"string","format":"uuid"},"project_title":{"type":"string"},"item_node_id":{"type":"string"},"title":{"type":"string"},"url":{"type":"string"},"start":{"type":"string","format":"date","nullable":true},"end":{"type":"string","format":"date","nullable":true},"status":{"type":"string"},"status_colour":{"type":"string"},"overdue":{"type":"boolean"},"lane":{"type":"string","description":"The iteration where the project has one, the project where it does not — which is what keeps one timeline readable across a sprint-driven and a date-driven project at the same time."}}},"GitHubProjectRollup":{"type":"object","properties":{"links_total":{"type":"integer"},"links_never_synced":{"type":"integer"},"links_failing":{"type":"integer"},"coverage_is_complete":{"type":"boolean","description":"Whether the counts describe every connected project. Named as a question about COVERAGE rather than health: a project that has never synced is not unhealthy, it is unmeasured, and only the second word is honest."},"items_total":{"type":"integer"},"items_open":{"type":"integer"},"items_archived":{"type":"integer"},"items_unassigned":{"type":"integer"},"items_no_status":{"type":"integer"},"overdue":{"type":"integer"},"stale":{"type":"integer"},"due_next_7_days":{"type":"integer"},"by_status":{"type":"array","items":{"$ref":"#/components/schemas/GitHubProjectStatusCount"}},"per_project":{"type":"array","items":{"type":"object","properties":{"link_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"owner_login":{"type":"string"},"project_number":{"type":"integer"},"items":{"type":"integer"},"open":{"type":"integer"},"overdue":{"type":"integer"},"stale":{"type":"integer"},"last_synced_at":{"type":"string","format":"date-time","nullable":true},"never_synced":{"type":"boolean"},"error":{"type":"string"}}}}}},"GitHubProjectStatusCount":{"type":"object","properties":{"option_id":{"type":"string"},"name":{"type":"string"},"colour":{"type":"string"},"count":{"type":"integer"},"limit":{"type":"integer","nullable":true},"over_limit":{"type":"boolean"}}},"GitHubProjectSummary":{"type":"object","properties":{"project_node_id":{"type":"string"},"project_number":{"type":"integer"},"title":{"type":"string"},"short_description":{"type":"string"},"closed":{"type":"boolean"},"public":{"type":"boolean"},"url":{"type":"string"},"updated_at":{"type":"string","format":"date-time"},"item_count":{"type":"integer","nullable":true},"owner_login":{"type":"string"},"owner_type":{"type":"string","enum":["organization","user"]}}},"GitHubProjectSyncResult":{"type":"object","properties":{"ok":{"type":"boolean","description":"A distinct field rather than something inferred from the counts. A project that legitimately has no items and a sync that could not see anything are the same zeros."},"error":{"type":"string"},"items_seen":{"type":"integer"},"items_created":{"type":"integer"},"items_updated":{"type":"integer"},"items_archived":{"type":"integer"},"fields_seen":{"type":"integer"},"conflicts":{"type":"integer"},"pushed_back":{"type":"integer","description":"Fields OUR value won and were therefore re-pushed to GitHub. Keeping a won value only on our side would be a resolution that resolves nothing and reports the same conflict on the next pull."},"pages":{"type":"integer"},"last_synced_at":{"type":"string","format":"date-time","nullable":true},"last_attempted_at":{"type":"string","format":"date-time","nullable":true}}},"GitHubProjectWipLimit":{"type":"object","required":["option_id"],"properties":{"option_id":{"type":"string","maxLength":64},"limit":{"type":"integer","minimum":0,"nullable":true}}},"GitHubSyncDirection":{"type":"string","enum":["both","pull"],"description":"`both` is the default (owner ruling, 2026-09-03: a new connection is read-write immediately). `pull` is the honest remedy when a push keeps being refused."},"GitHubWebhookSetup":{"type":"object","required":["state","url","events"],"properties":{"state":{"$ref":"#/components/schemas/GitHubWebhookState"},"url":{"type":"string","description":"The payload URL to paste into GitHub."},"secret":{"type":"string","description":"The signing secret, returned **only** for a connection the customer must configure themselves. Empty for an App connection, which is signed with the platform app's own secret and needs nothing from the customer."},"events":{"type":"array","items":{"type":"string"},"description":"The events the hook must subscribe to. `projects_v2_item` alone is not enough: renaming or closing the project emits `projects_v2`, and a board whose title is stale until the next sweep looks broken immediately."},"content_type":{"type":"string","description":"Always `json`. GitHub's default is `form`, which this endpoint cannot read."}}},"GitHubWebhookState":{"type":"string","enum":["pending","automatic","manual","failed"],"description":"Whether GitHub pushes changes at us, and if not, whose move it is. **Three outcomes and not a boolean.** `automatic` — we created the organisation webhook. `manual` — GitHub would not let us (creating one needs `admin:org_hook`, which most customers do not grant), so the customer creates it and `GET .../webhook` hands them the URL and the secret; this is the commonest outcome and is an instruction, not an error. `failed` — we tried and GitHub answered something unexpected; the reason is on `last_error`. `pending` — nothing has tried yet. The reconciliation sweep covers a connection in **every** state, so this decides how fast a change appears and never whether it appears."},"GlueRecord":{"type":"object","description":"A nameserver host inside the domain and the address(es) the registry holds for it.","required":["host"],"properties":{"host":{"type":"string","maxLength":253,"example":"ns1.example.com"},"ipv4":{"type":["string","null"],"description":"A public IPv4 address."},"ipv6":{"type":["string","null"],"description":"A public IPv6 address."},"registry":{"readOnly":true,"allOf":[{"$ref":"#/components/schemas/GlueRegistryState"}]}}},"GlueRegistryState":{"type":"object","description":"What the REGISTRY itself publishes for a nameserver host, read over RDAP on every call (the registrar's account list can differ: measured 2026-10-19, a deleted host lingered at the registry). `unknown` (no RDAP service for the TLD, a timeout) is never `absent`.","required":["state","ipv4","ipv6"],"properties":{"state":{"type":"string","enum":["present","absent","unknown"]},"ipv4":{"type":"array","items":{"type":"string"}},"ipv6":{"type":"array","items":{"type":"string"}}}},"GpuFlavour":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"gpu_count":{"type":"integer"},"gpu_model":{"type":"string"},"vcpus":{"type":"integer"},"ram_gb":{"type":"integer"},"price_per_hour_minor":{"type":"integer","nullable":true,"description":"Minor units of `currency` per GPU-hour. ⛔⛔ **`null` today for every row, and that is correct rather than missing** — the provider's flavour catalogue carries no price, and quoting one from a public rate card would be a list price for a different account presented as a measured one. Clients must render \"price on request\" and must **not** draw a zero."},"currency":{"type":"string","description":"ISO 4217 code the price would be denominated in."}}},"GpuFlavourList":{"type":"object","required":["flavours"],"properties":{"flavours":{"type":"array","items":{"$ref":"#/components/schemas/GpuFlavour"}}}},"GuestPostSite":{"type":"object","description":"One guest-post site from ZinnHub's feed (GUESTFEED1114). Signed in, `revealed` is true, `domain` and `domain_ascii` always carry the real site, and `name` and `sample_url` carry it where the site has them (otherwise null); on the public list all four are null and `revealed` is false.","required":["site_uid","label","revealed","currency","offers"],"properties":{"site_uid":{"type":"string"},"label":{"type":"string","description":"The public name, \"Site\" and its number (e.g. \"Site 12\")."},"revealed":{"type":"boolean"},"domain":{"type":["string","null"]},"domain_ascii":{"type":["string","null"]},"name":{"type":["string","null"]},"sample_url":{"type":["string","null"]},"language":{"type":["string","null"]},"country":{"type":["string","null"]},"general_niche":{"type":["string","null"]},"link_type":{"type":["string","null"]},"sponsored_label":{"type":["string","null"]},"turnaround_days":{"type":["integer","null"]},"max_links":{"type":["integer","null"]},"word_count_min":{"type":["integer","null"]},"revisions":{"type":["integer","null"]},"price_from_minor":{"type":["integer","null"]},"currency":{"type":"string"},"dr":{"type":["integer","null"]},"metrics":{"type":"object","additionalProperties":true},"verified_traffic":{"type":"object","additionalProperties":true},"offers":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"type":{"type":["string","null"]},"name":{"type":["string","null"]},"price_minor":{"type":["integer","null"]}}}},"niches":{"type":"array","items":{"type":"object","additionalProperties":true}},"labels":{"type":"array","items":{"type":"string"}},"last_checked":{"type":["string","null"],"format":"date-time"}}},"GuestPostSitePage":{"type":"object","required":["data","total","page","per_page","applied","revealed"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GuestPostSite"}},"total":{"type":"integer"},"page":{"type":"integer"},"per_page":{"type":"integer"},"applied":{"type":"object","additionalProperties":true},"revealed":{"type":"boolean"}}},"Health":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["ok"],"example":"ok"},"version":{"type":"string","example":"0.1.0"}}},"HolderDocumentKind":{"type":"string","enum":["identity","proof_of_address","company_register_extract"],"description":"`identity` — ID card or passport; `proof_of_address` — a recent utility bill, bank statement or registration certificate; `company_register_extract` — an extract from the company register."},"HolderVerification":{"type":"object","required":["id","domain_id","fqdn","holder_kind","status","issued_at","deadline_at","days_left","required_documents","missing_documents","customer_message","documents"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"domain_id":{"$ref":"#/components/schemas/Uuid"},"fqdn":{"type":"string"},"holder_kind":{"type":"string","enum":["individual","organisation"]},"status":{"$ref":"#/components/schemas/HolderVerificationStatus"},"issued_at":{"type":"string","format":"date-time","nullable":true},"deadline_at":{"type":"string","format":"date-time","nullable":true},"days_left":{"type":"integer","description":"Whole days to the deadline, rounded DOWN, never below 0."},"required_documents":{"type":"array","items":{"$ref":"#/components/schemas/HolderDocumentKind"}},"missing_documents":{"type":"array","items":{"$ref":"#/components/schemas/HolderDocumentKind"}},"customer_message":{"type":"string","description":"What our verification team asked you to change; empty when nothing."},"submitted_at":{"type":"string","format":"date-time","nullable":true},"registrar_submitted_at":{"type":"string","format":"date-time","nullable":true},"closed_at":{"type":"string","format":"date-time","nullable":true},"documents_purged_at":{"type":"string","format":"date-time","nullable":true},"documents":{"type":"array","items":{"$ref":"#/components/schemas/HolderVerificationDocument"}}}},"HolderVerificationDocument":{"type":"object","required":["id","kind","filename","content_type","size_bytes","uploaded_at","accepted","purged"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"kind":{"$ref":"#/components/schemas/HolderDocumentKind"},"filename":{"type":"string"},"content_type":{"type":"string","enum":["application/pdf","image/jpeg","image/png"]},"size_bytes":{"type":"integer"},"uploaded_at":{"type":"string","format":"date-time","nullable":true},"accepted":{"type":"boolean","description":"Staff accepted it and it went to the registry."},"purged":{"type":"boolean","description":"The encrypted copy has been destroyed."}}},"HolderVerificationList":{"type":"object","required":["items","count"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/HolderVerification"}},"count":{"type":"integer"}}},"HolderVerificationStatus":{"type":"string","enum":["pending_confirmation","awaiting_documents","under_review","changes_requested","submitted_to_registrar","verified","expired","cancelled"],"description":"`pending_confirmation` is staff-only (a detected request not yet confirmed) and never returned to a customer or partner."},"HostingCodeAnswer":{"type":"object","required":["org_id","offer"],"properties":{"org_id":{"type":"string","format":"uuid"},"offer":{"oneOf":[{"$ref":"#/components/schemas/HostingCodeOffer"},{"type":"null"}]}}},"HostingCodeOffer":{"type":"object","description":"A plugin licence holder's personal hosting code (50% off the first year).","required":["code","percent_off","plans","interval","usable","status","checkout_url"],"properties":{"code":{"type":"string","example":"ZINNHOST-7KQ4M2XA"},"percent_off":{"type":"integer","minimum":1,"maximum":100,"example":50},"plans":{"type":"array","description":"The hosting plan codes the code applies to.","items":{"type":"string"},"example":["mainstream_start","mainstream_grow"]},"interval":{"type":"string","enum":["annual"],"description":"The code applies to a plan billed yearly, for its first year only."},"usable":{"type":"boolean","description":"Whether the code can still be used."},"status":{"type":"string","description":"`available`, or why it cannot be used now — the coupon refusal reason (`exhausted` once it has been used, `inactive` if it was withdrawn)."},"checkout_url":{"type":"string","format":"uri"}}},"HostingFinderOptions":{"type":"object","required":["cms","purpose","product_lines"],"properties":{"cms":{"type":"array","items":{"type":"string"},"description":"Application keys our own fleet can install or an active line's policy allows, plus `static` and `none`. Enumerated from the estate so the form cannot ask a question the platform has no answer to."},"purpose":{"type":"array","items":{"type":"string"}},"product_lines":{"type":"array","items":{"type":"string"}}}},"HostingFinderRequest":{"type":"object","description":"The guided form's answers. **Every field is optional** — a half-filled form is a real and common answer, and refusing it would put a wall in front of the recommendation the form exists to give.","properties":{"purpose":{"type":"string","maxLength":32,"description":"`single_site` | `store` | `app` | `developer` | `ai` | `lms` | `agency` | `reseller` | `pbn` | `server`; anything else is read as not answered. Each purpose admits only the kinds of plan made for it — a Footprint-Free plan is recommended for `pbn` and nothing else (D32720)."},"cms":{"type":"string","maxLength":64,"description":"A key from `getPublicHostingFinderOptions`, or `static` / `none`."},"sites":{"type":"integer","minimum":1,"maximum":1000000},"monthly_visits":{"type":"integer","minimum":0},"needs_email":{"type":"boolean","default":false},"needs_domain":{"type":"boolean","default":false},"needs_ssh":{"type":"boolean","default":false},"budget_max_minor":{"type":"integer","minimum":0,"description":"A ceiling in the response currency's minor units. Over-budget plans are still returned, carrying an `over_budget` caveat: a finder that returns nothing because every plan is a pound over has answered nobody's question."},"limit":{"type":"integer","minimum":1,"maximum":50,"default":3,"description":"How many plans to return, best first. Up to 50, so a picker can list every plan that fits (a PBN has 42 tiers) rather than the first ten."}}},"HostingReason":{"type":"object","required":["code","value"],"properties":{"code":{"type":"string","description":"A machine value — `covers_sites`, `installs_cms`, `includes_free_domain`, `within_budget`, `free_trial`, `purpose_pbn`, `cms_not_offered`, `visits_overage_above`, `over_budget`, … **Never a sentence**: every surface renders its own copy in its own language, and an English string minted in the engine would reach an Arabic page inside an RTL document. A code a client does not recognise is skipped, not rendered."},"value":{"description":"The number or key the reason is about (the site allowance, the CMS key, the price), or `null` where the code says everything."}}},"HostingRecommendation":{"type":"object","required":["plan_code","plan_name","product_line","product_line_name","score","amount_minor","currency","interval","per_month_minor","reasons","caveats"],"properties":{"plan_code":{"type":"string"},"plan_name":{"type":"string"},"product_line":{"type":"string"},"product_line_name":{"type":"string"},"score":{"type":"integer","description":"Higher is better. Exposed so a client can say \"best match\" honestly rather than calling the first row best when the top two are tied."},"amount_minor":{"type":"integer","format":"int64"},"currency":{"type":"string","minLength":3,"maxLength":3},"interval":{"type":"string","enum":["monthly","annual"]},"per_month_minor":{"type":"integer","format":"int64","description":"The cheapest term's price per month, in `currency`'s minor units. Plans are ranked by this (never by `amount_minor`, which is a whole year on an annual term) and a page shows it beside the plan (D32720)."},"reasons":{"type":"array","items":{"$ref":"#/components/schemas/HostingReason"}},"caveats":{"type":"array","description":"What the answers ruled out about this plan. Served **even on the top result**: a finder that only ever says yes is an advert, and the owner asked for the reasoning to be shown.","items":{"$ref":"#/components/schemas/HostingReason"}}}},"HostingRegion":{"type":"object","required":["code","slug","city","country","name_key","available"],"additionalProperties":false,"properties":{"code":{"type":"string","description":"The placement key a site or an order carries as `region`.","example":"nbg1"},"slug":{"type":"string","description":"Our public identifier for the city; empty when we have not named it.","example":"nuremberg"},"city":{"type":"string","description":"The city in English — a fallback for a client with no catalogue of its own.","example":"Nuremberg"},"country":{"type":"string","description":"ISO-3166 alpha-2, or empty when unknown. Decorative; never the accessible name.","example":"DE"},"name_key":{"type":"string","description":"The catalogue key for \"City, Country\" in the reader's language.","example":"region.nbg1"},"available":{"type":"boolean","description":"Derived from registered fleet capacity — a box in this region can take a new site right now. Always `true` unless `include=unavailable` was passed."}}},"Hostname":{"type":"string","description":"A fully-qualified DNS hostname, lowercase, no trailing dot.","pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+$","maxLength":253,"example":"acme.example.com"},"IdeAssistAnswer":{"type":"object","description":"One reply from the editor's assistant.","required":["action","answer","proposal","model","funding"],"properties":{"action":{"type":"string","description":"The action this answers, echoed so the editor can render it correctly."},"answer":{"type":"string","description":"The assistant's answer, as markdown. Never blank on a `200` — an empty answer is a `422`, because the call was paid for either way and a blank panel in an editor is indistinguishable from a broken one."},"proposal":{"type":"string","description":"The complete replacement for the region that was sent, or empty. Non-empty only for an editing action, and only when the model returned exactly one well-formed code block with nothing elided — an answer that leaves part of the file out is refused rather than offered, because applying it would delete whatever it stood for. **A suggestion, never an instruction:** the editor diffs it and applies it only after the customer approves."},"model":{"type":"string","description":"The model that answered, so the editor can show what the customer paid for."},"funding":{"type":"string","description":"Which route paid — the customer's own provider key, their Zinn® credit, or their included allowance. The same decision the AI page renders, never a second one."}}},"IdeAssistAsk":{"type":"object","description":"One request about one file, made from inside the site's web editor.","required":["context"],"properties":{"action":{"type":"string","default":"ask","enum":["ask","explain","fix","refactor","complete","generate"],"description":"What to do. `ask` and `explain` are read-only and answer in prose. `fix`, `refactor`, `complete` and `generate` return a `proposal` the editor shows as a diff for the customer to approve — nothing is ever applied without that."},"question":{"type":"string","maxLength":4000,"description":"What the developer wants. Required for `ask` and `generate`; optional for the rest. Longer than 4,000 characters is a `422` asking them to select the part of the file they mean."},"path":{"type":"string","description":"The file's path relative to the site, shown to the model so it can reason about what kind of file it is. Optional — an unsaved buffer has none."},"context":{"type":"string","description":"The file, or the selected region of it. Truncated to 24,000 characters for a read-only action, and the answer says so rather than silently answering about a fragment. An **editing** action on a file longer than that is refused outright: a partial answer is merely less useful, while a partial *replacement*, applied, would delete everything after the cut."},"model":{"type":"string","description":"A model from `/ide-assist/models`. Omit for the automatic choice, which is the cheapest model that can do the job, computed from our price list."}}},"IdeAssistCredit":{"type":"object","description":"What the web editor shows beside its assistant: what is left to spend, and where the customer adds more. Read from the one AI meter every other surface uses — there is no second balance for the editor.","required":["available"],"properties":{"available":{"type":"boolean","description":"False when the meter could not be read. A third state on purpose: *we could not look* is not *you have nothing*, and collapsing them puts a top-up prompt in front of an account that is perfectly funded. Every other field is absent when this is false."},"currency":{"type":"string","description":"ISO 4217, for the amounts below."},"balance_micros":{"type":"integer","description":"Purchased credit held, in USD micros. ⛔ Not what they can spend — see `spendable_micros`."},"spendable_micros":{"type":"integer","description":"Everything that can pay for the next call: the balance PLUS what is left of today's included allowance. **This is the number the editor renders.**"},"included_remaining_micros":{"type":"integer","description":"What is left of today's included allowance, in USD micros."},"is_low":{"type":"boolean","description":"Whether what is spendable is low enough to say so. Computed by the meter rather than by each screen, because a second implementation of \"low\" is a second answer and the screen's is the one the customer believes."},"is_empty":{"type":"boolean","description":"Nothing can fund the next call — no credit and no allowance left."},"on_byo":{"type":"boolean","description":"The organisation holds a live key for every provider we route to, so credit genuinely cannot be spent. The editor shows no top-up affordance here: selling credit to somebody whose every call runs on their own key sells them nothing."},"top_up_url":{"type":"string","description":"Where this customer adds credit, resolved from **their own brand** — a reseller's customer is never sent to a hostname that is not their reseller's. Empty when `on_byo` is true, or when no brand could be resolved; the editor then renders the balance without a link rather than inventing one."}}},"IdeAssistModel":{"type":"object","description":"One model the editor's picker may offer, **with its price**. Since 2026-09-09 a model we cannot price is not offered at all, so every entry here carries a real figure a customer can read before spending.","required":["model","priced","default","input_usd_per_mtok","output_usd_per_mtok","cached_input_usd_per_mtok","currency","price_captured_on","price_source","price_age_days","price_is_stale"],"properties":{"model":{"type":"string"},"priced":{"type":"boolean","description":"Always `true`. Kept so an older editor build that reads it keeps working, and because a field that is now an invariant is worth stating: **an unpriced model is not offered.** Owner ruling 2026-09-09 — *\"it can never say unknown!\"* — after 33 of the 45 verified models on production had no price and the picker said so."},"default":{"type":"boolean","description":"Whether this is the automatic choice — the cheapest that can do the job."},"input_usd_per_mtok":{"type":"string","description":"USD per 1,000,000 prompt tokens. A **string**, not a number: an exact decimal to six places, and JSON has one number type, which is a float."},"output_usd_per_mtok":{"type":"string","description":"USD per 1,000,000 completion tokens."},"cached_input_usd_per_mtok":{"type":"string","description":"USD per 1,000,000 cached prompt tokens."},"currency":{"type":"string","description":"ISO 4217 — USD on every published list price today."},"price_captured_on":{"type":"string","format":"date","description":"The day the figure was read from the vendor."},"price_source":{"type":"string","enum":["operator","measured","vendor","shipped","alias"],"description":"Which ranked source answered."},"price_age_days":{"type":"integer","description":"How old the figure is. The editor shows it beside a stale price rather than hiding the model — a freshness problem must not become an availability one."},"price_is_stale":{"type":"boolean","description":"Older than the platform's price-freshness window."}}},"IdeAssistModels":{"type":"object","description":"The editor's model picker, cheapest first.","required":["models","refusal"],"properties":{"models":{"type":"array","items":{"$ref":"#/components/schemas/IdeAssistModel"}},"refusal":{"type":"string","description":"Why `models` is empty, when it is. Empty otherwise. An empty list with no reason cannot be told apart from \"we could not look\", so the reason travels with it."}}},"IdeChatAsk":{"type":"object","description":"One turn of the editor's chat, with the tools the editor can run.","required":["messages"],"properties":{"messages":{"type":"array","description":"The conversation so far. The engine is stateless, so the whole transcript arrives on every call and the caller bounds it.","items":{"$ref":"#/components/schemas/IdeChatMessage"}},"tools":{"type":"array","description":"What the editor can run — its MCP servers' tools and any the customer's own extensions contribute. Bounded and coerced on arrival; a malformed entry is dropped rather than offered, because a tool never offered cannot be called.","items":{"$ref":"#/components/schemas/IdeChatToolOffer"}},"path":{"type":"string","description":"The file the customer is looking at, if any."},"context":{"type":"string","description":"That file's contents, truncated to the assistant's context cap."},"model":{"type":"string","description":"A model from `/ide-assist/models`. Omit for the automatic choice, which is the cheapest priced model the organisation can run."}}},"IdeChatMessage":{"type":"object","description":"One turn of the editor's conversation. Authored inside the customer's own hosting jail, so it is data: the role is mapped to a closed set and anything unrecognised becomes `user`, never `assistant`.","properties":{"role":{"type":"string","enum":["user","assistant"]},"text":{"type":"string"},"tool_calls":{"type":"array","description":"An assistant turn being replayed with the tools it asked for. Providers match a result to a call by `id` and reject a result whose call they never saw, so a transcript that drops these cannot be continued.","items":{"$ref":"#/components/schemas/IdeChatToolCall"}},"tool_results":{"type":"array","description":"What the editor got back from running them.","items":{"type":"object","required":["call_id","content"],"properties":{"call_id":{"type":"string"},"content":{"type":"string"},"is_error":{"type":"boolean","description":"A first-class field, not an error string in `content`. A tool that failed and a tool that returned the word \"failed\" are different facts, and collapsing them is how a model reports a broken integration as a real answer about the customer's site."}}}}}},"IdeChatToolCall":{"type":"object","description":"The assistant asking the editor to run one tool. **A request, never something that has happened** — nothing on the engine side runs a tool, and there is deliberately no `result` field here for it to have put one in.","required":["id","name","arguments"],"properties":{"id":{"type":"string","description":"The provider's correlation handle. Echo it on the matching result."},"name":{"type":"string"},"arguments":{"type":"object","additionalProperties":true}}},"IdeChatToolOffer":{"type":"object","description":"One tool the editor is willing to run on the assistant's behalf.","required":["name","input_schema"],"properties":{"name":{"type":"string","maxLength":64},"description":{"type":"string","maxLength":1000},"input_schema":{"type":"object","description":"JSON Schema for the tool's arguments, as the MCP client reported it.","additionalProperties":true}}},"IdeChatTurn":{"type":"object","description":"One turn back. Exactly one of `answer` and `tool_calls` is meaningful: a non-empty `tool_calls` means the conversation is unfinished and the editor must run them and come back.","required":["answer","tool_calls","model","funding","turns","credit"],"properties":{"answer":{"type":"string","description":"Empty when the assistant asked for tools instead. Never empty alongside an empty `tool_calls` — that is a `422` with its own sentence, because the call was paid for either way."},"tool_calls":{"type":"array","items":{"$ref":"#/components/schemas/IdeChatToolCall"}},"model":{"type":"string"},"funding":{"type":"string","description":"Which purse ran it — the same value the AI page renders, from the same decision. The editor shows \"your Zinn® credit\" or \"your own API key\" beneath the answer."},"turns":{"type":"integer","minimum":0,"description":"How many turns of this conversation have already asked for tools, so the editor can stop a model that will not settle rather than paying for it indefinitely."},"credit":{"allOf":[{"$ref":"#/components/schemas/IdeAssistCredit"}],"description":"The balance **after** this turn, so the editor's running total moves with the question that spent it rather than lagging one call behind."}}},"IdeEditorEvent":{"type":"object","description":"Acknowledgement that an editor action was recorded.","required":["recorded"],"properties":{"recorded":{"type":"boolean"}}},"IdeEditorEventCreate":{"type":"object","description":"One thing the customer did in the web editor.","required":["event"],"properties":{"event":{"type":"string","enum":["file_saved","ai_applied","file_restored","terminal_opened","ai_created","ai_edited","ai_moved","ai_deleted"],"description":"A closed set. The caller runs inside the cage being audited, so it names an event and the engine chooses the audit action — a log whose rows can be authored by their own subject is not an audit log."},"path":{"type":"string","description":"The file, relative to the site. Truncated to 512 characters."},"bytes_before":{"type":"integer","minimum":0,"description":"Size of the file before the write, so a truncation is visible in the log."},"bytes_after":{"type":"integer","minimum":0},"version":{"type":"string","description":"Which kept version was restored, for a `file_restored` event."}}},"ImpersonationExitRequest":{"type":"object","description":"Body for ending an impersonation session. Deliberately empty in practice — `refresh_token` is retained, optional and ignored so a dashboard build from before the Zinn-owned grant does not get a 400 on the one control that gets a staff member OUT of a customer's account.","properties":{"refresh_token":{"type":"string","deprecated":true,"description":"Ignored. There is no upstream session to revoke."}}},"ImpersonationRedeemRequest":{"type":"object","description":"The single-use ticket from an ImpersonationGrant `url` fragment.","required":["ticket"],"properties":{"ticket":{"type":"string","maxLength":200}}},"ImpersonationRedeemed":{"type":"object","description":"The customer session token for a redeemed grant — the only place a grant token is ever returned. Confined to `org_id`, and dead the moment the session is ended.","required":["token","expires_at","session_id","org_id","org_name","actor"],"properties":{"token":{"type":"string","description":"The customer session bearer token (carries the staff `act` claim)."},"expires_at":{"type":"string","format":"date-time"},"session_id":{"type":"string"},"org_id":{"type":"string","description":"The single org this grant is good for."},"org_name":{"type":"string"},"actor":{"type":"string","description":"The real staff actor (`user:<id>`), for the banner."},"kind":{"type":"string","enum":["support","delegated_sign_in"],"description":"`support` — a staff member is viewing the customer's account (the non-dismissable staff banner). `delegated_sign_in` — the customer's OWN sign-in, handed over by the partner or reseller that manages them (a quiet \"Signed in from …\" notice, and signing out returns to the ordinary sign-in page). The grant is identical; the minting actor is audited either way."},"delegated_by":{"type":"string","description":"The partner's (or reseller's) name for `delegated_sign_in`, else \"\"."},"delegated_return_url":{"type":"string","description":"For a partner's `delegated_sign_in`: the way back to the partner's own app (https, the partner's first registered return host, path `/`), shown as \"Back to\" and the partner's name; else \"\"."}}},"ImpersonationStatus":{"type":"object","description":"The \"am I impersonating?\" status that drives the non-dismissable banner.","required":["active"],"properties":{"active":{"type":"boolean"},"actor":{"type":"string","description":"The real staff actor (`user:<id>`) when active."},"actor_email":{"type":"string","description":"The staff actor's e-mail, so the banner names a person rather than an id. Empty when inactive or when the actor is not a user."},"org_id":{"type":"string"},"org_name":{"type":"string"},"expires_at":{"type":"string","format":"date-time","nullable":true},"session_id":{"type":"string"},"kind":{"type":"string","enum":["support","delegated_sign_in"],"description":"`support` — a staff member is viewing the customer's account (the non-dismissable staff banner). `delegated_sign_in` — the customer's OWN sign-in, handed over by the partner or reseller that manages them (a quiet \"Signed in from …\" notice, and signing out returns to the ordinary sign-in page). The grant is identical; the minting actor is audited either way."},"delegated_by":{"type":"string","description":"The partner's (or reseller's) name for `delegated_sign_in`, else \"\"."},"delegated_return_url":{"type":"string","description":"For a partner's `delegated_sign_in`: the way back to the partner's own app (https, the partner's first registered return host, path `/`), shown as \"Back to\" and the partner's name; else \"\"."}}},"InboundEmail":{"type":"object","description":"One parsed inbound message, as the Email Routing Worker sends it. Deliberately small: every decision — which ticket, is the sender known, is this a duplicate — is made by the engine, so the Worker never needs to understand a ticket.","required":["from","message_id"],"properties":{"from":{"type":"string","maxLength":320,"description":"The envelope sender. Forgeable, and treated as such — it is checked against the ticket's org and the answer becomes a flag, never a permission."},"to":{"type":"string","maxLength":320},"message_id":{"type":"string","maxLength":998,"description":"The message's own `Message-ID`. Stored, and unique, so a redelivery cannot append twice."},"in_reply_to":{"type":"string","description":"Carries the signed ticket token when the customer replied to one of our notifications."},"references":{"type":"string","description":"The full thread chain. Searched as well as `in_reply_to`, because a reply to the third message in a thread puts our id here and not there."},"subject":{"type":"string"},"text":{"type":"string","description":"The message body. Quoted history is trimmed engine-side and the result is length-bounded."}}},"InboundEmailHeld":{"type":"object","description":"An inbound message the support spam guard held instead of filing.","required":["held","reason","ticket_id","duplicate"],"properties":{"held":{"type":"boolean","enum":[true]},"reason":{"type":"string","enum":["blocked_sender","duplicate","sender_flood","mail_loop"]},"ticket_id":{"type":"string","format":"uuid","nullable":true,"description":"For `duplicate`, the ticket the original message is already on."},"duplicate":{"type":"boolean"}}},"InboundEmailResult":{"type":"object","required":["ticket_id","duplicate","sender_verified","reopened"],"properties":{"ticket_id":{"type":"string","format":"uuid"},"duplicate":{"type":"boolean","description":"This exact message had already been filed — a success, not an error."},"sender_verified":{"type":"boolean","description":"Whether the sender is a known address on the ticket's org. `false` still files the message, flagged for staff."},"reopened":{"type":"boolean","description":"Whether filing it moved a `solved` ticket back to `open`."}}},"InboxMessage":{"type":"object","required":["id","kind","thread_key","subject","body","locale","created_at","read"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["campaign","ticket","account"]},"thread_key":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"},"body_html":{"type":"string"},"locale":{"type":"string"},"link_url":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"read":{"type":"boolean"}}},"InboxThread":{"type":"object","required":["thread_key","kind","subject","preview","message_count","unread_count"],"additionalProperties":false,"properties":{"thread_key":{"type":"string"},"kind":{"type":"string","enum":["campaign","ticket","account"]},"subject":{"type":"string"},"preview":{"type":"string"},"latest_at":{"type":"string","format":"date-time","nullable":true},"message_count":{"type":"integer"},"unread_count":{"type":"integer"},"link_url":{"type":"string","description":"⛔ Always a RELATIVE dashboard route. An absolute URL is refused at write time — an in-app link is clicked by a signed-in customer, so accepting one would be an open redirect on a trusted surface."}}},"InboxThreadDetail":{"type":"object","required":["thread_key","messages"],"additionalProperties":false,"properties":{"thread_key":{"type":"string"},"subject":{"type":"string"},"kind":{"type":"string","enum":["campaign","ticket","account"]},"messages":{"type":"array","items":{"$ref":"#/components/schemas/InboxMessage"}}}},"InboxUnread":{"type":"object","description":"⛔ `capped` is not decoration. A bare number that silently stops at the cap lies at exactly the moment it matters most; the client renders \"9+\" from this flag rather than inferring it from the value.","required":["unread","capped"],"additionalProperties":false,"properties":{"unread":{"type":"integer"},"capped":{"type":"boolean"}}},"InboxUpdateResult":{"type":"object","additionalProperties":false,"properties":{"marked_read":{"type":"integer"},"archived":{"type":"integer"},"unread":{"type":"integer"},"capped":{"type":"boolean"}}},"IndexMonitoring":{"type":"object","required":["daily","daily_from_plan","sections","external_sites","targets"],"additionalProperties":false,"properties":{"daily":{"type":"boolean","description":"Checks run daily rather than weekly."},"daily_from_plan":{"type":"boolean","description":"The daily cadence came from the plan rather than a standalone add-on. ⭐ An upsell surface reads this to say \"included in your plan\" instead of offering to sell something the customer already has."},"sections":{"$ref":"#/components/schemas/IndexMonitoringAllowance"},"external_sites":{"$ref":"#/components/schemas/IndexMonitoringAllowance"},"targets":{"type":"array","items":{"$ref":"#/components/schemas/IndexMonitoringTarget"}}}},"IndexMonitoringAllowance":{"type":"object","description":"One counted allowance, always with its denominator. ⛔ `remaining` alone is not renderable: it reads the same on an allowance of 3 with nothing used as on an allowance of 100 with 97 used, and only one of those is worth offering an upgrade for.","required":["allowance","used","remaining"],"additionalProperties":false,"properties":{"allowance":{"type":"integer","description":"How many this plan and its add-ons permit. `0` means none is bought."},"used":{"type":"integer","description":"How many rows exist. May exceed `allowance` after a downgrade."},"remaining":{"type":"integer","description":"`allowance - used`, floored at zero. ⛔ Never negative — a downgraded account shows `0` remaining and keeps its rows; see `monitored` on each target."}}},"IndexMonitoringTarget":{"type":"object","description":"One page, section or whole external site being monitored for indexing.","required":["id","kind","fqdn","path","label","operand","created_at","indexed","checked_at","monitored"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["section","external_site"],"description":"`section` is a page or path prefix inside a site, on top of the free whole-site check. `external_site` is an entire website hosted somewhere else, billed per site per month. They consume different allowances and are not interchangeable."},"fqdn":{"type":"string","description":"The hostname, lower-cased."},"path":{"type":"string","description":"The path prefix without slashes (`blog`, `shop/offers`). Always empty on an `external_site`, and never empty on a `section`."},"label":{"type":"string","description":"What the customer calls it, so a list of twelve paths is readable."},"operand":{"type":"string","description":"The exact search operand checked, e.g. `example.com/blog`."},"created_at":{"type":"string","format":"date-time"},"indexed":{"type":"boolean","nullable":true,"description":"⛔ **Three-valued.** `true` and `false` are answers from the provider. `null` means no reading exists yet, **or** this row is beyond the current allowance and is not being checked — read `monitored` to tell those apart. A client that renders `null` as `false` tells a customer their pages have been deindexed when nobody looked."},"checked_at":{"type":"string","format":"date-time","nullable":true,"description":"When the reading was taken. `null` when there has never been one."},"monitored":{"type":"boolean","description":"Whether the sweep is currently checking this row. `false` with the row still present is the \"you have downgraded, this one is paused\" state — shown rather than hidden, because the row is kept deliberately and the customer can free a slot."}}},"IndexMonitoringTargetCreate":{"type":"object","required":["fqdn"],"additionalProperties":false,"properties":{"kind":{"type":"string","enum":["section","external_site"],"default":"section"},"fqdn":{"type":"string","description":"The hostname to monitor, e.g. `example.com`."},"path":{"type":"string","description":"Required for `section`, and rejected for `external_site`. ⛔ An empty path on a section would be the whole site, which every plan already checks free — so it is refused rather than silently charged for."},"label":{"type":"string","maxLength":120}}},"InferenceDeployment":{"type":"object","required":["id","name","state","replicas"],"properties":{"id":{"type":"string","description":"The provider's identifier. For Gcore this is the deployment **name**."},"name":{"type":"string"},"state":{"type":"string","enum":["provisioning","running","stopped","failed","degraded","deleting"]},"model":{"type":"string"},"flavour":{"type":"string"},"replicas":{"type":"integer","description":"Replicas **requested**."},"ready_replicas":{"type":"integer","nullable":true,"description":"Replicas actually **serving**. ⛔ `null` when the provider reported no readiness at all, which is not the same as zero."},"endpoint_url":{"type":"string"},"region":{"type":"string"}}},"InferenceDeploymentList":{"type":"object","required":["deployments"],"properties":{"deployments":{"type":"array","items":{"$ref":"#/components/schemas/InferenceDeployment"}}}},"Invitation":{"type":"object","description":"A pending (or resolved) invitation to join an organization with a role. No secret is exposed — accept is authorized by the invitee's verified email (register #31).","required":["id","org_id","org_name","email","role","status","expires_at","created_at","site_grants"],"properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"org_name":{"type":"string","description":"The inviting organisation's display name, so an invitee can answer \"accept?\".","example":"Agency Ltd"},"email":{"type":"string","format":"email","example":"teammate@example.com"},"role":{"type":"string","example":"manager"},"site_grants":{"type":"array","description":"The individual sites this invitation lends, when it was created by sharing a site with an address that had no account (`POST /v1/sites/{siteId}/collaborators`). Empty for an ordinary team invitation. Each becomes a live per-site grant for the accepting person the moment they accept.","items":{"type":"object","required":["site_id","primary_domain","role"],"additionalProperties":false,"properties":{"site_id":{"type":"string","format":"uuid"},"primary_domain":{"type":"string","example":"client-site.example.com"},"role":{"$ref":"#/components/schemas/SiteCollaboratorRole"}}}},"status":{"type":"string","enum":["pending","accepted","revoked"],"example":"pending"},"expires_at":{"type":"string","format":"date-time"},"accepted_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"InvitationCreate":{"type":"object","description":"Invite an email to a role. The role must be one the inviter may grant.","required":["email","role"],"properties":{"email":{"type":"string","format":"email","maxLength":254,"example":"teammate@example.com"},"role":{"type":"string","maxLength":64,"description":"The role key to grant (e.g. `manager`, `billing`).","example":"manager"},"org_id":{"type":"string","format":"uuid","description":"Organization to invite into; defaults to the caller's own. The caller must hold `members.invite` in **that** organization."}}},"InvitationPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Invitation"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"Invoice":{"type":"object","description":"A legal billing document — an invoice or a credit note (docs/34 §1). An immutable snapshot with a gapless, per-entity number, a captured tax treatment and frozen FX rates; a reprint years later is byte-identical to the original. Amounts are integer minor units (§2.8); the margin/registrar-cost fields on the underlying order are never exposed (§2.4).","required":["id","document_type","number","status","currency","subtotal_minor","tax_minor","discount_minor","total_minor","lines","payments","pdf_url","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"document_type":{"$ref":"#/components/schemas/InvoiceDocumentType"},"order_id":{"type":["string","null"],"format":"uuid","description":"The order this document bills; null for a document raised without one."},"credits_invoice_id":{"type":["string","null"],"format":"uuid","description":"For a `credit_note`, the invoice it un-bills. Always null on an `invoice`."},"number":{"type":"string","description":"The gapless legal document number (docs/34 §1.2), allocated per legal entity, series and year. Credit notes use the separate `ZD-CRN` series.","example":"ZD-INV-2026-000123"},"status":{"$ref":"#/components/schemas/InvoiceStatus"},"currency":{"$ref":"#/components/schemas/CurrencyCode"},"subtotal_minor":{"type":"integer","format":"int64"},"tax_minor":{"type":"integer","format":"int64"},"discount_minor":{"type":"integer","format":"int64"},"total_minor":{"type":"integer","format":"int64"},"issued_at":{"type":["string","null"],"format":"date-time","description":"When the document was issued and its number allocated."},"pdf_url":{"type":["string","null"],"description":"A short-lived PDF link once rendered (docs/34 §4.2); null until then."},"lines":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceLine"}},"payments":{"type":"array","description":"Payment attempts against the order this document bills, so a customer can see how an invoice was settled. Empty for a document with no order.","items":{"$ref":"#/components/schemas/Payment"}},"created_at":{"type":"string","format":"date-time"}}},"InvoiceDocumentLink":{"type":"object","description":"A short-lived signed URL to a rendered invoice document (#708).","required":["url","locale"],"properties":{"url":{"type":"string","format":"uri","description":"Minted per request and **never persisted** — it expires in minutes, so storing it in a list payload or a cache would hand a client a link that is already dead."},"expires_at":{"type":"string","format":"date-time"},"locale":{"type":"string","description":"The language the document was rendered in."}}},"InvoiceDocumentType":{"type":"string","description":"Which kind of legal document this is (docs/34 §1.3). An `invoice` is what we bill; a `credit_note` is what we un-bill — it carries its own `ZD-CRN` series number and names the invoice it credits in `credits_invoice_id`.","enum":["invoice","credit_note"]},"InvoiceLine":{"type":"object","description":"One line of a legal invoice or credit note (docs/34 §6) — **write-once and frozen at issue**, so it is the amount and rate that were actually billed, never a live recomputation. Distinct from `OrderLine`: an order line records what was bought (its kind, what it provisioned, its metadata); an invoice line records what was charged and at what tax rate.","required":["id","description","quantity","unit_amount_minor","discount_minor","currency","tax_rate_bps","tax_amount_minor","tax_treatment"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"description":{"type":"string"},"quantity":{"type":"integer","format":"int32"},"unit_amount_minor":{"type":"integer","format":"int64"},"discount_minor":{"type":"integer","format":"int64"},"currency":{"$ref":"#/components/schemas/CurrencyCode"},"tax_rate_bps":{"type":"integer","format":"int32","description":"The captured rate in basis points (20% = 2000), frozen at issue (docs/34 §1.4)."},"tax_amount_minor":{"type":"integer","format":"int64"},"tax_treatment":{"$ref":"#/components/schemas/TaxTreatment"},"tax_service_type":{"type":"string","description":"`electronically_supplied` or `general_service`, frozen at issue (#1480) — the classification that decided **where** this line was supplied. Blank on documents issued before it existed; those were all `not_registered` at 0%, so nobody classified them and inventing one now would put historical money on a return nobody chose."},"tax_return":{"type":"string","description":"Which VAT return this line's tax lands on — `uk_vat`, `non_union_oss` or `none`. **Stored, not derived**: the quarterly OSS figures are then a `GROUP BY` over what was actually charged, rather than a re-derivation of last quarter's sales against today's rules."},"place_of_supply":{"type":"string","description":"The member state of consumption — the country whose rate was applied. Usually the buyer's, but `GB` for a service we perform ourselves, which is supplied where the *supplier* belongs."},"product_line":{"type":"string","description":"The product line this line billed for; empty when it names none."}}},"InvoicePage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"InvoiceStatus":{"type":"string","description":"A billing document's payment state, read off the document itself (docs/34 §4.1). `paid` — money captured; `due` — issued and still owed; `overdue` — past its due date unpaid; `refunded` — the money went back; `credited` — the whole of it has been un-billed by credit notes, and a credit note itself always reads `credited`.\n\n⛔ `canceled` was removed in #710. It was reachable only while this endpoint projected `Order` rows: a canceled order is never invoiced, so no legal document can carry that state. `overdue` and `credited` are the two members that arrived with the real `Invoice` model. Of the five, `due`/`paid`/`credited` are produced today; `overdue` and `refunded` are declared because the column can hold them and this endpoint serves that column — dunning does not yet write either.","enum":["paid","due","overdue","refunded","credited"]},"IpAllowEntry":{"type":"object","description":"One entry in an IP allow-list (#1493). The same shape on all three lists - staff infrastructure, staff site access, and a customer's own - because they share one validator and one reconciler.","required":["id","scope","cidr","label","enabled","expired","in_force","created_by","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"scope":{"type":"string","enum":["staff_infra","staff_site","customer_site"]},"cidr":{"type":"string","description":"Canonical CIDR. A bare address is stored as a host network (`/32`, or `/128` for IPv6) so one column answers both \"is this a range\" and \"does it contain X\".","example":"203.0.113.0/24"},"label":{"type":"string","maxLength":120,"description":"Required. An unlabelled range is one nobody dares remove, which is how a list grows until it stops being a control."},"expires_at":{"type":"string","format":"date-time","nullable":true,"description":"null = permanent. An expired entry is NOT deleted - it stays visible and greyed so an operator can see what lapsed and re-add it."},"enabled":{"type":"boolean"},"expired":{"type":"boolean","description":"Computed server-side. Two surfaces deriving \"is this still in force?\" from a raw timestamp is two implementations of one decision, and they disagree on the boundary second."},"in_force":{"type":"boolean","description":"enabled AND not expired - the only field that decides anything."},"created_by":{"type":"string","description":"Audit ref of whoever added it (`user:<id>` / `apikey:<id>`)."},"created_at":{"type":"string","format":"date-time"}}},"IpAllowEntryWrite":{"type":"object","required":["cidr","label"],"properties":{"cidr":{"type":"string","maxLength":64,"description":"An address or a CIDR range. `0.0.0.0/0` and `::/0` are refused, as is anything broader than /8 (IPv4) or /32 (IPv6). Both families are checked - rejecting only the IPv4 literal is how a list reads as restricted while the whole IPv6 internet is admitted.","example":"203.0.113.7"},"label":{"type":"string","maxLength":120},"expires_at":{"type":"string","format":"date-time","nullable":true},"enabled":{"type":"boolean","default":true}}},"JsonRpcRequest":{"type":"object","description":"A JSON-RPC 2.0 request (or notification, when `id` is omitted).","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"description":"Request id (string or number); omit for a notification.","anyOf":[{"type":"string"},{"type":"integer"}]},"method":{"type":"string","example":"tools/call"},"params":{"type":"object","additionalProperties":true}}},"JsonRpcResponse":{"type":"object","description":"A JSON-RPC 2.0 response — exactly one of `result` or `error`.","required":["jsonrpc","id"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"null"}]},"result":{"type":"object","additionalProperties":true},"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}},"KbArticle":{"type":"object","required":["slug","category","title","summary","body","locale","published_at","updated_at","locales"],"description":"One article as an anonymous reader receives it.","properties":{"slug":{"type":"string","description":"The article's URL segment **in the requested locale** — the translated slug where one has been published, the English slug otherwise (#2595, §2.19). ⛔ Link to this value rather than to the slug you requested: a caller that arrived on a **retired** slug receives the current one here, which is the signal a canonical tag or a 301 is built from."},"category":{"type":"string","description":"The category slug, or empty when the article is uncategorised."},"title":{"type":"string"},"summary":{"type":"string","description":"The meta description, the search snippet and the sentence an AI answer engine is most likely to quote (§2.18)."},"body":{"type":"string","description":"Markdown."},"locale":{"type":"string","description":"⛔ The locale the reader is **actually** getting, decided by whether the copy differs from the English rather than by what was asked for. A payload claiming `es` while carrying English is what makes a dashboard and a visitor disagree."},"published_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time"},"locales":{"type":"object","additionalProperties":{"type":"string"},"description":"This article's URL segment in every locale that has one, English included (`en`). On the detail response only; the list omits it. It is what an article page builds its hreflang alternates from, so a page render does not have to download the whole `/v1/public/kb/slugs` grid (D40432). A locale that is absent has no published segment: use the `en` value."}}},"KbArticlePage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KbArticleSummary"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"KbArticleSummary":{"type":"object","required":["slug","category","title","summary","locale","published_at","updated_at"],"description":"One article **in a list** — every field of `KbArticle` except `body`.\n\n🔴 **The body is omitted deliberately and must not be added back** (D26800). A list of 200 articles carrying full Markdown reached 2,027,887 bytes in Burmese, past the ceiling Next.js puts on a data-cache entry, so the public `/kb` index in five locales was re-fetched and re-rendered on **every request** — uncached for ever, with nothing red anywhere.\n\n⛔ The ceiling is **not** the \"2MB\" the Next.js warning names. Next stores a cached response base64-encoded and then measures the serialized entry, so a payload inflates by 4/3 before it is checked: the real limit on this list is **~1,572,864 bytes**. Read the body from `getPublicKbArticle`, which is the endpoint whose page renders it.","properties":{"slug":{"type":"string","description":"The article's URL segment **in the requested locale**, exactly as `KbArticle.slug`. This is what every link on a list is built from."},"category":{"type":"string","description":"The category slug, or empty when the article is uncategorised."},"title":{"type":"string"},"summary":{"type":"string","description":"The meta description and the search snippet — the sentence a list renders, and the one an AI answer engine is most likely to quote (§2.18)."},"locale":{"type":"string","description":"The locale the reader is **actually** getting, as `KbArticle.locale`."},"published_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time"}}},"KbCategory":{"type":"object","required":["slug","name","description","position"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"position":{"type":"integer","description":"Display order on the public index; lower sorts first."}}},"KbCategoryList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KbCategory"}}}},"KbEntryMapList":{"type":"object","description":"The named articles' title and summary in every locale we serve. The grid a content-map builder joins against, so that `/llms.txt` quotes an article in the reader's language rather than in English.","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["slug","locales"],"properties":{"slug":{"type":"string","description":"The ENGLISH slug, which is the article's identity in every other public payload — join on this, no second lookup needed.","example":"my-site-is-slow"},"locales":{"type":"object","description":"`locale -> {title, summary}`. Every locale we serve is present, filled with the English where there is no up-to-date translation, so a caller never writes the fallback a second time. `body` is deliberately absent — see the endpoint description.","additionalProperties":{"type":"object","required":["title","summary"],"properties":{"title":{"type":"string"},"summary":{"type":"string"}}},"example":{"en":{"title":"My site is slow","summary":"What to check first."},"de":{"title":"Meine Website ist langsam","summary":"Was zuerst zu prüfen ist."}}}}}}}},"KbSlugMapList":{"type":"object","description":"Every published article's URL segment in every locale it has one for. The list a sitemap builder joins against, so that a localized sitemap advertises the URL the page actually canonicals to.","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object","required":["slug","locales"],"properties":{"slug":{"type":"string","description":"The ENGLISH slug, which is the article's identity in every other public payload — join on this, no second lookup needed.","example":"my-site-is-slow"},"locales":{"type":"object","additionalProperties":{"type":"string"},"description":"`locale -> URL segment`. Always contains `en`. A locale absent here has no translated slug published yet, and its page is served at the English one.","example":{"en":"my-site-is-slow","de":"meine-website-ist-langsam"}}}}}}},"LabelValue":{"type":"object","description":"A named free-text pair (a TIN, or one custom invoice reference line). Rendered **verbatim** on the invoice and never interpreted (docs/34 §2.5); length-capped.","required":["label","value"],"properties":{"label":{"type":"string","maxLength":60,"example":"PO number"},"value":{"type":"string","maxLength":200,"example":"PO-2026-0042"}}},"LaunchNetworkCard":{"type":"object","required":["newest","launch_on"],"properties":{"newest":{"type":"array","maxItems":3,"items":{"type":"object","required":["name","tagline","url","logo"],"properties":{"name":{"type":"string","maxLength":80},"tagline":{"type":"string","maxLength":140},"url":{"type":"string","format":"uri","description":"The launch page (https)."},"logo":{"type":"string","description":"An https logo URL","or empty.":null},"went_live_at":{"type":"string","format":"date-time","nullable":true}}}},"launch_on":{"type":"object","required":["domain","name","url","flagship"],"properties":{"domain":{"type":"string","example":"thelaunchdirectory.com"},"name":{"type":"string","example":"The Launch Directory"},"url":{"type":"string","format":"uri"},"flagship":{"type":"boolean"}}}}},"LineKind":{"type":"string","description":"What a cart/order line buys.","enum":["domain_register","domain_transfer","domain_renew","domain_restore","hosting_plan","hosting_addon","privacy_addon","local_presence_addon","marketplace_package","aged_domain","compute_server","managed_database","boards_plan","extra","subscription_extension","subscription_debt","setup_fee"]},"LineTrial":{"type":"object","description":"One hosting product line's card-free trial, as this account sees it. `state`: `available` (never trialled, no plan on it — \"Try it free\"), `active` (running now), `used` (had it: ended, converted, cancelled or switched away from), `subscribed` (the account has a plan on it, so its trial would add nothing).","required":["product_line","template_code","plan_code","duration_days","max_sites","state","trial_id","ends_at"],"properties":{"product_line":{"type":"string"},"template_code":{"type":"string","description":"`TrialTemplate.code` (the `data-zinn-trial-cta` marker)."},"plan_code":{"type":"string","description":"The plan a trial of this line starts on."},"duration_days":{"type":"integer"},"max_sites":{"type":"integer"},"state":{"type":"string","enum":["available","active","used","subscribed"]},"trial_id":{"type":"string","format":"uuid","nullable":true},"ends_at":{"type":"string","format":"date-time","nullable":true},"requires_card":{"type":"boolean","default":false,"description":"⚖️ 2026-10-21 (ZEAB2): this trial starts only with a verified card on file — the card is NOT charged (abuse prevention; Developer Hosting runs arbitrary code). The dashboard shows its card step (`POST /v1/payment-methods`, a SetupIntent) first."}}},"LineTrialList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LineTrial"}}}},"LinkCoverage":{"type":"object","description":"How much of the estate the report is based on. ⛔ Without it a customer cannot tell *\"no outbound links\"* from *\"never scanned\"*, and those lead to opposite actions.","required":["sites_scanned","sites_pending"],"properties":{"sites_scanned":{"type":"integer","minimum":0},"sites_pending":{"type":"integer","minimum":0},"oldest_scan_at":{"type":"string","format":"date-time","nullable":true},"newest_scan_at":{"type":"string","format":"date-time","nullable":true}}},"LinkEdit":{"type":"object","description":"A bulk edit across the customer's network: change where a target's links point, or remove them, everywhere or on chosen sites.\n\n⭐ **Reversible by construction.** Every item stores the exact string it replaced and the exact string it wrote, so `undoLinkEdit` is an ordinary edit with the two the other way round. A \"restore the previous content\" undo would silently discard whatever the customer edited in the meantime, across every site at once.","required":["id","target_host","action","status","expected_links","expected_posts","expected_sites","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"target_id":{"type":"string","format":"uuid","nullable":true},"target_host":{"type":"string","description":"The host as it read when the edit was made. Kept as a string as well as a key, because a rewrite can empty a target of its last link and an audit line reading \"edited (deleted target)\" is not an audit line."},"action":{"type":"string","enum":["rewrite","unlink"]},"new_href":{"type":"string"},"new_text":{"type":"string","description":"New visible text. Empty means *keep whatever each link already says* — which is the common case, because one target's links carry many different anchors and flattening them all to one string is rarely what anybody wants."},"status":{"type":"string","enum":["pending","running","applied","partial","failed"],"description":"`partial` is the honest answer when some sites succeeded and some did not, and it exists because the other two are lies in that case: an operator's next action depends entirely on whether the network is now consistent."},"expected_links":{"type":"integer","minimum":0,"description":"What the operator was told would change, **recorded when they confirmed it** rather than recomputed later. The whole value of a confirmation is that it can be held up against the outcome afterwards."},"expected_posts":{"type":"integer","minimum":0},"expected_sites":{"type":"integer","minimum":0},"undo_of":{"type":"string","format":"uuid","nullable":true,"description":"The edit this one reverses, if any."},"undone_by":{"type":"string","format":"uuid","nullable":true,"description":"The edit that has already reversed this one. Present so the screen offers undo once — two undos of one edit put the original change back."},"created_at":{"type":"string","format":"date-time"},"finished_at":{"type":"string","format":"date-time","nullable":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/LinkEditItem"}}}},"LinkEditItem":{"type":"object","description":"One site's part of a bulk edit, and what actually happened to it.\n\n⭐ `before_html` and `after_html` are on the wire because the operator has to be able to see **exactly** what was written to their site. An edit screen that reports \"197 links changed\" and cannot show you one of them is asking to be trusted rather than checked.","required":["id","site_id","site_domain","before_html","after_html","expected_posts","status"],"properties":{"id":{"type":"string","format":"uuid"},"site_id":{"type":"string","format":"uuid"},"site_domain":{"type":"string"},"before_html":{"type":"string","description":"The exact `<a>` tag that was on the site."},"after_html":{"type":"string","description":"The exact string that replaced it. For an `unlink` this is the tag's **inner HTML** — the image or the bold text stays, only the link goes."},"expected_posts":{"type":"integer","minimum":0,"description":"How many posts our index said carried this link."},"replacements":{"type":"integer","minimum":0,"nullable":true,"description":"How many rows the site itself reported changing. **Null until the item has run** — `0` is a real and different answer, meaning the link was already gone."},"status":{"type":"string","enum":["pending","running","applied","failed","stale","unsupported"],"description":"`stale` — the link was no longer on the site, so nothing was changed; that is not a failure. `unsupported` — this host exposes no managed command (managed hosting), so the edit cannot be applied from here; also not a failure, and per item, because a mixed estate legitimately succeeds on some sites and cannot start on others."},"error":{"type":"string","description":"Operator-facing, and it says what to do next. Never a stack trace."},"applied_at":{"type":"string","format":"date-time","nullable":true}}},"LinkEditPage":{"type":"object","required":["items","total","offset","limit","has_more"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/LinkEdit"}},"total":{"type":"integer","minimum":0},"offset":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1},"has_more":{"type":"boolean"}}},"LinkEditPreview":{"type":"object","description":"The three numbers a confirmation must name before anything is written.\n\nComputed from our own index, never by asking two hundred boxes: the confirmation is in the request path, and a request that fans out to the estate is the synchronous bottleneck CLAUDE.md 2.16 forbids.","required":["links","posts","sites"],"properties":{"links":{"type":"integer","minimum":0},"posts":{"type":"integer","minimum":0},"sites":{"type":"integer","minimum":0}}},"LinkEditRequest":{"type":"object","required":["target_id","action"],"properties":{"target_id":{"type":"string","format":"uuid"},"action":{"type":"string","enum":["rewrite","unlink"]},"href":{"type":"string","description":"Where the links should point, for a `rewrite`. **`http`/`https` or a site-relative path only** — a scheme-relative `//host` form is refused with a message telling the operator to type `https://`, because the check that tells that apart from a path is the same check that gets a `javascript:` variant wrong, and we are writing this into a customer's published pages."},"anchor_text":{"type":"string","description":"New visible text. Omit to keep whatever each link already says."},"site_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Narrow the edit to these sites. **Omit the field entirely to change every site**; an empty array is refused, because it is a UI that failed to send a selection rather than a request to edit the whole network."}}},"LinkPlacement":{"type":"object","description":"One link, in one post, on one site.","required":["id","site_id","site_domain","post_id","wp_post_id","post_title","post_url","href","anchor_text","html","count"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"site_id":{"$ref":"#/components/schemas/Uuid"},"site_domain":{"type":"string"},"post_id":{"$ref":"#/components/schemas/Uuid"},"wp_post_id":{"type":"integer","format":"int64","description":"WordPress's own post id — the join key back to the site."},"post_title":{"type":"string"},"post_url":{"type":"string"},"href":{"type":"string"},"anchor_text":{"type":"string","description":"May be empty. An image link is a real link."},"html":{"type":"string","description":"⭐ The **whole `<a>` tag**. Sent in full because the bulk editor edits it in full — `rel`, `target` and the theme's classes are part of the link, not decoration to be flattened on the next save."},"count":{"type":"integer","minimum":1}}},"LinkPlacementPage":{"type":"object","required":["items","total","offset","limit","has_more"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/LinkPlacement"}},"total":{"type":"integer","minimum":0},"offset":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1},"has_more":{"type":"boolean"}}},"LinkRollup":{"type":"object","description":"Combined totals across **every** target the filters matched — the *\"including variants of it\"* number. Not the sum of the page, so it does not change as you page.","required":["targets","links","posts","sites"],"properties":{"targets":{"type":"integer","minimum":0},"links":{"type":"integer","minimum":0},"posts":{"type":"integer","minimum":0},"sites":{"type":"integer","minimum":0,"description":"⚠️ **Distinct** sites across the match, not a sum of the rows' `site_count`. A sum double-counts the site linking to both `skokka.com` and `blog.skokka.com`, and \"from how many of my sites\" is the number used to judge footprint."}}},"LinkSet":{"type":"object","required":["id","name","notes","is_archived","entries","created_at","updated_at","recipe_count","distribution","distribution_error"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","maxLength":120},"notes":{"type":"string"},"is_archived":{"type":"boolean","description":"An archived set is hidden from the picker and takes no new recipes; the recipes already using it keep working. Archiving is offered where deleting is refused."},"entries":{"type":"array","items":{"$ref":"#/components/schemas/LinkSetEntry"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"recipe_count":{"type":"integer","description":"How many recipes point at this set — so a delete button can say so first."},"distribution":{"type":"array","description":"The resolved share of every (URL, wording) pair, summing to 100 — what will actually happen. Computed by the same function a run uses.","items":{"type":"object","required":["url","text","share"],"properties":{"url":{"type":"string"},"text":{"type":"string"},"share":{"type":"number"}}}},"distribution_error":{"type":"string","description":"Why there is no distribution, or empty. Separate from `distribution` because an empty list also means \"this set has no links\", and one value for two facts is not an answer."}}},"LinkSetEntry":{"type":"object","required":["url","anchor_texts"],"properties":{"id":{"type":"string","format":"uuid","readOnly":true},"url":{"type":"string","maxLength":400,"description":"The destination. Must start with `https://` (or `http://`)."},"anchor_texts":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","maxLength":300},"description":"Every wording you want used for this URL. The destination's share is split evenly between them, so one page linked with four phrasings gets each phrasing a quarter of the time — which is what keeps a network's anchor profile natural."},"weight_percent":{"type":"number","nullable":true,"minimum":0,"maximum":100,"description":"This destination's share of all placements. **`null` means \"you did not say\"**, not zero: leave every share blank and the links rotate evenly; set some and the rest share what is left. Refused when the stated shares add up to more than 100, or reach 100 while other links have none — those links would be stored, listed, and never placed."},"position":{"type":"integer"}}},"LinkSetWrite":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"notes":{"type":"string","maxLength":2000},"is_archived":{"type":"boolean"},"entries":{"type":"array","maxItems":200,"items":{"$ref":"#/components/schemas/LinkSetEntry"}}}},"LinkTarget":{"type":"object","description":"A domain the customer's sites link out to — one row of the report.","required":["id","host","display_host","is_ip","own_site","link_count","post_count","site_count","first_seen_at","last_seen_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"host":{"type":"string","description":"The **normalised** identity: lower-cased, IDNA A-label, no leading `www.`, no trailing dot. Search matches on this, which is why variants cannot split."},"display_host":{"type":"string","description":"The spelling the site actually used. ⛔ Display only — the moment a query touches this the variants split again (D1328)."},"is_ip":{"type":"boolean","description":"A bare IP. Real links, tracked, and never rolled up by search."},"own_site":{"allOf":[{"$ref":"#/components/schemas/LinkTargetSite"}],"nullable":true,"description":"⭐ Non-null when this target is one of the customer's **own** sites. The distinction between *my own network* and *a client's money site* is the reason a PBN operator uses this tool. On the list endpoint the counts inside are `0` — per-site figures come from `getLinkTarget`, because an aggregate per row would be an N+1 over a report with thousands of rows."},"link_count":{"type":"integer","minimum":0,"description":"**Occurrences** — V1's \"Reflinks\". The same anchor three times in one post is three, which is what an operator means by \"how many times am I linking there\"."},"post_count":{"type":"integer","minimum":0},"site_count":{"type":"integer","minimum":0},"first_seen_at":{"type":"string","format":"date-time"},"last_seen_at":{"type":"string","format":"date-time"}}},"LinkTargetDetail":{"type":"object","required":["target","sites"],"properties":{"target":{"$ref":"#/components/schemas/LinkTarget"},"sites":{"type":"array","description":"Which of the customer's own sites link here, biggest first.","items":{"$ref":"#/components/schemas/LinkTargetSite"}}}},"LinkTargetPage":{"type":"object","required":["items","total","offset","limit","has_more","rollup","coverage"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/LinkTarget"}},"total":{"type":"integer","minimum":0},"offset":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1},"has_more":{"type":"boolean"},"rollup":{"$ref":"#/components/schemas/LinkRollup"},"coverage":{"$ref":"#/components/schemas/LinkCoverage"}}},"LinkTargetSite":{"type":"object","description":"One of the customer's own sites, in the context of a target.","required":["site_id","domain","name","links","posts"],"properties":{"site_id":{"$ref":"#/components/schemas/Uuid"},"domain":{"type":"string"},"name":{"type":"string"},"links":{"type":"integer","minimum":0},"posts":{"type":"integer","minimum":0},"scanned_at":{"type":"string","format":"date-time","nullable":true,"description":"When this site last completed a scan. `null` means never."}}},"LiveStream":{"type":"object","required":["id","name","state"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["idle","processing","ready","failed"],"description":"`idle` = the channel is enabled and nothing is arriving; `ready` = bytes are arriving now. ⛔ Not the same question, and rendering the first as the second sends a customer to publish a player at an empty manifest."},"playback_url":{"type":"string","description":"HLS manifest a player points at. Public; safe to render."},"poster_url":{"type":"string"},"recording":{"type":"boolean","description":"Whether the provider is also recording this broadcast to stored video."},"created_at":{"type":"string","format":"date-time","nullable":true}},"description":"⛔⛔ There is **no push-URL field here and there must never be one.** The RTMP/SRT push URL embeds a stream key: whoever holds it can broadcast as the customer."},"LiveStreamList":{"type":"object","required":["streams"],"properties":{"streams":{"type":"array","items":{"$ref":"#/components/schemas/LiveStream"}}}},"LocalAllowance":{"type":"object","required":["cap"],"properties":{"cap":{"type":["integer","null"],"description":"The plan's allowance; `null` means unlimited."},"used":{"type":"integer"},"resets_at":{"type":"string","format":"date-time","description":"For the monthly checks, when the count starts again (UTC)."}}},"LocalBusiness":{"type":"object","required":["cid","name"],"properties":{"cid":{"type":"string","pattern":"^[0-9]{3,40}$","description":"Google's own id for the place — the only handle that tells branches apart."},"name":{"type":"string","maxLength":200},"domain":{"type":"string","maxLength":253},"address":{"type":"string","maxLength":300},"category":{"type":"string","maxLength":120}}},"LocalBusinessRequest":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","maxLength":253,"description":"The business's website."},"label":{"type":"string","maxLength":120}}},"LocalBusinessSummary":{"type":"object","required":["target_id","domain","label","business","places","rows","in_map_pack","in_local_pack","measured"],"properties":{"target_id":{"type":"string","format":"uuid"},"domain":{"type":"string"},"label":{"type":"string"},"business":{"oneOf":[{"$ref":"#/components/schemas/LocalBusiness"},{"type":"null"}]},"places":{"type":"integer"},"rows":{"type":"integer"},"in_map_pack":{"type":"integer","description":"Rows where the business is in the map's top three."},"in_local_pack":{"type":"integer","description":"Rows where it is in the 3-pack on the results page."},"measured":{"type":"integer"}}},"LocalFindRequest":{"type":"object","required":["query","geo_id"],"properties":{"query":{"type":"string","minLength":2,"maxLength":200,"description":"The business's name."},"geo_id":{"type":"integer","minimum":1,"description":"The town to search from."},"language":{"type":"string","maxLength":8}}},"LocalFindResult":{"type":"object","required":["cid","name","domain","address","category","rating","votes","position"],"properties":{"cid":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"address":{"type":"string"},"category":{"type":"string"},"rating":{"type":["number","null"]},"votes":{"type":"integer"},"position":{"type":"integer"}}},"LocalKeyword":{"type":"object","required":["phrase"],"properties":{"phrase":{"type":"string","maxLength":120},"frequency":{"type":"string","enum":["monthly","weekly","daily"],"description":"Omitted means the plan's own cadence."}}},"LocalPlace":{"type":"object","required":["geo_id","name"],"properties":{"geo_id":{"type":"integer","minimum":1},"name":{"type":"string","maxLength":255},"country":{"type":"string","maxLength":4},"language":{"type":"string","maxLength":8,"description":"Results language; default `en`."},"device":{"type":"string","enum":["mobile","desktop"],"description":"Local searches are mostly made on a phone, so `mobile` is the default."}}},"LocalPlaceOption":{"type":"object","required":["geo_id","name","country","kind"],"properties":{"geo_id":{"type":"integer","description":"Google's geotarget id for the place."},"name":{"type":"string","description":"Most specific first, e.g. `Leeds,West Yorkshire,England,United Kingdom`."},"country":{"type":"string"},"kind":{"type":"string","description":"City, Post town, County, Region, Country, …"}}},"LocalRankings":{"type":"object","required":["target_id","domain","label","business","places","keywords","rows","last_checked_at"],"properties":{"target_id":{"type":"string","format":"uuid"},"domain":{"type":"string"},"label":{"type":"string"},"business":{"oneOf":[{"$ref":"#/components/schemas/LocalBusiness"},{"type":"null"}]},"places":{"type":"array","items":{"$ref":"#/components/schemas/LocalPlace"}},"keywords":{"type":"array","items":{"$ref":"#/components/schemas/LocalKeyword"}},"rows":{"type":"array","items":{"$ref":"#/components/schemas/LocalRow"}},"last_checked_at":{"type":["string","null"],"format":"date-time"}}},"LocalRankingsOverview":{"type":"object","required":["entitled","allowances","businesses"],"properties":{"entitled":{"type":"boolean","description":"Whether the org holds Local Rankings."},"allowances":{"type":"object","required":["businesses","places_per_business","keywords","checks","fastest_frequency"],"properties":{"businesses":{"$ref":"#/components/schemas/LocalAllowance"},"places_per_business":{"$ref":"#/components/schemas/LocalAllowance"},"keywords":{"$ref":"#/components/schemas/LocalAllowance"},"checks":{"$ref":"#/components/schemas/LocalAllowance"},"fastest_frequency":{"type":["string","null"],"enum":["monthly","weekly","daily",null]}}},"businesses":{"type":"array","items":{"$ref":"#/components/schemas/LocalBusinessSummary"}}}},"LocalReading":{"type":"object","required":["checked_at","map_position","map_depth","pack_position","organic_position","organic_url","organic_depth","rating","votes"],"properties":{"checked_at":{"type":"string","format":"date-time"},"map_position":{"type":["integer","null"],"description":"Position on Google Maps; `null` = not in the listings read."},"map_depth":{"type":"integer"},"pack_position":{"type":["integer","null"],"description":"Position in the local 3-pack on the results page."},"organic_position":{"type":["integer","null"],"description":"The website's organic position."},"organic_url":{"type":"string"},"organic_depth":{"type":"integer"},"rating":{"type":["number","null"]},"votes":{"type":["integer","null"]}}},"LocalRow":{"type":"object","required":["key","phrase","frequency","place","next_check_at","pending","failed","latest","map_change","organic_change","rivals","trend"],"properties":{"key":{"type":"string"},"phrase":{"type":"string"},"frequency":{"type":"string","enum":["monthly","weekly","daily"]},"place":{"$ref":"#/components/schemas/LocalPlace"},"next_check_at":{"type":["string","null"],"format":"date-time"},"pending":{"type":"boolean"},"failed":{"type":"boolean","description":"The row's last check did not go through; it is retried at `next_check_at`. Cleared by the next successful check."},"latest":{"oneOf":[{"$ref":"#/components/schemas/LocalReading"},{"type":"null"}]},"map_change":{"type":["integer","null"],"description":"Places moved UP the map since the previous reading."},"organic_change":{"type":["integer","null"]},"rivals":{"type":"array","items":{"type":"object","properties":{"position":{"type":"integer"},"name":{"type":"string"},"rating":{"type":["number","null"]},"votes":{"type":["integer","null"]}}}},"trend":{"type":"array","items":{"$ref":"#/components/schemas/LocalReading"}}}},"LocalSetup":{"type":"object","required":["places","keywords"],"properties":{"business":{"$ref":"#/components/schemas/LocalBusiness"},"places":{"type":"array","items":{"$ref":"#/components/schemas/LocalPlace"}},"keywords":{"type":"array","items":{"$ref":"#/components/schemas/LocalKeyword"}}}},"LocaleCode":{"type":"string","description":"BCP-47 / ISO locale code from the language registry (docs/28).","example":"en","maxLength":12},"MailAllowance":{"type":"object","description":"What the governing plan grants for mailboxes. `included: false` is a real answer, not an error — the organization has a plan and the plan does not cover email.","required":["included","box_quota_mb","mailbox_limit","source","offered_providers"],"properties":{"offered_providers":{"type":"array","description":"The providers this organization may set a domain up on, in picker order — **the one producer of the white-label rule** (W40-MAIL). `zinn` is absent, not disabled, for an organization under a `white_label` entitlement or beneath a reseller that holds one: mailboxes on our product carry our hostnames, and the card that names it on a reseller's client panel is itself the leak. The create and switch endpoints refuse from the same function, so the picker and the API cannot disagree.","items":{"$ref":"#/components/schemas/MailProvider"}},"included":{"type":"boolean","description":"Whether the plan includes mailboxes at an operable size."},"box_quota_mb":{"type":"integer","description":"Per-mailbox size in MB. `0` means no per-mailbox cap."},"mailbox_limit":{"type":"integer","description":"Mailboxes allowed per domain; `-1` is uncapped. The **smaller** of the plan's `mailboxes` grant and the platform abuse ceiling: a plan may lower it, and a generous plan can never raise it."},"source":{"type":"string","description":"Where the allowance came from. `domain` means **the domain itself grants it** — it is registered with us or was transferred in, so its mailboxes are free whatever the organization's hosting plan says (owner ruling 2026-08-16). That value can only appear when the request supplied `fqdn`, because it is a fact about one hostname rather than about the organization.\n\n`free` is the **last** answer, reached only when the plan and the domain have both declined: mailboxes on our own relay cost storage rather than a per-seat licence, so they are given rather than sold. It is deliberately last — a free tier that won would silently shrink a large paid mailbox to the free quota, invisibly, because mail would go on working. It appears only where our own relay actually serves the mail; where an upstream platform bills us per account there is nothing free to give, and the organization resolves to no allowance at all.","enum":["staff","subscription","trial","domain","free","none"]}}},"MailClientServer":{"type":"object","description":"One server a mail client connects to.","required":["host","port","security"],"properties":{"host":{"type":"string"},"port":{"type":"integer"},"security":{"type":"string","description":"How the socket is secured. `ssl` wraps the connection in TLS before the greeting (implicit TLS); `starttls` upgrades a plain connection. ⛔ They are not interchangeable: a client told the wrong one hangs rather than reporting an error, which reaches the customer as \"my e-mail does not work\".","enum":["ssl","starttls","none"]}}},"MailConnectionSettings":{"type":"object","description":"The IMAP/SMTP endpoints for a mail client.","required":["imap_host","imap_port","imap_ssl","smtp_host","smtp_port","smtp_starttls"],"properties":{"imap_host":{"type":"string"},"imap_port":{"type":"integer"},"imap_ssl":{"type":"boolean"},"smtp_host":{"type":"string"},"smtp_port":{"type":"integer"},"smtp_starttls":{"type":"boolean"}}},"MailDeliverability":{"type":"object","description":"SPF/DKIM/DMARC as they stand for a domain that already has email (#2138). The three booleans are derived from the same report as `would_delete`, so they cannot disagree with the record list beside them.","required":["domain","healthy","spf_ok","dkim_ok","dmarc_ok","fixable","needs_confirmation","existing_apex_mx","foreign_mx","foreign_spf_includes","would_delete","zone_unreadable","reason","warnings","live_mx","mx_readable","mx_ok","action_needed","required_records"],"properties":{"domain":{"type":"string"},"healthy":{"type":"boolean","description":"All three mechanisms present and ours - nothing to publish."},"spf_ok":{"type":"boolean"},"dkim_ok":{"type":"boolean"},"dmarc_ok":{"type":"boolean"},"fixable":{"type":"boolean","description":"Whether a one-click apply is offered. **False** over a foreign apex MX or an unreadable zone - the panel shows the reason instead of a button."},"needs_confirmation":{"type":"boolean","description":"True when applying would replace published records, so `confirm` is required."},"existing_apex_mx":{"type":"array","items":{"type":"string"}},"foreign_mx":{"type":"array","items":{"type":"string"},"description":"Apex MX targets that are not ours - the reason a fix is refused."},"foreign_spf_includes":{"type":"array","items":{"type":"string"}},"would_delete":{"type":"array","items":{"type":"string"},"description":"Records an apply would remove or replace, as `NAME TYPE VALUE`. Listed verbatim rather than counted: a customer must not be able to destroy mail records without seeing which ones (#663). A published record identical to one the apply would write is not listed - rewriting it with its own value changes nothing."},"zone_unreadable":{"type":"boolean"},"reason":{"type":"string","description":"Customer-grade English. Never a driver message."},"warnings":{"type":"array","items":{"type":"string"}},"live_mx":{"type":"array","items":{"type":"string"},"description":"The domain's MX hosts as PUBLIC DNS answers them right now (W43-09) - not our record of the zone. Empty when the domain publishes no MX, or when it could not be read (see `mx_readable`)."},"mx_readable":{"type":"boolean","description":"False when the public MX lookup failed. A failed lookup is never read as \"action needed\"."},"mx_ok":{"type":"boolean","description":"Every live MX host is one this preset publishes, and there is at least one."},"action_needed":{"type":"boolean","description":"The customer's OWN DNS must change: we cannot publish to this zone and either its live MX does not point where this preset sends mail, or its own nameservers do not answer with the DKIM keys our relay signs with (`dkim_missing`). The panel then lists `required_records` with copy buttons."},"dkim_missing":{"type":"array","items":{"type":"string"},"description":"For a domain whose DNS the customer runs: the DKIM records (`TXT <name>`) its own authoritative nameservers do NOT answer with. Without them mail we send for the domain is unsigned for it and fails DKIM alignment. Empty when all are published or when the nameservers could not be asked."},"required_records":{"type":"array","description":"The exact records to publish, as our preset would write them into a zone we host.","items":{"type":"object","required":["type","name","value","priority"],"properties":{"type":{"type":"string"},"name":{"type":"string"},"value":{"type":"string"},"priority":{"type":"integer","nullable":true}}}}}},"MailDeliverabilityApply":{"type":"object","properties":{"confirm":{"type":"boolean","default":false,"description":"Required when `needs_confirmation` is true. Defaults to false so a destructive apply is never a side effect of clicking \"fix\"."}}},"MailDnsRecordCheck":{"type":"object","description":"One mail DNS record a domain needs and what its own nameservers answer now.","required":["type","host","name","value","priority","purpose","status","found"],"properties":{"type":{"type":"string","description":"MX, TXT, CNAME or SRV."},"host":{"type":"string","description":"The host as a DNS panel asks for it - `@` for the domain itself."},"name":{"type":"string","description":"The full record name."},"value":{"type":"string"},"priority":{"type":"integer","nullable":true},"purpose":{"type":"string","enum":["receive","spf","dkim","dmarc","discovery","security"]},"status":{"type":"string","enum":["ok","missing","different","unknown"]},"found":{"type":"array","items":{"type":"string"},"description":"What the nameservers answered instead, when `status` is `different`."}}},"MailDnsRecords":{"type":"object","description":"Every DNS record one mail domain needs, each checked live.","required":["domain","provider","dns_hosted","nameservers","records","all_ok"],"properties":{"domain":{"type":"string"},"provider":{"type":"string"},"dns_hosted":{"type":"string","enum":["ours","external","unknown"],"description":"`ours`: we publish the records. `external`: add them at your DNS provider."},"nameservers":{"type":"array","items":{"type":"string"}},"records":{"type":"array","items":{"$ref":"#/components/schemas/MailDnsRecordCheck"}},"all_ok":{"type":"boolean","nullable":true,"description":"True when every record is live; null when any could not be checked."}}},"MailDomain":{"type":"object","additionalProperties":false,"required":["fqdn","org_id","sources","site_id","domain_id","mail_service","eligible","ineligible_reason"],"properties":{"fqdn":{"type":"string","description":"The hostname","lowercased.":null},"org_id":{"$ref":"#/components/schemas/Uuid"},"sources":{"type":"array","description":"Why this hostname is listed: `domain` (registered with us, connected or transferring in), `site` (a live site's primary domain), `mail` (it has an email service and neither of the others).","items":{"type":"string","enum":["domain","site","mail"]}},"site_id":{"type":["string","null"],"format":"uuid","description":"The site whose primary domain this is, if any."},"domain_id":{"type":["string","null"],"format":"uuid","description":"The domain record, if the hostname is a domain held with us."},"mail_service":{"oneOf":[{"$ref":"#/components/schemas/MailDomainService"},{"type":"null"}],"description":"The email service on this hostname, or `null` when none is set up."},"eligible":{"type":"boolean","description":"Whether email can be set up on this hostname."},"ineligible_reason":{"type":["string","null"],"enum":["platform_address",null],"description":"Why not, when `eligible` is false. `platform_address`: the hostname is on our own preview or staging domain, which never receives email."}}},"MailDomainList":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MailDomain"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"MailDomainService":{"type":"object","additionalProperties":false,"required":["id","status","provider"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"$ref":"#/components/schemas/MailServiceStatus"},"provider":{"$ref":"#/components/schemas/MailProvider"}}},"MailForwarder":{"type":"object","required":["id","source","targets","kind"],"properties":{"id":{"type":"string","description":"The mail backend's identifier."},"source":{"type":"string","description":"The local part being forwarded for `mailbox`; the domain itself for `catchall`/`wildcard`."},"targets":{"type":"array","items":{"type":"string"},"description":"Where mail goes. May include the backend's reserved drop/reject targets."},"kind":{"$ref":"#/components/schemas/MailForwarderKind"}}},"MailForwarderCreate":{"type":"object","required":["targets"],"properties":{"source":{"type":"string","maxLength":253,"description":"Required for `mailbox`; ignored for `catchall`/`wildcard`. The part before the `@` (`info`), or a full address on this service's own domain (`info@example.com`, taken as `info`). A full address on any other domain is refused `422` naming `source`."},"targets":{"type":"array","minItems":1,"items":{"type":"string","maxLength":320}},"kind":{"$ref":"#/components/schemas/MailForwarderKind"}}},"MailForwarderKind":{"type":"string","description":"`mailbox` forwards one address; `catchall` takes anything not otherwise matched at the domain; `wildcard` forwards the whole domain to another one.","enum":["mailbox","catchall","wildcard"]},"MailForwarderList":{"type":"object","description":"Unpaginated - it reads through to one domain, where the whole list is the answer.","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MailForwarder"}}}},"MailFreeTier":{"type":"object","description":"The free mailbox tier's policy and the arithmetic behind it. Every figure below the first two is **derived** from them and from the measured relay capacity.","required":["available","unavailable_cause","unavailable_reason","relay_zone","reserve_percent","quota_mb","per_org_ceiling","usable_bytes","offerable_bytes","committed_bytes","headroom_bytes","node_monthly_eur","mailboxes_per_node","orgs_per_node","worst_case_cost_per_mailbox_eur"],"properties":{"available":{"type":"boolean","description":"Whether free mailboxes are actually on offer. **Two measured legs, not a switch.** The first is *\"does mail land on our own relay\"* — true exactly when every mail hostname we publish sits under the relay's zone, because a mailbox served by an upstream platform is an account somebody bills us per seat for. The second is *\"is there room for one more\"*.\n\n⛔ The second leg exists because the first alone lets an **operational** action make a **commercial** commitment silently: whoever repoints the MX is thinking about deliverability, not mailbox economics, and would otherwise switch on an unbounded free tier estate-wide as a side effect.\n\n⛔ It gates the OFFER of a new free mailbox and **never an existing one**. Nothing here revokes, shrinks or stops delivering to a mailbox that already exists, and an organization that already holds mail keeps its allowance when the relay fills."},"unavailable_cause":{"type":"string","description":"Which leg refused, so that two situations sharing one symptom stay distinguishable. `relay` means the mail hostnames are not ours — a routing decision. `headroom` means the relay is full — a capacity problem somebody must act on by adding a node or lowering the quota. Empty when free mailboxes are on offer. `relay` is reported first when both fail: there is no point buying storage for a tier the MX will not let you offer.","enum":["relay","headroom",""]},"reserve_percent":{"type":"integer","description":"How much of the relay is held back from the free tier for the mail somebody is paying for. Free and paid mailboxes share one disk, and the failure this prevents is a paying customer's message bouncing off a relay filled by free accounts."},"offerable_bytes":{"type":"integer","format":"int64","description":"Usable storage less the reserve — what the free tier may draw on."},"committed_bytes":{"type":"integer","format":"int64","description":"Storage already promised to mailboxes on the relay — **every** mailbox, not only free ones, because a paid mailbox occupies the same disk."},"headroom_bytes":{"type":"integer","format":"int64","description":"Offerable storage still unpromised. Negative when the relay is oversubscribed."},"unavailable_reason":{"type":"string","description":"Why free mailboxes are not on offer, in a sentence an operator can act on. Empty when `available` is true. Names our own configuration rather than any supplier."},"relay_zone":{"type":"string","description":"The apex of our own mail relay — the name `available` compares against."},"quota_mb":{"type":"integer","description":"Per-mailbox size of a free mailbox, in MB."},"per_org_ceiling":{"type":"integer","description":"How many free mailboxes one organization may hold. A ceiling rather than a target, and the only term a customer can move — which is what stops the offer running away."},"usable_bytes":{"type":"integer","format":"int64","description":"Mail-available storage on one relay node, measured rather than assumed."},"node_monthly_eur":{"type":"integer","description":"What one relay node costs per month."},"mailboxes_per_node":{"type":"integer","description":"How many fully-used free mailboxes one node holds."},"orgs_per_node":{"type":"integer","description":"How many organizations one node holds if every one fills its ceiling."},"worst_case_cost_per_mailbox_eur":{"type":"number","description":"What a free mailbox costs per month, fully used. **Worst case deliberately**: a figure computed from average fill is a claim about customer behaviour dressed as a cost, and it is wrong in the direction that fills a disk."}}},"MailPreflight":{"type":"object","description":"What publishing our mail records into this domain's zone **would** find and remove.\n\nComputed by the same policy function the mutating call and the provisioning workflow use, so a preview and the action it previews cannot disagree. Nothing here names the mail backend: `reason` is authored copy, and the record strings are the customer's own zone contents.","required":["domain","safe","existing_apex_mx","foreign_mx","foreign_spf_includes","would_delete","zone_unreadable","reason","reason_code","warnings"],"properties":{"domain":{"type":"string","description":"The domain that was checked, normalised."},"safe":{"type":"boolean","description":"Whether an apply would proceed without the override flag. `false` means `POST /v1/mail/services` returns 409 unless the customer confirms."},"existing_apex_mx":{"type":"array","description":"Every apex `MX` currently published, in the order DNS returned them.","items":{"type":"string"}},"foreign_mx":{"type":"array","description":"The apex `MX` targets that are not ours to replace — the reason for a refusal, and the list the customer must see before confirming an override.","items":{"type":"string"}},"foreign_spf_includes":{"type":"array","description":"`include:` mechanisms in the current SPF that the new record would drop.","items":{"type":"string"}},"would_delete":{"type":"array","description":"Records the apply would remove or replace, as `\"NAME TYPE VALUE\"`.","items":{"type":"string"}},"zone_unreadable":{"type":"boolean","description":"The zone could not be read at all — never `safe`. Distinct from \"read it, found nothing\", because the two need different copy: one is \"we cannot see your DNS\", the other is \"your domain has no email today\"."},"reason":{"type":"string","description":"Customer-grade English describing what was found. English only: a client shows its own translated copy for `reason_code` and keeps this for logs and support."},"reason_code":{"type":"string","enum":["ready","already_ours","foreign_mx","zone_unreadable","no_nameservers"],"description":"What was found, as a stable code the client translates (MAILUX, §2.19): `ready` (no mail anywhere else, safe), `already_ours` (already points here, safe), `foreign_mx` (live mail elsewhere would be replaced), `zone_unreadable` (the zone could not be read), `no_nameservers` (the domain has no public nameservers, so it receives no mail and cannot be set up yet)."},"warnings":{"type":"array","description":"Non-blocking observations about the zone.","items":{"type":"string"}}}},"MailProvider":{"type":"string","description":"Which provider serves a domain's mail. `custom` is **the reseller's own provider** (W40-MAIL, owner ruling 2026-09-06): a white-label reseller sells mail they buy elsewhere, declares its MX / SPF / DKIM / autodiscover / client hostnames in `MailProviderConfig`, and we publish exactly that. Nothing is defaulted for it.","enum":["zinn","google_workspace","microsoft_365","custom"]},"MailProviderConfig":{"type":"object","description":"What a `custom` provider publishes — the reseller's own values. Every hostname is validated as a bare hostname (no scheme, port or path) and lowercased. `mx_hosts` is the one required input; the rest publish a record only when given. **A config that names one of Zinn®'s own mail hostnames is refused**: \"your own provider\" that resolves to us is our own product with the white-label leak put back.","properties":{"mx_hosts":{"type":"array","maxItems":10,"description":"MX targets in priority order (10, 20, 30…). At least one.","items":{"type":"string","maxLength":253}},"spf_include":{"type":"string","maxLength":253,"description":"The provider's SPF `include:` domain. Publishes `v=spf1 include:<value> ~all`; empty publishes no SPF — a guessed sender list is worse than none."},"dkim_selector":{"type":"string","maxLength":63,"description":"The DKIM selector (the label before `._domainkey`). Required with a key."},"dkim_txt_value":{"type":"string","maxLength":4096,"description":"The DKIM public-key TXT value. Mutually exclusive with `dkim_cname_target`."},"dkim_cname_target":{"type":"string","maxLength":253,"description":"A DKIM selector delegated by CNAME. Mutually exclusive with `dkim_txt_value`."},"autodiscover_host":{"type":"string","maxLength":253,"description":"The `autodiscover` CNAME target. Empty publishes none."},"imap_host":{"type":"string","maxLength":253,"description":"What a mail client connects to. Both client hosts or neither."},"smtp_host":{"type":"string","maxLength":253},"imap_port":{"type":"integer","minimum":1,"maximum":65535,"description":"`993` when omitted."},"smtp_port":{"type":"integer","minimum":1,"maximum":65535,"description":"`587` when omitted."},"webmail_url":{"type":"string","format":"uri","maxLength":2048,"description":"The provider's webmail, linked verbatim from the panel. Never a Zinn® host."},"dmarc_policy":{"type":"string","enum":["none","quarantine","reject"],"description":"`none` when omitted."},"dmarc_rua":{"type":"string","format":"email","description":"The DMARC aggregate-report mailbox. Defaults to `postmaster@<domain>`."}}},"MailProviderSwitch":{"type":"object","additionalProperties":false,"required":["provider"],"properties":{"provider":{"$ref":"#/components/schemas/MailProvider","description":"The provider to move this domain's email to."},"provider_config":{"oneOf":[{"$ref":"#/components/schemas/MailProviderConfig"},{"type":"null"}],"description":"Required in effect when `provider` is `custom` (an empty MX list is refused); ignored otherwise. A `custom` → `custom` call with **different** values is a re-declaration — the corrected records are published — rather than the no-op."},"confirm_fqdn":{"type":"string","maxLength":253,"description":"The domain, typed back by the customer. **Required when the switch destroys mailboxes we host** — i.e. when moving away from `zinn` on a domain that has any — and ignored otherwise.\n\n⛔ Deliberately not a boolean \"I am sure\": a checkbox is answered by muscle memory, and this is the one irreversible action on the mail surface. Equally deliberately **not** demanded when nothing of ours is destroyed, because friction that protects nothing is friction people learn to type through."}}},"MailRelayEventBatch":{"type":"object","required":["events"],"properties":{"events":{"type":"array","items":{"type":"object","required":["type","createdAt","data"],"properties":{"id":{"type":"string"},"type":{"type":"string","example":"delivery.dsn-perm-fail"},"createdAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true}}}}}},"MailRelayEventResult":{"type":"object","required":["received","counted","ignored","unknown_senders","suspended"],"properties":{"received":{"type":"integer"},"counted":{"type":"integer"},"ignored":{"type":"integer"},"unknown_senders":{"type":"integer"},"suspended":{"type":"integer"}}},"MailResponder":{"type":"object","description":"An auto-reply on one mailbox.","required":["id","local","address","subject","content","start_time","end_time"],"properties":{"id":{"type":"string","description":"The mail backend's identifier - the handle `DELETE` needs."},"local":{"type":"string","description":"The part before the `@`."},"address":{"type":"string","description":"The mailbox this replies for."},"subject":{"type":"string"},"content":{"type":"string","description":"The reply body."},"start_time":{"type":"string","nullable":true,"format":"date-time","description":"When the auto-reply starts. `null` when unscheduled (it replies from now on).\n\n⭐ This used to be declared **\"Opaque - do not parse, compare or render as a date\"** (#664), out of a sound fear that a backend's internal format would leak into this contract. The remedy was backwards: it did not keep the vendor's format out, it put the vendor's format in and forbade anyone from reading it — which is why the scheduling feature was parked for a wave as unbuildable (D9246), a date picker being impossible against a field nobody was allowed to interpret. The format was never mysterious, only unmeasured. It is RFC 3339, the seam lives in the driver where every other vendor difference lives, and a future replacement mail backend cannot change what this schema says."},"end_time":{"type":"string","nullable":true,"format":"date-time","description":"When the auto-reply stops. `null` to run until switched off."}}},"MailResponderCreate":{"type":"object","required":["local","content"],"properties":{"local":{"type":"string","maxLength":64,"description":"The mailbox to auto-reply for."},"subject":{"type":"string","maxLength":255},"content":{"type":"string","maxLength":4000},"start_time":{"type":"string","nullable":true,"format":"date-time","description":"RFC 3339. Omit or `null` for no schedule - see `MailResponder`."},"end_time":{"type":"string","nullable":true,"format":"date-time","description":"RFC 3339, and must be after `start_time` when both are given."}}},"MailResponderList":{"type":"object","description":"Unpaginated on purpose: this reads through to the backend for a single domain, where the whole list is one small response and there is no cursor to page from.","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MailResponder"}}}},"MailResponderUpdate":{"type":"object","description":"⛔ **No `local` on this body** — an auto-reply belongs to a mailbox, so the address is which mailbox you are editing, not a field of the reply.\n\n⭐ It previously read *\"the mail backend has no rename verb\"*, which was false. Change an address with `renameMailbox`; add a forwarder to give a mailbox a second one.","required":["content"],"properties":{"subject":{"type":"string","maxLength":255},"content":{"type":"string","maxLength":4000},"start_time":{"type":"string","nullable":true,"format":"date-time","description":"RFC 3339. `null` clears the schedule."},"end_time":{"type":"string","nullable":true,"format":"date-time","description":"RFC 3339, and must be after `start_time` when both are given."}}},"MailRouting":{"type":"object","description":"How one domain's mail is served. **Derived, never chosen by a customer**: it is a function of the customer's own mail connection, the plan's mailbox allowance and the zone's live DNS delegation, all three of which move — so it is recomputed on every convergence pass rather than read back.","required":["fqdn","mechanism","mechanism_label","forwards","stores","status","dns_authority","catch_all"],"properties":{"fqdn":{"type":"string","description":"The domain this routing is for."},"mechanism":{"type":"string","description":"Which mechanism serves this domain's inbound mail. `zinn_mailbox` stores it; `zinn_forward` and `cloudflare_routing` pass it on and store nothing; `external` means the customer's own provider; `none` is a deliberate choice, not an absence.","enum":["zinn_mailbox","zinn_forward","cloudflare_routing","external","none"]},"mechanism_label":{"type":"string","description":"Why this mechanism was chosen, in a sentence a person can act on."},"forwards":{"type":"boolean","description":"Whether mail is passed on rather than stored."},"stores":{"type":"boolean","description":"Whether this domain has real mailboxes on our relay."},"status":{"type":"string","description":"The last convergence pass's outcome. `held` is distinct from `failed` and means the zone could not be read, so nothing was changed — which is correct behaviour, not a fault. `refused` means the domain is not ours to change — we hold no zone for it, or its mail already arrives through another provider — so nothing was changed on purpose. Only `failed` is a fault.","enum":["pending","converged","held","refused","failed"]},"dns_authority":{"type":"string","description":"Whose nameservers the zone was delegated to when last measured. `unknown` means the lookup did not answer — never that it is delegated elsewhere.","enum":["cloudflare","other","unknown"]},"catch_all":{"type":"string","description":"Where mail to any address on this domain is delivered. Empty when no forwarding alias exists — a domain with no deliverable destination gets **no** alias rather than one pointing nowhere, because an alias that forwards to nothing is a black hole that looks configured."},"catch_all_state":{"type":"string","description":"Whether that catch-all is actually in force, measured by reading it back from the mail server on every convergence pass. `live` is the only working value; `not_live` means it was applied and the server does not return it (an operator is alerted); `pending` means not applied yet; `vendor` means the DNS provider's own forwarding serves it; `disabled` means it is switched off. Empty when there is no catch-all.","enum":["","pending","live","not_live","vendor","disabled"]},"catch_all_checked_at":{"type":"string","format":"date-time","nullable":true,"description":"When the catch-all was last read back from the mail server."},"last_converged_at":{"type":"string","format":"date-time","nullable":true,"description":"When the world last agreed with the intended state."}}},"MailRoutingList":{"type":"object","description":"Every domain's mail routing, for one organization.","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MailRouting"}}}},"MailService":{"type":"object","description":"A domain's email service. Backend account references are deliberately absent from this schema: our mailboxes run on a swappable provider whose name never reaches a customer surface (CLAUDE.md §2.6).","required":["id","fqdn","status","provider","mailbox_quota_mb","mailbox_limit","mailboxes_used","created_at","mailbox_provisioning","mail_only"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"fqdn":{"type":"string","description":"The domain the mailboxes are on."},"provider_config":{"oneOf":[{"$ref":"#/components/schemas/MailProviderConfig"},{"type":"null"}],"description":"The `custom` provider's declared values, served back so the domain screen can show and edit what was declared. `null` on every other provider, whose values are documented and derived rather than stored."},"site":{"oneOf":[{"$ref":"#/components/schemas/MailServiceSite"},{"type":"null"}],"description":"The site currently serving this domain, or `null` when no site does. **Derived from the hostname, never stored**: mail attaches to a domain and a domain outlives the site on it, so a stored site id would go stale the day a domain moved between sites — and nothing would notice, because mail would keep working. `null` is a normal state (a BYO hostname, or mail kept after its site was deleted), not an error."},"mailbox_provisioning":{"$ref":"#/components/schemas/MailboxProvisioning"},"mail_only":{"type":"boolean","description":"**This domain uses us for mail and nothing else** — an active mail service on a hostname no website of ours serves.\n\nPublished as one server-side answer because more than one consumer needs it and each deriving it separately would drift: malware scanning must exclude these (there is no filesystem to scan, so a verdict would be fabricated), and the site panel must not offer hosting controls for something we do not host.\n\n⛔ It is **not** simply \"`site` is null\". A site on the `mail` product line is a bookkeeping row rather than a website — that line grants `max_sites: 0` — and is still `mail_only: true`. Deriving it from a null `site` looks correct today and stops being correct the moment anything creates such a row."},"domain_id":{"oneOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}],"description":"The registered domain this serves, when we hold the registration."},"status":{"$ref":"#/components/schemas/MailServiceStatus"},"provider":{"$ref":"#/components/schemas/MailProvider"},"mailbox_quota_mb":{"type":"integer","description":"Size of each mailbox in MB, captured when the service was created."},"mailbox_limit":{"type":"integer","description":"Mailboxes allowed on this domain; `-1` is uncapped. Captured when the service was created; a later downgrade is enforced against the live plan as well, so the number actually applied is the smaller of the two."},"mailboxes_used":{"type":"integer","description":"How many mailboxes currently consume the allowance."},"dns_applied_at":{"type":["string","null"],"format":"date-time","description":"When the mail DNS was last published. `null` means never — mailboxes that exist but receive nothing, which is the one state a customer must be told about."},"awaiting_delegation":{"type":"boolean","description":"`true` when the service's mail records are STAGED in our zone and the domain is still delegated elsewhere (a domain moving to us before its nameserver change): mailboxes, forwarders and the catch-all work, but no mail arrives until the domain points at our nameservers. Goes `false` when the records are confirmed live (`dns_applied_at` set). `docs/1104` §7."},"created_at":{"type":"string","format":"date-time"}}},"MailServiceCreate":{"type":"object","required":["fqdn"],"properties":{"org_id":{"$ref":"#/components/schemas/Uuid"},"fqdn":{"type":"string","maxLength":253,"description":"The domain to set email up on."},"domain_id":{"oneOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]},"provider":{"allOf":[{"$ref":"#/components/schemas/MailProvider"}],"description":"Who runs the mailboxes for this domain. Defaults to `zinn` — our own email.\n\n`google_workspace` and `microsoft_365` publish that provider's own MX, SPF, DKIM and autodiscover records; we run no mailboxes for them and bill for none. `custom` publishes whatever `provider_config` declares (W40-MAIL).\n\n⛔ `zinn` is refused with `422` for an organization whose `offered_providers` (see `MailAllowance`) omit it — a white-label account. The refusal names no hostname and says what to choose instead.\n\n⚠️ This has been in the spec and accepted by the engine since the mail surface shipped. It was the **dashboard** that never sent it (`useCreateMailService` posted `{ fqdn }` alone), so every domain was set up on our own mail whatever the customer wanted. Recorded because this lane's own triage first blamed the spec — wrongly, from a `grep` whose context window stopped two lines short."},"provider_config":{"oneOf":[{"$ref":"#/components/schemas/MailProviderConfig"},{"type":"null"}],"description":"The `custom` provider's values. Required in effect for `custom`; ignored otherwise."}}},"MailServiceList":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MailService"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"MailServiceSite":{"type":"object","description":"The site serving a mail service's domain. Placement details (which fleet worker, which machine) are deliberately absent: they name our own infrastructure and answer no question a customer has.","required":["id","name","status","product_line"],"properties":{"id":{"type":"string","description":"The site's id."},"name":{"type":"string","description":"The site's name","falling back to its domain.":null},"status":{"type":"string","description":"The site's lifecycle state."},"product_line":{"type":"string","description":"The product line the site is on — what decides `mailbox_provisioning`."}}},"MailServiceStatus":{"type":"string","description":"A mail service's lifecycle state.","enum":["pending","provisioning","active","failed","suspended","deleting","deleted"]},"Mailbox":{"type":"object","description":"One mailbox. Never carries a password — see `MailboxCreated`.","required":["id","address","local","quota_mb","used_mb","percent_used","send_enabled","receive_enabled","status","system_managed","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"address":{"type":"string","description":"The full address."},"local":{"type":"string","description":"The part before the `@`."},"quota_mb":{"type":"integer","description":"This mailbox's size in MB. `0` means no cap."},"used_mb":{"type":"integer","description":"How much of it is used, as the mail backend last reported it (#932). Refreshed by the hourly reconcile, so it is a recent figure rather than a live one."},"percent_used":{"type":"integer","description":"How full, 0-100. Always `0` for an uncapped mailbox — a percentage of \"no limit\" is meaningless, not zero-ish. Read `usage_checked_at` before showing it: this is also `0` for a mailbox that has never been measured, and rendering \"0% full\" for \"not measured yet\" would be a confident lie."},"usage_checked_at":{"type":"string","format":"date-time","nullable":true,"description":"When the backend was last asked. `null` until the first sweep sees it."},"send_enabled":{"type":"boolean"},"send_suspended_at":{"type":"string","format":"date-time","nullable":true,"description":"When we paused this mailbox's sending because most of its recent mail was permanently refused (W43-72). null = not paused."},"send_suspended_reason":{"type":"string","description":"The counts that decided the pause, in plain words. Empty when not paused."},"receive_enabled":{"type":"boolean"},"status":{"$ref":"#/components/schemas/MailboxStatus"},"system_managed":{"type":"boolean","description":"**We** created this mailbox when the domain was provisioned; the customer did not ask for it. It is the address the site itself sends from, so `deleteMailbox` and `renameMailbox` refuse it with a `422` — and **nothing else about it is restricted**. Its owner opens webmail, resets its password, resizes it and sets an auto-reply exactly like any other mailbox.\n\nA client should hide those two actions on a `system_managed` mailbox rather than offer them and report the refusal, and should explain why the mailbox is there."},"credential_changed_at":{"type":["string","null"],"format":"date-time","description":"When the mailbox's password was last set through us — chosen or generated in the dashboard, or changed from webmail. Never the password itself. `null` = not changed since this was recorded."},"recovery_email":{"type":"string","description":"The opt-in recovery address a forgotten password can be reset through (empty when none). Set with `setMailboxRecovery`."},"recovery_verified":{"type":"boolean","description":"Whether the recovery address has opened its verification link."},"self_reset_available":{"type":"boolean","description":"Whether forgotten-password self-reset is switched on for this deployment. While it is off, `setMailboxRecovery` answers `422`."},"migration_access_until":{"type":["string","null"],"format":"date-time","description":"A move may copy mail INTO this mailbox until then (an import credential our team issued); `null` when there is none. Never who, never the credential."},"created_at":{"type":"string","format":"date-time"}}},"MailboxClientSetup":{"type":"object","description":"Everything needed to add one mailbox to a mail app.","required":["address","domain","provider","username","auth","incoming","outgoing","apple_profile_available","autodiscover_available"],"properties":{"address":{"type":"string","description":"The mailbox address."},"domain":{"type":"string"},"provider":{"$ref":"#/components/schemas/MailProvider"},"username":{"type":"string","description":"What to type in the username field — the **full address**, on both the incoming and the outgoing server."},"auth":{"type":"string","description":"How the customer proves who they are. `password` means the mailbox's own password, sent inside the TLS session `security` establishes.","enum":["password"]},"incoming":{"$ref":"#/components/schemas/MailClientServer"},"outgoing":{"$ref":"#/components/schemas/MailClientServer"},"apple_profile_available":{"type":"boolean","description":"Whether `/v1/mail/mailboxes/{mailboxId}/apple-profile` will serve a profile for this mailbox."},"autodiscover_available":{"type":"boolean","description":"Whether Outlook and Thunderbird can configure themselves from the address alone for this domain."}}},"MailboxCreate":{"type":"object","required":["local"],"properties":{"local":{"type":"string","maxLength":64,"description":"The part before the `@`."},"send":{"type":"boolean","default":true},"receive":{"type":"boolean","default":true},"password":{"type":"string","minLength":12,"maxLength":128,"writeOnly":true,"description":"Optional. The password the person chose. Checked before the mailbox is created (12–128 characters, must not contain the address or domain name, must not appear in a known data breach); a refused one is a `422` and creates nothing. Never echoed back. Omitted → a strong password is generated and returned once."}}},"MailboxCreated":{"type":"object","description":"A just-created or just-reset mailbox **and its one-time password**. The only schema in this API that carries a mailbox password: it is never stored and cannot be read back, so this response is the single moment it exists outside the mail system.","required":["mailbox","password"],"properties":{"mailbox":{"$ref":"#/components/schemas/Mailbox"},"password":{"type":["string","null"],"description":"The password, shown once. `null` when the person chose it (`chosen: true` — a password somebody typed is never sent back), or when the backend reconciled to a mailbox that already existed and refused to rotate a live password."},"chosen":{"type":"boolean","default":false,"description":"`true` when the password set is the one sent in the request."}}},"MailboxList":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Mailbox"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"MailboxPasswordSet":{"type":"object","description":"Body for `resetMailboxPassword`. Empty → a strong password is generated and returned once. `password` given → that password is set after the same checks as `MailboxCreate`, and is never echoed back.","properties":{"password":{"type":"string","minLength":12,"maxLength":128,"writeOnly":true}}},"MailboxProvisioning":{"type":"string","enum":["managed","self_service"],"description":"Whether **we** pre-create a starter mailbox on this domain. `managed` — we make one when the domain is provisioned (the Footprint-Free/PBN line and our own fleet); `self_service` — we make nothing and the customer creates their own.\n\n⚖️ **Since the owner's ruling of 2026-08-16 this does NOT restrict the customer.** On every line the customer creates, renames and deletes their own mailboxes up to `mailbox_limit`. The field is published so a client can explain a mailbox nobody asked for. The one address that cannot be deleted or renamed is identified per mailbox by `Mailbox.system_managed`, not by this value.\n\n⛔ It previously meant \"the customer may neither add nor remove any\", which is what `managed` reads like and is no longer true. A client still branching on it to hide the add button is showing a restriction that no longer exists."},"MailboxRecovery":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","maxLength":254,"description":"The recovery address. Must not be the mailbox itself."}}},"MailboxRename":{"type":"object","description":"The new local part for `renameMailbox`. Deliberately a body of its own rather than a field on `MailboxUpdate` — a rename moves where mail is delivered and a resize does not, and one body for both would make them indistinguishable in the audit log.","required":["local"],"properties":{"local":{"type":"string","maxLength":64,"description":"The new part before the `@`. Lower-cased and trimmed by the engine."}}},"MailboxStatus":{"type":"string","description":"One mailbox's state.","enum":["pending","active","failed","deleting"]},"MailboxUpdate":{"type":"object","description":"A partial change to a mailbox. At least one field must be present — an empty body is a 422 rather than a silent no-op, so a client bug is visible instead of looking like a successful save.","minProperties":1,"properties":{"quota_mb":{"type":"integer","minimum":1,"description":"New mailbox size in MB. Capped by the plan allowance captured on the service, and above that by the backend package ceiling."},"send":{"type":"boolean","description":"Whether the mailbox may send."},"receive":{"type":"boolean","description":"Whether the mailbox may receive."}}},"MalwareCleanRun":{"type":"object","description":"One malware clean (or restore) of one site. Counts plus the docroot-relative paths in `detail` (`cleaned`, `quarantined` as `[path, kept_at]` pairs, `failed`, `restored`).","required":["id","trigger","outcome","found","cleaned","quarantined","failed","restored","detail","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"trigger":{"type":"string","enum":["auto","customer","staff"]},"outcome":{"type":"string","enum":["cleaned","partial","failed","nothing","restored"],"description":"`cleaned` everything found was cleaned or quarantined; `partial` some was; `failed` nothing could be (a person must look); `nothing` nothing to clean; `restored` a file was put back."},"found":{"type":"integer","minimum":0},"cleaned":{"type":"integer","minimum":0},"quarantined":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"restored":{"type":"integer","minimum":0},"detail":{"type":"object","additionalProperties":true},"created_at":{"type":"string","format":"date-time"}}},"MalwareDetection":{"type":"object","description":"One live malware finding on a site.","required":["path","signature","detected_at"],"properties":{"path":{"type":"string","description":"Path **relative to the site's document root** — never absolute, which would disclose the host account handle and the fleet's filesystem layout (§2.4)."},"signature":{"type":"string","description":"The scanner's detection name (a vendor identifier, shown verbatim — not English prose, so it is not a translatable string)."},"detected_at":{"type":"string","format":"date-time"},"restored_at":{"type":["string","null"],"format":"date-time","description":"Set when the customer or staff put this file back (`restoreSiteSecurityDetection`) — it is still reported, but automatic cleaning leaves it alone; only an explicit *Clean now* touches it again."}}},"MalwareStatus":{"type":"string","enum":["clean","infected","scanning"],"description":"A site's scan verdict. There is deliberately **no** `unscanned` member: a site nothing has looked at yet is `clean` with `last_scan_at: null`, which is one nullable timestamp rather than a second way to say the same thing. Adding a member here is a breaking change for both consoles, which enumerate it."},"ManagedCareConnection":{"type":"object","description":"SERVERCARE-r2 — is the machine connected, what is pending, what was patched when. Never carries installer output or the token.","required":["state","patch_runs"],"additionalProperties":false,"properties":{"state":{"type":"string","enum":["not_connected","connecting","connected","failed","removed"]},"reason":{"type":"string","description":"A refusal-style code when `state` is `failed`."},"connected_at":{"type":"string","format":"date-time","nullable":true},"last_report_at":{"type":"string","format":"date-time","nullable":true},"os_name":{"type":"string"},"kernel":{"type":"string"},"pending_updates":{"type":"integer"},"pending_security":{"type":"integer"},"reboot_required":{"type":"boolean"},"last_patched_at":{"type":"string","format":"date-time","nullable":true},"patch_runs":{"type":"array","items":{"$ref":"#/components/schemas/ManagedCarePatchRun"}}}},"ManagedCarePatchRun":{"type":"object","required":["patched_at","package_count","packages"],"additionalProperties":false,"properties":{"patched_at":{"type":"string","format":"date-time"},"package_count":{"type":"integer"},"packages":{"type":"string","description":"The packages that run changed","newline-separated.":null}}},"ManagedCareState":{"type":"object","description":"SERVERCARE-r1 — a machine's care lane, its mode and the add-on as offered.","required":["management_mode","care","connection","offer"],"additionalProperties":false,"properties":{"management_mode":{"type":"string","enum":["self_managed","zinn_managed","zinn_managed_paused"]},"care":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ComputeAddOnAssignment"}]},"connection":{"$ref":"#/components/schemas/ManagedCareConnection"},"offer":{"type":"object","required":["code","price_minor","currency","orderable"],"additionalProperties":false,"properties":{"code":{"type":"string"},"price_minor":{"type":"integer","nullable":true,"description":"Live price in minor units; null when not sold in this currency."},"currency":{"type":"string"},"orderable":{"type":"boolean"}}}}},"ManagedDatabase":{"type":"object","description":"One standalone managed database. ⛔ Carries no password — the credential is fetched from `POST /v1/databases/{databaseId}/credentials` and is never a field here.","required":["id","label","engine","engine_version","size","status","port","database_name","username","high_availability","tls_required","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"label":{"type":"string","maxLength":64,"description":"The customer's own name for it. Never sent to the infrastructure."},"engine":{"type":"string","enum":["postgres","mysql"],"description":"Which engine this database runs (`docs/497`). Modelled as a field from the start, which is why MySQL was additive rather than a migration of every row."},"engine_version":{"type":"string","maxLength":8,"description":"The engine's **major** — `\"18\"`, `\"8.4\"`. The patch level is ours to keep current and is deliberately not customer-selectable: choosing your own patch level means choosing to run an unpatched database."},"engine_label":{"type":"string","description":"The engine and version as a customer sees them — \"PostgreSQL 18\", \"MySQL 8.4\". Assembled by the API so three frontends cannot disagree about a product name."},"size":{"type":"string","description":"A code from `GET /v1/databases/catalogue`."},"status":{"type":"string","enum":["provisioning","available","failed","suspended","deleting","deleted"]},"status_detail":{"type":"string","description":"Why a `failed` instance failed. Empty otherwise."},"host":{"type":"string","description":"Empty until the instance is `available`."},"port":{"type":"integer"},"database_name":{"type":"string"},"username":{"type":"string"},"high_availability":{"type":"boolean","description":"Whether a standby replica is held with automatic failover. **The property customers actually choose on** — stated rather than inferred from the size, because an inference goes wrong the first time the ladder changes."},"vcpu":{"type":"integer","nullable":true},"ram_gb":{"type":"integer","nullable":true},"storage_gb":{"type":"integer","nullable":true},"tls_required":{"type":"boolean","description":"Always true. TLS is a precondition of selling a publicly reachable database, not a feature that can be turned off."},"created_at":{"type":"string","format":"date-time"},"last_backup_at":{"type":"string","format":"date-time","nullable":true,"description":"When a backup last **completed**. `null` means none has ever run."},"order_line_id":{"type":["string","null"],"format":"uuid","description":"The paid basket line this database fulfils, or `null` for one that predates the purchase path or that staff tooling created. The subscription that bills it carries the same id."},"billing":{"$ref":"#/components/schemas/ManagedDatabaseBilling"},"restore_verified_at":{"type":"string","format":"date-time","nullable":true,"description":"When a backup of this database was last proved restorable **by restoring it and reading a row back over a client connection**. ⛔ Deliberately separate from `last_backup_at`: a backup job's success line proves bytes were written, not that they can be read back. `null` means we have never proved it, and is shown as such rather than hidden — a green \"backed up nightly\" that hides an untested chain is selling reassurance."}}},"ManagedDatabaseAllowedIp":{"type":"object","required":["id","cidr","description"],"properties":{"id":{"type":"string","format":"uuid"},"cidr":{"type":"string","example":"203.0.113.0/24"},"description":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"ManagedDatabaseAllowedIpCreate":{"type":"object","required":["cidr","description"],"properties":{"cidr":{"type":"string","description":"An address or CIDR range. A bare address is normalised to `/32` or `/128`."},"description":{"type":"string","maxLength":200,"description":"Required. An allow-list nobody can explain is one nobody dares prune later."},"acknowledge_public":{"type":"boolean","default":false,"description":"Required to add `0.0.0.0/0`. Opening a database to the whole internet is allowed but must never happen by pasting a value somebody half understood."}}},"ManagedDatabaseAllowedIpList":{"type":"object","required":["allowed_ips"],"properties":{"allowed_ips":{"type":"array","items":{"$ref":"#/components/schemas/ManagedDatabaseAllowedIp"}}}},"ManagedDatabaseBilling":{"type":["object","null"],"description":"The subscription paying for this database — what it costs, and when it next renews.\n\n⛔ `null` means **no subscription pays for it**, which is a real state (a row created before databases were buyable, or by staff tooling) and is shown as such rather than rendered as a price of zero.","required":["subscription_id","status","amount_minor","currency","interval"],"properties":{"subscription_id":{"type":"string","format":"uuid"},"status":{"type":"string","description":"`active`, `past_due`, `canceled`, …"},"amount_minor":{"type":"integer","description":"The recurring charge in integer minor units (§2.8 — money is never a float)."},"currency":{"type":"string","example":"USD"},"interval":{"type":"string","description":"The cadence it recurs on. Managed databases are sold monthly."},"current_period_end":{"type":"string","format":"date-time","nullable":true,"description":"When the current period ends, i.e. when it next renews."}}},"ManagedDatabaseCatalogue":{"type":"object","description":"What may be bought right now, **per engine**. `engines` is the field to read; `sizes`, `engine_versions` and `default_engine_version` describe the default engine only and are retained so a browser holding a cached bundle keeps working across the release that added MySQL.","required":["engines","default_engine","sizes","engine_versions","default_engine_version"],"properties":{"engines":{"type":"array","items":{"$ref":"#/components/schemas/ManagedDatabaseEngineOffer"}},"default_engine":{"type":"string","enum":["postgres","mysql"]},"sizes":{"deprecated":true,"type":"array","description":"The default engine's ladder. Use `engines[].sizes`.","items":{"$ref":"#/components/schemas/ManagedDatabaseSize"}},"engine_versions":{"deprecated":true,"type":"array","description":"The default engine's versions. Use `engines[].versions`.","items":{"$ref":"#/components/schemas/ManagedDatabaseEngineVersion"}},"default_engine_version":{"type":"integer","deprecated":true}}},"ManagedDatabaseClientAddress":{"type":"object","additionalProperties":false,"required":["address","family"],"properties":{"address":{"type":["string","null"],"description":"The caller's public IP address, or null when it cannot be resolved."},"family":{"type":["string","null"],"enum":["ipv4","ipv6",null]}}},"ManagedDatabaseCreate":{"type":"object","required":["label","size"],"properties":{"label":{"type":"string","maxLength":64},"size":{"type":"string","description":"A size code from `GET /v1/databases/catalogue`."},"engine":{"type":"string","enum":["postgres","mysql"],"description":"Optional. Omitted uses PostgreSQL. ⛔ Must match the engine the `size` code belongs to — a MySQL request carrying a `db_pg_*` size is refused, because it would run one engine and bill the other."},"engine_version":{"type":"string","maxLength":8,"description":"Optional engine version — `\"18\"`, `\"8.4\"`. Omitted uses the newest we offer for the chosen engine. ⛔ A version too close to end of life is refused **by name** rather than silently substituted: a customer who asked for one thing and received another finds out when their application breaks."}}},"ManagedDatabaseCredentials":{"type":"object","description":"⛔ The only response on this surface containing a secret. Returned by a POST so it cannot land in browser history or proxy logs, and audit-logged on every call.","required":["username","password","host","port","database_name","engine","dsn"],"properties":{"username":{"type":"string"},"password":{"type":"string"},"host":{"type":"string"},"port":{"type":"integer"},"database_name":{"type":"string"},"engine":{"type":"string","enum":["postgres","mysql"]},"dsn":{"type":"string","description":"A ready-to-use connection string **for this database's engine** — `postgresql://…?sslmode=verify-full` or `mysql://…?ssl-mode=VERIFY_IDENTITY`. Both spellings authenticate the server; the `require`/`REQUIRED` forms merely encrypt and are deliberately not used."}}},"ManagedDatabaseEngineOffer":{"type":"object","description":"One engine and everything on sale for it. ⛔ Sizes are **per engine** and are not interchangeable: a highly-available MySQL runs three members and two router pods where the PostgreSQL row of the same shape runs two pods, so the two ladders are the same capacity at different prices.","required":["engine","label","default_port","sizes","versions","default_version"],"properties":{"engine":{"type":"string","enum":["postgres","mysql"]},"label":{"type":"string","description":"PostgreSQL / MySQL, as a customer sees it."},"default_port":{"type":"integer"},"sizes":{"type":"array","items":{"$ref":"#/components/schemas/ManagedDatabaseSize"}},"versions":{"type":"array","items":{"$ref":"#/components/schemas/ManagedDatabaseOfferedVersion"}},"default_version":{"type":"string","description":"The version a customer gets if they express no preference. ⛔ Never a version offered only under a carve-out — see `past_upstream_eol`."}}},"ManagedDatabaseEngineVersion":{"type":"object","required":["major","label","end_of_life"],"properties":{"major":{"type":"integer"},"label":{"type":"string","example":"PostgreSQL 18"},"end_of_life":{"type":"string","format":"date","description":"When upstream stops patching this major. Published so a customer can see what they are choosing rather than discovering it later."}}},"ManagedDatabaseList":{"type":"object","required":["databases"],"properties":{"databases":{"type":"array","items":{"$ref":"#/components/schemas/ManagedDatabase"}}}},"ManagedDatabaseOfferedVersion":{"type":"object","required":["major","label","end_of_life","past_upstream_eol"],"properties":{"major":{"type":"string","description":"The engine's own version string — `\"18\"` for PostgreSQL, `\"8.4\"` for MySQL. Text, because MySQL's majors are dotted pairs whose two halves both carry meaning."},"label":{"type":"string"},"end_of_life":{"type":"string","format":"date"},"past_upstream_eol":{"type":"boolean","description":"True when upstream has already stopped patching this version and it is offered under a recorded carve-out (MySQL 8.0 today). ⛔ Surfaced rather than hidden: a customer choosing it is choosing a risk, and it is theirs to carry."}}},"ManagedDatabaseSize":{"type":"object","required":["code","name","vcpu","ram_gb","storage_gb","high_availability","price_minor","currency"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"vcpu":{"type":"integer"},"ram_gb":{"type":"integer"},"storage_gb":{"type":"integer"},"high_availability":{"type":"boolean"},"price_minor":{"type":"integer","description":"Monthly price in integer minor units (§2.8 — money is never a float)."},"currency":{"type":"string","example":"USD"}}},"ManagedDatabaseUpgrade":{"type":"object","required":["engine_version"],"properties":{"engine_version":{"type":"string","maxLength":8,"description":"The engine major to move to. Must be one this platform offers for the database's own engine, and newer than its current one. ⛔ Compared as version numbers, not as text: `\"9.7\" <= \"10.0\"` is true as a string, so a text comparison would refuse a legitimate upgrade as a downgrade."}}},"ManagedMigrationRequest":{"type":"object","additionalProperties":false,"description":"⛔ Carries **no credentials, by design**. A staff-run migration collects them out of band, from a human who can verify who they are talking to; accepting them here would put a stranger's root password into a purchase record that outlives the job.","properties":{"source_host":{"type":"string","maxLength":253,"description":"Where the site is hosted today, so the fulfilment queue is actionable without a round trip. A hostname, never a login. Optional."},"note":{"type":"string","maxLength":2000,"description":"Anything else staff should know before they start."},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"The currency the customer was quoted in. Validated and refused if no gateway can charge it — this is a charge, and silently substituting the base currency would bill a different number from the one they agreed to."}}},"MarketplaceBillingMode":{"type":"string","description":"How an offer is charged (docs/82 §2a). A property of the OFFER, chosen by the seller from what the listing type permits — a $200 one-off audit and $150/month of link building sit side by side on one Zinn®. Some types genuinely cannot recur (a domain sale), which is why the type holds the permitted set.","enum":["one_time","subscription"]},"MarketplaceCategoryNode":{"type":"object","required":["path","key","name","depth","parent_path","listing_count"],"properties":{"path":{"type":"string","description":"Materialised path, e.g. `web_design/landing_pages`."},"key":{"type":"string"},"name":{"type":"string","description":"Translated into the requested locale."},"depth":{"type":"integer","minimum":0},"parent_path":{"type":"string","nullable":true},"listing_count":{"type":"integer","minimum":1,"description":"Live listings in this category and every category under it."}}},"MarketplaceCategoryTree":{"type":"object","required":["vertical","categories"],"properties":{"vertical":{"type":"string"},"categories":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceCategoryNode"}}}},"MarketplaceContactDecision":{"type":"object","required":["action","confidence"],"properties":{"action":{"type":"string","description":"The rung the ladder chose. There is no rung that refuses to send — the hardest action is holding for review, and at high confidence the action is on the ACCOUNT rather than on the sentence.","enum":["allow","nudge","flag","mask","hold"]},"confidence":{"type":"integer","minimum":0,"maximum":100},"kinds":{"type":"array","description":"What was detected, which is what makes the false-positive rate actionable.","items":{"type":"string"}},"nudge":{"type":"string","description":"A message KEY for the inline warning, or empty. Never a sentence."}}},"MarketplaceConversation":{"type":"object","required":["id","context","is_buyer","unread"],"properties":{"id":{"type":"string","format":"uuid"},"context":{"type":"string","description":"Three contexts, one system. The context decides how hard the contact policy leans: hardest on `presales`, where nothing is paid and there is nothing to lose by leaving.","enum":["presales","direct","order"]},"subject":{"type":"string"},"sale_id":{"type":"string","format":"uuid","nullable":true},"listing_id":{"type":"string","format":"uuid","nullable":true},"is_buyer":{"type":"boolean"},"unread":{"type":"integer"},"last_message_at":{"type":"string","format":"date-time","nullable":true}}},"MarketplaceConversationList":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceConversation"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"MarketplaceDataRoomDocument":{"type":"object","description":"s1014 L69 (docs/1068 §7) — one data-room document. `title` is the seller's words (Class B), `filename` Class A. `state`, `review_reason` and `reviewed_at` are shown to the seller and staff only.","required":["id","title","filename","content_type","size_bytes","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"filename":{"type":"string"},"content_type":{"type":"string","enum":["application/pdf","image/png","image/jpeg","text/csv"]},"size_bytes":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["pending","approved","rejected"]},"review_reason":{"type":"string"},"reviewed_at":{"type":["string","null"],"format":"date-time"},"reviewed_by":{"type":"string","description":"Staff only."},"listing_id":{"type":"string","format":"uuid","description":"Staff only."},"org_id":{"type":"string","format":"uuid","description":"Staff only — the seller org."}}},"MarketplaceDealDeskNotice":{"type":"object","description":"s1014 L69 (docs/1068 §9d, owner Q17) — which of these negotiations our deal desk is helping with, free. Only THAT it is assisted; stage, notes and assignee are staff-only. Empty while the deal-desk switch is off for these organisations.","required":["assisted_thread_ids","from_usd_minor"],"properties":{"assisted_thread_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"from_usd_minor":{"type":"integer","description":"The threshold in US cents."}}},"MarketplaceDealOffer":{"type":"object","description":"s1014 L69 (docs/1068 §8, Q13) — one offer or counter-offer in a buyer org's negotiation. `amount_minor` is integer minor units of `currency` (the listing's own; never converted). `terms` is the maker's words (Class B). `state` reads `expired` as soon as `expires_at` passes, even before the expiry timer relabels the row. `can` lists what the reader may do now. Nothing here moves money.","required":["id","thread_id","parent_id","buyer_org_id","made_by_side","amount_minor","currency","terms","state","expires_at","decided_at","created_at","can","loi_available"],"properties":{"id":{"type":"string","format":"uuid"},"thread_id":{"type":"string","format":"uuid"},"parent_id":{"type":["string","null"],"format":"uuid"},"buyer_org_id":{"type":"string","format":"uuid"},"buyer_org_name":{"type":"string","description":"Seller's view only."},"made_by_side":{"type":"string","enum":["buyer","seller"]},"amount_minor":{"type":"integer","minimum":1},"currency":{"type":"string","minLength":3,"maxLength":3},"terms":{"type":"string","maxLength":4000},"state":{"type":"string","enum":["open","countered","accepted","declined","withdrawn","expired"]},"expires_at":{"type":"string","format":"date-time"},"decided_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"can":{"type":"array","items":{"type":"string","enum":["counter","accept","decline","withdraw"]}},"loi_available":{"type":"boolean"}}},"MarketplaceDocumentExpiryBasis":{"type":"string","description":"Why a document stops being valid — docs/82 §7a's two deliberately different rules. `document_date` is a photo ID expiring on its own printed date, read off it by a reviewer. `fixed_window` is a proof of address refreshed 12 months from acceptance regardless of what the document says, because it is evidence of *current* residence and its age is the only thing that matters. Both write one `valid_until`, so the payout gate compares one date.","enum":["","document_date","fixed_window"]},"MarketplaceDocumentKind":{"type":"string","description":"What a stored object is evidence of. `photo_id` covers passport, national identity card, driving licence and residence permit — there is no country list, and a student, workplace or library card is not government-issued and is not accepted.","enum":["photo_id","proof_of_address","certificate_of_incorporation","proof_of_registered_address","payout_destination_proof"]},"MarketplaceDocumentState":{"type":"string","enum":["uploaded","accepted","rejected","superseded"]},"MarketplaceDocumentUpload":{"type":"object","required":["document","upload"],"properties":{"document":{"$ref":"#/components/schemas/MarketplaceVerificationDocument"},"upload":{"$ref":"#/components/schemas/MarketplaceDocumentUploadGrant"}}},"MarketplaceDocumentUploadGrant":{"type":"object","description":"A presigned upload. The `headers` are part of the grant, not decoration — a signature computed over `content-type` fails with a 403 if the uploader omits it.","required":["url","method","headers","expires_at"],"properties":{"url":{"type":"string"},"method":{"type":"string","example":"PUT"},"headers":{"type":"object","additionalProperties":{"type":"string"}},"expires_at":{"type":"string","format":"date-time"}}},"MarketplaceDocumentUploadRequest":{"type":"object","required":["kind","filename","content_type","size_bytes"],"properties":{"kind":{"$ref":"#/components/schemas/MarketplaceDocumentKind"},"subject_id":{"type":"string","format":"uuid","description":"Required for `photo_id` and `proof_of_address` — a personal document with no person satisfies nobody's requirement while looking uploaded on every screen."},"filename":{"type":"string","maxLength":255},"content_type":{"type":"string","description":"JPEG, PNG or PDF. An allow-list, not a deny-list.","enum":["image/jpeg","image/png","application/pdf"]},"size_bytes":{"type":"integer","minimum":1,"maximum":10485760}}},"MarketplaceDocumentUrl":{"type":"object","required":["url","method","expires_at"],"properties":{"url":{"type":"string","description":"Carries its own signature and is therefore a credential until it expires. Never log it, never store it."},"method":{"type":"string","example":"GET"},"expires_at":{"type":"string","format":"date-time"}}},"MarketplaceFacet":{"type":"object","required":["key","label","kind","unit","declared","of"],"properties":{"key":{"type":"string"},"label":{"type":"string"},"kind":{"$ref":"#/components/schemas/MarketplaceFieldKind"},"unit":{"type":"string"},"measured":{"type":"boolean","description":"s1006 (Q59). True when Zinn® measures this field (Trust Flow, Domain Rating, the Majestic topic) and the seller cannot set it."},"declared":{"type":"integer","description":"How many listings in scope actually carry a value for this field."},"of":{"type":"integer","description":"How many listings are in scope at all. ⛔ Rendered WITH `declared` or not at all — \"482\" alone reads as a result count; \"482 of 1,930\" is the only form that tells a buyer what the filter cannot see."},"min":{"type":"string","nullable":true},"max":{"type":"string","nullable":true},"options":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceFacetOption"}}}},"MarketplaceFacetOption":{"type":"object","required":["value","label","count","selected"],"properties":{"value":{"type":"string"},"label":{"type":"string"},"count":{"type":"integer","description":"How many results carry this value. For a group the buyer has already filtered on, counted with that group's OWN predicate removed — otherwise every value they did not tick reads (0) and the filter becomes a dead end."},"selected":{"type":"boolean"}}},"MarketplaceFaq":{"type":"object","required":["question","answer"],"properties":{"question":{"type":"string","maxLength":300},"answer":{"type":"string","maxLength":3000}}},"MarketplaceFieldDefinition":{"type":"object","required":["key","kind","label"],"properties":{"key":{"type":"string","maxLength":40,"pattern":"^[a-z][a-z0-9_]*$","description":"Permanent. It is the stable half of the translation reference, the key every listing's values are addressed by, and what a facet query names — renaming it orphans all three silently. Capped at 40 characters so a legal key can never produce a translation reference the i18n tables cannot store."},"kind":{"$ref":"#/components/schemas/MarketplaceFieldKind"},"label":{"type":"string","maxLength":120},"help":{"type":"string","maxLength":400},"unit":{"type":"string","maxLength":16,"description":"Rendered after the value — `DA`, `/mo`, `words`."},"required":{"type":"boolean"},"facet":{"type":"boolean","description":"Whether buyers can filter on it. Only numeric, money, yes/no and choice fields may. Free text and links have one value per listing, so a filter built on them offers every listing its own option and matches nothing else. A per-package field and a private field are both refused too — the first has no single value to match on, the second would be published by its own filter list."},"public":{"type":"boolean","description":"Defaults true, except for `domain`, `url` and `file`, which default **closed** — docs/83 §3's whole argument is that the domain is what the buyer is paying to learn."},"per_package":{"type":"boolean"},"material":{"type":"boolean","description":"Whether editing this field on a LIVE listing sends it back for review (docs/78 §4.3). ⛔ Defaults **true**, and the direction is the security property: if the default were \"cosmetic\", the evasion writes itself — submit a clean listing, get it approved, then edit the description to whatever the content policy would have refused. Marking a field cosmetic is an explicit act by the operator who added it."},"deprecated":{"type":"boolean","description":"Hidden on the authoring form, still rendered on listings that already carry it. This is what replaces deleting a field."},"min":{"type":"string","nullable":true},"max":{"type":"string","nullable":true},"options":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceFieldOption"}}}},"MarketplaceFieldKind":{"type":"string","description":"What a field holds, and therefore how every surface treats it.\n\n⛔ Adding a member is a spec change, not a local one: the public renderer switches over this union with `assertNever`, so a new kind the frontend has no control for fails the `typescript` job rather than rendering a blank box. That is the intended cost.","enum":["text","textarea","integer","decimal","money","boolean","select","multiselect","date","url","domain","file"]},"MarketplaceFieldOption":{"type":"object","description":"One choice. `value` is the option's permanent identity and the stable half of its translation reference; `label` is what changes and what gets translated.","required":["value","label"],"properties":{"value":{"type":"string","maxLength":40,"pattern":"^[a-z][a-z0-9_]*$"},"label":{"type":"string","maxLength":120}}},"MarketplaceFreelancer":{"type":"object","description":"s1006 (Q60). A freelancer's public card.","required":["slug","display_name","headline","bio","skills","project_types","languages","rate_minor","rate_currency","rate_unit","portfolio"],"properties":{"slug":{"type":"string"},"display_name":{"type":"string"},"country":{"type":"string"},"headline":{"type":"string"},"bio":{"type":"string"},"skills":{"type":"array","items":{"type":"string"}},"project_types":{"type":"array","items":{"type":"string"}},"languages":{"type":"array","items":{"type":"string"}},"rate_minor":{"type":"integer","format":"int64","nullable":true},"rate_currency":{"type":"string"},"rate_unit":{"type":"string","enum":["hour","day","project"]},"portfolio":{"type":"array","items":{"$ref":"#/components/schemas/MarketplacePortfolioItem"}}}},"MarketplaceHandoverAction":{"type":"object","required":["action"],"properties":{"action":{"type":"string","description":"`transferred` is the seller's only action; `confirm` and `flag` are the buyer's. Enforced server-side — a seller marking an item received on the buyer's behalf would be a seller releasing their own money.","enum":["transferred","confirm","flag"]},"note":{"type":"string","description":"The seller's evidence, the buyer's note, or — on `flag` — the required reason.","maxLength":2000}}},"MarketplaceHandoverItem":{"type":"object","required":["id","label","required","state"],"properties":{"id":{"type":"string","format":"uuid"},"label":{"type":"string"},"detail":{"type":"string"},"required":{"type":"boolean","description":"Release gates on the REQUIRED items only. An optional extra a buyer never confirms must not be able to strand a seller's money."},"state":{"type":"string","description":"`transferred` is the seller's claim and is not delivery; only `confirmed` — the buyer's act — counts toward release.","enum":["pending","transferred","confirmed","flagged"]},"seller_note":{"type":"string","description":"The seller's evidence — an auth code reference, a screenshot, a note."},"buyer_note":{"type":"string"},"flagged_reason":{"type":"string"},"transferred_at":{"type":"string","format":"date-time","nullable":true},"confirmed_at":{"type":"string","format":"date-time","nullable":true},"zinn_asset":{"type":"string","description":"`site`, `domain` or `registrant` for a row the platform ticks when the asset has moved (docs/714 §3) — a seller cannot mark those transferred, and the buyer cannot confirm `registrant` until the domain's registrant record is theirs.","enum":["","site","domain","registrant"]},"zinn_refusal":{"type":"object","description":"Why the platform could not move the asset yet, as codes the screen renders in the reader's language — `code` (`ZONE_COLLISION`, `TRANSFER_REFUSED`, `NOT_SELLERS`, `GONE`, `FAILED`) and `blockers`, the site-transfer guard's own codes. Empty once the move has happened.","properties":{"code":{"type":"string"},"blockers":{"type":"array","items":{"type":"string"}}}}}},"MarketplaceHandoverResult":{"type":"object","required":["item","confirmed","required","order_accepted","state"],"properties":{"item":{"$ref":"#/components/schemas/MarketplaceHandoverItem"},"confirmed":{"type":"integer"},"required":{"type":"integer"},"order_accepted":{"type":"boolean","description":"True when this tick was the last required one and the money has been released. Reported because the buyer's last tick is the most consequential moment of the order and a screen that did not say so would make it the quietest."},"state":{"type":"string"}}},"MarketplaceHubCard":{"type":"object","required":["vertical_key","slug","title","price_minor","currency","published_at"],"properties":{"images":{"type":"array","maxItems":1,"description":"The listing's cover picture (s1014 J39), as a one-item list, or `[]` when it has none. Cover only: a card shows one image.","items":{"$ref":"#/components/schemas/MarketplaceImage"}},"vertical_key":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"summary":{"type":"string"},"vendor_display_name":{"type":"string","description":"Always \"Zinn Digital®\" (merchant of record). The vendor's own name is never sent on a public or buyer-facing marketplace payload (owner, s1014 MKTPLACE-r1, 2026-10-31)."},"first_party":{"type":"boolean","description":"Always true: Zinn Digital® is merchant of record on every marketplace sale, so a storefront shows no \"by …\" byline on any listing (owner, s1014 MKTPLACE-r1, 2026-10-31; supersedes the 2026-10-29 third-party carve-out)."},"domain_masked":{"type":"string","description":"`site****.com`. The real value is not in the table this reads."},"price_minor":{"type":"integer","format":"int64"},"price_max_minor":{"type":"integer","format":"int64"},"currency":{"type":"string"},"rating_score":{"type":"integer"},"review_count":{"type":"integer"},"sales_count":{"type":"integer"},"delivery_days_min":{"type":"integer"},"category_path":{"type":"string"},"published_at":{"type":"string","format":"date-time"}}},"MarketplaceHubVertical":{"type":"object","required":["key","slug","name","storefront_layout","listing_count"],"properties":{"key":{"type":"string"},"slug":{"type":"string","description":"The URL segment — `link-building`, never the key's `link_building`. ⛔ A search engine treats an underscore as a word JOINER and a hyphen as a separator, so serving the key would make `link_building` a single token on exactly the pages that carry the search volume. Served rather than derived on the client so a future per-locale slug changes every link with no frontend release; the underscored spelling still resolves and redirects here."},"name":{"type":"string","description":"Translated into the requested locale."},"tagline":{"type":"string"},"storefront_layout":{"$ref":"#/components/schemas/MarketplaceStorefrontLayout"},"listing_count":{"type":"integer","description":"Live listings. ⛔ Deliberately NOT accompanied by a \"from $X\": listings in one vertical are priced in whatever currency their Zinner® chose, so a minimum across them compares 900 JPY with 900 GBP and prints the smaller number."},"images":{"type":"array","maxItems":1,"description":"The storefront card's picture (s1014 J39): the cover of this vertical's newest listing that has one, or `[]` for an empty vertical. A real listing picture, never stock art.","items":{"$ref":"#/components/schemas/MarketplaceImage"}}}},"MarketplaceImage":{"type":"object","required":["id","width","height","is_cover","position"],"properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","nullable":true,"description":"The original. ⛔ `null` when no public delivery origin is configured, rather than a guessed URL — an R2 bucket is not public by default, and a card with a broken image is worse than a card with none."},"srcset":{"type":"string","description":"Width candidates through Cloudflare image resizing with `format=auto`, so a phone downloads a phone-sized AVIF/WebP and an old browser still gets something it can decode. Empty when no delivery origin is configured."},"width":{"type":"integer","description":"Pixel width AFTER orientation is applied. Required in the markup to reserve space — an `<img>` without it is the largest single source of layout shift."},"height":{"type":"integer","description":"Pixel height after orientation is applied."},"alt":{"type":"string"},"is_cover":{"type":"boolean"},"position":{"type":"integer"}}},"MarketplaceImageList":{"type":"object","required":["images","policy"],"properties":{"images":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceImage"}},"policy":{"$ref":"#/components/schemas/MarketplaceImagePolicy"}}},"MarketplaceImagePolicy":{"type":"object","description":"The effective limits — the listing type's, merged over the platform defaults.","required":["max_count","min_width","min_height","max_bytes","aspect_ratios"],"properties":{"max_count":{"type":"integer"},"min_width":{"type":"integer"},"min_height":{"type":"integer"},"max_bytes":{"type":"integer"},"aspect_ratios":{"type":"array","items":{"type":"string"},"description":"e.g. [\"16:9\", \"4:3\"]. Empty means any shape."}}},"MarketplaceImageUpdate":{"type":"object","properties":{"alt":{"type":"string","maxLength":300},"position":{"type":"integer","minimum":0,"maximum":999},"is_cover":{"type":"boolean","description":"Only `true` is meaningful — a listing always has exactly one cover."}}},"MarketplaceInclusionItem":{"type":"object","required":["label","required"],"properties":{"label":{"type":"string"},"detail":{"type":"string"},"required":{"type":"boolean"},"zinn_asset":{"type":"string","description":"`\"\"` for a row the seller wrote; `site`, `domain` or `registrant` for a row the platform adds and ticks itself. Clients render those three in the reader's language by this key.","enum":["","site","domain","registrant"]},"source_locale":{"type":"string","description":"On the public listing only: the language the seller wrote this row in when it has been translated for the reader, else empty."}}},"MarketplaceLatestCard":{"allOf":[{"$ref":"#/components/schemas/MarketplaceHubCard"},{"type":"object","required":["vertical_slug","taxonomy"],"properties":{"vertical_slug":{"type":"string","description":"The vertical's URL segment in the requested locale."},"taxonomy":{"type":"object","description":"The listing's taxonomy values (option KEYS, not labels) for the keys it declares: `platform`, `site_type`, `store_type`, `niche` (strings) and `monetization` (array). A key the listing does not declare is absent.","properties":{"platform":{"type":"string"},"site_type":{"type":"string"},"store_type":{"type":"string"},"niche":{"type":"string"},"monetization":{"type":"array","items":{"type":"string"}}}}}}]},"MarketplaceLatestFeed":{"type":"object","required":["data","total","locale","verticals"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceLatestCard"}},"total":{"type":"integer","description":"Live listings across the served verticals, not only the returned page."},"locale":{"type":"string"},"verticals":{"type":"array","items":{"type":"string"},"description":"The vertical keys actually served, after unknown and archived ones were dropped."},"categories":{"type":"array","items":{"type":"string"},"description":"The `category` allow-list clauses applied (`<vertical>:<path>`, sorted), so a reader can tell a filtered feed from an engine that ignored the parameter (s1006). Empty when none were asked for."}}},"MarketplaceLedger":{"type":"object","required":["data","page","balance"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceLedgerEntry"}},"page":{"$ref":"#/components/schemas/PageMeta"},"balance":{"$ref":"#/components/schemas/MarketplaceLedgerBalance"}}},"MarketplaceLedgerBalance":{"type":"object","description":"Computed by the database over EVERY entry, never summed from the page above it — a paginated list summed in a client is wrong from the second page onward, and wrong about the vendor's own money.","required":["pending_minor","released_minor","paid_minor"],"properties":{"pending_minor":{"type":"integer","format":"int64","description":"Held — the buyer has not accepted yet."},"released_minor":{"type":"integer","format":"int64","description":"Accepted and payable — what the next weekly payout run will pay."},"paid_minor":{"type":"integer","format":"int64"}}},"MarketplaceLedgerEntry":{"type":"object","description":"One append-only line of the engine-side ledger (docs/82 §1, §7). There is no escrow party: Zinn® is merchant of record, buys from the vendor NET and self-bills, so a payable is an unpaid SUPPLIER balance and not money held on someone's behalf.","required":["id","entry_type","state","amount_minor","currency","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"entry_type":{"type":"string","enum":["vendor_payable","payout","reversal","adjustment"]},"state":{"type":"string","description":"`pending` IS the buyer-protection promise, expressed as a row state — a payable the buyer has not accepted is invisible to every payout run.","enum":["pending","released","paid","reversed"]},"amount_minor":{"type":"integer","format":"int64","description":"Signed. Positive is owed TO the party, negative is paid away from them, so summing a party's rows is their balance with no per-type sign table to get wrong."},"currency":{"$ref":"#/components/schemas/CurrencyCode"},"note":{"type":"string"},"sale_id":{"anyOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]},"released_at":{"type":["string","null"],"format":"date-time"},"settled_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"MarketplaceListing":{"type":"object","required":["id","vendor_id","marketplace_id","marketplace_key","listing_type_id","listing_type_key","schema_version","title","slug","summary","field_values","state","price_minor","price_max_minor","currency","packages"],"properties":{"id":{"type":"string","format":"uuid"},"vendor_id":{"type":"string","format":"uuid"},"marketplace_id":{"type":"string","format":"uuid"},"marketplace_key":{"type":"string"},"category_id":{"type":"string","format":"uuid","nullable":true},"listing_type_id":{"type":"string","format":"uuid"},"listing_type_key":{"type":"string"},"schema_version":{"type":"integer","description":"The version this listing's values were authored against. Stamped once, never moved — a later schema must not reinterpret an older listing."},"title":{"type":"string","maxLength":180},"slug":{"type":"string","description":"Permanent once live. It is the public URL."},"summary":{"type":"string"},"field_values":{"type":"object","additionalProperties":true,"description":"\"`{key: {v, ver}}`\" — uniform two keys, `ver: null` for a seller-declared value, so no consumer branches on key presence. ⛔ A `domain` value is NOT here — it is in the reveal table."},"field_schema":{"type":"array","description":"Present on the detail read; the schema THIS listing is authored against.","items":{"$ref":"#/components/schemas/MarketplaceFieldDefinition"}},"state":{"$ref":"#/components/schemas/MarketplaceListingState"},"price_minor":{"type":"integer","format":"int64"},"price_max_minor":{"type":"integer","format":"int64"},"currency":{"type":"string","minLength":3,"maxLength":3},"published_at":{"type":"string","format":"date-time","nullable":true},"packages":{"type":"array","items":{"$ref":"#/components/schemas/MarketplacePackage"}},"inclusion_items":{"description":"What comes with the asset, as the seller composed it. Rows carrying `zinn_asset` were added by the platform because the listing sells a site or domain hosted with us (docs/714 §3); a seller cannot remove, rename or reorder them.","type":"array","items":{"$ref":"#/components/schemas/MarketplaceInclusionItem"}},"inclusion_revision":{"type":"integer","description":"How many times the seller has revised the list since publishing."},"description":{"type":"string","description":"s1006 — the long description, PLAIN TEXT: paragraphs separated by a blank line, list lines starting `- `. Never HTML; it is rendered as text."},"faqs":{"type":"array","description":"The listing's FAQ, shown on the page and as `FAQPage` structured data.","items":{"$ref":"#/components/schemas/MarketplaceFaq"}},"zinn_site_id":{"type":"string","format":"uuid","nullable":true,"description":"The site on our hosting this listing sells, set by `listListingFromSite` only. When the listing sells, the site moves into the buyer's account automatically."},"zinn_domain_id":{"type":"string","format":"uuid","nullable":true,"description":"The domain in our account this listing sells, set by `listListingFromDomain` only."}}},"MarketplaceListingCreate":{"type":"object","required":["listing_type_id","title"],"properties":{"listing_type_id":{"type":"string","format":"uuid"},"category_id":{"type":"string","format":"uuid","nullable":true},"title":{"type":"string","maxLength":180},"summary":{"type":"string"}}},"MarketplaceListingDealRoom":{"type":"object","description":"s1014 L69 (docs/1068 §6) — the seller's deal-room choice for one listing.","required":["available","policy","signatures"],"properties":{"available":{"type":"boolean"},"policy":{"type":"object","required":["nda_required","hide_identity"],"properties":{"nda_required":{"type":"boolean"},"hide_identity":{"type":"boolean"}}},"signatures":{"type":"array","items":{"type":"object","required":["buyer_org_id","buyer_org_name","signer_name","locale","template_version","signed_at"],"properties":{"buyer_org_id":{"type":"string","format":"uuid"},"buyer_org_name":{"type":"string"},"signer_name":{"type":"string"},"locale":{"type":"string"},"template_version":{"type":"integer"},"signed_at":{"type":"string","format":"date-time"}}}}}},"MarketplaceListingList":{"type":"object","required":["data","total"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceListing"}},"total":{"type":"integer"}}},"MarketplaceListingMultiple":{"type":["object","null"],"description":"s1014 L69 (docs/1068 Q17) — the business multiple: the asking price divided by the annual profit (12 x the listing's monthly profit), in hundredths (`250` = 2.50x). An ESTIMATE and NOT ADVICE (`estimate` and `not_advice` are always true). `basis` says where the profit came from: `verified` (a reading Zinn® took itself), `supplied` (a file the seller uploaded) or `declared` (typed by the seller, unverified). Null when the listing has no positive profit or no price, and while the valuation switch is OFF (except a pilot organisation's listings).","required":["estimate","not_advice","multiple_x100","ttm_profit_minor","price_minor","currency","basis"],"properties":{"estimate":{"type":"boolean","enum":[true]},"not_advice":{"type":"boolean","enum":[true]},"multiple_x100":{"type":"integer","minimum":1,"maximum":10000},"ttm_profit_minor":{"type":"integer"},"price_minor":{"type":"integer"},"currency":{"type":"string"},"basis":{"type":"string","enum":["verified","supplied","declared"]},"measured_by":{"type":"string"},"measured_at":{"type":"string"}}},"MarketplaceListingState":{"type":"string","description":"⛔ `archived`, never deleted. A listing that sold has public URLs, backlinks and an order behind it, and a 404 costs rankings that do not come back.","enum":["draft","in_review","live","paused","rejected","archived"]},"MarketplaceListingUpdate":{"type":"object","properties":{"description":{"type":"string","maxLength":20000,"description":"s1006 — plain-text long description (blank line between paragraphs, `- ` list lines). ⛔ Changing it, the title, the summary or the FAQ on a live third-party listing sends it back to review, like any other content change."},"faqs":{"type":"array","maxItems":20,"description":"Question/answer pairs; an entry missing either half is dropped.","items":{"$ref":"#/components/schemas/MarketplaceFaq"}},"inclusion_items":{"type":"array","description":"The handover checklist a buyer confirms receipt of, for an asset-transfer listing (a website, a domain, a Shopify store). The seller composes it; the listing type's `handover_template` is offered as `handover_suggestions` on the GET and is never applied for them, because a template copied in silently would put \"Instagram account\" on the order of a seller who has not got one — and the buyer would then be entitled to it.\n\n⛔ **Money does not release on an asset transfer until every REQUIRED item is buyer-confirmed**, and an order with no checklist at all is refused rather than treated as complete. Editing the list on a live listing is append-only and bumps `inclusion_revision`, which the buyer sees.","items":{"type":"object","required":["label"],"properties":{"label":{"type":"string","maxLength":200},"required":{"type":"boolean","default":true,"description":"Optional items are excluded from the release denominator, so a seller's payout never depends on a buyer bothering to tick a nice-to-have."}}}},"title":{"type":"string","maxLength":180},"summary":{"type":"string"},"slug":{"type":"string"},"field_values":{"type":"object","additionalProperties":true,"description":"Plain `{key: value}` — the envelope is added by the engine."},"publish":{"type":"boolean","description":"Validate against the stamped schema, require a package, recompute the price cache and go live — in one transaction."},"state":{"type":"string","enum":["live","paused","archived"],"description":"Take a Zinn® off sale, put it back, or retire it. Applied AFTER any value edit in the same request, so the storefront projection is rebuilt once from the state the listing actually ends in.\n\n⛔ A pause removes the listing from the storefront projection in the same transaction. A pause that leaves it searchable is not a pause — it keeps taking enquiries the vendor has been told it will not take.\n\n⛔ `archived` is one-way. docs/78 §4.5 archives rather than deletes so the public URL keeps resolving and the orders behind it stay explicable; a resurrect path would let one slug come to mean a different thing."}}},"MarketplaceManagedSaleState":{"type":"object","description":"s1014 L69 (docs/1068 §9e) — the managed-sale add-on for one listing. `price` is the catalogue row in the caller's currency (integer minor units). `eligible` is `offered` and no `reason`; `reason` is why this listing does not qualify (`notBusiness`, `listingClosed`, `noPrice`, `fxUnavailable`, `dealDeskInstead`, `alreadyBought`). `purchase` is the listing's managed sale that still counts, or null.","required":["offered","price","eligible","reason","deal_desk_from_usd_minor","purchase"],"properties":{"offered":{"type":"boolean"},"price":{"type":["object","null"],"required":["amount_minor","currency"],"properties":{"amount_minor":{"type":"integer"},"currency":{"type":"string"}}},"eligible":{"type":"boolean"},"reason":{"type":["string","null"],"enum":["notBusiness","listingClosed","noPrice","fxUnavailable","dealDeskInstead","alreadyBought",null]},"deal_desk_from_usd_minor":{"type":"integer","description":"The free deal desk's threshold in US cents."},"purchase":{"type":["object","null"],"required":["id","status","amount_minor","currency","bought_at"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"amount_minor":{"type":"integer"},"currency":{"type":"string"},"bought_at":{"type":"string","format":"date-time"}}}}},"MarketplaceMessage":{"type":"object","required":["id","body","mine","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"body":{"type":"string","description":"What the reader sees — the masked form where the policy masked it. The original is always kept in the order record and is what a dispute reads; it is not in this payload, because a masked message whose original is one call away is not masked."},"mine":{"type":"boolean"},"from_staff":{"type":"boolean"},"source_locale":{"type":"string","description":"BCP-47. Participants write in their own language; a message is translated FOR THE READER and the original is always shown, never replaced. Detected from the text when reader translation is on; the sender's declared locale otherwise."},"translation":{"nullable":true,"description":"The message in the reader's language (`?locale=`, else the account locale); `body` stays the original, offered behind \"show original\". Null for your own messages, when no translation is needed, when reader translation is off, or when a translation would have altered the order's anchor texts or URLs.","allOf":[{"$ref":"#/components/schemas/UserTextTranslation"}]},"masked":{"type":"boolean"},"policy_notice":{"type":"string","description":"A message KEY, rendered in every locale by the client. Set only for the SENDER of a masked message — telling the recipient \"they tried to give you an email address\" would be an accusation we have no business making at this confidence."},"held":{"type":"boolean","description":"Only on the send response. The one case where reporting \"sent\" would be a lie."},"created_at":{"type":"string","format":"date-time"}}},"MarketplaceMessageCreate":{"type":"object","required":["body"],"properties":{"body":{"type":"string","minLength":1,"maxLength":8000},"locale":{"type":"string","maxLength":16},"attachments":{"type":"array","maxItems":5,"description":"Refused entirely on a pre-sales thread: an attachment bypasses text scanning and we have no OCR, so on the one surface where nobody has paid there are no files.","items":{"type":"object","additionalProperties":true}}}},"MarketplaceMessageList":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceMessage"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"MarketplaceOrderArchetype":{"type":"string","description":"How this order behaves. Adding a CATEGORY is configuration; adding an ARCHETYPE is a build. Every order-side decision — whether a delivery clock exists, whether auto-accept applies, whether there is a handover checklist, how tight the contact policy is — is read from this rather than from the listing type's key.\n\nThe four are a taxonomy of what can go WRONG, not of what is sold, which is why `placement` is separate from `digital` even though both deliver a URL: a placement can be silently removed a month later and a delivered file cannot.","enum":["service","placement","digital","asset_transfer"]},"MarketplaceOrderDispute":{"type":"object","description":"A marketplace order's dispute, as the buyer or seller sees it (W43-74).","required":["sale_id","state","is_buyer","can_raise","refusal_code","dispute"],"properties":{"sale_id":{"type":"string","format":"uuid"},"state":{"type":"string"},"is_buyer":{"type":"boolean"},"can_raise":{"type":"boolean"},"refusal_code":{"type":["string","null"],"enum":["ALREADY_DISPUTED","NOT_YET_DISPUTABLE","NOT_DISPUTABLE",null]},"dispute":{"type":["object","null"],"required":["reason","raised_at","outcome","note","resolved_at"],"properties":{"reason":{"type":"string"},"raised_at":{"type":"string","format":"date-time"},"outcome":{"type":["string","null"],"enum":["release","refund_manual_required","refund_credit",null]},"note":{"type":"string"},"resolved_at":{"type":["string","null"],"format":"date-time"},"credit_minor":{"type":["integer","null"],"description":"s1014 L22 — what went back to the buyer's account credit (refund_credit only)."},"credit_currency":{"type":["string","null"]}}}}},"MarketplaceOrderTurn":{"type":"string","description":"Whose move it is. `staff` is a real answer, not a fallback: a disputed order is genuinely waiting on us, and telling a buyer \"waiting for the seller\" while a moderator holds it is the kind of small lie that turns a dispute into a chargeback.","enum":["buyer","seller","staff","nobody"]},"MarketplaceOrderWaitingOn":{"type":"string","description":"What the order is waiting FOR — the half that makes `turn` actionable.","enum":["requirements","delivery","revision","acceptance","handover","dispute","nothing"]},"MarketplaceOrderWorkspace":{"type":"object","required":["sale_id","state","archetype","turn","waiting_on","is_buyer"],"properties":{"listed_gross_minor":{"type":"integer","description":"L66 (docs/82 §2-fx) — the listed USD price. To a buyer `gross_minor`/`currency` are what they were charged (EUR/GBP when converted); to the seller, the listed USD the payable is on."},"listed_currency":{"type":"string"},"sale_id":{"type":"string","format":"uuid"},"state":{"type":"string"},"archetype":{"$ref":"#/components/schemas/MarketplaceOrderArchetype"},"listing_title":{"type":"string"},"package_name":{"type":"string"},"turn":{"$ref":"#/components/schemas/MarketplaceOrderTurn"},"waiting_on":{"$ref":"#/components/schemas/MarketplaceOrderWaitingOn"},"is_yours":{"type":"boolean","description":"Whether the caller is the party being waited on."},"is_buyer":{"type":"boolean"},"deadline":{"type":"string","format":"date-time","nullable":true,"description":"The clock that is actually running, or null when none is."},"paused":{"type":"boolean","description":"A clock EXISTS but is stopped — the revision pause. Distinct from a null deadline, which also covers an order that never had a clock at all."},"overdue":{"type":"boolean","description":"Never true while `delivery_due_at` is null: null means the clock has not started, which is exactly the state of an order whose buyer has not written their brief yet."},"handover_confirmed":{"type":"integer"},"handover_required":{"type":"integer"},"outstanding":{"type":"array","description":"Question keys the buyer still owes.","items":{"type":"string"}},"revisions_used":{"type":"integer"},"revisions_included":{"type":"integer"},"delivery_due_at":{"type":"string","format":"date-time","nullable":true},"currency":{"type":"string","minLength":3,"maxLength":3},"gross_minor":{"type":"integer","format":"int64","description":"Integer minor units. Money is never a float."},"commission_minor":{"type":"integer","format":"int64","nullable":true,"description":"The platform's commission, as its own figure. Present for the SELLER and null for the buyer — to a buyer the price is the price. The platform is merchant of record on every marketplace sale, so this is a margin on our own turnover rather than a deduction from someone else's."},"vendor_net_minor":{"type":"integer","format":"int64","nullable":true,"description":"What we owe the seller — a trade payable, not money held on trust."},"requirements_schema":{"type":"array","description":"The questions AS ASKED, frozen at purchase. A seller who rewrites their questions tomorrow cannot change what this buyer was asked. Every question carries `text_class` (docs/1067, ADR 0039): `verbatim` answers (anchor texts, URLs, keywords, domains) are shown byte-identical and never translated; `communication` answers may be translated for the reader with the original shown; `structured` answers are values with localised labels.","items":{"type":"object","additionalProperties":true,"properties":{"text_class":{"$ref":"#/components/schemas/UserTextClass"}}}},"requirements":{"type":"object","additionalProperties":true,"description":"The buyer's answers, in the same `{key: {v: …}}` envelope. `v` is exactly what the buyer typed; text answers also carry `lang`, the BCP-47 language detected from the brief (absent when unknown or when reader translation is off)."},"requirements_translations":{"type":"object","description":"Class B (`communication`) answers translated into the reader's language (`?locale=`, else the account locale), keyed by question. Never contains a `verbatim` question. Empty when the reader shares the brief's language, when reader translation is switched off, or when a translation would have altered an anchor or URL quoted inside the answer.","additionalProperties":{"$ref":"#/components/schemas/UserTextTranslation"}},"requirements_submitted_at":{"type":"string","format":"date-time","nullable":true},"handover_items":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceHandoverItem"}},"last_revision_reason":{"type":"string"}}},"MarketplaceOverview":{"type":"object","required":["verticals","latest","recently_sold","total_listings"],"properties":{"verticals":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceHubVertical"}},"latest":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceHubCard"}},"recently_sold":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceRecentSale"}},"total_listings":{"type":"integer"}}},"MarketplaceOwnFreelancerProfile":{"type":"object","required":["exists","profile"],"properties":{"exists":{"type":"boolean"},"profile":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/MarketplaceFreelancer"},{"type":"object","properties":{"published":{"type":"boolean"}}}]}}},"MarketplacePackage":{"type":"object","required":["id","name","description","price_minor","currency","delivery_days","revisions_included","position"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","maxLength":80},"description":{"type":"string"},"price_minor":{"type":"integer","format":"int64","description":"Integer MINOR units (CLAUDE.md §2.8). Never a float, never a decimal."},"currency":{"type":"string","minLength":3,"maxLength":3},"delivery_days":{"type":"integer"},"revisions_included":{"type":"integer","description":"⛔ `0` is a coherent offer — \"no revisions\" is a real thing to sell — so this is NOT nullable-means-unlimited. Contrast `auto_accept_days`, where null IS meaningful; the two are deliberately different."},"billing_mode":{"$ref":"#/components/schemas/MarketplaceBillingMode"},"billing_interval":{"type":["string","null"],"description":"`monthly` or `annual`. Required for a `subscription` package and null for a `one_time` one — the database enforces the pairing. A subscription with no interval has no renewal date; a one-time package with one is one refactor from renewing something nobody sold as recurring."},"position":{"type":"integer"},"active":{"type":"boolean"}}},"MarketplacePackageList":{"type":"object","required":["data","total","max_packages"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MarketplacePackage"}},"total":{"type":"integer"},"max_packages":{"type":"integer","description":"This vertical's cap, from a row an operator can change."},"permitted_billing_modes":{"type":"array","description":"What this listing type allows. The form is TOLD rather than guessing: a UI that hardcoded both modes would render a control whose every submission is refused.","items":{"$ref":"#/components/schemas/MarketplaceBillingMode"}},"permitted_billing_intervals":{"type":"array","items":{"type":"string","enum":["monthly","annual"]}}}},"MarketplacePackagesUpdate":{"type":"object","required":["packages"],"properties":{"packages":{"type":"array","minItems":1,"items":{"type":"object","required":["name","price_minor"],"properties":{"name":{"type":"string","maxLength":80},"description":{"type":"string"},"price_minor":{"type":"integer","format":"int64","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3},"delivery_days":{"type":"integer","minimum":0},"revisions_included":{"type":"integer","minimum":0},"billing_mode":{"$ref":"#/components/schemas/MarketplaceBillingMode"},"billing_interval":{"type":"string","enum":["monthly","annual"]}}}}}},"MarketplacePayout":{"type":"object","required":["id","state","amount_minor","currency","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"state":{"$ref":"#/components/schemas/MarketplacePayoutState"},"amount_minor":{"type":"integer","format":"int64","description":"The FULL amount owed. ⛔ A payout over a ceiling is HELD at its full value, never silently paid smaller — a truncating ceiling leaves the seller short, the ledger saying paid, and nothing raising (docs/82 §10c #8)."},"currency":{"$ref":"#/components/schemas/CurrencyCode"},"rail":{"type":["string","null"]},"rail_name":{"type":["string","null"]},"hold_reason":{"anyOf":[{"$ref":"#/components/schemas/MarketplacePayoutHoldReason"},{"type":"null"}]},"external_ref":{"type":"string","description":"The rail's own reference — a transaction hash, a batch id. Empty for account credit, which never leaves the platform and therefore has no external record."},"note":{"type":"string"},"fee_minor":{"type":"integer","format":"int64","description":"The payment provider's fee, passed on AT COST and taken off this payout (owner ruling 2026-10-25 — PayPal 2% capped USD 14 domestic / USD 90 international; bank and crypto e-mail payouts carry none). 0 when there is no fee."},"net_minor":{"type":"integer","format":"int64","description":"What reaches the seller — `amount_minor - fee_minor`."},"statement_number":{"type":["string","null"],"description":"The self-billed invoice number (`ZD-SBI-YYYY-NNNNNN`) — the payout statement IS the seller's invoice to us (docs/78 §11.4, §13.2). Set once the payout is paid; then `GET …/payouts/{payout_id}/statement` returns the document."},"sent_at":{"type":["string","null"],"format":"date-time","description":"When the provider ACCEPTED the transfer. A `sent` payout has left our balance and is still moving (PayPal, crypto e-mail payout); it becomes `paid` when the provider confirms, or `failed` (and the balance comes back) if it is refused or returned."},"settled_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"MarketplacePayoutHoldReason":{"type":"string","description":"Why a payout did not go out. Named rather than free text, so an operator can filter \"everything held for verification\" and a seller can be told which one it is.\n\n`below_rail_minimum` is not a loss — the balance ROLLS OVER to the next run and the seller can watch it accruing (docs/82 §7).\n\n⛔ `awaiting_manual_send` is a WAIT, not a fault, and it exists so a true refusal stops carrying a false reason. A rail whose live switch is off is staff-operated (owner rulings 2026-08-28 and 2026-10-25), and those payouts used to hold as `no_destination`: telling a seller who had added, proved and cooled off a destination that they had none, which sends them to redo work that was already correct.","enum":["unverified_vendor","no_destination","destination_cooling_off","over_per_payout_ceiling","over_per_run_ceiling","below_rail_minimum","awaiting_manual_send","seller_not_in_good_standing"]},"MarketplacePayoutList":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MarketplacePayout"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"MarketplacePayoutMethod":{"type":"object","description":"One destination a seller may be paid to, and the proof that it is theirs.","required":["id","rail","rail_name","destination","network","label","state","proof_kind","is_default","permitted_proof_kinds"],"properties":{"id":{"type":"string","format":"uuid"},"rail":{"type":"string"},"rail_name":{"type":"string"},"destination":{"type":"string","description":"⛔ **Masked, always.** Enough to recognise which account this is, never enough to reproduce it. The whole value never leaves the engine on a read path."},"network":{"type":"string","description":"⛔ Its own field, never folded into the address. Sending USDT TRC20 to a BEP20 address loses the money irrecoverably (docs/82 §7b), so the network is part of the destination's identity and the same address on two networks is two destinations."},"label":{"type":"string"},"state":{"$ref":"#/components/schemas/MarketplacePayoutMethodState"},"proof_kind":{"$ref":"#/components/schemas/MarketplacePayoutProofKind"},"rejection_reason":{"type":"string"},"is_default":{"type":"boolean"},"verified_at":{"type":"string","format":"date-time","nullable":true},"hold_until":{"type":"string","format":"date-time","nullable":true,"description":"docs/82 §7c's 48-hour cooling-off on the **first** payout to this destination — long enough for the change notice to land, short enough that a seller who genuinely changed bank barely notices. `null` once the hold has been spent by a payout, or for account credit, which never leaves the platform."},"permitted_proof_kinds":{"type":"array","items":{"$ref":"#/components/schemas/MarketplacePayoutProofKind"}},"country":{"type":"string","description":"The bank account's country (bank destinations set up through Stripe)."},"awaiting_email_link":{"type":"boolean","description":"True when the seller's next step is opening the link we e-mailed."}}},"MarketplacePayoutMethodCreate":{"type":"object","required":["rail"],"properties":{"rail":{"type":"string","enum":["paypal","crypto"],"description":"⚖️ Owner, 2026-10-25: sellers are paid by PayPal, bank (Stripe) or crypto (NOWPayments) only. PayPal and crypto are added here with the account's e-mail; bank is set up with `startMarketplaceVendorBankOnboarding`. Anything else — Payoneer included — is refused (`PAYOUT_METHOD_NOT_OFFERED`)."},"destination":{"type":"string","maxLength":255,"description":"The e-mail address of the PayPal account, or the e-mail the crypto payout is sent to (NOWPayments → ChangeNOW PRO)."},"network":{"type":"string","maxLength":32,"description":"Historical. Crypto is now paid to an e-mail address through NOWPayments (ChangeNOW PRO), never to a wallet — a non-empty network is refused (`CRYPTO_IS_PAID_BY_EMAIL`)."},"label":{"type":"string","maxLength":80}}},"MarketplacePayoutMethodList":{"type":"object","required":["data","rails","paid_as_credit","needs_new_method"],"properties":{"paid_as_credit":{"type":"boolean","description":"⚖️ Owner, 2026-10-25: Zinn® credit is every seller's default, set by us, until they add and confirm PayPal, bank or crypto. `true` = their earnings are paid as Zinn® credit, which can be spent on the platform and never withdrawn as cash."},"needs_new_method":{"type":"boolean","description":"The seller has a destination we no longer pay to (`unsupported`, e.g. Payoneer) and nothing usable instead — the screen asks them to choose one of the three."},"data":{"type":"array","items":{"$ref":"#/components/schemas/MarketplacePayoutMethod"}},"rails":{"type":"array","items":{"$ref":"#/components/schemas/MarketplacePayoutRailOption"}}}},"MarketplacePayoutMethodProof":{"type":"object","required":["proof_kind"],"properties":{"proof_kind":{"$ref":"#/components/schemas/MarketplacePayoutProofKind"},"proof_document_id":{"type":"string","format":"uuid","description":"Required when the proof is a document."},"proof_reference":{"type":"string","description":"Required for every non-document proof — the signed message, the transaction, or the account to check."}}},"MarketplacePayoutMethodState":{"type":"string","description":"Where one destination is in its own verification (docs/82 §7c). `retired` rows are kept rather than deleted — a payout that went there is explained by them. `unsupported` is a destination on a method we no longer pay by (Payoneer; a bank account proved by a statement; a crypto wallet address) — kept, never paid to, and the seller is asked to choose PayPal, bank (Stripe) or crypto (NOWPayments) instead (owner, 2026-10-25).","enum":["pending_proof","pending_review","verified","rejected","retired","unsupported"]},"MarketplacePayoutProofKind":{"type":"string","description":"How ownership of the destination was shown. ⛔ Crypto is the honest exception and is recorded as one: docs/82 §7c states that *no document can prove wallet ownership*, so a signed message or a micro-transaction genuinely proves it, and a self-declared address is accepted as proportionate **given the change control** — with which one was used stored rather than assumed. `not_required` is account credit alone, which never leaves the platform. Since 2026-10-25 (owner: PayPal, bank via Stripe, crypto via NOWPayments only) new destinations use `email_link` (PayPal and crypto — the seller opens a link we sent to that address) or `provider_onboarding` (bank — Stripe's hosted onboarding); the older kinds remain only on historical rows.","enum":["document","account_email","signed_message","micro_transaction","self_declared","not_required","email_link","provider_onboarding"]},"MarketplacePayoutRailOption":{"type":"object","description":"A rail as the seller choosing one sees it. The minimum and the fee note are served here because docs/82 §7 requires them **where the rail is chosen** — the rail changes what the seller actually receives.","required":["code","name","minimum_minor","fee_note","proof_kinds","payout_mode","eta_note","requires_verification"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"minimum_minor":{"type":"integer","description":"Below this a balance **rolls over** to the next run rather than being lost. Zero is meaningful and is account credit's real value."},"fee_note":{"type":"string"},"proof_kinds":{"type":"array","items":{"$ref":"#/components/schemas/MarketplacePayoutProofKind"}},"payout_mode":{"type":"string","enum":["automated","manual"],"description":"How the money actually leaves. `automated` — the weekly run sends it with no human. `manual` — an operator sends it from the payout queue, and the seller is told so **where they choose the rail**.\n\n⛔ This exists because docs/82 §7 warned that a rail with no driver \"would offer a vendor a choice that silently cannot pay\". The owner ruled on 2026-08-28 that all rails go live staff-operated, so the honest answer had to be expressible before the rows existed. (Payoneer was withdrawn on 2026-10-25; each of PayPal, bank and crypto turns `automated` only after its staff test payout succeeds.) A payout on such a rail holds under `awaiting_manual_send` — a wait with a stated timescale, never a fault."},"eta_note":{"type":"string","description":"When the seller can expect the money, as prose. Prose rather than a number for the same reason `fee_note` is: \"instantly\" and \"within 3 business days of the weekly run\" are not the same kind of claim."},"requires_verification":{"type":"boolean","description":"Whether this rail needs the seller's identity file approved before money may leave. ⚖️ Owner, 2026-08-28: *\"show what is available after kyc\"* — a screen cannot answer that from a hardcoded list, because the answer differs per rail and is operator-editable.\n\n⛔ `false` for account credit **only**, and it is not a loophole: credit never leaves the platform, so there is no transfer for AML to be about. This field decides what the seller is SHOWN; the payout gate re-reads the underlying facts regardless (§7a)."}}},"MarketplacePayoutReadiness":{"type":"object","description":"Whether money may leave the platform to this seller today, and every reason it may not. docs/82 §7a — the same computation the payout runner performs.","required":["permitted","reasons"],"properties":{"permitted":{"type":"boolean"},"reasons":{"type":"array","description":"Every reason at once, not the first — a seller told one problem at a time makes one round trip per problem.","items":{"type":"string","enum":["no_verification","verification_not_approved","document_expired","document_missing","subject_not_approved","sanctions_not_screened","sanctions_not_clear","document_request_holds_payouts","vendor_not_approved","no_destination","destination_cooling_off","dac7_data_incomplete","country_details_incomplete","identity_unverified"]}}}},"MarketplacePayoutSchedule":{"type":"object","required":["next_run_at","minimum_minor","currency"],"properties":{"next_run_at":{"type":"string","format":"date-time","description":"The next automatic payout run — Fridays 10:00 UTC."},"minimum_minor":{"type":"integer","format":"int64","description":"Below this a balance rolls over to the next run (US$50)."},"currency":{"$ref":"#/components/schemas/CurrencyCode"},"instant":{"description":"The instant tier, evaluated live — `null` when the caller is not a seller. Eligible sellers (20+ completed orders, no refund, dispute or chargeback in 90 days) are paid when a sale completes instead of on Friday.","type":["object","null"],"required":["eligible","completed_orders","required_orders","clean_days","reasons"],"properties":{"eligible":{"type":"boolean"},"completed_orders":{"type":"integer"},"required_orders":{"type":"integer"},"clean_days":{"type":"integer"},"reasons":{"type":"array","items":{"type":"string","enum":["switched_off","too_few_orders","recent_refund","recent_dispute","recent_chargeback"]}}}}}},"MarketplacePayoutState":{"type":"string","description":"⛔ `held` is not a failure and must not be retried blindly — it is the AML gate (docs/82 §7a: the payout is held, never the sale), a ceiling, or a missing verified destination. Each carries a `hold_reason`, and each is cleared by a human doing something rather than by the next run trying again harder.","enum":["pending","held","sent","paid","failed"]},"MarketplacePayoutStatement":{"type":"object","description":"One payout's statement, which is also the self-billed invoice Zinn Digital® raises on the seller's behalf under the self-billing agreement (docs/78 §11.4, §13.2; docs/82 §8). The dashboard renders it in the seller's own locale — `vat_treatment` is a CODE it words.","required":["payout_id","statement_number","issued_at","currency","supplier","customer","vat_treatment","lines","total_owed_minor","fee_minor","paid_minor","method","credit_only"],"properties":{"payout_id":{"$ref":"#/components/schemas/Uuid"},"statement_number":{"type":"string"},"issued_at":{"type":"string","format":"date-time"},"currency":{"$ref":"#/components/schemas/CurrencyCode"},"supplier":{"type":"object","description":"The seller — the supplier on a self-billed invoice.","properties":{"name":{"type":"string"},"address":{"type":"string"},"country":{"type":"string"},"vat_number":{"type":"string"},"self_billing_accepted_at":{"type":["string","null"],"format":"date-time"}}},"customer":{"type":"object","description":"Our issuing legal entity — the customer on a self-billed invoice.","properties":{"name":{"type":"string"},"address":{"type":"string"},"vat_number":{"type":"string"},"company_number":{"type":"string"}}},"vat_treatment":{"type":"string","enum":["not_registered","registered_domestic","registered_reverse_charge","unknown"]},"lines":{"type":"array","items":{"type":"object","properties":{"sale_id":{"type":["string","null"]},"order_date":{"type":["string","null"],"format":"date"},"accepted_at":{"type":["string","null"],"format":"date-time"},"description":{"type":"string"},"gross_minor":{"type":"integer","format":"int64"},"commission_minor":{"type":"integer","format":"int64"},"net_minor":{"type":"integer","format":"int64"}}}},"total_owed_minor":{"type":"integer","format":"int64"},"fee_minor":{"type":"integer","format":"int64"},"paid_minor":{"type":"integer","format":"int64"},"method":{"type":"string"},"destination":{"type":"string","description":"The destination MASKED — never the full address."},"external_ref":{"type":"string"},"credit_only":{"type":"boolean","description":"True when paid as Zinn® account credit — spend-only (owner ruling 2026-10-25): it is spent on hosting, plugins and services and is never withdrawn or converted to cash."}}},"MarketplacePortfolioItem":{"type":"object","required":["id","title","description","link_url","image"],"properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string"},"link_url":{"type":"string"},"image":{"type":"object","nullable":true,"properties":{"url":{"type":"string"},"srcset":{"type":"string"}}},"width":{"type":"integer"},"height":{"type":"integer"}}},"MarketplaceProject":{"type":"object","description":"s1006 (Q60). A buyer's posted brief.","required":["id","title","brief","category","skills","currency","state","created_at","is_mine"],"properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"brief":{"type":"string"},"category":{"type":"string"},"skills":{"type":"array","items":{"type":"string"}},"budget_min_minor":{"type":"integer","format":"int64","nullable":true},"budget_max_minor":{"type":"integer","format":"int64","nullable":true},"currency":{"type":"string"},"deadline":{"type":"string","format":"date","nullable":true},"state":{"type":"string","enum":["open","awarded","closed"]},"created_at":{"type":"string","format":"date-time"},"is_mine":{"type":"boolean"},"quote_count":{"type":"integer","description":"On `scope=mine` only."},"quoted":{"type":"boolean","description":"On `scope=board` only — you have quoted."}}},"MarketplaceProjectQuote":{"type":"object","required":["id","project_id","freelancer","listing","price_minor","currency","delivery_days","message","state","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"freelancer":{"type":"object","properties":{"display_name":{"type":"string"},"slug":{"type":"string"}}},"listing":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"}}},"price_minor":{"type":"integer","format":"int64"},"currency":{"type":"string"},"delivery_days":{"type":"integer"},"message":{"type":"string"},"state":{"type":"string","enum":["submitted","accepted","paid","declined","withdrawn"]},"conversation_id":{"type":"string","format":"uuid","nullable":true},"listing_package_id":{"type":"string","format":"uuid","nullable":true,"description":"Set once accepted — the reserved package the buyer checks out with."},"created_at":{"type":"string","format":"date-time"}}},"MarketplacePublicField":{"type":"object","required":["key","label","kind","unit","value","verified","structured"],"properties":{"key":{"type":"string"},"label":{"type":"string"},"kind":{"$ref":"#/components/schemas/MarketplaceFieldKind"},"unit":{"type":"string"},"value":{"description":"Already masked. A `domain` arrives as `site****.com`."},"verified":{"type":"boolean","description":"Whether the value carries a verification envelope, not who verified it."},"measured_by":{"type":"string","description":"Who produced this value — `platform` for a number Zinn® measured, empty for a seller-declared one. Owner directive D8: a vendor can never type, edit or override a metric, so `platform` is the only value that carries authority."},"measured_at":{"type":"string","description":"When we last measured it, ISO-8601, or empty. ⛔ Required alongside the value rather than optional: a metric with no date is exactly the vendor-declared claim this mechanism replaced, and reads never refresh — so the age is the caller's to judge and ours to publish."},"measured_host":{"type":"string","description":"The host we actually measured, or empty. ⭐ Published so the no-up-levelling rule is auditable from OUTSIDE the engine: a subdomain listing showing its apex's authority is the fraud this exists to prevent, and naming the host lets a buyer check rather than trust."},"structured":{"type":"boolean","description":"Whether this field may appear in JSON-LD. ⭐ Decided in the engine so the rendered array and the structured-data array are the same object — two filters would eventually disagree, invisibly (docs/82 §4a)."}}},"MarketplacePublicListing":{"type":"object","required":["id","slug","title","summary","marketplace_key","listing_type_key","schema_version","vendor_display_name","price_minor","price_max_minor","currency","sales_count","fields","packages"],"properties":{"source_locale":{"type":"string","description":"The language the **seller** wrote this listing in (#2606 slice E), or `\"\"` when nothing has been translated and the question does not arise. ⭐ The owner's ruling was *\"translate it, show the original language\"* — a machine translation of a third party's sales copy presented as their own words is a misattribution, on the page where a buyer is judging that vendor. Render it as *\"translated from X\"* whenever `copy_locale` is set and differs from it."},"copy_locale":{"type":"string","description":"The language `title` and `summary` are actually IN — the requested locale when a translation was served, `\"\"` when they are the seller's own words. ⛔ Not the locale that was asked for: a payload that echoed the request would make a fallback indistinguishable from a translation."},"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"title":{"type":"string"},"summary":{"type":"string"},"marketplace_key":{"type":"string"},"images":{"type":"array","description":"Cover first, so a client that renders only the first entry renders the right one without knowing the rule. Empty until the seller uploads one.","items":{"$ref":"#/components/schemas/MarketplaceImage"}},"storefront_layout":{"$ref":"#/components/schemas/MarketplaceStorefrontLayout"},"category_path":{"type":"string","nullable":true},"listing_type_key":{"type":"string"},"schema_version":{"type":"integer"},"vendor_display_name":{"type":"string","description":"Always \"Zinn Digital®\" (merchant of record). The vendor's own name is never sent on a public or buyer-facing marketplace payload (owner, s1014 MKTPLACE-r1, 2026-10-31)."},"first_party":{"type":"boolean","description":"Always true: Zinn Digital® is merchant of record on every marketplace sale, so a storefront shows no \"by …\" byline on any listing (owner, s1014 MKTPLACE-r1, 2026-10-31; supersedes the 2026-10-29 third-party carve-out)."},"has_reveal":{"type":"boolean","description":"Whether this listing holds an identifying value behind a mask (a domain shown as `site****.com`), so `revealMarketplaceListing` has something to return. False for a service listing, which masks nothing: a signed-in buyer is offered no \"show the full details\" panel there, rather than one that always fails (s1014 MKTPLACE)."},"price_minor":{"type":"integer","format":"int64"},"price_max_minor":{"type":"integer","format":"int64"},"currency":{"type":"string","minLength":3,"maxLength":3},"sales_count":{"type":"integer"},"published_at":{"type":"string","format":"date-time","nullable":true},"fields":{"type":"array","items":{"$ref":"#/components/schemas/MarketplacePublicField"}},"packages":{"type":"array","items":{"$ref":"#/components/schemas/MarketplacePackage"}},"inclusion_items":{"description":"docs/83 §4.1 — what a buyer gets, shown BEFORE they pay, translated for the reader with `source_locale` on each translated row.","type":"array","items":{"$ref":"#/components/schemas/MarketplaceInclusionItem"}},"inclusion_revision":{"type":"integer"},"description":{"type":"string","description":"s1006 — the long description, plain text, translated for the reader (falls back per string to the source)."},"faqs":{"type":"array","description":"The FAQ, translated for the reader; the page's `FAQPage` is built from it.","items":{"$ref":"#/components/schemas/MarketplaceFaq"}},"hosted_with_zinn":{"type":"string","description":"`site` or `domain` when the asset is hosted with Zinn® — it moves to the buyer automatically, and measured fields marked `measured_by: platform` came from our own servers. Empty otherwise.","enum":["","site","domain"]},"verified_traffic":{"$ref":"#/components/schemas/MarketplaceVerifiedTraffic"},"verified_revenue":{"$ref":"#/components/schemas/MarketplaceVerifiedRevenue"},"verified_badge":{"$ref":"#/components/schemas/MarketplaceVerifiedBadge"},"multiple":{"$ref":"#/components/schemas/MarketplaceListingMultiple"}}},"MarketplacePublicSchema":{"type":"object","required":["key","name","schema_version","field_schema"],"properties":{"key":{"type":"string"},"name":{"type":"string"},"schema_version":{"type":"integer"},"field_schema":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceFieldDefinition"}}}},"MarketplacePurchase":{"type":"object","description":"One purchase, as the BUYER sees it. It carries no commission figure — to a buyer the price is the price, and what the platform takes from the seller is the seller's deal, not theirs.","required":["id","state","listing_id","listing_title","package_name","amount_minor","currency"],"properties":{"listed_amount_minor":{"type":"integer","description":"L66 (docs/82 §2-fx) — the listed price (minor units of `listed_currency`). Equal to `amount_minor` unless the buyer was charged in EUR/GBP; `amount_minor`/`currency` are always what the buyer was charged."},"listed_currency":{"type":"string"},"id":{"$ref":"#/components/schemas/Uuid"},"state":{"$ref":"#/components/schemas/MarketplaceSaleState"},"listing_id":{"$ref":"#/components/schemas/Uuid"},"listing_title":{"type":"string"},"package_name":{"type":"string"},"package_description":{"type":"string"},"vendor_display_name":{"type":"string","description":"Always \"Zinn Digital®\" (merchant of record). The vendor's own name is never sent on a public or buyer-facing marketplace payload (owner, s1014 MKTPLACE-r1, 2026-10-31)."},"delivery_days":{"type":"integer"},"revisions_included":{"type":"integer"},"revision_count":{"type":"integer"},"billing_mode":{"$ref":"#/components/schemas/MarketplaceBillingMode"},"billing_interval":{"type":["string","null"]},"period_index":{"type":"integer","description":"0 for a one-time sale and a subscription's first period; one per renewal."},"amount_minor":{"type":"integer","format":"int64"},"currency":{"$ref":"#/components/schemas/CurrencyCode"},"auto_accepts":{"type":"boolean","description":"Read this BEFORE `accept_by`. A null `accept_by` means two completely different things — not delivered yet, or this type never auto-accepts at all (an asset sale releasing on a handover checklist, docs/83 §4.5) — and a UI that inferred \"no deadline\" from the null date would be wrong in both directions."},"auto_accept_days":{"type":["integer","null"]},"accept_by":{"type":["string","null"],"format":"date-time","description":"When this purchase auto-accepts if the buyer does nothing."},"delivered_at":{"type":["string","null"],"format":"date-time"},"accepted_at":{"type":["string","null"],"format":"date-time"},"accepted_automatically":{"type":"boolean","description":"Whether the timer accepted this rather than the buyer. It does NOT change the outcome — auto-accept has the same finality as the button, which is why the buyer must be warned before it fires rather than told after."},"last_revision_reason":{"type":"string"},"last_revision_at":{"type":["string","null"],"format":"date-time"},"order_id":{"$ref":"#/components/schemas/Uuid"},"created_at":{"type":"string","format":"date-time"}}},"MarketplacePurchaseList":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MarketplacePurchase"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"MarketplaceRecentSale":{"type":"object","description":"docs/83 §6's social proof, with its one rule kept: the mask stays on. Selling a site does not make its domain public.","required":["vertical_key","title","price_minor","currency","sold_at"],"properties":{"vertical_key":{"type":"string"},"title":{"type":"string"},"domain_masked":{"type":"string"},"category_path":{"type":"string"},"price_minor":{"type":"integer","format":"int64"},"currency":{"type":"string"},"sold_at":{"type":"string","format":"date-time"}}},"MarketplaceRequirementsSubmission":{"type":"object","required":["requirements"],"properties":{"requirements":{"type":"object","additionalProperties":true,"description":"Answer per question key, validated against the frozen schema."}}},"MarketplaceReveal":{"type":"object","required":["listing_id","field_key","value"],"properties":{"listing_id":{"type":"string","format":"uuid"},"field_key":{"type":"string"},"value":{"type":"string"}}},"MarketplaceRevisionRequest":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","minLength":1,"maxLength":2000,"description":"What needs changing. Required, and shown to the seller — a rejection they cannot read names nothing, so it produces a second rejection.","example":"The anchor text is wrong."}}},"MarketplaceSaleState":{"type":"string","description":"Where one purchased package is in its life (docs/82 §3). The terminal state is `accepted`, not `delivered`: delivery is the vendor's claim, acceptance is the buyer's act, and it is acceptance that ends the refund window and releases the money.","enum":["awaiting_delivery","delivered","revision_requested","accepted","disputed","refunded","cancelled"]},"MarketplaceSearchCard":{"type":"object","required":["id","slug","title","summary","vendor_display_name","domain_masked","category_path","price_minor","price_max_minor","currency","delivery_days_min","rating_score","review_count","sales_count"],"properties":{"images":{"type":"array","maxItems":1,"description":"The listing's cover picture (s1014 J39), as a one-item list, or `[]` when it has none. Cover only: a card shows one image.","items":{"$ref":"#/components/schemas/MarketplaceImage"}},"source_locale":{"type":"string","description":"The language the **seller** wrote this listing in (#2606 slice E), or `\"\"` when nothing has been translated and the question does not arise. ⭐ The owner's ruling was *\"translate it, show the original language\"* — a machine translation of a third party's sales copy presented as their own words is a misattribution, on the page where a buyer is judging that vendor. Render it as *\"translated from X\"* whenever `copy_locale` is set and differs from it."},"copy_locale":{"type":"string","description":"The language `title` and `summary` are actually IN — the requested locale when a translation was served, `\"\"` when they are the seller's own words. ⛔ Not the locale that was asked for: a payload that echoed the request would make a fallback indistinguishable from a translation."},"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"title":{"type":"string"},"summary":{"type":"string"},"vendor_display_name":{"type":"string","description":"Always \"Zinn Digital®\" (merchant of record). The vendor's own name is never sent on a public or buyer-facing marketplace payload (owner, s1014 MKTPLACE-r1, 2026-10-31)."},"first_party":{"type":"boolean","description":"Always true: Zinn Digital® is merchant of record on every marketplace sale, so a storefront shows no \"by …\" byline on any listing (owner, s1014 MKTPLACE-r1, 2026-10-31; supersedes the 2026-10-29 third-party carve-out)."},"domain_masked":{"type":"string","description":"`site****.com`, or empty. The full value is not in the table this reads — it lives in a separate table one authenticated endpoint touches — so this is a column that has never held anything else, not a serializer remembering to mask."},"category_path":{"type":"string"},"price_minor":{"type":"integer","format":"int64"},"price_max_minor":{"type":"integer","format":"int64"},"currency":{"type":"string","minLength":3,"maxLength":3},"delivery_days_min":{"type":"integer"},"rating_score":{"type":"integer","description":"Wilson lower bound × 10000 — not the raw average."},"review_count":{"type":"integer"},"sales_count":{"type":"integer"},"published_at":{"type":"string","format":"date-time","nullable":true},"fields":{"type":"object","additionalProperties":true,"description":"s1006 (Q59). The listing's value for each FACET of the named `type` — Domain Rating, Trust Flow, link type, site language — unwrapped, keyed by field key (the `facets[].key` of the same response, whose labels translate them). Empty when no `type` is named. ⛔ Facet keys only: a facet is public by construction and a domain is never facetable, so this cannot widen what the endpoint publishes."},"measured_fields":{"type":"array","items":{"type":"string"},"description":"The keys in `fields` whose value Zinn® measured (it carries our verification stamp) rather than the seller typing it."},"verified_badge":{"$ref":"#/components/schemas/MarketplaceVerifiedBadge"}}},"MarketplaceSearchResult":{"type":"object","required":["marketplace","results","next_cursor","total","total_is_capped","sort","sorts","facets","query","interpreted","retrieval"],"properties":{"marketplace":{"type":"object","required":["key","name","storefront_layout"],"properties":{"key":{"type":"string"},"name":{"type":"string"},"tagline":{"type":"string","description":"The operator's one-line description of the vertical. May be empty."},"storefront_layout":{"allOf":[{"$ref":"#/components/schemas/MarketplaceStorefrontLayout"}],"description":"How this vertical's results are laid out — the owner's 2026-08-08 instruction (\"layouts suited to what is sold — a guest post is a list/table, not a product card\") as data rather than a map compiled into the frontend.\n\n⛔ It travels with the SEARCH answer as well as the hub's, because the browse page is the one that ranks: serving it only on `/overview` meant the page a visitor actually lands on could not honour the instruction, and went on rendering an undifferentiated card list."}}},"canonical_vertical":{"type":"string","nullable":true,"description":"Set when the request used a SUPERSEDED slug — the segment this page should 301 to. `null` on the normal path.\n\n⛔ A retired slug still RESOLVES rather than 404ing: docs/83 §6 puts real ranking on these URLs and a 404 throws away what the old link earned. This field is what lets the storefront redirect instead of quietly serving a non-canonical URL — a boolean would leave the page knowing something was wrong and unable to act."},"listing_type":{"type":"string","nullable":true},"results":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceSearchCard"}},"next_cursor":{"type":"string","description":"Empty when there is no next page. Opaque — never build one by hand."},"total":{"type":"integer"},"total_is_capped":{"type":"boolean","description":"True when there are more than `total` results. The page renders \"10,000+\"; showing a flat \"10,000\" for a catalogue of two million would be false."},"sort":{"type":"string"},"sorts":{"type":"array","items":{"type":"string"},"description":"The sorts this catalogue offers, served with the data so the storefront is not compiled against a copy of the list."},"facets":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceFacet"}},"query":{"type":"string","description":"What was actually searched for, after the filter language took its bite. Empty when no phrase was given.\n\n⭐ Differs from what the buyer typed whenever `interpreted` is non-empty: `DR 40-50 finance` searches for `finance` and filters on DR. Carried so that \"why did this match?\" has an answer from outside the process."},"interpreted":{"type":"array","items":{"type":"string"},"description":"Human-readable chips for filters INFERRED from the phrase rather than ticked on the rail — already in the requested locale.\n\n⛔⛔ **Render these.** A search box that silently rewrites a query is the most confusing thing a search box can do: the buyer sees a result set that does not match what they typed, cannot tell why, and has no way to undo it. An explicitly ticked filter always wins over an inferred one, and when it does the chip is withdrawn rather than shown alongside."},"retrieval":{"type":"array","items":{"type":"string","enum":["lexical","trigram","semantic"]},"description":"Which retrieval paths actually ran for this request (docs/83 §2a, D-W15-9). Empty when no phrase was given, or when the deployment has no retrieval objects.\n\n⛔⛔ **Not diagnostics.** \"Nothing matched\" and \"the path that would have matched is switched off here\" produce an identical empty list and an identical healthy 200. `semantic` is absent when the `vector` extension is unavailable or no embeddings provider is configured; `trigram` is skipped for phrases under three characters, where a GIN trigram index cannot help."}}},"MarketplaceStorefrontLayout":{"type":"string","description":"How a vertical's results are laid out on the public storefront. Owner instruction 2026-08-08: *\"layouts suited to what is sold — a guest post is a list/table, not a product card.\"* A column on the vertical rather than a constant in the frontend, so adding a vertical stays admin data entry (docs/83 §2).","enum":["table","showcase","provider","compact"]},"MarketplaceTrafficVerification":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["not_connected","awaiting_property","active","needs_reconnect"]},"provider":{"type":"string"},"property_id":{"type":"string"},"property_name":{"type":"string"},"matched_host":{"type":"string"},"last_error":{"type":"string","description":"The last refusal code","empty when healthy.":null},"traffic":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/MarketplaceVerifiedTraffic"}]}}},"MarketplaceValuationEstimate":{"type":"object","description":"s1014 L69 (docs/1068 Q9/Q17) — an ESTIMATE of what a business might sell for, NOT ADVICE and never a promise. Annual profit (12 x `monthly_profit_minor`) times the multiple band for the asset class (a dated row with its `source`, picked by the profit in US dollars), moved by the dated adjustment rows for age, trend, concentration and verification coverage (`adjustments`; a factor with `bucket: null` was not given and moved nothing). Money is integer minor units in `currency` (the input's); multiples are hundredths. `inputs` lists every figure used with its `basis`: `verified` (read by Zinn® itself), `supplied` (a file the seller uploaded) or `declared` (typed, unverified).","required":["estimate","not_advice","asset_class","currency","monthly_profit_minor","ttm_profit_minor","value_low_minor","value_mid_minor","value_high_minor","multiple_low_x100","multiple_mid_x100","multiple_high_x100","adjustment_bps","band","adjustments","inputs","computed_at"],"properties":{"estimate":{"type":"boolean","enum":[true]},"not_advice":{"type":"boolean","enum":[true]},"asset_class":{"type":"string","enum":["websites","shopify_stores","amazon_fba","etsy_shops"]},"currency":{"type":"string"},"monthly_profit_minor":{"type":"integer"},"ttm_profit_minor":{"type":"integer"},"value_low_minor":{"type":"integer"},"value_mid_minor":{"type":"integer"},"value_high_minor":{"type":"integer"},"multiple_low_x100":{"type":"integer"},"multiple_mid_x100":{"type":"integer"},"multiple_high_x100":{"type":"integer"},"adjustment_bps":{"type":"integer"},"band":{"type":"object","properties":{"profit_from_usd_minor":{"type":"integer"},"multiple_low_x100":{"type":"integer"},"multiple_mid_x100":{"type":"integer"},"multiple_high_x100":{"type":"integer"},"source":{"type":"string"},"effective_from":{"type":"string","format":"date"}}},"adjustments":{"type":"array","items":{"type":"object","properties":{"factor":{"type":"string","enum":["age","trend","concentration","verification"]},"bucket":{"type":["string","null"]},"delta_bps":{"type":"integer"},"effective_from":{"type":["string","null"],"format":"date"}}}},"inputs":{"type":"array","items":{"type":"object","required":["key","basis"],"properties":{"key":{"type":"string"},"basis":{"type":"string","enum":["verified","supplied","declared"]},"by":{"type":"string"},"at":{"type":"string"},"value_minor":{"type":"integer"},"currency":{"type":"string"},"value":{}}}},"computed_at":{"type":"string","format":"date-time"},"listing_id":{"type":"string","format":"uuid"},"multiple":{"$ref":"#/components/schemas/MarketplaceListingMultiple"},"verified_sources":{"type":"integer","minimum":0,"maximum":2}}},"MarketplaceVendorProfile":{"type":"object","description":"Whether this account sells, and the state of its identity file.","required":["registered","vendor","verification"],"properties":{"registered":{"type":"boolean","description":"`false` is a normal answer — most customers are not sellers — and the other two fields are then `null`."},"vendor":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/MarketplaceVendorSelf"}]},"verification":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/MarketplaceVerification"}]}}},"MarketplaceVendorRegistration":{"type":"object","required":["display_name"],"properties":{"display_name":{"type":"string","maxLength":200,"description":"The name buyers see. Required."},"contact_email":{"type":"string","maxLength":254},"country":{"type":"string","example":"GB","description":"ISO-3166-1 alpha-2."},"org_id":{"type":"string","format":"uuid","description":"The organisation to register (D51530). Beats `X-Zinn-Org`; must be in the caller's scope or the call is `403`. Omit it on a single-organisation account."}}},"MarketplaceVendorSale":{"type":"object","description":"One sale, as the SELLER sees it — including the split, because it is their deal. The rate is per sale rather than one dashboard percentage: docs/82 §10c #4 resolves commission per period, so a vendor with a scheduled rate change has sales at two rates at once.","required":["id","state","listing_id","listing_title","package_name","gross_minor","currency"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"state":{"$ref":"#/components/schemas/MarketplaceSaleState"},"listing_id":{"$ref":"#/components/schemas/Uuid"},"listing_title":{"type":"string"},"package_name":{"type":"string"},"delivery_days":{"type":"integer"},"revisions_included":{"type":"integer"},"revision_count":{"type":"integer"},"billing_mode":{"$ref":"#/components/schemas/MarketplaceBillingMode"},"billing_interval":{"type":["string","null"]},"period_index":{"type":"integer"},"gross_minor":{"type":"integer","format":"int64","description":"What the buyer paid for this line, excluding tax."},"commission_bps":{"type":"integer"},"commission_minor":{"type":"integer","format":"int64"},"vendor_net_minor":{"type":"integer","format":"int64","description":"gross - commission, always. Never a second independent rounding: a half-penny landing in neither figure is too small to find and too persistent to ignore."},"currency":{"$ref":"#/components/schemas/CurrencyCode"},"auto_accepts":{"type":"boolean"},"accept_by":{"type":["string","null"],"format":"date-time"},"delivered_at":{"type":["string","null"],"format":"date-time"},"accepted_at":{"type":["string","null"],"format":"date-time"},"accepted_automatically":{"type":"boolean"},"last_revision_reason":{"type":"string","description":"What the buyer asked to be changed. The seller MUST be able to read this — it is the instruction, and a rejection without one produces a second rejection."},"last_revision_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"MarketplaceVendorSaleList":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceVendorSale"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"MarketplaceVendorSelf":{"type":"object","description":"The seller's own view of their vendor row.","required":["id","display_name","contact_email","country","state","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"display_name":{"type":"string"},"contact_email":{"type":"string"},"country":{"type":"string"},"state":{"$ref":"#/components/schemas/VendorState"},"created_at":{"type":"string","format":"date-time"}}},"MarketplaceVerification":{"type":"object","required":["id","track","state","legal_name","country","self_billing_accepted","subjects","documents","document_requests"],"properties":{"id":{"type":"string","format":"uuid"},"track":{"$ref":"#/components/schemas/MarketplaceVerificationTrack"},"state":{"$ref":"#/components/schemas/MarketplaceVerificationState"},"legal_name":{"type":"string"},"country":{"type":"string"},"company_number":{"type":"string"},"registered_address":{"type":"string"},"tin":{"type":"string","description":"Your Tax Identification Number as we hold it (`docs/331`). Returned so the screen can show what is on file and let you correct it — until Wave 37 this endpoint accepted a TIN and returned none, so the seller could not see whether theirs had saved."},"tin_issued_in":{"type":"string","description":"ISO-3166-1 alpha-2 jurisdiction that issued the TIN."},"tin_unavailable_reason":{"type":"string","description":"Set instead of `tin` where the jurisdiction legitimately issues or requires none. Empty when a TIN is held."},"residential_address":{"type":"string","description":"The individual seller's primary residence. Individual track only."},"residence_country":{"type":"string","description":"ISO-3166-1 alpha-2 country you live in; empty means the same as `country`."},"payout_bank_country":{"type":"string","description":"ISO-3166-1 alpha-2 country your payout bank is in."},"self_billing_accepted":{"type":"boolean"},"self_billing_vat_status":{"type":"string","enum":["unknown","registered","not_registered"],"description":"Your VAT position, as we hold it for the invoices we raise for you."},"self_billing_vat_number":{"type":"string"},"submitted_at":{"type":"string","format":"date-time","nullable":true},"reviewed_at":{"type":"string","format":"date-time","nullable":true},"rejection_reason":{"type":"string","description":"Shown to the seller verbatim. A rejection with no reason is repeated."},"subjects":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceVerificationSubject"}},"documents":{"type":"array","description":"Live documents only — superseded uploads are kept but not listed here.","items":{"$ref":"#/components/schemas/MarketplaceVerificationDocument"}},"document_requests":{"type":"array","items":{"$ref":"#/components/schemas/MarketplaceVerificationDocumentRequest"}}}},"MarketplaceVerificationDocument":{"type":"object","description":"A pointer to one uploaded document. The bytes live in object storage and are reached only through a short-lived signed URL; the object key is never published.","required":["id","kind","state","filename","content_type","size_bytes","uploaded_at"],"properties":{"id":{"type":"string","format":"uuid"},"kind":{"$ref":"#/components/schemas/MarketplaceDocumentKind"},"state":{"$ref":"#/components/schemas/MarketplaceDocumentState"},"subject_id":{"type":"string","format":"uuid","nullable":true},"filename":{"type":"string"},"content_type":{"type":"string"},"size_bytes":{"type":"integer"},"uploaded_at":{"type":"string","format":"date-time"},"rejection_reason":{"type":"string"},"expiry_basis":{"$ref":"#/components/schemas/MarketplaceDocumentExpiryBasis"},"valid_until":{"type":"string","format":"date","nullable":true,"description":"The one date the payout gate and the warning job compare against. Null until the document is accepted, and for documents that do not expire."}}},"MarketplaceVerificationDocumentRequest":{"type":"object","description":"Staff asking for a fresh document at any time (docs/82 §7a). Separate from expiry-driven refresh — this exists for when something looks wrong, and may hold payouts until it is satisfied.","required":["id","kind","reason","open","requested_at"],"properties":{"id":{"type":"string","format":"uuid"},"kind":{"$ref":"#/components/schemas/MarketplaceDocumentKind"},"reason":{"type":"string"},"due_on":{"type":"string","format":"date","nullable":true},"open":{"type":"boolean"},"requested_at":{"type":"string","format":"date-time"}}},"MarketplaceVerificationEnvelope":{"type":"object","required":["verification","requirements"],"properties":{"verification":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/MarketplaceVerification"}]},"requirements":{"$ref":"#/components/schemas/MarketplaceVerificationRequirements"}}},"MarketplaceVerificationRequirements":{"type":"object","description":"What the file still needs, computed from the track. ⭐ Published so a screen renders the checklist rather than re-implementing the track rules and drifting from them.","required":["missing","can_submit"],"properties":{"missing":{"type":"array","description":"Machine-readable tokens — `photo_id:missing:<subject_id>` for a person's document, `certificate_of_incorporation:missing` for a company-level one, `authorised_person:missing` when no one is named as able to act.","items":{"type":"string"}},"can_submit":{"type":"boolean"},"information_needed":{"type":"array","description":"The DATA tokens still owed (DAC7 items such as `dac7:tin`, and the country items `dac7:country_invalid`, `dac7:tin_issued_in_invalid`, `kyc:payout_bank_country`, `kyc:payout_bank_country_invalid`, `kyc:residence_country_invalid`). Never documents. On an approved file these hold the payout until supplied.","items":{"type":"string"}}}},"MarketplaceVerificationStart":{"type":"object","required":["track","legal_name"],"properties":{"track":{"$ref":"#/components/schemas/MarketplaceVerificationTrack"},"legal_name":{"type":"string","maxLength":300,"description":"The name exactly as it appears on the documents — a person's on the individual track, the company's on the company track. Not the storefront name: a storefront name is chosen and a legal name is given, and screening the wrong one screens nothing."},"country":{"type":"string","description":"ISO-3166-1 alpha-2."},"company_number":{"type":"string","maxLength":64},"registered_address":{"type":"string"},"tin":{"type":"string","maxLength":200,"description":"The seller's Tax Identification Number (docs/298 §2). For a UK **company** this is the CRN; for a UK **individual** their National Insurance number; elsewhere the local TIN. ⛔ Required before the file can be submitted or a payout released — HMRC's schema makes it a mandatory element, so a missing one is a return that cannot be produced, not a blank field. Give this OR `tin_unavailable_reason`, never both."},"tin_issued_in":{"type":"string","maxLength":2,"description":"ISO-3166-1 alpha-2 jurisdiction that ISSUED the TIN. ⛔ Not the same as `country`: a person resident in Ireland can hold a UK NI number, and reporting the residence country as the issuer is a wrong fact about a real taxpayer."},"tin_unavailable_reason":{"type":"string","enum":["jurisdiction_does_not_issue","jurisdiction_does_not_require"],"description":"Why there is no TIN, where there legitimately is none. ⛔ There is deliberately no \"seller refused\" value — that is not a reason a TIN is unavailable, it is the reason the payout is blocked. A stated reason is filed as `<TIN unknown=\"true\"/>`."},"residential_address":{"type":"string","description":"The individual seller's primary residence, as DAC7 asks for it. Individual track only — on the company track the primary address is `registered_address`, and a second column would be one address in two places free to disagree."},"residence_country":{"type":"string","maxLength":2,"description":"ISO-3166-1 alpha-2 country the seller LIVES in (KYC, `docs/82` §7a). Empty means the same as `country`. Refused (422 `RESIDENCE_COUNTRY_INVALID`) when it is not a country on the ISO list; omit the key to leave the stored value alone."},"payout_bank_country":{"type":"string","maxLength":2,"description":"ISO-3166-1 alpha-2 country the seller's payout bank is in (KYC, `docs/82` §7a). Required before a payout: a file without it reads `information_needed` and the payout is held with `country_details_incomplete`. Refused (422 `PAYOUT_BANK_COUNTRY_INVALID`) when it is not a country. ⭐ On an APPROVED file that owes information, this endpoint accepts the data items (country, residence and payout-bank country, TIN and its country, the residential address) and nothing else; the approval stands. `country` and `tin_issued_in` are refused the same way (`COUNTRY_INVALID`, `TIN_ISSUED_IN_INVALID`); a newly declared restricted country is refused with `COUNTRY_RESTRICTED`."},"accept_self_billing":{"type":"boolean","description":"Accept the self-billing agreement (docs/82 §8). Recorded with a timestamp and never cleared; required before the file can be submitted. Refused while `self_billing_vat_status` is `unknown` — we raise the invoice in your name, so we have to know your tax position before we do."},"self_billing_vat_status":{"type":"string","enum":["unknown","registered","not_registered"],"description":"Whether you are VAT registered. `not_registered` is a perfectly ordinary answer and self-bills correctly with no number on the document; what we cannot do is proceed without an answer, because an absent number would then mean either \"they are not registered\" or \"we never asked\" and the invoice would be wrong in one of those cases."},"self_billing_vat_number":{"type":"string","maxLength":32,"description":"Your VAT registration number. Required when `self_billing_vat_status` is `registered`: an invoice we raise in your name must show it, or neither of us can account for the tax on it."}}},"MarketplaceVerificationState":{"type":"string","description":"Where the identity file is. `expired` is reached automatically when a recorded document expiry passes; the payout gate re-reads the dates rather than trusting this column, so it holds even if the sweep has not run.","enum":["not_started","documents_requested","submitted","in_review","approved","rejected","expired"]},"MarketplaceVerificationSubject":{"type":"object","required":["id","kind","full_name","is_authorised","state"],"properties":{"id":{"type":"string","format":"uuid"},"kind":{"$ref":"#/components/schemas/MarketplaceVerificationSubjectKind"},"full_name":{"type":"string"},"ownership_percent":{"type":"integer","nullable":true,"minimum":25,"maximum":100,"description":"Null on the individual track and for a pure authorised signatory. A holding of 25% or less is refused rather than recorded."},"is_authorised":{"type":"boolean","description":"The person authorised to act. An individual is trivially that person."},"first_name":{"type":"string","description":"DAC7 given name. Blank when not supplied."},"last_name":{"type":"string","description":"DAC7 family name. Blank when not supplied."},"date_of_birth":{"type":"string","format":"date","nullable":true,"description":"DAC7 date of birth. Null when not supplied."},"state":{"$ref":"#/components/schemas/MarketplaceVerificationSubjectState"},"identity_verified":{"type":"boolean","description":"This person holds a valid identity check (verified, document not expired). The screen offers \"Verify your ID\" only to a person for whom this is false."},"rejection_reason":{"type":"string"}}},"MarketplaceVerificationSubjectCreate":{"type":"object","required":["kind","full_name"],"properties":{"kind":{"$ref":"#/components/schemas/MarketplaceVerificationSubjectKind"},"full_name":{"type":"string","maxLength":300},"ownership_percent":{"type":"integer","minimum":25,"maximum":100},"is_authorised":{"type":"boolean"},"first_name":{"type":"string","maxLength":200,"description":"DAC7 reports an individual seller's name as separate elements (docs/298 §2a). ⭐ Beside `full_name`, not instead of it: that is the name as it appears on the identity DOCUMENT, which is what a reviewer compares against a passport, and the two can legitimately differ."},"last_name":{"type":"string","maxLength":200},"date_of_birth":{"type":"string","format":"date","description":"⛔ Mandatory in HMRC's schema for an individual seller — `PersonParty_Type` declares `BirthInfo` without `minOccurs=\"0\"` — so a file without one produces a return HMRC rejects. Accepted for any subject and required only on the individual track: a company's beneficial owner is never reported, and demanding their date of birth would collect a person's data for no lawful purpose."}}},"MarketplaceVerificationSubjectKind":{"type":"string","description":"Why a natural person appears on the file. `primary` is the individual themselves, or the person authorised to act for a company; `beneficial_owner` is a holder of more than 25%. One person can be both.","enum":["primary","beneficial_owner"]},"MarketplaceVerificationSubjectState":{"type":"string","enum":["pending","approved","rejected"]},"MarketplaceVerificationSubjectUpdate":{"type":"object","description":"Only the keys present are changed.","properties":{"full_name":{"type":"string","minLength":1,"maxLength":300},"first_name":{"type":"string","maxLength":200},"last_name":{"type":"string","maxLength":200},"date_of_birth":{"type":"string","format":"date","nullable":true,"description":"ISO `YYYY-MM-DD`. A future date or another format is a 422 naming the field."}}},"MarketplaceVerificationTrack":{"type":"string","description":"Which set of rules the identity file is judged against (docs/82 §7a). The company track is not the individual track with extra fields: the required documents, the number of natural persons and the approval rule all differ.","enum":["individual","company"]},"MarketplaceVerifiedBadge":{"type":["object","null"],"description":"s1014 L69 (docs/1068 §9, owner Q8) — the listing-level Verified badge. Earned only by a reading Zinn® took itself from the source — Stripe payouts (`revenue`, read with the seller's read-only key) or Google Analytics 4 sessions (`traffic`, read over the seller's grant) — younger than the staff-set maximum age. Never a figure the seller typed or a file the seller uploaded. It says what we read and when, not that the business is good. `null` when the badge switch is off or no reading is fresh enough.","required":["sources","valid_until"],"properties":{"sources":{"type":"array","items":{"type":"object","required":["kind","by","at"],"properties":{"kind":{"type":"string","enum":["revenue","traffic"]},"by":{"type":"string","enum":["stripe","ga4"]},"at":{"type":"string","format":"date-time","description":"When we took the reading."}}}},"valid_until":{"type":"string","format":"date-time","description":"When the newest reading stops counting."}}},"MarketplaceVerifiedRevenue":{"type":"object","description":"s1014 L69 (Q6) — monthly recurring revenue of the business's ACTIVE Stripe subscriptions, read by Zinn® with the seller's read-only key and normalised to a month. `mrr_minor` is in the Stripe account's own `currency`; `mrr_usd_minor` is the same converted to US dollars at the marketplace's exchange rate (`rate` units of `currency` per dollar), or null when no current rate exists. `kept_verified` is true while the seller keeps it refreshed weekly. An empty object when there is no reading with a known MRR.","properties":{"provider":{"type":"string","enum":["stripe"]},"currency":{"type":"string"},"mrr_minor":{"type":"integer"},"mrr_usd_minor":{"type":["integer","null"]},"rate":{"type":["string","null"]},"active_subscriptions":{"type":["integer","null"]},"kept_verified":{"type":"boolean"},"measured_at":{"type":"string","format":"date-time"}}},"MarketplaceVerifiedTraffic":{"type":"object","description":"Q287 — \"GA4 verified traffic\": read from the seller's own GA4 property, which measures this listing's host. Empty (`{}`) when the listing has none, or when Google stopped accepting the seller's grant (a number we cannot re-check is not shown as verified).","properties":{"provider":{"type":"string","example":"ga4"},"sessions_30d":{"type":"integer","format":"int64"},"users_30d":{"type":"integer","format":"int64"},"sessions_90d":{"type":"integer","format":"int64"},"users_90d":{"type":"integer","format":"int64"},"measured_at":{"type":"string","format":"date-time"},"host":{"type":"string","description":"The host the property was matched on."}}},"MarketplaceVerticalPublicList":{"type":"object","required":["data","total"],"properties":{"data":{"type":"array","items":{"type":"object","required":["key","name","tagline"],"properties":{"key":{"type":"string","description":"The URL segment — `link_building`, `guest_posts`, …"},"name":{"type":"string"},"tagline":{"type":"string"}}}},"total":{"type":"integer"}}},"McpClient":{"type":"string","description":"The AI client a connection is for (informational).","enum":["claude_code","claude_desktop","cursor","chatgpt","other"]},"McpConnection":{"type":"object","description":"An MCP connection's metadata (never the token or its hash).","required":["id","name","client","prefix","scopes","sandbox","spend_window_seconds","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"name":{"type":"string","example":"My Claude Code"},"client":{"$ref":"#/components/schemas/McpClient"},"prefix":{"type":"string","description":"The token's public lookup prefix (not a secret).","example":"EXAMPLEPREFIX00"},"scopes":{"type":"array","description":"The RBAC permission keys this connection's token may exercise.","items":{"type":"string"},"example":["sites.view","domains.dns.manage"]},"sandbox":{"type":"boolean"},"kind":{"type":"string","enum":["token","oauth"],"description":"`token` = a pasted token; `oauth` = an AI app that signed in (docs/27 §3a)."},"oauth_client_name":{"description":"For `kind: oauth`, the app's own name as it registered.","anyOf":[{"type":"string"},{"type":"null"}]},"spend_cap_minor":{"description":"Optional per-window budget (integer minor units, CLAUDE.md §2.8) for AI-triggered paid actions. Null = no cap.","anyOf":[{"type":"integer","format":"int64"},{"type":"null"}]},"spend_currency":{"$ref":"#/components/schemas/CurrencyCode"},"spend_window_seconds":{"type":"integer","description":"The rolling window the spend cap applies over.","example":86400},"last_used_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"revoked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"}}},"McpConnectionCreate":{"type":"object","required":["name","scopes"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100,"example":"My Claude Code"},"client":{"$ref":"#/components/schemas/McpClient"},"scopes":{"type":"array","description":"RBAC permission keys to grant the token. Each must be a permission the caller holds in the target org (a connection can never out-scope its creator); an unheld scope is a `403`, an unknown one a `422`.","items":{"type":"string","maxLength":100},"example":["sites.view","domains.dns.manage","sites.cache.purge"]},"sandbox":{"type":"boolean","default":false},"org_id":{"description":"The org the connection belongs to. Defaults to the caller's sole managed org.","anyOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]},"spend_cap_minor":{"description":"Optional per-window paid-action budget (integer minor units). Null = no cap.","anyOf":[{"type":"integer","format":"int64","minimum":0},{"type":"null"}]},"spend_currency":{"$ref":"#/components/schemas/CurrencyCode"},"spend_window_seconds":{"type":"integer","minimum":60,"maximum":2592000,"default":86400}}},"McpConnectionCreated":{"allOf":[{"$ref":"#/components/schemas/McpConnection"},{"type":"object","required":["token","endpoint","config","config_file","command","note"],"properties":{"token":{"type":"string","description":"The full `zmcp_…` token, shown exactly once.","example":"zmcp_live_EXAMPLE000000000_EXAMPLEONLYNOTAREALKEY00"},"endpoint":{"type":"string","format":"uri","description":"The MCP protocol endpoint URL to configure in the AI client."},"config":{"type":"object","additionalProperties":true,"description":"A paste-ready config for the connection's `client`, embedding the endpoint and token. The shape differs per client: Claude Code gets an `http`-typed server, Cursor a `url` + `headers` server, and Claude Desktop a local `zinnector mcp` bridge with the token in `env` (Desktop cannot express a remote server with a header)."},"config_file":{"type":["string","null"],"description":"Where that client reads `config` — e.g. `.mcp.json`. `null` when it has no file.","example":".mcp.json"},"command":{"type":["string","null"],"description":"A one-line alternative for a client with a command line (Claude Code), else `null`. It embeds the token, so treat it like the token."},"note":{"type":["string","null"],"enum":["chatgpt_needs_oauth",null],"description":"Set when the client cannot use a bearer token at all. `chatgpt_needs_oauth`: ChatGPT connects by OAuth sign-in only, so this token cannot reach it."}}}]},"McpConnectionPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/McpConnection"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"McpGrantableScope":{"type":"object","required":["scope","tools","destructive_tools","held"],"properties":{"scope":{"type":"string","description":"The RBAC permission key, e.g. `sites.view`.","example":"sites.view"},"tools":{"type":"integer","description":"How many registered MCP tools this scope unlocks.","example":15},"destructive_tools":{"type":"integer","description":"How many of those tools are destructive and therefore require an explicit confirmation on every call.","example":0},"held":{"type":"boolean","description":"Whether the caller holds this permission in the target organization. A scope the caller does not hold cannot be granted to a connection."}}},"McpGrantableScopePage":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/McpGrantableScope"}}}},"McpOAuthApproveRequest":{"type":"object","required":["scopes"],"properties":{"org_id":{"$ref":"#/components/schemas/Uuid"},"scopes":{"type":"array","minItems":1,"items":{"type":"string"}}}},"McpOAuthConsentRequest":{"type":"object","required":["id","client","redirect_host","requested_scopes","offered_scopes","resource"],"properties":{"id":{"type":"string"},"client":{"type":"object","required":["name","kind"],"properties":{"name":{"type":"string","example":"Claude"},"uri":{"type":"string"},"logo_uri":{"type":"string"},"kind":{"type":"string","enum":["dcr","cimd"]},"verified_domain":{"description":"For a metadata-document client, the domain its id is served from.","anyOf":[{"type":"string"},{"type":"null"}]}}},"redirect_host":{"type":"string","example":"claude.ai"},"requested_scopes":{"type":"array","items":{"type":"string"}},"offered_scopes":{"type":"array","items":{"type":"string"},"description":"The permissions this client can use: each grants at least one tool the client is served. A connector directory's app (Claude, ChatGPT) gets a narrower tool set (docs/925 §1a), so a permission whose only tools that app leaves out (image generation, purchases) is not offered. The consent screen lists only these, and approving any other answers `422`."},"resource":{"type":"string","format":"uri"}}},"McpOAuthRedirect":{"type":"object","required":["redirect_url"],"properties":{"redirect_url":{"type":"string","description":"Where to send the browser next."},"connection_id":{"$ref":"#/components/schemas/Uuid"}}},"MediaStorageBlockPrice":{"type":"object","required":["amount_minor","currency","per_gb","interval"],"properties":{"amount_minor":{"type":"integer","format":"int64","description":"Integer minor units of `currency` — never a float, never formatted."},"currency":{"type":"string","description":"ISO 4217, uppercase."},"per_gb":{"type":"integer","description":"Gigabytes in one priced block. Overage is charged per whole block, rounded up."},"interval":{"type":"string","enum":["month"],"description":"The period the price is charged over. Stated rather than implied: a recurring price with no period on it reads as one-off, and on a meter that is an order-of-magnitude misunderstanding in the customer's disfavour."}}},"MediaStorageTerms":{"type":"object","description":"What this site's organisation gets included for media storage, what it is using, and what more would cost. Present on **every** media-offload response, including `configured: false` — the state in which a customer is deciding whether to switch a metered feature on is the one state in which the price has to be legible, and a price you can only learn by incurring it is not a disclosed price.\n\nMedia offload is **not a separate add-on**. It is an allowance in the plan plus metered overage beyond it.","required":["unlimited","included_gb","used_gb","over_gb","measured","price"],"properties":{"unlimited":{"type":"boolean","description":"`true` when the plan's media storage is uncapped. **Check this before `included_gb`.** The estate's UNLIMITED sentinel is `-1`, and it is deliberately never put on this wire: a client rendering the raw number would say \"included: -1 GB\" and quote an overage to somebody who was sold no cap. When this is `true`, `included_gb` is `null` and `over_gb` is always `0`.\n\n⛔ `unlimited: true` and \"this plan does not sell storage\" therefore BOTH carry `included_gb: null`, and they are opposite facts — everything versus nothing. This flag is the only thing that separates them."},"included_gb":{"type":"integer","nullable":true,"description":"Gigabytes of media storage the plan includes. `null` and `0` are different answers: `null` means this plan does not sell storage at all (**or** that it is uncapped — see `unlimited`), `0` means it does and includes none. A screen renders the first as an upsell and the second as a limit; collapsing them tells a customer they have used up an allowance nobody ever sold them."},"used_gb":{"type":"number","format":"double","description":"Decimal gigabytes currently stored, rounded to three places."},"over_gb":{"type":"number","format":"double","description":"Gigabytes beyond the allowance, `0` when inside it, when there is no allowance, and always when `unlimited`. Never negative — a negative would be billed as a credit by anything that multiplies it by a rate."},"measured":{"type":"boolean","description":"Whether `used_gb` is an observation rather than a default. `false` means nobody has measured this organisation yet, and an unmeasured bucket set looks exactly like an empty one — so a screen must not draw the second when it has the first."},"price":{"nullable":true,"description":"What one block beyond the allowance costs, in the currency this customer is actually billed in. `null` means **not priced** — no rate is in force, or no FX leg exists for their currency — which is not the same as free, and must not be rendered as an amount.","allOf":[{"$ref":"#/components/schemas/MediaStorageBlockPrice"}]}}},"MemberRoleChange":{"type":"object","description":"The new role for a member. Replaces every role they hold in this org — see `PATCH /v1/orgs/{orgId}/members/{userId}`.","required":["role"],"properties":{"role":{"type":"string","maxLength":64,"description":"A role key from `GET /v1/orgs/{orgId}/roles`.","example":"billing"}}},"Membership":{"type":"object","required":["org_id","role"],"properties":{"org_id":{"$ref":"#/components/schemas/Uuid"},"role":{"type":"string","description":"RBAC role key within the org (docs/06 §2).","example":"owner"}}},"MentionPhrase":{"type":"object","description":"One phrase to listen for across the public web, and how often. The phrase is matched as a PHRASE, not as loose words — \"acme widgets\" finds pages containing those two words together.","required":["phrase"],"properties":{"phrase":{"type":"string","minLength":3,"maxLength":200},"frequency":{"type":"string","enum":["daily","weekly","monthly"],"default":"weekly","description":"How often this phrase is checked. Each check counts against the plan's monthly checks; a schedule that would plan more checks a month than the plan includes is refused (daily counts as 30, weekly as 4.34, monthly as 1)."}}},"MentionPhraseState":{"allOf":[{"$ref":"#/components/schemas/MentionPhrase"},{"type":"object","properties":{"next_check_at":{"type":["string","null"],"format":"date-time","description":"When the next scheduled check runs. `null` means on the next sweep."},"last_checked_at":{"type":["string","null"],"format":"date-time","description":"When this phrase was last checked. `null` means never — which is not the same as \"checked and nobody mentions you\"."}}}]},"MenuSection":{"type":"string","description":"A dashboard menu section staff may hide for one organization. `marketplace` = the marketplace section (browse, purchases, aged domains, freelancers, projects, messages); `seller` = selling, earnings and the seller account; `reseller` = the reselling section; `agency` = agency boards, time tracking, client reports, clients and invoicing.","enum":["marketplace","seller","reseller","agency"]},"MigrationAgentConversation":{"type":"object","required":["id","title","opened_by","site_id","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string","description":"Your own opening words, trimmed — never a generated summary."},"opened_by":{"type":"string","enum":["customer","staff","agent"]},"site_id":{"type":"string","format":"uuid","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"MigrationAgentConversationDetail":{"allOf":[{"$ref":"#/components/schemas/MigrationAgentConversation"},{"type":"object","required":["turns"],"properties":{"turns":{"type":"array","items":{"$ref":"#/components/schemas/MigrationAgentTurn"}}}}]},"MigrationAgentConversationList":{"type":"object","required":["conversations"],"properties":{"conversations":{"type":"array","items":{"$ref":"#/components/schemas/MigrationAgentConversation"}}}},"MigrationAgentMessage":{"type":"object","required":["message"],"properties":{"message":{"type":"string","maxLength":4000,"description":"What you want, in your own words.","example":"Move my site from oldhost.example.com onto my WordPress plan."},"conversation_id":{"type":"string","format":"uuid","nullable":true,"description":"Continue an existing thread. Omit to start a new one."},"site_id":{"type":"string","format":"uuid","nullable":true,"description":"The site this thread is about, when you already know it."},"confirm":{"type":"array","description":"The actions you approve **for this message**, by name. The assistant cannot act on anything that is not in this list, however it words its own request — the platform compares its claim against what you sent.\n\nIt is a list of names rather than a single yes/no on purpose: agreeing to start a migration is not agreeing to roll one back, and one flag would make those the same word.","items":{"type":"string","enum":["migration_start","migration_start_new_site","migration_cancel","migration_rollback"]},"example":["migration_start"]},"credentials":{"type":"object","additionalProperties":true,"writeOnly":true,"description":"The login for your old host, in the same shape `POST /v1/sites/{siteId}/migrations` takes. Used for this request only: it is never stored on the conversation, never returned by any endpoint, and never shown to the model — the assistant is told whether a login was supplied and nothing more."}}},"MigrationAgentReply":{"type":"object","required":["conversation","turns"],"properties":{"conversation":{"$ref":"#/components/schemas/MigrationAgentConversation"},"turns":{"type":"array","description":"Both turns of this exchange — what you asked and what it answered.","items":{"$ref":"#/components/schemas/MigrationAgentTurn"}},"failure":{"type":"object","nullable":true,"additionalProperties":true,"description":"Present only when the assistant itself could not be reached. It says which kind of failure it was, so you are told whether an AI provider is having an outage, whether your own API key needs attention, or whether the fault is ours. Your migration is unaffected by it either way."}}},"MigrationAgentToolCall":{"type":"object","required":["name","ok"],"properties":{"name":{"type":"string","description":"The action, e.g. `migration_discover` or `migration_start`."},"arguments":{"type":"object","additionalProperties":true,"description":"What it was asked to act on. Never contains a credential."},"ok":{"type":"boolean","description":"Whether it succeeded."},"code":{"type":"string","description":"The refusal's machine code when `ok` is false, else empty."},"claimed_unconfirmed":{"type":"boolean","description":"True when the assistant asserted an approval you had not given. The action did not run. Shown to you rather than only logged: it is your site, and the attempt is a fact you are entitled to see."}}},"MigrationAgentTurn":{"type":"object","required":["id","actor","body","tool_calls","failure_code","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"actor":{"type":"string","enum":["customer","staff","agent"],"description":"Who spoke. `staff` is a Zinn® operator acting on your behalf."},"body":{"type":"string"},"tool_calls":{"type":"array","items":{"$ref":"#/components/schemas/MigrationAgentToolCall"}},"failure_code":{"type":"string","description":"Set when the assistant could not answer at all — a machine code, so the screen can say it in your own language and link a provider's own status page for an outage. Empty when nothing failed."},"created_at":{"type":"string","format":"date-time"}}},"MigrationCredentials":{"type":"object","required":["source","host","username"],"additionalProperties":false,"writeOnly":true,"description":"Where to pull from, and how to sign in. ⛔⛔ **These are live credentials for a third party's production server.** They are written straight to the platform's secret store, referenced from the job by a Vault path, deleted when the job ends, and are never returned by any endpoint, never written to an audit record and never quoted in an error. The job row keeps the **hostname only**.","properties":{"source":{"$ref":"#/components/schemas/MigrationSource"},"host":{"type":"string","maxLength":253,"description":"The server's public hostname, e.g. `server123.yourhost.com`. Must resolve to a public address — a private or link-local target is refused with `source_host_not_public` at the door as well as in the adapter."},"username":{"type":"string","maxLength":255,"description":"The login for the source panel or account."},"port":{"type":"integer","minimum":0,"maximum":65535,"default":0,"description":"`0` means the source driver's default for that panel."},"password":{"type":"string","maxLength":4096,"writeOnly":true},"private_key":{"type":"string","maxLength":16384,"writeOnly":true,"description":"An SSH private key in PEM form, for an `ssh` source."},"api_token":{"type":"string","maxLength":4096,"writeOnly":true},"include_mail":{"type":"boolean","default":true,"description":"⚖️ Defaults to true, and a source that cannot deliver mailboxes is **refused rather than silently migrated without them** — a migration that moves a website and loses the mail is worse for the customer than no migration. Untick it to move the website only."},"mailbox_passwords":{"type":"object","writeOnly":true,"additionalProperties":{"type":"string","maxLength":1024},"description":"`address -> password`, for every mailbox being moved. Required up front rather than discovered mid-sync: most panels will not hand over a mailbox without its own password, and finding that out at 90% leaves the customer with half their mail on each side. At most 500 entries."},"database_host":{"type":"string","maxLength":253,"default":"","description":"Optional. The source database server as the site itself reaches it (usually `localhost`). Used with the other `database_*` fields."},"database_port":{"type":"integer","minimum":0,"maximum":65535,"default":0,"description":"Optional. `0` means the database server's default port."},"database_username":{"type":"string","maxLength":255,"default":"","description":"Optional. The source site's own database login. An `ssh` source otherwise uses the account's `~/.my.cnf` or the site's `wp-config.php`; a login sent here wins over both. An `ftp` source hands it to its one-time helper, and only over a verified https address. Stored in the secret store with the rest, never returned."},"database_password":{"type":"string","maxLength":4096,"writeOnly":true,"default":""},"database_name":{"type":"string","maxLength":255,"default":"","description":"Optional. The site's database. With several sites under one `ssh` login it also tells the driver which folder is this site's."}}},"MigrationDiscoveryCandidate":{"type":"object","required":["source","port","confidence","signals"],"description":"One possible source, with the evidence for it rather than a bare score, so a customer who disagrees with the answer can see what it rests on.","properties":{"source":{"type":"string"},"port":{"type":"integer"},"confidence":{"type":"integer","minimum":0,"maximum":100},"signals":{"type":"array","description":"Machine codes from the evidence vocabulary — `panel_banner`, `panel_port`, `transport_port`, `ai_identified`. Localised by the client; never shown as-is.","items":{"type":"string"}}}},"MigrationDiscoveryRequest":{"type":"object","required":["host"],"additionalProperties":false,"description":"⛔ A hostname, and deliberately **nothing else**. The whole value of this step is that it runs before a password exists — a prospect can be told what they are on, and what we will be able to take, without having trusted us with anything. A credential field here would put a third party's login on the wire for a request that cannot use it.","properties":{"host":{"type":"string","maxLength":253,"description":"The server address the current host gave them, e.g. `server123.theirhost.com`. A hostname, not a web address — no scheme and no path. The customer's own domain works too when it still resolves to the old host."}}},"MigrationDiscoveryResult":{"type":"object","required":["outcome","host","source","port","confidence","confident","candidates","expectations","routes","proxy_fronted","refused","agent_used","agent_unavailable","discovery_id","timed_out"],"properties":{"outcome":{"type":"string","enum":["pending","identified","unidentified","unreachable"],"description":"`pending` while the discovery workflow is still probing — poll `getMigrationDiscovery` until it is one of the other three (D19865). ⛔ Three answers and never a boolean. `unidentified` means something answered and we cannot place it — a candidate for the managed migration. `unreachable` means nothing answered at all — usually a typo or a firewall. Opposite remedies; folding them hands both populations the same wrong advice."},"host":{"type":"string","description":"The hostname as it was normalised, which may differ from what was typed."},"source":{"type":"string","description":"The best candidate's `MigrationSource`, or `\"\"` when there is none."},"port":{"type":"integer","description":"The **login** port for that source, which is not necessarily the port the evidence came from: a banner read from cPanel's plaintext 2082 reports 2083, because that is where the credential must go."},"confidence":{"type":"integer","minimum":0,"maximum":100},"confident":{"type":"boolean","description":"May the credential form be pre-filled from this?"},"candidates":{"type":"array","items":{"$ref":"#/components/schemas/MigrationDiscoveryCandidate"}},"expectations":{"type":"array","description":"Machine codes for what to expect from the winning source — e.g. `ftp_files_only`. ⛔ Expectations, not a capability claim: the authoritative answer comes from the credentialed probe that follows.","items":{"type":"string"}},"routes":{"type":"array","description":"Every way in that was tried. Read it when a panel is firewalled — a host with 2083 closed and 22 open can still have everything moved.","items":{"$ref":"#/components/schemas/MigrationDiscoveryRoute"}},"proxy_fronted":{"type":"boolean","description":"This address is a CDN in front of a website, not a hosting account — several different panels' login ports accepted a connection at once and none of them answered with its own name, which is a proxy rather than a host. Almost always means the customer typed their web address instead of the server address their host gave them. When true, `source` is deliberately empty rather than a guess."},"refused":{"type":"string","description":"A customer-readable reason the hostname was rejected before any packet went out — a private address, an unresolvable name. `\"\"` otherwise."},"agent_used":{"type":"boolean","description":"Whether a language model was asked to read the sign-in page. It is asked only when the deterministic table produced no confident panel."},"agent_unavailable":{"type":"string","description":"Machine code when the model was asked and could not answer (`ai_unavailable`, `ai_timeout`, …). `\"\"` when it was not asked or it answered. ⛔ The deterministic answer stands either way."},"timed_out":{"type":"boolean","description":"The check hit its 120 s hard deadline before it finished. `outcome` is `unreachable`, but the host was slow rather than silent, so a screen must say \"too slow to check, try again\" and never \"nothing answered\"."},"discovery_id":{"type":"string","description":"The recorded run, for support. `\"\"` when the row could not be written — which never costs the customer their answer."}}},"MigrationDiscoveryRoute":{"type":"object","required":["route","port","open","checked"],"description":"One way in, and whether it answered. ⛔ Tri-state: `checked: false` means we never got to try (the hostname was refused, or the budget was spent), which is **not** `open: false`.","properties":{"route":{"type":"string","description":"The `MigrationSource` this port is a way in for."},"port":{"type":"integer"},"open":{"type":"boolean"},"checked":{"type":"boolean"}}},"MigrationDnsPlan":{"type":"object","required":["zone","destination","blocked","blocks","advisories","publish","withheld"],"description":"The **dry run**: exactly what the cutover will do to the zone, before it does it. Computed by the same function the cutover publishes from, so it cannot drift from what actually happens.","properties":{"zone":{"type":"string"},"destination":{"type":"string","description":"The origin address the site's own records will point at."},"blocked":{"type":"boolean","description":"`true` means the cutover will publish **nothing** and leave the customer's DNS where it is. A half-published zone is worse than an unpublished one, because the customer is then authoritative for a zone that answers wrongly."},"blocks":{"type":"array","items":{"type":"string","enum":["no_destination_address","no_dns_captured","source_zone_has_no_apex_address"]}},"advisories":{"type":"array","items":{"type":"string","enum":["caa_restricts_certificate_issuance"]}},"publish":{"type":"array","items":{"$ref":"#/components/schemas/MigrationPlannedRecord"}},"withheld":{"type":"array","items":{"$ref":"#/components/schemas/MigrationWithheldRecord"}}}},"MigrationDnsRecord":{"type":"object","required":["name","type","value","ttl","disposition"],"description":"One record read off the source's zone. Together these are the **dry run** for the DNS half: before the cutover they say exactly what will be published, and the `unsupported` rows say what could not be brought while the old host still exists to read them off.","properties":{"name":{"type":"string","description":"Relative to the zone, with the apex as `@`."},"type":{"type":"string"},"value":{"type":"string"},"ttl":{"type":"integer","description":"The TTL **as the source published it** — never the lowered cutover TTL. This is the value a rollback restores."},"priority":{"type":"integer","nullable":true},"disposition":{"type":"string","enum":["migratable","unsupported"]},"reason":{"type":"string","description":"Machine code on an unsupported row; empty on a migratable one."}}},"MigrationPlannedRecord":{"type":"object","required":["name","type","value","ttl"],"description":"One record as the cutover will publish it.","properties":{"name":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"ttl":{"type":"integer","description":"The **lowered** cutover TTL, unlike `MigrationDnsRecord.ttl`."},"priority":{"type":"integer","nullable":true},"repointed_from":{"type":"string","description":"The source's value when we are changing it; empty on a verbatim copy. Repointing is the only part of a cutover that can take a site down, so the old and new values are shown side by side."}}},"MigrationReport":{"type":"object","required":["verification_code","findings","next_steps","narrative","locale","agent_unavailable","created_at"],"description":"What the customer is told about a finished migration. Composed from the job's own counters, with a narrative added by the assistant when it is reachable. ⛔ A job whose assistant call failed gets this object with an empty `narrative` and `agent_unavailable` set — **never** no report, because \"no report\" is indistinguishable on a screen from \"still running\".","properties":{"verification_code":{"type":"string","description":"The destination-vs-source verdict at the moment the report was written, or `\"\"` for a clean pass. A machine code — `findings` is the part meant for a human."},"findings":{"type":"array","description":"What happened, most important first, as machine codes the client localises. A closed vocabulary: the assistant is told it is closed and anything outside it is dropped rather than shown.","items":{"type":"string"}},"next_steps":{"type":"array","description":"What is the customer's to do, as machine codes. Separate list, separate question.","items":{"type":"string"}},"narrative":{"type":"string","description":"Prose already in `locale` — generated *in* the language, so it is not localisable after the fact. `\"\"` when the assistant was unavailable."},"locale":{"type":"string"},"agent_unavailable":{"type":"string","description":"Why there is no narrative, as a machine code. ⭐ Present on purpose: a customer is entitled to know their report is the plain version rather than left wondering why it is short."},"created_at":{"type":"string","format":"date-time"}}},"MigrationRollback":{"type":"object","required":["available","reason"],"description":"Whether this migration can be put back, and — when it cannot — why not. ⛔⛔ `reason` travels with `available`, always. Six different facts render as the same absent button otherwise, and a customer looking at a migration that replaced their shop is owed the specific one.","properties":{"available":{"type":"boolean"},"reason":{"type":"string","description":"A machine code the dashboard localises; `\"\"` when `available` is true. One of `nothing_was_replaced`, `already_rolled_back`, `migration_not_finished`, `window_expired`, or `no_safety_backup:<state>` — where the tail is the `safety_backup_state`, so one key family covers all four of its cases.","example":"no_safety_backup:unsupported"},"backup_id":{"type":"string","description":"The archive the rollback would restore, or `\"\"`."},"expires_at":{"type":"string","format":"date-time","nullable":true,"description":"When the 30-day offer lapses. `null` when the job has no finish time yet, which is not the same as a deadline that has passed."}}},"MigrationSource":{"type":"string","enum":["cpanel","plesk","directadmin","ftp","ssh"],"description":"The kind of hosting the site is being pulled from. ⛔ `plesk` is offered so the refusal can be specific and actionable, **not** because it is supported: `pleskbackup` is reachable only through Plesk's admin-only CLI passthrough, so a customer-level login yields a complete inventory and no bytes at all. Sending it returns 422 with `plesk_needs_admin_credentials`, which tells the customer to ask their host for an admin login or buy Managed Migration."},"MigrationSourceDatabase":{"type":"object","required":["name","size_bytes"],"properties":{"name":{"type":"string"},"size_bytes":{"type":"integer","description":"As the source reports it. ⛔ `0` means unknown, never empty."}}},"MigrationSourceInventory":{"type":"object","required":["domains","files","databases","mailboxes","total_bytes","truncated","unavailable","mailboxes_without_passwords"],"properties":{"domains":{"type":"array","items":{"type":"string"}},"files":{"type":"integer","description":"How many files were found. A count, not the list — a 5,000-file estate is not a form field, and the per-item rows are written by the job."},"databases":{"type":"array","items":{"$ref":"#/components/schemas/MigrationSourceDatabase"}},"mailboxes":{"type":"array","items":{"$ref":"#/components/schemas/MigrationSourceMailbox"}},"total_bytes":{"type":"integer"},"truncated":{"type":"boolean","description":"True when the source stopped short of a complete listing. Reported, never swallowed."},"unavailable":{"type":"object","additionalProperties":{"type":"string"},"description":"⭐ **The most important field here**: `capability -> machine code`, naming what we could not look at. An empty object means \"we looked and there is nothing else\", which is a different claim from \"we could not look\" — and a client that renders the two the same tells a customer they have no mail when in fact we simply could not read it. An `ftp` source reads its database through a one-time PHP helper (docs/1296); when it cannot, `site_migration:databases` carries one of `bridge_php_not_run`, `bridge_blocked`, `bridge_site_password`, `bridge_site_unreachable`, `bridge_site_not_on_source`, `bridge_upload_refused`, `bridge_no_site_domain`, `bridge_no_mysql_in_php`, `bridge_config_not_found`, `bridge_database_login_refused` (both fixable with the `database_*` login), `bridge_database_not_mysql`, `bridge_query_failed`, or `ftp_login_cannot_reach_mysql` (no site address or no database config to look for)."},"mailboxes_without_passwords":{"type":"array","items":{"type":"string"},"description":"The addresses no usable password was supplied for. The form points at exactly these rows; a create with any of them present is refused with `mailbox_passwords_required`."}}},"MigrationSourceMailbox":{"type":"object","required":["address","size_bytes","messages","has_password"],"properties":{"address":{"type":"string"},"size_bytes":{"type":"integer"},"messages":{"type":"integer","description":"The panel's estimate. The IMAP sync counts for real; this is here so the customer can see what is about to move."},"has_password":{"type":"boolean","description":"Whether a usable password was supplied for this mailbox. ⛔ `false` is a **blocking** condition surfaced on the form, not a warning logged hours later when the sync reaches this address."}}},"MigrationWithheldRecord":{"type":"object","required":["name","type","value","reason"],"description":"A record read off the source that the cutover will deliberately NOT serve. ⛔ Distinct from an *unsupported* record, which we cannot express: this one we can express and have chosen not to publish.","properties":{"name":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"reason":{"type":"string","enum":["source_nameservers","no_ipv6_destination"],"description":"`source_nameservers` — the old host's apex `NS` set, which would re-delegate the zone back to the host being migrated away from. `no_ipv6_destination` — an `AAAA` with nowhere to point, which copied verbatim would serve the OLD site to IPv6 visitors while every IPv4 check reported the migration perfect."}}},"MoneyAmount":{"type":"object","description":"A money value — integer minor units + an ISO 4217 code (CLAUDE.md §2.8).","required":["amount_minor","currency"],"properties":{"amount_minor":{"type":"integer","format":"int64","example":3000},"currency":{"$ref":"#/components/schemas/CurrencyCode"}}},"MoodleBlockedRelease":{"type":"object","description":"A newer Moodle release this server cannot run, and why.","required":["release","branch","refusal"],"additionalProperties":false,"properties":{"release":{"type":"string"},"branch":{"type":"string"},"refusal":{"$ref":"#/components/schemas/MoodleRefusal"}}},"MoodleBranchPin":{"type":"object","description":"Whether the site stays on its installed Moodle branch (docs/1160 §10). Following new major versions is the default; a site is kept on its branch automatically while a plugin would break on the newest major (`source` `plugins`, `held_by` names them) or when the customer chose so. A pinned site still gets its branch's own weekly builds.","required":["pinned","source","branch","held_by"],"additionalProperties":false,"properties":{"pinned":{"type":"boolean"},"source":{"type":"string","enum":["follow","plugins","customer_pin","customer_follow"]},"branch":{"type":"string","nullable":true,"description":"`4.5`; null before the first check."},"held_by":{"type":"array","description":"Plugins that would break on the newest release on another branch.","items":{"type":"string"}}}},"MoodlePluginWarning":{"type":"object","required":["component","key","reason"],"additionalProperties":false,"properties":{"component":{"type":"string"},"key":{"type":"string","enum":["formatTilesModalFactory","unsupportedBranch"]},"reason":{"type":"string"}}},"MoodleRefusal":{"type":"object","description":"Why a Moodle upgrade cannot run. `key` is `refusal.moodleUpgrade.<camel>`; `params` fill it; `message` is the English fallback.","required":["code","key","params","message"],"additionalProperties":false,"properties":{"code":{"type":"string","enum":["NOT_MOODLE","NOT_OWN_FLEET","NOT_ACTIVE","NOT_CHECKED","UP_TO_DATE","UPGRADE_RUNNING","TARGET_NOT_OFFERED","DB_TOO_OLD","PHP_TOO_OLD","PLUGIN_INCOMPATIBLE","REQUIREMENTS_UNKNOWN","BRANCH_PINNED"]},"key":{"type":"string"},"params":{"type":"object","additionalProperties":{"type":"string"}},"message":{"type":"string"}}},"MoodleRelease":{"type":"object","description":"One Moodle release (s1014, docs/1160).","required":["version","release","branch"],"additionalProperties":false,"properties":{"version":{"type":"string","description":"Moodle's internal version, e.g. 2025100604.00."},"release":{"type":"string","description":"The human release, e.g. 5.2.4+ (Build: 20261024)."},"branch":{"type":"string","description":"The branch, e.g. 5.2."}}},"MoodleUpgradeRun":{"type":"object","description":"One Moodle upgrade (manual or scheduled). `rolled_back` = the upgrade failed and the site was restored to `from_release`, healthy. `failed` = the upgrade did not happen; `error_code` says whether the site was untouched (DOWNLOAD_FAILED, BACKUP_FAILED, MAINTENANCE_FAILED) or the restore itself failed (ROLLBACK_FAILED, staff alerted). `held` = a scheduled update was not applied (a plugin, the staging copy, no add-on).","required":["id","kind","state","step","from_release","to_release","error_code","message","message_key","plugin_holds","backup_kept_until","created_at","started_at","finished_at"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["manual","scheduled"]},"state":{"type":"string","enum":["queued","running","succeeded","rolled_back","failed","held"]},"step":{"type":"string","nullable":true,"description":"The step the run is on (or stopped at)."},"from_release":{"type":"string","nullable":true},"to_release":{"type":"string","nullable":true},"error_code":{"type":"string","nullable":true,"enum":["DOWNLOAD_FAILED","BACKUP_FAILED","MAINTENANCE_FAILED","UPGRADE_FAILED","HEALTH_FAILED","ROLLBACK_FAILED","STAGING_FAILED","PLUGIN_INCOMPATIBLE","NOT_ENTITLED"]},"message":{"type":"string","nullable":true,"description":"English."},"message_key":{"type":"string","nullable":true,"description":"`moodleUpgrade.error.<camel>` for `error_code`, or null."},"plugin_holds":{"type":"array","items":{"type":"object","required":["component","reason"],"additionalProperties":false,"properties":{"component":{"type":"string"},"reason":{"type":"string"}}}},"backup_kept_until":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time","nullable":true},"finished_at":{"type":"string","format":"date-time","nullable":true}}},"MyXeroSyncRun":{"type":"object","description":"What one manual sync did.","required":["pushed","failed","remaining"],"properties":{"pushed":{"type":"integer"},"failed":{"type":"integer"},"remaining":{"type":"integer","description":"Still outstanding after this batch. ⛔ Reported so a client never infers \"finished\" from a short batch — some rows may have failed rather than completed."},"connection":{"$ref":"#/components/schemas/XeroConnection"}}},"Nameservers":{"type":"object","required":["nameservers"],"properties":{"nameservers":{"type":"array","minItems":2,"maxItems":13,"items":{"type":"string","maxLength":253},"example":["ns1.zinndigital.com","ns2.zinndigital.com"]},"force":{"type":"boolean","writeOnly":true,"description":"Set the nameservers even when they publish no address for the domain's apex (otherwise refused with a 409 `refusal.dns.nameserversPublishNoApex`). Optional; false when omitted. Never returned."}}},"Notice":{"type":"object","description":"One notice as the customer's dashboard receives it.","required":["id","key","tone","title","body_html","body_i18n_key","body_params","dismissible"],"properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string","description":"The stable idempotency key. Useful for client-side deduplication."},"tone":{"$ref":"#/components/schemas/NoticeTone"},"title":{"type":"string","description":"Optional heading, already localized. Plain text, never markup."},"body_html":{"type":"string","description":"The operator's body, **already sanitised** to a formatting allow-list (`a`, `b`, `br`, `code`, `em`, `i`, `li`, `ol`, `p`, `small`, `span`, `strong`, `u`, `ul`; `href`/`title` only, `https`/`mailto` only) and already localized into the reader's language. Safe to render as HTML. Empty when `body_i18n_key` is set."},"body_i18n_key":{"type":"string","description":"A message key for a system-raised notice — the SPA renders `notice.body.<key>` from its own catalogue with `body_params`. The engine refuses a key it has not registered, so this is never an unknown string. Empty when `body_html` is set."},"body_params":{"type":"object","additionalProperties":{"type":"string"},"description":"Interpolation values for `body_i18n_key`."},"dismissible":{"type":"boolean","description":"Whether the customer may close it."}}},"NoticeList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Notice"}}}},"NoticeTone":{"type":"string","description":"What kind of thing a notice is. ⛔ A tone, never a colour: the operator says what this **is** and the design system decides how it looks in light and in dark, which is the only way the contrast can be guaranteed in both. An operator-chosen colour would be picked against whichever theme they were using and be unreadable in the other, with no gate able to tell.","enum":["info","success","warning","critical","promo"]},"NotificationConnection":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["email","slack","telegram","webhook","push","sms","whatsapp"]},"label":{"type":"string"},"target":{"type":"string"},"personal":{"type":"boolean"},"verified":{"type":"boolean","description":"Until this is true nothing is routed here. For a machine destination it becomes true when a real test message has been delivered; for an e-mail address it becomes true only when the RECIPIENT clicks the confirmation link, because any address we can type will accept our mail and that proves nothing about consent."},"verified_at":{"type":"string","format":"date-time","nullable":true},"checked_at":{"type":"string","format":"date-time","nullable":true,"description":"When we last managed to LOOK, as against `verified_at` which is when we last PROVED it works. One field cannot answer both: without the pair, \"we have not been able to reach your Slack for a week\" renders as \"verified a week ago\"."},"awaiting_confirmation":{"type":"boolean","description":"An e-mail destination that has been sent its confirmation link and is waiting for the recipient. Neither verified nor failed - a third state, and showing it as \"not verified\" makes the customer press Test again instead of the recipient pressing Confirm."},"verify_error":{"type":"string"},"verify_error_code":{"type":"string","enum":["their_endpoint_refused","their_endpoint_unreachable","their_credential_rejected","their_recipient_refused","not_configured","our_fault","could_not_check",""],"description":"The TRANSLATABLE half of `verify_error`. That sentence is authored English and this payload is rendered in 57 other languages, so a German customer was shown a translated wrapper around an untranslated reason (W39-AM, D21133).\n\n⭐ A code, never a redaction. CodeQL #315 asked for LESS engine text on that screen and §2.19 asks for the SAME information in the reader's language, and those pull in opposite directions: \"something went wrong\" would satisfy the first and make the second worse, because `their_endpoint_refused` is exactly the case where the customer must know it was their endpoint and not us.\n\n⛔ Empty means no failure to describe, which includes a §2.46 refusal to SPEND - a refusal is not an error and must not borrow an error's copy (§2.57). A consumer renders its own copy per code and falls back to `verify_error` for a code it has never heard of, so a newer engine cannot blank an older console."},"health":{"type":"string","enum":["healthy","idle","failing","unverified"],"description":"⚖️ Owner, 2026-09-03 - *\"can you get something to check that is set up and working properly please\"*. `verified` answers *did this EVER work*; this answers *is it working NOW*, which until W39-AM nothing on the estate could: every delivery outcome was written to the notification history and nothing was written back here, so a webhook that had been answering `500` for a week still rendered a green tick.\n\n⛔ FOUR states, not two. `idle` is *proved, and nothing has been sent here yet* - forcing that into \"working\" asserts a delivery that never happened, and into \"broken\" alarms a customer whose destination is fine. `unverified` is *never proved*, which has a different remedy from `failing` (press Verify, versus go and look at your own server)."},"last_delivery_at":{"type":"string","format":"date-time","nullable":true,"description":"When a real notification was last DELIVERED here, as against verified."},"last_failure_at":{"type":"string","format":"date-time","nullable":true},"last_delivery_error":{"type":"string","description":"Why the last delivery failed, in copy WE authored, chosen from a closed table by what failed and where it was going (`engine.notifications.failure_copy`). It is never the provider's own error text. That is enforced by the code rather than promised by it - the sentence is a literal and the classifier never receives the exception - because the previous arrangement passed `str(exc)` straight through and our mail supplier's adapter names the supplier and its API URL, which then rendered verbatim on the customer's screen (CodeQL `py/stack-trace-exposure` alert 315). A destination the customer CHOSE may be named, because they can go and look at it; a supplier they never chose may not (CLAUDE.md 2.57). The provider's own words go to the log with their chain, so support loses nothing."},"last_delivery_error_code":{"type":"string","enum":["their_endpoint_refused","their_endpoint_unreachable","their_credential_rejected","their_recipient_refused","not_configured","our_fault","could_not_check",""],"description":"The translatable half of `last_delivery_error`, on the same contract as `verify_error_code`. Classified by the adapter at the seam that knew what happened, never re-derived downstream."},"consecutive_failures":{"type":"integer","description":"Reset to 0 by any success, so a destination that recovers stops reporting itself broken with nobody pressing anything. `failing` is three in a row - one `502` from somebody's own server is a bad minute, and a screen that shouts on the first one is a screen customers learn to ignore."},"signing_secret":{"type":"string","description":"Webhook destinations only, and returned ONCE on create. Use it to verify the `X-Zinn-Signature` header. There is no endpoint that will show it again - one would turn a read of the connection list into a credential disclosure."},"signing_secret_notice":{"type":"string"},"routes":{"type":"object","additionalProperties":{"type":"boolean"},"description":"The FULL grid for this connection, one boolean per notification topic."},"us_ca_limited":{"type":"boolean","description":"An SMS/WhatsApp destination on a +1 (US/Canada) number. Its grid lists only the account-notice topics (payments, orders, mail DNS action needed); SEO, uptime and marketplace texts are not sent to it (they still come by e-mail and in the app)."}}},"NotificationConnectionDelivery":{"type":"object","description":"One delivery to a webhook destination - an event, or a Test press.","required":["id","event_type","test","status","attempts","created_at"],"properties":{"id":{"type":"string","format":"uuid","description":"The `X-Zinn-Delivery` header (and body `id`) the endpoint received."},"event_id":{"type":"string","format":"uuid","nullable":true},"event_type":{"type":"string","description":"e.g. `invoice.paid`, or `connection.verify` for a Test press."},"test":{"type":"boolean","description":"True for a Test press."},"status":{"type":"string","enum":["pending","retrying","delivered","failed"]},"attempts":{"type":"integer","minimum":0},"response_code":{"type":"integer","nullable":true,"description":"The endpoint's last HTTP status; null when it did not answer."},"error_code":{"type":"string","nullable":true,"description":"A `FailureCode` a screen translates; null when the last attempt landed."},"created_at":{"type":"string","format":"date-time"},"last_attempted_at":{"type":"string","format":"date-time","nullable":true},"next_attempt_at":{"type":"string","format":"date-time","nullable":true,"description":"When the next retry is due; null once delivered or given up."},"delivered_at":{"type":"string","format":"date-time","nullable":true}}},"NotificationConnectionDeliveryPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NotificationConnectionDelivery"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"NotificationPhoneState":{"type":"object","required":["availability","channels","consent_text_version","events_by_topic","event_groups"],"properties":{"availability":{"type":"object","required":["sms","whatsapp","countries","white_label","whatsapp_fallback_languages"],"properties":{"sms":{"type":"boolean"},"whatsapp":{"type":"boolean"},"countries":{"type":"array","items":{"type":"string","description":"ISO 3166-1 alpha-2"}},"white_label":{"type":"boolean"},"whatsapp_fallback_languages":{"type":"array","description":"Base language codes WhatsApp has no template language for. A WhatsApp alert for a person whose language is one of these is sent by SMS in their own language instead.","items":{"type":"string"}}}},"channels":{"type":"array","items":{"type":"object","required":["channel","connection_id","phone","health","consent_active","last_delivery_at"],"properties":{"channel":{"type":"string","enum":["sms","whatsapp"]},"connection_id":{"type":"string","format":"uuid"},"phone":{"type":"string"},"health":{"type":"string"},"consent_active":{"type":"boolean"},"last_delivery_at":{"type":"string","format":"date-time","nullable":true}}}},"consent_text_version":{"type":"string"},"events_by_topic":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"event_groups":{"type":"object","additionalProperties":{"type":"string"}}}},"NotificationPreference":{"type":"object","description":"One topic's delivery answer for the calling user in one organization.","required":["topic","channel","enabled","organization_default","can_opt_out","always_sent_count"],"properties":{"topic":{"type":"string","description":"A customer-meaningful group, not an event category and not an event type. Thirty-six templates is not a settings screen, and `payment.failed` and `payment_method.added` share a category while being completely different to a person.\n\nA stable key, deliberately: the engine sends no display strings for it, because it has no way to localise them and the client already has 37 catalogues."},"channel":{"type":"string"},"enabled":{"type":"boolean","description":"Your effective answer. Always `true` when `can_opt_out` is false, whatever is stored - so a row written before a message became mandatory can never render as \"off\"."},"organization_default":{"type":"boolean","description":"What the organization set for members who have not chosen. Shown so a member can see they are overriding it."},"can_opt_out":{"type":"boolean","description":"False when every message in the topic is one we are obliged to send."},"always_sent_count":{"type":"integer","description":"How many messages in this topic are sent whatever the customer chooses. Unlike `can_opt_out` this is meaningful for EVERY topic - four of the five carry unavoidable mail - so a screen can always say what switching the topic off does not stop."},"always_sent":{"type":"array","description":"Those messages by stable id, so a screen can name them rather than only count them. The difference between a disclaimer and an answer.","items":{"type":"string"}}}},"OAuthAuthorizationServerMetadata":{"type":"object","description":"RFC 8414 authorization-server metadata (the MCP OAuth 2.1 server).","required":["issuer","authorization_endpoint","token_endpoint","response_types_supported","code_challenge_methods_supported"],"properties":{"issuer":{"type":"string","format":"uri"},"authorization_endpoint":{"type":"string","format":"uri"},"token_endpoint":{"type":"string","format":"uri"},"registration_endpoint":{"type":"string","format":"uri"},"revocation_endpoint":{"type":"string","format":"uri"},"response_types_supported":{"type":"array","items":{"type":"string"}},"response_modes_supported":{"type":"array","items":{"type":"string"}},"grant_types_supported":{"type":"array","items":{"type":"string"}},"code_challenge_methods_supported":{"type":"array","items":{"type":"string"}},"token_endpoint_auth_methods_supported":{"type":"array","items":{"type":"string"}},"revocation_endpoint_auth_methods_supported":{"type":"array","items":{"type":"string"}},"client_id_metadata_document_supported":{"type":"boolean"},"authorization_response_iss_parameter_supported":{"type":"boolean"},"scopes_supported":{"type":"array","items":{"type":"string"}},"service_documentation":{"type":"string","format":"uri"},"op_policy_uri":{"type":"string","format":"uri"},"op_tos_uri":{"type":"string","format":"uri"}}},"OAuthClientRegistrationRequest":{"type":"object","required":["redirect_uris"],"properties":{"redirect_uris":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string"}},"client_name":{"type":"string","maxLength":200},"client_uri":{"type":"string","format":"uri"},"logo_uri":{"type":"string","format":"uri"},"token_endpoint_auth_method":{"type":"string","enum":["none","client_secret_post","client_secret_basic"]},"grant_types":{"type":"array","items":{"type":"string"}},"software_id":{"type":"string"}}},"OAuthClientRegistrationResponse":{"type":"object","required":["client_id","client_id_issued_at","client_name","redirect_uris","token_endpoint_auth_method"],"properties":{"client_id":{"type":"string","example":"zoc_0123456789abcdef01234567"},"client_id_issued_at":{"type":"integer"},"client_name":{"type":"string"},"redirect_uris":{"type":"array","items":{"type":"string"}},"grant_types":{"type":"array","items":{"type":"string"}},"response_types":{"type":"array","items":{"type":"string"}},"token_endpoint_auth_method":{"type":"string"},"client_uri":{"type":"string"},"logo_uri":{"type":"string"},"client_secret":{"type":"string","description":"Returned once, for a confidential client only."},"client_secret_expires_at":{"type":"integer"}}},"OAuthErrorResponse":{"type":"object","description":"An RFC 6749 §5.2 error.","required":["error"],"properties":{"error":{"type":"string","example":"invalid_grant"},"error_description":{"type":"string"}}},"OAuthProtectedResourceMetadata":{"type":"object","description":"RFC 9728 protected-resource metadata for the MCP server.","required":["resource","authorization_servers"],"properties":{"resource":{"type":"string","format":"uri"},"authorization_servers":{"type":"array","items":{"type":"string","format":"uri"}},"scopes_supported":{"type":"array","items":{"type":"string"}},"bearer_methods_supported":{"type":"array","items":{"type":"string"}},"resource_documentation":{"type":"string","format":"uri"},"resource_name":{"type":"string"},"resource_policy_uri":{"type":"string","format":"uri"},"resource_tos_uri":{"type":"string","format":"uri"}}},"OAuthRevokeRequest":{"type":"object","required":["token"],"properties":{"token":{"type":"string"},"token_type_hint":{"type":"string"},"client_id":{"type":"string"},"client_secret":{"type":"string"}}},"OAuthTokenRequest":{"type":"object","required":["grant_type"],"properties":{"grant_type":{"type":"string","enum":["authorization_code","refresh_token"]},"code":{"type":"string"},"redirect_uri":{"type":"string"},"code_verifier":{"type":"string"},"refresh_token":{"type":"string"},"client_id":{"type":"string"},"client_secret":{"type":"string"}}},"OAuthTokenResponse":{"type":"object","required":["access_token","token_type","expires_in","refresh_token","scope"],"properties":{"access_token":{"type":"string","description":"`zoat_…` — accepted only on `/v1/mcp`."},"token_type":{"type":"string","enum":["Bearer"]},"expires_in":{"type":"integer","example":3600},"refresh_token":{"type":"string","description":"`zort_…` — single use; rotates on every refresh."},"scope":{"type":"string","description":"The granted permission keys","space-separated.":null}}},"ObjectRef":{"type":"string","description":"Opaque reference to the owning entity, conventionally `<kind>:<id>` — e.g. `kb_article:0190f1a2-…` or `page:pricing`. The engine never parses it; it is the caller's join key back to its own content.","minLength":1,"maxLength":255,"example":"page:pricing"},"Offer":{"type":"object","description":"One upsell as the dashboard renders it. Copy is already in the reader's language, and `cta_url` is already resolved against their own account.","required":["key","tone","icon","title","body","cta_label","cta_url"],"additionalProperties":false,"properties":{"key":{"type":"string","description":"Stable identity, e.g. `cdn`. The client keys its per-viewer dismissals and its rotation position on this, so it must not change when the copy does.","example":"cdn"},"tone":{"type":"string","enum":["info","promo","warning"],"description":"⛔ A tone, never a colour. The operator picks *what kind of thing this is* and the design system decides how it looks in light and in dark — the only way the contrast can be right in both. An operator-chosen hex is picked against whichever theme they had open and is unreadable in the other, and no gate can see it. `warning` is reserved for a real constraint (a limit they are up against), never used to make an ordinary offer louder.","example":"info"},"icon":{"type":"string","description":"A ZDS icon name. Empty renders the card with no icon, not a gap.","example":"globe"},"title":{"type":"string","example":"Your plan does not include the CDN"},"body":{"type":"string","description":"Supporting line. May be empty — a one-line offer is legitimate."},"cta_label":{"type":"string","example":"See plans with the CDN"},"cta_url":{"type":"string","description":"Where the button goes. Either an in-app path starting with a single `/` or an absolute `https://` URL — validated on write **and re-checked on read**, so a row that predates the validator, or arrived from a fixture, still cannot reach an `href`.","example":"/billing"}}},"OfferList":{"type":"object","required":["data","slots"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Offer"}},"slots":{"type":"integer","description":"How many to show at once. ⚖️ The owner's number (3, 2026-08-28), served in the payload rather than hardcoded in the SPA so changing it is a deploy of one service instead of a coordinated release of the engine and both consoles. Reported in **every** shape of response, including the empty one, so a client sizing its panel from it never reads `undefined`.","example":3}}},"OffsiteCopy":{"type":"object","required":["id","backup_id","destination_id","taken_at","kind","status","size_bytes","attempts","restorable"],"properties":{"id":{"type":"string","format":"uuid"},"backup_id":{"type":"string","format":"uuid"},"destination_id":{"type":"string","format":"uuid"},"taken_at":{"type":"string","format":"date-time"},"kind":{"type":"string","enum":["full","incremental"]},"status":{"type":"string","enum":["pending","stored","failed","purged"]},"size_bytes":{"type":"integer","format":"int64"},"stored_at":{"type":"string","format":"date-time","nullable":true},"object_key":{"type":"string","description":"Where the ciphertext is at the destination."},"error_code":{"type":"string"},"attempts":{"type":"integer"},"restorable":{"type":"boolean"}}},"OffsiteDestination":{"type":"object","description":"A place the customer lets us send backups to. Carries no credential, ever.","required":["id","org_id","name","kind","status","prefix","sites_using","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"kind":{"type":"string","enum":["s3","sftp"]},"endpoint":{"type":"string"},"region":{"type":"string"},"bucket":{"type":"string"},"host":{"type":"string"},"port":{"type":"integer"},"username":{"type":"string"},"host_key_fingerprint":{"type":"string","description":"The pinned SFTP host key as `SHA256:…`, the form `ssh-keygen -lf` prints."},"prefix":{"type":"string"},"status":{"type":"string","enum":["working","failing"]},"last_checked_at":{"type":"string","format":"date-time","nullable":true},"last_check_code":{"type":"string"},"sites_using":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}},"OffsiteDestinationWrite":{"type":"object","required":["name","kind"],"properties":{"org_id":{"type":"string","format":"uuid"},"name":{"type":"string","maxLength":120},"kind":{"type":"string","enum":["s3","sftp"]},"prefix":{"type":"string","maxLength":255},"endpoint":{"type":"string","description":"S3: an https:// endpoint with no path."},"region":{"type":"string","description":"S3: the bucket's region, or auto for Cloudflare R2."},"bucket":{"type":"string"},"access_key_id":{"type":"string","writeOnly":true},"secret_access_key":{"type":"string","writeOnly":true},"host":{"type":"string","description":"SFTP: the server's host name."},"port":{"type":"integer","minimum":1,"maximum":65535},"username":{"type":"string"},"password":{"type":"string","writeOnly":true},"private_key":{"type":"string","writeOnly":true,"description":"OpenSSH format."}}},"Order":{"type":"object","required":["id","org_id","human_ref","status","currency","subtotal_minor","tax_minor","discount_minor","total_minor","lines","payments","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"org_id":{"$ref":"#/components/schemas/Uuid"},"human_ref":{"type":"string","description":"Human-friendly order reference.","example":"ZD-ORD-3F9A1C2B"},"status":{"$ref":"#/components/schemas/OrderStatus"},"currency":{"$ref":"#/components/schemas/CurrencyCode"},"subtotal_minor":{"type":"integer","format":"int64"},"tax_minor":{"type":"integer","format":"int64"},"discount_minor":{"type":"integer","format":"int64"},"total_minor":{"type":"integer","format":"int64"},"billing_country":{"type":["string","null"]},"placed_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/OrderLine"}},"payments":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"coverage":{"description":"What paying this order buys, said BEFORE the customer pays (s1014 R40, docs/747 §2a): the subscription period it covers, the periods still owed after it, and whether the services come back. Present only on an UNPAID order that pays for subscription time (a renewal, a prepayment or a pay-everything order); `null` otherwise.","oneOf":[{"$ref":"#/components/schemas/PaymentCoverage"},{"type":"null"}]},"payment_failure":{"description":"Present only on an unpaid order (`pending_payment` / `payment_failed`) whose latest payment attempt FAILED; `null` otherwise. Says why, so the customer is told plainly and offered another card, a retry or another way to pay (row 1108#29).","oneOf":[{"$ref":"#/components/schemas/PaymentFailure"},{"type":"null"}]}}},"OrderAddon":{"type":"object","required":["code","name","description","category","interval","amount_minor","currency","sla_hours","sla_business_days","group"],"properties":{"group":{"type":"string","enum":["your_site","performance","backups_security","capacity","seo","ai","marketing","support","other"],"description":"The checkout section this add-on is listed under, in this display order (`extras.checkout_offer.ADDON_GROUPS`). `your_site` holds the add-ons made for the plan's own application (Moodle's updates on a Moodle plan); `other` only for an add-on not yet classified."},"code":{"type":"string","maxLength":64},"name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string","description":"The stable slug the fulfilment workflow dispatches on."},"interval":{"type":"string","enum":["one_off","monthly","annual"],"description":"Whether this is a one-off charge or a recurring subscription (`annual`: billed once a year, e.g. automatic application updates). Branch on it — a running total that adds a monthly addon to a one-off domain registration without saying which is which is a number the customer cannot check."},"amount_minor":{"type":"integer","format":"int64"},"currency":{"type":"string","minLength":3,"maxLength":3},"sla_hours":{"type":["integer","null"],"description":"Elapsed-time SLA for an automated service; `null` where there is no committed one. A database optimisation does not care that it is Sunday."},"sla_business_days":{"type":["integer","null"],"description":"The same promise in **working days**, for a service a person performs, and it **wins** over `sla_hours` when both are set. Two fields because they measure different things — telling a Friday buyer their hand-built speed-up is due on Sunday is not a rounding error."}}},"OrderComputeServerRequest":{"type":"object","description":"⛔ Shape only. Everything that decides whether the provider would accept the order — the provider, the zone, the size, the disk/bandwidth pair — is validated in the engine, because those rules must hold for a workflow activity and a management command too, and the sentence a customer reads must be the same whichever door they came through.","required":["name","zone"],"additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":64,"description":"What to call the machine. It is also the name at the provider, which is what lets a retried purchase find the machine it already bought instead of buying a second."},"zone":{"type":"string","minLength":1,"maxLength":64,"description":"The data centre, as `getComputeCatalogue` reported it."},"spec":{"type":"string","maxLength":64,"description":"The machine size, as the configurator reported it. ⭐ **Either this or `plan_code`, not both** — and where the provider publishes no sizes the two collapse into one, because the configurator's size ids are our plan codes."},"plan_code":{"type":"string","maxLength":64,"description":"The tier to buy, for a catalogue-aware caller. Either this or `spec`."},"org_id":{"allOf":[{"$ref":"#/components/schemas/Uuid"}],"nullable":true,"description":"The organisation to buy for. Required only when the caller belongs to more than one — picking \"the first org in scope\" would buy a server on an arbitrary tenant's balance. Omitted, it is their own."},"provider":{"type":"string","maxLength":32,"description":"Which platform to place it on. Omitted, the engine resolves the range's default — ⛔ **except on a range priced per data centre** (`ComputeTier.zoned`), where omitting it is refused `422`: every platform there is one data centre with its own price, so \"the default\" would be picking a price on the customer's behalf."},"image":{"type":"string","maxLength":64,"description":"The operating system or one-click application the machine boots, as `getComputeCatalogue` reported it in `ComputeProvider.images`.\n\n⛔ Required — `422` — on any range that publishes images, and meaningless on one that does not. It is not marked required here because which ranges publish them is a live provider fact a schema cannot know. ⛔⛔ Check the image's `architecture` against the chosen size: ARM and x86 images are separate entries with the **same name**, and a mismatch is refused *after* the customer has paid."},"ssh_keys":{"type":"array","maxItems":25,"items":{"type":"string","maxLength":64},"description":"The ids of the authorised keys to install at build time, from `listComputeSshKeys`. Every id must be one of the ordering organisation's own registered keys (`listComputeSshKeys` for that org); any other id — another organisation's key, a key name, an unregistered vendor id — is refused `422` `refusal.compute.sshKeyNotYours` and nothing is built.\n\n⛔⛔ **Required on the Zinn® Private Cloud range, and the refusal is a security control rather than a convenience.** That provider answers a build with no key by returning a **root password** in its response body, and `null` when a key is sent. An order with no key therefore mints a root credential that would exist in our process, our logs and our exception reports; refusing is how it never exists."},"blueprint":{"type":"string","enum":["","bare","docker","k3s","k3s_argocd"],"default":"","description":"W43-49 (`docs/689`). The software stack installed at first boot on a Zinn® Cloud machine: Docker Engine, single-machine k3s, or k3s with Argo CD. Refused on a range whose first boot we do not write."},"term_months":{"type":"integer","minimum":1,"maximum":36,"default":1,"description":"How many months to buy up front. Outside 1…36 is refused `422` before a single vendor write, the same bound `renewComputeServer` applies."},"optimisation":{"type":"string","maxLength":64,"description":"A stack optimisation profile, as the configurator reported it."},"disk":{"type":"string","maxLength":32,"description":"An explicit disk allocation, for a provider whose `supports_disk_and_bandwidth` is true. Sending it to one whose is false is refused."},"bandwidth":{"type":"string","maxLength":32,"description":"An explicit transfer allocation, for a provider whose `supports_disk_and_bandwidth` is true."}}},"OrderConfig":{"type":"object","required":["plan_code","plan_name","plan_id","plan_version_id","plan_version","product_line","product_line_name","currency","terms","default_interval","trial_days","included_domains","included_domain_tlds","domain_term_years","regions","spec","addons"],"properties":{"plan_code":{"type":"string"},"plan_name":{"type":"string"},"plan_id":{"type":"string","description":"The plan's stable identity — what a URL or an analytics event refers to."},"plan_version_id":{"type":"string","description":"The **purchasable** identifier: what a `hosting_plan` cart line pins. Not `plan_id` — a price change mints a new version rather than mutating the sold one, so this value changes and `plan_id` does not."},"plan_version":{"type":"integer","minimum":1},"product_line":{"type":"string"},"product_line_name":{"type":"string","description":"The line's display name from the engine's one source table, so a client never has to render a raw code to a customer."},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"What everything on this payload is priced in. It may **differ** from the currency asked for: a currency with no derived price row yet falls back to USD and says so here rather than labelling an unconverted number with the requested symbol."},"terms":{"type":"array","description":"Cheapest per month first, which is what `default_interval` names.","items":{"$ref":"#/components/schemas/OrderTerm"}},"default_interval":{"type":"string","description":"The cadence to select on first render — **derived** as the cheapest per month rather than typed beside the price table. A typed default is a comment that happens to run: correct only until somebody edits a price."},"trial_days":{"type":["integer","null"],"description":"The free trial this plan offers, or `null` for none. A trial takes no card and starts immediately, so the button beneath the configuration has to say \"start trial\" rather than \"pay\"."},"trial_requires_card":{"type":"boolean","default":false,"description":"⚖️ 2026-10-21 (ZEAB2): this plan's trial starts only with a verified card on file (Developer Hosting) — it is NOT charged. A guest basket refuses it (422); the page sends the visitor to the app's trial start (sign up, add a card, start)."},"included_domains":{"type":"integer","minimum":0,"description":"How many domain registrations the plan includes free — the \"use the free domain this plan includes\" branch. `0` is the common case: render that branch only when the allowance is real, or the page advertises something checkout will charge for.\n\nOnly the FIRST year is covered however long the registration term."},"included_domain_tlds":{"type":"array","items":{"type":"string"},"description":"Which extensions the free registration may be spent on. Empty alongside a non-zero `included_domains` means the plan grants any offered TLD."},"domain_term_years":{"type":"array","items":{"type":"integer","minimum":1,"maximum":10}},"regions":{"type":"array","description":"The data centres a site on this plan may be created in. **Empty is a real answer** — the Footprint-Free line offers no region by owner ruling, because a PBN customer is deliberately not asked where their sites live. Render no section rather than an empty picker.","items":{"$ref":"#/components/schemas/OrderRegion"}},"spec":{"type":"array","description":"The read-only \"what is included\" panel, ordered for display. Not a filtered allow-list: every resolved entitlement appears, so a capability added to the catalogue tomorrow is described without anybody editing a client.","items":{"$ref":"#/components/schemas/OrderSpecItem"}},"addons":{"type":"array","description":"The services offered **on this product line** and deliverable today — a PBN addon never appears on a mainstream plan, and an addon whose fulfilment handler has been withdrawn never appears at all.","items":{"$ref":"#/components/schemas/OrderAddon"}}}},"OrderCustomerAction":{"type":"object","description":"Where a customer completes a payment that is waiting on them. Exactly one of `url` and `token` carries the answer: a hosted page the customer opens, or a client-side credential the gateway's browser SDK confirms with. A caller uses whichever is set.","required":["kind","provider"],"properties":{"kind":{"type":"string","enum":["pay","approve","authenticate"],"description":"What the customer is being asked to do. `pay` — open a crypto invoice and send payment; `approve` — approve the payment in their PayPal account; `authenticate` — confirm the payment with their bank (3-D Secure)."},"url":{"type":"string","description":"The hosted page to send the customer to, or `\"\"` when this action is a credential instead. For crypto this is the NOWPayments invoice and it is **stable for the life of the order** — the same link every time it is asked for, because the confirming webhook is matched against that one invoice."},"token":{"type":"string","description":"A short-lived client-side credential for the gateway's browser SDK (Stripe's client secret), or `\"\"`. Never stored by the platform — it is re-read from the gateway each time this endpoint is called, so it is always fresh."},"publishable_key":{"type":"string","description":"The Stripe publishable key of the account that owns `token`, to load Stripe.js with before calling `handleNextAction` (3-D Secure). Set only on a Stripe `authenticate` action settled on the platform's own account; `\"\"` otherwise. A token with an empty key cannot be completed in this browser (it belongs to a reseller's own Stripe account), so the client tells the customer to contact support rather than loading Stripe.js against the wrong account."},"provider":{"type":"string","description":"The payments driver that owns this action (`nowpayments`, `paypal`, `stripe`)."}}},"OrderLine":{"type":"object","required":["id","kind","description","unit_amount_minor","currency"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"kind":{"$ref":"#/components/schemas/LineKind"},"description":{"type":"string"},"unit_amount_minor":{"type":"integer","format":"int64"},"currency":{"$ref":"#/components/schemas/CurrencyCode"},"tax_amount_minor":{"type":"integer","format":"int64"},"discount_minor":{"type":"integer","format":"int64"},"period_years":{"type":["integer","null"]},"listing_package_id":{"description":"The marketplace package a `marketplace_package` line was bought against, carried across from the cart at capture.","anyOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]},"interval":{"type":"string","description":"The billing interval this line was **sold at** — empty on a one-off. Part of the receipt: it is the cadence the customer agreed to be charged on, and an invoice that omits it is ambiguous."},"result_kind":{"type":["string","null"],"description":"The kind of resource this line produced once fulfilled — one of `subscription`, `domain`, `marketplace_sale`, `compute_server`, `managed_database`, `extra_purchase`, `trial`, `aged_domain` (an aged-domain order, s1014) or `none`. (This list previously contradicted itself across two sentences, naming `marketplace_sale` in one and `compute_server` in the other and omitting both from the other.)\n\nA `compute_server` line produces a Subscription **and** a machine, and `result_id` points at the **machine**: it is what the customer bought, what support is asked about, and the half that can fail to build. The subscription is reachable from the machine either way.\n\nA `managed_database` line is the compute shape exactly: a Subscription **and** a database instance, with `result_id` pointing at the **instance**.\n\nA `trial` line produces a **Trial and no subscription at all**: the Trial row is the entitlement grant, and the subscription is what conversion later produces. `result_id` points at the Trial, so a staff surface can see that the line is on a clock rather than on a plan."},"result_id":{"anyOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]},"metadata":{"type":"object","additionalProperties":true}}},"OrderPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"OrderRegion":{"type":"object","required":["code","country"],"properties":{"code":{"type":"string","description":"The data centre code (`nbg1`, `lon`, …)."},"country":{"type":"string","description":"ISO-3166 alpha-2, or `\"\"` where the location records none."}}},"OrderSpecItem":{"type":"object","required":["key","value"],"properties":{"key":{"type":"string","description":"The entitlement key (`max_sites`, `disk_gb`, `free_ssl`, …). The **key**, not a sentence: every surface renders its own copy in its own language, and both consoles already own an `entitlements.*` catalogue for exactly these."},"value":{"description":"A boolean, an integer or a string depending on which entitlement it is — deliberately untyped on the wire for that reason."}}},"OrderStatus":{"type":"string","description":"An order's lifecycle state (docs/31 §4.3).","enum":["draft","pending_payment","paid","fulfilling","completed","partially_fulfilled","payment_failed","canceled","refunding","refunded"]},"OrderTerm":{"type":"object","required":["interval","amount_minor","currency","per_month_minor","saving_minor","saving_percent"],"properties":{"interval":{"type":"string","enum":["monthly","annual"]},"amount_minor":{"type":"integer","format":"int64","description":"What one term costs, in the currency's minor units."},"currency":{"type":"string","minLength":3,"maxLength":3},"per_month_minor":{"type":"integer","format":"int64","description":"What this cadence works out at per month, so two rows compare honestly. Integer division with the remainder dropped — it is a comparison aid, and rounding up would let it exceed the monthly price on a plan whose annual saving is a penny."},"saving_minor":{"type":"integer","format":"int64","description":"Saved against paying monthly for the same year (`12 x monthly - annual`, clamped at zero). **Computed, not described**: a \"2 months free\" string beside the prices would be a second expression of the same fact, and it is the copy that goes stale the first time one line is discounted differently from the rest.\n\nAlways present. `0` where there is no monthly price to compare against — an omitted field renders as \"no saving\" in one client and \"unknown\" in another, and only one of those is true."},"saving_percent":{"type":"integer","minimum":0,"maximum":100}}},"OrgMember":{"type":"object","description":"One person's membership of one organization. `removable` is the engine's decision, not a hint — it already accounts for the caller's own permissions, the privilege-inversion guard and last-owner protection.","required":["user_id","email","name","roles","joined_at","is_self","removable","not_removable_reason","role_assignable"],"properties":{"user_id":{"$ref":"#/components/schemas/Uuid"},"email":{"type":"string","format":"email"},"name":{"type":"string","description":"Display name; may be empty for an account that never set one."},"roles":{"type":"array","description":"Every role this person holds in this org, sorted.","items":{"type":"string"},"example":["owner"]},"joined_at":{"type":"string","format":"date-time","description":"When their EARLIEST membership of this org was created."},"is_self":{"type":"boolean","description":"Whether this row is the calling user."},"removable":{"type":"boolean"},"not_removable_reason":{"description":"Why not, when `removable` is false. Null when removable — and also null for a caller lacking `members.remove`, because \"you cannot remove anyone here\" is a fact about the caller, not about each colleague, and reporting it per-row would hand a junior member a map of which colleagues outrank them.","anyOf":[{"$ref":"#/components/schemas/OrgMemberRemovalBlock"},{"type":"null"}]},"role_assignable":{"type":"boolean","description":"Whether `PATCH` on this member would be accepted — the caller holds `members.role.assign` here, does not outrank themselves, and this is not the last owner. ⛔ *Which* role may then be conferred is `GET /v1/orgs/{orgId}/roles`; this says only whether the picker should render."}}},"OrgMemberPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OrgMember"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"OrgMemberRemovalBlock":{"type":"string","description":"Why a member cannot be removed. `last_owner` — removing them would leave the org unownable, so assign another owner first. `more_privileged` — they hold permissions the caller does not, so the caller may not evict them (the mirror of the invite escalation guard). ⛔ A named schema rather than an inline enum so the dashboard's computed-key audit can enumerate it: the UI renders `team.cannotRemove.{reason}` and a member added here without its copy would show the raw key where the explanation should be (CLAUDE.md §2.21).","enum":["last_owner","more_privileged"]},"OrgMigration":{"allOf":[{"$ref":"#/components/schemas/SiteMigration"},{"type":"object","required":["site_name","site_domain","site_status"],"description":"One migration plus just enough of its site to render an estate-wide row without opening it. ⛔ The site fields are ON the row rather than looked up by the client: a screen that fetched each site to render its name would issue one request per row.","properties":{"site_name":{"type":"string","description":"May be empty — a site's display name is optional, which is exactly the case for sites created by `POST /v1/migrations`, so a row rendered from this alone would be blank for them."},"site_domain":{"type":"string"},"site_status":{"type":"string"}}}]},"OrgType":{"type":"string","description":"Organization type in the tenancy tree.","enum":["reseller","customer","staff"]},"Organization":{"type":"object","required":["id","type","name","default_currency","status","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"type":{"$ref":"#/components/schemas/OrgType"},"parent_org_id":{"description":"Parent in the tenancy tree; null for a top-level org.","anyOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]},"name":{"type":"string","example":"Acme Agency"},"brand_id":{"type":["string","null"],"description":"White-label brand applied to this org's surfaces."},"default_currency":{"$ref":"#/components/schemas/CurrencyCode"},"status":{"type":"string","enum":["active","suspended","closed"]},"created_at":{"type":"string","format":"date-time"},"hidden_menu_sections":{"type":"array","description":"Dashboard menu sections this organization's console does not show (set by staff, `setAdminOrgMenuVisibility`). Presentation only: every endpoint keeps its own permission check. Empty or absent = the normal menu.","items":{"$ref":"#/components/schemas/MenuSection"}}}},"OrganizationCreate":{"type":"object","required":["type","name"],"properties":{"type":{"$ref":"#/components/schemas/OrgType"},"parent_org_id":{"description":"Defaults to the caller's org when omitted.","anyOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]},"name":{"type":"string","minLength":1,"maxLength":200,"example":"Acme Agency"},"default_currency":{"allOf":[{"$ref":"#/components/schemas/CurrencyCode"}],"default":"USD"}}},"OrganizationPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Organization"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"OrganizationRename":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":200,"minLength":1,"description":"The organization's display name. The only editable field."}}},"OriginLoadState":{"type":"object","description":"One site's origin-load state (s1014 ORIGINGUARD, docs/1110).","required":["state","measured","slow","requests","slow_by_kind","top_kind","ep_faults","peak_slow"],"properties":{"state":{"type":"string","enum":["quiet","watching","slow"]},"measured":{"type":"boolean","description":"false = the guard has never found this site over the line."},"slow":{"type":"integer","description":"Requests of 2 s or more in the last 10 minutes."},"requests":{"type":"integer"},"slow_share":{"type":"number","nullable":true},"slow_by_kind":{"type":"object","additionalProperties":{"type":"integer"},"description":"Keys: own_jobs, visitor_ajax, admin, translated_paths, pages."},"top_kind":{"type":"string","enum":["","own_jobs","visitor_ajax","admin","translated_paths","pages","saturated"]},"ep_faults":{"type":"integer","description":"PHP entry-process denials (508)","worst 5 minutes.":null},"page_cache_ratio":{"type":"number","nullable":true},"edge_hit_ratio":{"type":"number","nullable":true},"first_bad_at":{"type":"string","format":"date-time","nullable":true},"alerted_at":{"type":"string","format":"date-time","nullable":true},"cleared_at":{"type":"string","format":"date-time","nullable":true},"peak_slow":{"type":"integer"},"last_pass_at":{"type":"string","format":"date-time","nullable":true}}},"OutboundMailAccount":{"type":"object","description":"One organisation's own mail service. Never carries the credential.","required":["id","provider","from_domain","status"],"properties":{"id":{"type":"string","format":"uuid"},"provider":{"type":"string","enum":["smtp","mailgun","sendgrid","postmark","ses","resend"]},"from_domain":{"type":"string","description":"The domain the From header uses once verified."},"config":{"type":"object","additionalProperties":true,"description":"The non-secret settings. Never contains a credential."},"is_smtp":{"type":"boolean","description":"Whether this provider is reached over SMTP rather than an HTTP API. True for `smtp` and for `ses`, which uses Amazon's SMTP endpoint."},"status":{"type":"string","enum":["unverified","pending","verified","failing"],"description":"`failing` is a VERIFIED account whose recent sends were refused - a fault to fix, not a setup step not reached. It keeps sending (and keeps failing visibly): mail is never quietly moved back onto the platform's account, because a silent fallback is a bill nobody sees."},"verification_sent_to":{"type":"string","description":"Where the last test message went, so \"check that inbox\" names an inbox."},"verification_expires_at":{"type":"string","format":"date-time","nullable":true},"verified_at":{"type":"string","format":"date-time","nullable":true},"last_error":{"type":"string","description":"The provider's own words about the last failure, with credentials removed."},"last_failure_at":{"type":"string","format":"date-time","nullable":true},"last_success_at":{"type":"string","format":"date-time","nullable":true},"consecutive_failures":{"type":"integer"}}},"OutboundMailState":{"type":"object","description":"Everything the \"Email sending\" screen needs: what is attached, whether it is live, and the form definition for every provider we support.","required":["account","providers","sending_as","fallback_notice","can_configure","client_orgs_held"],"properties":{"can_configure":{"type":"boolean","description":"Whether this organisation's plan includes its own sending identity - the agency and reseller plans do, a plain client plan does not. A claim about the PLAN, never the authorisation: every write re-checks it server-side. It travels here so the screen can say \"this is part of the agency and reseller plans\" instead of rendering a form that answers 422."},"account":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/OutboundMailAccount"}],"description":"null when this organisation sends on the platform's account."},"providers":{"type":"array","description":"The provider catalogue AND the fields each one needs, served from the same definition the API validates against - so the form a customer fills in and the rules it must satisfy cannot drift apart across two repositories.","items":{"type":"object","required":["value","label","fields","credential_label"],"properties":{"value":{"type":"string"},"label":{"type":"string"},"credential_label":{"type":"string","description":"What to call the secret on the form - \"SMTP password\" for SMTP, \"Postmark server token\" for Postmark. A field labelled wrongly is a support ticket."},"fields":{"type":"array","items":{"type":"object","required":["name","label","required","kind"],"properties":{"name":{"type":"string"},"label":{"type":"string"},"required":{"type":"boolean"},"kind":{"type":"string","enum":["text","port","bool","choice"]},"default":{},"placeholder":{"type":"string"},"choices":{"type":"array","items":{"type":"string"}}}}}}}},"sending_as":{"type":"string","enum":["own","platform"],"description":"Who is actually paying for this organisation's mail right now. `platform` whenever no account is attached OR the attached one has not completed its round trip."},"fallback_notice":{"type":"string","description":"Plain-language explanation shown when `sending_as` is `platform`; empty otherwise. Part of the contract rather than presentation - an empty state that does not say who is paying reads as \"nothing to do here\"."},"client_orgs_held":{"type":"integer","description":"How many client organisations under this one currently have their non-essential notifications held because no own mail provider is connected (owner ruling 2026-09-03). `0` when a usable account is attached, when the organisation has no clients, or when its plan does not include an own sending identity. Mail a client must receive to use their account - password resets, invoices - is never held."}}},"OverageChargeAttempt":{"type":"object","description":"One threshold charge raised against a machine for one metering period.","required":["threshold_minor","amount_minor","currency","outcome","detail","created_at"],"additionalProperties":false,"properties":{"threshold_minor":{"type":"integer","description":"The rung this settles — the accrued total the ladder fired at."},"amount_minor":{"type":"integer","description":"What was charged: the accrued total minus everything already settled, so a machine that crosses two rungs between polls pays each rung's share exactly once."},"currency":{"type":"string","maxLength":3},"outcome":{"type":"string","enum":["paid","declined","action_required","no_mandate"],"description":"⛔ Only `declined` stops a machine. `action_required` is an authentication challenge the customer has been asked to complete and `no_mandate` is an account with no chargeable card by construction — neither is a customer who has refused to pay, and stopping either would be stopping somebody who has done nothing wrong."},"detail":{"type":"string","description":"Why, in a sentence, or `\"\"`."},"created_at":{"type":"string","format":"date-time"}}},"OverviewShortcutIds":{"type":"array","maxItems":24,"items":{"type":"string","maxLength":64,"pattern":"^[a-z0-9][a-z0-9_-]*$"},"description":"Dashboard navigation ids, in the order the cards appear. Opaque to the engine: it bounds the count, the length and the charset and stores the rest verbatim, because the section list is the client's nav tree and a copy of it here would start refusing pages shipped after the copy was made.\n\nThe cap is a BOUND, not a product opinion. The owner asked for \"6-10 preset shortcuts\" — that is where a new account starts, and it lives in the client beside the tree the presets name. 24 is three rows of eight: past any grid a person would keep, and nowhere near a payload worth worrying about on a user row."},"OverviewShortcuts":{"type":"object","required":["shortcuts","chosen"],"properties":{"shortcuts":{"$ref":"#/components/schemas/OverviewShortcutIds"},"chosen":{"type":"boolean","description":"Whether this person has ever chosen. ⛔ Not inferable from an empty list, which is why it is on the wire: `false` with an empty list means nobody has chosen and the client shows its presets, while `true` with an empty list means this person deliberately cleared their grid. Collapse the two and a customer who cleared their cards gets the presets back on the next page load, and the bug reads as \"it does not save\"."}}},"OwnDnsPreflight":{"type":"object","required":["ok","code","domain"],"properties":{"ok":{"type":"boolean","description":"True only when `code` is `ok`."},"code":{"type":"string","enum":["ok","no_account","provider_error","zone_missing","cannot_edit","unchecked","ns_mismatch","ns_unknown"]},"key":{"type":"string","nullable":true,"description":"The refusal catalogue key","null when ok.":null},"params":{"type":"object","additionalProperties":true},"message":{"type":"string","description":"The fix","in the caller's language. Empty when ok.":null},"domain":{"type":"string"},"zone":{"type":"string"},"provider":{"type":"string"},"permission":{"type":"string"},"expected_nameservers":{"type":"array","items":{"type":"string"}},"live_nameservers":{"type":"array","items":{"type":"string"}}}},"OwnedProductLine":{"type":"object","description":"One product line an organization has, or has had, something on.\n\n⛔ Deliberately **not** a `ProductLine`. That schema carries `description`, `included_features` and `default_entitlements` — sales copy for a line somebody is choosing. This answers *\"which of my things may I filter by\"*, so it carries only what a filter can use. It would also force invented entitlements for a line we have since retired, which is a lie a client cannot see through.","required":["code","name"],"properties":{"code":{"type":"string","maxLength":64,"description":"The line code, as `Site.product_line` and the `product_line` filter use it.","example":"footprint_free"},"name":{"type":"string","maxLength":200,"description":"The catalogue display name, or `\"\"` when the line is no longer in the catalogue (`Site.product_line` is a plain code column, so a code can outlive its row). A client localises `code` first and falls back to this; `\"\"` means *humanise the code*, never *this line has no name*. Such a line is served rather than dropped — dropping it would silently remove a filter the customer needs, and the only symptom would be a shorter list.","example":"Footprint-Free Hosting"}}},"OwnedProductLineList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OwnedProductLine"}}}},"PageMeta":{"type":"object","required":["has_more"],"properties":{"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to fetch the next page; null on the last page."},"has_more":{"type":"boolean","description":"Whether more items exist beyond this page."}}},"PanelClient":{"type":"object","required":["id","login","name","status"],"additionalProperties":false,"properties":{"id":{"type":"string"},"login":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","description":"⛔ Empty means the panel did not say, never `active`."}}},"PanelConnection":{"type":"object","description":"A running control panel we can reach and administer.","required":["id","host","port","panel","label","licence_id","proved_capabilities","panel_version","panel_hostname","licence_name","verify_tls","checked_at","last_error"],"additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"host":{"type":"string"},"port":{"type":"integer","default":8443},"panel":{"type":"string"},"label":{"type":"string"},"licence_id":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/Uuid"}],"description":"The licence this panel runs on, where we sold it. Null is a supported case, not an error: a customer may connect a panel they licensed elsewhere."},"proved_capabilities":{"type":"array","items":{"type":"string"},"description":"⛔⛔ **What this CONNECTION demonstrated, not what the adapter can express.** A Plesk box can answer every read and refuse `/cli/*/call` outright, and both one-click login and licence installation go through that gateway. A client MUST gate its buttons on this list: an empty entry means we could not prove it, and \"we could not check\" and \"it does not work\" must gate a button identically."},"panel_version":{"type":"string"},"panel_hostname":{"type":"string","description":"The panel's own hostname, which need not be the host we connect to."},"licence_name":{"type":"string","description":"The edition the panel reports it is licensed for."},"verify_tls":{"type":"boolean","description":"Whether we verify the panel's TLS certificate. Per connection, because many Plesk boxes present a self-signed certificate on 8443 — the panel's own default before a customer installs one."},"checked_at":{"type":"string","format":"date-time","nullable":true,"description":"⛔ `null` means **never checked**, which is not the same as *failed*. A client must render the two differently."},"last_error":{"type":"string","description":"Empty when the last check succeeded. Otherwise the reason, which distinguishes *we could not reach it* from *it refused our credential* — the two send a customer to opposite places."}}},"PanelDomain":{"type":"object","required":["id","name","status","www_root"],"additionalProperties":false,"properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","description":"The panel's own status word. ⛔ Empty means unreported, never \"fine\"."},"www_root":{"type":"string"}}},"PanelLicence":{"type":"object","description":"One control-panel licence bought for one machine.","required":["id","product_code","state","target_kind","server_id","bound_ip","key_number","price_minor","currency","message","activated_at"],"additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"product_code":{"type":"string","description":"The `PanelProduct.code` this licence is for."},"state":{"type":"string","enum":["pending","active","suspended","released","failed"],"description":"⛔ `suspended` is **not** a synonym for released. The charge has stopped and the record has not: the licence returns automatically when the account is back in good standing, with no ticket and no re-ordering.\n\n⛔ `pending` is still BILLING. The supplier charges from the moment the purchase returns, so a row stuck pending because our own activation step failed is the most expensive kind to treat as free — it is exactly the orphan nobody looks for."},"target_kind":{"type":"string","enum":["ours","customer"],"description":"Whose machine this licence runs on. ⛔ Stored rather than derived from whether `server_id` is set: *\"did we build this machine\"* and *\"whose problem is it when the disk fills\"* are different questions, and support scope must not silently follow a foreign key."},"server_id":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/Uuid"}],"description":"Our machine, when there is one. Null for a customer-owned server."},"bound_ip":{"type":"string","nullable":true,"description":"The address the licence is registered against at the supplier. ⛔ This is what releasing needs — by teardown the machine may be gone, and a licence we cannot release bills monthly for ever."},"key_number":{"type":"string","description":"The panel-facing key number (`PLSK.01234567`) — an identifier, not a secret. ⛔ The activation code itself is never returned by this API; it lives in Vault."},"price_minor":{"type":"integer","format":"int64","description":"What the customer is charged per month, in minor units, frozen at purchase. A copy rather than a join, so an operator repricing the catalogue cannot move an existing customer's bill."},"currency":{"type":"string","minLength":3,"maxLength":3},"message":{"type":"string","description":"Why it failed or was suspended, in a sentence the customer reads."},"activated_at":{"type":"string","format":"date-time","nullable":true}}},"PanelLoginLink":{"type":"object","description":"⛔⛔ **`url` IS A LIVE CREDENTIAL** — an authenticated administrative session on the customer's panel. Do not log it, do not store it, do not put it in an email. It belongs in one browser.","required":["url","username","single_use"],"additionalProperties":false,"properties":{"url":{"type":"string","description":"The one-time login URL. Treat it as a secret."},"username":{"type":"string","description":"Which panel user the session belongs to. Empty means the administrator."},"single_use":{"type":"boolean","nullable":true,"description":"Whether the link dies on first use. ⛔ `null` is unknown, and a client must not promise single-use on the strength of it. Plesk's are single-use, which is a stronger guarantee than any expiry clock — which is why no expiry is returned."}}},"PanelProduct":{"type":"object","description":"One row of the control-panel picker — an edition, or an extension that attaches to one.\n\n⛔ **There is deliberately no cost field.** What Openprovider charges us lives on the catalogue row for the admin margin ledger; rendered beside the sell price it is a margin leak — the same reason `ComputeAddOnOffer` carries none.","required":["code","kind","panel","host_type","requires_editions","position","price_minor","currency"],"additionalProperties":false,"properties":{"code":{"type":"string","description":"Stable catalogue key — `plesk_vps_web_admin`, `plesk_srv_web_host`, `plesk_wpt_deluxe_pro`."},"kind":{"type":"string","enum":["edition","extension"],"description":"⛔ An `extension` is **not** independently installable: it attaches to a base edition and is inert without one. Buying one for a machine with no Plesk on it takes the customer's money for something that cannot work, so it is refused."},"panel":{"type":"string","description":"The panel family — `plesk` today."},"host_type":{"type":"string","enum":["any","vps","dedicated"],"description":"⛔⛔ **Plesk sells a VPS licence and a dedicated-server licence as different SKUs at different money** (measured 2026-08-29: Web Host is `EUR 21.20` for a VPS and `EUR 24.00` for a dedicated server). Selling the wrong one gives the customer a key Plesk refuses, on their own machine, where nobody can see why. `any` is for extensions that genuinely do not care."},"requires_editions":{"type":"array","items":{"type":"string"},"description":"For an extension: the edition codes it may be added to. Empty means any edition. ⛔ Several extensions are sold as a *different vendor item per edition* (WP Toolkit Deluxe has an Admin, a Pro and a Host SKU), so this is not cosmetic."},"position":{"type":"integer","description":"Sort order on the picker, lowest first. Authored."},"price_minor":{"type":"integer","format":"int64","description":"What the customer pays per month, in integer minor units."},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 code the price is quoted in."}}},"PartnerAddonOrder":{"type":"object","required":["order_id","human_ref","org_id","status","currency","site_id","subtotal_minor","tax_minor","total_minor","lines"],"properties":{"order_id":{"type":"string","format":"uuid"},"human_ref":{"type":"string","description":"The reference the payment page returns to you as `?order=`."},"pay_url":{"type":"string","description":"Only in the response that placed (or replayed) the order: the hosted page the customer pays on. It carries a secret that is stored nowhere — treat it as one."},"pay_expires_at":{"type":"string","format":"date-time"},"org_id":{"type":"string","format":"uuid"},"status":{"type":"string","description":"As on `PartnerOrder`."},"currency":{"type":"string"},"site_id":{"type":["string","null"],"format":"uuid","description":"The site the add-ons are for."},"subtotal_minor":{"type":"integer"},"tax_minor":{"type":"integer"},"total_minor":{"type":"integer"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/PartnerAddonOrderLine"}}}},"PartnerAddonOrderCreate":{"type":"object","required":["site_id","currency","addons","return_url","cancel_url"],"properties":{"site_id":{"type":"string","format":"uuid","description":"The customer's site the add-ons are for. Its product line decides what is sold."},"currency":{"type":"string","minLength":3,"maxLength":3},"addons":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","required":["code"],"properties":{"code":{"type":"string","maxLength":64,"description":"A code from `listCatalogAddons`."}}}},"billing_country":{"type":"string","maxLength":2,"description":"Overrides the country on the customer's billing profile for this order."},"return_url":{"type":"string","maxLength":2048,"description":"As on a domain order."},"cancel_url":{"type":"string","maxLength":2048,"description":"As on a domain order."},"locale":{"type":"string","maxLength":12,"default":"en","description":"The language the payment page opens in."}}},"PartnerAddonOrderLine":{"type":"object","required":["kind","code","description","interval","term_months","currency","amount_minor","purchase_id","purchase_status"],"properties":{"kind":{"type":"string","description":"Always `extra` (an add-on)."},"code":{"type":"string","description":"The add-on code."},"description":{"type":"string"},"interval":{"type":"string","description":"`monthly` or `one_off`."},"term_months":{"type":"integer","description":"`1` on a monthly add-on, `0` on a one-off."},"currency":{"type":"string"},"amount_minor":{"type":"integer"},"purchase_id":{"type":["string","null"],"format":"uuid","description":"The purchase fulfilment made of this line once paid; `null` before."},"purchase_status":{"type":["string","null"],"description":"That purchase's status — `fulfilling`, `awaiting_staff` (work a person does), `completed`, `failed` or `refunded`; `null` before payment."}}},"PartnerCapabilities":{"type":"object","required":["hosting_orders"],"properties":{"site_moves":{"type":"object","description":"The site-move contract (`createPartnerSiteMove`). Every value is derived: `served` from the mounted route, `plans` from the same functions a move is refused on.","required":["version","served","test_customers_only","archive","statuses","refusal_codes","plans"],"properties":{"version":{"type":"integer","description":"`2` added `dns`, `source`, `step`, `progress`, `elapsed_seconds`, `switch`, `rollback_advised`, the customer-DNS watch and `retryPartnerSiteMove`."},"served":{"type":"boolean","description":"`true` when every linked customer may move a site — open your button on this. While `false`, only your TEST customer can (`test_customers_only`), and any other customer is refused with `moves_not_open`."},"test_customers_only":{"type":"boolean"},"archive":{"type":"object","required":["formats","layout","max_bytes"],"properties":{"formats":{"type":"array","items":{"type":"string"}},"layout":{"type":"string"},"max_bytes":{"type":["null","integer"],"description":"Always `null`: a move has NO size limit (D28455). Room is made for a large archive (the site's disk quota is raised, the target box is waited on); it is slower, never refused. `archive_too_large` is no longer returned."}}},"statuses":{"type":"array","items":{"type":"string"}},"refusal_codes":{"type":"array","items":{"type":"string"}},"plans":{"type":"array","items":{"type":"object","required":["code","product_line","importable","apps"],"properties":{"code":{"type":"string"},"product_line":{"type":"string"},"importable":{"type":"boolean"},"apps":{"type":"array","items":{"type":"string"}}}}}}},"hosting_orders":{"type":"object","required":["version","terms","term_discount_bps","refuses_unfulfillable","region","refusal_codes","plans","addon_orders","addon_order_refusal_codes","trial","resource_boosts","subscriptions"],"properties":{"trial":{"type":"object","required":["served","refusal_codes","reminder_days_before_end","plans","cancel","cancel_refusal_codes"],"description":"The card-free trial on `createPartnerHostingOrder` (`trial: true`). Every value is derived.","properties":{"served":{"type":"boolean","description":"`true` exactly while the engine accepts `trial: true` AND the expiry sweep that ends a trial is switched on — a trial is never offered while nothing would end it. Open your trial choice on this."},"refusal_codes":{"type":"array","items":{"type":"string"}},"reminder_days_before_end":{"type":"integer","description":"How many days before `ends_at` the customer is e-mailed."},"cancel":{"type":"boolean","description":"Whether `cancelPartnerTrial` is served. Derived from the mounted route, never typed."},"cancel_refusal_codes":{"type":"array","items":{"type":"string"},"description":"Every `details[0].code` a trial cancel can be refused with."},"plans":{"type":"array","description":"Every plan with a trial on offer, and its length.","items":{"type":"object","required":["code","trial_days","grace_days"],"properties":{"code":{"type":"string"},"trial_days":{"type":"integer"},"grace_days":{"type":"integer","description":"Days between `ends_at` and `cutoff_at`."}}}}}},"resource_boosts":{"type":"object","description":"The performance-boost contract (`docs/866` §3). `codes` are the add-on codes to order — with the plan on `createPartnerHostingOrder` (the boost applies to the site that order creates, so `site` is required) or later on `createPartnerAddonOrder`. One level per order; a higher level replaces a lower one and credits the lower one's unused days as account credit; removal (`cancelPartnerBoost`) is effective at the end of the paid month with no refund; a trialing subscription is refused. `site_resources` and `cancel` say whether those routes are served, derived from the mounted routes.","required":["version","codes","levels","one_per_order","upgrade","removal","site_resources","cancel","refusal_codes","cancel_refusal_codes"],"additionalProperties":false,"properties":{"version":{"type":"integer"},"codes":{"type":"array","items":{"type":"string"}},"levels":{"type":"array","items":{"type":"integer"}},"one_per_order":{"type":"boolean"},"upgrade":{"type":"string","enum":["replaces_lower_with_credit"]},"removal":{"type":"string","enum":["end_of_paid_month"]},"site_resources":{"type":"boolean"},"cancel":{"type":"boolean"},"refusal_codes":{"type":"array","items":{"type":"string"}},"cancel_refusal_codes":{"type":"array","items":{"type":"string"},"description":"`cancelPartnerBoost` refusals: not_a_boost, not_owned, already_cancelled, already_ended."}}},"addon_orders":{"type":"boolean","description":"Whether `createPartnerAddonOrder` is served. Derived from the mounted route, never typed."},"addon_order_refusal_codes":{"type":"array","items":{"type":"string"},"description":"Every `details[0].code` an add-on order can be refused with."},"version":{"type":"integer","description":"The hosting-order contract in force. `4` added `purchase_id` / `purchase_status` to every hosting-order line, so an add-on bought inside a hosting order reports its delivery the way an add-on order's line does. `5` added the card-free trial (`trial` on the request and the order, and the `trial` block here). `6` added performance boosts (`resource_boosts`), the boost refusal codes (`boost_one_level`, `boost_needs_site`, `boost_adds_nothing`, `boost_on_trial`) and `getPartnerSiteResources` / `cancelPartnerBoost`. `7` (ADR 0036): a customer may hold any number of plan subscriptions and no order cancels another implicitly; `replaces_subscription_id` on the request and the `subscriptions` block here."},"subscriptions":{"type":"object","required":["multiple","replaces_subscription_id","replace_refusal_codes"],"additionalProperties":false,"description":"ADR 0036 (owner ruling 2026-09-28). `multiple`: a customer may hold ANY number of plan subscriptions, on any product line, several on the same line included, and a paid hosting order ADDS a plan — it never cancels or supersedes another. `replaces_subscription_id`: an order may name the ONE live plan subscription it replaces (an upgrade or downgrade on the same product line); exactly that one is cancelled when the order is fulfilled and its sites move onto the new plan. `replace_refusal_codes` are the `details[0].code` values that field can be refused with.","properties":{"multiple":{"type":"boolean"},"replaces_subscription_id":{"type":"boolean"},"replace_refusal_codes":{"type":"array","items":{"type":"string"}}}},"terms":{"type":"array","items":{"type":"integer"}},"term_discount_bps":{"type":"object","additionalProperties":{"type":"integer"},"description":"Basis points off the TOTAL, by term in months, e.g. 3 -> 500. The 12-month entry (1666) is derived: owner D28 (2026-10-06) sells every year at exactly ten months, and the charge is monthly x 10, never this rate applied."},"refuses_unfulfillable":{"type":"boolean"},"region":{"type":"boolean"},"refusal_codes":{"type":"array","items":{"type":"string"}},"plans":{"type":"array","items":{"type":"object","required":["code","orderable","regions"],"properties":{"code":{"type":"string"},"orderable":{"type":"boolean","description":"Whether a new order of this plan is accepted right now."},"regions":{"type":"array","items":{"type":"string"},"description":"The `region` values an order of this plan accepts right now."}}}}}}}},"PartnerConsent":{"type":"object","required":["partner","customer_email","org_id","org_name","expires_at","scopes"],"properties":{"partner":{"type":"string"},"customer_email":{"type":"string","format":"email"},"org_id":{"type":"string","format":"uuid"},"org_name":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"scopes":{"type":"array","items":{"type":"string"},"description":"The permissions the partner would hold in this organization."}}},"PartnerConsentSent":{"type":"object","required":["state","sent","expires_at"],"properties":{"state":{"type":"string"},"sent":{"type":"boolean"},"expires_at":{"type":"string","format":"date-time"}}},"PartnerCustomer":{"type":"object","required":["external_id","org_id","state","created_org","has_registrant","email"],"properties":{"external_id":{"type":"string"},"org_id":{"type":"string","description":"The organization you may act on, as `X-Zinn-Org`. Empty while the link is not active — a pending link names no organization you may use."},"state":{"type":"string","enum":["active","pending_consent","revoked"]},"created_org":{"type":"boolean","description":"Whether we made this organization for you, or the customer already had one."},"has_registrant":{"type":"boolean","description":"Whether a registrant contact is on file. An order is refused until it is."},"email":{"type":"string","format":"email"}}},"PartnerCustomerCreate":{"type":"object","required":["external_id","email"],"properties":{"external_id":{"type":"string","maxLength":128,"description":"Your own id for the customer."},"email":{"type":"string","format":"email"},"name":{"type":"string","maxLength":200},"country":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2. Used for tax determination and on the invoice."},"currency":{"type":"string","minLength":3,"maxLength":3,"default":"USD"},"attribution":{"type":"object","description":"Optional. Where YOU say this customer came from — your own first-party attribution: `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`, `gclid`, `gbraid`, `wbraid`, `fbclid`, `ttclid`, `msclkid`, `twclid`, `ref`, `referrer_host`, `landing_page` (host + path). Unknown keys are dropped. Recorded once, as the first touch of an organization this call creates; it never replaces a source we already hold.","additionalProperties":{"type":"string","maxLength":2048}}}},"PartnerDomainItem":{"type":"object","required":["fqdn"],"description":"One domain to buy: a registration (the default) or a transfer-in of a name the customer already holds at another registrar. A registration needs `availability_token`; a transfer needs `auth_code`, is for one year, and is refused with the preflight's reason when `POST /v1/domains/transfer/preflight` would call it ineligible. A transfer is priced from the same transfer price that preflight quotes.","properties":{"fqdn":{"type":"string","maxLength":253},"kind":{"type":"string","enum":["domain_register","domain_transfer","local_presence_addon"],"default":"domain_register","description":"What the line buys. Absent means a registration. `local_presence_addon` buys the registry's local presence (trustee) service for a name already ordered and HELD because the registry wants an owner in its own country (`lines[].waiting_for_local_presence` on `getPartnerDomainOrder`): name that line in `held_line_id`. Its years are the held line's; paying for it releases the held registration."},"local_presence":{"type":"boolean","default":false,"description":"On a registration or transfer: also buy the registry's local presence (trustee) service for this domain, for the same years, so a customer outside the registry's country can own it (`getTldRequirements` -> `local_presence_addon` gives the price, and whether it is for companies only). Refused (`422`) when the customer's owner already qualifies or no service is sold. Promo codes never apply to it."},"held_line_id":{"type":"string","format":"uuid","description":"With `kind: local_presence_addon` only: the `line_id` of this customer's held order line."},"period_years":{"type":"integer","minimum":1,"maximum":10,"default":1,"description":"Years to register. A transfer must be `1`."},"privacy":{"type":"boolean","default":true},"auto_renew":{"type":"boolean","default":true},"availability_token":{"type":"string","description":"The token `/v1/domains/search` issued for this exact name. Required for a registration, and re-verified server-side — it proves the name was free, it never sets the price. Not used for a transfer."},"auth_code":{"type":"string","maxLength":255,"writeOnly":true,"description":"The authorisation (EPP) code from the registrar the domain is held at. Required for a transfer. Write-only: it is kept in the secret store, never stored with the order and never returned."},"registry_data":{"$ref":"#/components/schemas/RegistryData"}}},"PartnerDomainOrderCreate":{"type":"object","required":["items","currency","return_url","cancel_url"],"properties":{"return_url":{"type":"string","maxLength":2048,"description":"Where the customer's browser goes once the order is paid. `https`, on a host allowlisted for your programme (exact match, default port, no userinfo)."},"cancel_url":{"type":"string","maxLength":2048,"description":"Where the browser goes if the customer leaves without paying. Same rules."},"locale":{"type":"string","maxLength":12,"default":"en","description":"The language the payment page opens in."},"items":{"type":"array","minItems":1,"maxItems":20,"items":{"$ref":"#/components/schemas/PartnerDomainItem"}},"currency":{"type":"string","minLength":3,"maxLength":3},"billing_country":{"type":"string","minLength":2,"maxLength":2,"description":"Overrides the country on the customer's billing profile for this order."}}},"PartnerEvent":{"type":"object","required":["id","type","occurred_at","external_id","data"],"properties":{"id":{"type":"string","format":"uuid","description":"Unique per event; de-duplicate on it. Also the cursor."},"type":{"type":"string","description":"An `order.*` (`placed`, `paid`, `payment_failed`, `fulfilled`, `partially_fulfilled`, `canceled`, `refunded`) or `domain.*` (`registered`, `registration_failed`, `nameservers_changed`, `expiring`, `expired`, `renewed`, `entered_redemption`, `restored`, `suspended`, `transferred_out`, `deleted`) event."},"occurred_at":{"type":"string","format":"date-time"},"external_id":{"type":"string","description":"Your id for the customer the event concerns."},"data":{"type":"object","additionalProperties":true,"description":"For `order.*`: `order_id`, `human_ref`, `status`, `previous_status`, `currency`, `total_minor`, `reason` and `reason_code`. On `order.partially_fulfilled`, `reason` is a sentence safe to show the customer and `reason_code` its type (`delegation_unknown`, `registrant_local_presence`, `transfer_rejected`, `transfer_auth_code`, or `delivery_failed`); both are \"\" when there is none. For `domain.*`: `domain_id`, `fqdn`, `status`, and where known `previous_status`, `expires_at`, `nameservers` — except `domain.registrant_email_flagged` and `domain.registrant_email_confirmed`, which carry `registrant_email`, `deadline_at`, `suspended`, `domain_count` and `domains` (see `reportPartnerRegistrantEmailReminder`)."}}},"PartnerEventPage":{"type":"object","required":["events","next_cursor","has_more"],"properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/PartnerEvent"}},"next_cursor":{"type":"string","description":"Pass as `after` next time. Unchanged when the page is empty."},"has_more":{"type":"boolean"}}},"PartnerHostingOrder":{"type":"object","required":["order_id","human_ref","org_id","status","currency","term_months","subtotal_minor","tax_minor","total_minor","lines","site","subscription_id","trial"],"properties":{"order_id":{"type":"string","format":"uuid"},"human_ref":{"type":"string","description":"The reference the payment page returns to you as `?order=`."},"pay_url":{"type":"string","description":"Only in the response that placed (or replayed) the order: the hosted page the customer pays on. It carries a secret that is stored nowhere — treat it as one. Absent on a trial order, which has nothing to pay."},"pay_expires_at":{"type":"string","format":"date-time"},"org_id":{"type":"string","format":"uuid"},"trial":{"oneOf":[{"$ref":"#/components/schemas/PartnerHostingTrial"},{"type":"null"}],"description":"Present on an order placed with `trial: true`; `null` on every other order. Until fulfilment starts the trial, `status` is `pending` and the dates are `null`."},"replaces_subscription_id":{"type":["string","null"],"format":"uuid","description":"The live plan subscription this order replaces, as named on the request (ADR 0036); `null` when the order ADDS a plan. Once fulfilled that subscription is `canceled` and `subscription_id` is its replacement."},"status":{"type":"string","description":"As on `PartnerOrder`."},"currency":{"type":"string"},"term_months":{"type":"integer"},"subtotal_minor":{"type":"integer"},"tax_minor":{"type":"integer"},"total_minor":{"type":"integer"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/PartnerHostingOrderLine"}},"site":{"oneOf":[{"$ref":"#/components/schemas/PartnerHostingOrderSite"},{"type":"null"}]},"subscription_id":{"type":["string","null"],"format":"uuid","description":"The subscription the paid plan line became; `null` until fulfilment."}}},"PartnerHostingOrderCreate":{"type":"object","required":["term_months","currency","return_url","cancel_url"],"properties":{"plan_code":{"type":"string","maxLength":64,"description":"The plan's `code` from `listInAppCatalogPlans`. This or `plan_version_id`."},"plan_version_id":{"type":["string","null"],"format":"uuid","description":"The plan's current `plan_version_id`. This or `plan_code`."},"term_months":{"type":"integer","enum":[1,3,6,12],"description":"The term to sell, in months. A published interval that covers it is used as-is; otherwise it is N months of the monthly price, with no discount. Ignored on a trial order, which is recorded as one month at 0."},"trial":{"type":"boolean","default":false,"description":"Start the plan's card-free trial instead of selling it: priced at 0, settled with no payment step, never converted or charged automatically. One per customer, ever; no `addons`. See the operation description."},"trial_id":{"type":["string","null"],"format":"uuid","description":"On a PAID order (`trial` false): the trial this purchase converts — its `trial.trial_id`. Optional. When set, the plan must be one of that trial's `subscribe.plan_codes` (any tier of the same product line), else `422` `trial_subscribe_other_line`; a trial that is `canceled`, `converted` or not yours is `trial_not_convertible`. On payment the trial converts and its site moves onto the new plan."},"replaces_subscription_id":{"type":["string","null"],"format":"uuid","description":"On a PAID order (`trial` false): the customer's live plan subscription this order REPLACES — an upgrade or downgrade (`hosting_orders.version` 7, ADR 0036). Omitted, the plan is ADDED beside every plan the customer already holds and nothing is cancelled: a customer may hold any number of plans, several on one product line included. Named, exactly that subscription is cancelled when this order is fulfilled, and its sites move onto the new plan. Refused `422` with `replaces_not_found` (not a live plan of this customer), `replaces_other_line` (a plan on a different product line — buy it as an additional plan instead; a plan on a retired line may be replaced by its successor line's plan, e.g. `wordpress` or `fleet_enterprise` by the one WordPress line `mainstream`) or `replaces_on_trial` (a trial replaces nothing)."},"currency":{"type":"string","minLength":3,"maxLength":3},"site":{"oneOf":[{"$ref":"#/components/schemas/PartnerHostingSite"},{"type":"null"}]},"addons":{"type":"array","maxItems":20,"items":{"type":"object","required":["code"],"properties":{"code":{"type":"string","maxLength":64,"description":"A code from `listCatalogAddons`."}}}},"billing_country":{"type":"string","maxLength":2,"description":"Overrides the country on the customer's billing profile for this order."},"region":{"type":"string","maxLength":32,"description":"Where the customer chose to be hosted. Refused (`region_unknown` / `region_unavailable`) unless we can place a site there today; omitted, our default location. A site without its own `region` takes this one."},"return_url":{"type":"string","maxLength":2048,"description":"As on a domain order."},"cancel_url":{"type":"string","maxLength":2048,"description":"As on a domain order."},"locale":{"type":"string","maxLength":12,"default":"en","description":"The language the payment page opens in."}}},"PartnerHostingOrderLine":{"type":"object","required":["kind","code","description","interval","term_months","currency","amount_minor","purchase_id","purchase_status"],"properties":{"kind":{"type":"string","description":"`hosting_plan` or `extra` (an add-on)."},"code":{"type":"string","description":"The plan code or the add-on code."},"description":{"type":"string"},"interval":{"type":"string","description":"`monthly`, `annual` or `one_off`."},"term_months":{"type":"integer","description":"How many months this line buys — `0` on a one-off add-on."},"currency":{"type":"string"},"amount_minor":{"type":"integer"},"purchase_id":{"type":["string","null"],"format":"uuid","description":"On an `extra` line, the purchase fulfilment made of it once the order was paid — the same row `getPartnerAddonOrder` reports for an add-on bought later. `null` before payment, and always `null` on the `hosting_plan` line (the plan becomes `subscription_id`). Since `hosting_orders.version` 4."},"purchase_status":{"type":["string","null"],"description":"That purchase's status — `fulfilling`, `awaiting_staff` (work a person does), `completed`, `failed` or `refunded`; `null` before payment and on the `hosting_plan` line. Since `hosting_orders.version` 4."}}},"PartnerHostingOrderSite":{"type":"object","required":["domain","app","region","temporary_domain","site_id","status","error"],"properties":{"domain":{"type":"string"},"temporary_domain":{"type":"boolean","description":"Whether `domain` is an address we minted because none was sent."},"app":{"type":"string"},"region":{"type":"string"},"site_id":{"type":["string","null"],"format":"uuid","description":"`null` until created."},"status":{"type":["string","null"],"description":"The site's own status once created."},"error":{"type":["string","null"],"description":"Why the paid order could not create the site, when it could not."}}},"PartnerHostingSite":{"type":"object","properties":{"domain":{"type":"string","maxLength":253,"description":"The site's hostname. Omitted, we mint a temporary address on our own preview domain and return it on the order."},"app":{"type":"string","maxLength":64,"description":"A one-click application `key` from `listCatalogApplications`, or a stack name (`wordpress`, `woocommerce`, `static`, …). `woocommerce` is WordPress with WooCommerce installed and ready. Omitted on an application plan (`app_*`), that plan's own application is installed; omitted on any other plan it is a `422` (`app_required`)."},"region":{"type":"string","maxLength":32,"description":"A region `code` from `listHostingRegions` for the plan's product line. Omitted, we place it. A region we run with no capacity today is refused before the order exists with `region_unavailable`; a string that is not one of our regions with `region_unknown`."}}},"PartnerHostingSlot":{"type":"object","required":["kind","subscription_id","plan_code","product_line","max_sites","used_sites","free_sites","available_sites","trial_ends_at","importable","accepts_apps","replaceable_sites"],"properties":{"kind":{"type":"string","enum":["subscription","trial"],"description":"What holds the slot. A trial's id is still passed as `subscription_id`."},"subscription_id":{"type":"string","format":"uuid","description":"The subscription's id, or the trial's id when `kind` is `trial`."},"trial_ends_at":{"type":["string","null"],"format":"date-time"},"available_sites":{"type":"integer","description":"`free_sites` plus the replaceable sites; -1 means unlimited."},"plan_code":{"type":"string"},"product_line":{"type":"string"},"max_sites":{"type":"integer","description":"-1 means unlimited."},"used_sites":{"type":"integer"},"free_sites":{"type":"integer","description":"-1 means unlimited."},"importable":{"type":"boolean","description":"Whether this plan's sites can take an imported archive."},"accepts_apps":{"type":"array","items":{"type":"string"}},"replaceable_sites":{"type":"array","items":{"type":"object","required":["site_id","hostname","replaceable","replaceable_reason"],"properties":{"site_id":{"type":"string","format":"uuid"},"hostname":{"type":"string"},"replaceable":{"type":"boolean","const":true},"replaceable_reason":{"type":"string","enum":["temporary_host","empty_starter"]}}}}}},"PartnerHostingSlots":{"type":"object","required":["slots"],"properties":{"slots":{"type":"array","items":{"$ref":"#/components/schemas/PartnerHostingSlot"}}}},"PartnerHostingTrial":{"type":"object","required":["trial_id","status","plan_code","started_at","ends_at","cutoff_at","converted_subscription_id","subscribe"],"properties":{"trial_id":{"type":["string","null"],"format":"uuid"},"status":{"type":"string","enum":["pending","active","expired","converted","canceled"],"description":"`pending` until fulfilment starts it; `active` while the site serves free — including the grace window between `ends_at` and `cutoff_at`; `expired` once `cutoff_at` has passed and the trial's site is suspended; `converted` once the customer has paid for a plan (the site moved onto it); `canceled` by staff."},"plan_code":{"type":"string","description":"The plan trialled."},"started_at":{"type":["string","null"],"format":"date-time"},"ends_at":{"type":["string","null"],"format":"date-time","description":"The end of the free period. The customer is e-mailed before it and at it; nothing is charged at it."},"cutoff_at":{"type":["string","null"],"format":"date-time","description":"`ends_at` plus the grace window: when the trial is revoked and its site suspended if nothing has been bought. It moves if staff extend the trial."},"converted_subscription_id":{"type":["string","null"],"format":"uuid"},"subscribe":{"type":"object","required":["plan_code","plan_codes","terms"],"description":"How the customer keeps the site: place an ordinary paid order (`createPartnerHostingOrder`, `trial` false, `trial_id` this trial, **no** `site`) for `plan_code` or any of `plan_codes` in one of `terms`, and send them its `pay_url`. Valid in every status but `converted` and `canceled`.","properties":{"plan_code":{"type":"string","description":"The plan trialled — the default choice."},"plan_codes":{"type":"array","items":{"type":"string"},"description":"Every plan on the trial's product line orderable right now (e.g. Starter, Plus, Pro). The trial's site moves onto whichever is bought."},"terms":{"type":"array","items":{"type":"integer"}}}}}},"PartnerMarketplaceWithdrawalRequest":{"type":"object","additionalProperties":false,"required":["slugs"],"properties":{"id":{"type":"string","maxLength":200,"description":"The sender's own event id, for its logs and ours."},"reason":{"type":"string","maxLength":64,"description":"Why, in V1's words (`seller_banned`, `removed`, `retired`, ...)."},"slugs":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"string","minLength":1,"maxLength":255},"description":"V1 listing slugs."}}},"PartnerMarketplaceWithdrawalResult":{"type":"object","required":["archived","already_gone","unknown","purged_urls","purge_ok","indexnow_urls","announce"],"properties":{"archived":{"type":"array","items":{"type":"string"}},"already_gone":{"type":"array","items":{"type":"string"}},"unknown":{"type":"array","items":{"type":"string"}},"purged_urls":{"type":"integer"},"purge_ok":{"type":"boolean"},"indexnow_urls":{"type":"integer"},"announce":{"type":"string","enum":["none","workflow","inline"],"description":"How the purge and IndexNow step runs: `workflow` (started, after the response), `inline` (done before the response; the counts above are its result) or `none`."}}},"PartnerOrder":{"type":"object","required":["order_id","human_ref","org_id","status","currency","subtotal_minor","tax_minor","total_minor","lines"],"properties":{"order_id":{"type":"string","format":"uuid"},"human_ref":{"type":"string","description":"The reference the payment page returns to you as `?order=`."},"pay_url":{"type":"string","description":"Only in the response that placed (or replayed) the order: the hosted page the customer pays on. It carries a secret that is stored nowhere — treat it as one."},"pay_expires_at":{"type":"string","format":"date-time"},"org_id":{"type":"string","format":"uuid"},"status":{"type":"string","description":"`pending_payment` for a freshly placed order; afterwards the order's lifecycle (`paid`, `fulfilling`, `completed`, `partially_fulfilled`, `canceled`, …)."},"currency":{"type":"string"},"subtotal_minor":{"type":"integer"},"tax_minor":{"type":"integer"},"total_minor":{"type":"integer"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/PartnerOrderLine"}}}},"PartnerOrderDomain":{"type":"object","required":["domain_id","status","nameservers","expires_at"],"properties":{"domain_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"nameservers":{"type":"array","items":{"type":"string"}},"expires_at":{"type":["string","null"],"format":"date-time"}}},"PartnerOrderLine":{"type":"object","required":["line_id","kind","waiting_for_local_presence","domain_name","period_years","amount_minor"],"properties":{"line_id":{"type":"string","format":"uuid","description":"The order line's id; a `local_presence_addon` item names it as `held_line_id`."},"kind":{"type":"string","enum":["domain_register","domain_transfer","local_presence_addon"]},"waiting_for_local_presence":{"type":"boolean","description":"`true` when the registry refused the owner as not local and the line is held: place a domain order with a `local_presence_addon` item naming this `line_id` to release it."},"domain_name":{"type":"string"},"period_years":{"type":"integer"},"amount_minor":{"type":"integer"},"domain":{"description":"Only on `getPartnerDomainOrder`: the domain this line became, or `null` until provisioning has created it.","oneOf":[{"$ref":"#/components/schemas/PartnerOrderDomain"},{"type":"null"}]}}},"PartnerOwnPluginBuilds":{"type":"object","required":["digest_version","builds","queued"],"properties":{"digest_version":{"type":"string","example":"v1"},"queued":{"type":"integer","description":"How many `want` pairs were newly queued for a lookup."},"builds":{"type":"array","items":{"type":"object","required":["dir","version","source","digest","manifest"],"properties":{"dir":{"type":"string","description":"The folder the build installs under."},"version":{"type":"string"},"source":{"type":"string","enum":["channel","wporg","freemius","freemius-premium"]},"digest":{"type":"string","description":"`<digest_version>:<sha256>`"},"manifest":{"type":"object","description":"Every file of the build: `f` path -> size, `h` path -> sha256, `d` the directories. The per-file rule exempts a file inside one of our plugin folders only when its path is a released file and its size is within min(2 KB, 10%) of the released size; the sha256 is the integrity check and the malware-scan allowlist (a file of ours is known by its hash, never by its path).","additionalProperties":true}}}}}},"PartnerPanelAccess":{"type":"object","required":["member","email","panel_url","invitation"],"properties":{"member":{"type":"boolean","description":"The linked e-mail already belongs to the customer's organization."},"email":{"type":"string","format":"email"},"panel_url":{"type":"string","format":"uri","description":"The control-panel address to give the customer."},"invitation":{"oneOf":[{"type":"null"},{"type":"object","required":["status","sent_at","expires_at","email"],"properties":{"status":{"type":"string","enum":["pending","accepted","revoked","expired"]},"sent_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"email":{"type":"string","format":"email"}}}]}}},"PartnerPanelInvite":{"type":"object","required":["status","invitation_id","accept_url","email"],"properties":{"status":{"type":"string","enum":["invited","already_member"]},"invitation_id":{"type":["string","null"],"format":"uuid"},"accept_url":{"type":"string","format":"uri"},"email":{"type":"string","format":"email"}}},"PartnerPanelSession":{"type":"object","required":["url","expires_at","client_org_id"],"properties":{"url":{"type":"string","format":"uri","description":"Open this in the customer's browser. The single-use ticket is in the fragment; redeem once, within 300 seconds."},"expires_at":{"type":"string","format":"date-time","description":"When the SESSION ends (one hour), not the ticket."},"client_org_id":{"$ref":"#/components/schemas/Uuid"}}},"PartnerPanelSessionRequest":{"type":"object","properties":{"site_id":{"type":["string","null"],"format":"uuid","description":"Open the session on this site (it must be in the customer's organization)."},"next":{"type":"string","enum":["/store","/servers/new","/billing/plan","/sites/new/buy"],"description":"Land on this page after sign-in instead of the dashboard (ignored when `site_id` is set) — for a line the partner does not sell itself (owner D7, 2026-10-06). A fixed allow-list; any other value is a `422` on `next`."}}},"PartnerPayment":{"type":"object","required":["order","status","partner","currency","lines","subtotal","tax","total","total_minor","rails","return_url","cancel_url","labels","locale","direction"],"properties":{"order":{"type":"string","description":"The order's human reference."},"status":{"type":"string","enum":["payable","paid"]},"partner":{"type":"string"},"currency":{"type":"string"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/PartnerPaymentLine"}},"subtotal":{"type":"string"},"tax":{"type":"string"},"total":{"type":"string"},"total_minor":{"type":"integer"},"rails":{"type":"array","items":{"type":"string","enum":["card"]}},"return_url":{"type":"string","description":"Set once paid; empty otherwise."},"cancel_url":{"type":"string","description":"Set while payable; empty once paid."},"labels":{"type":"object","additionalProperties":{"type":"string"}},"locale":{"type":"string"},"direction":{"type":"string","enum":["ltr","rtl"]}}},"PartnerPaymentLine":{"type":"object","required":["domain","years","amount","amount_minor"],"properties":{"domain":{"type":"string","description":"The domain name, or — on a hosting order — the line's description."},"years":{"type":"integer"},"term":{"type":"string","description":"Only on a non-domain line: how it is billed (\"Monthly\", \"One-off\"), localised. Shown in place of `years`."},"amount":{"type":"string","description":"Formatted for the page's locale."},"amount_minor":{"type":"integer"}}},"PartnerPaymentStep":{"type":"object","required":["status","settled","client_token","setup_intent_id","redirect_url","action_kind","paypal_order_id","rail","return_url"],"properties":{"status":{"type":"string"},"settled":{"type":"boolean"},"client_token":{"type":"string","description":"A card-form client secret for the browser SDK, when one is needed."},"setup_intent_id":{"type":"string"},"redirect_url":{"type":"string","description":"Where to send the browser to approve the payment on a rail that finishes off-site — a crypto invoice today. Empty on the card and PayPal rails, both of which finish on this page."},"action_kind":{"type":"string"},"paypal_order_id":{"type":"string","description":"The PayPal order the browser's SDK attaches to, on the PayPal rail. Minted by us — an id a client invents is refused by the gateway, not honoured."},"rail":{"type":"string","description":"Which rail this step belongs to (`stripe`, `paypal`, `nowpayments`)."},"return_url":{"type":"string","description":"The partner URL to send the browser to","once paid.":null}}},"PartnerProDiscountCodeRequest":{"type":"object","additionalProperties":false,"required":["external_id","email","product","hosting_in_good_standing"],"properties":{"external_id":{"type":"string","minLength":1,"maxLength":128,"example":"v1-10442"},"email":{"type":"string","format":"email","maxLength":320},"product":{"type":"string","example":"tranzly"},"hosting_in_good_standing":{"type":"boolean","description":"Your assertion, on every call, that this customer holds a paid hosting plan in good standing with you now. `false` is refused."}}},"PartnerProDiscountIssued":{"type":"object","additionalProperties":false,"required":["external_id","product","created","code"],"properties":{"external_id":{"type":"string"},"product":{"type":"string"},"created":{"type":"boolean"},"code":{"$ref":"#/components/schemas/ProDiscountCode"}}},"PartnerProDiscountOffers":{"type":"object","additionalProperties":false,"required":["terms","offers"],"properties":{"terms":{"$ref":"#/components/schemas/ProDiscountTerms"},"offers":{"type":"array","items":{"$ref":"#/components/schemas/ProDiscountOffer"}}}},"PartnerProvenPluginRelease":{"type":"object","additionalProperties":false,"required":["plugin","version","zip_url","sha256","proven_at","notes"],"properties":{"plugin":{"type":"string","enum":["tranzly","page-builder-sandwich","zinn-chat","zinn-footprint","tranzly-premium","page-builder-sandwich-premium"]},"version":{"type":"string","example":"2.7.2"},"edition":{"type":"string","enum":["licensed"],"description":"Present only on a licensed-build row (first-party partner only). The plugin folder is `<base_plugin>-premium`, never laid over a free install."},"base_plugin":{"type":"string","enum":["tranzly","page-builder-sandwich"],"description":"The free plugin this licensed build belongs to (licensed rows only)."},"zip_url":{"type":"string","format":"uri","description":"HTTPS, on our API host. A free build downloads with no credentials (signed grant); a licensed build needs the same partner key.","example":"https://api.zinndigital.com/v1/partner/plugin-packages/zinn-chat/2.7.2?exp=1760054400&sig=0a9dc78b5d3b0aefc3163e16f6d486feb772ba9888880ab80c13ff69702fa6e8"},"sha256":{"type":"string","minLength":64,"maxLength":64,"description":"Lowercase hex SHA-256 of exactly the bytes at `zip_url`."},"proven_at":{"type":"string","format":"date-time","description":"When the first staff or test site on the canary ring kept this version."},"notes":{"type":"string"},"db_state":{"type":"object","additionalProperties":false,"description":"What of a site's database the plugin owns, as SQL LIKE patterns: its options, its tables (relative to the site's table prefix) and its post-meta keys. Snapshot them before the update and restore them on a rollback (docs/899 §11).","required":["options","tables","postmeta"],"properties":{"options":{"type":"array","items":{"type":"string","pattern":"^[A-Za-z0-9_%\\\\-]+$"}},"tables":{"type":"array","items":{"type":"string","pattern":"^[A-Za-z0-9_%\\\\-]+$"}},"postmeta":{"type":"array","items":{"type":"string","pattern":"^[A-Za-z0-9_%\\\\-]+$"}}}}}},"PartnerProvenPluginReleases":{"type":"object","additionalProperties":false,"required":["releases"],"properties":{"releases":{"type":"array","description":"At most one entry per plugin — its newest proven, unhalted version.","items":{"$ref":"#/components/schemas/PartnerProvenPluginRelease"}}}},"PartnerRegistrant":{"type":"object","required":["first","last","email","phone","street","city","postcode","country"],"properties":{"first":{"type":"string","maxLength":128},"last":{"type":"string","maxLength":128},"org_name":{"type":"string","maxLength":200},"email":{"type":"string","format":"email"},"phone":{"type":"string","maxLength":32},"street":{"type":"array","minItems":1,"maxItems":3,"items":{"type":"string","maxLength":200}},"city":{"type":"string","maxLength":128},"state":{"type":"string","maxLength":128},"postcode":{"type":"string","maxLength":32},"country":{"type":"string","minLength":2,"maxLength":2}}},"PartnerRegistrantReminder":{"type":"object","required":["registrant_email","deadline_at","stage","sent_at"],"properties":{"registrant_email":{"type":"string","format":"email","maxLength":254},"deadline_at":{"type":"string","format":"date-time","description":"The `deadline_at` of the `domain.registrant_email_flagged` event."},"stage":{"type":"string","pattern":"^[a-z0-9_-]{1,32}$","description":"Your own name for this step of your reminder ladder, e.g. `notice`, `72h`."},"sent_at":{"type":"string","format":"date-time"},"channel":{"type":"string","enum":["email","ticket","in_app"],"default":"email"}}},"PartnerRegistrantReminderRecorded":{"type":"object","required":["recorded","reports_for_deadline"],"properties":{"recorded":{"type":"boolean"},"reports_for_deadline":{"type":"integer","description":"How many reminders you have reported for this e-mail and deadline."}}},"PartnerSiteMove":{"type":"object","required":["id","status","domain","app","subscription_id","v2_site_id","source_ref","preview_url","origin","tls","checks","error_code","error","replaced_site","created_at","updated_at","live_at"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","importing","imported","going_live","live","failed","cancelled"],"description":"`imported` — built and answering on `preview_url`; switch DNS, then call `goLivePartnerSiteMove`. `live` — the domain is served by us over HTTPS; only now delete the original."},"domain":{"type":"string"},"app":{"type":"string"},"subscription_id":{"type":"string","format":"uuid"},"v2_site_id":{"type":["string","null"],"format":"uuid","description":"Our site id, once the site exists."},"source_ref":{"type":"string"},"replaced_site":{"type":"boolean","description":"Whether the move imported into an existing empty site."},"preview_url":{"type":"string","description":"An `https` address that serves the imported site with no DNS change, or `\"\"` until `imported`."},"origin":{"type":"object","required":["a","aaaa","cname"],"description":"What the domain's web record must point at. Publish an `A` to each `a` address; `aaaa` is empty while the box has no IPv6 — publish no `AAAA` then.","properties":{"a":{"type":"array","items":{"type":"string"}},"aaaa":{"type":"array","items":{"type":"string"}},"cname":{"type":"string"}}},"tls":{"type":"object","required":["state","detail"],"properties":{"state":{"type":"string","enum":["pending","issued","deferred","failed"],"description":"The origin certificate for `domain`. `deferred` until the domain reaches us."},"detail":{"type":"string"}}},"checks":{"type":"object","required":["http_status","title","bytes","database_imported"],"description":"What we measured on the preview after the import.","properties":{"http_status":{"type":"integer"},"title":{"type":"string"},"bytes":{"type":"integer"},"database_imported":{"type":"boolean"}}},"error_code":{"type":"string"},"error":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"live_at":{"type":["string","null"],"format":"date-time"},"step":{"type":"string","enum":["queued","creating_site","waiting_for_space","downloading","importing_files","importing_database","checking","ready_to_switch","waiting_for_dns","switching","securing","live","failed","cancelled"],"description":"Where the move is, finer than `status` — show it with `progress` and `elapsed_seconds` so a long import never looks crashed. There is no size limit and no clock on a move's size (D28455), so a large move is simply long. **`waiting_for_space`**: the server is short of disk for this archive; the move re-checks every 10 minutes by itself (`progress.unit` `mb_free`: `done` = free MB on the server, `total` = MB it needs) and continues — never a refusal, `status` stays `importing`. **Is it advancing?** While `status` is `importing` the platform re-reads the server every ~10 s and writes `updated_at` each time it gets an answer: `progress.done` rises during `downloading` (`bytes`) and `importing_files` (`files`); `importing_database` has no counter (only `step_started_at` and `updated_at`). **A real stall** is `updated_at` not moving for 15 minutes while `status` is `importing` (we have lost the server), or `progress.done` not moving for 60 minutes in `downloading`/`importing_files`. A long `importing_database` or a `waiting_for_space` is not a stall."},"progress":{"type":"object","required":["percent","done","total","unit"],"description":"Measured on the hosting box while it applies the archive. `null` means not known yet — never zero.","properties":{"percent":{"type":["integer","null"]},"done":{"type":["integer","null"]},"total":{"type":["integer","null"]},"unit":{"type":["string","null"],"enum":["bytes","files","mb_free",null]}}},"started_at":{"type":"string","format":"date-time"},"step_started_at":{"type":["string","null"],"format":"date-time"},"elapsed_seconds":{"type":"integer"},"retryable":{"type":"boolean"},"dns_case":{"type":"string","enum":["partner_switch","customer_switch","unknown"]},"dns_holder":{"type":"string"},"switch":{"type":"object","description":"EXACTLY what to publish for the domain to be served by us.","required":["records","ssl_mode","ssl_mode_after_live","www","no_ipv6"],"properties":{"records":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"value":{"type":"string"},"proxied":{"type":["boolean","null"]}}}},"ssl_mode":{"type":["string","null"]},"ssl_mode_after_live":{"type":["string","null"]},"www":{"type":"boolean"},"no_ipv6":{"type":"boolean","description":"Publish no AAAA — the hosting box has no IPv6 address."}}},"rollback_advised":{"type":"boolean","description":"Your switch did not take within the attempt: restore the records you saved in `dns.current`. The original never stopped serving."},"waiting_since":{"type":["string","null"],"format":"date-time"},"reminders_sent":{"type":"integer"},"extra_disk_mb":{"type":"integer","minimum":0,"description":"Free disk space (MB) this move gave the site on top of its plan so the move could land whatever its size (D28455). `0` when the plan's own space was enough. Always present."},"extra_disk_expires_at":{"type":["string","null"],"format":"date-time","description":"When `extra_disk_mb` ends: **7 days after `live_at`** (D28457). `null` while the move is still running (the extra is open-ended until it goes live) or when there is no extra. Nothing is deleted then: the site's disk ceiling returns to the plan's, and the ordinary quota warnings, and a freeze on writes if the site stays over, take over. The customer is told at go-live and again 48 hours before — show the date beside the move so they can upgrade or clean up in time. A retried move re-opens it until its new go-live."}}},"PartnerSiteMoveCreate":{"type":"object","required":["subscription_id","domain","app","archive_url","archive_sha256"],"properties":{"subscription_id":{"type":"string","format":"uuid","description":"The customer's hosting subscription the site moves onto — a `subscription_id` from `listPartnerHostingSlots`."},"domain":{"type":"string","maxLength":253,"description":"The hostname the site serves on, apex or subdomain. Its DNS stays where it is."},"app":{"type":"string","maxLength":64,"description":"What the site is built with: `wordpress`, `php` (a plain PHP or static-HTML document root) or an application key the plan lists in `site_moves.plans[].apps`."},"php_version":{"type":"string","maxLength":8,"description":"Optional PHP version, e.g. `8.3`. Omit for the plan's default."},"archive_url":{"type":"string","format":"uri","maxLength":2048,"description":"The `https` link to the archive. Never echoed back."},"archive_sha256":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Lower-case hex SHA-256 of the archive file, checked before it is applied."},"archive_bytes":{"type":"integer","minimum":0,"description":"The archive's size in bytes, when you know it."},"replace_site_id":{"type":["string","null"],"format":"uuid","description":"Import into this empty site instead of taking a new slot — one of `listPartnerHostingSlots` `replaceable_sites`."},"source_ref":{"type":"string","maxLength":128,"description":"Your own id for the site being moved, echoed back on every read."},"dns":{"$ref":"#/components/schemas/PartnerSiteMoveDns"},"source":{"type":"object","description":"Facts about the source site the post-import fix-ups use.","properties":{"docroot":{"type":"string","maxLength":500,"description":"The site's document root on the source server (e.g. `/var/www/example.com/www`). Absolute paths to it in `.user.ini`, `.htaccess`, Wordfence's WAF loader and the database are rewritten to ours. Optional: when absent it is detected from the WAF's `auto_prepend_file`."},"hosts":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":253},"description":"Other hostnames the site was served at on the source (a temporary host, an old domain). Every stored form of each (plain, JSON-escaped, URL-encoded, serialised) is rewritten to the move's domain, and the move is not `imported` until a crawl of the site finds none of them."}}}}},"PartnerSiteMoveDns":{"type":"object","description":"Where the domain's zone is held and who changes it. Omitted, it is `unknown` and the customer-switch path applies (exact records shown and e-mailed, change detected).","properties":{"holder":{"type":"string","enum":["partner_cloudflare","partner_bunny","partner_other","customer_cloudflare","customer_bunny","customer_other","unknown"]},"auto_switch":{"type":"boolean","description":"`true` when YOU hold working credentials for the zone and will repoint it — this decides `dns_case: partner_switch` whatever the holder."},"proxied":{"type":["boolean","null"]},"ssl_mode":{"type":["string","null"],"enum":[false,"flexible","full","strict",null]},"has_www":{"type":"boolean","description":"The site uses `www.` too; we serve it and it is in `switch.records`."},"nameservers":{"type":"array","items":{"type":"string"}},"current":{"type":"array","description":"The web records you will change, so a rollback restores them exactly.","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"value":{"type":"string"},"proxied":{"type":["boolean","null"]}}}}}},"PartnerSiteMoveList":{"type":"object","required":["moves"],"properties":{"moves":{"type":"array","items":{"$ref":"#/components/schemas/PartnerSiteMove"}}}},"PartnerSiteMoveRetry":{"type":"object","properties":{"archive_url":{"type":"string","format":"uri","maxLength":2048},"archive_sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"}}},"PartnerSiteResources":{"type":"object","required":["site_id","plan_tier","limits_reason","tier","boost_level","limits","usage_24h","held","offers"],"additionalProperties":false,"properties":{"site_id":{"type":"string","format":"uuid"},"plan_tier":{"type":"string"},"limits_reason":{"type":"string","enum":["plan","box_floor","app_size","app_size_below_rung"],"description":"Which rule set this site's CPU and memory (`docs/866` §3): `plan` — the plan's rung; `box_floor` — the server it runs on has a higher minimum than the plan's rung; `app_size` — an application plan's process size is above the rung, so it is used; `app_size_below_rung` — that size is below the rung, and the rung is kept."},"tier":{"type":"string"},"boost_level":{"type":"integer"},"limits":{"type":"object","required":["cpu_percent","memory_mb","entry_processes"],"additionalProperties":false,"properties":{"cpu_percent":{"type":"integer","description":"100 = one core."},"memory_mb":{"type":"integer"},"entry_processes":{"type":"integer"}}},"usage_24h":{"oneOf":[{"type":"null"},{"type":"object","additionalProperties":{"type":"object","properties":{"peak":{"type":"number"},"latest":{"type":"number"}}}}]},"held":{"oneOf":[{"type":"null"},{"type":"object","required":["id","purchase_id","level","extra_code","renews_on","renews","ends_on"],"properties":{"id":{"type":"string","format":"uuid","description":"The boost's id — what `cancelPartnerBoost` takes. Canonical."},"purchase_id":{"type":"string","format":"uuid","description":"Always equal to `id`; kept because the dashboard's shape names it this way. Prefer `id`."},"level":{"type":"integer"},"extra_code":{"type":"string"},"renews_on":{"type":["string","null"],"format":"date","description":"The next renewal date; `null` when nothing renews (a $0 boost never bills, and a boost whose removal is scheduled stops renewing)."},"renews":{"type":"boolean","description":"`true` exactly when `renews_on` is set."},"ends_on":{"type":["string","null"],"format":"date","description":"The last day a paid boost works once its removal is scheduled. `null` while it renews, and for a $0 boost (a comp or test settlement), which has no end."}}}]},"offers":{"type":"array","items":{"type":"object","required":["code","level","tier","cpu_percent","memory_mb","entry_processes"],"additionalProperties":false,"properties":{"code":{"type":"string"},"level":{"type":"integer"},"tier":{"type":"string"},"cpu_percent":{"type":"integer"},"memory_mb":{"type":"integer"},"entry_processes":{"type":"integer"}}}}}},"PartnerSubscription":{"type":"object","required":["subscription_id","org_id","plan_code","status","auto_renew","current_period_end","ends_at","refunded"],"properties":{"subscription_id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"plan_code":{"type":"string"},"status":{"type":"string","enum":["trialing","active","past_due","canceled","expired"],"description":"Unchanged by a cancel — the subscription stays `active` until its period ends."},"auto_renew":{"type":"boolean","description":"Whether it charges again at `current_period_end`. `false` after a cancel."},"current_period_end":{"type":"string","format":"date-time"},"ends_at":{"type":["string","null"],"format":"date-time","description":"When service stops: `current_period_end` while renewal is off, `null` while it renews."},"refunded":{"type":"boolean","description":"Always `false`. This route never moves money."}}},"PartnerSubscriptionCancel":{"type":"object","properties":{"refund":{"type":"boolean","default":false,"description":"Must be `false` or absent. `true` is refused with `refund_not_offered` and nothing is changed — this route never moves money."}}},"PartnerWebhook":{"type":"object","required":["id","endpoint","events","status","verified_at","consecutive_failures","last_delivery_at","last_failure_at","last_delivery_error"],"properties":{"id":{"type":"string","format":"uuid"},"endpoint":{"type":"string","format":"uri"},"events":{"type":"array","description":"The event types this endpoint receives. An empty list means every type we publish, including ones added later.","items":{"type":"string"}},"status":{"type":"string","enum":["active","unverified","suspended"],"description":"`unverified` until your endpoint answers 2xx to our signed verification POST — until then it receives nothing else. `suspended` after 20 consecutive failures."},"verified_at":{"type":"string","format":"date-time","nullable":true},"consecutive_failures":{"type":"integer"},"last_delivery_at":{"type":"string","format":"date-time","nullable":true},"last_failure_at":{"type":"string","format":"date-time","nullable":true},"last_delivery_error":{"type":"string","description":"Why the last delivery failed, as your endpoint answered it — empty once a delivery succeeds. This is the field to read when `status` is `suspended`: the count tells you the endpoint is no longer receiving, and this tells you what to fix. Re-subscribing the same endpoint clears it and re-verifies."},"signing_secret":{"type":"string","description":"The HMAC key for `X-Zinn-Signature`. Returned ONCE, on creation, and never again — we keep only what is needed to sign. Lost it? Subscribe the same endpoint again and you get a new one; the old one stops working."}}},"PartnerWebhookCreate":{"type":"object","required":["endpoint"],"properties":{"endpoint":{"type":"string","format":"uri","maxLength":500,"description":"An `https://` URL we can reach from the public internet. Judged again when the socket opens, so an address that resolves to a private range is refused at delivery time as well as here."},"events":{"type":"array","description":"Omit or leave empty for every event type we publish.","items":{"type":"string"}}}},"PartnerWebhookList":{"type":"object","required":["items","available_events"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PartnerWebhook"}},"available_events":{"type":"array","description":"Every event type you may subscribe to.","items":{"type":"string"}}}},"PayPalMandateConfirmRequest":{"type":"object","required":["setup_token_id"],"properties":{"setup_token_id":{"type":"string","description":"The `setup_token_id` returned by `POST /v1/payment-methods/paypal`."},"org_id":{"type":"string","format":"uuid","description":"Organization to attach the mandate to. The caller must hold `billing.payment.manage` in **that** organization, and PayPal's own answer must name the same organization."}}},"PayPalMandateSetup":{"type":"object","description":"An opened PayPal vault setup. `approval_url` is single-use, short-lived, is for the buyer's browser only and is never persisted by Zinn®.","required":["setup_token_id","approval_url"],"properties":{"setup_token_id":{"type":"string","example":"5C991763VB2781234"},"approval_url":{"type":"string","nullable":true,"description":"Where to send the buyer to approve the mandate. `null` when PayPal returned no approval link, in which case the setup cannot be completed and the customer should try again."}}},"Payment":{"type":"object","description":"A payment summary. The gateway-side `provider_ref` is an engine secret and is never returned (CLAUDE.md §2.4).","required":["id","status","amount_minor","currency"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"status":{"type":"string","enum":["pending","requires_action","authorized","captured","failed","refunded","partially_refunded"]},"amount_minor":{"type":"integer","format":"int64"},"currency":{"$ref":"#/components/schemas/CurrencyCode"},"wallet_applied_minor":{"type":"integer","format":"int64","description":"Wallet credit applied before the gateway was charged."},"refunded_minor":{"type":"integer","format":"int64"},"failure_reason":{"type":"string"},"decline_class":{"description":"The class of this attempt's failure (PAYNOTICE, row 1108#29), decided from the gateway's machine codes when it failed. Empty when the attempt did not fail or was recorded before the class existed.","oneOf":[{"$ref":"#/components/schemas/PaymentDeclineClass"},{"type":"string","enum":[""]}]},"created_at":{"type":"string","format":"date-time"}}},"PaymentConfig":{"type":"object","description":"What a browser needs to render a payment step. Public by construction — a *publishable* key plus which gateways are on.","required":["providers","stripe_publishable_key","card_capture_available","paypal_client_id","paypal_available"],"properties":{"providers":{"type":"array","items":{"$ref":"#/components/schemas/PaymentConfigProvider"}},"stripe_publishable_key":{"type":"string","description":"Empty when Stripe is not configured. Served here rather than baked into the SPA bundle so the merchant account can be rotated from admin (§2.35).","example":"pk_test_51H…"},"card_capture_available":{"type":"boolean","description":"Whether the dashboard can show a card form. Computed here so \"can this customer add a payment method?\" has one answer rather than one per client."},"paypal_client_id":{"type":"string","description":"PayPal's client id, which goes in the JS SDK's script URL — the browser cannot render Buttons or hosted card fields without it. Public by construction (the catalogue marks it `secret: false`), and empty when PayPal is not configured.","example":"AY…"},"paypal_available":{"type":"boolean","description":"Whether PayPal can actually be offered. Its own flag rather than something the SPA infers from `providers`: a PayPal row can be enabled with the client id blank, and a client reasoning \"PayPal is listed, render the buttons\" would mount an SDK with no client id and show the customer a broken payment option."}}},"PaymentConfigProvider":{"type":"object","required":["code","mode"],"properties":{"code":{"$ref":"#/components/schemas/PaymentProviderCode"},"mode":{"$ref":"#/components/schemas/PaymentProviderMode"}}},"PaymentCoverage":{"type":"object","description":"What one payment covers on a subscription, computed from the live paid-through date (a payment always applies to wherever the period is now).","required":["subscription_id","covers_from","covers_to","periods","periods_owed_before","periods_owed_after","amount_owed_after","services_resume","owed_until","debt_paid"],"properties":{"debt_paid":{"description":"The recorded debt (GAP-9) this payment pays FIRST, net (before tax); amount 0 when it carries none.","allOf":[{"$ref":"#/components/schemas/MoneyAmount"}]},"subscription_id":{"$ref":"#/components/schemas/Uuid"},"covers_from":{"type":"string","format":"date-time"},"covers_to":{"type":"string","format":"date-time"},"periods":{"type":"integer","minimum":0},"periods_owed_before":{"type":"integer","minimum":0},"periods_owed_after":{"type":"integer","minimum":0},"amount_owed_after":{"description":"Net amount still owed after this payment (before tax).","allOf":[{"$ref":"#/components/schemas/MoneyAmount"}]},"services_resume":{"type":"boolean","description":"Whether the services come back once this payment lands."},"owed_until":{"type":"string","format":"date-time","description":"The date the subscription is paid through once everything owed is paid."}}},"PaymentDeclineClass":{"type":"string","description":"Why a payment did not go through, named for what the customer can do about it (`engine.commerce.payment_help.NoticeClass`). `processing`: our side or the gateway's, not the customer's card. `unknown`: not positively identified, so nothing is guessed.","enum":["bank_declined","insufficient_funds","limit","authentication","card_expired","card_details","card_unusable","crypto_expired","no_method","processing","unknown"]},"PaymentFailure":{"type":"object","description":"Why the latest payment attempt on an UNPAID order failed, so every surface that shows the order can say what happened and what to do (owner 2026-11-08, row 1108#29).","required":["decline_class","rail","failed_at"],"properties":{"decline_class":{"$ref":"#/components/schemas/PaymentDeclineClass"},"rail":{"type":"string","description":"The payment rail of the failed attempt (`stripe`, `paypal`, `nowpayments`, …)."},"failed_at":{"type":"string","format":"date-time"}}},"PaymentFormClosed":{"type":"object","description":"The customer closed the add-a-payment-method form.","required":["submitted"],"properties":{"org_id":{"type":"string","format":"uuid","description":"Organization the form was adding a method to. Defaults to the caller's own; the caller must hold `billing.payment.manage` there."},"submitted":{"type":"boolean","description":"Whether the customer pressed Save (or started a PayPal approval) at least once before closing the form."}}},"PaymentFormClosedRecorded":{"type":"object","required":["recorded","funnel_signalled"],"properties":{"recorded":{"type":"boolean","description":"Always true — the close was logged."},"funnel_signalled":{"type":"boolean","description":"Whether a card-required trial funnel was open for this organization and was told."}}},"PaymentFormFailure":{"type":"object","description":"What broke in the customer's browser on the add-a-payment-method form. `reason` is the SDK's own short message (for example `Failed to load Stripe.js`), never card data.","required":["gateway","stage"],"properties":{"org_id":{"type":"string","format":"uuid","description":"Organization the form was adding a method to. Defaults to the caller's own; the caller must hold `billing.payment.manage` there."},"gateway":{"type":"string","enum":["stripe","paypal"],"description":"Which payment form failed."},"stage":{"type":"string","enum":["load","mount","confirm"],"description":"`load` — the vendor's script did not load (blocked, offline, CSP); `mount` — the script loaded but the form did not render; `confirm` — saving broke for a reason that is not the customer's (a network or gateway error, never a decline or an incomplete field)."},"reason":{"type":"string","maxLength":300,"description":"The SDK's own message, trimmed. Optional."}}},"PaymentFormFailureRecorded":{"type":"object","required":["recorded","funnel_signalled"],"properties":{"recorded":{"type":"boolean","description":"Always true — the failure was logged and counted."},"funnel_signalled":{"type":"boolean","description":"Whether a card-required trial funnel was open for this organization and was told (it then reports the failure as `card_form` with this reason)."}}},"PaymentMethod":{"type":"object","description":"A stored mandate — the gateway-side consent Zinn® may charge off-session. Only display-safe fields are exposed; the gateway `customer_ref`/`method_token` are engine secrets and are never returned (CLAUDE.md §2.4).","required":["id","gateway","status","role","removal_blocked_by","method_type","can_auto_renew","brand","last4","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"gateway":{"type":"string","enum":["stripe","paypal"],"description":"The rail holding the mandate. Crypto (NOWPayments) is absent by design — it has no mandate primitive, so those customers are invoiced ahead rather than rebilled (ADR 0011 §6).","example":"stripe"},"status":{"type":"string","enum":["pending","active","expired","revoked"],"description":"Only `active` is chargeable; `pending` means the gateway has not confirmed it yet.","example":"active"},"role":{"type":"string","enum":["","primary","backup"],"description":"Which job this mandate does for the **organisation**. `primary` is charged first; `backup` is charged immediately if the primary declines; `\"\"` is simply stored.\n\n⛔ Replaced `is_default` on 2026-08-22 (owner ruling). That flag was unique per `(org, gateway)`, so an account could hold three simultaneous \"defaults\" — one per rail — and there was no expressible answer to *\"which card pays my invoice?\"*. Exactly one `primary` and at most one `backup` exist per organisation.","example":"primary"},"removal_blocked_by":{"type":"string","enum":["","subscription","adhoc_charge","reseller_programme"],"description":"Empty when this method may be removed. Otherwise the obligation that keeps the **floor** binding: this is the account's last operational way to pay and the named thing is still going to charge it, so `DELETE` will answer `409`.\n\n⭐ Computed by the engine, never inferred by a client. The rule needs the subscription table, the ad-hoc schedule, the reseller programme **and** the crypto election — a client guessing from list length would disable the button for a customer who has cancelled everything and is entitled to remove their card.","example":""},"method_type":{"type":"string","description":"The gateway's own name for what kind of mandate this is — Stripe's `PaymentMethod.type` (`card`, `sepa_debit`, `klarna`, `kakao_pay`, …). Empty on a rail that does not type its mandates (PayPal billing agreements).","example":"card"},"can_auto_renew":{"type":"boolean","description":"Whether this mandate can be charged **off-session**, i.e. whether a renewal can be taken without the customer present. `false` means the subscription renews **manually**: the customer is invoiced ahead, reminded on the dunning ladder, and the service is suspended if the invoice goes unpaid — exactly as for a crypto-only customer who holds no mandate at all (ADR 0011 §6).\n\n⛔ Read this rather than inferring it from `method_type`. The capability table is the engine's, it is deliberately conservative, and it is corrected by the gateway when a real charge is refused for reuse — a client-side copy of the list would drift from the rule the rebill sweep actually applies.","example":true},"brand":{"type":"string","example":"visa"},"last4":{"type":"string","maxLength":4,"example":"4242"},"exp_month":{"type":"integer","nullable":true,"minimum":1,"maximum":12,"example":12},"exp_year":{"type":"integer","nullable":true,"example":2030},"holder_name":{"type":"string","example":""},"confirmed_at":{"type":"string","format":"date-time","nullable":true,"description":"When the gateway confirmed the mandate. Null while `pending`."},"created_at":{"type":"string","format":"date-time"}}},"PaymentMethodPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethod"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"PaymentMethodSetup":{"type":"object","description":"An opened on-session setup. `client_secret` is short-lived, is for the browser SDK only, and is never persisted by Zinn®.","required":["setup_intent_id","client_secret"],"properties":{"setup_intent_id":{"type":"string","example":"seti_1234"},"client_secret":{"type":"string"}}},"PaymentMethodSetupRequest":{"type":"object","description":"Optional target organization; defaults to the caller's own.","properties":{"org_id":{"type":"string","format":"uuid","description":"Organization to attach the mandate to. The caller must hold `billing.payment.manage` in **that** organization."},"for_trial":{"type":"boolean","description":"Absent means false. The card-required free-trial step is asking. The SetupIntent then offers only the methods that can be charged off-session later (card, Link, SEPA Direct Debit, Revolut Pay, Amazon Pay … whichever of those the account can set up), because a method that cannot renew would save and still not start the trial. Without it every method the account offers is shown; those that cannot renew go to manual renewal. Ignored by `beginPayPalMandateSetup` (a PayPal mandate is always chargeable off-session)."}}},"PaymentMethodUpdate":{"type":"object","required":["role"],"properties":{"role":{"type":"string","enum":["","primary","backup"],"description":"Nominate this mandate as the account's `primary` or `backup`, or send `\"\"` to clear its role. Roles are **account-wide**: promoting a method demotes whichever method held that slot, and nominating the current primary as backup **swaps** the two atomically.","example":"primary"}}},"PaymentOptions":{"type":"object","required":["gateways"],"description":"The payment rails a purchase may be settled on, most-preferred first. Returned by both `getPaymentOptions` (before an order exists — the checkout picker) and `getOrderPaymentOptions` (an order already placed), which answer with one function so a screen can never offer a rail the charge path then refuses.","properties":{"gateways":{"type":"array","description":"Provider codes (`stripe`, `paypal`, `nowpayments`). Never empty — `stripe` is always present, because an unreadable provider registry must not be reported as \"nothing is enabled\".","items":{"type":"string","example":"paypal"}},"charge_currencies":{"type":"object","additionalProperties":{"type":"string","minLength":3,"maxLength":3},"description":"The ISO currency each offered rail CHARGES in, keyed by provider code. Equal to the purchase currency for a card rail; `USD` for a rail that cannot present it (PayPal outside its currencies) and always `USD` for crypto (owner ruling 2026-11-08). The price stays in the purchase currency; the screen shows the USD figure with the local amount as \"≈\".","example":{"stripe":"UZS","paypal":"USD","nowpayments":"USD"}},"usd_rate":{"type":["string","null"],"description":"Decimal string: one major unit of the purchase currency in USD, at today's stored rate. Present only when some rail charges USD for a non-USD purchase; `null` when none does or no rate is stored (the screen then names the currency without an amount, and the charge refuses before any money moves). The rate actually charged is recorded on the payment and stamped on the invoice.","example":"0.0000785"}}},"PaymentPreferences":{"type":"object","description":"How an account intends to pay — the crypto election, the nominated primary/backup, and the two questions a billing screen must not answer for itself.","required":["org_id","pays_by_crypto","primary_payment_method_id","backup_payment_method_id","auto_renew_possible","fallback_reachable"],"properties":{"org_id":{"type":"string","format":"uuid"},"pays_by_crypto":{"type":"boolean","description":"The account pays in crypto (NOWPayments). Satisfies the \"at least one operational payment method\" floor with no card on file, and moves the account to **invoice-ahead** renewal — crypto has no off-session primitive, so it can never be auto-charged.","example":false},"primary_payment_method_id":{"type":"string","format":"uuid","nullable":true,"description":"The mandate charged first, or `null` if none is nominated or usable."},"backup_payment_method_id":{"type":"string","format":"uuid","nullable":true,"description":"The mandate charged if the primary declines."},"auto_renew_possible":{"type":"boolean","description":"Whether this account can be charged unattended at all. `false` for a crypto-only account, and for one whose only mandates are rails Stripe will not let us reuse — both renew by invoice-ahead. ⛔ The engine's answer, not the client's guess: a rule duplicated in TypeScript drifts from the one the rebill sweep applies.","example":true},"fallback_reachable":{"type":"boolean","description":"Whether the nominated backup could actually catch the primary's decline. `false` when there is no backup, or when it sits on a **different gateway** — a charge resolves one gateway per organisation, so a PayPal backup cannot rescue a Stripe primary. Surfaced so the customer is told when they nominate it, not on the night it fails.","example":true}}},"PaymentPreferencesUpdate":{"type":"object","required":["pays_by_crypto"],"properties":{"pays_by_crypto":{"type":"boolean","description":"Elect (or stop) paying by crypto. ⛔ Turning it **off** is refused with `409` when crypto is currently the only way the account can be charged and something is still going to charge it — the floor is on the resulting state, not on one of the two actions that can breach it.","example":true}}},"PaymentProviderCode":{"type":"string","enum":["stripe","paypal","nowpayments"],"description":"A gateway the platform can be configured with (docs/36 §1)."},"PaymentProviderMode":{"type":"string","enum":["test","live"],"description":"Which credential set. Both are stored per provider; exactly one is enabled, and that is the one that charges money."},"PaymentStep":{"type":"object","description":"The order a one-click purchase was placed as, waiting for an on-session payment (Q225). Settle it with `payOrder` (a card, with `gateway`), `openPayPalOrder` + `capturePayPalOrder`, or the crypto invoice `payOrder` opens; read its total and tax from `getOrder`. Closing the step without paying may be reported with `reportOrderPaymentStepAbandoned`.","required":["order_id","order_ref","purchase_id","total_minor","currency"],"properties":{"order_id":{"type":"string","format":"uuid"},"order_ref":{"type":"string","description":"The order's human reference, for the customer to quote.","example":"ZD-ORD-0190F1A23B4C"},"purchase_id":{"type":["string","null"],"format":"uuid","description":"The waiting `ExtraPurchase`, or null when the step is for a cart or order with no add-on purchase behind it (cart checkout and order Pay with nothing stored that can settle it, 1108#13)."},"total_minor":{"type":"integer","description":"The order total in minor units, tax included."},"currency":{"type":"string","example":"USD"}}},"PbnBoostChoose":{"type":"object","required":["level"],"additionalProperties":false,"properties":{"level":{"type":"integer","minimum":1,"maximum":3},"org_id":{"type":"string","format":"uuid"},"currency":{"type":"string","maxLength":3},"gateway":{"type":"string","description":"The payment rail the customer picked."}}},"PbnBoostHeld":{"type":"object","required":["purchase_id","level","extra_code","renews","renews_on","ends_on","amount_minor","currency","comp"],"additionalProperties":false,"properties":{"purchase_id":{"type":"string","format":"uuid"},"level":{"type":"integer","minimum":1,"maximum":3},"extra_code":{"type":"string"},"renews":{"type":"boolean"},"renews_on":{"type":["string","null"],"format":"date"},"ends_on":{"type":["string","null"],"format":"date","description":"The last day a boost whose removal is scheduled works."},"amount_minor":{"type":"integer","description":"What the current month was billed","in minor units of `currency`.":null},"currency":{"type":"string"},"comp":{"type":"boolean","description":"True for a staff organization","which is not charged.":null}}},"PbnBoostOffer":{"type":"object","required":["level","extra_code","multiplier_pct","cpu_percent","memory_mb","per_site_minor","minimum_minor","price_minor","currency","sites"],"additionalProperties":false,"properties":{"level":{"type":"integer","minimum":1,"maximum":3},"extra_code":{"type":"string"},"multiplier_pct":{"type":"integer","description":"CPU and memory as a percentage of the plan's (150 = 1.5x)."},"cpu_percent":{"type":"integer","description":"Each PBN site's CPU limit at this level (100 = one core)."},"memory_mb":{"type":"integer"},"per_site_minor":{"type":"integer"},"minimum_minor":{"type":"integer"},"price_minor":{"type":"integer","description":"The monthly price for `sites` sites — max(minimum","per site x sites).":null},"currency":{"type":"string"},"sites":{"type":"integer","minimum":0}}},"PbnBoostPurchase":{"type":"object","required":["purchase_id","level","extra_code","status","amount_minor","currency"],"additionalProperties":false,"properties":{"purchase_id":{"type":"string","format":"uuid"},"level":{"type":"integer"},"extra_code":{"type":"string"},"status":{"type":"string"},"amount_minor":{"type":"integer"},"currency":{"type":"string"}}},"PbnBoostSites":{"type":"object","required":["boosted","waiting_for_room","not_on_our_servers"],"additionalProperties":false,"properties":{"boosted":{"type":"integer","minimum":0,"description":"Active PBN sites whose server has room — they run at the boosted limits."},"waiting_for_room":{"type":"integer","minimum":0,"description":"Active PBN sites whose server is busy or unmeasured; they keep plan limits until it has room","and are counted in the price.":null},"not_on_our_servers":{"type":"integer","minimum":0,"description":"Sites on a server we do not run","which the boost cannot reach.":null}}},"PbnBoostState":{"type":"object","required":["level","held_level","suspended","held","eligible","site_count","sites","offers"],"additionalProperties":false,"properties":{"level":{"type":"integer","minimum":0,"maximum":3,"description":"The level the sites run at now; 0 when none","or while the account is not in good standing.":null},"held_level":{"type":"integer","minimum":0,"maximum":3},"suspended":{"type":"boolean","description":"A boost is held but not applied because the account is not in good standing."},"held":{"oneOf":[{"$ref":"#/components/schemas/PbnBoostHeld"},{"type":"null"}]},"eligible":{"type":"boolean","description":"The account has Footprint-Free sites or a plan."},"site_count":{"type":"integer","minimum":0,"description":"PBN sites the price is counted on."},"sites":{"$ref":"#/components/schemas/PbnBoostSites"},"offers":{"type":"array","items":{"$ref":"#/components/schemas/PbnBoostOffer"}}}},"PbsKit":{"type":"object","description":"A `pbs-kit/1` document (docs/plugins-overhaul/pbs-cloud-library.md §3).","required":["format","slug","name","tier","pages"],"additionalProperties":true,"properties":{"format":{"type":"string","enum":["pbs-kit/1"]},"slug":{"type":"string"},"name":{"type":"string"},"locale":{"type":"string"},"tier":{"type":"string","enum":["free","pro"]},"pages":{"type":"array","items":{"type":"object","required":["slug","title","content"],"additionalProperties":true,"properties":{"slug":{"type":"string"},"title":{"type":"string"},"front":{"type":"boolean"},"content":{"type":"string","description":"Block markup."}}}}}},"PbsKitCatalogue":{"type":"object","required":["kits","pro_unlocked","locale"],"properties":{"pro_unlocked":{"type":"boolean"},"locale":{"type":"string","description":"The platform locale the catalogue is in."},"kits":{"type":"array","items":{"$ref":"#/components/schemas/PbsKitSummary"}}}},"PbsKitSummary":{"type":"object","required":["slug","name","niche","category","tier","pages","locked"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"niche":{"type":"string"},"category":{"type":"string"},"tier":{"type":"string","enum":["free","pro"]},"description":{"type":"string"},"palette":{"type":"object","additionalProperties":{"type":"string"}},"fonts":{"type":"object","additionalProperties":{"type":"string"}},"preview":{"type":"object","additionalProperties":true},"version":{"type":"integer"},"locked":{"type":"boolean","description":"A Pro kit this caller cannot import."},"pages":{"type":"array","items":{"type":"object","required":["slug","title","front"],"properties":{"slug":{"type":"string"},"title":{"type":"string"},"front":{"type":"boolean"}}}}}},"PbsLibraryAccount":{"type":"object","required":["plan","can_save","quota_bytes","used_bytes","item_count","max_items","max_item_bytes","max_image_bytes","max_image_edge","image_types","teams_allowed"],"properties":{"plan":{"type":"string","enum":["personal","business","agency"]},"licence_state":{"type":"string","enum":["active","lapsed"]},"can_save":{"type":"boolean"},"quota_bytes":{"type":"integer"},"used_bytes":{"type":"integer"},"item_count":{"type":"integer"},"max_items":{"type":"integer"},"max_item_bytes":{"type":"integer"},"max_image_bytes":{"type":"integer"},"max_image_edge":{"type":"integer"},"image_types":{"type":"array","items":{"type":"string"}},"teams_allowed":{"type":"boolean"},"session":{"type":"object","properties":{"kind":{"type":"string","enum":["licence","team"]},"can_write":{"type":"boolean"},"team_id":{"type":"string","format":"uuid","nullable":true},"team_name":{"type":"string","nullable":true}}}}},"PbsLibraryImage":{"type":"object","required":["sha256","content_type","size_bytes","width","height","created"],"properties":{"sha256":{"type":"string"},"content_type":{"type":"string"},"size_bytes":{"type":"integer"},"width":{"type":"integer"},"height":{"type":"integer"},"created":{"type":"boolean"}}},"PbsLibraryItem":{"type":"object","required":["id","kind","title","tags","team_id","content_bytes","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["section","page","style"]},"title":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"team_id":{"type":"string","format":"uuid","nullable":true},"content_bytes":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"PbsLibraryItemCreated":{"allOf":[{"$ref":"#/components/schemas/PbsLibraryItem"},{"type":"object","required":["account"],"properties":{"account":{"$ref":"#/components/schemas/PbsLibraryAccount"}}}]},"PbsLibraryItemDetail":{"allOf":[{"$ref":"#/components/schemas/PbsLibraryItem"},{"type":"object","required":["content","images"],"properties":{"content":{"description":"The saved design."},"images":{"type":"array","items":{"type":"string"}}}}]},"PbsLibraryItemInput":{"type":"object","properties":{"kind":{"type":"string","enum":["section","page","style"]},"title":{"type":"string","maxLength":200},"tags":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":40}},"content":{"description":"The design (block markup + styles)","at most 2 MB as JSON.":null},"images":{"type":"array","maxItems":60,"items":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}},"team_id":{"type":"string","format":"uuid","nullable":true}}},"PbsLibrarySession":{"type":"object","required":["token","expires_at","account"],"properties":{"token":{"type":"string","description":"`zpl_…`, shown once."},"expires_at":{"type":"string","format":"date-time"},"account":{"$ref":"#/components/schemas/PbsLibraryAccount"}}},"PbsLibrarySessionInput":{"type":"object","required":["product","install_id","license_id","site_url","timestamp","nonce","signature"],"properties":{"product":{"type":"string","enum":["page-builder-sandwich"]},"install_id":{"type":"string","pattern":"^[0-9]{1,20}$"},"license_id":{"type":"string","pattern":"^[0-9]{1,20}$"},"site_url":{"type":"string","format":"uri","maxLength":500},"timestamp":{"type":"integer","description":"Unix seconds; within 300 s of the server clock."},"nonce":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,64}$"},"signature":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}},"PbsLibraryTeam":{"type":"object","required":["id","name","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"PbsLibraryTeamMember":{"type":"object","required":["id","site_url","label","role","joined_at"],"properties":{"id":{"type":"string","format":"uuid"},"site_url":{"type":"string"},"label":{"type":"string"},"role":{"type":"string","enum":["read","write"]},"joined_at":{"type":"string","format":"date-time"},"last_used_at":{"type":"string","format":"date-time","nullable":true}}},"PermissionCheck":{"type":"object","required":["key","state","detail","reason","http_status"],"properties":{"key":{"type":"string","description":"The machine identifier for the permission. The client owns the human-readable label and the vendor's own name for the grant (i18n — CLAUDE.md §2.7)."},"state":{"$ref":"#/components/schemas/PermissionState"},"detail":{"type":"string","description":"What happened, in English, for an **operator** — a log line, the admin view, a support ticket. Composed from the HTTP status alone and never from the vendor's exception text, which can carry the request URL and its authorization header.\n\n⛔ Not for a customer's screen. It is built in the driver layer, where there is no i18n layer to build it through, so a client that renders it is shipping English prose to every locale. Render `reason` instead."},"reason":{"type":"string","description":"The machine reason, for the client to translate. One of `credential_rejected`, `permission_denied`, `request_refused`, `not_found`, `rate_limited`, `unreachable`, `no_zone`, `zone_not_on_account`, `zone_vanished`, `proved`, `proved_with_leftover`, `declared_not_exercised`, `not_declared`, `cannot_enumerate`. Empty means no specific reason — render nothing."},"http_status":{"type":["integer","null"],"description":"The status the check saw, when there was one. `null` means the vendor was never reached — which is not a verdict on the permission."}}},"PermissionReport":{"type":"object","required":["credential_valid","usable","checks","missing","unverified","account_ref","detail","checked_at"],"properties":{"credential_valid":{"type":"boolean","description":"A statement about the **credential**, not about the permissions. `false` means the provider rejected it outright, in which case the rows are not meaningful and the screen must say \"this credential is dead\" — never \"these permissions are missing\", which sends the customer to tick boxes that are already ticked."},"usable":{"type":"boolean","description":"Whether we may store and use this credential: alive, with no **proved** absence of anything required. ⛔ Deliberately not \"every row passed\" — a brand-new account with no zone on it yet has unknowable zone-scoped rows, and blocking on those would make the very first connection impossible."},"checks":{"type":"array","items":{"$ref":"#/components/schemas/PermissionCheck"},"description":"One row per permission, in a stable catalogue order rather than the order the checks happened to finish in — a checklist whose rows reshuffle between two retests looks broken to the person reading it."},"missing":{"type":"array","items":{"type":"string"},"description":"Required permissions the provider **proved** are absent. Not the unknowns."},"unverified":{"type":"array","items":{"type":"string"},"description":"Permissions we could not determine either way. The honest amber set."},"target":{"type":"string","description":"The connection target this report was judged for (`\"\"` = the provider default, `pages` = Cloudflare Pages only). A retest re-judges for the same target."},"required":{"type":"array","items":{"type":"string"},"description":"The permission keys this target requires, in catalogue order. Every other row is optional for this connection."},"account_ref":{"type":"string","description":"The account or zone the provider reported — discovered, never assumed."},"detail":{"type":"string","description":"An overall explanation, used mainly for a rejected credential."},"checked_at":{"type":["string","null"],"format":"date-time","description":"When this was taken. ⛔ Never render the report without it: a checklist with no date on it is indistinguishable from a live one and will be read as live, when in fact the customer can revoke a permission at their vendor a second after it was written and nothing here would know."}}},"PermissionState":{"type":"string","enum":["pass","fail","unknown"],"description":"The verdict for one permission. Three values, and the third is load-bearing: `unknown` is what an honest check returns when it could not reach the question — no zone on the account yet, the vendor down or rate-limiting, or a well-formed request refused on its content. ⛔ Collapsing it into either neighbour is a defect: into `pass` it becomes a green tick that lies, and into `fail` it shows a red panel for a credential that is completely fine."},"PhpVersionCatalogEntry":{"type":"object","description":"One PHP version offered to new sites (public catalog).","required":["version","status","is_default","product_lines"],"properties":{"version":{"type":"string","description":"The minor-version family.","example":"8.3"},"status":{"$ref":"#/components/schemas/PhpVersionStatus"},"is_default":{"type":"boolean","description":"Whether this is the default version for new sites — of the queried product line when `product_line` was given, else true if it is a default on any line."},"product_lines":{"type":"array","description":"The product-line codes this version is offered on.","items":{"type":"string"}}}},"PhpVersionCatalogList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PhpVersionCatalogEntry"}}}},"PhpVersionStatus":{"type":"string","description":"A PHP version's support tier — `active` (current, recommended), `hardened_legacy` (past upstream EOL but security-patched via CloudLinux alt-php), or `eol` (kept only because a grandfathered site still references it).","enum":["active","hardened_legacy","eol"]},"PlanMove":{"type":"object","required":["plan_code","name","direction","blocked_by"],"properties":{"plan_code":{"type":"string","example":"pbn_25"},"name":{"type":"string","example":"PBN 25"},"product_line":{"type":"string","description":"The product line this plan belongs to. Usually the line asked for; a customer on a RETIRED line (`wordpress`, `fleet_enterprise`, replaced by the one WordPress line on 2026-10-06) is offered the successor line's plans as moves of the same subscription, and this says which line each one is on.","example":"mainstream"},"direction":{"type":"string","description":"Where this tier sits relative to the one they hold. `current` is the plan they are on, reported rather than omitted — a ladder missing the rung you are standing on reads as though you are on none of them.","enum":["upgrade","downgrade","current"],"example":"upgrade"},"price":{"nullable":true,"description":"The tier's **list price** per interval — context, never the amount a move costs. What the customer actually pays for the move is `quote`.","allOf":[{"$ref":"#/components/schemas/PlanMovePrice"}]},"quote":{"nullable":true,"description":"What this move costs **now**, prorated against the period already paid for and taxed on the net difference — the same computation the site Plan card uses, taken from the same module so the two screens cannot disagree. Null when the subscription entitles no site to use as a handle (bought and never deployed); the client then shows `price` and sends the customer to checkout, which is the correct door for that case only.","allOf":[{"$ref":"#/components/schemas/PlanMoveQuote"}]},"blocked_by":{"type":"array","description":"Limits the account is already over for this plan. Empty means the move is offerable. Populated only on a `downgrade`; limits that could not be measured are never listed here.","items":{"type":"object","required":["key","used","limit"],"properties":{"key":{"type":"string","description":"The entitlement key, for the client to localise.","example":"max_sites"},"label":{"type":"string","example":"max_sites"},"unit":{"type":"string","example":"sites"},"used":{"type":"integer","example":7},"limit":{"type":"integer","example":5},"scope":{"type":"string","description":"The thing the numbers are about when the limit is per-domain rather than per-account. Empty for an account-wide limit.","example":""}}}}}},"PlanMoveCurrent":{"type":"object","required":["plan_code","name","subscription_id"],"properties":{"plan_code":{"type":"string","example":"pbn_5"},"name":{"type":"string","example":"PBN 5"},"product_line":{"type":"string","description":"The product line the held plan belongs to. Usually the line asked for; a customer on a RETIRED line (`wordpress`, `fleet_enterprise`, replaced by the one WordPress line on 2026-10-06) is offered the successor line's plans as moves of the same subscription, and this says which line each one is on.","example":"mainstream"},"subscription_id":{"$ref":"#/components/schemas/Uuid"},"price":{"nullable":true,"description":"What they pay today, in their own currency and term. Null when the catalogue holds no price for that pair — reported rather than hidden, because a missing price is why a move cannot be quoted.","allOf":[{"$ref":"#/components/schemas/PlanMovePrice"}]}}},"PlanMovePrice":{"type":"object","required":["amount_minor","currency"],"properties":{"amount_minor":{"type":"integer","description":"Integer minor units — never a float (CLAUDE.md §2.8).","example":2999},"currency":{"type":"string","description":"ISO 4217, the organization's own billing currency.","example":"EUR"}}},"PlanMoveQuote":{"type":"object","description":"A prorated plan-change quote, in integer minor units of `currency`. Exactly one of `total_minor` and `credit_minor` is non-zero, or neither is: a move that costs money charges `total_minor` now, and a move that returns money credits `credit_minor` to the account.","required":["total_minor","credit_minor","currency"],"properties":{"total_minor":{"type":"integer","description":"Charged now — the net difference plus its tax. Never negative.","example":812},"credit_minor":{"type":"integer","description":"Returned as account credit. Never negative.","example":0},"tax_minor":{"type":"integer","description":"The tax inside `total_minor`, computed on the net difference.","example":135},"currency":{"type":"string","minLength":3,"maxLength":3,"example":"USD"}}},"PlanMoves":{"type":"object","description":"The plan an organization holds on one product line, and every tier it can move to.","required":["current","moves"],"properties":{"current":{"nullable":true,"description":"The plan they are on. Null when they hold none on this line, in which case `moves` is empty — there is nothing to move from.","allOf":[{"$ref":"#/components/schemas/PlanMoveCurrent"}]},"moves":{"type":"array","items":{"$ref":"#/components/schemas/PlanMove"}},"handle_site_id":{"type":"string","description":"The site to POST a plan change to. A **handle, not a scope** — `change_plan` applies the new entitlements to every site the subscription entitles, so which one is used changes only whose page shows the new allowance first. Empty when the subscription entitles no site.","example":"01920000-0000-7000-8000-000000000000"}}},"PlatformTransfer":{"type":"object","required":["id","source_platform","target_platform","source_url","tier_code","status","price_amount_minor","price_currency","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"source_platform":{"type":"string"},"source_platform_name":{"type":"string"},"target_platform":{"type":"string"},"target_platform_name":{"type":"string"},"source_url":{"type":"string"},"target_site_id":{"type":["string","null"],"format":"uuid"},"tier_code":{"type":"string"},"tier_name":{"type":"string"},"entity_count_estimate":{"type":"integer"},"status":{"$ref":"#/components/schemas/PlatformTransferStatus"},"status_label":{"type":"string"},"price_amount_minor":{"type":"integer","format":"int64"},"price_currency":{"type":"string","minLength":3,"maxLength":3},"redirects_mapped":{"type":"boolean"},"redirect_count":{"type":"integer"},"canonicals_verified":{"type":"boolean"},"sitemap_submitted":{"type":"boolean"},"structured_data_preserved":{"type":"boolean"},"seo_checks_complete":{"type":"boolean"},"customer_note":{"type":"string"},"sla_due_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"products":{"type":"integer"},"customers":{"type":"integer"},"orders":{"type":"integer"},"blog_posts":{"type":"integer"},"cms_pages":{"type":"integer"},"addons":{"type":"array","items":{"$ref":"#/components/schemas/TransferAddonCode"}},"aftercare":{"type":"string"},"aftercare_reruns":{"type":"integer"},"aftercare_days":{"type":"integer"},"seo_promised":{"type":"boolean","description":"The SEO add-on was bought, so the SEO checks gate completion."},"target_mode":{"type":"string","enum":["existing","zinn_hosting"]},"target_url":{"type":"string"},"source_access_method":{"type":"string"},"target_access_method":{"type":"string"},"source_login_hint":{"type":"string","description":"Masked; never the login itself."},"target_login_hint":{"type":"string","description":"Masked; never the login itself."},"has_source_credentials":{"type":"boolean"},"has_target_credentials":{"type":"boolean"},"credentials_deleted_at":{"type":["string","null"],"format":"date-time"},"contact_name":{"type":"string"},"contact_email":{"type":"string"},"contact_phone":{"type":"string"},"preferred_start_date":{"type":["string","null"],"format":"date"},"preferred_window":{"type":"string"},"intake_checks":{"type":"object","description":"Reachability of each store address, keyed `source` / `target`.","additionalProperties":{"type":"object","properties":{"ok":{"type":"boolean"},"status":{"type":["integer","null"]},"checked_at":{"type":"string","format":"date-time"},"detail":{"type":"string"}}}},"intake_missing":{"type":"array","description":"What we still need before a specialist can start, as field codes (`source_url`, `source_access`, `source_credentials`, `target_url`, `target_access`, `target_credentials`, `contact_email`). Empty when complete.","items":{"type":"string"}},"intake_completed_at":{"type":["string","null"],"format":"date-time"},"preview_url":{"type":"string","description":"The free preview to check","once ready.":null},"events":{"type":"array","description":"The customer-visible trail only. Staff notes name vendors and what a job cost us, and never appear here.","items":{"$ref":"#/components/schemas/PlatformTransferEvent"}}}},"PlatformTransferCreate":{"allOf":[{"$ref":"#/components/schemas/TransferQuoteRequest"},{"type":"object","required":["source_url","contact_email"],"properties":{"source_url":{"type":"string","maxLength":512},"target_mode":{"type":"string","enum":["existing","zinn_hosting"],"default":"existing","description":"The new store already exists, or we build it on our hosting."},"target_url":{"type":"string","maxLength":512},"contact_name":{"type":"string","maxLength":200},"contact_email":{"type":"string","format":"email","maxLength":254},"contact_phone":{"type":"string","maxLength":40},"preferred_start_date":{"type":["string","null"],"format":"date"},"preferred_window":{"type":"string","maxLength":200},"customer_note":{"type":"string","maxLength":4000},"org_id":{"type":["string","null"],"format":"uuid"},"target_site_id":{"type":["string","null"],"format":"uuid","description":"Where it lands. May be omitted — a customer often buys the transfer before the destination site exists, which is the point of an on-ramp."}}}]},"PlatformTransferEvent":{"type":"object","required":["id","at","to_status"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"at":{"type":"string","format":"date-time"},"actor":{"type":"string"},"from_status":{"type":"string"},"to_status":{"type":"string"},"note":{"type":"string"}}},"PlatformTransferIntake":{"type":"object","properties":{"source_url":{"type":"string","maxLength":512},"source_access_method":{"$ref":"#/components/schemas/TransferAccessMethod"},"source_credentials":{"$ref":"#/components/schemas/PlatformTransferStoreCredentials"},"target_mode":{"type":"string","enum":["existing","zinn_hosting"]},"target_url":{"type":"string","maxLength":512},"target_access_method":{"$ref":"#/components/schemas/TransferAccessMethod"},"target_credentials":{"$ref":"#/components/schemas/PlatformTransferStoreCredentials"},"contact_name":{"type":"string","maxLength":200},"contact_email":{"type":"string","format":"email","maxLength":254},"contact_phone":{"type":"string","maxLength":40},"preferred_start_date":{"type":["string","null"],"format":"date"},"preferred_window":{"type":"string","maxLength":200},"customer_note":{"type":"string","maxLength":4000}}},"PlatformTransferList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PlatformTransfer"}},"next_cursor":{"type":["string","null"]},"has_more":{"type":"boolean"}}},"PlatformTransferPay":{"type":"object","properties":{"currency":{"type":["string","null"],"minLength":3,"maxLength":3,"description":"The currency the customer was quoted in. Refused if no gateway can charge it — silently substituting the base currency would bill a different number from the one on the screen."}}},"PlatformTransferStatus":{"type":"string","enum":["draft","payment_failed","queued","awaiting_customer","preview","in_progress","seo_qa","completed","cancelled"]},"PlatformTransferStoreCredentials":{"type":"object","description":"Write-only. Stored in the secrets vault; never returned by any customer endpoint.","properties":{"login":{"type":"string","maxLength":254},"password":{"type":"string","maxLength":512,"writeOnly":true},"api_token":{"type":"string","maxLength":2048,"writeOnly":true},"notes":{"type":"string","maxLength":2000}}},"PluginAiCompleteInput":{"type":"object","required":["requests"],"properties":{"requests":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","required":["messages"],"properties":{"id":{"type":"string","maxLength":64,"description":"Echoed back on the result."},"messages":{"type":"array","minItems":1,"maxItems":40,"items":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string","maxLength":60000}}}},"system":{"type":"string","maxLength":8000},"schema":{"type":["object","null"],"additionalProperties":true,"description":"A JSON Schema with `type` object; the answer comes back as `data`."},"schema_name":{"type":"string","pattern":"^[a-zA-Z0-9_-]{1,64}$","default":"answer"},"max_tokens":{"type":"integer","minimum":1,"maximum":4096,"default":1024},"temperature":{"type":"string","format":"decimal","default":"0.20","description":"0 to 1."}}}},"purpose":{"type":"string","maxLength":64,"description":"What the plugin used it for (usage log only)."}}},"PluginAiCompleteResult":{"type":"object","required":["funding","charged_micros","balance_micros","currency","results"],"properties":{"funding":{"type":"string","enum":["credits","byo"],"description":"`byo`: the org's own key saved in Zinn® paid, and nothing was charged."},"charged_micros":{"type":"integer","description":"Total Zinn® credits debited by this call","USD micros.":null},"balance_micros":{"type":"integer","description":"The org's balance after this call."},"currency":{"type":"string","enum":["USD"]},"results":{"type":"array","items":{"type":"object","required":["id","ok"],"properties":{"id":{"type":"string"},"ok":{"type":"boolean"},"text":{"type":"string"},"data":{"description":"The structured answer when a `schema` was sent."},"model":{"type":"string"},"input_tokens":{"type":"integer"},"output_tokens":{"type":"integer"},"charged_micros":{"type":"integer"},"failure":{"$ref":"#/components/schemas/VendorFailure"}}}}}},"PluginClick":{"type":"object","description":"docs/1002 §4 — what the plugin sites' click beacon sends.","required":["href"],"properties":{"href":{"type":"string","maxLength":2048,"description":"The link clicked — a `checkout.freemius.com` checkout, a wordpress.org plugin page or a GitHub zip."},"site":{"type":"string","maxLength":120,"description":"Fallback when the request has no `Origin`."},"touch":{"type":"object","description":"What the site kept from the visitor's landing: `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`, `gclid`, `gbraid`, `wbraid`, `referrer_host`, `landing_page` (host + path). Unknown keys are dropped.","additionalProperties":{"type":"string","maxLength":300}},"ga_client_id":{"type":"string","pattern":"^[0-9]{1,12}[.][0-9]{1,12}$"},"ga_session_id":{"type":"string","pattern":"^[0-9]{1,16}$"},"handoff":{"type":"boolean","description":"VOAIHOUSEWP2 — `true` when the link opens one of our plugins' own download pages (`tranzly.io/download/`, `pagebuildersandwich.com/download/`) from another of our sites: the click is stored as a hand-off (kind `handoff`), not a download, because that page's own button is the download. Ignored on any other link."}}},"PluginGuardHit":{"type":"object","description":"One plugin-guard finding or refusal (L06 s1014, docs/1027). Staff reads add the staff-only fields.","required":["id","kind","verdict","state","path","plugin","door","first_seen_at","last_seen_at"],"properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["blocklist","phishing"]},"verdict":{"type":"string","enum":["blocked","kit","suspect"]},"state":{"type":"string","enum":["reported","quarantined","refused","restored","gone","dismissed"]},"path":{"type":"string","description":"Path relative to the site's public folder","or the refused plugin or file name.":null},"plugin":{"type":"string","description":"A blocked plugin's folder name (empty for a phishing finding)."},"door":{"type":"string","description":"For a refusal: install, upload, theme-upload or rollout."},"first_seen_at":{"type":"string","format":"date-time"},"last_seen_at":{"type":"string","format":"date-time"},"quarantined_at":{"type":"string","format":"date-time","nullable":true},"review_requested_at":{"type":"string","format":"date-time","nullable":true},"resolved_at":{"type":"string","format":"date-time","nullable":true},"site_id":{"type":"string","format":"uuid","description":"Staff only."},"org_id":{"type":"string","format":"uuid","description":"Staff only."},"domain":{"type":"string","description":"Staff list only."},"worker":{"type":"string","description":"Staff only."},"entries":{"type":"array","description":"Staff only - the blocklist entries that matched.","items":{"type":"object","properties":{"id":{"type":"string","nullable":true},"type":{"type":"string"},"value":{"type":"string"}}}},"evidence":{"type":"string","description":"Staff only - marker names or the matching rule","never file bytes.":null},"version":{"type":"string","description":"Staff only."},"quarantined_to":{"type":"string","description":"Staff only."},"notified_at":{"type":"string","format":"date-time","nullable":true,"description":"Staff only."},"actor":{"type":"string","description":"Staff only."}}},"PluginHostingCodeAnswer":{"type":"object","required":["offer"],"properties":{"offer":{"oneOf":[{"$ref":"#/components/schemas/HostingCodeOffer"},{"type":"null"}]}}},"PluginHostingCodeRequest":{"type":"object","required":["email","licence_id"],"properties":{"email":{"type":"string","format":"email","maxLength":320},"licence_id":{"type":"integer","minimum":1,"description":"The store licence id."}}},"PluginRelease":{"type":"object","description":"One published version of one thing Zinn® publishes — a WordPress plugin, or one of the billing-panel provisioning modules. The archive itself is at `downloadPlugin`; this row carries what you need to check it.","required":["kind","slug","name","version","package_sha256","package_bytes"],"properties":{"kind":{"type":"string","enum":["wordpress_plugin","whmcs_module","hostbill_module","generic_client"],"description":"What this is, and therefore where it is installed. `wordpress_plugin` goes in `wp-content/plugins`; `whmcs_module` in a WHMCS install's `modules/servers/`; `hostbill_module` in `includes/modules/Hosting/`; `generic_client` is a single PHP file you drop into your own billing system.\n\n⛔ The `requires_wp` and `tested_wp` fields are empty on everything that is not a `wordpress_plugin` — they are WordPress header fields and mean nothing to a billing panel. `requires_php` is meaningful for all four."},"slug":{"type":"string","description":"The archive's directory name, e.g. `zinn-cache` or `zinn-whmcs`."},"name":{"type":"string"},"version":{"type":"string"},"package_sha256":{"type":"string","minLength":64,"maxLength":64,"description":"Lowercase hex SHA-256 of the archive. The value `downloadPlugin` returns in `X-Zinn-Package-SHA256`, and the one the plugin's own updater checks a download against before WordPress installs it."},"package_bytes":{"type":"integer"},"requires_wp":{"type":"string"},"requires_php":{"type":"string"},"tested_wp":{"type":"string","description":"The WordPress version this release was installed and activated against before it was published — a real test on a real install, not an estimate. Empty means we have not stated one; it does not mean \"any version\"."},"changelog":{"type":"string"},"homepage":{"type":"string"},"distribution":{"type":"string","enum":["public","app-only","licensed"],"description":"Who may download this plugin. `public` — anyone, no account needed, and it is also listed on https://zinndigital.com/wordpress-plugins. `app-only` — signed-in customers only; it is absent from this catalogue entirely for an anonymous caller, and `downloadPlugin` answers 404 rather than 403 so the endpoint is not an oracle for what we publish privately. Sites we host receive updates for both."},"published_at":{"type":"string","format":"date-time"}}},"PluginReleaseList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PluginRelease"}}}},"PluginSiteConnectInput":{"type":"object","required":["email","product","site_url","consent"],"properties":{"email":{"type":"string","format":"email","maxLength":320},"name":{"type":"string","maxLength":200},"product":{"type":"string","pattern":"^[a-z0-9-]{2,40}$","example":"tranzly"},"site_url":{"type":"string","format":"uri","maxLength":500},"site_name":{"type":"string","maxLength":200},"plugin_version":{"type":"string","maxLength":40},"wp_version":{"type":"string","maxLength":40},"php_version":{"type":"string","maxLength":40},"locale":{"type":"string","maxLength":16,"description":"The WordPress locale (`fr_FR`); mail to the contact is rendered in it."},"consent":{"type":"boolean","description":"Must be literally `true` — the site owner agreed on the consent screen (WordPress.org Guideline 7). Anything else is `422`."},"website":{"type":"string","description":"Honeypot. Must be empty."}}},"PluginSiteConnected":{"type":"object","required":["connection_id","token","scopes","contact"],"properties":{"connection_id":{"type":"string","format":"uuid"},"token":{"type":"string","description":"`zps_` + 43 URL-safe characters. Returned ONCE; the engine keeps only its SHA-256. The plugin stores it sealed (libsodium secretbox, ADR 0034's key scheme).","example":"zps_Xk3v…"},"scopes":{"type":"array","items":{"type":"string","enum":["support.tickets","support.diagnostics"]}},"contact":{"type":"object","required":["email","is_new"],"properties":{"email":{"type":"string","format":"email"},"is_new":{"type":"boolean"}}}}},"PluginSiteConnection":{"type":"object","required":["connection_id","product","site_url","status","scopes","created_at","last_used_at"],"properties":{"connection_id":{"type":"string","format":"uuid"},"product":{"type":"string"},"site_url":{"type":"string"},"status":{"type":"string","enum":["active","revoked"],"description":"Always `active` on `getPluginSiteConnection` — a revoked token is a `401`."},"scopes":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"last_used_at":{"type":["string","null"],"format":"date-time"}}},"PluginSupportCredentialInput":{"type":"object","required":["kind","secret"],"properties":{"kind":{"type":"string","enum":["temporary_access","wp_admin","file_manager","cpanel","ftp","other"]},"url":{"type":"string","maxLength":500},"username":{"type":"string","maxLength":200},"secret":{"type":"string","maxLength":2000,"description":"Written to Vault, never to the database; never logged, never returned by a list or read; purged 30 days after the ticket closes."},"notes":{"type":"string","maxLength":1000},"expires_at":{"type":["string","null"],"format":"date-time"}}},"PluginSupportDiagnostics":{"type":"object","description":"Site facts the plugin collected. Stored only when `consent_diagnostics` is true.","properties":{"site_url":{"type":"string","maxLength":500},"wp_version":{"type":"string","maxLength":40},"php_version":{"type":"string","maxLength":40},"theme":{"type":"string","maxLength":200},"plugins":{"type":"array","maxItems":500,"items":{"type":"object","required":["slug"],"properties":{"slug":{"type":"string","maxLength":200},"version":{"type":"string","maxLength":40},"active":{"type":"boolean"}}}},"plugin_version":{"type":"string","maxLength":40},"multisite":{"type":"boolean"},"error_log_excerpt":{"type":"string","maxLength":20000},"extra":{"type":"object","additionalProperties":true}}},"PluginSupportDiscarded":{"type":"object","description":"The honeypot answer. Deliberately carries no reference and no id, so a bot learns nothing it could reuse.","required":["accepted"],"properties":{"accepted":{"type":"boolean"}}},"PluginSupportProduct":{"type":"string","description":"A product plugin support is offered for. Adding one is a registry entry in `engine/pluginsupport/products.py`, not a new endpoint.","enum":["page-builder-sandwich","tranzly","zinn-order-updates","zinn-seo"]},"PluginSupportTicketCreated":{"type":"object","required":["reference","priority"],"properties":{"reference":{"type":"string","example":"ZT-7KQ3MX"},"priority":{"type":"string","enum":["normal","high"]}}},"PluginSupportTicketInput":{"type":"object","required":["product","subject","message"],"properties":{"email":{"type":"string","format":"email","maxLength":320,"description":"Required when no connection token is sent."},"name":{"type":"string","maxLength":200},"product":{"type":"string","pattern":"^[a-z0-9-]{2,40}$","example":"tranzly"},"kind":{"type":"string","enum":["help","bug","feedback","feature_request"],"default":"help"},"subject":{"type":"string","maxLength":200},"message":{"type":"string","maxLength":20000},"locale":{"type":"string","maxLength":16},"consent_diagnostics":{"type":"boolean","default":false},"diagnostics":{"$ref":"#/components/schemas/PluginSupportDiagnostics"},"credentials":{"type":"array","maxItems":10,"items":{"$ref":"#/components/schemas/PluginSupportCredentialInput"}},"licence":{"type":"object","description":"A CLAIM, verified with Freemius before it changes priority.","properties":{"plan":{"type":"string","maxLength":40},"freemius_install_id":{"type":"string","maxLength":20},"freemius_license_id":{"type":"string","maxLength":20}}},"deflection_id":{"description":"The AI answer the visitor read first (`deflectPublicSupportQuestion`), so the support stats count this ticket as answered-then-ticketed. An unknown or stale id is ignored.","oneOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]},"website":{"type":"string","description":"Honeypot. Must be empty."}}},"PluginUpdateAttempt":{"type":"object","required":["id","plugin","from_version","to_version","outcome","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"plugin":{"type":"string"},"from_version":{"type":"string"},"to_version":{"type":"string"},"outcome":{"type":"string","enum":["updated","rolled_back","held","unchecked","failed"]},"detail":{"type":"string"},"door":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"PluginUpdateCheck":{"type":"object","description":"What the plugin sends. Its shape is fixed by the code already installed on customer sites; it is not ours to change without shipping a new plugin first.","required":["slug","version"],"properties":{"slug":{"type":"string","description":"The plugin asking","e.g. `zinn-cache`.":null},"version":{"type":"string","description":"The version currently installed."},"site":{"type":"string","description":"The site's own home URL","for our logs.":null}}},"PluginUpdateDescriptor":{"type":"object","description":"A newer release, in the exact shape the shipped updater's `parse_response` reads. Every field name here is read from that file rather than chosen: a response that is nearly right is discarded on every site, silently.","required":["version","package","package_sha256"],"properties":{"version":{"type":"string"},"package":{"type":"string","format":"uri","description":"Where to fetch the archive. Always HTTPS on our own hostname — the updater refuses any other host, which is what stops a forged descriptor pointing a site at somebody else's zip."},"package_sha256":{"type":"string","minLength":64,"maxLength":64},"tested":{"type":"string"},"requires":{"type":"string"},"requires_php":{"type":"string"},"changelog":{"type":"string"},"homepage":{"type":"string"}}},"PluginVersion":{"type":"object","description":"One downloadable version of a plugin.","required":["version","line","is_current","published_at","requires_wp","requires_php","tested_wp","package_sha256","package_bytes","changelog_url"],"properties":{"version":{"type":"string","example":"1.1.2"},"line":{"type":"string","example":"1.1","description":"The WordPress-style major version (`x.y`) this release belongs to."},"is_current":{"type":"boolean"},"published_at":{"type":"string","format":"date-time"},"requires_wp":{"type":"string"},"requires_php":{"type":"string"},"tested_wp":{"type":"string","description":"The WordPress version this release was installed and activated against before it was published. Empty means not stated, never \"any version\"."},"package_sha256":{"type":"string","minLength":64,"maxLength":64,"description":"Lowercase hex SHA-256 of this version's archive — the value `downloadPlugin` returns in `X-Zinn-Package-SHA256` when asked for this `version`."},"package_bytes":{"type":"integer"},"changelog_url":{"type":"string","format":"uri","nullable":true,"description":"Where this release's own notes say its changes are described. `null` when the release names nowhere — never a URL guessed from the slug."}}},"PluginVersionGroup":{"type":"object","required":["slug","name","kind","distribution","releases"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["wordpress_plugin","whmcs_module","hostbill_module","generic_client"]},"distribution":{"type":"string","enum":["public","app-only","licensed"]},"releases":{"type":"array","description":"The current release first, then the older ones, newest first.","minItems":1,"items":{"$ref":"#/components/schemas/PluginVersion"}}}},"PluginVersionList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PluginVersionGroup"}}}},"PostPlacement":{"type":"object","description":"Publish one post to one site, in one category, at one time — V1's `PostTask`. This row is the product: a PBN customer does not want \"a post\", they want this content on that site next Tuesday, forty times over, and a record afterwards of which ones landed.","required":["id","post_id","post_title","site_id","site_domain","category","publish_at","status","wp_post_id","wp_post_url","target_kind","remote_post_id","remote_post_url","dropped_capabilities","error","published_at","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"post_id":{"type":"string","format":"uuid"},"post_title":{"type":"string"},"site_id":{"type":"string","format":"uuid"},"site_domain":{"type":"string"},"category":{"type":"string","description":"The WordPress category NAME. Empty means the site's default category. A name rather than a term id because term ids are per-site and one post goes to many."},"publish_at":{"type":"string","format":"date-time","description":"When the sweep may publish it — not a promise about the second."},"status":{"type":"string","enum":["scheduled","publishing","published","failed","cancelled"]},"wp_post_id":{"type":"integer","nullable":true,"description":"Null until the post is live. Nullable rather than `0`, because \"not published yet\" and \"published as post 0\" are different facts and a zero renders as a broken link."},"wp_post_url":{"type":"string"},"target_kind":{"type":"string","description":"Which adapter published it. Empty until it publishes. A placement is no longer necessarily a WordPress post — `wp_post_id`/`wp_post_url` above are the WordPress projection of the three generic fields here and are populated only for `wordpress`.","enum":["","wordpress","headless_rest","git_static"]},"remote_post_id":{"type":"string","description":"What the destination calls the thing it created. A **string**, because a Ghost id is a hex ObjectId, a Shopify id is a GID URL and a Git target's is a commit sha — only WordPress has an integer, and `wp_post_id` already holds that one."},"remote_post_url":{"type":"string","description":"Where it lives. Empty when the destination does not report a URL."},"dropped_capabilities":{"type":"array","description":"What the destination could not carry, and why — `[[\"featured_image\", \"this destination has nowhere to attach a featured image\"], …]`. ⛔ Empty is the normal case and means nothing was dropped; it never means nothing was checked, because a recipe set to refuse fails the placement rather than reaching this field. This is the record that stops a silent drop being silent.","items":{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":2}},"error":{"type":"string","description":"A machine code the client localises, never a sentence. One of `site_not_active`, `site_changed_owner`, `no_adapter`, `no_target_configured`, `no_credential`, `no_repository`, `missing_capability`, `wp_cli_failed`, `wp_rest_failed`, `cms_unreachable`, `cms_refused`, `unauthorised`, `no_post_id`, `no_remote_id`, `git_push_failed`, `body_too_large`, `target_failed`, `lookup_failed`, `image_too_large`, `image_needs_url`, `image_unsupported`, `image_upload_failed`, `image_encoding_failed`, `bad_ghost_key`, `bad_payload_login`, `no_auth_header`, `no_base_url`, `unknown_auth_scheme`, `probe_failed`, `blocked_address`.\n\n⛔ This list is not maintained by hand: a test walks the engine's AST for every code it can raise and fails if one is missing here — because a code the client has no key for is rendered raw to a customer, in 58 languages, on the screen telling them their article did not publish."},"published_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"PostPlacementCreate":{"type":"object","required":["site_id","publish_at"],"properties":{"site_id":{"type":"string","format":"uuid"},"publish_at":{"type":"string","format":"date-time"},"category":{"type":"string","maxLength":200,"default":""}}},"PostPlacementPage":{"type":"object","required":["items","total","offset","limit","has_more"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PostPlacement"}},"total":{"type":"integer","minimum":0},"offset":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1},"has_more":{"type":"boolean"}}},"PremiumDnsOffer":{"type":"object","description":"Whether the Premium DNS upsell may be shown for one domain. ⛔ `available: false` with a `reason` is a considered suppression, not an error.","additionalProperties":false,"required":["available","reason","code","active","extra"],"properties":{"available":{"type":"boolean","description":"Show the offer."},"extra":{"nullable":true,"description":"The catalogue row for `code`, priced in the caller's currency exactly as `GET /v1/extras` would serve it. The Premium DNS rows are not public, so the storefront list never carries them; the card's purchase review prices from this row (§2.8: never a number typed in the client). `null` when the offer is not available, is already active, or its row is not sellable.","allOf":[{"$ref":"#/components/schemas/Extra"}]},"reason":{"type":"string","nullable":true,"enum":["registrar_locks_nameservers","no_zone_of_its_own","registry_unavailable"],"description":"Why the offer is hidden, as a CODE for the client to translate. `null` when `available` is true, and also when `active` is true — an existing purchase is not a suppression."},"code":{"type":"string","nullable":true,"description":"The `Extra.code` to purchase, chosen by the domain's product line."},"active":{"type":"boolean","description":"Already bought for this domain and not refunded. The screen says so rather than offering it again — and it is a THIRD state, not `available: false` with a reason: hiding the card would read as \"not available to you\", and showing the offer again would read as \"you do not have it\".\n\nThe purchase itself names this domain through `ExtraPurchaseCreate.domain_id`. Premium DNS is applied at the registrar, per zone, so the unit is the domain and there may be no site anywhere near it."}}},"PrepayOrder":{"type":"object","description":"The **unpaid** order minted for a prepayment. ⛔⛔ No money has been taken. The client settles it through `POST /v1/orders/{orderId}/pay`, which already knows how to pay from account balance, from a gateway, or from both — which is what lets a customer with no chargeable mandate (crypto, or a market whose regulator forbids off-session charges) use this at all.","required":["order_id","order_number","periods","total_amount_minor","currency","status"],"properties":{"order_id":{"$ref":"#/components/schemas/Uuid"},"order_number":{"type":"string"},"periods":{"type":"integer"},"total_amount_minor":{"type":"integer","description":"Including tax."},"currency":{"type":"string","minLength":3,"maxLength":3},"status":{"type":"string"}}},"PrepayQuote":{"type":"object","description":"What paying for N more whole billing periods would cost, and where the subscription would run to (W41-G). ⛔ It carries a **price** and makes no claim about the customer's balance: funds are read once, at charge time. Quoting against a balance read minutes earlier is how a customer who has since topped up gets refused with the money sitting there.","required":["subscription_id","periods","interval","unit_amount_minor","total_amount_minor","currency","current_period_end","extends_to","max_periods"],"properties":{"subscription_id":{"$ref":"#/components/schemas/Uuid"},"periods":{"type":"integer","minimum":1},"interval":{"type":"string","enum":["monthly","annual"]},"unit_amount_minor":{"type":"integer","description":"The captured per-period price in minor units (§2.8) — never re-derived from the catalogue."},"total_amount_minor":{"type":"integer","description":"Net of tax; tax is added on the order."},"currency":{"type":"string","minLength":3,"maxLength":3},"current_period_end":{"type":"string","format":"date-time"},"extends_to":{"type":"string","format":"date-time"},"max_periods":{"type":"integer","description":"The most periods one payment may buy."},"debt_amount_minor":{"type":"integer","minimum":0,"description":"s1014 R40 GAP-9 (docs/747 §2c): a recorded debt — service already provided, brought back by staff while still owed — that this order pays FIRST, net minor units. Included in `total_amount_minor`. 0 when none."}}},"PrepayRequest":{"type":"object","required":["periods"],"properties":{"periods":{"type":"integer","minimum":1,"description":"How many whole billing periods to pay for now."}}},"PresalesAnswer":{"type":"object","required":["answer","grounded","citations","plan_codes","plans"],"description":"One answer. ⛔⛔ `grounded: false` is a SUCCESS, not a failure — see the operation's description. Render it as a route to a human; never as an error.","properties":{"answer":{"type":"string","description":"The reply, in the language the visitor wrote in."},"grounded":{"type":"boolean","description":"True when the answer came from the supplied articles and catalogue. False when the assistant said it could not answer from them — which is the honest outcome and the one this surface exists to make possible."},"citations":{"type":"array","items":{"type":"string"},"description":"Slugs of published articles the answer used, for `/kb/{slug}`. ⛔ Filtered to the ones actually supplied to the model, so a fabricated citation can never render as a link to a 404."},"plan_codes":{"type":"array","items":{"type":"string"},"description":"Catalogue plan codes the answer recommends or prices, filtered the same way. The site turns these into links to the page that sells them."},"plans":{"type":"array","description":"The plans in `plan_codes`, in the same order, with the name a visitor sees. ⛔ A code is an internal identifier and is never shown; the answer text has already had every supplied code replaced by its name (D25026).","items":{"type":"object","required":["code","name"],"properties":{"code":{"type":"string"},"name":{"type":"string"}}}}}},"PresalesAskRequest":{"type":"object","required":["question"],"description":"One pre-sales question, plus whatever the caller is holding of the thread.","properties":{"question":{"type":"string","minLength":1,"maxLength":1000,"description":"What the visitor asked, in their own language. ⛔ Shorter than the dashboard assistant's 4,000: a customer pastes an error log, a prospect asks a question, and an unbounded prompt on an anonymous surface is an unbounded bill."},"locale":{"type":"string","default":"en","description":"Which translation of a knowledge-base article to retrieve, and the language to answer in. An unknown value falls back to English rather than failing."},"currency":{"type":"string","default":"USD","description":"Which currency's catalogue prices reach the answer. ⛔ A hint, not a filter: a plan that carries no price in this currency is quoted in one it does have, clearly labelled, because an empty price list reads to a reader exactly like a free product."},"history":{"type":"array","maxItems":6,"description":"Earlier turns, oldest first. ⛔ The CALLER holds these because nothing is stored — there is no account to hang a conversation on and no lawful basis to keep one. They are therefore untrusted input and are bounded and truncated.","items":{"$ref":"#/components/schemas/PresalesTurn"}}}},"PresalesTicketAccepted":{"type":"object","required":["reference"],"properties":{"reference":{"type":"string","description":"The ticket reference the asker can quote back at us."}}},"PresalesTicketInput":{"type":"object","required":["email","question"],"properties":{"email":{"type":"string","format":"email","maxLength":254,"description":"Where the answer is sent."},"name":{"type":"string","maxLength":200},"question":{"type":"string","minLength":1,"maxLength":5000},"source_page":{"type":"string","maxLength":200,"description":"The site path the question was asked from (e.g. `/en/hosting`). Anything not starting `/` is dropped."},"locale":{"type":"string","maxLength":16,"description":"The asker's language; the answer is written in it."},"turnstile_token":{"type":"string","description":"The Cloudflare Turnstile token."},"website":{"type":"string","description":"Honeypot. Leave empty."}}},"PresalesTurn":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string","maxLength":1500}}},"Principal":{"type":"object","required":["user","memberships","capabilities"],"properties":{"user":{"$ref":"#/components/schemas/User"},"capabilities":{"type":"object","additionalProperties":{"type":"boolean"},"description":"What this **deployment** is wired to do — not what this person is permitted to do. ⛔ The two fail differently: a missing permission means the control is correctly absent, while a missing capability means the control is present, the person is entitled to press it, and the backend refuses **after** a confirmation dialog. A console gates its UI on both (#1329).\n\n`impersonation` — whether staff can open a customer's dashboard as them. True exactly when this deployment holds a grant signing key. Wired from the same object the feature uses, so it cannot drift from the behaviour it describes.","example":{"impersonation":true}},"memberships":{"type":"array","description":"The user's org memberships and roles (docs/02 §1).","items":{"$ref":"#/components/schemas/Membership"}},"account_restrictions":{"type":"array","description":"The organisations this person reaches that are in **bad standing** and are therefore locked to billing (W43-107, owner ruling 2026-09-15). While an org is listed here every non-billing endpoint answers `403` with code `ACCOUNT_RESTRICTED` for it — tools, backup downloads, site moves, exports and the API/CLI alike — and only billing, subscriptions and the org's own record stay open. Empty for an account in good standing. Re-read on every request, so paying what is owed lifts it at once.","items":{"type":"object","required":["org_id","reason"],"properties":{"org_id":{"$ref":"#/components/schemas/Uuid"},"reason":{"type":"string","enum":["past_due","suspended"],"description":"`past_due` — a subscription the dunning ladder suspended for non-payment; `suspended` — the organisation itself is suspended."}}}},"email_warning":{"description":"MAILQUOTA (owner ruling 2026-11-11): this person's own address is a real mailbox whose inbox was FULL when they signed up, so our e-mails may bounce; the dashboard shows a banner asking them to clear it. `null` when there is nothing to say, and once the day-long check expires.","oneOf":[{"$ref":"#/components/schemas/EmailWarning"},{"type":"null"}]},"is_staff":{"type":["boolean","null"],"description":"HOSTILE1116 (2026-11-16): whether this person is a member of a staff organisation, the same test the engine applies to every `/v1/admin/*` route. A membership `role` cannot answer it, because customer organisations have a `manager` role too. The admin console shows a \"not a staff account\" screen and calls no staff endpoint unless this is `true`; it fails closed, so `null` (the engine did not compute it) is treated as not staff."}}},"PrivacyDownloadLink":{"type":"object","required":["url","expires_at"],"properties":{"url":{"type":"string","format":"uri","description":"A presigned URL. A credential — never log it."},"expires_at":{"type":"string","format":"date-time"}}},"PrivacyErasureCreate":{"type":"object","required":["confirm_name","acknowledge"],"properties":{"confirm_name":{"type":"string","description":"The organization's exact name, typed."},"acknowledge":{"type":"boolean","description":"Must be `true` — the second confirmation."}}},"PrivacyErasureState":{"type":"object","required":["request","cooling_off_days"],"properties":{"request":{"oneOf":[{"$ref":"#/components/schemas/PrivacyRequest"},{"type":"null"}]},"cooling_off_days":{"type":"integer"}}},"PrivacyRequest":{"type":"object","description":"A GDPR data export or account erasure (`docs/1100`).","required":["id","org_id","kind","status","created_at","erase_after","completed_at","cancelled_at","expires_at","size_bytes","row_count","table_count","retain_until"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"org_id":{"$ref":"#/components/schemas/Uuid"},"kind":{"type":"string","enum":["export","erasure"]},"status":{"$ref":"#/components/schemas/PrivacyRequestStatus"},"created_at":{"type":"string","format":"date-time"},"erase_after":{"type":["string","null"],"format":"date-time","description":"Erasure only — when the cooling-off period ends and the erasure runs."},"completed_at":{"type":["string","null"],"format":"date-time"},"cancelled_at":{"type":["string","null"],"format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time","description":"Export only — when the archive is deleted."},"size_bytes":{"type":"integer","format":"int64"},"row_count":{"type":"integer","format":"int64"},"table_count":{"type":"integer"},"retain_until":{"type":["string","null"],"format":"date","description":"Erasure only — the last day the retained tax records are kept."}}},"PrivacyRequestList":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PrivacyRequest"}}}},"PrivacyRequestStatus":{"type":"string","enum":["pending","scheduled","running","ready","expired","completed","cancelled","failed"]},"PrivateNetwork":{"type":"object","required":["id","region","region_label","egress_ip","status","seats_used","can_add_device","items"],"properties":{"id":{"type":"string","format":"uuid"},"region":{"type":"string","description":"Machine code for the gateway's region, e.g. `eu-nbg1`."},"region_label":{"type":"string","description":"What the customer sees, e.g. `Germany (Nuremberg)`."},"egress_ip":{"type":"string","nullable":true,"description":"The dedicated address every device on this network connects out from — the one to add to SSH/SFTP allow-lists. It belongs to this organisation alone; a shared gateway address would mean another customer's packets also satisfied those allow-lists.\n\nNull only in the short window between purchase and the address being attached. While it is null no configuration can be issued, so a customer is never handed one that egresses from an address they were told was theirs."},"status":{"type":"string","enum":["active","suspended","closed"],"description":"`suspended` means the organisation is not currently in good standing, so devices are withheld from the gateway. ⛔ Nothing is deleted — devices resume on their own when payment resumes."},"seats_used":{"type":"integer","description":"Devices currently enrolled and not revoked."},"can_add_device":{"type":"boolean","description":"Whether another device may be enrolled right now. False when the allowance is spent, the address has not landed, or the organisation is not in good standing. The screen renders the control as ABSENT rather than disabled when this is false."},"items":{"type":"array","items":{"$ref":"#/components/schemas/PrivateNetworkDevice"}}}},"PrivateNetworkDevice":{"type":"object","required":["id","label","address","status","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"label":{"type":"string","maxLength":80,"description":"What the customer calls it — \"Neil's MacBook\"."},"address":{"type":"string","description":"The device's address inside the tunnel."},"status":{"type":"string","enum":["active","revoked"]},"created_at":{"type":"string","format":"date-time"},"revoked_at":{"type":"string","format":"date-time","nullable":true},"last_seen_at":{"type":"string","format":"date-time","nullable":true,"description":"Last handshake the gateway reported. Null until the device first connects, which is what makes \"you are paying for five devices and three have never been used\" answerable."}}},"PrivateNetworkDeviceCreate":{"type":"object","required":["label"],"properties":{"label":{"type":"string","maxLength":80}}},"PrivateNetworkIssuedDevice":{"type":"object","required":["seat","config"],"properties":{"seat":{"$ref":"#/components/schemas/PrivateNetworkDevice"},"config":{"type":"string","description":"The complete WireGuard configuration file. ⛔⛔ Returned ONCE, on this response only. It contains the device's private key, which is generated in memory and never stored anywhere by Zinn® — so no endpoint can return it again. Save it or rotate the device."}}},"PrivateNetworkRead":{"type":"object","description":"`GET /v1/private-network`. `network` is null when the organisation has not bought the product (NIGHTFIX1114 PNEMPTY: a normal answer, so a 200, not a 404).","required":["network"],"additionalProperties":false,"properties":{"network":{"oneOf":[{"$ref":"#/components/schemas/PrivateNetwork"},{"type":"null"}]}}},"ProDiscountCode":{"type":"object","description":"One personal, single-use code. The code itself is a credential worth one purchase.","additionalProperties":false,"required":["code","checkout_url","status","percent","issued_at","expires_at","redeemed_at"],"properties":{"code":{"type":"string","example":"ZHK3M7Q2XW9PAB"},"checkout_url":{"type":"string","format":"uri","description":"The store's checkout with the code already applied."},"status":{"type":"string","enum":["active","redeemed","expired","revoked"]},"percent":{"type":"integer","example":50},"issued_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time"},"redeemed_at":{"type":"string","format":"date-time","nullable":true}}},"ProDiscountCodeRequest":{"type":"object","additionalProperties":false,"properties":{"org_id":{"type":"string","format":"uuid","nullable":true,"description":"The account to act for. Required when you belong to more than one."}}},"ProDiscountIssued":{"type":"object","additionalProperties":false,"required":["product","created","code"],"properties":{"product":{"type":"string"},"created":{"type":"boolean"},"code":{"$ref":"#/components/schemas/ProDiscountCode"}}},"ProDiscountList":{"type":"object","additionalProperties":false,"required":["org_id","eligible","terms","offers"],"properties":{"org_id":{"type":"string","format":"uuid"},"eligible":{"type":"boolean","description":"Whether this account holds a paid hosting plan, active and in good standing."},"terms":{"$ref":"#/components/schemas/ProDiscountTerms"},"offers":{"type":"array","items":{"$ref":"#/components/schemas/ProDiscountOffer"}}}},"ProDiscountOffer":{"type":"object","additionalProperties":false,"required":["product","name","plugin","plugin_name","edition","state","code"],"properties":{"product":{"type":"string","description":"The Pro product's key — what `getProDiscountCode` takes.","example":"tranzly"},"name":{"type":"string","example":"Tranzly Pro"},"plugin":{"type":"string","description":"The free plugin it upgrades (the one installed on hosted sites).","example":"tranzly"},"plugin_name":{"type":"string","example":"Tranzly"},"edition":{"type":"string","example":"tranzly-pro"},"state":{"type":"string","enum":["available","active","redeemed"],"description":"`available` — ask for a code; `active` — you hold a live code; `redeemed` — you have used your discount for this plugin."},"code":{"allOf":[{"$ref":"#/components/schemas/ProDiscountCode"}],"nullable":true}}},"ProDiscountTerms":{"type":"object","description":"The hosting-customer discount's terms, read from the plugin registry.","additionalProperties":false,"required":["percent","first_payment_only","code_valid_days"],"properties":{"percent":{"type":"integer","example":50},"first_payment_only":{"type":"boolean","description":"Renewals are at the normal price.","example":true},"code_valid_days":{"type":"integer","example":30}}},"ProductLine":{"type":"object","description":"A family of plans sharing one surface and entitlement bundle (CLAUDE.md §2.14).","required":["code","name","included_features","default_entitlements"],"properties":{"code":{"type":"string","description":"Stable machine code for the product line.","example":"footprint_free"},"name":{"type":"string","example":"Footprint-Free Hosting"},"description":{"type":"string","example":"Zero-footprint PBN hosting built for SEOs."},"included_features":{"type":"array","description":"Display-only marketing bullets (not enforced entitlements).","items":{"type":"string"}},"default_entitlements":{"$ref":"#/components/schemas/Entitlements"}}},"ProductLineList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductLine"}}}},"PromoCodeSet":{"type":"object","required":["code"],"properties":{"code":{"type":"string","maxLength":64,"example":"DAVIDIBIZA20"}}},"Proposal":{"allOf":[{"$ref":"#/components/schemas/ProposalSummary"},{"type":"object","required":["lines","totals","events","editable"],"properties":{"message":{"type":"string"},"terms":{"type":"string"},"agency_tax_rate_id":{"type":["string","null"],"format":"uuid"},"recipient_country":{"type":"string"},"recipient_tax_id":{"type":"string"},"recipient_locale":{"type":"string"},"accepted_revision":{"type":["integer","null"]},"accepted_by_name":{"type":"string"},"source_request_id":{"type":["string","null"],"format":"uuid"},"completed_at":{"type":["string","null"],"format":"date-time"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/ProposalLine"}},"totals":{"$ref":"#/components/schemas/ProposalTotals"},"invoice":{"oneOf":[{"$ref":"#/components/schemas/ProposalInvoice"},{"type":"null"}]},"events":{"type":"array","items":{"$ref":"#/components/schemas/ProposalEvent"}},"editable":{"type":"boolean"},"public_url":{"type":"string","description":"Returned ONCE, by `send`. Never readable again."}}}]},"ProposalEvent":{"type":"object","required":["kind","created_at"],"properties":{"kind":{"type":"string"},"actor":{"type":"string"},"revision":{"type":"integer"},"body":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"ProposalInput":{"type":"object","properties":{"title":{"type":"string","minLength":3,"maxLength":200},"message":{"type":"string"},"terms":{"type":"string"},"currency":{"type":"string","minLength":3,"maxLength":3},"valid_until":{"type":["string","null"],"format":"date"},"agency_tax_rate_id":{"type":["string","null"],"format":"uuid"},"recipient_name":{"type":"string","maxLength":200},"recipient_email":{"type":"string","format":"email"},"recipient_company":{"type":"string","maxLength":200},"recipient_country":{"type":"string","maxLength":2},"recipient_tax_id":{"type":"string","maxLength":64},"recipient_locale":{"type":"string","maxLength":12},"source_request_id":{"type":["string","null"],"format":"uuid"},"lines":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/ProposalLineInput"}}}},"ProposalInvoice":{"type":"object","required":["kind","reference","status","paid","total_minor","currency","pay_url"],"properties":{"kind":{"type":"string","enum":["direct","agency"]},"reference":{"type":"string"},"status":{"type":"string"},"paid":{"type":"boolean"},"total_minor":{"type":"integer"},"currency":{"type":"string"},"pay_url":{"type":["string","null"]}}},"ProposalLine":{"allOf":[{"$ref":"#/components/schemas/ProposalLineInput"},{"type":"object","required":["total_minor"],"properties":{"total_minor":{"type":"integer"}}}]},"ProposalLineInput":{"type":"object","required":["title","unit_amount_minor"],"properties":{"title":{"type":"string","minLength":3,"maxLength":300},"description":{"type":"string"},"quantity":{"type":"integer","minimum":1,"default":1},"unit_amount_minor":{"type":"integer","minimum":0,"description":"NET price per unit in minor units (§2.8)."}}},"ProposalList":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ProposalSummary"}}}},"ProposalStatus":{"type":"string","enum":["draft","sent","changes_requested","accepted","declined","withdrawn","project","completed"]},"ProposalSummary":{"type":"object","required":["id","reference","status","title","currency","recipient_name","recipient_email","revision","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"reference":{"type":"string"},"status":{"$ref":"#/components/schemas/ProposalStatus"},"title":{"type":"string"},"currency":{"type":"string"},"recipient_name":{"type":"string"},"recipient_email":{"type":"string"},"recipient_company":{"type":"string"},"revision":{"type":"integer"},"valid_until":{"type":["string","null"],"format":"date"},"sent_at":{"type":["string","null"],"format":"date-time"},"decided_at":{"type":["string","null"],"format":"date-time"},"paid_at":{"type":["string","null"],"format":"date-time"},"board_id":{"type":["string","null"],"format":"uuid"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ProposalTotals":{"type":"object","required":["subtotal_minor","tax_minor","total_minor"],"properties":{"subtotal_minor":{"type":"integer"},"tax_minor":{"type":["integer","null"],"description":"The tax the invoice will charge, from the same calculator. `null` when it cannot be said yet (no country, provider unavailable) — never a zero that reads as \"no tax\"."},"total_minor":{"type":["integer","null"]}}},"PublicBilling":{"type":"object","required":["country"],"description":"The buyer block. Only `country` is required, because tax is country- and currency-aware and an order with no jurisdiction has no determinable tax; the rest can be completed later in the dashboard.","properties":{"country":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2."},"legal_name":{"type":"string","maxLength":200},"company_name":{"type":"string","maxLength":200},"address_line1":{"type":"string","maxLength":200},"address_line2":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":120},"region":{"type":"string","maxLength":120},"postcode":{"type":"string","maxLength":32},"vat_number":{"type":"string","maxLength":32}}},"PublicCart":{"type":"object","required":["id","status","currency","expires_at","items","totals"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"token":{"type":"string","description":"The bearer token. Returned **only** from `createPublicCart` — it is absent on every subsequent read, because only its digest is stored."},"status":{"type":"string","enum":["open","converted","expired"]},"currency":{"$ref":"#/components/schemas/CurrencyCode"},"product_line":{"type":"string","nullable":true},"expires_at":{"type":"string","format":"date-time","description":"After this the cart is gone — reads 404 whether or not it has been purged."},"items":{"type":"array","items":{"$ref":"#/components/schemas/PublicCartItem"}},"totals":{"$ref":"#/components/schemas/PublicCartTotals"}}},"PublicCartCreate":{"type":"object","properties":{"currency":{"$ref":"#/components/schemas/CurrencyCode"},"product_line":{"type":"string","maxLength":64}}},"PublicCartExtraCreate":{"type":"object","required":["code"],"properties":{"interval":{"type":"string","enum":["","monthly","annual"],"description":"`annual` puts an **SEO tool** in the basket for twelve months at V1's yearly saving (D19). The 3-tool bundle is applied across the basket automatically. A `422` on a row with no yearly term."},"code":{"type":"string","maxLength":64,"description":"The catalogue code of the service being added (`managed_migration`, `site_speedup_standard`, …), from `OrderConfig.addons`.\n\nOne field, and deliberately no product line beside it: which addons a basket may buy is a fact about the basket, not a claim the client makes. This endpoint is anonymous, so a caller-supplied line would let anybody buy a PBN-only addon on any basket."}}},"PublicCartItem":{"type":"object","required":["id","kind","name","domain_name","tld","period_years","interval","plan_code","extra_code","privacy","is_trial","domain","included_domain_applied","unit_amount_minor","currency","discount_minor","line_total_minor"],"properties":{"allowed_years":{"type":"object","nullable":true,"required":["min","max"],"description":"s1014 DOMAINS: for a domain line, the terms (years) it can be changed to with `updatePublicCartItem` — the extension's own range, served by the engine so the basket, the dashboard and the AI read one source. Null on any other line.","properties":{"min":{"type":"integer"},"max":{"type":"integer"}}},"listing_package_id":{"type":["string","null"],"format":"uuid","description":"The package a `marketplace_package` line sells, for the checkout's tax quote (`POST /v1/public/pricing/tax-quote` rates it by the listing's service type); null on every other line (L66)."},"listed_amount_minor":{"type":["integer","null"],"description":"L66 (docs/82 §2-fx) — on a marketplace line CHARGED in EUR/GBP, the listed USD price (minor units) it was converted from at the locked rate; null on every other line."},"listed_currency":{"type":["string","null"],"description":"The listing currency (`USD`) when `listed_amount_minor` is set, else null."},"id":{"$ref":"#/components/schemas/Uuid"},"kind":{"type":"string","enum":["domain_register","hosting_plan","compute_server","extra","marketplace_package"],"description":"`marketplace_package` (s1014 J08): one package of a live marketplace listing, bought as a guest — the account is created at checkout and the line converts to the signed-in `marketplace_package` cart line; its `name` is \"Listing — Package\". What this line buys. The public funnel sold domain registrations only until owner ruling D-W15-2 put hosting, free trials and machines through the same checkout — a client MUST branch on this rather than assuming a domain, or it renders an empty name for half the basket. `extra` joined in 2026-09-09 when addons became configurable alongside the plan they are bought with, and it is the one kind whose price may be **recurring or one-off** — read `interval` rather than assuming a basket total is a single figure."},"name":{"type":"string","description":"What the basket should CALL this line: the FQDN for a domain, the machine's name for a server, and `\"\"` for a hosting plan (whose title the storefront already holds in its catalogue snapshot — looking it up here would be a query per line on every cart read)."},"domain_name":{"type":"string","description":"The full FQDN this item registers; `\"\"` on every non-domain line."},"tld":{"type":"string","description":"Empty on every non-domain line."},"period_years":{"type":"integer","nullable":true,"minimum":1,"maximum":10,"description":"The registration term in years; `null` on every non-domain line."},"interval":{"type":"string","enum":["","monthly","annual"],"description":"The recurring cadence of a plan or server line; `\"\"` for a one-off domain registration."},"plan_code":{"type":"string","description":"The catalogue code of the size a `compute_server` line buys (e.g. `cloud_20i_medium`); `\"\"` on every other kind."},"extra_code":{"type":"string","maxLength":64,"description":"The catalogue code of the service an `extra` line buys; `\"\"` on every other kind. Served alongside `name` because this payload looks nothing up per line — without the code and the captured name an addon row would render as a price with nothing beside it."},"is_trial":{"type":"boolean","description":"Whether this line is a FREE TRIAL rather than a purchase (owner ruling 2026-08-09 — a trial takes no card and starts immediately). A trial line is priced at **zero**, and a basket that shows 0.00 with no other signal reads as a pricing fault: branch on this to label the line and to say \"start trial\" rather than \"pay\" on the button beneath it."},"domain":{"allOf":[{"$ref":"#/components/schemas/PublicCartPlanDomain"}],"nullable":true,"description":"On a `hosting_plan` line, which domain it is for; `null` on every other kind and whenever the visitor has not said yet.\n\n⛔ `null` and \"an answer of nothing\" are different states: the basket has to be able to offer the question again rather than assume it was asked."},"region":{"type":"string","description":"On a `hosting_plan` line, the data centre its sites will be placed in, as the public city slug `GET /v1/catalog/regions` publishes (`helsinki`); `\"\"` when the visitor left it to us, and on every other kind (s1014 R37). The checkout page shows it and changes it with `updatePublicCartItem`."},"included_domain_applied":{"type":"boolean","description":"Whether this line was priced free against the plan's `included_domains` allowance — the free domain a hosting plan grants (owner ruling 2026-08-14: free year one, on a staff-editable TLD allow-list per plan).\n\n⛔ **Branch on this rather than inferring it from \"discounted to zero\".** That inference is three facts about arithmetic standing in for one fact about intent, and it reads any other zero — a promo, a support credit — as the customer's free domain. A basket that shows an unexplained 0.00 is not believed; label the line \"Free with your plan\".\n\n⭐ Only ONE year is covered however long the term, so on a multi-year registration this is `true` while `line_total_minor` is still positive. A client that treats it as \"this line is free\" will show the wrong price."},"privacy":{"type":"boolean","description":"WHOIS privacy, when the TLD supports it (forced false when it does not)."},"is_premium":{"type":"boolean","description":"Bound to a live per-name registrar quote rather than the TLD catalogue. The price holds for the availability token's TTL and is re-verified at checkout; a quote that has moved is a `409`, never a silent re-charge."},"unit_amount_minor":{"type":"integer","format":"int64","description":"Server-computed price in minor units — never a client-supplied figure."},"currency":{"$ref":"#/components/schemas/CurrencyCode"},"discount_minor":{"type":"integer","format":"int64"},"line_total_minor":{"type":"integer","format":"int64","description":"Unit price less discount. Tax is added at checkout, not here."},"privacy_amount_minor":{"type":"integer","format":"int64","description":"How much of `unit_amount_minor` is the WHOIS-privacy extra; `0` when it was not bought or the TLD sells none. A guest cart cannot hold a second row for the same name, so privacy is priced **into** the domain item here and materialised as its own `privacy_addon` order line at checkout — this field is the breakdown that lets the basket show it as the separate purchasable it is."}}},"PublicCartItemCreate":{"type":"object","required":["kind","domain","tld","years","availability_token"],"properties":{"kind":{"type":"string","enum":["domain_register"]},"domain":{"type":"string","maxLength":253,"description":"The full FQDN (`acme.com`) or just the second-level label (`acme`) alongside `tld`. Both resolve to the same name; a sub-domain is rejected."},"tld":{"type":"string","maxLength":63},"years":{"type":"integer","minimum":1,"maximum":10},"availability_token":{"type":"string","maxLength":2048,"description":"The `token` from a search result **for this exact name**. Required — it is what proves the item came from a real search, so nothing that search declines to sell can be added by hand."},"privacy":{"type":"boolean","default":true}}},"PublicCartItemUpdate":{"type":"object","additionalProperties":false,"description":"Exactly one of `region` (a hosting plan line) or `years` (a domain line).","properties":{"region":{"type":"string","maxLength":32,"description":"A public city slug (`helsinki`) or placement code; `\"\"` = choose for me."},"years":{"type":"integer","minimum":1,"maximum":10,"description":"s1014 DOMAINS: a domain line's registration term, within the item's own `allowed_years` (the extension's range; one year for a premium name). Out of range is a `422` (`refusal.domains.termNotSold`). The price follows; renewals follow the chosen term."}}},"PublicCartMarketplaceCreate":{"type":"object","additionalProperties":false,"required":["listing_package_id"],"properties":{"listing_package_id":{"$ref":"#/components/schemas/Uuid"}}},"PublicCartPlanCreate":{"type":"object","required":["plan_version_id","interval"],"properties":{"plan_version_id":{"type":"string","format":"uuid","description":"The immutable plan VERSION being bought. Pinning the version rather than the plan is what stops a catalogue edit repricing a basket somebody is part-way through."},"interval":{"type":"string","enum":["monthly","annual"]},"domain":{"allOf":[{"$ref":"#/components/schemas/PublicCartPlanDomain"}],"nullable":true,"description":"Which domain this hosting is for. **Optional** — \"I will decide later\" is a real and common answer, and refusing it would put a wall in front of the purchase this field exists to unblock."},"trial":{"type":"boolean","default":false,"description":"Start a free trial of this plan instead of buying it. The line prices at zero and the order completes with no payment step (owner ruling 2026-08-09 — a trial takes no card and starts immediately)."},"trial_campaign":{"type":"string","maxLength":64,"pattern":"^[-a-zA-Z0-9_]*$","description":"The campaign a trial is started from (owner, 2026-10-21 — the \"Move from Zeabur\" page's 30-day trial, docs/1006). Sent only by that campaign's landing page. A campaign-only trial template is invisible to every public surface and is granted only when this names it and it is offered on the plan; any other value is ignored (the plan's public trial, if any, still applies). Meaningless without `trial`."},"trial_app":{"type":"string","enum":["","node","python","php","abantecart","cakephp","concretecms","craft","dolibarr","dotnet","drupal","joomla","laravel","matomo","magento","mautic","mediawiki","modx","moodle","nextcloud","opencart","oscommerce","osticket","owncloud","payload","phpbb","piwigo","prestashop","silverstripe","strapi","suitecrm","typo3","whmcs","woocommerce","wordpress","zenphoto"],"description":"The application a trial is started for (owner, 2026-11-02 — an application card's \"Start a free trial\" starts the matching hosting trial with that application). One of the app-trial picker's values (`APP_TRIAL_CHOICES`); honoured only on a `trial` line whose plan is that application's own trial plan, and refused (422) otherwise. Recorded on the trial as its app choice, so the first run opens the site form on that application's stack with the application chosen. Ignored on a purchase."},"region":{"type":"string","maxLength":32,"description":"The data centre the visitor chose for the sites this plan will host. Blank means *no preference* — we place them ourselves.\n\nParity with the signed-in cart's `region`, which has carried the same choice since the owner ruled (2026-09-01) that a region is picked at purchase as well as per site. Without it the public configuration page could offer the picker and the answer would reach nothing.\nAccepts a placement code or a public city slug (`helsinki`, as `GET /v1/catalog/regions` publishes), and is checked against THIS plan's product line (s1014 R37): a city that line cannot use is refused.\n\nValidated against the data centres we can actually honour, not merely against the vocabulary: an unhonourable code is a `422` rather than a stored preference every site then quietly ignores. `OrderConfig.regions` is the list to offer — it is **empty** on Footprint-Free by owner ruling, and the picker must then not render at all."}}},"PublicCartPlanDomain":{"type":"object","required":["mode","fqdn"],"description":"Which domain a hosting plan is being bought for. ⚖️ The owner's complaint, twice: *\"I still do not see when adding hosting there is an option to use a domain from us or another provider or to register a new domain for the service at the same time.\"*\n\nTwo modes, because those are the two an ANONYMOUS visitor can give. The third branch — \"use a domain we already hold for you\" — needs an account to mean anything and is offered in the dashboard's site-create flow instead.","properties":{"mode":{"type":"string","enum":["register","external"],"description":"`register` — the domain is being registered in THIS basket. The `fqdn` must match a `domain_register` item already in the cart; anything else is a `422`, so a plan line can never carry a claim the order does not deliver.\n\n`external` — the buyer already owns the name somewhere else. Recorded as stated: whether they can delegate it is settled by `POST /v1/domains/connect`, which returns the delegation to set. Asking an unauthenticated endpoint to prove ownership is both a rate-limit surface and the wrong question."},"fqdn":{"type":"string","maxLength":253,"description":"The full domain name, lower-cased and without a trailing dot."}}},"PublicCartServerCreate":{"type":"object","required":["plan_code","interval","name"],"properties":{"plan_code":{"type":"string","maxLength":64,"description":"The catalogue code of the size, as `listCatalogCompute` publishes it (e.g. `cloud_20i_medium`). A **plan code** rather than a `plan_version_id`, because that is what the engine resolves an order from — pinning the immutable version so a catalogue edit cannot reprice a basket somebody is part-way through is the server's job, not the client's."},"interval":{"type":"string","enum":["monthly","annual"],"description":"The term the machine is bought for. A cadence the chosen size is not priced at is a `422`; `listCatalogCompute` publishes every cadence each size is sold at, so a term picker built from it never offers one that cannot be honoured."},"name":{"type":"string","maxLength":64,"description":"What the customer will call the machine. Unique within a basket — two lines naming the same machine each pass individually and collide only once both are fulfilled, which is after the card."}}},"PublicCartTotals":{"type":"object","required":["subtotal","discount","total"],"description":"Pre-tax totals. Tax appears on the order, once a billing country exists.","properties":{"subtotal":{"$ref":"#/components/schemas/MoneyAmount"},"discount":{"$ref":"#/components/schemas/MoneyAmount"},"total":{"$ref":"#/components/schemas/MoneyAmount"}}},"PublicChatAgentConfig":{"type":"object","description":"Everything the widget needs to draw itself. No identifiers, no secrets.","required":["name","greeting"],"properties":{"name":{"type":"string"},"greeting":{"type":"string"},"brand_colour":{"type":"string"},"launcher_position":{"type":"string","enum":["left","right"]},"handoff_enabled":{"type":"boolean"},"live_chat_key":{"type":"string","description":"CHAT-UNIFY (owner row 31): present only when the site ALSO runs Zinn® Chat, the agent may hand over, and that chat accepts this page's origin. The embed then hands the page to the Zinn® Chat widget (`/embed/zinn-chat.js`, `data-zinn-chat`), whose assistant answers from this same agent and can pass the same conversation to the team: one widget, AI first, then a person. A public key, already visible on the page."},"strings":{"type":"object","description":"The widget's own words — button labels, placeholder, greeting fallback, error line — in the language asked for by `?locale=` (the nearest of the 58 site locales, else English). ⛔ Served here so the embed script carries no language data (§2.19, §2.22).","additionalProperties":{"type":"string"}}}},"PublicChatConfig":{"type":"object","required":["widget_id","branding","online"],"properties":{"widget_id":{"type":"string","format":"uuid"},"team_name":{"type":"string"},"greeting":{"type":"string"},"accent_colour":{"type":"string"},"position":{"type":"string","enum":["left","right"]},"branding":{"type":"boolean","description":"Whether \"Powered by Zinn® Chat\" is shown. Decided by the TIER, not by the widget's own flag — a customer who downgrades stops hiding our mark without anybody editing their settings."},"logo_url":{"type":"string","description":"The customer's logo for the chat header, or empty. Served only when the chat is on Premium, the same tier gate as `branding`."},"ai_enabled":{"type":"boolean"},"online":{"type":"boolean","description":"Whether a person is likely to answer, from the customer's declared business hours. Not operator presence: that would need the dashboard to hold a socket open, which this design deliberately refuses. Opening hours are a Premium setting, so a free chat reads as always online. ⭐ On OUR OWN chat it is staff presence instead: true while a member of staff has the admin live-chat inbox open."},"strings":{"type":"object","additionalProperties":{"type":"string"},"description":"The widget's own words in the visitor's language (`?locale=`)."},"desk":{"$ref":"#/components/schemas/PublicChatDesk"}}},"PublicChatDesk":{"type":"object","description":"Present only on OUR OWN chat (zinndigital.com and the product sites): the extra routes the launcher offers — a ticket form and links — and the Turnstile site key the ticket form must solve (`null` when Turnstile is not configured).","required":["ticket","person","turnstile_site_key","links","avatar_url","avatar_name"],"properties":{"ticket":{"type":"boolean"},"avatar_url":{"type":"string","format":"uri","description":"Zinn®, our Viking, as the chat's avatar (a square SVG, head and shoulders). Only our own chat carries it, because only our own chat carries `desk`: a customer's chat is their brand and never shows him."},"avatar_name":{"type":"string","description":"The avatar's name, `Zinn®` (a brand name, the same in every language)."},"turnstile_site_key":{"type":"string","nullable":true},"person":{"type":"boolean","description":"Whether the launcher offers \"Talk to a person\" now — the office-hours setting (`getAdminLiveChatHours`, default Off all day). False hides the option."},"turnstile_frame":{"type":"string","format":"uri","nullable":true,"description":"The challenge page to frame for THIS page (`getPublicChatChallenge`), preferred over rendering `turnstile_site_key` directly so the ticket form works on every site the chat is allowed on (Q272). `null` when no site key is configured."},"links":{"type":"array","items":{"type":"object","required":["key","url"],"properties":{"key":{"type":"string","enum":["kb","pricing","status"]},"url":{"type":"string","format":"uri"}}}}}},"PublicChatMessageCreate":{"type":"object","required":["message"],"properties":{"message":{"type":"string","maxLength":4000},"page_url":{"type":"string"},"page_title":{"type":"string"},"referrer":{"type":"string"},"locale":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"attr":{"type":"string","maxLength":2000,"description":"First message only: the `zinn_attr` cookie (`k=v&k=v`) or the page's query string. Only allow-listed campaign keys are kept (the utm_ keys, gclid, ...); shown to staff only."}}},"PublicChatStarted":{"allOf":[{"$ref":"#/components/schemas/PublicChatThread"},{"type":"object","required":["conversation_id","visitor_token"],"properties":{"conversation_id":{"type":"string","format":"uuid"},"visitor_token":{"type":"string","description":"Returned ONCE and never again. A bearer secret — the only thing between one visitor and another's transcript on the same site — presented afterwards in `X-Zinn-Chat-Token`, never in a query string."}}}]},"PublicChatThread":{"type":"object","required":["state","cursor","poll_after_ms","messages"],"properties":{"state":{"type":"string","enum":["ai","waiting","open","offline","closed"]},"cursor":{"type":"integer"},"poll_after_ms":{"type":"integer","description":"How long the widget should wait before asking again. Decided by the SERVER on every response, because a cadence baked into the widget is cached on somebody else's site behind somebody else's CDN and could never be changed."},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ChatMessage"}}}},"PublicChatTicketCreate":{"type":"object","required":["email","message"],"properties":{"email":{"type":"string","format":"email","maxLength":254},"name":{"type":"string","maxLength":200},"subject":{"type":"string","maxLength":200},"message":{"type":"string","maxLength":20000},"turnstile_token":{"type":"string","maxLength":2048},"deflection_id":{"description":"The AI answer shown first (`answerPublicChatTicket`), counted in the support stats.","oneOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]},"website":{"type":"string","description":"A honeypot. Leave empty; a filled one is accepted and discarded."}}},"PublicChatTicketCreated":{"allOf":[{"$ref":"#/components/schemas/PublicChatThread"},{"type":"object","required":["reference"],"properties":{"reference":{"type":"string","description":"The ticket's public reference (`ZT-XXXXXX`), also e-mailed to the visitor."}}}]},"PublicCheckoutRequest":{"type":"object","required":["cart_token","email","billing"],"properties":{"cart_token":{"type":"string","maxLength":128},"email":{"type":"string","format":"email","maxLength":254},"password":{"type":"string","minLength":12,"maxLength":128,"description":"Optional. Omit it and the account is created without a credential, so the customer sets one through the identity provider's own verified flow — which is the safer default, because it proves the inbox before granting a password."},"name":{"type":"string","maxLength":200},"locale":{"type":"string","maxLength":12},"turnstile_token":{"type":"string","maxLength":2048,"description":"Q114: the Cloudflare Turnstile token from the sign-up form's challenge (site key from `GET /v1/public/quotes/form`). Demanded once the `signup` human-check surface is on; a replay of an already-converted cart is not asked again (tokens are single-use)."},"billing":{"$ref":"#/components/schemas/PublicBilling"},"registrant":{"allOf":[{"$ref":"#/components/schemas/Registrant"}],"description":"Who the basket's domains are registered to. Optional on the wire — a basket with no domain needs none — but **required whenever the basket holds a domain**: without it the call is refused `422 REGISTRANT_REQUIRED` before any account, organization or order is created. It becomes the new organization's default registrant."},"registry_data":{"type":"object","description":"Q10 — `domain_name` → the fields that domain's registry demands beyond the registrant (`getTldRequirements` lists them per extension: ID / tax / company numbers, `.us` nexus, `.ca` legal type, registry acceptances …). Every `domain_register` / `domain_transfer` line is checked against its extension BEFORE anything is placed; a missing or invalid value is `422 REGISTRY_DATA_REQUIRED` with one `details[]` entry per problem (`domain`, `field`, `code`). Keys an extension does not declare are dropped. Write-only: never echoed on an order.","writeOnly":true,"additionalProperties":{"$ref":"#/components/schemas/RegistryData"}},"news_opt_in":{"type":"boolean","description":"The UNTICKED \"Send me Zinn® news\" box at sign-up / checkout (s1014 DOUBLEOPTIN, docs/1052 §7j). `true` sends ONE confirmation e-mail with a signed link; nothing is marketing until it is clicked (double opt-in). Omitted means `false`. No schema `default`, for the reason `marketing_opt_out` gives."},"news_source":{"type":"string","enum":["signup","checkout"],"description":"Where the box was ticked, for the consent record. Omitted means `checkout`."},"news_wording":{"type":"string","maxLength":32,"description":"The version of the sentence shown beside the box (`news-v1`), for the consent record. An unknown version records no request."},"marketing_opt_out":{"type":"boolean","description":"\"Don't email me offers and tips\" — the marketing opt-out offered at collection (soft opt-in, PECR reg. 22(3); owner ruling 2026-08-26). `true` records the same suppression a one-click unsubscribe does for the account this checkout creates. OPTIONAL: omitted means `false` (we may send marketing) — the server applies that default. ⛔ No schema `default` here: the generated TS types turn a defaulted property into a REQUIRED one, which broke every existing caller of this public endpoint (marketplace-web build, 2026-10-14, #9576)."},"promo_code":{"type":"string","maxLength":64,"description":"A hosting/SEO-tool coupon typed on the public checkout (docs/1311), e.g. a partner's code. Checked before any account exists; a code that cannot apply is a `422` with `details[0].field = promo_code` and `details[0].code` naming why. The saving is taken off the first billing period of each eligible line of the placed order."},"expected_total_minor":{"type":["integer","null"],"format":"int64","minimum":0,"description":"The order total (tax included, minor units) the checkout page displayed. When sent and the placed order would total anything else, checkout refuses `422` with `details[0].code = TOTAL_CHANGED` before any order is placed, and nothing is charged: the visitor is shown the new total and confirms again (docs/1311).","example":7999},"email_warning_accepted":{"type":"boolean","description":"MAILQUOTA (owner ruling 2026-11-11). The buyer was told their inbox is full (`422`, `details[0].code = EMAIL_MAILBOX_FULL`) and chose \"Continue anyway\": with `true` the checkout goes ahead with this address and the result carries `email_warning`. Absent or `false`, a full inbox answers the `422` and nothing is created."},"accept_refund_terms":{"type":"boolean","description":"The customer's EXPRESS agreement that **refunds are issued as Zinn® credit** on their account, not to the original payment method (owner ruling 2026-10-26; Consumer Contracts Regulations 2013 reg 34(6)). A tick box on every sign-up form, unticked by default. Without `true` the checkout is refused `422 REFUND_TERMS_REQUIRED` before any account exists; with it the agreement is recorded against the organisation created. ⛔ No schema `default` (see `marketing_opt_out`)."},"attribution":{"type":"object","additionalProperties":{"type":"string","maxLength":400}}}},"PublicCheckoutResult":{"type":"object","required":["order_id","org_id","next","currency","subtotal_minor","tax_minor","total_minor"],"properties":{"order_id":{"$ref":"#/components/schemas/Uuid"},"org_id":{"allOf":[{"$ref":"#/components/schemas/Uuid"}],"description":"The organization created by this call — the customer's new tenant."},"next":{"type":"string","enum":["payment","done"],"description":"What the client should do next. `payment` — the order exists and is `pending_payment`; nothing has been charged. `done` — the order totals **zero** and there is nothing to charge, so the customer is finished: this is what a free trial returns (owner ruling 2026-08-09 — a trial takes no card and starts immediately). It is keyed on the order TOTAL, not on the trial flag, because zero is zero however it got there and a payment step for nothing is a payment step for nothing."},"currency":{"type":"string","description":"ISO 4217 code of the placed order."},"subtotal_minor":{"type":"integer","description":"The order's net amount, in minor units."},"tax_minor":{"type":"integer","description":"The tax computed for `billing.country`, in minor units. A guest basket has no country, so this is the first moment the tax exists — show it."},"total_minor":{"type":"integer","description":"What the order owes, tax included, in minor units. ⛔ Display THIS, never the basket total, which is pre-tax (D25043)."},"email_warning":{"description":"Present (non-null) when the order went through with `email_warning_accepted`: the customer's inbox is full, so the confirmation e-mail may bounce until they clear it.","oneOf":[{"$ref":"#/components/schemas/EmailWarning"},{"type":"null"}]}}},"PublicComputeAddOn":{"type":"object","required":["code","kind","applies_at","is_free","prices"],"additionalProperties":false,"description":"One machine add-on as the public site shows it (`listCatalogComputeAddOns`). Sell prices only, in every currency the row is stored in.","properties":{"code":{"type":"string","description":"Stable key (`managed` is managed server care, `cloudlinux`, `plesk_web_pro` …)."},"kind":{"type":"string","description":"The add-on family (`managed`, `software`, …)."},"applies_at":{"type":"string","description":"When the add-on takes effect (at order or on a running machine)."},"is_free":{"type":"boolean"},"prices":{"type":"array","description":"The stored monthly price per currency, in minor units (CLAUDE.md §2.8).","items":{"type":"object","required":["currency","amount_minor"],"additionalProperties":false,"properties":{"currency":{"type":"string","minLength":3,"maxLength":3},"amount_minor":{"type":"integer"}}}}}},"PublicComputeTier":{"type":"object","required":["plan_code","name","deploy_target","plan_version_id","prices","cores","ram_gb","disk_gb","bandwidth_tb"],"description":"One sellable machine size. **Every** cadence it is priced at travels with it, so a term picker can render both figures honestly without a network round trip on a radio button.\n\n⛔ The vendor's own spec token is deliberately absent and must stay absent: it is the platform's identifier for the machine, the cart resolves it server-side from `plan_code`, and a vendor-side identifier rendered to a customer is a margin leak.","properties":{"plan_code":{"type":"string","description":"The stable catalogue code — what `addPublicCartServer` takes."},"name":{"type":"string","description":"The customer-facing size name, e.g. \"Zinn® Cloud Medium\"."},"deploy_target":{"type":"string","description":"The compute target that builds this size — `aws_cloud` or `gcp_cloud`, our own accounts (W43-45). The per-data-centre `own_cloud` range is listed by `listCatalogOwnCloudCompute`, never here."},"plan_version_id":{"type":"string","format":"uuid","description":"The immutable plan VERSION this tier's prices were read from. Published for parity with `listCatalogPlans`; the public cart does not require it."},"prices":{"type":"array","description":"Every cadence this size is priced at, monthly first. A cadence absent here has no price row and must not be offered — choosing it would pass the configurator and `422` at add-to-basket.","items":{"$ref":"#/components/schemas/PublicComputeTierPrice"}},"cores":{"type":"integer","nullable":true,"description":"vCPU cores, or `null` when the catalogue does not state it. ⛔ Always **present** — this and the three below are declared unconditionally on the engine's serializer, so an unstated figure arrives as `null`, never as a missing key. A client renders \"not stated\"; it must never render `0`."},"ram_gb":{"type":["number","null"],"description":"Memory in GB, or `null` when the catalogue does not state it. ⛔ A **number**, not an integer: Google Cloud's Micro is 3.75 GB, and an `integer` here published it as `null` — so the size carried no memory line at all, and a spec renderer that drops absent segments showed cores, disk and bandwidth and nothing about RAM."},"disk_gb":{"type":"integer","nullable":true,"description":"Disk in GB, or `null` when the catalogue does not state it."},"bandwidth_tb":{"type":"integer","nullable":true,"description":"Monthly bandwidth in TB, or `null` when the catalogue does not state it."}}},"PublicComputeTierPrice":{"type":"object","required":["interval","amount_minor","currency"],"description":"One cadence a machine size is sold at. Integer minor units + an ISO currency code (CLAUDE.md §2.8).","properties":{"interval":{"type":"string","enum":["monthly","annual"]},"amount_minor":{"type":"integer","format":"int64"},"currency":{"$ref":"#/components/schemas/CurrencyCode"}}},"PublicDocumentTranslationSet":{"type":"object","required":["locale","documents"],"properties":{"locale":{"$ref":"#/components/schemas/LocaleCode"},"documents":{"type":"object","description":"`object_ref -> (field -> translated text)`. **Every `object_ref` the caller asked for is a key**, even when its inner object is empty — an omitted key would be indistinguishable from a document the caller forgot to request, which silently serves English. The field names are the ones the CMS walker (`cms/src/lib/snapshotKeys.ts`) assigns, so a consumer applies them with that same walker rather than by matching on shape.","additionalProperties":{"type":"object","additionalProperties":{"type":"string"}},"example":{"page:hosting":{"hero.title":"Jede Art zu hosten","title":"Hosting"},"page:pricing":{}}}}},"PublicDocumentTranslations":{"type":"object","required":["locale","object_ref","fields"],"properties":{"locale":{"$ref":"#/components/schemas/LocaleCode"},"object_ref":{"type":"string","description":"The document these fields belong to, echoed back.","example":"page:hosting"},"fields":{"type":"object","description":"`field -> translated text`, flat. The field names are the ones the CMS walker (`cms/src/lib/snapshotKeys.ts`) assigns when it collects a document's translatable leaves, so the consumer applies them with that same walker rather than by matching on shape. An empty object means the pipeline has not produced any `up_to_date` text for this document yet, which is a normal state and not an error.","additionalProperties":{"type":"string"},"example":{"hero.title":"Jede Art zu hosten","title":"Hosting"}}}},"PublicDomainSearchRequest":{"type":"object","required":["query"],"properties":{"query":{"type":"string","minLength":1,"maxLength":253,"description":"A base name (`acme`) checked across `tlds`, or one full FQDN (`acme.com`)."},"tlds":{"type":"array","maxItems":5,"description":"Extensions to check the base name against. **At most 5** — each miss is a paid registrar lookup made for an anonymous visitor, and asking for more is a `422`, not a truncated answer. Omit it (which is what the marketplace site does) and the base name is checked across the curated default set — **`.com` `.net` `.org` `.io` `.co`**, in that order. The default is a contract, not an implementation detail: it is inside the 5-extension limit by construction, so omitting `tlds` can never be rejected for asking too much.","items":{"type":"string","maxLength":63}}}},"PublicFootprintCheck":{"type":"object","required":["token","state","sites_count","reachable_count","risks","risk_count","good_count","sites","started_at"],"properties":{"token":{"type":"string","description":"Read the check back with this."},"state":{"type":"string","enum":["running","done","failed"]},"score":{"type":"integer","nullable":true,"minimum":0,"maximum":100,"description":"100 means nothing public ties the sites together. `null` until done."},"grade":{"type":"string","description":"A to E; empty until done."},"sites_count":{"type":"integer"},"reachable_count":{"type":"integer"},"risks":{"type":"object","required":["critical","high","medium","low"],"description":"How many things to look at, by how strongly each ties the sites together.","properties":{"critical":{"type":"integer"},"high":{"type":"integer"},"medium":{"type":"integer"},"low":{"type":"integer"}}},"risk_count":{"type":"integer"},"good_count":{"type":"integer","description":"Things checked and found clear."},"sites":{"type":"array","items":{"type":"object","required":["domain","measured","reachable"],"properties":{"domain":{"type":"string"},"measured":{"type":"boolean"},"reachable":{"type":"boolean"}}}},"started_at":{"type":"string","format":"date-time"},"finished_at":{"type":"string","format":"date-time","nullable":true}}},"PublicFootprintCheckAvailability":{"type":"object","required":["enabled","max_sites"],"properties":{"enabled":{"type":"boolean","description":"Whether a free check can be started right now."},"max_sites":{"type":"integer","description":"How many sites one free check may name."}}},"PublicFootprintCheckCreate":{"type":"object","required":["domains"],"properties":{"domains":{"type":"array","minItems":1,"maxItems":5,"items":{"type":"string","maxLength":300},"description":"One to five public site names or URLs. Each is normalised to its bare host."}}},"PublicHostingRegion":{"type":"object","required":["slug","city","country"],"additionalProperties":false,"properties":{"slug":{"type":"string","example":"nuremberg"},"city":{"type":"string","example":"Nuremberg"},"country":{"type":"string","example":"DE"}}},"PublicMessageCatalogue":{"type":"object","required":["locale","messages"],"properties":{"locale":{"$ref":"#/components/schemas/LocaleCode"},"messages":{"type":"object","description":"The catalogue, **nested** — `nav.link.pbn` arrives as three levels of object, not as a dotted key — because the consumer is `next-intl`, which reads this shape directly. It is the same shape as the committed `marketplace-web/messages/<locale>.json`, and it must stay so: the site merges one over the other, and a flat response would not fail, it would silently render every string in English.\n\nValues are always strings; the nesting depth is whatever the key implies. An empty object means the pipeline has not produced any `up_to_date` string for this locale yet, which is a normal state and not an error.","additionalProperties":true,"example":{"nav":{"link":{"pbn":"Footprint-Free","hosting":"Hosting"}},"hero":{"title":"Jede Art zu hosten"}}}}},"PublicNameserverCheck":{"type":"object","description":"The public instruction card for one domain, plus a live reading of its delegation. The unauthenticated twin of `RegistrarGuide`, which serves the same card to a signed-in customer for a domain the platform already holds.","additionalProperties":false,"required":["fqdn","slug","registrar","panel_url","self_serve","locked","expected","observed","outcome","recheck_after_seconds"],"properties":{"fqdn":{"type":"string","description":"The domain as we normalised it — lower-cased, trailing dot removed."},"slug":{"type":"string","enum":["godaddy","namecheap","porkbun","cloudflare","squarespace","namecom","gandi","spaceship","namesilo","hostinger","ovh","dynadot","ionos","generic"],"description":"Which instruction set to render. ⛔ A slug, never step text — the client supplies its own localized steps, because step text returned from an API cannot go through the translation pipeline. `generic` is a real answer covering every registrar on earth, not a failure to identify one."},"registrar":{"type":"string","nullable":true,"description":"The registrar exactly as the registry names it, or `null` when none was published. ⛔ Never inferred from `slug`."},"panel_url":{"type":"string","nullable":true,"format":"uri","description":"A deep link into that registrar's own nameserver screen, where known."},"self_serve":{"type":"boolean","description":"Can we make the change for the customer with an API key they supply? Derived from which delegation adapters exist, never stated per registrar."},"locked":{"type":"boolean","description":"The domain cannot be delegated anywhere else — true for Cloudflare Registrar, whose domains use Cloudflare's nameservers by design. ⛔ This is a STATE, not a failure, and it is not the same as `self_serve: false`: plenty of registrars we cannot automate can still be changed by hand, and those two need opposite copy."},"expected":{"type":"array","items":{"type":"string"},"description":"The nameservers to enter at the registrar. ⛔ Derived per request from the platform's own assignment, never written into card content — a hostname typed into a page is correct on the day it is written and silently wrong after any DNS change, with nothing to go red."},"observed":{"type":"array","items":{"type":"string"},"description":"What the domain points at right now — public DNS where it answered, the registry's record otherwise. Empty means the reading was positive and there was nothing there; it does **not** mean the reading failed. See `outcome`."},"outcome":{"type":"string","enum":["delegated","propagating","not_delegated","unknown"],"description":"What we established. `delegated` = done. `propagating` = the registry has our pair and DNS has not caught up; the customer did it right and must simply wait. `not_delegated` = a real reading that it points elsewhere or nowhere. `unknown` = we could not find out. ⛔ `unknown` is not `not_delegated` and `propagating` is not a failure."},"recheck_after_seconds":{"type":"integer","nullable":true,"description":"Roughly how long to wait before checking again, or `null` when there is nothing to wait for. A hint about our own interface, not a claim about DNS propagation."}}},"PublicNewsPreferencesEnvelope":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["email","status","locale"],"properties":{"email":{"type":"string","description":"The address","masked (`r***@example.com`).":null},"status":{"type":"string","enum":["pending","confirmed","unsubscribed"]},"locale":{"type":"string"}}}}},"PublicNewsSubscribe":{"type":"object","required":["email","wording_version"],"properties":{"email":{"type":"string","format":"email","maxLength":320},"locale":{"type":"string","maxLength":16},"source":{"type":"string","enum":["footer","newsletter_page"]},"source_page":{"type":"string","maxLength":500},"wording_version":{"type":"string","enum":["news-v1"]},"turnstile_token":{"type":"string","maxLength":4096},"website_confirm":{"type":"string","maxLength":500,"description":"The honeypot - a person leaves it empty."}}},"PublicOwnCloudComputePrice":{"type":"object","required":["interval","amount_minor","currency"],"description":"The cheapest figure a Zinn® Private Cloud size is sold at, at one cadence.","properties":{"interval":{"type":"string","description":"The billing cadence, e.g. `monthly` or `annual`."},"amount_minor":{"type":"integer","format":"int64","description":"Integer minor units (§2.8), the **minimum** across every data centre this size is priced in at this cadence."},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO 4217 code."}}},"PublicOwnCloudComputeTier":{"type":"object","required":["plan_code","name","cores","ram_gb","disk_gb","bandwidth_tb","from_prices","locations","overage_per_tb","bandwidth_tb_by_location","alternative"],"description":"One **Zinn® Private Cloud** size — the range we source ourselves — as a logged-out visitor may read it.\n\n⛔⛔ **Every figure on this object is a MINIMUM across data centres**, which is what makes `from_prices` a different field from `PublicComputeTier.prices` rather than the same one under another name. On this range a size has no single price, so there is no honest way to render one number without the word *from* beside it.\n\n⛔ `plan_version_id` and `deploy_target` are deliberately absent, unlike the sibling schema. Both exist there to let an anonymous basket resolve a purchase; nothing on this range can be bought anonymously (verification precedes a first machine), so publishing them would imply a checkout that does not exist.","properties":{"plan_code":{"type":"string","description":"The stable catalogue code for the size."},"name":{"type":"string","description":"The customer-facing size name, e.g. \"Zinn® Private Cloud Standard 4\"."},"cores":{"type":"integer","nullable":true,"description":"vCPU cores, or `null` when the catalogue does not state it."},"ram_gb":{"type":["number","null"],"description":"Memory in GB, or `null` when unstated. A **number**, for the reason `PublicComputeTier.ram_gb` records: an `integer` here silently drops a fractional size to `null`."},"disk_gb":{"type":"integer","nullable":true,"description":"Disk in GB, or `null` when the catalogue does not state it."},"bandwidth_tb":{"type":"integer","nullable":true,"description":"Monthly bandwidth in TB, or `null` when the catalogue does not state it."},"from_prices":{"type":"array","description":"The **cheapest** figure this size is sold at, one entry per cadence. ⛔ Not \"the price\": the dearest data centre can cost over 50% more, so a client that renders one of these without the word *from* is publishing a figure most orders cannot be placed at. ⚖️ Owner ruling 2026-11-10 (OWNERANS1110): the cheapest LIST price over every city the size is offered in, EVEN WHEN that city is sold out now, so the figure does not move with supplier stock; checkout still sells only cities in stock.","items":{"$ref":"#/components/schemas/PublicOwnCloudComputePrice"}},"locations":{"type":"array","description":"The cities this size is **priced** in, as our own slugs (`falkenstein`, `singapore`) — never a supplier zone token. ⛔ Priced is not the same as buildable: stock is settled live at order time, so a client must not present this as availability. A city we have no public words for is omitted rather than published as a vendor key.","items":{"type":"string"}},"overage_per_tb":{"type":"array","description":"⚖️ Owner decision D73 (2026-10-08): what one TB of traffic **beyond the included amount** costs in each city, in USD — twice the network provider's published rate, read from the bandwidth ladder the meter bills from, so the page and the invoice are one figure. A city the ladder does not price is absent, never `0`. Charged automatically at thresholds, never in advance.","items":{"$ref":"#/components/schemas/PublicOwnCloudOverage"}},"bandwidth_tb_by_location":{"type":"array","description":"⚖️ Q342 (2026-10-08): the traffic this size INCLUDES each month in each city, in TB of 2^40 bytes — read from the network provider's own included-traffic figure for this machine type there, which is exactly where `overage_per_tb` starts to be billed (e.g. 20 TB in Europe and 1 TB in Singapore for the same VPS size). Empty when the provider's rate card cannot be read — never a guessed figure. `bandwidth_tb` is the single legacy figure and is not the allowance per city.","items":{"$ref":"#/components/schemas/PublicOwnCloudIncluded"}},"unmetered_bandwidth":{"type":"boolean","description":"⚖️ Owner ruling 2026-11-04 (1104#42): `true` when this size is a dedicated (bare-metal) server in every city it sells in — such a server includes UNLIMITED bandwidth and is never charged for traffic, so `bandwidth_tb` is `null` and `overage_per_tb` is empty. Decided by the same zone test the bandwidth meter uses to skip a dedicated box, so \"unlimited\" is published exactly where nothing is billed. Always `false` on a cloud size, which is metered."},"sold_out":{"type":"boolean","description":"`true` only when the request asked `include_sold_out=true` and the stock watch holds this size sold out: its prices are real, but no data centre can build it now, so it is not orderable. Always `false` on the default list, which omits such sizes."},"alternative":{"description":"s1014 AIREGIONS: on a `sold_out` size, the plan a visitor can order now instead (same product line, GPU only for GPU, closest size, matched by the stock watch). `null` on a size that is on sale, or when nothing comparable is available.","oneOf":[{"type":"null"},{"type":"object","required":["plan_code","name"],"additionalProperties":false,"properties":{"plan_code":{"type":"string"},"name":{"type":"string"}}}]}}},"PublicOwnCloudIncluded":{"type":"object","required":["location","tb"],"additionalProperties":false,"description":"The monthly traffic one size includes in one city; overage starts above it.","properties":{"location":{"type":"string","description":"Our own city slug (`falkenstein`, `singapore`), never a supplier zone token."},"tb":{"type":"number","description":"Terabytes (2^40 bytes) included per month."}}},"PublicOwnCloudOverage":{"type":"object","required":["location","amount_minor","currency"],"additionalProperties":false,"description":"The price of one TB of traffic beyond the included amount, in one city.","properties":{"location":{"type":"string","description":"Our own city slug (`falkenstein`, `singapore`), never a supplier zone token."},"amount_minor":{"type":"integer","format":"int64","description":"Integer minor units per TB (§2.8)."},"currency":{"type":"string","minLength":3,"maxLength":3}}},"PublicProposal":{"type":"object","required":["reference","status","revision","expired","answerable","labels","history"],"properties":{"reference":{"type":"string"},"status":{"$ref":"#/components/schemas/ProposalStatus"},"revision":{"type":"integer"},"expired":{"type":"boolean"},"answerable":{"type":"boolean"},"document":{"type":["object","null"],"description":"The frozen revision the recipient reads — title, message, lines, totals.","additionalProperties":true},"invoice":{"oneOf":[{"$ref":"#/components/schemas/ProposalInvoice"},{"type":"null"}]},"project":{"type":["object","null"],"description":"The project room — cards, messages and files — once paid.","additionalProperties":true},"history":{"type":"array","items":{"$ref":"#/components/schemas/ProposalEvent"}},"locale":{"type":"string"},"direction":{"type":"string","enum":["ltr","rtl"]},"issuer_name":{"type":"string"},"labels":{"type":"object","additionalProperties":{"type":"string"}}}},"PublicSupportAnswer":{"type":"object","required":["deflection_id","answer","articles"],"properties":{"deflection_id":{"$ref":"#/components/schemas/Uuid"},"answer":{"$ref":"#/components/schemas/TicketDeflectionAnswer"},"articles":{"type":"array","description":"Published help articles matching the question, in the visitor's language.","items":{"type":"object","required":["slug","title"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"slug":{"type":"string"},"title":{"type":"string"},"url":{"type":"string"}}}}}},"PublicSupportDeflectRequest":{"type":"object","required":["question","surface"],"properties":{"question":{"type":"string","maxLength":8000},"surface":{"type":"string","enum":["public","plugin","chat"]},"locale":{"type":"string","maxLength":20},"product":{"type":"string","maxLength":60},"category":{"type":"string","maxLength":40}}},"PublicTldPriceRow":{"type":"object","description":"One catalogue row as an anonymous visitor sees it, and since #845 retired `listTldPricing` the only public projection of one. It is a **superset** of the authenticated `TldPrice` row rather than a reuse of it: the `/[locale]/domains/{tld}` landing family is generated from this response, so a row carries the registry policy a per-TLD page has to state in prose. The registrar wholesale is never present, on any field.","required":["tld","sellable","is_premium","category","popularity","privacy_supported","restore_supported","idn_supported","transfer_grants_year","transfer_grants_year_source","transfer_supported","requires_local_presence","local_presence_available","eligible_countries","min_years","max_years","default_years"],"properties":{"tld":{"type":"string","description":"The label with no leading dot.","example":"co.uk"},"register":{"anyOf":[{"$ref":"#/components/schemas/MoneyAmount"},{"type":"null"}],"description":"First-year registration, USD. `null` when the registrar does not price the operation — never `0`, which on a price table is a false quote rather than a missing value."},"renew":{"anyOf":[{"$ref":"#/components/schemas/MoneyAmount"},{"type":"null"}]},"transfer":{"anyOf":[{"$ref":"#/components/schemas/MoneyAmount"},{"type":"null"}]},"sellable":{"type":"boolean","description":"All three operations are priced, so this row can be quoted end to end. Stated once here rather than re-derived by every consumer."},"is_premium":{"type":"boolean","description":"Priced live per name by the registry, so the table price is indicative."},"category":{"type":"string","enum":["gtld","new_gtld","cctld","sponsored"]},"popularity":{"type":"integer","minimum":0,"description":"Ranking key — higher is more popular, 0 is unranked. Never a claim."},"privacy_supported":{"type":"boolean"},"restore_supported":{"type":"boolean"},"idn_supported":{"type":"boolean","description":"Whether the registry accepts internationalised (non-ASCII) labels."},"transfer_grants_year":{"type":["boolean","null"],"description":"Whether an inbound transfer ADDS a year to the expiry. ⛔ `null` means **unknown, not \"no\"**: ICANN's Transfer Policy makes this true for every gTLD, but each country registry sets its own rule (`.uk` and `.de` keep the existing expiry, `.co` and `.io` add a year) and we hold no source for most of them. Render the \"+1 year\" line only on `true` — rendering `null` as a free year is a promise that will not be kept. `transfer_grants_year_source` says which rung answered, so `null` is distinguishable from a stated `false`."},"transfer_grants_year_source":{"type":"string","enum":["icann_gtld_policy","registrar_feed","registry_policy_unknown"],"description":"Where `transfer_grants_year` came from. `registrar_feed` = a registrar stated it for this extension; `icann_gtld_policy` = derived from the gTLD registry class; `registry_policy_unknown` = nobody has told us, so the value is `null`."},"transfer_supported":{"type":"boolean","description":"Whether an inbound transfer is possible at all on this extension. A transfer promotion has nothing to offer where this is `false`; `transfer` (the price) and `sellable` say whether it can also be quoted."},"requires_local_presence":{"type":"boolean","description":"The registry demands a local presence or trustee service beyond a contact address — a chargeable extra, not a refusal."},"local_presence_available":{"type":"boolean","description":"A paid registry trustee (local-presence service) is sold for this extension: the registrar offers one AND a priced row exists. `false` means no trustee may be claimed on a page about it; `requires_local_presence` alone does not mean one can be bought."},"eligible_countries":{"type":"array","description":"ISO-3166 alpha-2 countries a registrant must be in. **Empty means anyone, anywhere** — it is not \"unknown\". A checkout that ignores this sells a name the registry rejects after the money has moved.","items":{"type":"string","minLength":2,"maxLength":2}},"min_years":{"type":"integer","minimum":1},"max_years":{"type":"integer","minimum":1},"default_years":{"type":"integer","minimum":1},"related_kind":{"anyOf":[{"type":"string","enum":["brand_protection","regional","similar","popular"]},{"type":"null"}],"description":"Why this extension is offered beside the one that was searched. Present and non-null only on a `related` row. A machine value — every surface maps it to its own localized sentence."}}},"PublicTldPricingPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicTldPriceRow"}},"page":{"$ref":"#/components/schemas/PageMeta"},"summary":{"$ref":"#/components/schemas/PublicTldPricingSummary"},"related":{"type":"array","description":"Neighbour extensions worth offering beside an exact-TLD `q`. Absent when `q` is empty, is not an extension we sell, or on any page but the first.","items":{"$ref":"#/components/schemas/PublicTldPriceRow"}}}},"PublicTldPricingSummary":{"type":"object","description":"Whole-collection facts, counted rather than derived from the page in hand. First page only.","required":["currency","active","matched"],"properties":{"currency":{"type":"string","description":"The currency every price in this response is expressed in (USD)."},"active":{"type":"integer","minimum":0,"description":"How many extensions we sell. **This is the number a \"search across N extensions\" line must read.** A constant in a page template is a public claim that goes stale the first time the catalogue sync deactivates a registry."},"matched":{"type":"integer","minimum":0,"description":"How many match the current `q`/`category`. Equals `active` when unfiltered."}}},"PublicWhoisAnswer":{"type":"object","description":"One public WHOIS lookup. ⛔ `state` carries the meaning; `registry` is only ever populated when `state` is `registered`.","additionalProperties":false,"required":["fqdn","state","registry"],"properties":{"fqdn":{"type":"string","description":"The normalised name that was looked up (lower-cased, no trailing dot)."},"state":{"type":"string","enum":["registered","not_registered","unknown"],"description":"`registered` — the registry returned a record. `not_registered` — the registry answered `404`. `unknown` — we could not find out (no RDAP service for the extension, a timeout, a rate limit, an unreadable body). ⛔ `unknown` is not `not_registered`."},"registry":{"allOf":[{"$ref":"#/components/schemas/RegistryProfile"}],"nullable":true,"description":"The registry record, or `null` for any state other than `registered`."}}},"PurgeSiteCacheRequest":{"type":"object","description":"An empty or absent `path` means \"everything\", which is the common case.","additionalProperties":false,"properties":{"path":{"type":"string","maxLength":1024,"description":"One path to drop, relative to the site root. Omit it, or send `\"\"`, to clear the whole cache.","example":"/wp-content/themes/zinn/style.css"}}},"PushDevice":{"type":"object","description":"A phone registered for alerts by the phone app (ADR 0042). The push token itself is never returned.","required":["id","connection_id","installation_id","platform","quiet_enabled","quiet_start","quiet_end","health","last_seen_at","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"connection_id":{"type":"string","format":"uuid"},"installation_id":{"type":"string"},"platform":{"type":"string","enum":["ios","android"]},"device_name":{"type":"string"},"os_version":{"type":"string"},"app_version":{"type":"string"},"locale":{"type":"string"},"time_zone":{"type":"string"},"quiet_enabled":{"type":"boolean"},"quiet_start":{"type":"integer","minimum":0,"maximum":1439},"quiet_end":{"type":"integer","minimum":0,"maximum":1439},"health":{"type":"string"},"last_delivery_at":{"type":"string","format":"date-time","nullable":true},"last_seen_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"QuoteChoice":{"type":"object","required":["value","label"],"description":"One dropdown option. ⛔ `label` is English: it is the engine's own enum label, and the public form renders its OWN translated label keyed on `value` (§2.19). The label here is for an API consumer that has no catalogue, never for a visitor.","properties":{"value":{"type":"string"},"label":{"type":"string"}}},"QuoteFormConfig":{"type":"object","required":["turnstile_site_key","max_attachments","max_attachment_bytes","accepted_types","project_types","budget_bands","timelines","contact_topics"],"description":"Everything the public quote and contact forms need to render themselves.","properties":{"turnstile_site_key":{"type":"string","nullable":true,"description":"The Cloudflare Turnstile site key, or `null` when no challenge is configured. ⛔ Public by construction — it ships in the page's HTML — which is why it is served rather than kept secret. ⛔ `null`, never `\"\"`: the client branches on it."},"max_attachments":{"type":"integer","description":"How many files one submission may carry."},"max_attachment_bytes":{"type":"integer","description":"The ceiling across the WHOLE request, not per file. Five files each inside the per-file cap is far more than an anonymous caller should be able to store."},"accepted_types":{"type":"array","items":{"type":"string"},"description":"The media types an attachment may be. An allow-list, never a block-list — a block-list is a claim that somebody thought of every dangerous format."},"project_types":{"type":"array","items":{"$ref":"#/components/schemas/QuoteChoice"}},"budget_bands":{"type":"array","items":{"$ref":"#/components/schemas/QuoteChoice"}},"timelines":{"type":"array","items":{"$ref":"#/components/schemas/QuoteChoice"}},"contact_topics":{"type":"array","description":"What a contact message may be about (W43-83).","items":{"$ref":"#/components/schemas/QuoteChoice"}}}},"QuoteRequestAccepted":{"type":"object","required":["reference","status","attachments_stored","attachments_refused"],"properties":{"reference":{"type":"string","description":"The short handle a human quotes back at us, e.g. `QR-2609-K7M3PX` for a quote or `CM-2609-K7M3PX` for a contact message. ⛔ Not sequential: a running number published to strangers leaks how much work we are winning, and nothing here needs one."},"status":{"type":"string"},"attachments_stored":{"type":"integer"},"attachments_refused":{"type":"string","nullable":true,"description":"Copy for the visitor when a file could not be attached, or `null`. ⛔ The enquiry was still accepted — see the endpoint description."}}},"QuoteRequestInput":{"type":"object","required":["name","email","description"],"description":"One enquiry from a stranger — a job they want priced (`kind: quote`) or a message (`kind: contact`). ⛔ `project_type` is required for a quote and `topic` for a contact message; the engine refuses either one missing with a `422` naming the field.","properties":{"kind":{"type":"string","enum":["quote","contact"],"default":"quote","description":"Which public form this came from."},"topic":{"type":"string","enum":["sales","support","billing","partnership","press","other"],"description":"Required when `kind` is `contact`; ignored otherwise."},"name":{"type":"string","maxLength":200},"email":{"type":"string","format":"email","maxLength":320},"description":{"type":"string","minLength":1,"maxLength":8000,"description":"What they need doing — the thing we actually price. ⛔ Bounded here as well as in the engine: a `TextField` has no length, and an operator has to READ this."},"project_type":{"type":"string","description":"The shape of the work, from `project_types`. Deliberately not the technology — a WordPress build and a bespoke application are quoted by different people on different lead times; \"PHP\" and \"Python\" are not, which is what `stack` is for."},"company":{"type":"string","maxLength":200},"phone":{"type":"string","maxLength":64},"country":{"type":"string","maxLength":2,"description":"ISO 3166-1 alpha-2."},"stack":{"type":"string","maxLength":200},"budget_band":{"type":"string","description":"A RANGE, never a figure. Somebody who has not been quoted does not have a number, and storing one invents a precision they never gave — which an operator then anchors their quote to. `unsure` is a first-class answer."},"timeline":{"type":"string"},"website_url":{"type":"string","maxLength":500,"description":"The site the job is about. ⛔ Optional and may be blank: a broken site is one of the commonest reasons to be here, and refusing the enquiry over a URL loses exactly the customer in most trouble."},"locale":{"type":"string","maxLength":12,"default":"en","description":"The language the form was filled in. ⛔ The confirmation is sent in it — without this a platform sold in 58 languages answers every enquiry in English, and nothing looks broken."},"source_page":{"type":"string","maxLength":255,"description":"Which page the form was submitted from — how we learn what converts."},"turnstile_token":{"type":"string","description":"Cloudflare's token. ⛔ Not marked required: whether it is needed is the engine's answer (is a secret configured?), not the schema's — hard-coding `required` would make an unconfigured environment reject every submission over a field its form does not render."},"website_confirm":{"type":"string","description":"⛔ Leave this empty. It is a honeypot, and it is documented rather than hidden because an SDK consumer that populated every string field would otherwise be refused with no way to find out why."}}},"Readiness":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["ready","not_ready"]},"reason":{"type":"string","enum":["database","warming"]},"warm":{"type":"integer","minimum":0,"description":"With `reason=warming`, how many of this instance's workers are warm."},"workers":{"type":"integer","minimum":1,"description":"With `reason=warming`, how many workers must be warm before it is ready."},"version":{"type":"string"},"database":{"type":"string","enum":["degraded"],"description":"With `status=ready`: the database has not answered this instance's latest check, but it answered within the readiness grace (45 s), so the instance stays in service through a shared blip such as a switchover (D50901)."}}},"RefundApproveInput":{"type":"object","description":"A staff approval. The refund is issued as Zinn® credit; `to_original_source` is the owner's audited override only.","properties":{"note":{"type":"string","maxLength":1000},"to_original_source":{"type":"boolean","description":"`true` sends this refund back to the original payment method — the owner only, with `override_reason`; anyone else is 403. Omitted means `false` (Zinn® credit)."},"override_reason":{"type":"string","maxLength":1000}}},"RefundDecisionInput":{"type":"object","description":"A staff approve/reject decision — an optional internal note.","properties":{"note":{"type":"string","maxLength":1000}}},"RefundEligibility":{"type":"object","description":"The refund policy's decision for an order (a preview, not stored).","required":["eligible","policy_class","requires_approval","auto_approved","amount","reason"],"properties":{"eligible":{"type":"boolean"},"policy_class":{"$ref":"#/components/schemas/RefundPolicyClass"},"requires_approval":{"type":"boolean"},"auto_approved":{"type":"boolean","description":"Eligible and needs no human — the money-back path issues immediately."},"amount":{"$ref":"#/components/schemas/MoneyAmount"},"reason":{"type":"string","description":"A customer-safe explanation of the decision."}}},"RefundPolicyClass":{"type":"string","description":"How the refund policy classified a request (captured at request time).","enum":["money_back","pro_rata","ineligible"]},"RefundRequest":{"type":"object","required":["id","org_id","order_id","status","policy_class","amount","to_wallet","reason","decided_by","decision_note","decided_at","refund_reference","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"org_id":{"$ref":"#/components/schemas/Uuid"},"order_id":{"$ref":"#/components/schemas/Uuid"},"status":{"$ref":"#/components/schemas/RefundRequestStatus"},"policy_class":{"$ref":"#/components/schemas/RefundPolicyClass"},"amount":{"$ref":"#/components/schemas/MoneyAmount"},"to_wallet":{"type":"boolean","description":"Where the refund went. `true` (every refund): issued as Zinn® credit to the account wallet. `false` only when the owner's override sent it back to the original payment method (owner ruling 2026-10-26)."},"reason":{"type":"string"},"decided_by":{"type":"string"},"decision_note":{"type":"string"},"decided_at":{"type":["string","null"],"format":"date-time"},"refund_reference":{"type":"string","description":"Set once the refund has been issued (its idempotency key)."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"RefundRequestCreate":{"type":"object","description":"Optional body for opening a refund request — the amount is server-decided.","properties":{"org_id":{"$ref":"#/components/schemas/Uuid"},"reason":{"type":"string","maxLength":1000},"to_wallet":{"type":"boolean","deprecated":true,"description":"Ignored. Refunds are issued as Zinn® credit to the account wallet (owner ruling 2026-10-26); the field is accepted so older clients are not refused. ⛔ No schema `default` (a defaulted property becomes REQUIRED in the generated TypeScript)."}}},"RefundRequestPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RefundRequest"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"RefundRequestStatus":{"type":"string","description":"A refund request's lifecycle state (docs/05 §4.13).","enum":["pending","auto_approved","approved","rejected"]},"Refusal":{"type":"object","description":"A refusal's message KEY and the values its sentence interpolates, so the surface that has the reader's locale renders it — `CLAUDE.md` §2.7/§2.19 (\"no hardcoded user-facing strings\", \"no English-only anything ever ships\").\n\n⭐ The seam is §57's, reused rather than reinvented: the engine decides a key plus parameters and the client renders `t(key, params)` from its own catalogue, exactly as it already does for `VendorFailure.message_key`. The engine does not know the reader's locale — a refusal is raised deep in a service, sometimes inside a Temporal activity with no request at all — so it must not try to translate.\n\n⛔ A key this client does not carry falls back to the envelope's English `message` rather than rendering raw, which is why a new engine key can never put `refusal.compute.someNewThing` on a customer's screen.","required":["key","params"],"properties":{"key":{"type":"string","description":"The catalogue key, `refusal.<area>.<thing>`. The AREA is the product the customer thinks they are using, not the Python module the sentence came from.","example":"refusal.compute.alreadyThatSize"},"params":{"type":"object","additionalProperties":{"type":"string"},"description":"The values the template interpolates, already stringified. ⛔ Strings, never numbers or dates: a value a customer must read AS a number or a date belongs in a key the surface formats for their locale, not in a parameter Python has already rendered one way for everybody.","example":{"label":"web-01"}}}},"Registrant":{"type":"object","required":["first","last","email","phone","street","city","postcode","country"],"description":"Who a domain is registered to — the ICANN registrant (docs/803). Validated as a registrar would: every field except `org_name` and `state` is required, `country` is ISO 3166-1 alpha-2, and `phone` must be international with its country code.","properties":{"first":{"type":"string","maxLength":128},"last":{"type":"string","maxLength":128},"org_name":{"type":"string","maxLength":200},"email":{"type":"string","format":"email","maxLength":254},"phone":{"type":"string","maxLength":32,"description":"International form with the country code (`+44 20 7946 0000`, `0044…` also accepted). Stored and returned as EPP `+CC.NUMBER` (`+44.2079460000`).","example":"+44.2079460000"},"street":{"type":"array","minItems":1,"maxItems":3,"items":{"type":"string","maxLength":255}},"city":{"type":"string","maxLength":128},"state":{"type":"string","maxLength":128,"description":"May be blank — most of the world has no state."},"postcode":{"type":"string","maxLength":32},"country":{"type":"string","minLength":2,"maxLength":2,"example":"GB"}}},"RegistrantEmailVerification":{"type":"object","description":"One domain whose registrant email address the registrar has not confirmed.","required":["domain_id","fqdn","email","state","deadline_at","checked_at","resent_at","resend_available_at","domains_sharing_email"],"properties":{"domain_id":{"$ref":"#/components/schemas/Uuid"},"fqdn":{"type":"string","maxLength":253},"email":{"type":"string","format":"email","maxLength":254,"description":"The address the registrar sent its confirmation link to."},"state":{"type":"string","enum":["pending","suspended"],"description":"`suspended`: the deadline passed and the registry has suspended the name."},"deadline_at":{"type":["string","null"],"format":"date-time","description":"When the registry suspends the name if the address is still unconfirmed."},"checked_at":{"type":"string","format":"date-time","description":"When the registrar was last asked."},"resent_at":{"type":["string","null"],"format":"date-time","description":"When you last asked for the email again, if you have."},"resend_available_at":{"type":["string","null"],"format":"date-time","description":"When the next resend is allowed; `null` when it is allowed now."},"domains_sharing_email":{"type":"integer","minimum":1,"description":"How many of your domains use this address, this one included. The registrar checks an address, not a domain, so one resend restarts the check on every one of them."}}},"RegistrantEmailVerificationList":{"type":"object","required":["items","count"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/RegistrantEmailVerification"}},"count":{"type":"integer"}}},"RegistrarAccount":{"type":"object","required":["connection_id","provider","vendor"],"properties":{"connection_id":{"$ref":"#/components/schemas/Uuid"},"provider":{"$ref":"#/components/schemas/ConnectionProvider"},"vendor":{"type":"string"},"account_login":{"type":"string","description":"What the registrar reported about the account when it was connected — a domain count at GoDaddy, the account name at Namecheap, the egress address Porkbun saw. Empty when the vendor exposes nothing useful."},"connected_at":{"type":"string","format":"date-time"}}},"RegistrarAccountRefresh":{"type":"object","required":["refused","vendor","seen","created","updated","retired"],"properties":{"refused":{"type":"string","description":"Empty on success. Otherwise a machine reason (`listing_failed`, `no_driver`) — and when it is set, **every count below is 0 and nothing was retired**, because a failure to read is not a change to the portfolio."},"vendor":{"type":"string"},"seen":{"type":"integer","description":"Domains the registrar listed."},"created":{"type":"integer"},"updated":{"type":"integer"},"retired":{"type":"integer","description":"Domains the account stopped listing, marked gone rather than deleted. ⛔ Shown to the customer, never swallowed: it is either a transfer they made or a key that lost access."}}},"RegistrarDomain":{"type":"object","required":["id","connection_id","provider","vendor","fqdn","state"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"connection_id":{"$ref":"#/components/schemas/Uuid"},"provider":{"$ref":"#/components/schemas/ConnectionProvider"},"vendor":{"type":"string","description":"The driver name behind the provider, e.g. `godaddy`."},"fqdn":{"type":"string","description":"The domain name, lower-cased and without a trailing dot."},"expires_at":{"type":"string","format":"date-time","nullable":true,"description":"⛔ `null` means the registrar did not state one, **never** \"expired\". A placeholder date here reads as \"expired 56 years ago\" to everything downstream."},"days_to_expiry":{"type":"integer","nullable":true,"description":"Whole days until expiry, or `null` when no expiry is known."},"registrar_status":{"type":"string","description":"The registrar's own word for the domain's state, verbatim and unmapped (`ACTIVE`, `EXPIRED`, `clientTransferProhibited`…). Empty when it said nothing."},"nameservers":{"type":"array","nullable":true,"items":{"type":"string"},"description":"The live delegation, or `null` when we have never read it. ⛔ `null` and `[]` are different answers — `[]` says the domain is delegated **nowhere**, which is a real and alarming state."},"expected_nameservers":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Where this name's site needs it to point, or `null` when there is no site and therefore no opinion. ⛔ An empty expectation is never rendered as drift."},"nameserver_drift":{"type":"boolean","description":"Whether the live delegation differs from `expected_nameservers`. `false` whenever either side is unknown — an alarming value invented from an absence sends a customer to fix a domain that is exactly right."},"auto_renew":{"type":"boolean","nullable":true,"description":"⛔ `null` means the registrar did not say, never \"off\"."},"locked":{"type":"boolean","nullable":true,"description":"Transfer lock. ⛔ `null` means the registrar did not say."},"state":{"$ref":"#/components/schemas/RegistrarDomainState"},"state_reason":{"type":"string","description":"A machine key for `state` (`expires_within_30_days`, `not_pointing_at_its_site`, `credential_rejected`, `rate_limited`…). ⛔ A client translates it; it is never rendered raw and it is never English prose composed by the engine."},"matched_domain_id":{"allOf":[{"$ref":"#/components/schemas/Uuid"}],"nullable":true,"description":"The platform `Domain` for the same name in the same org, when there is one."},"last_synced_at":{"type":"string","format":"date-time","nullable":true,"description":"When we last **successfully** read this domain. ⛔ `null` on a row that exists means it has been listed and never read in detail — not that it is new."}}},"RegistrarDomainList":{"type":"object","required":["items","total","accounts"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/RegistrarDomain"}},"total":{"type":"integer","description":"How many domains match **before** the page limit. ⛔ Compare it with `items.length` before telling a customer this is all of them."},"accounts":{"type":"array","items":{"$ref":"#/components/schemas/RegistrarAccount"},"description":"The linked accounts these domains came from — served here because an account with zero domains is a state the screen must render and a domain list cannot express."}}},"RegistrarDomainState":{"type":"string","enum":["ok","ns_drift","expiring","expired","gone","unknown"],"description":"**Our** verdict about a linked domain — deliberately not the registrar's status, which is carried separately and unmapped.\n\n`unknown` is a real state and must never be rendered as `ok`: \"we looked and all is well\" and \"we could not look\" are different facts and only the first is reassuring. A freshly imported domain is `unknown` until it has been read in detail, because two of the three registrars' account listings carry neither the expiry nor the delegation.\n\n`gone` means the account stopped listing it — sold, transferred away, or the API key's scope narrowed. The row is kept rather than deleted, so a domain that comes back returns rather than reappearing as a stranger."},"RegistrarGuide":{"type":"object","description":"How a customer changes this domain's delegation, keyed to the registrar the public registry says holds it.","additionalProperties":false,"required":["slug","registrar","panel_url","self_serve","locked","expected","nameservers"],"properties":{"slug":{"type":"string","enum":["godaddy","namecheap","porkbun","cloudflare","squarespace","namecom","gandi","spaceship","namesilo","hostinger","ovh","dynadot","ionos","generic"],"description":"Which instruction set to render. ⛔ A slug, never step text — a client supplies its own localized steps. `generic` is a real answer covering every registrar."},"registrar":{"type":"string","nullable":true,"description":"The registrar exactly as the registry names it, or `null` when none was published. ⛔ Never inferred from `slug`: showing a brand name the registry did not state would present our guess as the registry's statement."},"panel_url":{"type":"string","nullable":true,"format":"uri","description":"A deep link into that registrar's own nameserver screen, where known."},"self_serve":{"type":"boolean","description":"Can we make the change for the customer with an API key they supply? Derived from which delegation adapters exist, never stated per registrar."},"locked":{"type":"boolean","description":"The domain cannot be delegated anywhere else — true for Cloudflare Registrar. ⛔ A STATE, not a failure, and not the same as `self_serve: false`."},"expected":{"type":"array","items":{"type":"string"},"description":"The nameservers this domain should be set to. Resolved from the zone's own nameservers first, so a provider-assigned pair is reported rather than a fleet-wide constant."},"nameservers":{"type":"array","items":{"type":"string"},"description":"Where the registry says the domain delegates right now."}}},"RegistrationRoute":{"type":"object","required":["key","label_key","detail_key","locks_nameservers","supports_premium","supports_renew","supports_auth_code","available","unavailable_reason"],"description":"One way to buy a domain, and what that way costs the customer in freedom. The flags are derived from the registrar driver's advertised capabilities, never typed beside them, so a driver that gains or loses an endpoint moves this copy with it.","properties":{"key":{"$ref":"#/components/schemas/RegistrationRouteKey"},"label_key":{"type":"string","description":"An i18n message key. Never English — the console resolves it."},"detail_key":{"type":"string"},"locks_nameservers":{"type":"boolean","description":"The domain's DNS must stay with this registrar. True for Cloudflare, and it is the single most important thing to tell the buyer before they choose."},"supports_premium":{"type":"boolean"},"supports_renew":{"type":"boolean","description":"Whether a term can be bought on demand. `false` for Cloudflare, which has no renew endpoint at all — it renews on its own schedule against our card, and the platform bills the customer ahead of that."},"supports_auth_code":{"type":"boolean"},"available":{"type":"boolean","description":"Whether this organisation can use the route right now."},"unavailable_reason":{"type":"string","description":"An i18n key explaining why not; empty when available. Unusable routes are returned greyed rather than filtered out — a one-option list is indistinguishable from a list whose second option failed to load."}}},"RegistrationRouteKey":{"type":"string","enum":["default","cloudflare"],"description":"Which registrar buys the name. `default` is the organisation's own registrar connection and behaves exactly as it always has. `cloudflare` is an additional, deliberately-chosen route: it is cheaper at wholesale, and it **locks the domain to Cloudflare nameservers** for as long as we hold it, which is why the customer picks it rather than a balancer picking for them."},"RegistrationRoutes":{"type":"object","required":["routes"],"properties":{"routes":{"type":"array","items":{"$ref":"#/components/schemas/RegistrationRoute"}}}},"RegistryData":{"type":"object","writeOnly":true,"description":"The fields one domain's registry demands, keyed by `TldRequirementField.key`; values are strings (`\"1\"` accepts a `check` field, dates are `YYYY-MM-DD`). Never returned.","additionalProperties":{"type":"string","maxLength":255}},"RegistryProfile":{"type":"object","required":["fqdn","checked_at","registrar","registrar_iana_id","registered_at","expires_at","last_changed_at","statuses","nameservers","dnssec","transfer_locked","lapsed"],"description":"A domain's public registry record, read over RDAP. The WHOIS card — and it answers for a domain registered at a registrar we hold no account with, which is the whole reason it is a separate resource from `Domain`.\n\n⛔⛔ **`null` means the registry did not publish the field.** It never means the domain lacks the thing. The two fields where that distinction has a victim are `transfer_locked` and `dnssec`: rendering either `null` as `false` tells a customer their domain is unprotected and sends them to change something that is already correct.\n\n⛔ Contact data is deliberately absent — see the endpoint description.","properties":{"fqdn":{"type":"string","maxLength":253,"description":"The name this record is about, normalised to lower case.","example":"ntcloudhosting.com"},"checked_at":{"type":"string","format":"date-time","description":"When we read the registry. Answers are cached for a few hours, so this is the age of the reading and not the time of the request."},"registrar":{"type":"string","nullable":true,"description":"The registrar of record, as the registry publishes it.","example":"Tucows Domains Inc."},"registrar_iana_id":{"type":"string","nullable":true,"description":"The registrar's IANA id — stable where the display name is not.","example":"69"},"registered_at":{"type":"string","format":"date-time","nullable":true,"description":"When the domain was first registered."},"expires_at":{"type":"string","format":"date-time","nullable":true,"description":"When the registration lapses. ⭐ This is the **registry's** date, not our billing date, and on a domain the customer renews elsewhere it is the only true one we have."},"last_changed_at":{"type":"string","format":"date-time","nullable":true,"description":"When the registry record last changed. A renewal, a nameserver edit or a lock change all move it, so it is a useful \"something happened\" marker and not a statement of what."},"statuses":{"type":"array","description":"The EPP status set, lower-cased as RDAP publishes it. An empty array means the registry published none — not that the domain has none.","items":{"type":"string","maxLength":64},"example":["client transfer prohibited","client update prohibited"]},"nameservers":{"type":"array","description":"The nameservers the **registry** holds. May legitimately differ from the public delegation mid-propagation — compare with `Delegation.nameservers`, which is what the internet actually answers.","items":{"type":"string","maxLength":253},"example":["ns1.ntcloudhosting.com","ns2.ntcloudhosting.com"]},"dnssec":{"type":"boolean","nullable":true,"description":"Whether the delegation is signed. `null` when the registry published no `secureDNS` block at all, which many do not."},"transfer_locked":{"type":"boolean","nullable":true,"description":"Whether a client transfer prohibition is set. `null` when no status set was published — ⛔ not `false`, for the reason in this schema's description."},"lapsed":{"type":"boolean","description":"Whether the registration is in a redemption or pending-delete window right now. Worth surfacing loudly: those windows are short, cost a fee to reverse, and end with the name being released."}}},"RenameCancelAccepted":{"type":"object","required":["site_id","domain","status"],"properties":{"site_id":{"$ref":"#/components/schemas/Uuid"},"domain":{"$ref":"#/components/schemas/Hostname","description":"The new domain the cancelled change was waiting for."},"status":{"type":"string","enum":["cancelling"],"description":"`cancelling` — the waiting change is undoing the new name's zones and will end; the site stays on its current address."}}},"RenameDnsRecord":{"type":"object","description":"The DNS record that makes the new name reach the site.","required":["type","name","value"],"properties":{"type":{"type":"string","enum":["A","AAAA"]},"name":{"$ref":"#/components/schemas/Hostname"},"value":{"type":"string","description":"The site's origin address."}}},"RenameDomainAccepted":{"type":"object","required":["site_id","new_domain","workflow_id","status"],"properties":{"site_id":{"$ref":"#/components/schemas/Uuid"},"new_domain":{"$ref":"#/components/schemas/Hostname"},"workflow_id":{"type":"string","description":"The Temporal workflow id running the rename saga (deterministic per site)."},"status":{"type":"string","enum":["accepted","waiting_for_dns","in_progress"],"description":"`accepted` — the saga started and switches now; `waiting_for_dns` — it waits for `dns_record` to be added, then switches on its own; `in_progress` — another change for this site is already past its DNS wait and finishes first."},"dns_record":{"$ref":"#/components/schemas/RenameDnsRecord"}}},"RenameDomainRequest":{"type":"object","required":["new_domain"],"properties":{"new_domain":{"allOf":[{"$ref":"#/components/schemas/Hostname"}],"description":"The site's new primary domain (FQDN)."},"keep_old_as_alias":{"type":"boolean","default":false,"description":"Keep serving the old domain as an alias of the site after the flip. Forced true when the old and new names share one registrable zone (`example.com` to `www.example.com`, or two names under one zone): dropping the old name there would tear down the zone the site has just moved into."}}},"RepoBranch":{"type":"object","required":["name","commit_sha"],"properties":{"name":{"type":"string"},"commit_sha":{"type":"string"}}},"ResellerAiClient":{"type":"object","additionalProperties":false,"required":["org_id","name","balance_micros","status"],"properties":{"org_id":{"$ref":"#/components/schemas/Uuid"},"name":{"type":"string"},"balance_micros":{"type":"integer","format":"int64","description":"The client's OWN AI credit, USD micros. Their money, not yours."},"status":{"type":"string"}}},"ResellerAiClientAdjustment":{"type":"object","additionalProperties":false,"required":["delta_micros","reason"],"properties":{"delta_micros":{"type":"integer","format":"int64","description":"Signed USD micros. Positive gives credit to the client, negative takes unspent credit back. Zero is refused — a ledger row that means nothing."},"reason":{"type":"string","maxLength":255,"description":"Why. Required, for the same reason a staff adjustment requires one: a movement of somebody's money with no stated cause is unanswerable three months later."}}},"ResellerAiClientAdjustmentResult":{"type":"object","additionalProperties":false,"required":["pool_balance_micros","client_balance_micros","typical_calls"],"properties":{"pool_balance_micros":{"type":"integer","format":"int64"},"client_balance_micros":{"type":"integer","format":"int64"},"typical_calls":{"type":"integer","description":"Roughly how many AI questions the client's new balance buys. An **illustration** — a long article costs many times a short question."}}},"ResellerAiCreditSettings":{"type":"object","additionalProperties":false,"required":["low_pool_threshold_micros","auto_buy_enabled"],"properties":{"low_pool_threshold_micros":{"type":"integer","format":"int64","minimum":0,"description":"`0` = derive it from what you allocate."},"auto_buy_enabled":{"type":"boolean","description":"Buy a pack from Zinn® automatically when your pool cannot cover a client's purchase. Off unless you turn it on — it charges your card with nobody watching."},"auto_buy_pack_code":{"type":"string","description":"Blank = the smallest pack that covers the shortfall, resolved when it fires."},"auto_buy_monthly_cap_micros":{"type":"integer","format":"int64","minimum":0,"description":"`0` = four of the chosen pack. A cooldown is not a ceiling."}}},"ResellerAiCreditSettingsResult":{"type":"object","additionalProperties":false,"required":["low_pool_threshold_micros","auto_buy_enabled","auto_buy_pack_code","auto_buy_monthly_cap_micros","is_low"],"properties":{"low_pool_threshold_micros":{"type":"integer","format":"int64"},"auto_buy_enabled":{"type":"boolean"},"auto_buy_pack_code":{"type":"string"},"auto_buy_monthly_cap_micros":{"type":"integer","format":"int64"},"is_low":{"type":"boolean"}}},"ResellerAiCredits":{"type":"object","additionalProperties":false,"required":["pool","wholesale_discount_bps","packs","clients"],"properties":{"pool":{"$ref":"#/components/schemas/ResellerAiPool"},"wholesale_discount_bps":{"type":"integer","description":"Your discount off Zinn®'s list price for AI credit, in basis points. Separate from your hosting discount — different product, different margin."},"packs":{"type":"array","items":{"$ref":"#/components/schemas/ResellerAiPack"}},"clients":{"type":"array","items":{"$ref":"#/components/schemas/ResellerAiClient"}}}},"ResellerAiPack":{"type":"object","additionalProperties":false,"required":["code","name","grant_micros","list_price_minor","wholesale_price_minor","retail_price_minor","retail_source","is_active","currency"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"grant_micros":{"type":"integer","format":"int64","description":"Credit granted, in USD **micros** — a millionth of one US dollar, so one cent is 10,000 micros. Micros rather than minor units because a single model call costs a fraction of a cent and rounding each one up to a penny over-bills by two orders of magnitude."},"list_price_minor":{"type":"integer","format":"int64","description":"What Zinn® charges a direct customer, integer minor units of `currency`."},"wholesale_price_minor":{"type":"integer","format":"int64","description":"What you pay Zinn® — list less your wholesale discount on AI credit."},"retail_price_minor":{"type":"integer","format":"int64","description":"What your client pays you. Defaults to `list_price_minor`."},"retail_source":{"type":"string","enum":["price_list","default"],"description":"`price_list` when you set this number, `default` when it is Zinn®'s. Sent rather than left to be inferred: comparing the retail and list amounts gets it wrong the moment a reseller deliberately prices at exactly our list."},"is_active":{"type":"boolean"},"currency":{"type":"string","minLength":3,"maxLength":3}}},"ResellerAiPool":{"type":"object","additionalProperties":false,"required":["balance_micros","threshold_micros","is_low","client_count","allocated_micros","auto_buy_enabled","auto_buy_pack_code","auto_buy_spent_this_month_micros","auto_buy_monthly_cap_micros"],"properties":{"balance_micros":{"type":"integer","format":"int64","description":"What is left in your pool, USD micros. This is a balance on the same AI credit ledger your clients use — there is no separate pool store to reconcile against."},"threshold_micros":{"type":"integer","format":"int64","description":"The resolved low-pool line: yours if you set one, otherwise two allocations' worth of what you actually allocate. `0` when you have allocated nothing yet."},"is_low":{"type":"boolean","description":"`false` when there is no basis for a threshold, not just when the pool is healthy — a reseller who has allocated nothing is not in trouble."},"client_count":{"type":"integer"},"allocated_micros":{"type":"integer","format":"int64","description":"Everything you have ever moved out of the pool into a client, USD micros."},"auto_buy_enabled":{"type":"boolean"},"auto_buy_pack_code":{"type":"string"},"auto_buy_spent_this_month_micros":{"type":"integer","format":"int64","description":"What automatic buying has committed this calendar month. Counts only packs the automation bought — a pack you buy by hand does not eat the ceiling you set on it."},"auto_buy_monthly_cap_micros":{"type":"integer","format":"int64"}}},"ResellerAiPriceWrite":{"type":"object","additionalProperties":false,"required":["pack_code","price_minor"],"properties":{"pack_code":{"type":"string"},"price_minor":{"type":"integer","format":"int64","nullable":true,"description":"What your client pays, integer minor units. **`null` resets this pack to Zinn®'s price** and removes your override. A zero or negative value is refused."},"currency":{"type":"string","minLength":3,"maxLength":3},"is_active":{"type":"boolean"}}},"ResellerBrand":{"type":"object","description":"A reseller's brand, plus whether it is configured and entitled.","required":["configured","entitled","name","logo_url","primary_colour","support_url","status_url","panel_hostname","panel_hostname_active","panel_hostname_status","panel_hostname_records","sending_domain","sending_domain_verified","sending_domain_status","sending_domain_records"],"properties":{"configured":{"type":"boolean","description":"Whether a brand row exists yet. False renders an empty form, not a 404."},"entitled":{"type":"boolean","description":"Whether white-label is on this org's plan at all."},"name":{"type":"string"},"logo_url":{"type":"string"},"primary_colour":{"type":"string"},"support_url":{"type":"string"},"status_url":{"type":"string"},"panel_hostname":{"type":"string","description":"Read-only here — provisioned on `/v1/reseller/brand/panel-hostname`, because a hostname you merely typed is a link to nowhere on every client's screen."},"panel_hostname_active":{"type":"boolean","description":"Whether the edge is actually **serving** it. ⛔ Measured, not the edge's status word: a custom hostname can be `active` with a valid certificate and still answer 522, so the engine fetches the URL before this becomes `true`. Nothing links to the hostname until it does."},"panel_hostname_status":{"type":"string","description":"The edge's own status word, for display. Never branch on it."},"panel_hostname_records":{"type":"array","items":{"$ref":"#/components/schemas/BrandDnsRecord"}},"panel_hostname_claim":{"description":"A hostname asked for and not yet proven (za-24), with the TXT record that proves it; `null` when there is none.","oneOf":[{"$ref":"#/components/schemas/BrandHostnameClaim"},{"type":"null"}]},"sending_domain":{"type":"string","description":"Read-only here — provisioned on `/v1/reseller/brand/sending-domain`, because an unverified domain does not deliver."},"sending_domain_verified":{"type":"boolean","description":"Read-only. The mail provider's answer, not a setting."},"sending_domain_status":{"type":"string","description":"The provider's own status word, for display. Never branch on it."},"sending_domain_records":{"type":"array","items":{"$ref":"#/components/schemas/BrandDnsRecord"}},"palette":{"type":"object","additionalProperties":{"type":"string"},"description":"Named design-system colour tokens, `{token: \"#rrggbb\"}`, over the closed set in `palette_tokens`.\n\n⛔ Hex only, and that is a security boundary rather than a formatting rule: a CSS colour is a grammar including `url()`, `var()` and `image-set()`, so \"any valid CSS colour\" would accept an expression into a stylesheet served on somebody else's domain. A hex triple cannot reference anything.\n\n⭐ `accent` is adopted from `primary_colour` when you do not name one, and `accent_ink` — the colour of text ON the accent — is **derived** from luminance rather than chosen. The commonest way a white-label panel looks broken is white label text on a pale brand colour, so that combination is not representable."},"font_source":{"type":"string","enum":["catalogue","google",""],"description":"`catalogue` for one of `font_catalogue`, `google` for a family we self-host."},"font_key":{"type":"string","description":"The catalogue key when `font_source` is `catalogue`."},"font_google_family":{"type":"string","description":"A Google family NAME, never a URL.\n\n⛔ We fetch the family once, server-side, and serve the woff2 files from our own origin — so your clients never make a request to Google and their IP addresses never reach a third party. Install it with `POST /v1/reseller/brand/font` before selecting it here."},"nav_position":{"type":"string","enum":["side","top",""]},"density":{"type":"string","enum":["comfortable","compact",""]},"corner_radius":{"type":"string","enum":["soft","square",""]},"colour_scheme":{"type":"string","enum":["system","light","dark",""],"description":"The scheme a client's **first** visit lands on. ⛔ A default, never a lock — the panel's own theme toggle still works, because removing a visitor's dark mode is an accessibility regression rather than a brand decision."},"favicon_sha256":{"type":"string","description":"A favicon distinct from the panel logo. Upload it with `POST /v1/branding/logo` and `purpose=favicon`. Empty falls back to the logo — a 32px render of a wordmark beats somebody else's mark on your client's tab."},"favicon_url":{"type":"string"},"email_logo_sha256":{"type":"string","description":"The mark used in transactional mail (`purpose=email`). Separate because the constraints differ: mail clients render on a light background whatever the reader's theme, block SVG, and give no control over scaling."},"email_logo_url":{"type":"string"},"dns_nameservers":{"type":"array","maxItems":4,"items":{"type":"string"},"description":"Your **own** authoritative nameservers, so a client typing them into a registrar never reads ours. Empty means ours.\n\n⛔ At least two, or none — registrars refuse a single nameserver. There is deliberately no \"use the platform's\" boolean beside this: two representations of one fact, and the day they disagree a client's zone gets nameservers nobody chose."},"font_catalogue":{"type":"array","description":"The typefaces you may pick, served **with** the value so a new one appears in your picker on deploy rather than when somebody remembers to update the app too.","items":{"type":"object","required":["key","label","stack"],"properties":{"key":{"type":"string"},"label":{"type":"string"},"stack":{"type":"string","description":"The full CSS `font-family` value, fallbacks included."}}}},"layout_options":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"The allowed values for each layout choice, keyed by field name."},"palette_tokens":{"type":"array","items":{"type":"string"},"description":"The colour tokens `palette` may name."},"accent_contrast":{"$ref":"#/components/schemas/BrandAccentContrast"}}},"ResellerBrandWrite":{"type":"object","description":"The parts of a brand a reseller authors. ⛔ `panel_hostname`, `sending_domain`, `sending_domain_verified` and `logo_url` are deliberately absent — see the endpoint description. The logo has its own door: `POST /v1/branding/logo`.","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":120,"description":"What your clients are told they are using. Never blank."},"primary_colour":{"type":"string","maxLength":32},"support_url":{"type":"string","format":"uri","maxLength":500},"status_url":{"type":"string","format":"uri","maxLength":500},"palette":{"type":"object","additionalProperties":{"type":"string"},"description":"Named colour tokens, hex values only. An unrecognised token is a **422 naming it**, not a silent drop — a field that is ignored is how somebody comes to believe the platform is broken when their colour does not appear. An empty value deletes a token."},"font_source":{"type":"string","enum":["catalogue","google",""]},"font_key":{"type":"string","maxLength":32},"font_google_family":{"type":"string","maxLength":64,"description":"Install it with `POST /v1/reseller/brand/font` first — this field selects a family we already hold, and setting it alone would name a stylesheet with nothing behind it."},"nav_position":{"type":"string","enum":["side","top",""]},"density":{"type":"string","enum":["comfortable","compact",""]},"corner_radius":{"type":"string","enum":["soft","square",""]},"colour_scheme":{"type":"string","enum":["system","light","dark",""]},"favicon_sha256":{"type":"string","maxLength":64},"email_logo_sha256":{"type":"string","maxLength":64},"dns_nameservers":{"type":"array","maxItems":4,"items":{"type":"string","maxLength":253},"description":"Your own nameservers. **At least two, or none** — a registrar refuses a single one, and refusing it here with a sentence is better than at the registrar with a code."}}},"ResellerClientPlan":{"type":"object","required":["client_org_id","created"],"properties":{"client_org_id":{"$ref":"#/components/schemas/Uuid"},"subscription_id":{"type":"string","nullable":true,"description":"Pass this as `subscription_id` on `createSite`. Null when the client is on no plan — provisioning a site in that state is what leaves it unbilled."},"plan_code":{"type":"string","nullable":true},"plan_name":{"type":"string","nullable":true},"interval":{"type":"string","nullable":true},"created":{"type":"boolean","description":"True when this call granted the plan, false when the client was already on it. A retried provision needs the difference without inferring it from a timestamp."},"wholesale_amount_minor":{"type":"integer","nullable":true,"description":"What Zinn® charges you per period. `null`, never `0`, when unpriced."},"wholesale_currency":{"type":"string","nullable":true}}},"ResellerClientPlanSet":{"type":"object","required":["plan_code"],"additionalProperties":false,"properties":{"plan_code":{"type":"string","maxLength":64,"description":"The plan to put this client on, by code — the value your product's module settings carry. The newest active version of it is always what is granted."},"interval":{"type":"string","maxLength":16,"description":"Billing interval for the wholesale line. Defaults to `monthly`."}}},"ResellerClientVendorRow":{"type":"object","required":["client_org_id","client_name","daily_lookup_cap","billed_data_enabled","plan_daily_allowance"],"properties":{"client_org_id":{"$ref":"#/components/schemas/Uuid"},"client_name":{"type":"string"},"daily_lookup_cap":{"type":"integer","nullable":true,"description":"Your cap for this client's daily research lookups. `null` means no cap — they get whatever their plan grants. A cap can only ever reduce that: the smaller of the two is applied, so a number above their plan allowance changes nothing."},"billed_data_enabled":{"type":"boolean","description":"`false` stops this client drawing on your pool. Their plan, sites and history are untouched and they still see readings already paid for."},"plan_daily_allowance":{"type":"integer","description":"What their own plan grants per day today, so a cap can be shown against something. `-1` means unlimited."}}},"ResellerClientVendorWrite":{"type":"object","additionalProperties":false,"properties":{"daily_lookup_cap":{"type":"integer","nullable":true,"minimum":0,"maximum":100000,"description":"Daily research lookups for this client. `null` removes your cap. Can only reduce what their plan grants."},"billed_data_enabled":{"type":"boolean"}}},"ResellerClientWalletOpen":{"type":"object","description":"A reseller opening (or adding to) a client's float. `currency` decides which float — a EUR float is not a USD one and there is no rate at which merging them is safe.","required":["client_org_id","currency","amount_minor","reason"],"properties":{"client_org_id":{"$ref":"#/components/schemas/Uuid"},"currency":{"type":"string","minLength":3,"maxLength":3},"amount_minor":{"type":"integer","minimum":1,"description":"Strictly positive. Opening a float is a DEPOSIT; taking money off a client is a correction and belongs on the adjustments endpoint, which has the below-zero guard and an existing balance to check it against."},"reason":{"type":"string","minLength":3,"maxLength":255,"description":"The client reads this on their own statement of account."}}},"ResellerCurrency":{"type":"object","required":["code","name","symbol","offered"],"properties":{"code":{"type":"string","minLength":3,"maxLength":3,"description":"ISO-4217 alphabetic code."},"name":{"type":"string"},"symbol":{"type":"string"},"offered":{"type":"boolean","description":"Whether your clients may be quoted in it. Every currency reads `true` while `offers_all` is set — that is the state of a programme that has made no choice, not an empty selection."}}},"ResellerCurrencyPolicy":{"type":"object","required":["currencies","offers_all","offered_count","total_count","default_currency","sell_in_currency","switcher"],"properties":{"currencies":{"type":"array","items":{"$ref":"#/components/schemas/ResellerCurrency"}},"offers_all":{"type":"boolean","description":"You have made no choice, so your clients get every currency."},"offered_count":{"type":"integer"},"total_count":{"type":"integer"},"default_currency":{"type":"string","description":"What a client is quoted in before they choose. Empty means the platform answer — their own inference, then USD."},"sell_in_currency":{"type":"string","minLength":3,"maxLength":3,"description":"What **you** are priced and settled in, resolved — never empty, and never disclosed to your clients."},"switcher":{"type":"boolean","description":"Whether the currency control renders in your clients' panel at all. `false` quotes every client in `default_currency`."}}},"ResellerCurrencyWrite":{"type":"object","additionalProperties":false,"properties":{"currencies":{"type":"array","description":"Replaces the list your clients may be quoted in. An empty array returns you to offering every currency we can charge.","items":{"type":"string","minLength":3,"maxLength":3}},"default_currency":{"type":"string","maxLength":3,"description":"Empty returns to the platform answer. Must be one you offer."},"sell_in_currency":{"type":"string","maxLength":3,"description":"Empty returns to the platform base currency. Deliberately not required to be one of `currencies`."},"switcher":{"type":"boolean","description":"Whether the currency control renders in your clients' panel."}}},"ResellerDunning":{"type":"object","description":"A reseller's own dunning ladder, or the platform default they fall back to.","required":["using_platform_default","max_total_days","active_version","versions"],"properties":{"using_platform_default":{"type":"boolean","description":"True when the reseller has published no ladder of their own. `active_version` then carries the PLATFORM rungs their clients are chased on today, so the screen never has to render an empty ladder - which would describe a system in which nobody is chased at all."},"max_total_days":{"type":"integer","description":"The longest a whole ladder may run. A hard coupling, not a preference: the rebill workflow's execution timeout is derived from it, and a longer ladder would be terminated mid-climb, leaving the customer neither chased nor suspended."},"active_version":{"allOf":[{"$ref":"#/components/schemas/DunningPolicyVersion"}],"description":"The ladder in force. On the platform-default view this is synthesised rather than read from a row, so `id` is null and `version` is 0."},"versions":{"type":"array","description":"Every version this reseller has published, newest first.","items":{"$ref":"#/components/schemas/DunningPolicyVersion"}}}},"ResellerDunningPublish":{"type":"object","required":["steps","reason"],"properties":{"steps":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/DunningStep"}},"reason":{"type":"string","minLength":1,"maxLength":500,"description":"Why it changed. Required: a ladder decides when a paying customer is suspended, and a version with no reason is one nobody can explain a year later."}}},"ResellerEdgePolicy":{"type":"object","required":["data"],"properties":{"data":{"type":"array","description":"Every CDN and DNS network your clients could be placed on, in category then alphabetical order. The list reflects **your** pool: your own connected accounts if you have any, otherwise Zinn®'s.","items":{"$ref":"#/components/schemas/ResellerEdgeVendor"}}}},"ResellerEdgePolicyWrite":{"type":"object","additionalProperties":false,"required":["disabled"],"properties":{"disabled":{"type":"array","description":"The **complete** set of networks to turn off. Anything absent is turned on, so send the full state rather than a change — two screens open at once cannot then leave a switch behind. Naming a network your pool does not serve is refused rather than ignored.","items":{"$ref":"#/components/schemas/ResellerEdgeVendorRef"}}}},"ResellerEdgeVendor":{"type":"object","required":["category","vendor","label","enabled"],"properties":{"category":{"type":"string","enum":["cdn","dns"],"description":"Which kind of network this is."},"vendor":{"type":"string","description":"The network's key, as used when creating a site (`cloudflare`, …)."},"label":{"type":"string","description":"The network's display name. Never show `vendor` to a customer."},"enabled":{"type":"boolean","description":"Whether your clients may be placed on it. A network you have never touched is `true` — these switches record exceptions, not a full list."},"inherited_off":{"type":"boolean","description":"Only on the per-client view. `true` means you have turned this network off for **all** your clients, so it cannot be turned back on for this one here."}}},"ResellerEdgeVendorRef":{"type":"object","additionalProperties":false,"required":["category","vendor"],"properties":{"category":{"type":"string","enum":["cdn","dns"]},"vendor":{"type":"string"}}},"ResellerGateway":{"type":"object","required":["code","name","summary","dashboard_url","webhook_url","webhook_events","webhook_instructions","inputs","connected","is_default"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"summary":{"type":"string"},"dashboard_url":{"type":"string"},"webhook_url":{"type":"string","description":"An OUTPUT — paste it into the provider. Built from the host the request arrived on, so it is reachable by construction."},"webhook_events":{"type":"array","items":{"type":"string"}},"webhook_instructions":{"type":"string"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/ResellerGatewayField"}},"connected":{"type":"boolean"},"connection_id":{"oneOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]},"account_login":{"type":"string"},"is_default":{"type":"boolean"},"validated_at":{"type":["string","null"],"format":"date-time"}}},"ResellerGatewayConnect":{"type":"object","additionalProperties":false,"required":["values"],"properties":{"values":{"type":"object","additionalProperties":{"type":"string"},"description":"`{settings_key: value}` for the fields the gateway declares. Written to Vault, never to a database row, a log line, an audit entry or an error message (CLAUDE.md §2.4)."},"mode":{"type":"string","enum":["test","live"]},"validate_only":{"type":"boolean","description":"Check the credentials and return the result without storing."}}},"ResellerGatewayField":{"type":"object","required":["key","title","purpose","where","secret","mandatory"],"description":"One input on the connect form, served by the engine so adding a fourth gateway needs no frontend change.","properties":{"key":{"type":"string"},"title":{"type":"string"},"purpose":{"type":"string"},"where":{"type":"string","description":"The click path inside that provider's own dashboard."},"secret":{"type":"boolean","description":"True ⇒ the value goes to Vault and is never returned."},"mandatory":{"type":"boolean"},"example":{"type":"string","description":"A shape hint for the placeholder, never a real value."}}},"ResellerGatewayList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ResellerGateway"}}}},"ResellerInvoiceBranding":{"type":"object","description":"How your invoices read, plus whether you issue under your own company at all.","required":["configured","legal_entity_name","footer_text","payment_terms","payment_details","support_contact"],"properties":{"configured":{"type":"boolean","description":"False when your clients are still invoiced under Zinn Digital®, in which case there is nothing here to set."},"legal_entity_name":{"type":"string","description":"The company these invoices are issued by."},"footer_text":{"type":"string"},"payment_terms":{"type":"string"},"payment_details":{"type":"string"},"support_contact":{"type":"string"}}},"ResellerInvoiceBrandingWrite":{"type":"object","description":"The sentences you control on your own invoices. All optional; send an empty string to clear one.","properties":{"footer_text":{"type":"string","maxLength":600,"description":"Small print at the foot of the document — typically your registered company name and number."},"payment_terms":{"type":"string","maxLength":600,"description":"When and how you expect to be paid."},"payment_details":{"type":"string","maxLength":600,"description":"Remittance details — account name, IBAN, BIC, a payment link. Line breaks are preserved exactly as you type them."},"support_contact":{"type":"string","maxLength":200,"description":"Where your client asks about this invoice."}}},"ResellerLanguage":{"type":"object","required":["code","name","native_name","rtl","offered"],"properties":{"code":{"type":"string"},"name":{"type":"string","description":"The language's English name."},"native_name":{"type":"string","description":"The endonym","as its speakers write it.":null},"rtl":{"type":"boolean"},"offered":{"type":"boolean","description":"Whether your clients may choose it. True for every language when you have made no choice."}}},"ResellerLanguagePolicy":{"type":"object","required":["languages","offers_all","offered_count","total_count","default_locale"],"properties":{"languages":{"type":"array","items":{"$ref":"#/components/schemas/ResellerLanguage"}},"offers_all":{"type":"boolean","description":"You have made no choice, so your clients get every language."},"offered_count":{"type":"integer"},"total_count":{"type":"integer"},"default_locale":{"type":"string","description":"What a new client account starts in. Empty means the platform default."},"switcher":{"type":"boolean","description":"Whether the language control renders in your clients' panel at all. `false` shows every client the panel in `default_locale`; it never removes their right to change their own account language."}}},"ResellerLanguageWrite":{"type":"object","additionalProperties":false,"properties":{"locales":{"type":"array","description":"Replaces the list your clients may choose from. An empty array returns you to offering every language.","items":{"type":"string","maxLength":12}},"default_locale":{"type":"string","maxLength":12,"description":"Empty returns to the platform default."},"switcher":{"type":"boolean","description":"Whether the language control renders in your clients' panel."}}},"ResellerLegalEntity":{"type":"object","additionalProperties":false,"required":["name","country","number_prefix"],"description":"The reseller's own issuing company. ⛔ There is deliberately no field for \"is this the platform default\" or \"whose entity is this\" — both are set by the engine, and a reseller row that claimed to be the platform default would stop every Zinn® invoice.","properties":{"id":{"$ref":"#/components/schemas/Uuid"},"name":{"type":"string","maxLength":200},"company_number":{"type":"string","maxLength":64},"address_line1":{"type":"string","maxLength":200},"address_line2":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":120},"region":{"type":"string","maxLength":120},"postcode":{"type":"string","maxLength":32},"country":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2. Stored uppercase."},"vat_number":{"type":"string","maxLength":32},"footer_text":{"type":"string"},"number_prefix":{"type":"string","pattern":"^[A-Z0-9]{2,8}$","description":"The prefix in every invoice number you issue (`AG-INV-2026-000123`). Globally unique across all companies on the platform, and frozen once you have issued an invoice."},"number_prefix_locked":{"type":"boolean","readOnly":true,"description":"True once an invoice has been issued under this company."},"created_at":{"type":"string","format":"date-time","readOnly":true},"updated_at":{"type":"string","format":"date-time","readOnly":true}}},"ResellerLegalEntityEnvelope":{"type":"object","required":["data"],"properties":{"data":{"oneOf":[{"$ref":"#/components/schemas/ResellerLegalEntity"},{"type":"null"}],"description":"`null` when no company details are held yet."}}},"ResellerLine":{"type":"object","required":["code","name","description","enabled","plan_count","active_client_count"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"enabled":{"type":"boolean","description":"Whether your clients may buy from this line. A line you have never decided about is on."},"plan_count":{"type":"integer","description":"Sellable plans in this line."},"active_client_count":{"type":"integer","description":"Your clients holding a live subscription in this line. They keep it if you turn the line off — the switch refuses new orders only."}}},"ResellerLineDiscount":{"type":"object","required":["product_line","discount_bps","scope"],"properties":{"product_line":{"type":"string","description":"The product-line code, e.g. `zinn_campaigns`."},"discount_bps":{"type":"integer","minimum":0,"description":"The discount off list on this line, in basis points."},"scope":{"type":"string","enum":["platform","platform_product_line",""],"description":"Which platform-wide rate applies; empty when none is in force."}}},"ResellerLineList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ResellerLine"}}}},"ResellerLineWrite":{"type":"object","additionalProperties":false,"required":["disabled"],"properties":{"disabled":{"type":"array","description":"The complete set of product-line codes to turn OFF. Anything absent is on. A replacing set rather than a patch, so the last save is the truth.","items":{"type":"string","maxLength":64}}}},"ResellerMailBrand":{"allOf":[{"$ref":"#/components/schemas/ResellerMailBrandInput"},{"type":"object","required":["configured"],"properties":{"configured":{"type":"boolean","description":"Whether every hostname the preset needs has been supplied. **All-or-nothing**: a half-set would publish the reseller's MX beside the platform's SPF include, which is a leak and a broken mail setup at the same time. Only a configured brand unlocks hosted mail on a white-label account."},"verified_at":{"type":"string","format":"date-time","nullable":true,"description":"When these names were last confirmed to resolve to the relay."}}}]},"ResellerMailBrandInput":{"type":"object","description":"A reseller's own mail hostnames. Every field is public DNS — there is no credential here, because the relay authenticates the mailbox rather than the brand.","required":["mx_hosts","spf_include","autodiscover_host","imap_host","smtp_host","webmail_host"],"properties":{"name":{"type":"string","maxLength":120,"description":"What the reseller calls this brand, for their own screens."},"mx_hosts":{"type":"array","description":"Apex MX targets in priority order, on the reseller's own domain, pointed at the relay's addresses. Their names — an A record they publish, never a CNAME to ours, which would put the platform's hostname in every lookup their client runs.","items":{"type":"string","maxLength":255}},"spf_include":{"type":"string","maxLength":255,"description":"The domain in the reseller's `v=spf1 include:…`. A delegation, so it must be a name whose SPF record they control and which in turn includes our sender list."},"autodiscover_host":{"type":"string","maxLength":255},"imap_host":{"type":"string","maxLength":255},"smtp_host":{"type":"string","maxLength":255},"webmail_host":{"type":"string","maxLength":255,"description":"Where the reseller's client's browser goes to read mail — the single most visible name in the whole product."}}},"ResellerNameserverGlue":{"type":"object","description":"One glue record the reseller registers at their own registrar.","required":["host","type","ipv4"],"properties":{"host":{"type":"string","description":"e.g. `ns1.acme-hosting.com`"},"type":{"type":"string","enum":["A"]},"ipv4":{"type":"string"},"purpose":{"type":"string"}}},"ResellerNameservers":{"type":"object","description":"A reseller's own nameserver brand — the hostnames their clients' domains are delegated to, and whether those hostnames actually answer.\n\n⛔ `serving` is a MEASUREMENT, not a claim. It turns on only when `/v1/reseller/nameservers/verify` has looked the hostnames up on the public internet and found them resolving to our anycast. Until then a client zone keeps the platform nameservers, because delegating a live domain to a nameserver with no glue takes that domain off the internet.","required":["domain","hostnames","glue","serving","status","vendor"],"properties":{"domain":{"type":"string","description":"The reseller's own domain, or `\"\"` when they have not claimed one."},"hostnames":{"type":"array","items":{"type":"string"},"description":"Derived from `domain` — `ns1.acme-hosting.com`, `ns2.acme-hosting.com`. Two, because registries reject a single-nameserver delegation."},"glue":{"type":"array","items":{"$ref":"#/components/schemas/ResellerNameserverGlue"},"description":"The `A` records the reseller must register at THEIR registrar. Nothing we hold can create them: they are a registry operation on a domain we do not sponsor."},"serving":{"type":"boolean"},"status":{"type":"string","description":"One sentence from the last check, for the screen and for support."},"vendor":{"type":"string","description":"Which of our anycast DNS providers serves these hostnames."},"checked_at":{"type":"string","format":"date-time","nullable":true,"description":"When it was last CHECKED, whatever the outcome. `null` means nobody has looked — a different fact from \"checked and not serving\"."},"checked":{"type":"boolean","description":"Verify responses only. `false` means our resolver could not answer and **nothing was changed** — not that the glue is missing. The two send a reseller to opposite actions."},"supported_vendors":{"type":"array","items":{"type":"string"},"description":"The anycast providers that can serve a nameserver brand of your own."}}},"ResellerNameserversWrite":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","maxLength":253,"description":"Just the domain you own — `acme-hosting.com`, with no scheme and no `ns1.` prefix. We add `ns1` and `ns2`. A domain Zinn® operates is refused."}}},"ResellerOverview":{"type":"object","required":["program","panel","mail","dns","api","support","commerce","languages","notifications","clients"],"properties":{"program":{"$ref":"#/components/schemas/ResellerOverviewProgram"},"panel":{"$ref":"#/components/schemas/ResellerOverviewPanel"},"mail":{"$ref":"#/components/schemas/ResellerOverviewMail"},"dns":{"$ref":"#/components/schemas/ResellerOverviewDns"},"api":{"$ref":"#/components/schemas/ResellerOverviewApi"},"support":{"$ref":"#/components/schemas/ResellerOverviewSupport"},"commerce":{"$ref":"#/components/schemas/ResellerOverviewCommerce"},"languages":{"$ref":"#/components/schemas/ResellerOverviewLanguages"},"notifications":{"$ref":"#/components/schemas/ResellerOverviewNotifications"},"clients":{"$ref":"#/components/schemas/ResellerOverviewClients"}}},"ResellerOverviewApi":{"type":"object","required":["base_url","docs_url","live_key_count","sandbox_key_count","manage_route"],"properties":{"base_url":{"type":"string","description":"Taken from this request, so it is right on every environment."},"docs_url":{"type":"string"},"live_key_count":{"type":"integer"},"sandbox_key_count":{"type":"integer"},"manage_route":{"type":"string"}}},"ResellerOverviewClients":{"type":"object","required":["count","manage_route"],"properties":{"count":{"type":"integer"},"manage_route":{"type":"string"}}},"ResellerOverviewCommerce":{"type":"object","required":["gateways","gateway_gap","has_invoicing_entity","invoicing_gap","lines_offered","lines_total","manage_route"],"properties":{"gateways":{"type":"array","description":"The payment accounts this reseller has connected, with the display name the rest of the panel uses.","items":{"type":"object","required":["code","name"],"properties":{"code":{"type":"string"},"name":{"type":"string"}}}},"gateway_gap":{"type":"boolean","description":"Active, but no gateway connected — nobody can pay you."},"has_invoicing_entity":{"type":"boolean"},"invoicing_gap":{"type":"boolean"},"lines_offered":{"type":"integer"},"lines_total":{"type":"integer"},"manage_route":{"type":"string"}}},"ResellerOverviewDns":{"type":"object","required":["fleet_nameservers","platform_nameservers","manage_route"],"properties":{"fleet_nameservers":{"type":"array","items":{"type":"string"}},"platform_nameservers":{"type":"array","items":{"type":"string"}},"manage_route":{"type":"string"}}},"ResellerOverviewLanguages":{"type":"object","required":["offered_count","total_count","offers_all","default_locale","manage_route"],"properties":{"offered_count":{"type":"integer"},"total_count":{"type":"integer"},"offers_all":{"type":"boolean"},"default_locale":{"type":"string"},"manage_route":{"type":"string"}}},"ResellerOverviewMail":{"type":"object","required":["sending_domain","verified","in_use","status","dns_records","manage_route"],"properties":{"sending_domain":{"type":"string"},"verified":{"type":"boolean"},"in_use":{"type":"string","description":"Empty until verified — an unverified domain does not deliver, so \"typed\" must never read as \"in use\"."},"status":{"type":"string"},"dns_records":{"type":"array","items":{"type":"object","additionalProperties":true}},"manage_route":{"type":"string"}}},"ResellerOverviewNotifications":{"type":"object","required":["own_dunning_ladder","channel_count","verified_channel_count","gap","dunning_route","channels_route"],"properties":{"own_dunning_ladder":{"type":"boolean","description":"You publish your own payment-chasing ladder. `false` means your clients are chased on the platform ladder — a fact, not a gap."},"channel_count":{"type":"integer","description":"Destinations you have set up for your own alerts."},"verified_channel_count":{"type":"integer","description":"How many of them actually deliver. A destination that never verified does not, so this is the number that matters."},"gap":{"type":"boolean","description":"True only when you have set up destinations and NONE of them work. Zero channels is not a gap — e-mail to the account owner always delivers."},"dunning_route":{"type":"string"},"channels_route":{"type":"string"}}},"ResellerOverviewPanel":{"type":"object","required":["default_url","custom_hostname","custom_hostname_active","live_url","status","dns_records","brand_name","logo_url","primary_colour","manage_route"],"properties":{"default_url":{"type":"string"},"custom_hostname":{"type":"string"},"custom_hostname_active":{"type":"boolean","description":"Serving, not merely typed. `live_url` falls back to ours until this is true, because linking a client at a host that does not answer locks them out of their own account."},"live_url":{"type":"string"},"status":{"type":"string"},"dns_records":{"type":"array","items":{"type":"object","additionalProperties":true}},"brand_name":{"type":"string"},"logo_url":{"type":"string"},"primary_colour":{"type":"string"},"manage_route":{"type":"string"}}},"ResellerOverviewProgram":{"type":"object","required":["status","can_sell","billing_day","default_markup_bps"],"properties":{"status":{"type":"string"},"can_sell":{"type":"boolean"},"billing_day":{"type":"integer"},"default_markup_bps":{"type":"integer"}}},"ResellerOverviewSupport":{"type":"object","required":["client_support_url","client_status_url","clients_reach_you_not_zinn","gap","manage_route"],"properties":{"client_support_url":{"type":"string"},"client_status_url":{"type":"string"},"clients_reach_you_not_zinn":{"type":"boolean","description":"Your clients reach you, never us; you escalate to us. So an unset support URL leaves them with nowhere to go."},"gap":{"type":"boolean"},"manage_route":{"type":"string"}}},"ResellerPluginAffiliateProgramme":{"type":"object","additionalProperties":false,"required":["product_slug","product_title","commission","commission_type","cookie_days","landing_url","apply_url"],"properties":{"product_slug":{"type":"string"},"product_title":{"type":"string"},"commission":{"type":"integer","minimum":1,"description":"Percentage points when `commission_type` is `percentage`; otherwise the amount Freemius holds."},"commission_type":{"type":"string","description":"Freemius commission type, e.g. `percentage`."},"cookie_days":{"type":["integer","null"],"minimum":0},"landing_url":{"type":["string","null"],"format":"uri"},"apply_url":{"type":["string","null"],"format":"uri","description":"The public page that takes an application, or null when there is none yet."}}},"ResellerPluginAffiliates":{"type":"object","additionalProperties":false,"required":["enabled","complete","programmes","without_programme","skipped"],"properties":{"enabled":{"type":"boolean","description":"False when Zinn® staff turned the Pro-plugin affiliate programmes off for this reseller (then `programmes` is empty). Commission already earned is never clawed back."},"complete":{"type":"boolean","description":"False only when Freemius was asked about a product and could not answer (an HTTP error or no connection); the list may be short and a retry may help. No programme, or a product that cannot be checked, never makes it false."},"programmes":{"type":"array","items":{"$ref":"#/components/schemas/ResellerPluginAffiliateProgramme"}},"without_programme":{"type":"array","description":"Products Freemius answered for with no active, visible affiliate programme.","items":{"type":"object","additionalProperties":false,"required":["product_slug","product_title"],"properties":{"product_slug":{"type":"string"},"product_title":{"type":"string"}}}},"skipped":{"type":"array","description":"Products that were not asked, with why (`no_keys`, no key pair on the platform, e.g. a bundle).","items":{"type":"object","additionalProperties":false,"required":["product_slug","product_title","reason"],"properties":{"product_slug":{"type":"string"},"product_title":{"type":"string"},"reason":{"type":"string","enum":["no_keys"]}}}}}},"ResellerPrice":{"type":"object","required":["plan_id","plan_code","plan_name","interval","currency","amount_minor","is_active","price_source"],"properties":{"id":{"oneOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}],"description":"Null when you have not authored this row yet."},"plan_id":{"$ref":"#/components/schemas/Uuid"},"plan_code":{"type":"string"},"plan_name":{"type":"string"},"interval":{"type":"string"},"currency":{"type":"string","minLength":3,"maxLength":3},"amount_minor":{"type":"integer","description":"What YOUR client pays, in minor units."},"is_active":{"type":"boolean"},"list_amount_minor":{"type":["integer","null"],"description":"Zinn®'s list price for the same plan."},"wholesale_amount_minor":{"type":["integer","null"],"description":"What the plan costs YOU after your wholesale discount."},"wholesale_discount_bps":{"type":"integer"},"price_source":{"type":"string","enum":["price_list","markup","unpriced"],"description":"Whether the price is one you set, one derived from list by your default markup, or absent because the catalogue holds no price in this currency."}}},"ResellerPriceList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ResellerPrice"}}}},"ResellerPriceWrite":{"type":"object","additionalProperties":false,"required":["plan_id","interval","currency","amount_minor"],"properties":{"plan_id":{"$ref":"#/components/schemas/Uuid"},"interval":{"type":"string"},"currency":{"type":"string","minLength":3,"maxLength":3},"amount_minor":{"type":"integer","minimum":0},"is_active":{"type":"boolean"}}},"ResellerProgram":{"type":"object","required":["id","status","billing_day","default_markup_bps","has_invoicing_entity","can_sell","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"status":{"type":"string","enum":["pending","active","suspended"],"description":"Set by Zinn®, never by the reseller. `pending` can price but not sell."},"billing_day":{"type":"integer","minimum":1,"maximum":28,"description":"Day of month the wholesale statement closes. Capped at 28 so every month has one — an anchor that moves double-bills at the seam."},"default_markup_bps":{"type":"integer","minimum":0,"description":"Basis points added to Zinn®'s list price for plans you have not priced explicitly. 0 means \"sell at list\", which is not zero margin — you still keep the wholesale discount."},"legal_entity_id":{"oneOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}],"description":"Your own issuing entity for invoices to your clients."},"has_invoicing_entity":{"type":"boolean","description":"Whether we hold the company details your client invoices are issued under. False means you cannot invoice a client yet."},"can_sell":{"type":"boolean"},"bills_clients_directly":{"type":"boolean","description":"Whether you invoice your own clients outside our system. When `true` we raise no document to them at all, and `has_invoicing_entity` being false is then a finished state rather than something still to do."},"collect_on_platform_gateway":{"type":"boolean","description":"Whether your clients may check out on Zinn®'s payment account when you have usable gateway connected of your own. `true` (the default) means a client is never blocked by your onboarding: we take the payment, and credit what we collected back to you on your next wholesale statement, so you are billed the net. `false` restores the refusal — your clients cannot buy until you connect a gateway, which is the right setting only if you must be the sole merchant of record for them."},"created_at":{"type":"string","format":"date-time"}}},"ResellerProgramUpdate":{"type":"object","additionalProperties":false,"properties":{"billing_day":{"type":"integer","minimum":1,"maximum":28},"default_markup_bps":{"type":"integer","minimum":0,"maximum":100000},"bills_clients_directly":{"type":"boolean","description":"Turn on to invoice your own clients yourself — we stop issuing to them from the next run. Nothing already issued changes: an invoice is immutable. Turning it back off resumes issuing, including for orders placed while it was on."},"collect_on_platform_gateway":{"type":"boolean","description":"Turn OFF to refuse your clients' payments rather than let them settle on Zinn®'s account while you have no gateway connected. Your clients then cannot buy until you connect one; leave it on unless you must be the sole merchant of record."}}},"ResellerService":{"type":"object","description":"One site you have provisioned for a client, as a reseller sees it: whose it is, what it runs, what state it is in, what it is using, and what you charge for it.","required":["site_id","client_org_id","client_org_name","primary_domain","status","created_at"],"properties":{"site_id":{"$ref":"#/components/schemas/Uuid"},"client_org_id":{"$ref":"#/components/schemas/Uuid"},"client_org_name":{"type":"string"},"primary_domain":{"type":"string"},"name":{"type":"string"},"status":{"$ref":"#/components/schemas/SiteStatus"},"product_line":{"type":["string","null"]},"plan_code":{"type":["string","null"]},"plan_name":{"type":["string","null"]},"held_by_reseller":{"type":"boolean","description":"True when the current suspension was placed through this surface, which is the only case `unsuspendResellerService` will release. A site suspended by the abuse desk reports false and stays yours to see but not to release."},"pending_deletion_at":{"type":["string","null"],"format":"date-time","description":"When a scheduled deletion falls due, or null."},"sell_amount_minor":{"type":["integer","null"],"description":"What YOU charge for this plan, in minor units of `sell_currency` — your own price-list row if you have authored one, otherwise our list price with your default markup applied. Null when the plan is not priced in that currency."},"sell_currency":{"type":["string","null"],"minLength":3,"maxLength":3},"created_at":{"type":"string","format":"date-time"},"serving_change":{"description":"A suspend or unsuspend still being applied on the site's server, or the last one when it failed; `null` otherwise (D50801).","oneOf":[{"$ref":"#/components/schemas/ResellerServingChange"},{"type":"null"}]}}},"ResellerServiceDetail":{"description":"One service, plus its current disk and bandwidth usage.\n\nUsage is deliberately absent from `listResellerServices` and present only here. Reading it is a round trip to the hosting platform (cached, ~minutes), so putting it on the list would be one network call per row — a loop over a queryset that calls a network per row, which is exactly what CLAUDE.md §2.10 forbids. A billing panel syncing usage walks its own service list and reads this endpoint per service, which is bounded by that reseller's own client count and served from cache in between.","allOf":[{"$ref":"#/components/schemas/ResellerService"},{"type":"object","properties":{"disk_used_bytes":{"type":["integer","null"],"description":"Null when the hosting platform has no usage to report for this site."},"bandwidth_used_bytes":{"type":["integer","null"],"description":"Outbound bandwidth this billing period, or null."},"usage_measured_at":{"type":["string","null"],"format":"date-time","description":"When the reading was taken. Null alongside null usage — so \"we have not measured this\" is never mistaken for \"it used nothing\" (§2.44)."}}}]},"ResellerServiceHold":{"type":"object","additionalProperties":false,"properties":{"reason":{"type":"string","maxLength":500,"description":"Your own note for the audit trail — typically the invoice number that went unpaid. Recorded against the suspension; never shown to the client."}}},"ResellerServicePackage":{"type":"object","description":"What the move actually did, read back from the rows rather than echoed.","required":["site_id","plan_code","plan_version_id","subscription_id"],"properties":{"site_id":{"$ref":"#/components/schemas/Uuid"},"plan_code":{"type":"string"},"plan_name":{"type":"string"},"plan_version_id":{"type":"string"},"package_type":{"type":"string","description":"The vendor package template the service now sits on. Empty on our own fleet, where a plan names no template because there is no vendor — the plan *is* its entitlement set, applied as a real quota on a box we own."},"subscription_id":{"type":"string","description":"The client's new subscription. This is the row your next wholesale statement is built from, which is how the change reaches your bill."},"wholesale_amount_minor":{"type":"integer","nullable":true,"description":"What Zinn® will now charge you per period. `null`, never `0`, if unpriced."},"wholesale_currency":{"type":"string","nullable":true}}},"ResellerServicePackageChange":{"type":"object","required":["plan_code"],"additionalProperties":false,"properties":{"plan_code":{"type":"string","maxLength":64,"description":"The plan to move onto, by **code**. The newest active version of it is always what gets applied, so a plan we have re-priced since your product was configured cannot be sold at its old price."}}},"ResellerServicePackageChoices":{"type":"object","description":"Where this service sits now, and everywhere it could move to.","required":["changeable","options"],"properties":{"current_plan_code":{"type":"string","nullable":true},"current_plan_name":{"type":"string","nullable":true},"changeable":{"type":"boolean","description":"False when the surface is shut whatever plan is picked — see `reason`. Your panel should hide the upgrade control rather than offer one that cannot work."},"reason":{"type":"string","description":"Why, when `changeable` is false. A stable code: `no_subscription` · `not_billable` · `no_package_type` · `subscription_not_live` · `renewal_unpaid` (the subscription owes an unpaid renewal; pay it first, then change plan).\n\n⛔ `shared_subscription` is retired (2026-09-08) and is never returned again — a plan covering several sites is changed for all of them rather than declined."},"options":{"type":"array","items":{"$ref":"#/components/schemas/ResellerServicePackageOption"}}}},"ResellerServicePackageOption":{"type":"object","description":"One package this client's service could be moved onto, already scored against what they are actually using.","required":["plan_code","plan_name","direction","eligible"],"properties":{"plan_code":{"type":"string","description":"The code to send to `changeResellerServicePackage`, and the value to put in the product's module settings in your billing panel."},"plan_name":{"type":"string"},"direction":{"type":"string","enum":["upgrade","downgrade","same"],"description":"By list price — what the word means to a customer — not by allowance arithmetic across the entitlement matrix."},"eligible":{"type":"boolean","description":"Whether this service may move onto it right now."},"blocked_reason":{"type":"string","description":"A **stable code**, never prose, so your panel can render it in its own language: `usage_exceeds` · `account_over_limit` · `platform_mismatch` · `no_price` · `unknown_package_type` · `different_target` · `no_package_type`. Empty when `eligible` is true."},"blocked_detail":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"integer"}},"description":"The numbers behind `usage_exceeds` and `account_over_limit` — limit identifier → `{in_use, allowed}` — so a screen can say which limit and by how much rather than \"this is not allowed\"."},"wholesale_amount_minor":{"type":"integer","nullable":true,"description":"What **Zinn® charges you** for one period of this plan, after your programme's discount, in integer minor units. `null` — never `0` — when the catalogue holds no price in the currency asked for."},"wholesale_currency":{"type":"string","nullable":true},"sell_amount_minor":{"type":"integer","nullable":true,"description":"What **you charge your client**: your own price-list row where you have authored one, otherwise our list price plus your default markup. `null`, never `0`, when it cannot be resolved."},"sell_currency":{"type":"string","nullable":true}}},"ResellerServicePage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ResellerService"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"ResellerServiceSso":{"type":"object","required":["url","expires_at"],"properties":{"url":{"type":"string","format":"uri","description":"Open this in the client's browser. The single-use ticket is in the URL fragment, so it never reaches a server log. Redeem once, within `expires_at`."},"expires_at":{"type":"string","format":"date-time"},"client_org_id":{"$ref":"#/components/schemas/Uuid"}}},"ResellerServingChange":{"type":"object","required":["id","kind","state","error_code","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"kind":{"type":"string","enum":["suspend","unsuspend"]},"state":{"type":"string","enum":["queued","running","failed"]},"error_code":{"type":["string","null"],"enum":["conflict","unsupported","box_unconfirmed","gone",null]},"created_at":{"type":"string","format":"date-time"}}},"ResellerSupportDesk":{"type":"object","required":["ai_enabled","ai_provider","website_url","instructions","knowledge","connected_providers"],"properties":{"ai_enabled":{"type":"boolean"},"ai_provider":{"type":"string","description":"The provider of your own key the agent uses; empty means your first connected key."},"website_url":{"type":"string"},"instructions":{"type":"string","maxLength":4000},"knowledge":{"type":"string","maxLength":20000},"connected_providers":{"type":"array","description":"The providers you have a live AI key of your own for.","items":{"type":"string"}}}},"ResellerSupportDeskInput":{"type":"object","additionalProperties":false,"properties":{"ai_enabled":{"type":"boolean"},"ai_provider":{"type":"string","maxLength":32},"website_url":{"type":"string","maxLength":500},"instructions":{"type":"string","maxLength":4000},"knowledge":{"type":"string","maxLength":20000}}},"ResellerSupportEscalation":{"type":"object","additionalProperties":false,"required":["note"],"properties":{"note":{"type":"string","minLength":1,"maxLength":5000,"description":"What you need from platform support. Shown first, above the client's thread."}}},"ResellerSupportMessage":{"type":"object","required":["id","author_kind","body","internal","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"author_kind":{"$ref":"#/components/schemas/TicketAuthorKind"},"body":{"type":"string"},"internal":{"type":"boolean","description":"An internal note your client never sees."},"created_at":{"type":"string","format":"date-time"}}},"ResellerSupportReply":{"type":"object","additionalProperties":false,"required":["body"],"properties":{"body":{"type":"string","minLength":1,"maxLength":20000},"internal":{"type":"boolean","default":false}}},"ResellerSupportTicket":{"type":"object","description":"One client ticket on your support desk (docs/99 §4e).","required":["id","subject","status","priority","client_org_id","client_name","created_at","updated_at","escalated_ticket_id"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"subject":{"type":"string"},"status":{"$ref":"#/components/schemas/TicketStatus"},"priority":{"$ref":"#/components/schemas/TicketPriority"},"client_org_id":{"$ref":"#/components/schemas/Uuid"},"client_name":{"type":"string","description":"Your client's organization name."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"escalated_ticket_id":{"type":["string","null"],"description":"The ticket in your own organization this was escalated to us as, if any."}}},"ResellerSupportTicketDetail":{"allOf":[{"$ref":"#/components/schemas/ResellerSupportTicket"},{"type":"object","required":["messages"],"properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/ResellerSupportMessage"}}}}]},"ResellerSupportTicketPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ResellerSupportTicket"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"ResellerTaxRegistration":{"type":"object","additionalProperties":false,"required":["jurisdiction","number","effective_from"],"properties":{"id":{"$ref":"#/components/schemas/Uuid","readOnly":true},"jurisdiction":{"type":"string","minLength":2,"maxLength":8,"description":"ISO country code of the registration — or `EU` for the Union one-stop-shop, which is a scheme rather than a member state.","example":"GB"},"scheme":{"type":"string","enum":["standard","flat_rate","oss","non_union_oss"],"default":"standard"},"number":{"type":"string","maxLength":32,"description":"Your VAT registration number, as it must appear on an invoice. Checked for shape only — we do not verify that it exists, and a number that does not will still charge your clients VAT.","example":"GB123456789"},"effective_from":{"type":"string","format":"date","description":"The date the registration takes effect. Required and never defaulted to today: the date your tax authority gave you is usually not the day you enter it here, and guessing it either charges VAT for a period you were not liable for or misses one you were."},"effective_to":{"type":["string","null"],"format":"date","description":"The date it ended, or `null` while still in force."},"in_force":{"type":"boolean","readOnly":true,"description":"Whether this registration is in force today."},"created_at":{"type":"string","format":"date-time","readOnly":true}}},"ResellerTaxRegistrationEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ResellerTaxRegistration"}}},"ResellerTaxRegistrationListEnvelope":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ResellerTaxRegistration"}},"meta":{"type":"object","properties":{"company_required":{"type":"boolean","description":"`true` when no company details are held yet, so a registration cannot be added. Distinguishes \"you have none\" from \"you cannot have any yet\"."}}}}},"ResellerTaxRegistrationRemovalEnvelope":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","outcome"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"outcome":{"type":"string","enum":["ended","deleted"],"description":"`deleted` for a registration that had not started; `ended` for one that had, where the row is kept because issued invoices reference it."}}}}},"ResellerTerms":{"type":"object","required":["standard_discount_bps","ai_credits_discount_bps","lines"],"properties":{"standard_discount_bps":{"type":"integer","minimum":0,"description":"The discount off list on every line with no rate of its own, in basis points."},"ai_credits_discount_bps":{"type":"integer","minimum":0,"description":"The discount on AI credit packs, in basis points."},"lines":{"type":"array","items":{"$ref":"#/components/schemas/ResellerLineDiscount"}}}},"ResellerTermsResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ResellerTerms"}}},"ResellerVendorPolicy":{"type":"object","required":["seo_data_mode","monthly_pool_micros","alert_at_bps","client_overrides"],"properties":{"seo_data_mode":{"type":"string","enum":["own_keys","platform_pool"],"description":"`own_keys` runs client SEO and indexing lookups on credentials you connect yourself and is free of charge from us. `platform_pool` runs them on Zinn®'s accounts against your monthly allowance."},"monthly_pool_micros":{"type":"integer","format":"int64","nullable":true,"description":"Your monthly allowance of Zinn-funded vendor spend, in USD micros (1,000,000 = $1). Read-only — it is a commercial term of your programme. `null` means **no pool has been set**, which is unbounded; it is not the same as `0`, which would mean you may draw nothing."},"alert_at_bps":{"type":"integer","description":"Basis points of the pool at which you are warned. 8000 = 80%."},"client_overrides":{"type":"array","description":"Every one of your clients, including those you have never capped — a client with no cap set appears with `daily_lookup_cap: null`.","items":{"$ref":"#/components/schemas/ResellerClientVendorRow"}}}},"ResellerVendorPolicyWrite":{"type":"object","additionalProperties":false,"properties":{"seo_data_mode":{"type":"string","enum":["own_keys","platform_pool"]}}},"ResellerVendorServiceDraw":{"type":"object","required":["service","calls","cost_micros","is_priced"],"properties":{"service":{"type":"string","description":"The upstream vendor, e.g. `dataforseo`, `majestic`, `llm`."},"calls":{"type":"integer","description":"Billed calls made for your client base in the period. Always known."},"cost_micros":{"type":"integer","format":"int64","nullable":true,"description":"What those calls cost, USD micros. `null` when this vendor bills in prepaid units we do not price per call — it is **not** zero, and must never be shown as free."},"is_priced":{"type":"boolean","description":"`false` means `cost_micros` is `null` and these calls are excluded from every money total in this response."}}},"ResellerVendorUsage":{"type":"object","required":["pool_enforced","seo_data_mode","pool_micros","month_spent_micros","month_remaining_micros","month_is_floor","month_unpriced_calls","should_warn","ceiling_micros","ceiling_is_floor","org_count","services"],"properties":{"pool_enforced":{"type":"boolean","description":"Read this first. `false` means no pool has been set, so nothing is bounded — it does not mean you have a large allowance remaining."},"seo_data_mode":{"type":"string","enum":["own_keys","platform_pool"]},"pool_micros":{"type":"integer","format":"int64","nullable":true},"month_spent_micros":{"type":"integer","format":"int64","description":"Priced spend this calendar month. A **minimum** whenever `month_is_floor` is true."},"month_remaining_micros":{"type":"integer","format":"int64","nullable":true,"description":"`null` when no pool is set, or when the month's spend is a floor — an unknown cannot be subtracted from a budget to give a remainder."},"month_is_floor":{"type":"boolean","description":"`true` means `month_spent_micros` understates the truth because a vendor we cannot price per call was used. Show it beside the number."},"month_unpriced_calls":{"type":"integer","description":"Billed calls this month excluded from the money total."},"should_warn":{"type":"boolean","description":"You have crossed `alert_at_bps` of your pool."},"ceiling_micros":{"type":"integer","format":"int64","description":"The most your client base could draw in a month if every client used every allowance their plan includes. Independent of how busy this month was."},"ceiling_is_floor":{"type":"boolean"},"org_count":{"type":"integer","description":"Organizations counted — you plus your clients. A client of yours who is themselves a reseller has their own pool and is not counted beyond themselves."},"services":{"type":"array","items":{"$ref":"#/components/schemas/ResellerVendorServiceDraw"}}}},"ResolvedMalwareDetection":{"type":"object","description":"A malware finding that is no longer present. Same shape as `MalwareDetection` plus the instant it was first seen to be gone.\n\n⛔ `resolved_at` is evidence the finding **went away**; `resolution` is the only field that says who took it away. See `SiteSecurity.recent_resolutions`.","required":["id","path","signature","detected_at","resolved_at","resolution"],"properties":{"id":{"type":"string","format":"uuid","description":"The finding's id — what `restoreSiteSecurityDetection` addresses."},"can_restore":{"type":"boolean","description":"`true` for a file the platform cleaned (`scanner_removed`) or moved to quarantine (`quarantined`) — the one-click undo for a false positive."},"path":{"type":"string","description":"Path **relative to the site's document root** — never absolute, which would disclose the host account handle and the fleet's filesystem layout (§2.4)."},"signature":{"type":"string","description":"The scanner's detection name, shown verbatim."},"detected_at":{"type":"string","format":"date-time"},"resolved_at":{"type":"string","format":"date-time","description":"When a scan first found this finding absent. Never null — a null `resolved_at` is what makes a finding *live*, and those are in `detections`."},"resolution":{"type":"string","enum":["unknown","scanner_removed","no_longer_present","quarantined"],"description":"**How** it stopped being reported — the attribution `resolved_at` cannot carry.\n\n`quarantined` (owner D22, Q71) — the platform moved this file (a phishing page) out of the site's public folder and KEPT it; `quarantine_path` says where.\n\n`scanner_removed` — the scanner reported, in its own payload, that it remediated this file. **This is the only value that licenses a client to say we removed it.** `no_longer_present` — a later complete scan did not report it and nothing said why; the file may have been deleted by the customer, replaced by a deploy or renamed. `unknown` — resolved before the platform classified resolutions, or by a path that does not classify.\n\n⛔ `unknown` and `no_longer_present` must render identically. Neither claims we did anything, and collapsing either into `scanner_removed` fabricates a security claim about a file we may never have touched."},"quarantine_path":{"type":"string","description":"For `resolution: quarantined`, where the file is kept now, relative to the hosting account's home folder (`zinn-quarantine/<utc>/<path>`). Empty otherwise."}}},"RestoreQuote":{"type":"object","description":"What it costs to restore one lapsed domain from the registry's redemption period, or why it cannot be restored. Money is integer minor units + an ISO currency code; both are `null` when `restorable` is false, because a figure that cannot be honoured is worse than none.","required":["domain_id","fqdn","restorable","reason","amount_minor","currency","line_kind"],"properties":{"domain_id":{"$ref":"#/components/schemas/Uuid"},"fqdn":{"type":"string"},"restorable":{"type":"boolean"},"reason":{"type":["string","null"],"description":"Why not, when `restorable` is false. `NOT_IN_REDEMPTION` — the domain has not lapsed that far, so a renewal is what it needs. `NOT_PRICED` — the registry has no redemption product, or we hold no price for it in this currency."},"amount_minor":{"type":["integer","null"],"format":"int64"},"currency":{"type":["string","null"],"minLength":3,"maxLength":3},"line_kind":{"type":"string","description":"The cart line kind that buys it.","enum":["domain_restore"]}}},"ReviewProfile":{"type":"object","description":"One business's identity on one review platform. `profile_id` is that platform's own identifier — a `place_id`, a domain, a `url_path` — and is opaque.","required":["platform","profile_id"],"properties":{"platform":{"type":"string","enum":["google","trustpilot","tripadvisor"]},"profile_id":{"type":"string"},"name":{"type":"string"},"address":{"type":"string"},"url":{"type":"string"}}},"Runtime":{"type":"string","description":"The runtime the web server serves the site with. `node`, `python` and `ruby` are long-lived application processes the web server itself runs (docs/715); `dotnet` is one the platform supervises and the web server proxies to (docs/681 §6b).","enum":["static","php","node","python","ruby","dotnet"]},"RuntimeDetectionSummary":{"type":"object","description":"One thing the runtime sensor saw on a customer's site.\n\n⛔ The sensor's raw output line is deliberately **not** on this schema. It carries absolute host paths, the site's host account handle and the server's own identifiers — the same disclosure `last_scan_error_code` exists to prevent, and on the footprint-free product line, naming the host is the thing the product is sold to avoid. Staff read the raw line on the admin runtime-detections endpoint.","required":["rule","priority","detected_at","tags"],"properties":{"rule":{"type":"string","description":"The detection rule that fired, e.g. `Read sensitive file untrusted`."},"priority":{"type":"string","description":"The rule's severity. Only `warning` and above reach this endpoint — informational detections are the overwhelming majority and are staff-facing only."},"detected_at":{"type":"string","format":"date-time"},"tags":{"type":"array","items":{"type":"string"},"description":"The rule's tags, e.g. `mitre_credential_access`."}}},"SellableLineKind":{"type":"string","description":"The line kinds a cart will accept **today** — the write-side subset of `LineKind`.\n\nNarrower than `LineKind` on purpose. `LineKind` is what a line can *be* (a read\nshape, including values only historical rows carry); this is what the platform is\nwilling to *sell*. `hosting_addon` is the difference: it is a valid `LineKind` and\n`POST /v1/carts/{cartId}/lines` answers **422** for it, because nothing provisions\none. Adding a kind here without also giving it a fulfilment route fails the engine's\n`test_line_kind_fulfilment_routes` guard (#624).\n\n`extra` joined this list on 2026-09-09 and it **reverses a recorded decision**: an\naddon used to be bought only from its own screen, deliberately, so that there was one\npurchase path for it. The owner then asked for addons on the order configuration page\nwith a running total matching checkout to the minor unit, and those two requirements\ntogether make a basket line the only honest answer. There is still one constructor\nbehind both doors, so it is not a second purchase path — only a second door.\n","enum":["domain_register","domain_transfer","domain_renew","domain_restore","hosting_plan","privacy_addon","marketplace_package","aged_domain","compute_server","managed_database","boards_plan","extra","local_presence_addon"]},"SellableListingType":{"type":"object","required":["id","key","name","archetype","marketplace","field_count"],"properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"name":{"type":"string"},"archetype":{"type":"string"},"marketplace":{"type":"object","required":["key","name"],"properties":{"key":{"type":"string"},"name":{"type":"string"}}},"field_count":{"type":"integer","description":"How many fields this kind of Zinn® will ask for. Derived from the schema on read rather than stored, so it cannot drift from the form the seller then sees."}}},"SellableListingTypeList":{"type":"object","required":["data","total"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellableListingType"}},"total":{"type":"integer"}}},"SeoAccount":{"type":"object","required":["org_id","currency","balance_micros","is_low","is_empty","forecast","holds","unit_prices","site","settings","packs","buy_url"],"properties":{"org_id":{"type":"string","format":"uuid"},"currency":{"type":"string","enum":["USD"]},"balance_micros":{"type":"integer","description":"Zinn® credit balance","USD micros.":null},"is_low":{"type":"boolean"},"is_empty":{"type":"boolean"},"forecast":{"type":"object","required":["spend_micros","balance_micros","days","runs_out_on","short","currency"],"properties":{"spend_micros":{"type":"integer","description":"Scheduled pay-per-use work over the window."},"balance_micros":{"type":"integer"},"days":{"type":"integer"},"runs_out_on":{"type":["string","null"],"format":"date"},"short":{"type":"boolean","description":"The window's work costs more than the balance."},"currency":{"type":"string"}}},"holds":{"type":"object","required":["site","org_held_since","needed_micros"],"properties":{"site":{"type":"object","additionalProperties":{"type":"string","format":"date-time"},"description":"This site's products held for want of credit, and since when."},"org_held_since":{"type":["string","null"],"format":"date-time"},"needed_micros":{"type":"integer","description":"What the held work needed when it was held."}}},"unit_prices":{"type":"array","items":{"type":"object","required":["unit","price_micros"],"properties":{"unit":{"type":"string","enum":["rank_check","ai_prompt_run","index_check","link_check","audit_page","keyword_list","domain_report"]},"price_micros":{"type":"integer"}}}},"site":{"type":"object","required":["target_id","domain","funding","kinds","monthly_spend_cap_micros","spent_this_month_micros","cap_remaining_micros"],"properties":{"target_id":{"type":"string","format":"uuid"},"domain":{"type":"string"},"funding":{"type":"string","enum":["plan","credits"]},"kinds":{"type":"array","items":{"$ref":"#/components/schemas/VisibilityAuditKind"}},"monthly_spend_cap_micros":{"type":["integer","null"]},"spent_this_month_micros":{"type":"integer"},"cap_remaining_micros":{"type":["integer","null"]}}},"settings":{"type":"object","description":"The organization's auto top-up settings (as `getAiCredits` returns them).","additionalProperties":true},"packs":{"type":"array","description":"The Zinn® credit packs on sale (as `getAiCredits` returns them).","items":{"type":"object","additionalProperties":true}},"buy_url":{"type":"string","description":"Where \"Buy credits\" opens — in a new tab. It names the organisation the site spends from (`?org=<org_id>`), so the app opens on that account even when the person last used another one."}}},"SeoAllowanceMeter":{"type":"object","description":"One allowance axis. `metered: false` means this organisation is not metered on it — the product is not held, or arrives only in a hosting plan and keeps the pay-per-run model (`cap` and `remaining` are then `null`). `resets_at` is set for a monthly axis (the first instant of next month, UTC) and `null` for a standing one.","required":["metered","cap","used","remaining","resets_at"],"properties":{"metered":{"type":"boolean"},"cap":{"type":["integer","null"]},"used":{"type":"integer"},"remaining":{"type":["integer","null"]},"resets_at":{"type":["string","null"],"format":"date-time"}}},"SeoAllowances":{"type":"object","description":"Every allowance a V1-parity SEO tier sells, metered at the point of use. Monthly: `audits` (site audits), `refreshes` (backlink profile readings), `lists` (keyword research requests), `reports` (domain-score and competitor reads). Standing: `prompts` (AI questions asked per check, summed over AI targets), `links` (watched links), `profiles` (domains whose backlink profile is watched). A use past a cap is refused with `422` naming the allowance; nothing set up is deleted when a plan shrinks — the point of use stops at the cap, oldest first.","required":["prompts","audits","links","profiles","refreshes","lists","reports","audit_pages"],"properties":{"prompts":{"$ref":"#/components/schemas/SeoAllowanceMeter"},"audits":{"$ref":"#/components/schemas/SeoAllowanceMeter"},"links":{"$ref":"#/components/schemas/SeoAllowanceMeter"},"profiles":{"$ref":"#/components/schemas/SeoAllowanceMeter"},"refreshes":{"$ref":"#/components/schemas/SeoAllowanceMeter"},"lists":{"$ref":"#/components/schemas/SeoAllowanceMeter"},"reports":{"$ref":"#/components/schemas/SeoAllowanceMeter"},"audit_pages":{"type":"integer","description":"Pages one site audit may crawl — the largest any held tier grants."}}},"SeoAnalyticsReport":{"type":"object","required":["property","rows","row_count","currency"],"properties":{"property":{"type":"string"},"rows":{"type":"array","items":{"type":"object","properties":{"dimensions":{"type":"object","additionalProperties":{"type":"string"}},"metrics":{"type":"object","additionalProperties":{"type":"number"}}}}},"row_count":{"type":"integer"},"currency":{"type":"string"}}},"SeoAnalyticsReportRequest":{"type":"object","required":["dateRanges","metrics"],"properties":{"dateRanges":{"type":"array","minItems":1,"maxItems":4,"items":{"type":"object","required":["startDate","endDate"],"properties":{"startDate":{"type":"string","description":"YYYY-MM-DD, today, yesterday or NdaysAgo."},"endDate":{"type":"string"}}}},"dimensions":{"type":"array","maxItems":4,"items":{"type":"string","enum":["date","landingPage","landingPagePlusQueryString","pagePath","sessionDefaultChannelGroup","sessionSource","sessionMedium","country","deviceCategory"]}},"metrics":{"type":"array","minItems":1,"maxItems":8,"items":{"type":"string","enum":["sessions","engagedSessions","totalUsers","newUsers","keyEvents","conversions","totalRevenue","purchaseRevenue","ecommercePurchases","screenPageViews","bounceRate","engagementRate","averageSessionDuration","totalAdRevenue","publisherAdClicks","publisherAdImpressions"]},"description":"`totalAdRevenue`, `publisherAdClicks` and `publisherAdImpressions` are filled when the property is linked to AdSense (zs-711)."},"channel":{"type":"string","maxLength":60,"description":"e.g. Organic Search."},"ai_referrals":{"type":"boolean","default":false,"description":"Only sessions an AI assistant sent (ChatGPT, Perplexity, Gemini, Copilot, Claude, DeepSeek, Meta AI), matched on `sessionSource` by one fixed pattern (zs-708). Replaces `channel`."},"limit":{"type":"integer","minimum":1,"maximum":100000,"default":1000},"offset":{"type":"integer","minimum":0,"default":0}}},"SeoAuthorityMetrics":{"type":"object","description":"The figures themselves. **Every field is nullable**: `null` means the provider did not supply it, `0` means it supplied zero. Conflating the two would show a healthy domain as worthless.","properties":{"trust_flow":{"type":"integer","nullable":true,"minimum":0,"maximum":100,"description":"How trustworthy the linking neighbourhood is."},"citation_flow":{"type":"integer","nullable":true,"minimum":0,"maximum":100,"description":"Link volume regardless of quality. Read against trust_flow, never alone."},"referring_domains":{"type":"integer","nullable":true,"minimum":0,"description":"Distinct linking domains — the figure a link buyer actually judges on."},"external_backlinks":{"type":"integer","nullable":true,"minimum":0,"description":"Total inbound links; inflated by site-wide links, so never shown alone."},"topical_trust_flow_topic":{"type":"string","nullable":true,"description":"The provider's topical category for the domain."},"topical_trust_flow_value":{"type":"integer","nullable":true,"minimum":0,"maximum":100,"description":"Trust Flow within that topic — the number that matters for relevance."},"last_crawled_at":{"type":"string","format":"date-time","nullable":true,"description":"When the provider last saw a backlink. Separates a live profile from one that stopped being crawled years ago — both can show the same Trust Flow."}}},"SeoBusinessReviews":{"type":"object","required":["location","reviews","average","total","next"],"properties":{"location":{"type":"string"},"reviews":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"author":{"type":"string"},"rating":{"type":"string","enum":["ONE","TWO","THREE","FOUR","FIVE","STAR_RATING_UNSPECIFIED",""]},"comment":{"type":"string"},"created":{"type":"string"},"reply":{"type":"string"},"replied":{"type":"string"}}}},"average":{"type":"number"},"total":{"type":"integer"},"next":{"type":"string"}}},"SeoCdn":{"type":"object","required":["hosted","https","offered","zone","price"],"properties":{"hosted":{"type":"boolean","description":"The site is on Zinn® hosting (it keeps the Premium CDN tier)."},"https":{"type":"boolean"},"offered":{"type":"boolean"},"zone":{"oneOf":[{"$ref":"#/components/schemas/ZinnCdnZone"},{"type":"null"}]},"price":{"$ref":"#/components/schemas/ZinnCdnPrice"},"created":{"type":"boolean","description":"`enableSeoCdn` only: the zone was created by this call."}}},"SeoConnectAnswer":{"type":"object","required":["user_code"],"properties":{"user_code":{"type":"string","maxLength":20},"org_id":{"type":"string","format":"uuid"}}},"SeoConnectDeviceCode":{"type":"object","required":["device_code","user_code","verification_uri","verification_uri_complete","expires_in","interval"],"properties":{"device_code":{"type":"string","description":"Secret. Keep it on the server; never show it."},"user_code":{"type":"string","example":"BCDF-GHJK"},"verification_uri":{"type":"string","format":"uri"},"verification_uri_complete":{"type":"string","format":"uri","description":"Open this in a NEW TAB — the code is filled in."},"expires_in":{"type":"integer","description":"Seconds."},"interval":{"type":"integer","description":"Seconds between polls of `exchangeSeoConnect`."}}},"SeoConnectRequest":{"type":"object","required":["user_code","site_url","site_host","plugin_version","method","expires_in","suggested_org_id","approvable_org_ids"],"properties":{"user_code":{"type":"string"},"site_url":{"type":"string"},"site_host":{"type":"string"},"plugin_version":{"type":"string"},"method":{"type":"string","enum":["device","signup"]},"expires_in":{"type":"integer"},"suggested_org_id":{"type":["string","null"],"format":"uuid"},"approvable_org_ids":{"type":"array","items":{"type":"string","format":"uuid"}}}},"SeoConnectSignupInput":{"allOf":[{"$ref":"#/components/schemas/SeoConnectStartInput"},{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","maxLength":320},"name":{"type":"string","maxLength":200},"website":{"type":"string","description":"Honeypot. Leave empty; a filled value is answered `202` and discarded."}}}]},"SeoConnectSignupResult":{"allOf":[{"$ref":"#/components/schemas/SeoConnectDeviceCode"},{"type":"object","required":["account"],"properties":{"account":{"type":"string","enum":["created","exists"],"description":"`created` — check your e-mail to set a password; the site connects once you sign in. `exists` — sign in at `verification_uri_complete` and approve the site."},"email_warning":{"allOf":[{"$ref":"#/components/schemas/EmailWarning"}],"description":"Present only when the address's inbox is full (MAILQUOTA): the set-password e-mail may bounce, so the connect screen tells the site owner to clear it."}}}]},"SeoConnectStartInput":{"type":"object","required":["site_url","site_uuid","consent"],"properties":{"site_url":{"type":"string","format":"uri","maxLength":500},"site_uuid":{"type":"string","pattern":"^[A-Za-z0-9-]{8,64}$","description":"The plugin's own install id, kept in an option; a reconnect replaces the old token."},"plugin_version":{"type":"string","maxLength":40},"wp_version":{"type":"string","maxLength":40},"locale":{"type":"string","maxLength":16,"description":"The WordPress locale (`fr_FR`)."},"consent":{"type":"boolean","enum":[true],"description":"Literally `true` — the site owner agreed on the plugin's opt-in screen."}}},"SeoConnectToken":{"type":"object","required":["token","connection_id","scopes","site_url","org"],"properties":{"token":{"type":"string","description":"`zsc_…`, shown once."},"connection_id":{"type":"string","format":"uuid"},"scopes":{"type":"array","items":{"type":"string","enum":["seo.read","seo.run","seo.spend","seo.notices"]}},"site_url":{"type":"string"},"org":{"$ref":"#/components/schemas/SeoConnectionOrg"}}},"SeoConnectionOrg":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"SeoConnectionUpdate":{"type":"object","properties":{"scopes":{"type":"array","items":{"type":"string","enum":["seo.read","seo.run","seo.spend","seo.notices"]},"description":"Must include `seo.read`."},"monthly_spend_cap_micros":{"type":["integer","null"],"minimum":0}}},"SeoContentRun":{"type":"object","required":["id","kind","status","units","price_micros","charged_micros","refunded_micros","currency","result","error","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"kind":{"type":"string","enum":["originality","image"]},"status":{"type":"string","enum":["queued","complete","partial","failed"]},"units":{"type":"integer"},"price_micros":{"type":"integer"},"charged_micros":{"type":"integer"},"refunded_micros":{"type":"integer"},"currency":{"type":"string","example":"USD"},"result":{"type":"object","additionalProperties":true,"description":"Originality: `phrases` [{phrase, answered, copies [{url, domain, title, snippet}], own}], `answered`, `found_elsewhere`, `original_percent`. Image: `mime`."},"images":{"type":"array","items":{"type":"object","required":["mime","data"],"properties":{"mime":{"type":"string"},"data":{"type":"string","format":"byte"}}}},"error":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"}}},"SeoCrux":{"type":"object","required":["url","scope","form_factor","source","has_data","metrics","overall","collection_period","fetched_at","cached"],"properties":{"url":{"type":"string","description":"The origin or page that was looked up."},"scope":{"type":"string","enum":["origin","url"]},"form_factor":{"type":"string","enum":["phone","desktop"]},"source":{"type":"string","enum":["crux_api","pagespeed"]},"has_data":{"type":"boolean","description":"False when the site is below CrUX's traffic threshold."},"metrics":{"type":"object","description":"Keyed `lcp`, `inp`, `cls`, `fcp`, `ttfb`; absent metrics are omitted.","additionalProperties":{"$ref":"#/components/schemas/SeoCruxMetric"}},"overall":{"type":["string","null"],"enum":["good","needs_improvement","poor",null],"description":"Google's Core Web Vitals assessment (LCP, INP and CLS all good = good)."},"collection_period":{"type":["object","null"],"properties":{"first_date":{"type":"string","format":"date"},"last_date":{"type":"string","format":"date"}}},"fetched_at":{"type":"string","format":"date-time"},"cached":{"type":"boolean"}}},"SeoCruxMetric":{"type":"object","required":["p75","unit","rating"],"properties":{"p75":{"type":["number","null"]},"unit":{"type":"string","enum":["ms","score"]},"rating":{"type":["string","null"],"enum":["good","needs_improvement","poor",null]},"good":{"type":"number","description":"Share of visits rated good (0-1)."},"needs_improvement":{"type":"number"},"poor":{"type":"number"}}},"SeoDataAccount":{"type":"object","required":["vendor","key_hint","status","status_reason","allowance","checked_at","connected_at"],"properties":{"vendor":{"type":"string"},"key_hint":{"type":"string","description":"The last four characters of the key — never more."},"status":{"type":"string","enum":["active","rejected","removed"]},"status_reason":{"type":"string"},"allowance":{"type":"object","description":"What the vendor last reported for free, read at `checked_at`.","properties":{"plan":{"type":"string"},"units_left":{"type":["integer","null"]},"units_limit":{"type":["integer","null"]},"resets_at":{"type":["string","null"],"format":"date-time"}}},"checked_at":{"type":["string","null"],"format":"date-time"},"connected_at":{"type":["string","null"],"format":"date-time"}}},"SeoDataAlertRule":{"type":"object","required":["metric","when","by"],"properties":{"metric":{"type":"string","maxLength":40},"when":{"type":"string","enum":["drops","rises","above","below"]},"by":{"type":"string","description":"A decimal number of 0 or more (more than 0 for drops / rises)."}}},"SeoDataEstimate":{"type":"object","required":["vendor","unit","domains","units_per_run","runs_per_month","units_per_month","units_left","credit_micros_per_run","credit_micros_per_month"],"properties":{"vendor":{"type":"string"},"unit":{"type":"string"},"domains":{"type":"integer"},"units_per_run":{"type":"integer"},"runs_per_month":{"type":"integer"},"units_per_month":{"type":"integer"},"units_left":{"type":["integer","null"]},"credit_micros_per_run":{"type":["integer","null"]},"credit_micros_per_month":{"type":["integer","null"]}}},"SeoDataFeed":{"type":"object","required":["vendor","show","track","alerts","cadence_days","state","resume_at","next_due_at","last_succeeded_at","last_units","last_error"],"properties":{"vendor":{"type":"string"},"show":{"type":"array","items":{"type":"string"}},"track":{"type":"array","items":{"type":"string"}},"alerts":{"type":"array","items":{"$ref":"#/components/schemas/SeoDataAlertRule"}},"cadence_days":{"type":"integer"},"state":{"type":"string","enum":["active","paused_quota","paused_credit","paused_key","paused_user"]},"resume_at":{"type":["string","null"],"format":"date-time","description":"When a quota pause lifts."},"next_due_at":{"type":["string","null"],"format":"date-time"},"last_succeeded_at":{"type":["string","null"],"format":"date-time"},"last_units":{"type":"integer","description":"Vendor units (Zinn® Authority — credit micros) the last check spent."},"last_error":{"type":"string"}}},"SeoDataFeedInput":{"type":"object","properties":{"show":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":40}},"track":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":40}},"alerts":{"type":"array","maxItems":20,"items":{"$ref":"#/components/schemas/SeoDataAlertRule"}},"cadence_days":{"type":"integer","enum":[1,7,30],"default":30},"enabled":{"type":"boolean","default":true}}},"SeoDataHistory":{"type":"object","required":["source","metric","attribution","attribution_url","series"],"properties":{"source":{"type":"string"},"metric":{"type":"string"},"attribution":{"type":"string"},"attribution_url":{"type":"string"},"series":{"type":"object","description":"`{domain: [{date, value}]}`, oldest first.","additionalProperties":{"type":"array","items":{"type":"object","required":["date","value"],"properties":{"date":{"type":"string","format":"date"},"value":{"type":["string","null"]}}}}}}},"SeoDataKeyInput":{"type":"object","properties":{"api_key":{"type":"string","maxLength":400,"writeOnly":true},"access_id":{"type":"string","maxLength":400,"writeOnly":true,"description":"Moz Links API v2 only."},"access_secret":{"type":"string","maxLength":400,"writeOnly":true,"description":"Moz Links API v2 only (the Secret Key that pairs with the Access ID)."},"database":{"type":"string","pattern":"^[a-z]{2,8}$","description":"Semrush regional database (default us)."}}},"SeoDataLatestCell":{"type":"object","required":["value",true,"previous"],"properties":{"value":{"type":["string","null"],"description":"A decimal as text; null when the vendor gave no figure."},"true":{"type":"string","format":"date"},"previous":{"type":["string","null"]}}},"SeoDataMetricSpec":{"type":"object","required":["key","name","better","kind"],"properties":{"key":{"type":"string"},"name":{"type":"string","description":"The vendor's own name for the metric."},"better":{"type":"string","enum":["higher","lower"]},"kind":{"type":"string","enum":["score","count","position"]}}},"SeoDataOverview":{"type":"object","required":["org_id","sites","keys"],"properties":{"org_id":{"$ref":"#/components/schemas/Uuid"},"sites":{"type":"array","items":{"type":"object","required":["connection_id","site","site_url","metrics","paused","paused_names"],"properties":{"connection_id":{"$ref":"#/components/schemas/Uuid"},"site":{"type":"string"},"site_url":{"type":"string"},"paused":{"type":"array","items":{"type":"string"},"description":"The sources (keys) whose checks are paused for this site."},"paused_names":{"type":"array","items":{"type":"string"},"description":"The same paused sources by the vendor's own name (Open PageRank), in the same order, for display; a brand name is never translated."},"metrics":{"type":"array","items":{"type":"object","required":["source","metric","name","vendor_name","better","attribution","value",true,"previous"],"properties":{"source":{"type":"string"},"metric":{"type":"string"},"name":{"type":"string","description":"The metric's English name. A vendor's own metric name (Domain Rating) is shown as it is; a generic one (Referring domains) is shown from the screen's own translated catalogue, keyed by `metric`."},"vendor_name":{"type":"string","description":"The vendor's name (Open PageRank), filled verbatim into a translated generic label such as \"{vendor} position\", so a brand is never translated."},"better":{"type":"string","enum":["higher","lower"]},"attribution":{"type":"string"},"value":{"type":["string","null"]},"true":{"type":"string","format":"date"},"previous":{"type":["string","null"]}}}}}}},"keys":{"type":"array","items":{"type":"object","required":["vendor","status","key_hint"],"properties":{"vendor":{"type":"string"},"status":{"type":"string"},"key_hint":{"type":"string"}}}}}},"SeoDataSourceSpec":{"type":"object","required":["key","name","tier","attribution","attribution_url","key_url","free_key","key_fields","unit","plan_note","metrics"],"properties":{"key":{"type":"string","enum":["ahrefs_free","ahrefs","majestic","moz","semrush","se_ranking","openpagerank","zinn_authority"]},"name":{"type":"string"},"tier":{"type":"string","enum":["free","pro","credits"]},"attribution":{"type":"string","description":"Printed beside every value from this source."},"attribution_url":{"type":"string"},"key_url":{"type":"string","description":"Where the site owner gets a key (\"\" for Zinn® Authority)."},"free_key":{"type":"boolean"},"key_fields":{"type":"array","items":{"type":"string","enum":["api_key","access_id","access_secret"]}},"unit":{"type":"string","description":"The unit the vendor counts the allowance in."},"plan_note":{"type":"string"},"metrics":{"type":"array","items":{"$ref":"#/components/schemas/SeoDataMetricSpec"}}}},"SeoDataSources":{"type":"object","required":["site","sources","accounts","feeds","targets","latest","cadences","max_competitors","authority_price_micros"],"properties":{"site":{"type":"string"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/SeoDataSourceSpec"}},"accounts":{"type":"array","items":{"$ref":"#/components/schemas/SeoDataAccount"}},"feeds":{"type":"array","items":{"$ref":"#/components/schemas/SeoDataFeed"}},"targets":{"type":"array","items":{"$ref":"#/components/schemas/SeoDataTarget"}},"latest":{"type":"object","description":"`{source: {metric: {domain: cell}}}`.","additionalProperties":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/SeoDataLatestCell"}}}},"cadences":{"type":"array","items":{"type":"integer"}},"max_competitors":{"type":"integer"},"authority_price_micros":{"type":["integer","null"],"description":"Zinn® credit per Zinn® Authority check (USD micros)."}}},"SeoDataTarget":{"type":"object","required":["domain","role","label"],"properties":{"domain":{"type":"string"},"role":{"type":"string","enum":["own","competitor"]},"label":{"type":"string"}}},"SeoEdge":{"type":"object","required":["hosted","cdn","can_purge","ai_bots"],"properties":{"hosted":{"type":"boolean","description":"The connected site is on Zinn® hosting in this org."},"site_id":{"type":"string","format":"uuid"},"domain":{"type":"string"},"cdn":{"type":"string","description":"The CDN tier serving it (`free`, `premium`, `byo`), or `none`."},"can_purge":{"type":"boolean"},"ai_bots":{"type":["object","null"],"properties":{"supported":{"type":"boolean"},"mode":{"type":["string","null"],"enum":["allow","block",null]},"why_not":{"type":"string","enum":["","shared_zone","held","no_zone_control","unreadable"]}}}}},"SeoEdgeUpdateInput":{"type":"object","properties":{"purge_urls":{"type":"array","maxItems":200,"items":{"type":"string","maxLength":2000},"description":"Pages of this site to purge at the edge (at most 30 after de-duplication)."},"purge_everything":{"type":"boolean","default":false},"ai_bots":{"type":["string","null"],"enum":["allow","block",null]}}},"SeoEdgeUpdateResult":{"type":"object","required":["purge","ai_bots"],"properties":{"purge":{"type":["object","null"],"properties":{"site_id":{"type":"string","format":"uuid"},"purged":{"description":"`everything`, or the number of pages purged."},"server":{"type":"boolean","description":"The server's own cache was cleared too."},"edge":{"type":"boolean","description":"The CDN cache was purged."}}},"ai_bots":{"type":["object","null"],"properties":{"site_id":{"type":"string","format":"uuid"},"domain":{"type":"string"},"before":{"type":"string","enum":["allow","block"]},"mode":{"type":"string","enum":["allow","block"],"description":"Read back from the CDN after the write."},"changed":{"type":"boolean"}}}}},"SeoGoogleLink":{"type":"object","required":["connected","status","account_email","features","search_console_property","analytics_property","business_location","redirect_uri"],"properties":{"connected":{"type":"boolean"},"status":{"type":"string","enum":["none","pending","active","needs_reconnect"]},"account_email":{"type":"string"},"features":{"type":"array","items":{"type":"string","enum":["search_console","analytics","business","indexing"]}},"search_console_property":{"type":"string"},"analytics_property":{"type":"string"},"business_location":{"type":"string"},"redirect_uri":{"type":"string","description":"Where Google returns the browser (shown for support)."},"choices":{"type":"object","description":"Only with `choices=1`.","properties":{"search_console":{"type":"array","items":{"type":"object","properties":{"property":{"type":"string"},"permission":{"type":"string"}}}},"analytics":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"account":{"type":"string"}}}},"business":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"title":{"type":"string"},"website":{"type":"string"},"address":{"type":"string"}}}}}}}},"SeoGuard":{"type":"object","required":["enabled","site_url","key_urls","max_key_urls","tier","interval_minutes","pro_until","last_checked_at","next_check_at","incidents"],"properties":{"enabled":{"type":"boolean"},"site_url":{"type":"string"},"key_urls":{"type":"array","items":{"type":"string"}},"max_key_urls":{"type":"integer"},"tier":{"type":"string","enum":["free","pro"]},"interval_minutes":{"type":"integer","description":"1440 on Free","15 on a confirmed Pro licence.":null},"pro_until":{"type":["string","null"],"format":"date-time"},"last_checked_at":{"type":["string","null"],"format":"date-time"},"next_check_at":{"type":["string","null"],"format":"date-time"},"incidents":{"type":"array","description":"Every open problem, and those fixed in the last 30 days.","items":{"$ref":"#/components/schemas/SeoGuardIncident"}}}},"SeoGuardIncident":{"type":"object","required":["id","code","url","detail","opened_at","last_seen_at","resolved_at"],"properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string","enum":["site_down","home_noindex","page_noindex","robots_blocks_google","sitemap_error","canonicals_changed","home_title_missing","ssl_expiring"]},"url":{"type":"string"},"detail":{"type":"object","additionalProperties":true},"opened_at":{"type":"string","format":"date-time"},"last_seen_at":{"type":"string","format":"date-time"},"resolved_at":{"type":["string","null"],"format":"date-time"}}},"SeoGuardInput":{"type":"object","properties":{"enabled":{"type":"boolean"},"key_urls":{"type":"array","maxItems":40,"items":{"type":"string","maxLength":2000}},"licence":{"type":"object","required":["freemius_install_id","freemius_license_id"],"properties":{"freemius_install_id":{"type":"string","maxLength":32},"freemius_license_id":{"type":"string","maxLength":32}}},"rebaseline":{"type":"boolean","default":false},"check_now":{"type":"boolean","default":false}}},"SeoImageInput":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","maxLength":2000},"shape":{"type":"string","enum":["landscape","square","portrait"],"default":"landscape"}}},"SeoIndexCheck":{"type":"object","required":["id","status","urls","indexed","not_indexed","unknown","results","price_micros","charged_micros","refunded_micros","currency","created_at","finished_at"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","complete","failed"]},"urls":{"type":"integer"},"indexed":{"type":"integer"},"not_indexed":{"type":"integer"},"unknown":{"type":"integer","description":"Pages the index could not be asked about — refunded."},"results":{"type":"array","items":{"type":"object","required":["url","indexed","estimated_pages"],"properties":{"url":{"type":"string"},"indexed":{"type":["boolean","null"],"description":"`null` is unknown, never not-indexed."},"estimated_pages":{"type":["integer","null"],"description":"Google's own loose estimate for the address — a trend, not a count."}}}},"price_micros":{"type":"integer","description":"Price per page","USD micros.":null},"charged_micros":{"type":"integer","description":"Debited up front."},"refunded_micros":{"type":"integer","description":"Returned for unanswered pages."},"currency":{"type":"string","enum":["USD"]},"created_at":{"type":"string","format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"}}},"SeoIndexCheckInput":{"type":"object","required":["urls"],"properties":{"urls":{"type":"array","maxItems":2000,"items":{"type":"string","maxLength":2000},"description":"Addresses on the connected site; a scheme-less one is read as `https://`. At most 1,000 distinct addresses."}}},"SeoLookupPackRequest":{"type":"object","required":["quantity"],"properties":{"quantity":{"type":"integer","description":"The pack size to buy. Must be one offered by `GET /v1/seo/quota`.","example":25}}},"SeoLookupQuota":{"type":"object","description":"The research allowance meter, and what more costs.","required":["daily_allowance","used_today","remaining","can_look_up","packs"],"properties":{"daily_allowance":{"type":"integer","description":"Lookups included per day. `-1` means unlimited."},"used_today":{"type":"integer","description":"Plan-funded lookups run since midnight UTC."},"plan_remaining":{"type":"integer","minimum":0},"top_up_remaining":{"type":"integer","minimum":0,"description":"Purchased lookups still unspent. These do not expire."},"remaining":{"type":"integer","minimum":0},"is_unlimited":{"type":"boolean"},"can_look_up":{"type":"boolean","description":"Whether a lookup would be permitted right now. **Not** the same as `remaining > 0`: a suspended or unpaid account may have lookups left and still be refused."},"in_good_standing":{"type":"boolean"},"packs":{"type":"array","description":"Packs of extra lookups available to buy.","items":{"type":"object","required":["quantity","amount_minor","currency"],"properties":{"quantity":{"type":"integer","minimum":1},"amount_minor":{"type":"integer","description":"Price in integer minor units — never a decimal."},"currency":{"type":"string","minLength":3,"maxLength":3}}}}}},"SeoMetricsHistory":{"type":"object","description":"A domain's stored readings, **oldest first** — the series a trend chart plots. Points where the provider had never seen the domain carry `not_in_index: true` and null metrics; they are kept rather than dropped so a real gap is visible as a gap.","required":["fqdn","points"],"properties":{"fqdn":{"type":"string"},"points":{"type":"array","items":{"type":"object","required":["measured_at","not_in_index"],"properties":{"measured_at":{"type":"string","format":"date-time"},"not_in_index":{"type":"boolean"},"trust_flow":{"type":"integer","nullable":true,"minimum":0,"maximum":100},"citation_flow":{"type":"integer","nullable":true,"minimum":0,"maximum":100},"referring_domains":{"type":"integer","nullable":true,"minimum":0},"external_backlinks":{"type":"integer","nullable":true,"minimum":0}}}}}},"SeoNotice":{"type":"object","required":["id","kind","event_type","severity","domain","created_at","acked","data","title","message","site_email"],"properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["low_balance","forecast_short","credit_hold","credit_resumed","rank_drop","link_lost","deindexed","ai_mention_lost","ai_mention_gained","brand_mention","guard_incident","guard_resolved","review_new","review_rating_drop"]},"event_type":{"type":"string"},"severity":{"type":"string","enum":["info","success","warning","critical"]},"domain":{"type":"string","description":"The site it is about; empty for an organization-wide notice."},"created_at":{"type":"string","format":"date-time"},"acked":{"type":"boolean"},"data":{"type":"object","additionalProperties":true,"description":"The event's display-safe facts (amounts in USD micros, dates, the site's own phrases and addresses)."},"title":{"type":"string"},"message":{"type":"string"},"site_email":{"type":"object","required":["default_on","subject","text","html"],"properties":{"default_on":{"type":"boolean"},"subject":{"type":"string"},"text":{"type":"string"},"html":{"type":"string"}}}}},"SeoNoticeAckInput":{"type":"object","properties":{"ids":{"type":"array","maxItems":100,"items":{"type":"string","format":"uuid"}},"all":{"type":"boolean","default":false}}},"SeoNoticeFeed":{"type":"object","required":["locale","unread","items"],"properties":{"locale":{"type":"string","description":"The language the copy is in."},"unread":{"type":"integer","description":"Notices this site has not dismissed (the menu bubble)."},"items":{"type":"array","items":{"$ref":"#/components/schemas/SeoNotice"}}}},"SeoOfferCatalogue":{"type":"object","required":["currency","dashboard","offers"],"properties":{"currency":{"type":"string","enum":["USD"]},"dashboard":{"type":"string","description":"The dashboard address orders continue on."},"offers":{"type":"array","items":{"type":"object","required":["key","ledger","available","currency","products"],"properties":{"key":{"$ref":"#/components/schemas/SeoOfferKey"},"ledger":{"type":"string","description":"The Zinn® SEO feature id (zs-6xx)."},"available":{"type":"boolean"},"currency":{"type":"string","enum":["USD"]},"referral":{"type":"object","description":"`referral` only: the organization's own referral link when it is an approved affiliate.","properties":{"state":{"type":"string"},"url":{"type":"string"}}},"products":{"type":"array","items":{"type":"object","required":["key","kind","available"],"properties":{"key":{"type":"string"},"kind":{"type":"string","enum":["extra","plan","market","domain","bundle","aged","account","cdn","credits"]},"audience":{"type":"string","enum":["hosted","elsewhere"],"description":"zs-658: shown only to a site hosted with us, or only to one hosted elsewhere (the list a site receives is already filtered)."},"available":{"type":"boolean"},"facts":{"type":"object","additionalProperties":true,"description":"Read from the live row: `price_minor` and `interval` (extra, plan, domain, bundle with `list_minor`, `saving_minor`, `parts`), or `from_minor` and `listings` (market, aged), or `path` and `terms` (account), or for `cdn` `price_minor` (the monthly minimum), `per_gb_micros`, `monthly_minimum_micros` and `screen`, or `unit_micros`, `monthly_micros` and `path` (credits — a tool paid per use from Zinn® credits, priced from its live per-unit row in USD micros). Integer minor units of `currency` unless named micros."}}}}}}}}},"SeoOfferDomainResults":{"type":"object","required":["currency","results"],"properties":{"currency":{"type":"string","enum":["USD"]},"results":{"type":"array","items":{"type":"object","required":["fqdn","available","premium","reason"],"properties":{"fqdn":{"type":"string"},"available":{"type":"boolean"},"premium":{"type":"boolean"},"reason":{"type":"string"},"price":{"type":["object","null"],"additionalProperties":true}}}}}},"SeoOfferKey":{"type":"string","enum":["links","content","domains","wayback","vetting","reputation","citations","uptime","hosting","footprint","security","indexing","experts","services","cdn","backups","support","referral","bundle","update_guard","managed_ai","reseller_data"]},"SeoOfferListings":{"type":"object","required":["currency","listings"],"properties":{"currency":{"type":"string","enum":["USD"]},"listings":{"type":"array","items":{"type":"object","required":["id","title","summary","category","rating","sales","packages"],"properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"summary":{"type":"string"},"category":{"type":"string"},"rating":{"type":"integer"},"sales":{"type":"integer"},"packages":{"type":"array","items":{"type":"object","required":["id","name","price_minor","delivery_days"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"price_minor":{"type":"integer"},"delivery_days":{"type":"integer"}}}}}}}}},"SeoOfferOrder":{"type":"object","required":["id","offer","ledger","product","kind","label","context","url","status","watched","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"offer":{"$ref":"#/components/schemas/SeoOfferKey"},"ledger":{"type":"string"},"product":{"type":"string"},"kind":{"type":"string"},"label":{"type":"string"},"context":{"type":"object","additionalProperties":{"type":"string"}},"url":{"type":"string","description":"Where the order continues — opened in a new tab."},"status":{"type":"string","enum":["opened","basket","awaiting_payment","payment_failed","paid","brief_needed","in_progress","delivered","done","disputed","cancelled","refunded","expired"]},"total_minor":{"type":["integer","null"]},"tax_minor":{"type":["integer","null"]},"currency":{"type":"string"},"order_id":{"type":"string","format":"uuid"},"sale_id":{"type":"string","format":"uuid"},"placement_url":{"type":"string"},"watched":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"SeoOfferOrderInput":{"type":"object","required":["offer","product"],"properties":{"offer":{"$ref":"#/components/schemas/SeoOfferKey"},"product":{"type":"string","maxLength":24},"package_id":{"type":"string","format":"uuid"},"domain":{"type":"string","maxLength":253},"context":{"type":"object","properties":{"finding":{"type":"string","maxLength":80},"target_url":{"type":"string","maxLength":2000},"anchor":{"type":"string","maxLength":200},"brief":{"type":"string","maxLength":4000},"variant":{"type":"string","enum":["a","b"]}}}}},"SeoOfferOrderList":{"type":"object","required":["orders"],"properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/SeoOfferOrder"}}}},"SeoOriginalityInput":{"type":"object","required":["phrases"],"properties":{"phrases":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","maxLength":2000},"description":"The draft's sentences to search; those under 8 words and repeats are dropped, and at most 20 may remain."},"language":{"type":"string","maxLength":12,"example":"en"}}},"SeoOriginalityQuote":{"type":"object","required":["unit","units","price_micros","cost_micros","currency"],"properties":{"unit":{"type":"string","example":"originality_phrase"},"units":{"type":"integer"},"price_micros":{"type":"integer","description":"One sentence","USD micros.":null},"cost_micros":{"type":"integer","description":"The whole check","USD micros.":null},"currency":{"type":"string","example":"USD"}}},"SeoProductCatalogue":{"type":"object","required":["currency","products","cadences","grid_sizes"],"properties":{"currency":{"type":"string","enum":["USD"]},"products":{"type":"array","items":{"type":"object","required":["code","unit","feature","watchable","price_micros"],"properties":{"code":{"$ref":"#/components/schemas/SeoProductCode"},"unit":{"type":"string","description":"The unit it is billed in (`geo_point`, `review_read` …)."},"feature":{"type":"string","description":"The Zinn® SEO feature id."},"watchable":{"type":"boolean","description":"Whether it can run on a schedule."},"price_micros":{"type":"integer","description":"One unit","USD micros.":null}}}},"cadences":{"type":"array","items":{"type":"integer"},"description":"Allowed schedule periods in days."},"grid_sizes":{"type":"array","items":{"type":"integer"},"description":"Allowed local grid widths."}}},"SeoProductCode":{"type":"string","enum":["geo_grid","reviews","shopping","traffic","snapshot","youtube","amazon","sentiment","technology","questions","brief","domain_overview","visibility","trends"],"description":"`geo_grid` local rank grid (zs-520) · `reviews` Google/Trustpilot/Tripadvisor reviews (zs-521) · `shopping` Google Shopping price and position (zs-522) · `traffic` competitor traffic and top pages (zs-523) · `snapshot` results-page copy and picture (zs-524) · `youtube` YouTube rankings (zs-525) · `amazon` Amazon rankings (zs-526) · `sentiment` brand sentiment (zs-527) · `technology` technology lookup (zs-528) · `questions` \"People also ask\" (zs-529) · `brief` content brief from the top ten (zs-530) · `domain_overview` any domain's traffic, keywords, top pages and backlink summary (zs-653, billed in `domain_report`) · `visibility` share of search visibility over a phrase set (zs-654, `rank_check` per phrase) · `trends` Google Trends interest, seasonality and related searches (zs-709, `trends_check` per request)."},"SeoProductInput":{"type":"object","required":["params"],"properties":{"params":{"$ref":"#/components/schemas/SeoProductParams"}}},"SeoProductParams":{"type":"object","additionalProperties":true,"description":"The tool's parameters. `geo_grid`: `phrase`, `lat`, `lng`, `size` (3/5/7/9), `spacing_km` (0.2-10), `business` (Google id or name), `domain`, `language` — billed size x size points. `reviews`: `profiles` [{`platform` google|trustpilot|tripadvisor, `profile_id` place id / domain / Tripadvisor page, `name`}], `location` — billed per platform. `shopping` / `amazon`: `products` [{`title`, `sku`, `asin`}] (≤ 100), `sellers` (your seller names), `location`, `language` — billed per product. `youtube`: `phrases` (≤ 100), `own` (your channel or video links), `location`, `language` — per phrase. `snapshot`: `phrases` (≤ 25), `device`, `location`, `language` — per phrase. `traffic`: `domains` (≤ 10), `location`, `language` — per domain. `technology`: `domains` (≤ 10) — per domain. `sentiment`: `phrases` (≤ 10) — per phrase. `questions` / `brief`: `phrase`, `location`, `language` — one unit; `brief` also takes `stop` (≤ 400 of the writer's language's most common words, left out of its terms; never billed). `domain_overview`: `domains` (≤ 10), `location`, `language` — per domain. `visibility`: `phrases` (≤ 100), `rivals` (≤ 10 domains), `location`, `language` — per phrase. `trends`: `phrases` (≤ 5, compared on one scale), `time_range` past_90_days|past_12_months|past_5_years, `location`, `language` — one unit."},"SeoProductPlaces":{"type":"object","required":["places"],"properties":{"places":{"type":"array","items":{"type":"object","required":["name","cid","place_id","address","lat","lng","domain","category","rating","votes"],"properties":{"name":{"type":"string"},"cid":{"type":"string","description":"Google's id for the place — what the grid finds you by."},"place_id":{"type":"string","description":"What Google reviews are read by."},"address":{"type":"string"},"lat":{"type":["number","null"]},"lng":{"type":["number","null"]},"domain":{"type":"string"},"category":{"type":"string"},"rating":{"type":["number","null"]},"votes":{"type":"integer"}}}}}},"SeoProductPlacesInput":{"type":"object","required":["query"],"properties":{"query":{"type":"string","maxLength":200,"description":"The business name."},"lat":{"type":["number","null"]},"lng":{"type":["number","null"]},"location":{"type":"string","maxLength":120,"description":"A country, when no point is given."},"language":{"type":"string","maxLength":8}}},"SeoProductQuote":{"type":"object","required":["product","unit","units","price_micros","cost_micros","params","balance_micros","currency"],"properties":{"product":{"$ref":"#/components/schemas/SeoProductCode"},"unit":{"type":"string"},"units":{"type":"integer"},"price_micros":{"type":"integer","description":"One unit","USD micros.":null},"cost_micros":{"type":"integer","description":"The whole run."},"params":{"$ref":"#/components/schemas/SeoProductParams"},"balance_micros":{"type":"integer"},"currency":{"type":"string","enum":["USD"]}}},"SeoProductRun":{"type":"object","required":["id","product","status","params","units","price_micros","charged_micros","refunded_micros","currency","result","alerts","watch_id","error","created_at","finished_at"],"properties":{"id":{"type":"string","format":"uuid"},"product":{"$ref":"#/components/schemas/SeoProductCode"},"status":{"type":"string","enum":["queued","complete","partial","failed"],"description":"`partial`: some units answered and paid, the rest refunded. `failed`: refunded in full."},"params":{"$ref":"#/components/schemas/SeoProductParams"},"units":{"type":"integer"},"price_micros":{"type":"integer"},"charged_micros":{"type":"integer","description":"Debited up front."},"refunded_micros":{"type":"integer","description":"Returned for what was not answered."},"currency":{"type":"string","enum":["USD"]},"result":{"type":"object","additionalProperties":true,"description":"The tool's answer. Every item carries `answered`; an unanswered item is refunded and is never a measurement. `geo_grid`: `points` [{lat, lng, position|null, top, answered}], `found_at`, `top3_at`, `average_position`. `reviews`: `platforms` [{platform, rating, review_count, unanswered_negative, reviews}]. `shopping`/`amazon`: `products` [{our_position, our_price_minor, cheapest_price_minor, currency, offers}]. `youtube`: `phrases` [{position, results}]. `snapshot`: `phrases` [{own_position, features, entries, has_screenshot}]. `traffic`: `domains` [{monthly_visits, keywords, value_minor, top_pages}]. `technology`: `domains` [{found, groups}]. `sentiment`: `phrases` [{total, positive, neutral, negative, score, top_domains}]. `questions`: `questions` [{question, answer, source_url}]. `brief`: `median_words`, `questions`, `terms`, `term_stats` [{term, pages, min, median, max}] (terms several top pages share and how often each uses them), `entities` [{name, pages}], `page_questions`, `pages` [{url, title, words, headings, outline [{level, text}], read}] — the content optimiser's model (zs-766); the pages' text is never returned or stored. `domain_overview`: `domains` [{monthly_visits|null, keywords|null, top3, top10, top_keywords, top_pages, backlinks|null}]. `visibility`: `own`, `domains` [{domain, visibility %}], `leaders`, `pages` [{url, visibility}], `phrases` [{positions, url, top}]. `trends`: `time_range`, `phrases` [{phrase, average, points [{date, value|null}], top, rising, seasonality [{month, value}]}]."},"alerts":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Reviews: `new_reviews` and `rating_drop` since the previous reading (a first reading is a baseline)."},"watch_id":{"type":["string","null"],"format":"uuid"},"error":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"}}},"SeoProductRunList":{"type":"object","required":["runs"],"properties":{"runs":{"type":"array","items":{"$ref":"#/components/schemas/SeoProductRun"}}}},"SeoProductWatch":{"type":"object","required":["id","product","params","cadence_days","active","next_due_at","last_attempted_at","last_run_id","held_since","last_skip","cost_per_run_micros","cost_30d_micros","currency"],"properties":{"id":{"type":"string","format":"uuid"},"product":{"$ref":"#/components/schemas/SeoProductCode"},"params":{"$ref":"#/components/schemas/SeoProductParams"},"cadence_days":{"type":"integer"},"active":{"type":"boolean"},"next_due_at":{"type":["string","null"],"format":"date-time"},"last_attempted_at":{"type":["string","null"],"format":"date-time"},"last_run_id":{"type":["string","null"],"format":"uuid"},"held_since":{"type":["string","null"],"format":"date-time","description":"Paused for want of credit since then; carries on by itself after a top-up."},"last_skip":{"type":"string","description":"Why the last scheduled run did not happen (`insufficient_credit`, `spend_cap` …)."},"cost_per_run_micros":{"type":"integer"},"cost_30d_micros":{"type":"integer"},"currency":{"type":"string","enum":["USD"]}}},"SeoProductWatchInput":{"type":"object","required":["product","params"],"properties":{"product":{"$ref":"#/components/schemas/SeoProductCode"},"params":{"$ref":"#/components/schemas/SeoProductParams"},"cadence_days":{"type":"integer","enum":[1,7,30],"default":7}}},"SeoProductWatchList":{"type":"object","required":["watches"],"properties":{"watches":{"type":"array","items":{"$ref":"#/components/schemas/SeoProductWatch"}}}},"SeoProductWatchPatch":{"type":"object","properties":{"params":{"$ref":"#/components/schemas/SeoProductParams"},"cadence_days":{"type":"integer","enum":[1,7,30]},"active":{"type":"boolean"}}},"SeoProvider":{"type":"object","required":["provider","name","connected","platform_available","capabilities"],"properties":{"provider":{"type":"string","description":"The identifier used when connecting a key, e.g. `seo_ahrefs`."},"name":{"type":"string","description":"The provider's display name."},"connected":{"type":"boolean","description":"Whether a working client can be built from your stored credential right now. Measured rather than recorded — a key revoked at the provider reports false."},"platform_available":{"type":"boolean","description":"Whether Zinn® holds its own account with this provider AND your plan or add-on lets you draw on it. False for providers Zinn® holds no account with at all, in which case connecting your own key is the only route."},"capabilities":{"type":"array","items":{"type":"string"},"description":"Which metrics this provider can supply."}}},"SeoProviderList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SeoProvider"}}}},"SeoResearchInput":{"type":"object","properties":{"seed":{"type":"string","maxLength":120,"description":"`keywords` only: suggestions around this phrase."},"page_url":{"type":"string","maxLength":2000,"description":"`keywords` only: one page of the site."},"location":{"type":"string","maxLength":120,"description":"The market the question is asked in, in the customer's own words — \"Germany\", \"de\" — exactly as `TrackedKeyword.location`. Blank is the default market. A market that cannot be resolved is never guessed: the run uses the default market and the audit summary's `market.resolved` is `false`, so a screen can say which market the numbers are from."},"language":{"type":"string","maxLength":8,"description":"The results language for `location` (\"de\"). Blank is the default."},"competitor":{"type":"string","maxLength":253,"description":"`gap` only: one rival domain. The run then also reads the phrases that domain ranks for and stores, as the audit summary's `gap`, the ones the site does not rank for (`keywords`: `keyword`, `position`, `search_volume`, `url`), with `compared`, `own_checked`, `their_checked` and `own_complete`. `own_complete: false` means the site ranks for more phrases than one report reads, so a listed phrase is \"not among its strongest\", not proven absent; `compared: false` means a list could not be read and NO gap is reported. Not a domain, or the site itself, is refused `422` before anything is spent. Same price as a `gap` run without it."}}},"SeoSearchAnalytics":{"type":"object","required":["property","query","rows","more"],"properties":{"property":{"type":"string"},"query":{"type":"object","additionalProperties":true,"description":"The query as sent to Google."},"rows":{"type":"array","items":{"type":"object","required":["keys","clicks","impressions","ctr","position"],"properties":{"keys":{"type":"array","items":{"type":"string"}},"clicks":{"type":"integer"},"impressions":{"type":"integer"},"ctr":{"type":"number"},"position":{"type":"number"}}}},"more":{"type":"boolean","description":"The page was full; ask again with the next startRow."}}},"SeoSearchAnalyticsQuery":{"type":"object","required":["startDate","endDate"],"properties":{"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"dimensions":{"type":"array","maxItems":4,"items":{"type":"string","enum":["date","hour","query","page","country","device","searchAppearance"]}},"type":{"type":"string","enum":["web","image","video","news","discover","googleNews"],"default":"web"},"rowLimit":{"type":"integer","minimum":1,"maximum":25000,"default":1000},"startRow":{"type":"integer","minimum":0,"default":0},"dataState":{"type":"string","enum":["final","all","hourly_all"],"default":"final","description":"hourly_all with the hour dimension: recent data hour by hour."},"aggregationType":{"type":"string","enum":["auto","byPage","byProperty"]},"dimensionFilterGroups":{"type":"array","maxItems":3,"items":{"type":"object","properties":{"filters":{"type":"array","maxItems":10,"items":{"type":"object","required":["dimension","expression"],"properties":{"dimension":{"type":"string","enum":["query","page","country","device","searchAppearance"]},"operator":{"type":"string","enum":["equals","notEquals","contains","notContains","includingRegex","excludingRegex"]},"expression":{"type":"string","maxLength":4096}}}}}}}}},"SeoSiteCheck":{"type":"object","required":["id","kind","url","status","result","error","spent_micros","currency","created_at","finished_at"],"properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["cloak","lab"]},"url":{"type":"string"},"status":{"type":"string","enum":["queued","complete","failed"]},"result":{"type":"object","additionalProperties":true,"description":"Cloak: `verdict` (`same`, `differs`, `cloaked`, `unreadable`), `signals`, `similarity_bps`, `spam_terms_for_bot`, `extra_link_hosts_for_bot`, `visitor`, `googlebot`, `limits`. Lab: `performance`, `accessibility`, `best_practices`, `seo` (0-100), `lcp_ms`, `cls_milli`, `inp_ms`, `ttfb_ms`, `fcp_ms`, `opportunities`; `free_reason` when it cost nothing."},"error":{"type":"string"},"spent_micros":{"type":"integer","description":"Net Zinn® credits taken","read from the ledger.":null},"currency":{"type":"string","enum":["USD"]},"created_at":{"type":"string","format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"}}},"SeoSiteCheckInput":{"type":"object","required":["url"],"properties":{"url":{"type":"string","maxLength":2000,"description":"A page on the connected site."}}},"SeoSiteConnection":{"type":"object","required":["connection_id","org_id","site_url","site_uuid","status","scopes","method","token_hint","plugin_version","created_at","last_used_at","revoked_at","revoked_by","target_id","monthly_spend_cap_micros"],"properties":{"connection_id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"site_url":{"type":"string"},"site_uuid":{"type":"string"},"status":{"type":"string","enum":["active","revoked"]},"scopes":{"type":"array","items":{"type":"string"}},"method":{"type":"string","enum":["device","signup"]},"token_hint":{"type":"string","description":"The first eight characters after `zsc_`."},"plugin_version":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"last_used_at":{"type":["string","null"],"format":"date-time"},"revoked_at":{"type":["string","null"],"format":"date-time"},"revoked_by":{"type":["string","null"],"enum":["site","user","staff","replaced",null]},"target_id":{"type":["string","null"],"format":"uuid","description":"The site's own watch-list row (`getSeoSiteTarget`), once it has one."},"monthly_spend_cap_micros":{"type":["integer","null"],"minimum":0,"description":"The most Zinn® credit this site's tools may spend per calendar month, USD micros; `null` is no limit. Set with `updateOrgSeoConnection`."}}},"SeoSiteConnectionPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SeoSiteConnection"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"SeoSiteConnectionSelf":{"allOf":[{"$ref":"#/components/schemas/SeoSiteConnection"},{"type":"object","required":["org"],"properties":{"org":{"$ref":"#/components/schemas/SeoConnectionOrg"}}}]},"SeoSitemapStatus":{"type":"object","required":["path","errors","warnings","submitted"],"properties":{"path":{"type":"string"},"last_submitted":{"type":"string"},"last_downloaded":{"type":"string"},"pending":{"type":"boolean"},"is_index":{"type":"boolean"},"warnings":{"type":"integer"},"errors":{"type":"integer"},"submitted":{"type":"integer","description":"Addresses Google read from it."}}},"SeoUrlInspection":{"type":"object","required":["url","verdict","coverage"],"properties":{"url":{"type":"string"},"verdict":{"type":"string","description":"PASS, PARTIAL, FAIL or NEUTRAL (Google's words)."},"coverage":{"type":"string"},"indexing":{"type":"string"},"robots":{"type":"string"},"fetch":{"type":"string"},"last_crawl":{"type":"string"},"google_canonical":{"type":"string"},"user_canonical":{"type":"string"},"crawled_as":{"type":"string"},"sitemaps":{"type":"array","items":{"type":"string"}},"mobile":{"type":"string"},"rich_results":{"type":"string"},"link":{"type":"string","description":"The same report in Search Console."}}},"SeoV2Catalogue":{"type":"object","required":["products","owned"],"properties":{"products":{"type":"array","items":{"type":"object","required":["code","name","category","price_minor","currency","interval","screen","context","feature","buy_url"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"price_minor":{"type":"integer","description":"Price in minor units of `currency` (never a float)."},"currency":{"type":"string"},"interval":{"type":"string","description":"`one_off` or `monthly` (the catalogue's own value)."},"screen":{"type":"string","description":"The plugin screen (view id) that offers it."},"context":{"type":"string","description":"Where on that screen."},"feature":{"type":"string","description":"The Zinn® SEO feature id."},"buy_url":{"type":"string","description":"The product's page in the Zinn® app, naming the account (opened in a new tab; empty when the app address is not configured)."},"offer":{"type":["string","null"],"description":"The offer (`createSeoOfferOrder`) that orders it into a basket, when there is one; null: open `buy_url`."},"offer_product":{"type":["string","null"],"description":"The offer's product key for it."}}}},"owned":{"type":"array","items":{"type":"object","required":["code","name","category","status","since"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"status":{"type":"string","enum":["pending","fulfilling","awaiting_staff","completed"]},"since":{"type":"string","format":"date-time"}}}}}},"SeoWorkEntryInput":{"type":"object","required":["id","kind","count","date"],"properties":{"id":{"type":"string","pattern":"^[A-Za-z0-9._:-]{1,80}$","description":"The plugin's own stable id for this entry."},"kind":{"type":"string","enum":["meta_updated","schema_added","redirect_added","broken_link_fixed","internal_link_added","image_alt_added","content_optimised","sitemap_submitted","indexing_requested","issue_resolved"]},"count":{"type":"integer","minimum":1,"maximum":100000},"date":{"type":"string","format":"date","description":"Within the last 400 days."}}},"SessionOffering":{"type":"object","required":["currencies","default_currency","currency_switcher","locales","default_locale","language_switcher","restricted"],"properties":{"currencies":{"type":"array","description":"The currencies this viewer may be quoted in. Never empty.","items":{"type":"string","minLength":3,"maxLength":3}},"default_currency":{"type":"string","description":"Always a member of `currencies`."},"currency_switcher":{"type":"boolean","description":"`false` means render no currency control at all — not a disabled one."},"locales":{"type":"array","description":"The languages this viewer may read the panel in. Never empty.","items":{"type":"string"}},"default_locale":{"type":"string","description":"Always a member of `locales`."},"language_switcher":{"type":"boolean","description":"`false` means render no language control at all."},"restricted":{"type":"boolean","description":"A reseller stands between this viewer and Zinn®. Explicit rather than inferred: a reseller who has narrowed nothing returns identical lists to no reseller at all."}}},"SetComputeSpendCapRequest":{"type":"object","required":["monthly_cap_minor"],"additionalProperties":false,"properties":{"monthly_cap_minor":{"type":["integer","null"],"minimum":0,"description":"The new limit in minor units of the billing currency, or `null` to clear it."},"org_id":{"type":["string","null"],"format":"uuid","description":"Required only when the caller belongs to more than one organisation."}}},"SharedAgencyBoardActivity":{"type":"object","required":["id","verb","created_at","actor_label"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"verb":{"type":"string"},"payload":{"type":"object","additionalProperties":true},"card_id":{"type":"string","format":"uuid","nullable":true},"created_at":{"type":"string","format":"date-time"},"actor_label":{"type":"string","description":"⚖️ **Who did it, as the CLIENT is allowed to see it.** Owner ruling 2026-09-01: a client is never shown an individual member of the agency's staff, so anything the agency did is attributed to the agency ORGANISATION by name. The client's own colleagues ARE named — a client who cannot see which of their own people answered a question has been given half a feed. ⛔ A rendered label, deliberately not an `AgencyBoardActor`: there is no field here a staff member's name or email could travel in even by accident."},"actor_is_client":{"type":"boolean","description":"Whether this was done by the client's own side."},"occurrences":{"type":"integer","minimum":1,"description":"How many times this act happened. See `AgencyBoardActivity.occurrences`."},"last_at":{"type":"string","format":"date-time","description":"When the most recent occurrence happened."}}},"SharedAgencyBoardActivityList":{"type":"object","required":["items","total","returned"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SharedAgencyBoardActivity"}},"total":{"type":"integer","description":"Every client-visible row on this board. ⛔ Reported because `items` is capped: this endpoint returned the latest 100 and said nothing about it, and a truncation nobody counts reads as a complete list (§2.50)."},"returned":{"type":"integer","description":"How many rows `items` actually holds."}}},"SharedAgencyBoardAttachment":{"type":"object","required":["id","card_id","filename"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"card_id":{"$ref":"#/components/schemas/Uuid"},"filename":{"type":"string"},"content_type":{"type":"string"},"size_bytes":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}},"SharedAgencyBoardCard":{"type":"object","required":["id","column_id","title"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"column_id":{"$ref":"#/components/schemas/Uuid"},"title":{"type":"string"},"body":{"type":"string"},"due_at":{"type":"string","format":"date-time","nullable":true},"raised_by_us":{"type":"boolean","description":"Whether the client raised this card. Named from the READER's side, because this payload is only ever read by the client."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"SharedAgencyBoardColumn":{"type":"object","required":["id","name","position","is_intake"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"name":{"type":"string"},"position":{"type":"integer"},"is_intake":{"type":"boolean"}}},"SharedAgencyBoardComment":{"type":"object","required":["id","card_id","body","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"card_id":{"$ref":"#/components/schemas/Uuid"},"body":{"type":"string"},"from_client":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"author_label":{"type":"string","description":"Who wrote it, as the client may see it — the agency's organisation name for anything the agency wrote, the person's name for the client's own colleagues. Same ruling as `SharedAgencyBoardActivity.actor_label`."}}},"SharedAgencyBoardCommentCreate":{"type":"object","required":["body"],"properties":{"body":{"type":"string","maxLength":20000}}},"SharedAgencyBoardDetail":{"type":"object","required":["id","name","columns","cards"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"name":{"type":"string"},"description":{"type":"string"},"open_question_count":{"type":"integer"},"intake_column_id":{"type":"string","format":"uuid","nullable":true},"columns":{"type":"array","items":{"$ref":"#/components/schemas/SharedAgencyBoardColumn"}},"cards":{"type":"array","items":{"$ref":"#/components/schemas/SharedAgencyBoardCard"}},"comments":{"type":"array","items":{"$ref":"#/components/schemas/SharedAgencyBoardComment"}},"questions":{"type":"array","items":{"$ref":"#/components/schemas/SharedAgencyBoardQuestion"}},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/SharedAgencyBoardAttachment"}}}},"SharedAgencyBoardList":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SharedAgencyBoardSummary"}}}},"SharedAgencyBoardQuestion":{"type":"object","required":["id","card_id","body","status","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"card_id":{"$ref":"#/components/schemas/Uuid"},"body":{"type":"string"},"status":{"type":"string","enum":["open","answered","cancelled"]},"answer_body":{"type":"string"},"answered_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"SharedAgencyBoardRequestCreate":{"type":"object","required":["title"],"properties":{"title":{"type":"string","maxLength":300},"body":{"type":"string","maxLength":20000}}},"SharedAgencyBoardSummary":{"type":"object","required":["id","name","agency_org_id"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"name":{"type":"string"},"description":{"type":"string"},"agency_org_id":{"$ref":"#/components/schemas/Uuid"}}},"SharedBoard":{"type":"object","required":["status","role","requires_account","shared_by","sign_in","board"],"properties":{"status":{"type":"string","enum":["ok"]},"role":{"$ref":"#/components/schemas/AgencyBoardInviteRole"},"requires_account":{"type":"boolean","description":"Whether the visitor must sign in before they can do anything. `false` for a `viewer` link — they can read this board with no Zinn® account at all."},"shared_by":{"type":"string","description":"The **brand** whose board this is, resolved by walking up the organisation tree — so a reseller's client is told the reseller's name, not the client org's and not ours."},"sign_in":{"$ref":"#/components/schemas/SharedBoardSignIn"},"board":{"allOf":[{"$ref":"#/components/schemas/SharedAgencyBoardDetail"}],"description":"The client projection — the same field-listed view the agency's own client gets, produced by the same code. Anything marked internal is excluded at the queryset."}}},"SharedBoardExpired":{"type":"object","required":["status","detail"],"properties":{"status":{"type":"string","enum":["expired"]},"detail":{"type":"string"}}},"SharedBoardJoined":{"type":"object","required":["joined","board_id"],"properties":{"joined":{"type":"boolean"},"seated":{"type":"boolean","description":"Whether this call created the seat, as opposed to returning an existing one."},"role":{"$ref":"#/components/schemas/AgencyBoardInviteRole"},"board_id":{"$ref":"#/components/schemas/Uuid"},"membership_id":{"type":"string","format":"uuid","nullable":true},"detail":{"type":"string"}}},"SharedBoardSignIn":{"type":"object","required":["brand_name","sign_in_url","is_white_label"],"description":"Where this board's visitors sign in, and under whose name.\n\n⛔⛔ Computed by the engine from the board, because nothing downstream knows whose board it is: the dashboard reads one hardcoded OIDC authority and a marketing page has no organisation at all, so a landing page resolving its own sign-in link would resolve **ours** — sending a reseller's client to a stranger's login on the one journey the reseller white-labelled.","properties":{"brand_name":{"type":"string"},"logo_url":{"type":"string"},"primary_colour":{"type":"string"},"sign_in_url":{"type":"string","description":"The panel the brand is actually **serving**, so a reseller who has typed a hostname but not yet pointed DNS at it still sends their client somewhere that answers."},"is_white_label":{"type":"string","enum":["true","false"]}}},"ShowcaseEntryPublic":{"type":"object","required":["id","site_url","site_name","description","screenshot_url","approved_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"site_url":{"type":"string"},"site_name":{"type":"string"},"description":{"type":"string"},"screenshot_url":{"type":"string","format":"uri"},"approved_at":{"type":["string","null"],"format":"date-time"}}},"ShowcaseEntryPublicList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ShowcaseEntryPublic"}}}},"ShowcaseRequestCreated":{"type":"object","required":["reference","status"],"properties":{"reference":{"type":"string","description":"The ticket handle (`ZT-XXXXXX`)."},"status":{"$ref":"#/components/schemas/ShowcaseStatus"}}},"ShowcaseRequestInput":{"type":"object","required":["product","site_url","site_name","description","email","consent"],"properties":{"product":{"$ref":"#/components/schemas/PluginSupportProduct"},"site_url":{"type":"string","maxLength":500,"description":"The site's address (`https://` is assumed when missing). Stored without query or fragment."},"site_name":{"type":"string","maxLength":120},"description":{"type":"string","maxLength":500,"description":"A sentence or two about the site."},"email":{"type":"string","format":"email","maxLength":320},"name":{"type":"string","maxLength":200,"description":"The sender's own name."},"locale":{"type":"string","maxLength":16,"description":"The page language (`ar`, `pt-BR`)."},"consent":{"type":"boolean","description":"Must be literally `true` — the visitor agreed to the site being shown publicly."},"website":{"type":"string","description":"The honeypot. Leave empty; a filled one answers `202` and stores nothing."}}},"ShowcaseStatus":{"type":"string","description":"`pending` waits for staff; `approved` is public once its screenshot is `ready`; `removed` was declined or taken down.","enum":["pending","approved","removed"]},"SignupAccepted":{"type":"object","required":["status","resend_after_seconds"],"properties":{"status":{"type":"string","enum":["sent"]},"resend_after_seconds":{"type":"integer","minimum":0,"description":"How long the page waits before offering \"Resend\" again."}}},"SignupCompleteRequest":{"type":"object","additionalProperties":false,"required":["token","password"],"properties":{"token":{"type":"string","maxLength":200},"password":{"type":"string","format":"password","maxLength":256}}},"SignupCompleted":{"type":"object","required":["sign_in_url"],"properties":{"sign_in_url":{"type":"string","format":"uri","description":"A single-use sign-in link, valid about two minutes."}}},"SignupLinkState":{"type":"object","required":["state","email","intent","plan","trial"],"properties":{"state":{"type":"string","enum":["valid","expired","used","invalid","exists"],"description":"`valid` shows the password form; `expired` offers a new link; `used` and `exists` offer sign-in; `invalid` offers starting again."},"email":{"type":"string","description":"The address the link was sent to, or empty for an invalid token."},"intent":{"type":"string"},"plan":{"type":"string"},"trial":{"type":"string"}}},"SignupStartRequest":{"type":"object","additionalProperties":false,"required":["email"],"properties":{"email":{"type":"string","format":"email","maxLength":320},"locale":{"type":"string","maxLength":16,"default":"en","description":"The language the mail is written in and the account is created with."},"intent":{"type":"string","enum":["register","trial"],"default":"register"},"plan":{"type":"string","maxLength":64,"default":"","description":"The plan the person picked on the public site, carried to the dashboard."},"trial":{"type":"string","maxLength":64,"default":"","description":"The trial the person picked on the public site, carried to the dashboard."},"marketing_opt_out":{"type":"boolean","default":false,"description":"Ticked \"do not send me marketing email\"; stored on the account."}}},"SignupTokenRequest":{"type":"object","additionalProperties":false,"required":["token"],"properties":{"token":{"type":"string","maxLength":200}}},"Site":{"type":"object","required":["id","org_id","product_line","source","primary_domain","stack_type","runtime","status","created_at","server","disk"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"org_id":{"$ref":"#/components/schemas/Uuid"},"product_line":{"type":"string","description":"Product line code this site belongs to (CLAUDE.md §2.14).","example":"footprint_free"},"source":{"$ref":"#/components/schemas/SiteSource"},"blueprint_id":{"description":"The exact blueprint version the site was built from; null for imports.","anyOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]},"subscription_id":{"description":"The subscription entitling this site; null while unassigned.","anyOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]},"plan_code":{"description":"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 references — the name is marketing copy and can change without the offer changing.","anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"example":"pbn_25"},"plan_name":{"description":"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 — not an error).","anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"example":"PBN 25"},"domain_pointing":{"type":"object","nullable":true,"description":"**Whether this site's domain actually reaches us** (`docs/823`) — the compact form, for the row. `null` means we have never measured it, which a client renders as no badge rather than a healthy one: a tick we have not earned is the defect this field exists to remove.\n\nThe full answer, with the exact records or nameservers to set and what we observed, is `GET /v1/sites/{siteId}/domain-pointing`. It is not inlined here because a 50-row page must not carry a nameserver list.\n\n⛔ Distinct from the domain's lifecycle `status`. `connected` means the customer brought their own domain; it has never meant a visitor arrives.","required":["state","measured_at"],"properties":{"state":{"type":"string","enum":["moving_in","serving","serving_via_other_dns","propagating","awaiting_record","awaiting_pointing","pointed_elsewhere","zone_expired","unknown"]},"measured_at":{"type":"string","format":"date-time","nullable":true,"description":"When the VERDICT was reached, not when we last looked."}}},"seo":{"description":"**This site's search-index status and authority metrics, on the list row.**\n\nThe same readings `GET /v1/sites/{siteId}/index-check` and `/seo-metrics` return for one site, computed for a whole page at once so a customer can see which of their sites are not indexed without opening each one. Never triggers a provider lookup — both seams bill per call, so the list serves stored readings and freshness comes from the scheduled sweeps.\n\n⛔ `null` means **this response did not compute a summary** (a create response, a single-site fetch), not \"no data\". \"No data\" is `index_state: never_checked` / `seo_state: never_fetched`. A client that renders null as \"nothing yet\" says the same thing about a page it failed to load.","anyOf":[{"$ref":"#/components/schemas/SiteSeoSummary"},{"type":"null"}]},"primary_domain":{"$ref":"#/components/schemas/Hostname"},"parent_site_id":{"type":["string","null"],"format":"uuid","readOnly":true,"description":"The site this one is a standalone subdomain of (1105#32 C), or null. Site lists group a child under its parent from this field. Cleared when either site moves to another organisation or the parent is removed."},"preview_only":{"type":"boolean","readOnly":true,"description":"True while the site answers only on a platform preview hostname. Paid per-site checks (SEO authority, index and AI visibility) start once the customer adds their own domain; the dashboard shows that instead of an empty panel. Same predicate the billed sweeps use."},"dns_not_pointed":{"type":"boolean","readOnly":true,"description":"True when our serving check found that visitors to this site's domain do not reach our servers (the domain's DNS points somewhere else, or nowhere). The site itself is running; the dashboard shows \"DNS not pointed to us\" with the steps to fix it instead of a plain \"Active\"."},"migration_hold":{"type":"string","readOnly":true,"enum":["none","move_in_progress","moves_ended_points_elsewhere"],"description":"Why traffic for this site's domain is held back while it is the target of a move. `none` = not held. `move_in_progress` = a move is running; the switch-over publishes the domain. `moves_ended_points_elsewhere` = every move into this site has ended and the domain still points at the old host, so we do not take its traffic; point the domain at our nameservers or start a new move."},"name":{"type":"string","description":"Human label for the site; defaults to the primary domain.","maxLength":200,"example":"Acme Marketing Site"},"stack_type":{"$ref":"#/components/schemas/StackType"},"runtime":{"$ref":"#/components/schemas/Runtime"},"php_version":{"type":"string","maxLength":8,"description":"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, `POST /v1/sites` accepted a `php_version` that no response ever mentioned again. It is the **desired** state, not proof the box has switched; `GET /v1/sites/{siteId}/php-version` resolves the effective version (this value, or the line default) and lists what it may change to.","example":"8.4"},"status":{"$ref":"#/components/schemas/SiteStatus"},"status_reason":{"description":"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.","anyOf":[{"$ref":"#/components/schemas/SiteStatusReason"},{"type":"null"}]},"failed_step":{"type":"string","maxLength":16,"description":"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 write that clears `status_reason`) or failed before this was recorded. Answers the customer's \"how far did it get?\" without a sentence composed in the engine.","example":"dns"},"failed_activity":{"type":"string","maxLength":64,"description":"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 on a customer response and is what an operator needs to open the right subsystem, which a row saying only `provisioning_failed` never could. `\"\"` under the same rules as `failed_step`.","example":"create_dns_zone"},"install":{"description":"Row 45 (s1014, owner 2026-10-29): what the installing screen may honestly say, and whether Retry is valid - the same answer `retrySiteProvisioning` enforces. `null` unless the site is `pending`, `provisioning` or `failed`.","nullable":true,"allOf":[{"$ref":"#/components/schemas/SiteInstallState"}]},"provider_refusal":{"description":"R42 (owner 2026-10-18): a DNS or CDN provider REFUSED this domain - normal, and the customer's to route around. `null` unless the site is `failed` on a refusal. The site shows \"<network> would not accept <domain> - choose another network\", lists the networks `getSiteProviderOptions` offers minus the refusing one, and one click calls `retrySiteProvisioning` with the chosen `cdn_vendor` / `dns_vendor`. Codes only, never the provider's text.","nullable":true,"allOf":[{"$ref":"#/components/schemas/SiteProviderRefusal"}]},"provisioning_started_at":{"type":"string","format":"date-time","nullable":true,"readOnly":true,"description":"When the site last ENTERED `provisioning` - the start of the current build attempt, so a retried site's elapsed time and \"taking longer than expected\" count from the retry, not from `created_at`. `null` on a site that has not entered provisioning since this field was added; clients fall back to `created_at`."},"enforcement_error":{"type":"string","enum":["","config_rejected","stop_unconfirmed","start_unconfirmed","unverified"],"description":"Why the enforcement rung this site is on (suspended, restricted, quarantined, or a resume from one) was **not confirmed by its box**. `\"\"` when the last rung change was confirmed. A stop the box did not confirm is still recorded as stopped, because enforcement fails safe towards not serving, and this field is what stops anyone reading that status as verified. It clears on the next change the box confirms. A code the client localises, never vendor text.","example":""},"server":{"$ref":"#/components/schemas/SiteServer"},"disk":{"$ref":"#/components/schemas/SiteDisk"},"region":{"type":"string","description":"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 moves (pool exhaustion, a re-place after a failure), and reporting the stored request told a customer their site was in Falkenstein while it served from Nuremberg. Empty until the site is placed, where the stored value is the customer's own request and is echoed instead. For a site on the resold range this is the **data centre code** the customer chose (`lhr`), which is why `createSite` accepts it and validates it against the locations `listHostingLocations` offers.","maxLength":32,"example":"nbg1"},"cdn_vendor":{"type":"string","description":"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 back — never the resolved account, which stays undisclosed on a managed line.","maxLength":64,"example":"bunnycdn"},"dns_vendor":{"type":"string","description":"The DNS vendor this site's zone was pinned to, or `\"\"` when the footprint balancer chooses.","maxLength":64,"example":"bunny_dns"},"deploy_target":{"type":"string","description":"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 rendered raw. It names a *kind* of platform rather than a box, so unlike the fleet worker it leaks no co-tenancy; the client needs it to know whether a site has a hosting control surface at all.","example":"twentyi_shared"},"panel_connection_id":{"description":"**Which control panel this site's subscription lives on** — the `PanelConnection` from `GET /v1/panels/connections`. Set only when `deploy_target` is `plesk`; **null for every other target**, which is almost every site on the platform.\n\n⭐ Exposed because it is the only thing that makes a panel site *addressable*. A fleet site names its machine through the worker it is placed on and a resold site is found by a reseller-wide package search; a panel box is neither — it is one host among however many that organization has connected, reachable only by the credential stored against **this** connection. A client rendering a panel site's controls has to know which panel to send the customer to, and there is no second way to derive it.\n\n⛔ It is an id, not a co-tenancy leak: it names a panel the caller's own organization already connected and can already list. It never names one of our fleet boxes — `worker_id` stays unexposed for the reason the schema comment above gives.","anyOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]},"deletion_state":{"type":"string","enum":["none","scheduled","running","stalled","deleted"],"description":"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.\n\n⛔ **An axis of its own — do NOT fold it into `status`.** `status: deleting` means a teardown workflow is running; `deletion_state: scheduled` means a request is armed and the site is **still serving**, for the remainder of its grace period. Measured on production 2026-08-21: eight sites read `status: deleting`, while two freshly-scheduled ones read `status: failed`. A renderer that treats the two as one axis is wrong in both directions.\n\nBefore this field a scheduled site read `active` on every customer surface and then silently vanished at the end of its grace period; the only endpoint that knew was `GET /v1/sites/{siteId}/deletion`, and the only action that revealed it was a second `DELETE`, which errors.","example":"scheduled"},"deletion_scheduled_for":{"type":"string","format":"date-time","nullable":true,"description":"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 a customer cannot move under them.","example":"2026-08-28T09:14:00Z"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"SiteApmHotspot":{"type":"object","description":"One ranked cost — the slow plugin, PHP extension, PHP function or database query, folded across every profiled request in the window.","required":["kind","name","samples","total_ms","avg_duration_ms","calls"],"additionalProperties":false,"properties":{"kind":{"type":"string","enum":["wordpress_plugin","php_extension","php_function","database_query","other"],"description":"`other` is the fall-through, so a new vendor type degrades to a rendered row rather than to a 500 on a performance screen."},"name":{"type":"string","maxLength":160},"samples":{"type":"integer"},"total_ms":{"type":"integer"},"avg_duration_ms":{"type":"integer"},"calls":{"type":"integer"}}},"SiteApmSummary":{"type":"object","description":"Everything the APM panel renders, in one response.\n\n⛔ One payload rather than four endpoints, because the screen draws four panels at once and four round trips on an interactive path is what §2.16 forbids — and because `enrolment_state` must arrive WITH the data, so a screen showing nothing can say why.","required":["tracing","enrolment_state","enrolment_detail","last_collected_at","window_hours","p95_duration_ms","p95_sample_count","transactions","hotspots","timeline"],"additionalProperties":false,"properties":{"tracing":{"type":"boolean","description":"Whether the server is currently profiling this site."},"enrolment_state":{"type":"string","enum":["unknown","enrolled","refused","unsupported"],"description":"Why there may be no data. `unknown` — not collected yet. `enrolled` — collected, and the site was genuinely quiet. `refused` — the server would not start profiling. `unsupported` — hosting that cannot profile at all."},"enrolment_detail":{"type":"string","description":"The server's own sentence when it refused; empty otherwise."},"last_collected_at":{"type":"string","format":"date-time","nullable":true,"description":"When we last harvested this site, or null if never."},"window_hours":{"type":"integer","description":"The period these aggregates cover."},"p95_duration_ms":{"type":"integer","nullable":true,"description":"The 95th percentile of PHP time across EVERY request traced for this site in the window, in milliseconds.\n\n⚠️ This is the customer's OWN traffic. It is a different quantity from `/v1/sites/{siteId}/vitals`'s `ttfb_ms`, which is a Lighthouse LAB measurement from one synthetic run — a surface presenting both as \"speed\" is §2.54's adjacent-question defect, so the label must say which is which.\n\n⛔ `null` means *not enough traffic to state a percentile*, never zero."},"p95_sample_count":{"type":"integer","description":"How many requests `p95_duration_ms` was computed over. Shipped WITH it, always: a p95 over 30 requests and one over 30,000 are indistinguishable on screen otherwise (§2.44)."},"transactions":{"type":"array","description":"Pages ranked by total PHP time, heaviest first.","items":{"$ref":"#/components/schemas/SiteApmTransaction"}},"hotspots":{"type":"array","description":"Plugins, functions and queries ranked by total PHP time.","items":{"$ref":"#/components/schemas/SiteApmHotspot"}},"timeline":{"type":"array","description":"PHP execution time by hour, oldest first.","items":{"$ref":"#/components/schemas/SiteApmTimelinePoint"}}}},"SiteApmTimelinePoint":{"type":"object","description":"One hour of the site's PHP execution time.","required":["hour","requests","avg_duration_ms"],"additionalProperties":false,"properties":{"hour":{"type":"string","format":"date-time"},"requests":{"type":"integer"},"avg_duration_ms":{"type":"integer"}}},"SiteApmTrace":{"type":"object","description":"One profiled request kept whole.\n\n⛔ There is deliberately no `client_ip` field. The omission is enforced at the parse boundary — `engine.fleet.xray.SlowRequest` has no such attribute — so no layer beneath this schema could leak one even if somebody added the name here.","required":["id","transaction","method","path","duration_ms","throttled_ms","io_throttled_ms","hit_limits","has_error","error_text","cache_miss_reasons","started_at"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"transaction":{"type":"string","maxLength":200},"method":{"type":"string","maxLength":10},"path":{"type":"string","description":"The path as traced, before normalisation — so a developer can reproduce the exact request, which the grouped transaction label deliberately cannot express."},"duration_ms":{"type":"integer"},"throttled_ms":{"type":"integer"},"io_throttled_ms":{"type":"integer"},"hit_limits":{"type":"boolean"},"has_error":{"type":"boolean"},"error_text":{"type":"string"},"cache_miss_reasons":{"type":"array","description":"Why this request bypassed the page cache; empty when it was cacheable.","items":{"type":"string"}},"started_at":{"type":"string","format":"date-time"}}},"SiteApmTraceCost":{"type":"object","description":"One line of a kept request's breakdown — the function-level row.\n\n⭐ `location` is `file:line` relative to the customer's own document root; the leading account directory is a shared-hosting internal and is cut at the parse boundary.","required":["name","kind","duration_ms","percent","calls","query","location"],"additionalProperties":false,"properties":{"name":{"type":"string","maxLength":160},"kind":{"type":"string","enum":["wordpress_plugin","php_extension","php_function","database_query","other"]},"duration_ms":{"type":"integer"},"percent":{"type":"number","format":"float"},"calls":{"type":"integer"},"query":{"type":"string","description":"The already-redacted SQL for a `database_query` row, else empty. Literals are replaced by the vendor before we see them and are never restored here."},"location":{"type":"string","maxLength":512}}},"SiteApmTraceDetail":{"allOf":[{"$ref":"#/components/schemas/SiteApmTrace"},{"type":"object","description":"A kept request plus its function-level breakdown, heaviest first.","required":["costs"],"properties":{"costs":{"type":"array","items":{"$ref":"#/components/schemas/SiteApmTraceCost"}}}}]},"SiteApmTransaction":{"type":"object","description":"One page, aggregated over the requested window. The `transaction` is a NORMALISED path — `/2026/09/a-post/` and `/2026/08/another/` both fold to `/{year}/{month}/{slug}` — because ranking raw permalinks on a blog produces four hundred rows of one sample each and answers nothing.","required":["transaction","method","samples","total_ms","avg_duration_ms","p95_duration_ms","max_duration_ms","throttled_ms","error_count","cache_miss_count"],"additionalProperties":false,"properties":{"transaction":{"type":"string","maxLength":200},"method":{"type":"string","maxLength":10},"samples":{"type":"integer"},"total_ms":{"type":"integer"},"avg_duration_ms":{"type":"integer"},"p95_duration_ms":{"type":"integer","nullable":true,"description":"The 95th percentile of PHP time for this page, in milliseconds — 95% of these requests finished within it.\n\n⛔ `null` means *not enough requests to state a percentile*, and is NOT zero. A zero would read as \"instant\", which is the most flattering possible misreading of \"we do not know\" (§2.44). Below the engine's sample floor the 95th percentile is simply the maximum, which `max_duration_ms` already carries.\n\n⭐ Derived from a stored duration HISTOGRAM, not from a stored percentile: percentiles cannot be averaged, so a stored p95 could never be merged across a re-collected window nor summed across pages. A histogram is exactly additive."},"max_duration_ms":{"type":"integer"},"throttled_ms":{"type":"integer","description":"Milliseconds these requests spent **stopped** at the account's resource ceiling. Separate from the total on purpose: it is what turns *\"the site is slow\"* into *\"the plan is too small\"*, and folding it in hides the one actionable number."},"error_count":{"type":"integer"},"cache_miss_count":{"type":"integer","description":"How many of these requests could not be served from the page cache. A cache miss on a page that should hit is usually the entire explanation for a slow site.\n\n⛔ Named `error_count` / `cache_miss_count` rather than `errors` / `cache_misses`, matching the model. `errors` would shadow DRF's own `Serializer.errors` (the validation-error map) on the serializer that renders this — a real footgun, caught by `mypy --strict` rather than by a person."}}},"SiteAppAutoUpdate":{"type":"object","description":"The paid automatic app updates add-on for one site (s1014 row 41): the code that applies (`wordpress_auto_updates`, `woocommerce_auto_updates`, `joomla_auto_updates`, `nextcloud_auto_updates`, `drupal_auto_updates`, `mediawiki_auto_updates`, `phpbb_auto_updates`, `owncloud_auto_updates`, `matomo_auto_updates`, `typo3_auto_updates`, `concretecms_auto_updates`, `prestashop_auto_updates`, `magento_auto_updates`, `strapi_auto_updates`, `payload_auto_updates`, `oscommerce_auto_updates`, `dolibarr_auto_updates`, `silverstripe_auto_updates`, `craft_auto_updates`, `osticket_auto_updates`, `piwigo_auto_updates`, `modx_auto_updates`, `suitecrm_auto_updates`, `zenphoto_auto_updates`, `opencart_auto_updates`, `abantecart_auto_updates` or `mautic_auto_updates`), the window and the last run's outcome.","required":["site_id","app_key","code","offered","active","can_buy","refusal","price","purchase_id","renews_on","ends_on","enabled","window_weekday","window_hour","timezone","next_window_at","last_run_at","last_outcome","last_detail"],"additionalProperties":false,"properties":{"site_id":{"type":"string","format":"uuid"},"app_key":{"type":["string","null"],"description":"The app the add-on serves on this site, or null when none is sold for it.","enum":["wordpress","woocommerce","joomla","nextcloud","phpbb","owncloud","mediawiki","drupal","matomo","typo3","concretecms","prestashop","magento","strapi","payload","oscommerce","dolibarr","silverstripe","craft","osticket","piwigo","modx","suitecrm","zenphoto","opencart","abantecart","mautic",null]},"code":{"type":"string","nullable":true,"description":"The catalogue code to buy (`<app_key>_auto_updates`)."},"offered":{"type":"boolean","description":"Whether the add-on is on sale to this organisation."},"active":{"type":"boolean","description":"Whether the add-on is on and in good standing now."},"can_buy":{"type":"boolean"},"refusal":{"type":"string","nullable":true,"description":"Why it cannot be bought right now, or null."},"price":{"nullable":true,"description":"The yearly price in the caller's currency, or null when not on sale.","allOf":[{"$ref":"#/components/schemas/MoneyAmount"}]},"purchase_id":{"type":"string","format":"uuid","nullable":true},"renews_on":{"type":"string","format":"date","nullable":true},"ends_on":{"type":"string","format":"date","nullable":true},"enabled":{"type":"boolean"},"window_weekday":{"type":"integer","minimum":0,"maximum":6,"nullable":true,"description":"0 = Monday to 6 = Sunday; null = every day."},"window_hour":{"type":"integer","minimum":0,"maximum":23},"timezone":{"type":"string"},"next_window_at":{"type":"string","format":"date-time","nullable":true},"last_run_at":{"type":"string","format":"date-time","nullable":true},"last_outcome":{"type":["string","null"],"enum":["updated","current","rolled_back","failed",null]},"last_detail":{"type":"string","nullable":true,"description":"What the last run changed, or why it was rolled back."}}},"SiteApplicationReinstall":{"type":"object","required":["site_id","primary_domain","available","refusal","application","modes","run"],"properties":{"site_id":{"type":"string","format":"uuid"},"primary_domain":{"type":"string"},"available":{"type":"boolean"},"refusal":{"type":["string","null"],"enum":["not_php_app","no_application","not_on_fleet","not_active",null],"description":"Why the site cannot be reinstalled; `null` when it can."},"application":{"type":["object","null"],"required":["key","name"],"properties":{"key":{"type":"string"},"name":{"type":"string"}}},"modes":{"type":"array","items":{"type":"object","required":["mode","available","reason"],"properties":{"mode":{"$ref":"#/components/schemas/SiteApplicationReinstallMode"},"available":{"type":"boolean"},"reason":{"type":["string","null"],"enum":["keep_database_unsupported",null]}}}},"run":{"type":["object","null"],"description":"The latest reinstall of this site; `null` when there has never been one.","required":["workflow_id","status","mode","started_at","closed_at","outcome","database_backed_up","files_backed_up"],"properties":{"workflow_id":{"type":"string"},"status":{"type":"string","description":"Temporal's status — RUNNING, COMPLETED, FAILED, TERMINATED, TIMED_OUT, ..."},"mode":{"oneOf":[{"$ref":"#/components/schemas/SiteApplicationReinstallMode"},{"type":"null"}]},"started_at":{"type":["string","null"],"format":"date-time"},"closed_at":{"type":["string","null"],"format":"date-time"},"outcome":{"type":["string","null"],"enum":["reinstalled","failed",null]},"database_backed_up":{"type":"boolean"},"files_backed_up":{"type":"boolean"},"restored":{"type":["boolean","null"],"description":"A failed run only. `true`: the site was put back from the backups this run took, so it is as it was before. `false`: putting it back failed too (staff see `restore_error`). `null`: nothing had been removed, or the run did not fail."},"database_backup":{"type":["string","null"],"description":"Staff only — the database dump's path on the server."},"files_backup":{"type":["string","null"],"description":"Staff only — the files archive's path on the server."},"error":{"type":["string","null"],"description":"Staff only — the failing step's message."},"restore_error":{"type":["string","null"],"description":"Staff only — why putting the site back failed, when it did."}}}}},"SiteApplicationReinstallMode":{"type":"string","enum":["keep_database","fresh"],"description":"`keep_database` — fresh files reconnected to the existing tables; `fresh` — files, data directory and tables cleared and the application installed from nothing. Both back the database and files up first."},"SiteApplicationReinstallRequest":{"type":"object","required":["mode","confirm_domain"],"properties":{"mode":{"$ref":"#/components/schemas/SiteApplicationReinstallMode"},"confirm_domain":{"type":"string","maxLength":253,"description":"The site's primary domain, typed by the customer (case-insensitive)."}}},"SiteApplicationReinstallStart":{"type":"object","required":["workflow_id","mode","started"],"properties":{"workflow_id":{"type":"string"},"mode":{"$ref":"#/components/schemas/SiteApplicationReinstallMode"},"started":{"type":"boolean","description":"`true` once the request is queued. A consumer starts the workflow; a run already going absorbs the request (one workflow id per site)."}}},"SiteBackup":{"type":"object","required":["id","status","trigger","size_bytes","restorable","message","created_at","finished_at","expires_at","last_restored_at","restore_status","restore_failure","restore_finished_at","kind","file_count","reused_bytes"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"status":{"$ref":"#/components/schemas/BackupStatus"},"trigger":{"$ref":"#/components/schemas/BackupTrigger"},"size_bytes":{"type":"integer","format":"int64","description":"The size object storage reported, re-read from the backend rather than carried from the host — a truncated upload that curl reports as success would otherwise be recorded at the host's size and only surface during a restore."},"restorable":{"type":"boolean","description":"Whether this backup can be restored today. False for anything that is not stored offsite, and for a stored row with no object key."},"message":{"type":["string","null"],"description":"Why the backup failed, else null. Rendered to the customer verbatim."},"created_at":{"type":"string","format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time","description":"When retention will remove it. Recomputed from the org's **live** `backup_retention_days` on every prune, so an upgrade extends existing backups rather than holding the customer to last week's plan."},"retention_tier":{"type":"string","enum":["","weekly","monthly"],"description":"Why this backup is kept past the daily window (owner D52): `weekly` or `monthly` when it is that copy, empty for an ordinary daily backup. Set the night the backup leaves the daily window; `monthly` wins when one backup is both. A weekly or monthly copy restores and downloads like any other backup."},"kind":{"type":"string","enum":["full","incremental"],"description":"Whether this archive carries the whole tree or only what changed since an earlier backup.\n\n⛔ **This describes the ARCHIVE, never the restore.** Both kinds restore to a complete site: an incremental's manifest lists every path in the tree at that instant, so a customer picks a night and never assembles a chain. Do not present an incremental as offering less protection — it does not.\n\n⭐ Render it alongside `file_count`, not alongside `size_bytes` on its own. A 41 MB full beside a 1 KB incremental invites exactly the wrong conclusion; the two rows may describe trees of identical size."},"file_count":{"type":"integer","description":"Paths in the site's tree at the moment this backup was taken — the size of the **restore**, and the honest answer to *\"how much of my site is in this?\"* for both kinds. `0` on a backup taken before the platform recorded manifests, and on an adapter that cannot produce one."},"reused_bytes":{"type":"integer","format":"int64","description":"Bytes this backup did not have to ship because an earlier one in its chain already holds them. `0` on a full.\n\nMeasured on a real site the day this shipped: a night that changed **2 files** reused 136,518,848 bytes and shipped 1,132 — against a 41,344,028-byte full archive the platform would previously have taken, every night, for ever."},"last_restored_at":{"type":["string","null"],"format":"date-time","description":"When this backup was last restored FROM. ADR 0013 §6 — an untested backup is not a backup, so the platform records that it was used."},"restore_status":{"type":"string","enum":["","running","succeeded","failed"],"description":"The outcome of the latest restore FROM this backup. Blank means never restored (or restored before outcomes were recorded); `running` from the moment a restore is accepted; `succeeded` or `failed` once it settles. A retry that succeeds clears an earlier failure."},"restore_failure":{"type":"string","enum":["","files_permission","disk_full","archive_unavailable","timed_out","unknown"],"description":"Why the latest restore failed, as a class the panel explains, when `restore_status` is `failed`; blank otherwise. Never the driver's message, which goes to staff only."},"restore_finished_at":{"type":["string","null"],"format":"date-time","description":"When the latest restore settled (succeeded or failed); null while running or never."},"has_database":{"type":["boolean","null"],"description":"Whether this archive carries a database dump that is **present and non-empty**. `null` means the channel did not report it — which is *not recorded*, never *no*.\n\n⛔ A files-only archive is a supported outcome, not a failure: a static site, a plain-PHP site, or a host whose PHP forbids `mysqldump` all produce one on purpose. Render all three states as three different sentences. A zero-byte dump is the dangerous case — it imports successfully over a working database and leaves an empty site — which is why this means non-empty rather than merely present."},"source_bytes":{"type":"integer","format":"int64","description":"Uncompressed bytes on the source when the archive was taken, as the source reported them. `0` means *not reported*.\n\n⛔ Not `size_bytes`, which is the compressed object we re-read from storage and the only figure we can prove. This one exists because a transfer onto our hosting has no live source left to compare against, so it is the only thing an arrival can be asserted against."}}},"SiteBackupState":{"type":"object","required":["site_id","backups","can_backup","in_progress","on_demand_backups","daily_backups","retention_days","weekly_copies","monthly_copies","offsite_enabled","immutable","immutable_days","immutability_verified_at","immutability_reason","restore_drill_passed","restore_drill_at","restore_drill_reason","on_demand_limit","on_demand_used","on_demand_remaining","on_demand_next_at"],"properties":{"site_id":{"$ref":"#/components/schemas/Uuid"},"backups":{"type":"array","items":{"$ref":"#/components/schemas/SiteBackup"}},"can_backup":{"type":"boolean","description":"False while a backup is in flight, when this site's hosting platform cannot take one at all, or when the site's on-demand allowance for the last 24 hours is spent."},"in_progress":{"type":"boolean"},"on_demand_backups":{"type":"boolean","description":"Always true. On-demand backups are included on every plan (owner ruling 2026-08-10); what bounds them is `on_demand_limit` per rolling 24 hours, not the plan. Retained for compatibility with clients that read it."},"unsupported_reason":{"type":"string","description":"A stable machine identifier saying why this site's hosting platform cannot be backed up at all, or empty when it can. The client renders it as a localised sentence. Distinct from the allowance: this one no upgrade and no waiting will change."},"on_demand_limit":{"type":"integer","description":"On-demand backups allowed per rolling 24 hours, per site."},"on_demand_used":{"type":"integer","description":"On-demand backups taken in the last 24 hours. Failed attempts are not counted — the customer got nothing from them."},"on_demand_remaining":{"type":"integer","description":"How many the customer may still take right now."},"on_demand_next_at":{"type":"string","format":"date-time","nullable":true,"description":"When the next on-demand slot opens, as the oldest counted backup ages out of the rolling window. Null whenever `on_demand_remaining` is above zero."},"daily_backups":{"type":"boolean","description":"The plan's `daily_backups` entitlement — whether the nightly sweep selects this site."},"retention_days":{"type":"integer","description":"The plan's `backup_retention_days` entitlement, clamped to the platform maximum."},"weekly_copies":{"type":"integer","minimum":0,"description":"Weekly copies this site's plan keeps on top of the daily backups (owner D52; `backup_weekly_copies`). Each lives one week longer per copy than a daily backup. 0 when the plan keeps none, or when the platform cannot honour them for this site."},"monthly_copies":{"type":"integer","minimum":0,"description":"Monthly copies this site's plan keeps (`backup_monthly_copies`; 12 = one per month for a year). 0 when the plan keeps none."},"offsite_enabled":{"type":"boolean","description":"Whether object storage is configured. False means every backup stays on the worker host it was taken on."},"immutable":{"type":"boolean","description":"Whether backup immutability is enforced **and proven recently**. True only when the platform's last reconciliation actually attempted to delete a canary object under the backup prefix and the storage backend *refused* — reading a lock rule back is not proof that it bites. It also goes false when that proof goes stale (older than the two-day verification SLA), because \"it worked a fortnight ago\" is not the claim `/features/backups` makes. A client may repeat the immutability promise to a customer exactly when this is true, and must not otherwise."},"immutable_days":{"type":"integer","description":"How many days a written backup cannot be altered or deleted by anyone — us, a compromised site, or a stolen token. 30 by owner ruling (2026-08-12), matching sold retention; `0` alongside `immutable: true` would mean an indefinite lock. Meaningless while `immutable` is false."},"immutability_verified_at":{"type":"string","format":"date-time","nullable":true,"description":"When a delete was last actually attempted against the protected prefix and refused. ⛔ Not when the configuration was last read, and not when the reconciler last ran: a run that could not reach the storage backend deliberately leaves this untouched, so a broken credential can never look like a fresh, healthy check. Null when no verification has ever succeeded."},"immutability_reason":{"type":"string","description":"A stable machine identifier saying why immutability is not currently provable — `never_checked`, `no_rule`, `delete_succeeded`, `credential_missing`, `lock_api_unreachable`, `canary_write_failed`, `vendor_unsupported` — and empty when the last answer was clean. `lock_api_unreachable` means the storage vendor's lock API did not answer (a timeout or 5xx after retries), which is neither a bad credential nor a missing rule. Never a sentence: the client renders it as localised copy (§2.19). ⛔ The codes are not interchangeable — `delete_succeeded` means we asked and the guarantee does not hold, while `credential_missing` means we could not ask, and collapsing them renders a security incident and a broken credential identically."},"restore_drill_passed":{"type":"boolean","description":"Whether the platform's weekly restore drill last **passed**, and recently enough to still mean something. The drill restores a real stored backup onto a platform-owned site and passes only when a canary planted in that site's live database immediately beforehand is **gone** afterwards — the archive predates the canary, so its absence is the only evidence that the data was genuinely replaced rather than that an API returned 200. Goes false when the last pass ages past the ten-day drill SLA, because `/features/backups` claims restores are exercised *regularly*. A client may repeat that claim exactly when this is true, and must not otherwise."},"restore_drill_at":{"type":"string","format":"date-time","nullable":true,"description":"When the last drill finished, whatever its outcome. Null when no drill has ever completed."},"restore_drill_reason":{"type":"string","description":"A stable machine identifier saying why restores are not currently proven — `never_drilled`, `no_drill_site`, `no_recent_backup`, `canary_unavailable`, `restore_failed`, `fence_refused`, `canary_survived`, `no_content`, `unverifiable`, `not_serving`, `serving_untestable`, `stale` — and empty when the last drill passed **and** that pass is still inside the SLA. ⛔ `stale` exists so that a pass which has aged out reports a cause rather than an empty string: `restore_drill_passed` is the *provable* half, so without it an aged pass would send `passed: false` with no reason, matching none of the codes above. Never a sentence: the client renders it as localised copy (§2.19). ⛔ The codes are not interchangeable. `canary_survived` means a restore reported success and changed nothing, which is a product defect; `no_drill_site` means the platform has nothing it is allowed to drill, which is an operational gap; `unverifiable` means the restore ran and could not be checked; and `fence_refused` means the drill was aimed at a site it must not touch, which is the most serious of all of them and is a completely different investigation from `restore_failed`. Collapsing them would report every one as the same absence. ⛔ `not_serving` and `serving_untestable` are likewise NOT interchangeable, and the pair exists because every other code above is answered over `wp-cli`, which is the same channel a restore repairs through and therefore cannot see the vhost map, the `:443` listener, the origin certificate or the PHP handler. Both mean a visitor could not load the site over HTTPS after the drill; they differ in what that licenses you to conclude. `not_serving` means the site **did** serve immediately before the restore, so the restore broke it — a product defect. `serving_untestable` means it was already dark beforehand, so the drill could not exercise the serving path at all and nothing may be inferred about the restore, which is why it reports `unproven` rather than a failure."}}},"SiteBlueprint":{"type":"object","required":["id","name","notes","status","stack_type","runtime","product_line","source_domain","source_site_id","has_screenshot","deployable","deployment_count","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"name":{"type":"string","maxLength":100,"example":"Standard PBN site"},"notes":{"type":"string","description":"The customer's own note, so they can tell their templates apart."},"status":{"$ref":"#/components/schemas/SiteBlueprintStatus"},"message":{"type":"string","description":"Why a capture failed, in human English. Empty otherwise. Rendered to the customer verbatim."},"stack_type":{"allOf":[{"$ref":"#/components/schemas/StackType"}],"description":"The stack the source site ran, **copied at capture time**. This is the compatibility axis: a blueprint can only be deployed onto a site of the same stack. Copied rather than read through `source_site_id` because a blueprint has to outlive the site it came from — deleting that site is half the reason anybody captures one."},"runtime":{"$ref":"#/components/schemas/Runtime"},"product_line":{"type":"string","maxLength":64,"description":"The line the source site was on. **Advisory** — shown so a customer can tell a PBN template from a mainstream one — and deliberately NOT part of the compatibility guard: moving a site between your own lines is legitimate."},"source_domain":{"type":"string","maxLength":253,"description":"The domain of the site this was captured from, kept after that site is gone."},"source_site_id":{"description":"The site it came from, or null once that site has been deleted.","anyOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]},"has_screenshot":{"type":"boolean","description":"Whether a picture exists. ⛔ Deliberately a boolean and not a URL: minting a presigned URL is a round trip to object storage, and doing it per row on a list endpoint would put an external call on the busiest read of the feature. Ask `getSiteBlueprintScreenshot` for the tiles you actually render."},"deployable":{"type":"boolean","description":"Whether a site can be built from this **today**. Three conditions, not one: the capture finished, a backup is linked, and that backup is still restorable. A `ready` blueprint whose archive has gone is not deployable, and offering a button for it would fail an hour into a provisioning run."},"deployment_count":{"type":"integer","minimum":0,"description":"How many sites have been built from this blueprint."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"SiteBlueprintCreate":{"type":"object","required":["site_id","name"],"properties":{"site_id":{"allOf":[{"$ref":"#/components/schemas/Uuid"}],"description":"The built site to capture. Must be `active`."},"name":{"type":"string","minLength":1,"maxLength":100},"notes":{"type":"string"},"backup_id":{"description":"An existing **stored** backup of that site to adopt, instead of taking a new one. Adopting spends none of the site's three-per-rolling-day on-demand allowance and makes the blueprint `ready` immediately — which is what a customer wants when this morning's site is broken and last night's backup is the template they mean. A backup that is not on this site, is not stored, or already backs another blueprint is refused.","anyOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]}}},"SiteBlueprintDeployRequest":{"type":"object","required":["blueprint_id"],"properties":{"blueprint_id":{"allOf":[{"$ref":"#/components/schemas/Uuid"}],"description":"The SITE blueprint to deploy. ⛔ Always named explicitly — never \"the latest\". This overwrites a live site."},"site_title":{"type":"string","maxLength":200,"description":"The copy's WordPress site title, one line. Blank or omitted means a fresh one is chosen (`getSiteBlueprintTitleSuggestion`). ⛔ A copy never keeps the original site's title or tagline, which would link the sites."},"tagline":{"type":"string","maxLength":200,"description":"The copy's WordPress tagline, one line. Blank or omitted means a fresh one is chosen."}}},"SiteBlueprintDeployStatus":{"type":"string","enum":["pending","waiting","restoring","done","failed"],"description":"⭐ `waiting` is a real state and not a synonym for `pending`. A deploy started from the create form cannot restore anything until the new site has finished provisioning, which takes minutes — so the screen has to be able to say \"waiting for the new site to be built\" rather than showing a restore that looks stuck."},"SiteBlueprintDeployment":{"type":"object","required":["id","blueprint_id","site_id","status","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"blueprint_id":{"$ref":"#/components/schemas/Uuid"},"site_id":{"$ref":"#/components/schemas/Uuid"},"status":{"$ref":"#/components/schemas/SiteBlueprintDeployStatus"},"message":{"type":"string","description":"Why it failed, or — after a successful restore whose URL rewrite did not take — what still needs attention. Rendered to the customer verbatim."},"site_title":{"type":"string","description":"The copy's WordPress site title: the one typed at deploy, or the fresh one it was given. Empty until the copy step has run, and on a redeploy onto the original site."},"tagline":{"type":"string","description":"The copy's WordPress tagline, as for `site_title`."},"started_at":{"type":["string","null"],"format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"SiteBlueprintPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SiteBlueprint"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"SiteBlueprintScreenshotGrant":{"type":"object","required":["url","expires_at"],"properties":{"url":{"type":"string","format":"uri","description":"⛔ A **bearer credential** for the picture until it expires — never log it, never store it, hand it straight to the browser."},"expires_at":{"type":"string","format":"date-time"}}},"SiteBlueprintStatus":{"type":"string","enum":["capturing","ready","failed"],"description":"Where a capture got to. `ready` means the backup behind the blueprint is restorable, not merely that the row was written — a backup that ended \"on host only\" (no object storage configured) cannot be restored onto a *different* site and does not make a blueprint ready. A failed capture is kept rather than deleted so the customer can see that it failed and why."},"SiteBlueprintTitleSuggestion":{"type":"object","required":["site_title","tagline"],"properties":{"site_title":{"type":"string"},"tagline":{"type":"string"}}},"SiteBlueprintUpdate":{"type":"object","description":"⛔ Omitted is not the same as empty. Omitting a field leaves it alone; sending `\"\"` for `notes` clears it. Collapsing the two would make it impossible to clear a note, or would wipe one on every rename.","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"notes":{"type":"string"}}},"SiteBuild":{"type":"object","description":"One \"describe a site and we build it\" run.\n\n`files` is present on the **detail** and create responses and absent from the **list**, deliberately: a generated tree can be a hundred kilobytes, and a list of thirty drafts that inlined every one would be a response no client can render. `file_count` is always present so a list can still say something true.","required":["id","title","brief","status","file_count","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"title":{"type":"string","description":"The builder's own name for the site, so a customer can tell drafts apart."},"summary":{"type":"string","description":"The builder's one-sentence account of what it made. ⛔ Not translated, and that is not an i18n gap: it is customer content, written in whatever language the brief was, exactly like the site's own copy."},"brief":{"type":"string","description":"What the customer asked for, verbatim. Kept so a re-build can start from it."},"status":{"$ref":"#/components/schemas/SiteBuildStatus"},"file_count":{"type":"integer"},"files":{"type":"object","additionalProperties":{"type":"string"},"description":"The generated site, as relative path to file text. Paths are validated on the way **in** against an allow-list of extensions a static host can serve, so a stored path is already safe and a client need not re-check one."},"model":{"type":"string","description":"Which model wrote it."},"cost_usd_micros":{"type":"integer","format":"int64","description":"What this build cost the customer, USD micros, at actual token usage."},"funding":{"type":"string","description":"`byo` when the customer's own provider key paid, `credit` when their Zinn® balance did. The same vocabulary the usage meter records."},"deploy_target":{"type":"string"},"site_id":{"type":["string","null"],"format":"uuid"},"repo_url":{"type":"string","description":"The git repository the files were pushed to, when one was asked for. Empty when the organization has no source-control connection — the repository is the optional half of a publish and its absence never blocks one."},"live_url":{"type":"string","description":"Where the published site is serving. Empty until it is published."},"error":{"type":"string","description":"Why a `failed` build failed, in the customer's terms. Never an exception or a stack trace."},"failure":{"description":"The classified §2.57 failure behind `error` — whose key was refused, which vendor, and the one door to fix it. Null when the failure was not classified (D25029).","oneOf":[{"$ref":"#/components/schemas/VendorFailure"},{"type":"null"}]},"hold_reason":{"type":"string","description":"Why a `held` publish stopped and what the customer can do about it. Blank in every other state.\n\nA separate field from `error` on purpose: a client keying \"did this go wrong?\" off a non-empty `error` would paint a hold red and, worse, retry it — and the retry is an attempt to overwrite the customer's own files."},"created_at":{"type":"string","format":"date-time"},"published_at":{"type":["string","null"],"format":"date-time"}}},"SiteBuildCreate":{"type":"object","required":["brief"],"properties":{"brief":{"type":"string","maxLength":2000,"description":"What the site is for, who it is for, and which pages it needs. A tighter brief produces a better site than a longer one."},"provider":{"type":"string","description":"Force a provider. Omit for the cheapest route this organization's funding allows, resolved exactly as every other customer-funded AI surface resolves it."},"model":{"type":"string","description":"Force a model. Omit to let the resolver choose."},"site_id":{"oneOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}],"description":"The site this build is FOR, chosen before building. Recorded on the draft as its intended destination (`SiteBuild.site_id`) so the publish step opens on that site; it deploys nothing by itself. Must be one of the organization's own sites, or the request is answered 404 and nothing is built. Omit (or null) for \"a new site, set up when I publish\". A rebuild keeps its parent's site."}}},"SiteBuildEnv":{"type":"object","required":["names"],"description":"⛔ NAMES ONLY. There is deliberately no schema anywhere in this API that carries a build variable's VALUE: a build variable is routinely an API key, and a shape that cannot express a value is what makes exposing one a change somebody has to review rather than a field added in a hurry.","properties":{"names":{"type":"array","items":{"type":"string"},"description":"The variable names this site holds, sorted."},"applied":{"type":"boolean","description":"Present only on a save to a Node.js, Python or Ruby site on our own servers: `true` means the running application received the variables and was restarted, `false` that it is not on a server yet (the first deploy hands them over). Absent for every other site, whose variables are build-time only."}}},"SiteBuildEnvWrite":{"type":"object","required":["variables"],"description":"The site's whole build environment after this call: `variables` are the ones being SET, `keep` names the ones to retain with the value already stored, and anything in NEITHER list is deleted. `keep` exists because the store is write-only — no endpoint returns a value, so a form cannot send back the values it is not changing, and \"unchanged\" therefore has to be stated rather than inferred from omission. That leaves omission free to mean delete, which plain merge semantics can never express.","properties":{"variables":{"type":"object","additionalProperties":{"type":"string"},"description":"Name to new value, for the variables being set or replaced. A mapping rather than a list of key/value objects because a mapping cannot express a duplicate name — two rows with one name is a state a form can produce and nobody can see which won."},"keep":{"type":"array","items":{"type":"string"},"description":"Names to retain unchanged. A name here that the store does not hold is ignored rather than refused — it means the variable was deleted elsewhere, and failing the whole save over it would leave the customer unable to save anything. A name in BOTH lists is refused."}}},"SiteBuildEnvelope":{"type":"object","required":["build"],"properties":{"build":{"$ref":"#/components/schemas/SiteBuild"},"trial":{"$ref":"#/components/schemas/SiteBuilderTrial"}}},"SiteBuildFile":{"type":"object","additionalProperties":false,"required":["path","content"],"properties":{"path":{"type":"string","maxLength":255,"description":"Relative path inside the generated site, e.g. `index.html`."},"content":{"type":"string","description":"The file's complete new contents. May be empty."}}},"SiteBuildImage":{"type":"object","required":["path","alt","content_type","cost_usd_micros"],"properties":{"path":{"type":"string"},"alt":{"type":"string"},"content_type":{"type":"string"},"cost_usd_micros":{"type":"integer","format":"int64"}}},"SiteBuildImageQuoteEnvelope":{"type":"object","required":["quote"],"properties":{"quote":{"type":"object","required":["images","already_generated","unit_price_usd_micros","total_usd_micros"],"properties":{"images":{"type":"array","items":{"$ref":"#/components/schemas/SiteBuildImageSlot"}},"already_generated":{"type":"array","items":{"type":"string"},"description":"Paths already generated for this draft. Not quoted again."},"unit_price_usd_micros":{"type":"integer","format":"int64"},"total_usd_micros":{"type":"integer","format":"int64"}}}}},"SiteBuildImageSlot":{"type":"object","required":["path","alt"],"properties":{"path":{"type":"string"},"alt":{"type":"string"}}},"SiteBuildImagesConfirm":{"type":"object","additionalProperties":false,"required":["agreed_total_usd_micros"],"properties":{"agreed_total_usd_micros":{"type":"integer","format":"int64","minimum":0,"description":"The `total_usd_micros` you were quoted. Refused with `price_moved` if it no longer matches, and nothing is charged."},"provider":{"type":"string"},"model":{"type":"string"}}},"SiteBuildImagesEnvelope":{"type":"object","required":["images","build"],"properties":{"images":{"type":"array","items":{"$ref":"#/components/schemas/SiteBuildImage"}},"build":{"$ref":"#/components/schemas/SiteBuild"}}},"SiteBuildList":{"type":"object","required":["builds","trial","balance_micros","spend_micros"],"properties":{"builds":{"type":"array","items":{"$ref":"#/components/schemas/SiteBuild"}},"trial":{"$ref":"#/components/schemas/SiteBuilderTrial"},"balance_micros":{"type":"integer","format":"int64","description":"The organization's AI credit balance, USD micros."},"spend_micros":{"type":"integer","format":"int64","description":"What this organization has spent on the builder in total, USD micros."}}},"SiteBuildPublish":{"type":"object","required":["site_id"],"properties":{"site_id":{"allOf":[{"$ref":"#/components/schemas/Uuid"}],"description":"The site to publish onto. It must already be on a managed edge host; a site on a resold package is refused with the provider's own reason, not a generic failure."},"connect_repo":{"type":"boolean","default":false,"description":"Also put the files in the organization's connected git provider. Defaults to false: creating a repository on somebody's account is a named, permanent artefact on an account we only borrow, so it is opt-in.\n\nWhen the site already has a repository connected, the files are pushed **into that one** rather than into a new one — that is the repository the site actually deploys from, so the generated site joins the customer's existing pipeline."},"repo_owner":{"type":"string","description":"Which account to create the repository under. Required for a new repository and ignored when the site already has one. ⛔ Never inferred: one token reaches every account it was granted, so the owner is a property of the site rather than of the credential, and guessing means creating a visible artefact on an account the customer did not name."}}},"SiteBuildRebuild":{"type":"object","additionalProperties":false,"properties":{"brief":{"type":"string","maxLength":2000,"minLength":1,"description":"The tweaked description. Omit to rebuild from the brief already stored. An empty string is refused rather than treated as \"no brief\"."},"provider":{"type":"string"},"model":{"type":"string"}}},"SiteBuildStatus":{"type":"string","description":"Where a build got to. `failed` is a settled state carrying a reason in `error`, never an absent row — a build that could not run and a build nobody started are different facts and only one of them is the customer's to fix.\n\n`held` is **not** a failure and must not be rendered as one. It means the publish reached the site and declined to act: a site on our own fleet already held files we did not put there, so applying the generated site would have destroyed the customer's own work. The reason is in `hold_reason`, the generated files are safe in the repository, and the customer resolves it on the site's sync screen. A client that retries a `held` build automatically is retrying an overwrite.\n\n`generating` is the row's first state: `createSiteBuild` and `rebuildSiteBuild` return it at once, with no files, and a durable workflow fills it in — a real multi-page site takes one to three minutes to write, which no request can hold (D20191). Poll `listSiteBuilds` or `getSiteBuild` until it reads `drafted` or `failed`; `error` carries the reason for the latter.","enum":["generating","drafted","published","failed","held"]},"SiteBuilderTrial":{"type":"object","description":"The **one-time** free allowance for the AI site builder. One grant per organization, for ever — not monthly, and not per site.\n\n`granted` is true because the credit was actually posted to the ledger, not because a flag was set: it is enforced by a `UNIQUE(org_id, reference)` constraint on the credit table rather than by application code, so it cannot drift from the balance it describes. A client may therefore treat it as the authority on whether to offer the trial.\n\nPublished on the AI summary rather than on a builder-specific endpoint so an organization-level surface (the dashboard Overview) can decide whether to show the offer from the one call it already makes, never one call per site.","required":["granted","amount_micros","builds"],"properties":{"granted":{"type":"boolean","description":"Whether this organization has already received its free allowance."},"amount_micros":{"type":"integer","format":"int64","description":"What the allowance is worth, USD micros (1 USD = 1,000,000). The grant lands on the ordinary AI credit balance and is spendable on any AI surface — there is one meter, and a ring-fenced trial balance would be a second meter wearing its name."},"builds":{"type":"integer","description":"How many builds this organization has **published**. ⛔ Published, not drafted: \"they tried it and shipped\" and \"they tried it and abandoned it\" are different facts, and counting drafts reports the second as the first."}}},"SiteCacheHealth":{"type":"object","required":["reported","problems"],"properties":{"reported":{"type":"boolean"},"received_at":{"type":"string","format":"date-time"},"plugin_version":{"type":"string"},"licensed":{"type":"boolean"},"connected":{"type":"boolean"},"fallback":{"type":"boolean"},"last_error":{"type":"string"},"hit_ratio_1h":{"type":"number","nullable":true},"hit_ratio_24h":{"type":"number","nullable":true},"requests_1h":{"type":"integer"},"avg_ms":{"type":"number","nullable":true},"server_hit_ratio":{"type":"number","nullable":true},"used_memory":{"type":"integer","nullable":true},"maxmemory":{"type":"integer","nullable":true},"evicted_keys":{"type":"integer","nullable":true},"uncached_by":{"type":"array","items":{"$ref":"#/components/schemas/SiteCacheHealthComponentRow"}},"slow_queries_by":{"type":"array","items":{"$ref":"#/components/schemas/SiteCacheHealthComponentRow"}},"problems":{"type":"array","items":{"$ref":"#/components/schemas/SiteCacheHealthProblem"}}}},"SiteCacheHealthAccepted":{"type":"object","required":["accepted","problems"],"properties":{"accepted":{"type":"boolean"},"problems":{"type":"array","items":{"$ref":"#/components/schemas/SiteCacheHealthProblem"}}}},"SiteCacheHealthComponentRow":{"type":"object","properties":{"component":{"type":"string","description":"`plugin:<slug>`, `theme:<slug>`, `mu-plugin:<file>` or `core`."},"misses":{"type":"integer"},"count":{"type":"integer"},"max_ms":{"type":"number"}}},"SiteCacheHealthProblem":{"type":"string","enum":["disconnected","memory_full","evicting","hit_ratio_low"],"description":"`disconnected` — the object cache is not connected (serving from memory); `memory_full` — Redis memory is at least 95% of its limit; `evicting` — 1,000 or more keys were evicted since the previous report; `hit_ratio_low` — under 60% of reads hit the cache in the last hour (only judged with at least 50 requests)."},"SiteCacheHealthReportRequest":{"type":"object","required":["site"],"additionalProperties":true,"properties":{"site":{"type":"string"},"plugin_version":{"type":"string"},"licensed":{"type":"boolean"},"dropin_revision":{"type":"integer"},"connected":{"type":"boolean"},"fallback":{"type":"boolean"},"last_error":{"type":"string"},"hit_ratio_1h":{"type":"number","nullable":true},"hit_ratio_24h":{"type":"number","nullable":true},"requests_1h":{"type":"integer"},"avg_ms":{"type":"number","nullable":true},"server_hit_ratio":{"type":"number","nullable":true},"used_memory":{"type":"integer","nullable":true},"maxmemory":{"type":"integer","nullable":true},"evicted_keys":{"type":"integer","nullable":true},"uncached_by":{"type":"array","items":{"type":"object","additionalProperties":true}},"slow_queries_by":{"type":"array","items":{"type":"object","additionalProperties":true}},"measured_at":{"type":"integer"}}},"SiteCachePurgeResult":{"type":"object","required":["purged"],"properties":{"purged":{"type":"boolean"}}},"SiteCanonicalHost":{"type":"object","required":["canonical_host","force_https","serves_on","redirects_from","redirect_status","certificate_hosts","apex_delivery","apex_deliverable"],"properties":{"canonical_host":{"type":"string","enum":["apex","www"]},"force_https":{"type":"boolean","description":"Redirect http to https at the edge. Defaults to true on every new site."},"serves_on":{"type":"string","description":"The hostname that actually serves."},"redirects_from":{"type":"string","description":"The hostname that permanently redirects to `serves_on`."},"redirect_status":{"type":"integer","description":"Always 301. A 302 tells search engines to keep indexing the alias, which leaves the duplicate-content problem unsolved while looking correct in a browser."},"certificate_hosts":{"type":"array","items":{"type":"string"},"description":"**Both** hostnames, always. TLS is negotiated on the name being redirected from, so a certificate covering only `serves_on` puts a security interstitial in front of the alias and the visitor never reaches the redirect."},"apex_delivery":{"type":"string","enum":["native","alias","a_records","unsupported"],"description":"How the zone apex is made to resolve. A bare apex cannot be a `CNAME`, so on a pull-zone CDN it resolves only through CNAME-flattening/ALIAS at the DNS provider, or through A/AAAA records to the CDN's published anycast edge addresses. `native` means the CDN is itself the authoritative zone, so there is no separate problem to solve.\n\nReported for **both** canonical choices, not only when the apex is canonical: a 301 has to be served by something, so an apex that cannot resolve breaks the redirect too and the visitor gets `NXDOMAIN`."},"apex_deliverable":{"type":"boolean","description":"`false` when neither mechanism is available for this CDN/DNS pairing. The combination is refused rather than accepted, because the alternative provisions cleanly, reports healthy, and cannot be reached at the name most visitors type."}}},"SiteCanonicalHostUpdate":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"canonical_host":{"type":"string","enum":["apex","www"]},"force_https":{"type":"boolean"}}},"SiteCapacity":{"type":"object","description":"The organization's site cap as the create applies it — who grants it, how big it is, and how much is spent.\n\n⛔ `limit`, `used`, `remaining` and `entitling_org_id` are `null` in two distinguishable situations and a client must render **neither as a count**: `disclosed: false` (the plan is not this tenant's to see — say so in words, using `managed_elsewhere`), and `unlimited: true` (there is genuinely no cap). They are omitted rather than zeroed because a zero is a number, and a wrong one.","required":["has_room","unlimited","source","has_plan","broken_chain","disclosed","managed_elsewhere"],"properties":{"has_room":{"type":"boolean","description":"Whether one more site may be created right now. Always answered, at every permission level — it discloses nothing a caller cannot obtain by POSTing. Advisory: no lock is taken, so a concurrent create may still win the last slot.","example":true},"unlimited":{"type":"boolean","description":"Whether the grant is uncapped. When true, `limit` and `remaining` are null.","example":false},"source":{"type":"string","description":"What grants the allowance — `subscription`, `trial`, `staff`, or `none` when nothing in the organization chain grants hosting at all.","enum":["subscription","trial","staff","none"],"example":"subscription"},"has_plan":{"type":"boolean","description":"Whether anything grants hosting. `false` is the `PLAN_REQUIRED` state the create would refuse with, reported before the customer fills the form in.","example":true},"broken_chain":{"type":"boolean","description":"The organization's `parent_org` chain could not be walked — a data defect, not a customer without a plan. A client must say \"contact support\" for this, never \"choose a plan\", or it sells somebody a plan they may already have.","example":false},"disclosed":{"type":"boolean","description":"Whether the figures below are populated. False when the caller lacks `billing.view`, or when the governing plan belongs to an organization outside their scope.","example":true},"managed_elsewhere":{"type":"boolean","description":"There IS a plan, and it is not this caller's to see — a client organization hosted under its parent's plan. The sentence to render instead of a number.","example":false},"limit":{"type":"integer","nullable":true,"description":"How many sites the plan covers. Null when undisclosed or unlimited.","example":25},"used":{"type":"integer","nullable":true,"description":"Sites already consuming the allowance, counted across the entitling organization's whole subtree. Null when undisclosed.","example":7},"remaining":{"type":"integer","nullable":true,"description":"Slots left, never negative — a downgrade to a smaller tier does not delete existing sites, so `used` may legitimately exceed `limit`. Null when undisclosed or unlimited.","example":18},"added_slots":{"type":"integer","nullable":true,"description":"Website slots bought as add-ons on the plan's line, already included in `limit` — so a screen can say \"25 in your plan + 3 added\" without adding them a second time. Null exactly when `limit` is.","example":0},"entitling_org_id":{"allOf":[{"$ref":"#/components/schemas/Uuid"}],"nullable":true,"description":"Which organization's plan applied — this one, or an ancestor under hierarchical tenancy. Null when undisclosed."},"breakdown":{"type":"object","additionalProperties":{"type":"integer","minimum":1},"description":"`used`, split by the site status holding each slot — the answer to \"what are my occupied slots actually holding?\". Keys are `SiteStatus` values; the counts sum to `used` exactly.\n\n⛔ **`used` is true and incomplete without this.** Every status except `deleted` occupies a slot, deliberately: a failed build is retriable and a suspended site's content is retained on disk, so both keep their capacity. Measured on production 2026-08-21 through a real customer's own session: `used: 37` — active 15, failed 14, deleting 8. **22 of 37 occupied slots were not running sites**, and a customer at their cap who deletes one to make room gets nothing until the purge completes seven days later. Render this, or the figure you show is correct and misleading.\n\nEmpty `{}` when the figures are undisclosed or the grant is unlimited (there is no total to explain). A status with no sites is **omitted**, never sent as `0`, so a client can render one clause per key without composing \"and 0 failed\".","example":{"active":15,"failed":13,"deleting":8,"provisioning":1}}}},"SiteCdnAnalytics":{"type":"object","required":["site_id","supported","days","total_requests","total_threats"],"properties":{"site_id":{"$ref":"#/components/schemas/Uuid"},"supported":{"type":"boolean","example":true},"days":{"type":"array","description":"Most recent first.","items":{"$ref":"#/components/schemas/CdnTrafficDay"}},"total_requests":{"type":"integer","example":14154},"total_threats":{"type":"integer","example":29}}},"SiteCdnBudget":{"type":"object","required":["cap_minor","spent_period_minor","state","metered"],"properties":{"cap_minor":{"type":"integer","description":"This site's ceiling in integer minor units. `0` means no per-site ceiling — the account cap alone applies."},"spent_period_minor":{"type":"integer"},"state":{"type":"string","enum":["active","paused_cap","paused_standing","paused_admin"],"description":"Four states rather than a boolean, because the remedy differs: the customer's own cap is self-service, a standing lapse needs a payment, and a staff pause needs staff."},"paused_reason":{"type":"string"},"metered":{"type":"boolean","description":"Whether this site is on the tier that pays per gigabyte."},"serving":{"type":"boolean","description":"Whether the **metered** CDN is serving right now. Reads both this site's state and its account's, because either can pause it.\n\n⛔ **Absent entirely when `metered` is `false`**, rather than sent as `false`. A site on the free or included tier has no credit account by design, so a `false` here would tell a customer their working CDN is off because they are not paying for a product they never bought. Absence means not applicable."},"currency":{"type":"string","description":"ISO code denominating `cap_minor` and `spent_period_minor` (§2.8). ⛔ Absent when the org has not opened metered credit, because minor units without an exponent are unreadable: a zero-decimal currency seeded into an amount field on an assumed exponent of 2 comes back a hundredfold wrong on the next save."}}},"SiteCdnBudgetUpdate":{"type":"object","additionalProperties":false,"required":["cap_minor"],"properties":{"cap_minor":{"type":"integer","minimum":0,"description":"0 for no per-site ceiling, otherwise at least the platform minimum."}}},"SiteCdnChoice":{"allOf":[{"$ref":"#/components/schemas/SiteProviderChoice"},{"type":"object","required":["default"],"properties":{"default":{"type":"string","description":"The CDN vendor the platform will use when the customer names none — empty when the choice is left to the footprint balancer. On the Footprint-Free line this is `cloudflare` (owner decision, 2026-08-06): with Cloudflare the CDN *is* the DNS, and the Cloudflare account pool is the footprint moat the line is sold on. It is reported even though `vendors` is empty on that line, because it is what makes the `dns` answer below correct before the customer has touched a control — and it is **empty** when the organization's pool holds no Cloudflare account, since a default the pool cannot satisfy would fail at provisioning rather than here.","maxLength":64,"example":"cloudflare"},"separates_sites":{"type":"object","additionalProperties":{"type":"boolean"},"description":"Per vendor in `vendors`: can two of **your** sites be placed on different accounts of it? This is the Footprint-Free promise stated as a fact about the pool, and it is arithmetic rather than a badge — measured 2026-09-09, three zones inside one Cloudflare account answer on one nameserver pair and a zone in another account answers on a different one, so a Cloudflare account *is* a nameserver identity. A vendor we hold one usable account of cannot separate anything: fifty sites on it all share it, and they are linkable to each other by a reverse-nameserver lookup.\n\n⛔ A boolean, never a count. No account identifiers, no labels, no totals, and nothing about any other tenant's placement — a picker needs to know that a choice keeps the promise, not how much capacity sits behind it.\n\n⛔ It is computed for the accounts serving **this** organization, so a customer whose own connected account is the only one is told `false` even where the platform pool is large. That is the true answer to their question, which is about their own sites.","example":{"cloudflare":true,"fastly":false}},"offers":{"type":"array","items":{"$ref":"#/components/schemas/SiteCdnOffer"},"description":"What each CDN on this product line **costs**, so the create wizard's selector can say whether a network is included or metered and at what per-GB price rather than only naming it.\n\nSourced from the same catalogue the site's own CDN tab reads, so the two surfaces cannot disagree about what a network costs — a price compiled into the client bundle is the drift this endpoint was widened to remove.\n\n⛔ On a **managed line** each entry omits `vendor` and `label` entirely, exactly as `GET /v1/sites/{siteId}/cdn/offers` does. A price is not a disclosure, but a vendor name is: an empty string still crosses the wire and still renders."}}}]},"SiteCdnFirewallRules":{"type":"object","required":["supported","rules"],"properties":{"supported":{"type":"boolean","example":true},"rules":{"type":"array","description":"In evaluation order. The provider's custom-rules phase is terminating — the first match decides.","items":{"$ref":"#/components/schemas/CdnFirewallRule"}}}},"SiteCdnFirewallRulesUpdate":{"type":"object","description":"The complete ordered rule set. The write is convergent: the provider is made to match exactly, including removing what is gone, so a client that sends a subset of what it was shown deletes the rest.","additionalProperties":false,"required":["rules"],"properties":{"rules":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":false,"required":["action","expression"],"properties":{"key":{"type":"string","maxLength":120},"action":{"$ref":"#/components/schemas/CdnFirewallAction"},"expression":{"type":"string","maxLength":4000},"description":{"type":"string","maxLength":500},"enabled":{"type":"boolean","default":true}}}}}},"SiteCdnFlatTier":{"type":"object","description":"One rung of the flat monthly CDN add-on.","required":["code","label","price_minor","allowance_gb"],"properties":{"code":{"type":"string"},"label":{"type":"string"},"price_minor":{"type":"integer","description":"Monthly price in integer minor units of the account currency."},"allowance_gb":{"type":"integer","description":"Included traffic, in **base-region-equivalent** gigabytes. Traffic to a dearer region spends more than its own size — see `region_weights`."}}},"SiteCdnOffer":{"type":"object","description":"One CDN, as it is sold on one product line. `vendor` and `label` are **absent** on a managed line rather than blank — the name must not reach the client at all.","required":["kind","included"],"properties":{"kind":{"type":"string","enum":["included","flat","metered","byo"],"description":"`included` is bundled with the plan; `flat` is a fixed monthly price for a bounded allowance; `metered` is charged per gigabyte against prepaid credit; `byo` is the customer's own account and their own bill."},"included":{"type":"boolean","description":"Whether choosing this costs the customer nothing extra from us."},"vendor":{"type":"string","description":"Machine key. Omitted entirely on a managed line."},"label":{"type":"string","description":"The customer-facing network name. Omitted entirely on a managed line."},"price_per_gb_micros":{"type":"integer","format":"int64","description":"Present only on a `metered` offer. Micros of USD per gigabyte — a millionth of a dollar, because a per-GB rate does not fit in cents without rounding error."},"price_region":{"type":"string","description":"Which region band `price_per_gb_micros` is quoted for."}}},"SiteCdnOffers":{"type":"object","required":["line","managed","sellable","offers","byo","flat_tiers","region_weights"],"properties":{"sellable":{"type":"boolean","description":"Whether this platform owns the edge in front of this site, and therefore whether any of these offers can be sold on it. ⛔ It is decided by the deploy target, not by the product line: a mainstream site deployed to a reseller's shared hosting is already behind that vendor's edge, so selling it a CDN puts a second one in front of a site that has one — and every observable says the sale worked. When this is false the offers below are informational only and the surface must not offer a purchase."},"line":{"type":"string","description":"The site's product line, which is half the offer key."},"managed":{"type":"boolean","description":"Whether this line's CDN is platform-managed footprint machinery. When true the customer neither chooses nor is told the vendor."},"offers":{"type":"array","items":{"$ref":"#/components/schemas/SiteCdnOffer"},"description":"In presentation order — never leading with the paid upsell."},"byo":{"type":"array","items":{"$ref":"#/components/schemas/SiteCdnOffer"},"description":"The same vendors, offered as the customer's own connected account."},"flat_tiers":{"type":"array","items":{"$ref":"#/components/schemas/SiteCdnFlatTier"},"description":"Empty on a managed line, where the CDN is already included."},"region_weights":{"type":"object","additionalProperties":{"type":"integer","format":"int64"},"description":"How much allowance one gigabyte to each region spends, in micros of a base-region gigabyte. The base region is exactly 1000000."}}},"SiteCdnPageRuleState":{"type":"object","required":["vendor_id","enabled"],"properties":{"vendor_id":{"type":"string"},"enabled":{"type":"boolean"}}},"SiteCdnPageRuleUpdate":{"type":"object","additionalProperties":false,"required":["enabled"],"properties":{"enabled":{"type":"boolean"}}},"SiteCdnPageRules":{"type":"object","required":["supported","rules"],"properties":{"supported":{"type":"boolean","example":true},"rules":{"type":"array","items":{"$ref":"#/components/schemas/CdnPageRule"}}}},"SiteCdnProfile":{"type":"object","description":"The recommended edge configuration for a site, the provider's live state, and the drift between them.","required":["site_id","profile","settings_supported","settings_shared_zone","cache_rules_supported","drifted","settings","rules","managed"],"properties":{"site_id":{"$ref":"#/components/schemas/Uuid"},"profile":{"type":"string","description":"Which recommended profile applies to this site, chosen by product line — `footprint_free` caches HTML aggressively, `mainstream` leaves that decision to the origin."},"settings_supported":{"type":"boolean","description":"Whether this site's CDN can express the profile's zone settings."},"settings_shared_zone":{"type":"boolean","description":"`true` when the site is served by a parent zone that other sites share (a preview address). Zone-level settings belong to that zone, not to this site: they are never written for it and are not compared, so `settings` is empty and none of them appears in `drifted`. The cache rules are still compared."},"cache_rules_supported":{"type":"boolean","description":"Whether this site's CDN can express per-request cache rules. Separate from `settings_supported` because a provider may offer one and not the other."},"drifted":{"type":"array","description":"Setting keys whose live value differs from the recommendation, plus `cache_rules` when a recommended rule is missing at the provider. Empty means the zone matches what we recommend.","items":{"type":"string"}},"settings":{"type":"array","items":{"$ref":"#/components/schemas/SiteCdnProfileSetting"}},"rules":{"type":"array","description":"The recommended rules, in evaluation order. Bypasses come first.","items":{"$ref":"#/components/schemas/SiteCdnProfileRule"}},"managed":{"type":"boolean","description":"Whether the customer has asked us to keep this profile applied. `false` — the default — means drift is reported and nothing is corrected without a person pressing the button. `true` means the `zinn-managed-cdn-profile` sweep re-applies it on a cadence. Set with `PATCH`."}}},"SiteCdnProfileRule":{"type":"object","description":"One recommended cache rule, and whether it is live at the provider.","required":["key","description","cache","applied"],"properties":{"key":{"type":"string","description":"Stable identifier, e.g. `bypass-signed-in`."},"description":{"type":"string","description":"What the rule does, in the customer's terms."},"cache":{"type":"boolean","description":"`true` if the rule caches matching requests, `false` if it is a bypass. Bypass rules are always evaluated first."},"applied":{"type":"boolean","description":"Whether this rule is currently live at the provider."}}},"SiteCdnProfileSetting":{"type":"object","description":"One knob of the recommended profile, with the provider's live value beside it.","required":["key","recommended","actual","matches"],"properties":{"key":{"type":"string","description":"The setting this row is about, e.g. `cache_level` or `ssl_mode`."},"recommended":{"type":"string","description":"The value we recommend, rendered as a string. Deliberately not a union of string and boolean: these are shown to a customer, never computed with, and a `oneOf` here would make every caller narrow a type before it could print a label."},"actual":{"type":"string","description":"The value the provider currently has, rendered the same way."},"matches":{"type":"boolean","description":"Whether the provider's value equals the recommendation."}}},"SiteCdnSecurity":{"type":"object","description":"How hard the edge is on suspicious traffic, and how it treats AI crawlers.","required":["site_id","supported","security_level","bot_fight_mode","ai_bots_protection","crawler_protection","always_use_https","automatic_https_rewrites","opportunistic_encryption","min_tls_version","protection_tier","bot_management_included"],"properties":{"site_id":{"$ref":"#/components/schemas/Uuid"},"supported":{"type":"boolean","description":"Whether the CDN serving this site can express these settings at all. `false` for a provider with no equivalent vocabulary; the other fields then carry defaults and a client should render the controls disabled rather than hiding the screen.","example":true},"unreadable":{"type":"array","items":{"type":"string"},"description":"Fields the CDN account's credential could not read, so their values here are defaults, not the zone's state. A client renders each listed control disabled and says it could not be read; the other fields are real. Empty when everything was read."},"flood_hold_until":{"type":["string","null"],"format":"date-time","description":"s1014 L04. While the flood guard holds this site's zone in Under Attack, the earliest it may lift it (the hold restarts on every pass that still sees the flood); `null` when it holds nothing. Meanwhile `security_level` cannot be lowered (`409`) — a client renders the reason instead of the level control.","example":null},"protection_tier":{"type":"string","description":"The protection level this organisation's plan sells (`protection_tier`). Absent from a plan means the floor — every site with a CDN already has the provider's baseline protection whether or not anyone sold it, so this is never \"none\".","example":"standard"},"bot_management_included":{"type":"boolean","description":"Whether that tier reaches bot management — enabling `bot_fight_mode`, or setting `ai_bots_protection`/`crawler_protection` to `block` or `managed_challenge`. Derived server-side on purpose: a client comparing tier strings would be a second copy of the ladder's ordering, and it would drift the day a rung is added. When `false` a client should disable those controls **with the reason shown**, rather than let the customer click and collect a refusal.\n\nTurning a control off is always permitted, on every tier, so this must never disable the \"off\" direction.","example":false},"security_level":{"$ref":"#/components/schemas/CdnSecurityLevel"},"bot_fight_mode":{"type":"boolean","description":"Challenge traffic the provider classifies as automated. Read from the provider's bot-management resource, not from a zone setting — the zone setting of that name does not exist.","example":false},"ai_bots_protection":{"$ref":"#/components/schemas/CdnAiBotMode"},"crawler_protection":{"$ref":"#/components/schemas/CdnCrawlerProtectionMode"},"always_use_https":{"type":"boolean","description":"Redirect every plain-HTTP request to HTTPS at the edge.","example":true},"automatic_https_rewrites":{"type":"boolean","description":"Rewrite insecure sub-resource URLs in HTML to HTTPS where possible.","example":true},"opportunistic_encryption":{"type":"boolean","description":"Advertise HTTP/2 over TLS to clients that arrive over plain HTTP.","example":true},"min_tls_version":{"$ref":"#/components/schemas/CdnMinTlsVersion"}}},"SiteCdnSecurityUpdate":{"type":"object","description":"A partial update. Every field is optional and an absent field is left alone, never reset — a client written before a control existed must not switch it off on save.","additionalProperties":false,"minProperties":1,"properties":{"security_level":{"$ref":"#/components/schemas/CdnSecurityLevel"},"bot_fight_mode":{"type":"boolean"},"ai_bots_protection":{"$ref":"#/components/schemas/CdnAiBotMode"},"crawler_protection":{"$ref":"#/components/schemas/CdnCrawlerProtectionMode"},"always_use_https":{"type":"boolean"},"automatic_https_rewrites":{"type":"boolean"},"opportunistic_encryption":{"type":"boolean"},"min_tls_version":{"$ref":"#/components/schemas/CdnMinTlsVersion"}}},"SiteCdnSettings":{"type":"object","description":"The edge behaviour a customer controls for their own zone.","required":["site_id","supported","supported_values","cache_level","development_mode","development_mode_seconds_remaining","always_online","ssl_mode","brotli","email_obfuscation"],"properties":{"site_id":{"$ref":"#/components/schemas/Uuid"},"supported":{"type":"boolean","description":"Whether the CDN serving this site can express these settings at all. `false` for a pull-zone provider with no equivalent vocabulary; the other fields then carry defaults and a client should render the controls disabled rather than hiding the screen.","example":true},"supported_values":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"For an **enumerated** supported field, which values this provider can be set to. A field absent from this map takes every value in its own vocabulary — the common case, so the payload is about the exceptions.\n\n⛔ Per FIELD was still not fine-grained enough, and the gap arrived as an error on the customer's save button. `cache_level` is `basic | simplified | aggressive`, while Bunny's and KeyCDN's controls are booleans, and CDN77's and Gcore's third state is a named parameter list rather than `basic`. So four of five providers take two of the three values, and a client must grey out the option rather than offering it and failing the save.\n\n⚠️ It narrows **writes only**. `cache_level` may be reported as `by_parameters`, which appears in no provider's list here by construction, so a client validating the CURRENT value against this map would reject two adapters' honest answer.\n\n⛔ Only enumerated fields appear. A boolean cannot be narrowed — a provider that cannot express one belongs outside `supported_fields`, not here with an empty list, which would render a control with no options.","example":{"cache_level":["simplified","aggressive"]}},"supported_fields":{"type":"array","items":{"type":"string"},"description":"Which of the six settings this site's CDN can actually express. ⛔ Sent always and **empty rather than omitted** when there are none — a client reading absence as \"all of them\" would render five controls for a provider that has none.\n\n⭐ The capability is per FIELD because the vendors make it so: read from their own published schemas, Bunny has no development-mode and no Brotli field, and CDN77 has neither plus no always-online. A single all-or-nothing flag over that matrix forces a choice between reporting success for a knob the provider ignored and refusing the whole patch. `PUT` answers `422` naming any field outside this list rather than dropping it — a dropped field is the same lie one layer up."},"cache_level":{"$ref":"#/components/schemas/CdnCacheLevelReported"},"development_mode":{"type":"boolean","description":"Bypass the cache entirely so edits are visible immediately. The provider expires this automatically — see `development_mode_seconds_remaining`.","example":false},"development_mode_seconds_remaining":{"type":"integer","minimum":0,"description":"Seconds until the provider switches development mode off again, as reported by the provider rather than derived from when we set it. `0` when it is off. It is a countdown and not a timestamp because that is the shape the provider returns; rendering \"expires in 2h 45m\" from it needs no clock of ours.","example":0},"always_online":{"type":"boolean","description":"Serve an archived copy of the page when the origin is unreachable.","example":false},"ssl_mode":{"$ref":"#/components/schemas/CdnSslMode"},"brotli":{"type":"boolean","description":"Serve Brotli-compressed responses to clients that accept them.","example":true},"email_obfuscation":{"type":"boolean","description":"Hide e-mail addresses on the site's pages from scrapers (the CDN rewrites them and a small script restores them for visitors). On by default at the provider; turn it off when a page script reads `mailto:` links itself. Only meaningful when listed in `supported_fields` (docs/1001 §1.2).","example":true}}},"SiteCdnSettingsUpdate":{"type":"object","additionalProperties":false,"minProperties":1,"description":"A **partial** update — send only what should change. An absent field is left alone, never reset, so a client that predates a setting cannot switch it off. Unknown properties are refused rather than discarded: on a pooled CDN account a zone resolves by name alone, so a body key that looked like a hostname must be impossible to submit quietly.","properties":{"cache_level":{"$ref":"#/components/schemas/CdnCacheLevel"},"development_mode":{"type":"boolean"},"always_online":{"type":"boolean"},"ssl_mode":{"$ref":"#/components/schemas/CdnSslMode"},"brotli":{"type":"boolean"},"email_obfuscation":{"type":"boolean"}}},"SiteCdnTieredCache":{"type":"object","required":["site_id","supported","tiered_cache","tiered_cache_editable","smart_routing","smart_routing_editable"],"properties":{"site_id":{"$ref":"#/components/schemas/Uuid"},"supported":{"type":"boolean","description":"A fact about the **driver** — whether this provider has the feature at all.","example":true},"tiered_cache":{"type":"boolean","example":false},"tiered_cache_editable":{"type":"boolean","description":"A fact about the **zone's plan**, reported separately from `supported`. A free zone answers `false` and the control must be disabled rather than offering a save the provider will refuse.","example":false},"smart_routing":{"type":"boolean","nullable":true,"description":"`null` — never `false` — when the provider refuses to report it. `false` would tell a customer that a paid feature they are not buying is switched off.","example":null},"smart_routing_editable":{"type":"boolean","example":false}}},"SiteCdnTieredCacheUpdate":{"type":"object","additionalProperties":false,"required":["enabled"],"properties":{"enabled":{"type":"boolean"}}},"SiteCdnUsage":{"type":"object","required":["metered","period","spend_micros","cap_micros","cap_source","percent","status","warn_low_pct","warn_high_pct","last_checked_at","tiers"],"properties":{"metered":{"type":"boolean","description":"False on an unmetered CDN (included, no allowance, never paused)."},"period":{"type":"string","description":"The UTC month, `YYYY-MM`.","example":"2026-11"},"spend_micros":{"type":"integer","format":"int64","description":"Provider cost of serving the site this month, in micro-USD."},"cap_micros":{"type":"integer","format":"int64","description":"This month's allowance (default or override, plus top-ups), in micro-USD."},"cap_source":{"type":"string","enum":["default","override","upgraded"]},"percent":{"type":"integer","minimum":0},"status":{"type":"string","enum":["ok","warned","paused","failed","unmetered"]},"warn_low_pct":{"type":"integer"},"warn_high_pct":{"type":"integer"},"last_checked_at":{"type":"string","format":"date-time","nullable":true},"tiers":{"type":"array","items":{"$ref":"#/components/schemas/SiteCdnUsageTier"}}}},"SiteCdnUsageTier":{"type":"object","required":["code","name","extra_micros","price_minor","currency","enough"],"properties":{"code":{"type":"string","example":"small"},"enough":{"type":"boolean","description":"Whether this top-up lifts the site back under its allowance this month (spend < allowance + extra). A top-up that is not `enough` would leave the CDN paused, so it is refused (V1 parity, docs/1302 §1)."},"name":{"type":"string"},"extra_micros":{"type":"integer","format":"int64","description":"Extra allowance this top-up adds for the rest of the month, in micro-USD."},"price_minor":{"type":"integer","description":"Price in integer minor units of `currency`."},"currency":{"type":"string","minLength":3,"maxLength":3,"example":"USD"}}},"SiteCdnUsageTopUp":{"type":"object","required":["tier","extra_micros","price_minor","currency","period","usage"],"properties":{"tier":{"type":"string"},"extra_micros":{"type":"integer","format":"int64"},"price_minor":{"type":"integer"},"currency":{"type":"string","minLength":3,"maxLength":3},"period":{"type":"string"},"usage":{"$ref":"#/components/schemas/SiteCdnUsage"}}},"SiteCdnUsageTopUpRequest":{"type":"object","required":["tier","request_id"],"properties":{"tier":{"type":"string","maxLength":32},"request_id":{"type":"string","maxLength":100,"description":"Client-generated idempotency key; a retry with the same id is a no-op."}}},"SiteCertificateStatus":{"type":"object","description":"The TLS certificate serving one site (#5711, `docs/537`).\n","required":["site_id","state","scope","hostnames","covered","serving"],"properties":{"site_id":{"type":"string","format":"uuid"},"state":{"type":"string","enum":["none","pending","issued","failed","retired"],"description":"⛔ `none` means nothing has been attempted, which is a DIFFERENT fact from `failed`. Collapsing them would leave a screen unable to tell a new site from a broken one.\n"},"scope":{"type":"string","enum":["site","shared"],"description":"`shared` when one platform certificate for a registrable domain we own covers this site — the ordinary case for a preview hostname.\n"},"shared_suffix":{"type":"string","description":"The registrable domain a shared certificate covers. Empty when `scope` is `site`."},"hostnames":{"type":"array","items":{"type":"string"},"description":"Read back off the ISSUED artefact, never from what was requested — a CA that trimmed a name must not be reported as covering it.\n"},"covered":{"type":"boolean","description":"A certificate authority has signed a certificate for this site."},"serving":{"type":"boolean","description":"⛔ The box actually presents it. DIFFERENT from `covered`: a certificate that exists in Vault and is not installed serves nobody.\n"},"failure_reason":{"type":"string"},"failure_detail":{"type":"string"},"not_after":{"type":"string","format":"date-time","nullable":true},"installed_at":{"type":"string","format":"date-time","nullable":true},"environment":{"type":"string","description":"⛔ Travels because a `staging` certificate is trusted by NO browser. A screen showing one as simply \"issued\" would report green for a site every visitor sees a warning on.\n"},"wildcard_covered":{"type":"boolean","description":"Whether subdomains are covered. A wildcard needs DNS-01, which needs a TXT record in the zone, so a domain whose DNS we do not manage cannot have one.\n"}}},"SiteCleaner":{"type":"object","description":"The Site Cleaner for one site (s1014 B01, docs/1081 §7).","required":["site_id","offered","active","supported","can_buy","prices","schedule","skip","jobs"],"additionalProperties":false,"properties":{"site_id":{"type":"string","format":"uuid"},"offered":{"type":"boolean","description":"Whether the add-on is on sale to this organisation."},"active":{"type":"boolean","description":"Whether the account holds it and may clean now."},"supported":{"type":"boolean"},"unsupported_reason":{"type":"string","nullable":true},"can_buy":{"type":"boolean"},"refusal":{"type":"string","nullable":true},"prices":{"type":"array","items":{"type":"object","required":["code","amount_minor","currency"],"additionalProperties":false,"properties":{"code":{"type":"string","enum":["site_cleaner","site_cleaner_yearly"]},"amount_minor":{"type":"integer"},"currency":{"type":"string"}}}},"purchase_id":{"type":"string","format":"uuid","nullable":true},"renews_on":{"type":"string","format":"date","nullable":true},"ends_on":{"type":"string","format":"date","nullable":true},"schedule":{"type":"string","enum":["off","daily","weekly","monthly"]},"next_run_at":{"type":"string","format":"date-time","nullable":true},"skip":{"type":"array","items":{"type":"string"}},"last_scan":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/SiteCleanerJob"}]},"in_flight":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/SiteCleanerJob"}]},"jobs":{"type":"array","items":{"$ref":"#/components/schemas/SiteCleanerJob"}}}},"SiteCleanerItem":{"type":"object","description":"One thing the Site Cleaner could remove (from a scan).","required":["id","cat","name"],"additionalProperties":true,"properties":{"id":{"type":"string","description":"Stable item id, e.g. `db:revisions`, `plugin:<slug>`."},"cat":{"type":"string","enum":["plugins","themes","leftovers","database","logs","files"]},"name":{"type":"string"},"detail":{"type":"string"},"mb":{"type":"number","description":"Approximate size in MB."},"files":{"type":"integer"},"rows":{"type":"integer"},"default":{"type":"boolean","description":"Ticked by default (a scheduled clean removes it)."},"paths":{"type":"array","items":{"type":"string"},"description":"Files and folders (relative to the site folder) that go with it, first 50."}}},"SiteCleanerJob":{"type":"object","description":"One Site Cleaner scan, clean or undo of one site.","required":["id","kind","trigger","state","message","has_backup","created_at"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["scan","clean","undo"]},"trigger":{"type":"string","enum":["manual","schedule","staff"]},"state":{"type":"string","enum":["queued","running","done","nothing","restored","failed"]},"cms":{"type":"string","description":"The application detected: wordpress, joomla, drupal, prestashop, opencart, grav, mediawiki, laravel, phpbb, matomo, owncloud, nextcloud or other."},"message":{"type":"string"},"totals":{"type":"object","additionalProperties":true,"description":"count, mb, files, rows of the selected (clean) or default-ticked (scan) items."},"selected":{"type":"array","items":{"type":"string"}},"saved_mb":{"type":"number"},"saved_files":{"type":"integer"},"saved_db_mb":{"type":"number"},"removed_count":{"type":"integer"},"has_backup":{"type":"boolean","description":"Whether a backup was taken before the clean."},"backup_expires_at":{"type":"string","format":"date-time","nullable":true},"undo_of":{"type":"string","format":"uuid","nullable":true},"created_at":{"type":"string","format":"date-time","nullable":true},"started_at":{"type":"string","format":"date-time","nullable":true},"finished_at":{"type":"string","format":"date-time","nullable":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/SiteCleanerItem"}}}},"SiteClone":{"type":"object","required":["id","blueprint_id","site_id","site_name","site_domain","site_status","step","message","can_retry","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"blueprint_id":{"$ref":"#/components/schemas/Uuid"},"site_id":{"$ref":"#/components/schemas/Uuid"},"site_name":{"type":"string"},"site_domain":{"type":"string"},"site_status":{"type":"string","description":"The new site's status, or `deleted` when it no longer exists."},"step":{"$ref":"#/components/schemas/SiteCloneStep"},"message":{"type":"string","description":"Why it failed, or what still needs attention. English; shown verbatim."},"can_retry":{"type":"boolean","description":"Whether `retrySiteClone` will accept this row."},"created_at":{"type":"string","format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"}}},"SiteCloneAccepted":{"type":"object","required":["site","clone"],"properties":{"site":{"$ref":"#/components/schemas/Site"},"clone":{"$ref":"#/components/schemas/SiteClone"}}},"SiteCloneRequest":{"type":"object","additionalProperties":false,"required":["primary_domain"],"properties":{"primary_domain":{"type":"string","description":"The new site's domain. It must not be in use by any site."},"name":{"type":"string","maxLength":200,"description":"A name for the new site in your site list. Defaults to the domain."}}},"SiteCloneStep":{"type":"string","enum":["copying","waiting","restoring","done","failed"],"description":"`copying` — the copy of the original is being taken; `waiting` — the new site is still being built; `restoring` — the copy is being put onto it; `done`; `failed`."},"SiteCmsTarget":{"type":"object","description":"Where one site's posts go. ⛔ **No secret is ever returned, in any form** — not masked, not last-four. `has_credential` is a boolean and the only consumer of the value is the adapter making the call.","required":["site_id","kind","preset","base_url","collection","auth_scheme","auth_header","field_map","enabled","has_credential","capabilities","detected_identity","last_probe_at","last_probe_reachable","last_probe_code","last_probe_detail"],"properties":{"site_id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["","wordpress","headless_rest","git_static"],"description":"Empty when nothing claims this site. For a site with no configured row this is the **derived** target — most WordPress sites on our own fleet need no configuration at all, because we hold a managed shell on the box."},"preset":{"type":"string","enum":["","payload","strapi","directus","ghost","shopify","webflow","custom"]},"base_url":{"type":"string","description":"The CMS's API root. Empty for a target whose address is derived from the site (fleet WordPress, a connected Git repository)."},"collection":{"type":"string","description":"The collection posts are created in — `posts` on Payload, a blog id on Shopify, a collection id on Webflow, the content directory on a Git target."},"auth_scheme":{"type":"string","enum":["","bearer","payload_api_key","ghost_admin_jwt","shopify_token","header"]},"auth_header":{"type":"string","description":"For the `header` auth scheme — which header the key is sent in."},"field_map":{"type":"object","additionalProperties":{"type":"string"},"description":"Renames, for a destination that spells our fields differently. ⛔ It **renames**; it never adds a capability. A field map cannot make a target able to carry a tag it has no field for."},"enabled":{"type":"boolean","description":"A disabled target is skipped and reads as `needs_setup` — kept rather than deleted so pausing publishing to a site does not lose its set-up."},"has_credential":{"type":"boolean"},"capabilities":{"type":"array","items":{"type":"string"}},"detected_identity":{"type":"string","description":"What the destination said it was, last time it answered."},"last_probe_at":{"type":"string","format":"date-time","nullable":true},"last_probe_reachable":{"type":"boolean","nullable":true,"description":"⛔ `null` means **never probed**; `false` means probed and could not be reached. Those are different facts and a client must not render them the same."},"last_probe_code":{"type":"string"},"last_probe_detail":{"type":"string"}}},"SiteCmsTargetWrite":{"type":"object","required":["kind"],"properties":{"kind":{"type":"string","enum":["wordpress","headless_rest","git_static"]},"preset":{"type":"string","enum":["","payload","strapi","directus","ghost","shopify","webflow","custom"]},"base_url":{"type":"string","maxLength":400},"collection":{"type":"string","maxLength":64},"auth_scheme":{"type":"string","enum":["","bearer","payload_api_key","ghost_admin_jwt","shopify_token","header"]},"auth_header":{"type":"string","maxLength":64},"field_map":{"type":"object","additionalProperties":{"type":"string"}},"enabled":{"type":"boolean","default":true},"secret":{"type":"string","writeOnly":true,"description":"The API key. ⛔ Write-only, and **omitting it keeps the credential you already have** rather than clearing it. It is written to Vault before the row is saved, and the row is only saved if that succeeded."}}},"SiteCollaborator":{"type":"object","description":"One person's access to one site. `active` and `status` are computed by the engine, never by the client: a clock skew between browser and server would otherwise show an \"active\" chip on a grant the engine has already stopped honouring.","required":["id","site_id","user_id","email","role","reason","granted_by","created_at","expires_at","active","status"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"site_id":{"type":"string","format":"uuid"},"user_id":{"type":["string","null"],"format":"uuid","description":"The collaborator, once known. Null while the grant is `pending` — the address has been invited and has not accepted yet (whether or not it has an account)."},"email":{"type":"string","format":"email"},"role":{"$ref":"#/components/schemas/SiteCollaboratorRole"},"reason":{"type":"string","description":"Why this person was given this site. Required on creation, and returned here because a year later it is the only thing that can answer *\"why does this person have my site?\"*."},"granted_by":{"type":"string","description":"The audit ref of whoever granted it, `user:<id>`."},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time","description":"When the grant lapses on its own, or null for *until revoked*. Evaluated at read time, so it takes effect on the clock rather than when a sweep next runs."},"active":{"type":"boolean","description":"Neither revoked nor past its expiry, as of this response."},"status":{"type":"string","enum":["pending","active","expired","revoked"],"description":"`pending` — invited, waiting for the person to sign in as that address; `active` — in force now; `expired` — lapsed on its own end date; `revoked` — ended by the owner, the row kept for the audit question."}}},"SiteCollaboratorCreate":{"type":"object","required":["email","role","reason"],"additionalProperties":false,"properties":{"email":{"type":"string","format":"email","maxLength":320,"description":"The person to share with. An address with no account here is invited in the same call and the grant is returned `pending` — see the endpoint description."},"role":{"$ref":"#/components/schemas/SiteCollaboratorRole"},"reason":{"type":"string","maxLength":300,"minLength":1,"description":"Why they are being given this site. Required rather than optional: an optional reason is one nobody fills in, and the audit value of the record collapses to *\"somebody granted somebody something once\"*."},"expires_at":{"type":["string","null"],"format":"date-time","description":"Optional automatic end. Null means until revoked. A time in the past is refused with `expiry_in_the_past` rather than silently creating a dead grant."}}},"SiteCollaboratorRole":{"type":"string","enum":["viewer","editor","manager"],"description":"What a collaborator may do on the site they were granted. `viewer` reads it; `editor` adds the day-to-day work (deploys, cache, plugins, staging); `manager` adds the structural and destructive operations (restore, domain, SSL, DNS). No level includes deleting the site or seeing what the owner pays for it — a collaborator cannot delete the thing they were lent, and billing is never theirs."},"SiteCollaboratorRoles":{"type":"object","required":["items","collaborator_role_seeded"],"additionalProperties":false,"properties":{"items":{"type":"array","items":{"type":"object","required":["key","label"],"additionalProperties":false,"properties":{"key":{"$ref":"#/components/schemas/SiteCollaboratorRole"},"label":{"type":"string"}}}},"collaborator_role_seeded":{"type":"boolean","description":"Whether the `site_collaborator` organisation role exists in this deployment. See the endpoint description: it separates an empty answer from a blind one."}}},"SiteContentState":{"type":"object","additionalProperties":false,"required":["site_id","state"],"properties":{"site_id":{"type":"string","format":"uuid"},"state":{"type":"string","enum":["empty","present","unknown"],"description":"`unknown` means the server could not be asked — never render it as `empty`.","example":"empty"}}},"SiteCreate":{"type":"object","description":"Send `primary_domain`, or `temporary_domain: true` for a site with no domain yet (exactly one of the two).","required":["product_line"],"properties":{"org_id":{"description":"The organization to create the site under. Defaults to the caller's org; the caller must hold `sites.create` in the target org.","anyOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]},"product_line":{"type":"string","minLength":1,"maxLength":64,"example":"footprint_free"},"primary_domain":{"$ref":"#/components/schemas/Hostname"},"parent_site_id":{"type":["string","null"],"format":"uuid","description":"Create this site as a STANDALONE SUBDOMAIN of one of the organisation's own sites (master 1105#32 C, the V1 model). `primary_domain` must end in `.<parent primary_domain>`; the parent must be a live site in the same organisation and must not itself be a subdomain site (one level deep). It is a full site and uses one site slot; its DNS goes into the parent's zone. A subdomain added UNDER a site instead is `POST /v1/sites/{site_id}/subdomains`. A refusal is `422` naming `parent_site_id` or `primary_domain`."},"temporary_domain":{"type":"boolean","description":"No domain yet: the platform gives the site a free address on its preview domain (`t-<12 hex>.zinnpreview.com`, HTTPS from the start) and returns it as `primary_domain`. The customer moves the site onto their own domain later with `POST /v1/sites/{site_id}/rename-domain` (the free address keeps redirecting). Not allowed together with `primary_domain`; one of the two is required."},"name":{"type":"string","maxLength":200,"example":"Acme Marketing Site"},"source":{"$ref":"#/components/schemas/SiteSource"},"blueprint_id":{"description":"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.","anyOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]},"site_blueprint_id":{"description":"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 it, so it comes up with the same content, plugins, theme and settings as the site it was captured from — and its stored web addresses are rewritten to this site's domain. ⛔ **Not the same field as `blueprint_id`**: that one names a stack recipe Zinn® publishes, this one names a template you made from a site you already built. Sending both is a `422`. When given, `source`, `stack_type` and `runtime` are all derived and must not be sent. A blueprint whose capture has not finished, or whose backup is no longer available, is a `422` at create time rather than a site that comes up empty an hour later.","anyOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]},"stack_type":{"$ref":"#/components/schemas/StackType"},"runtime":{"description":"**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 and accepted. Still accepted for compatibility when it matches what the stack derives; a value that disagrees is a `422` rather than being silently corrected.","allOf":[{"$ref":"#/components/schemas/Runtime"}]},"php_version":{"type":"string","maxLength":8,"description":"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 what is available, never a silent fallback. Omit for the line's default. A `422` too on a stack that does not run PHP — a static site has no PHP handler to pin. Changeable afterwards via `PUT /v1/sites/{siteId}/php-version`.","example":"8.3"},"application":{"type":"string","maxLength":64,"description":"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:\n\n* `stack_type: one_click` — the `key` of an entry from `GET /v1/hosting/applications?product_line=…`, the vendor's live catalogue intersected with the line's rows. Omit it and a `one_click` site is created as a plain PHP account the customer can install onto later from the site's own panel — a real product, not a broken state. An application the product line does not offer is a `422` naming the line, never a silent drop.\n* `stack_type: headless_cms` — the `key` of a CMS we host on our own fleet (`payload`, `strapi`, or `custom` to bring your own), from `GET /v1/hosting/fleet-applications`. This stack exists **to** ask the question, so there is no default: a CMS we do not host is a `422` that names the choices.\n\nNaming an application on any other stack is a `422`, because that stack already decides what gets installed and the two would silently disagree — a `nextcloud` site installs Nextcloud.","example":"payload"},"application_licence_key":{"type":"string","maxLength":80,"writeOnly":true,"description":"The customer's own licence key for an application that cannot install without one (today `whmcs`). Required for such an application and a `422` (code `REQUIRED`) when absent; a `422` (code `INVALID`) for a key in the wrong shape or for an application that takes no key. Stored only in the secret store, used once by the installer, and never returned by any endpoint.","example":"Owned-1a2b3c4d5e6f7g8h9i0j"},"application_licence_source":{"type":"string","enum":["own","zinn"],"writeOnly":true,"description":"Where a licensed application's licence comes from. `own` (the default) means `application_licence_key` is required. `zinn` means a licence from our reseller pool is assigned to the site and billed monthly at `FleetApplication.licence_offer`'s price; `application_licence_key` must then be absent. A `422` on this field (code `UNAVAILABLE`) when no licence can be supplied just now, (code `INVALID`) for an application that takes no licence.","example":"zinn"},"subscription_id":{"description":"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 exist elsewhere).","anyOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]},"region":{"type":"string","description":"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 checked against the regions we run (`engine.hosting.regions`), a vendor-hosted site against the data centres we have activated (`listHostingLocations`). A value in neither is refused with a `422` naming the choices — the refusal happens here rather than inside the provisioning workflow, where the only thing the customer would see is a site that failed. The stored value is lower-cased: worker regions and data-centre codes are lower-case and are matched exactly, so `NBG1` would otherwise be a value guaranteed to match nothing.\n\nA fleet region we run that has **no box able to take this site right now** is refused with error code `REGION_UNAVAILABLE` (`details[0].offered` lists the regions that can) — before the site row exists. `listHostingRegions` is the list to choose from.","maxLength":32,"example":"nbg1"},"cdn_vendor":{"type":"string","description":"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 Footprint-Free site is spread across the pool deliberately, so naming a vendor is a `422`. Must be a vendor returned by `GET /v1/sites/provider-options`.","maxLength":64,"example":"bunnycdn"},"dns_vendor":{"type":"string","description":"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 organization already holds adopts that zone's provider, because one zone cannot be served by two providers at once.","maxLength":64,"example":"bunny_dns"},"use_own_dns":{"type":"boolean","description":"Serve this site's DNS from **your own connected DNS account** rather than Zinn®'s pool (W20-G). Checked before anything is provisioned: when `true`, the read-only pre-flight (`preflightOwnDns`) must pass or the create is refused with 422 naming the fix.\n\n⛔ This is a different question from `dns_vendor`, and the two must not be confused: `dns_vendor` picks **which provider** inside our pool, this picks **whose account**. An organization can legitimately want Bunny from our pool, or Cloudflare from their own account, and only one of those is expressible as a vendor name.\n\nA **preference, not a demand**: if the organization has no usable DNS connection the site falls back to the pool, because a site that cannot be provisioned is a worse outcome than one provisioned on our account with the connection checklist saying why. Connect an account first at `POST /v1/connections/{provider}`."},"cdn_tier":{"type":"string","description":"The CDN tier this site starts on (W20-G — \"deploy/select it at deployment time for the applicable lines\").\n\n⭐ Omit for the product line's own default, which is **not** the same as `off`: a Footprint-Free line defaults to Premium because the edge is what keeps the origin unreachable. `byo` requires an already-connected Cloudflare account (`NO_CLOUDFLARE_CONNECTION` otherwise).\n\n⛔ A managed (Footprint-Free) line accepts only its own tier (`premium`), as a no-op, and refuses every other value with `FOOTPRINT_MANAGED`, **including `byo`** (and `premium` with a `cdn_account_id`). Moving such a site to your own account is allowed (owner ruling G-3) but only from the site's CDN tab, where the shared-footprint warning and its confirmation live — accepting it here would take a footprint decision the customer was never shown.","maxLength":16,"example":"byo"},"cdn_account_id":{"type":"string","description":"**Which** of your own CDN accounts the site is created on — the half `cdn_tier` cannot express. List them with `listCdnTargetsForCreate`.\n\n⛔ Only meaningful with `cdn_tier: byo`, and sending it with any other tier is **refused** rather than ignored: it would be stored nowhere and change nothing, so the request would appear to have been honoured while the site went onto whichever account the platform preferred.\n\n⛔ The id must name an account of **your own organisation**. A platform pool account id is refused, not accepted — placing your site on shared infrastructure you do not own is exactly the linkage the account model exists to prevent.\n\nOmit it, or send an empty string, to use Zinn®'s pool.","maxLength":64},"canonical_host":{"type":"string","enum":["apex","www"],"description":"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** rather than corrected afterwards: the alias is attached and redirected as part of bringing the site up, and a later change republishes both.\n\nOmitted means the platform default, `apex`."},"create_mailbox":{"type":"boolean","description":"\"Create an email account\" (G13). Read by the Footprint-Free line only, which forwards the domain's mail and gets a mailbox only when asked; the forward stays. Every other line gets its starter mailbox regardless. **Omitted means `false`.** A mailbox can be added later from the site's Email tab or the Email screen."},"site_title":{"type":"string","maxLength":200,"description":"The WordPress **Site Title** (V1 parity). Read for a WordPress stack only. Omitted or blank means the primary domain, as before. With `site_blueprint_id` it is the COPY's title instead, one line: omitted or blank means a fresh one is chosen, and ⛔ a copy never keeps the original site's title."},"site_tagline":{"type":"string","maxLength":200,"description":"The WordPress **Tagline** (`blogdescription`). Read for a WordPress stack only. Omitted or blank leaves WordPress's own tagline. With `site_blueprint_id` it is the COPY's tagline, one line: omitted or blank means a fresh one is chosen."},"force_https":{"type":"boolean","description":"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."},"plugins":{"type":"array","maxItems":30,"items":{"type":"string","pattern":"^[A-Za-z0-9_][A-Za-z0-9_-]*$","maxLength":128},"description":"WordPress.org plugin slugs to install and activate while the site is built, on top of whatever the blueprint declares. WordPress stacks only; any other stack is a `422`."},"theme":{"type":"string","pattern":"^([A-Za-z0-9_][A-Za-z0-9_-]*)?$","maxLength":128,"description":"A WordPress.org theme slug to install and activate while the site is built. Omitted or blank means WordPress's own default theme — the one that ships inside the release the site is built on, which is always the current stable release.\n\nA slug the theme directory does not know is a `422` naming it. If the directory cannot be reached the choice is accepted and installed during provisioning. WordPress stacks only.","example":"astra"},"random_theme":{"type":"boolean","description":"**Footprint-Free only.** Let the platform draw the theme from WordPress.org's popular themes. The draw happens once, when the site is created, and is stored — so a retried build installs the same theme. Refused (`422`) on any other product line, on a stack without WordPress, and alongside `theme`; `503` when the theme directory cannot be reached, because there is no honest fallback theme. `GET /v1/sites/provider-options` says which lines offer it (`wordpress_theme.modes`)."},"footprint_acknowledged":{"type":"boolean","description":"Omitted means `false`. The customer accepted the shared-footprint warning for their own CDN account on a platform-managed line (Footprint-Free). With it, `cdn_tier: byo` plus a named `cdn_account_id` is accepted at create on that line; without it, refused (`422`)."},"deploy_target":{"type":"string","maxLength":16,"description":"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 created before this field existed resolves to.\n\nOnly a value from `getSiteProviderOptions`' `deploy_targets` with `available: true` is accepted, and the three conditions are checked on every create: the target is an edge host, this organization holds an **active connection** to it, and the `external_deploy_targets` allowance has room. Anything else is a `422` naming this field — including the targets that run on **our** platforms, which are real values your plan may already place you on and are still not yours to choose.\n\n⛔ Which of **our** platforms a site runs on is not a request field and will not become one: `deploy_target` selects the provisioning driver and, through the DNS authority, the nameservers, so accepting an arbitrary value would let any caller holding `sites.create` provision on our reseller account without a plan that entitles them to it. An edge host is different in kind, which is why it is allowed: the site runs on **your** provider account and your bill, which is what the extra-externally-hosted-sites add-on sells.","example":"netlify"},"panel_connection_id":{"description":"**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.\n\n⛔ **Required when the resolved deploy target is `plesk`**, and the word *resolved* is the operative one: the target is usually decided by the plan you bought rather than by the `deploy_target` field above, so a create that names no target at all can still land on `plesk` and still needs this. Omitting it is a `400` with code `PANEL_CONNECTION_REQUIRED`, refused at the form rather than accepted and failed during provisioning — a panel site with no connection is not degraded, it is unreachable, and there is no fallback: a site whose panel is unknown cannot be resolved to the org's default hosting connection, because on this estate that is a different vendor's account entirely.\n\n⛔ Sending it for **any other** target is a `400` with code `PANEL_CONNECTION_NOT_APPLICABLE`, never a silently ignored field. A caller who believes they are placing a site on their own panel and is quietly given a fleet site has been told the opposite of what happened.\n\n⛔ The id must belong to **the organization the site is being created in** — not merely to somewhere in your account tree. One panel connection is admin over every other site on the same box, so accepting an id from a sibling organization would operate one client's site through another client's credential. A connection that is not this organization's is a `404` with the same wording as one that does not exist, so the endpoint cannot be used to learn which panel ids exist elsewhere.\n\n⭐ `null` is accepted and means exactly what omitting it means — *no panel* — so a client that always sends the field can leave it empty for a fleet site without tripping the not-applicable refusal. Only a **present, non-null** id counts as asking for a panel.","anyOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]}}},"SiteCustomDomain":{"type":"object","description":"A hostname bound to the site's deploy target, and its DNS state.","required":["hostname","is_primary","status","is_apex","dns_mode","dns_zone","dns_vendor","dns_written_at","resolves","last_checked_at","last_check_detail","records","refusal"],"properties":{"hostname":{"type":"string"},"is_primary":{"type":"boolean"},"status":{"type":"string","enum":["pending","active","failed"],"description":"The provider's verdict on the binding."},"is_apex":{"type":"boolean","description":"Whether this hostname is the zone apex. An apex cannot hold a CNAME, so its record set is provider-specific and sometimes impossible — see `refusal`."},"dns_mode":{"type":"string","enum":["unknown","our_zone","byo_dns","nameservers","keep_dns","manual"],"description":"Which DNS tier this hostname landed on. `unknown` means nothing has been attempted yet and must not be rendered as \"no action needed\". `keep_dns` (Q464): the records are ready, but the domain keeps its DNS where it is — a partner moved the site here, or our zone would not carry the e-mail the domain receives today — so the customer adds the records at their current DNS and is never asked to change nameservers."},"dns_zone":{"type":"string"},"dns_vendor":{"type":"string"},"dns_written_at":{"type":"string","format":"date-time","nullable":true},"resolves":{"type":"boolean","nullable":true,"description":"Three-valued. `true` every wanted record is live, `false` at least one answered and is wrong, `null` no check has answered. `null` is not `false`."},"last_checked_at":{"type":"string","format":"date-time","nullable":true},"last_check_detail":{"type":"string"},"records":{"type":"array","items":{"$ref":"#/components/schemas/DnsRecordPlan"}},"refusal":{"type":"string","description":"Non-empty when no valid record set exists for this hostname at this provider — today, a Cloudflare Pages apex on a zone that is not on Cloudflare DNS, because that provider publishes no apex address and relies on CNAME flattening."}}},"SiteCustomDomainDns":{"type":"object","description":"The outcome of publishing (or checking) one hostname's records.","required":["hostname","mode","zone","vendor","detail","nameservers","records","checks","resolves"],"properties":{"hostname":{"type":"string"},"mode":{"type":"string","enum":["unknown","our_zone","byo_dns","nameservers","keep_dns","manual"]},"zone":{"type":"string"},"vendor":{"type":"string"},"detail":{"type":"string"},"nameservers":{"type":"array","items":{"type":"string"},"description":"Populated only in `nameservers` mode — the zone is built and the records are in it, and setting these at the registrar is the one thing left to do."},"records":{"type":"array","items":{"$ref":"#/components/schemas/DnsRecordPlan"}},"checks":{"type":"array","items":{"$ref":"#/components/schemas/DnsRecordCheck"}},"resolves":{"type":"boolean","nullable":true}}},"SiteCustomDomainWrite":{"type":"object","required":["hostname"],"properties":{"hostname":{"type":"string","maxLength":253},"write_dns":{"type":"boolean","default":true,"description":"Publish the DNS records in the same call. Defaults to true because doing the DNS for the customer is the point of this surface; opting out is the unusual request."}}},"SiteDatabase":{"type":"object","description":"A site's database size + single-use SSO links into its phpMyAdmin, File Manager and Web IDE panels (see `getSiteDatabase`). The figures come from the fleet worker and the panels are provisioned per host, so an un-provisioned site returns `available: false` with null figures and null panel URLs — never fabricated zeros or a link to a panel that is not there.","required":["available","size_mb","tables","phpmyadmin_sso_url","filemanager_sso_url","web_ide_sso_url"],"properties":{"available":{"type":"boolean","description":"Whether a host is serving this site's database + panels yet."},"reason":{"type":"string","description":"Why a link or a figure is missing, in words a customer can act on. `available: false` alone cannot distinguish \"this site has no server yet\" from \"we could not reach the box\" from \"we refuse to hand this panel out\", and those need different responses from the reader.\n\n⛔ This paragraph used to end: *\"the File Manager URL is null by design rather than pending: the panel on a worker box has a single administrator account whose home is `/`, so it cannot be scoped to one site.\"* That was true for one day and was **reversed by the owner on 2026-08-15** — the engine now mints a per-site File Manager token scoped to one account's home with no `chmod`. The code changed and this description did not (W22-H, D10418). A null File Manager URL today means the site has no box of ours to scope a home on, e.g. it is hosted on the managed platform — a fact about the hosting, not a policy about the customer."},"reason_code":{"type":"string","description":"A stable, machine-readable name for the reason above — the half a CLIENT should render. `reason` is English prose for staff, SDK consumers and support tickets; this platform ships in 58 languages, so a client that prints `reason` to a customer has shipped English into every one of them.\n\n⛔ Added by W22-H (D11371) after exactly that gap was measured: the engine composed five distinct `reason` values, the OpenAPI schema declared the field, and the dashboard's own `SiteDatabase` type omitted it — so every cause rendered as one generic \"Not available for this site\". A field being in the spec is not evidence anything reads it.\n\nClients map this to their own translated string and fall back to a generic translated line for a code they do not know, exactly as the dashboard's migration warnings already do. Adding a value here is therefore safe and can never put raw English on a customer's screen.\n\nValues today - `site_has_no_server`, `hosting_has_no_database_panel`, `host_offers_no_database_panel`, `panel_host_unreachable` (retrying is sensible), `panel_cannot_open_needs_support` (retrying is futile, a human must intervene), `filemanager_not_on_our_fleet`. Empty string when nothing is wrong.\n\n⛔ `panel_host_unreachable` and `panel_cannot_open_needs_support` are the two halves of #2840 and MUST stay distinct: both were reported as \"try again in a few minutes\", so a customer whose credential can never resolve was told to wait, and waiting was not the remedy."},"size_mb":{"type":["integer","null"],"format":"int64","minimum":0,"description":"Total database size in MB; null when unavailable."},"tables":{"type":["integer","null"],"minimum":0,"description":"Number of tables in the database; null when unavailable."},"tools":{"type":"array","items":{"type":"string","enum":["phpmyadmin","filemanager","web_ide"]},"description":"The per-site tools this site has a door for (open one with `createSitePanelSession`). On the full read it is exactly the tools whose URL is non-null; on `links=false` it comes from the last stored reading."},"checked_at":{"type":["string","null"],"format":"date-time","description":"When the site's server was last asked for this reading. `null` on `links=false` when it has never been asked on the site's current host (a background reading has been started)."},"phpmyadmin_sso_url":{"type":["string","null"],"format":"uri","description":"HTTPS single-use SSO link into phpMyAdmin, minted on read; null when the panel is not provisioned. Never a non-HTTPS URL."},"filemanager_sso_url":{"type":["string","null"],"format":"uri","description":"HTTPS single-use SSO link into the File Manager, minted on read; null when the panel is not provisioned. Never a non-HTTPS URL."},"web_ide_sso_url":{"type":["string","null"],"format":"uri","description":"HTTPS single-use SSO link into the Web IDE — real VS Code (`code-server`) running in the browser against this site's files. Minted on read; null when the site is not on one of our own hosts. Never a non-HTTPS URL.\n\nThe editor runs as the site's **own Linux account inside that account's CageFS jail**, one process per site, so its integrated terminal cannot name — let alone read — another tenant's files. That is why this is null for a vendor-hosted site: there is no cage of ours to run it in. A fact about the hosting, not a policy about the customer."}}},"SiteDatabaseQueryResult":{"type":"object","description":"One guarded statement's outcome.","required":["ok","verb","write"],"properties":{"ok":{"type":"boolean"},"verb":{"type":"string","example":"SELECT"},"write":{"type":"boolean"},"dry_run":{"type":"boolean","description":"True when a write was rolled back as a preview."},"error":{"type":"string","description":"MySQL's own refusal, when `ok` is false."},"affected":{"type":"integer","description":"Rows a write changed (or would change)."},"total_rows":{"type":"integer"},"columns":{"type":"array","items":{"type":"string"}},"rows":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"SiteDeletion":{"type":"object","description":"The deletion lifecycle of one site, as the customer's danger zone renders it.\n\nThe grace period is a **row**, not a timer nobody can see: what was typed, who asked, when it fires. During it the site is not suspended — it serves normally, so a customer who changes their mind loses nothing by waiting.","required":["site_id","primary_domain","state","deletable","scheduled_for","requested_at","grace_days","grace_free_reason","can_cancel"],"additionalProperties":false,"properties":{"site_id":{"type":"string","format":"uuid","description":"The site this deletion state belongs to.","example":"0f8f2c66-1b0a-4c6a-9c5b-2a2f0f2c3d44"},"primary_domain":{"type":"string","description":"⛔ What the customer must type into `deleteSite`, and what the engine compares against. Read it from here rather than from a `Site` object already on screen: one value on both sides is what stops the instruction and the check drifting apart.","example":"example.com"},"state":{"type":"string","enum":["none","scheduled","running","stalled","deleted"],"description":"Where the site is in its lifecycle. A stable machine value the client turns into a localised sentence — never English composed by the engine (§2.19).\n\n⛔ `stalled` is `running` that has stopped moving — the site row is still `status: deleting`, so this is a statement about elapsed time, not a different row state. It appears once a teardown has been running longer than the same threshold `ZinnSiteDeletionWedged` alerts on (6h), and it exists because `deleting` previously meant *in progress* and *broken* at once and rendered the reassuring one: three sites sat at \"Deleting\" for up to fourteen days while the customer who asked was told it was in progress (D18042).","example":"scheduled"},"deletable":{"type":"boolean","description":"Whether a deletion could be requested right now. False on a site whose state does not allow it, so the form is explained rather than offered and refused."},"scheduled_for":{"type":"string","format":"date-time","nullable":true,"description":"When the teardown fires, or null when nothing is scheduled.","example":"2026-08-12T09:00:00Z"},"requested_at":{"type":"string","format":"date-time","nullable":true,"description":"When the deletion was requested, or null when nothing is scheduled.","example":"2026-08-05T09:00:00Z"},"grace_days":{"type":"integer","minimum":1,"maximum":30,"description":"How many days the countdown runs. Clamped at both ends — a floor of one day is what stops a misconfiguration meaning *delete now*.","example":7},"grace_free_reason":{"type":"string","enum":["","internal","never_provisioned"],"description":"Why this site would skip the grace period entirely, or `\"\"` when it would not.\n\n`never_provisioned` means the site is `failed` — provisioning never completed, so nothing was ever served and there is nothing to undo. `deleteSite` on such a site tears it down **immediately**, and the confirmation dialog must say so: *\"gone on the 28th, cancel any time\"* and *\"gone the moment you confirm\"* are different promises. `internal` is one of ours, with no customer behind it.\n\n⛔ **The engine decides this, not the client.** A client recomputing it from `status` would put the rule in two places, and the copy the customer reads would be the one that is not the engine's. What makes `never_provisioned` safe is an invariant in the transition table — there is no `active -> failed` edge — not a judgement about how bad a failure looked.","example":""},"can_cancel":{"type":"boolean","description":"⛔ **Its own field, and never recomputed as `state == \"scheduled\"`.** Once the teardown starts, the request row still says scheduled while the site is already being deleted; a client doing its own arithmetic would offer the cancel button at the exact moment it can only fail."}}},"SiteDeploy":{"type":"object","required":["site_id","target","status","last_deployed_at","live_url","repo","commit","message","can_deploy"],"properties":{"site_id":{"$ref":"#/components/schemas/Uuid"},"target":{"oneOf":[{"$ref":"#/components/schemas/DeployTarget"},{"type":"null"}],"description":"Null when no target can be derived yet."},"status":{"$ref":"#/components/schemas/DeployStatus"},"last_deployed_at":{"type":["string","null"],"format":"date-time","description":"When the site last went live, or null if it never has. Null means nothing to show — never zero and never an epoch date."},"live_url":{"type":["string","null"],"format":"uri","description":"The served URL once live, always https, else null. A non-HTTPS value is rejected server-side rather than returned."},"repo":{"type":["string","null"],"description":"Source repository for the Pages targets, else null."},"commit":{"type":["string","null"],"description":"The deployed commit ref, else null."},"message":{"type":["string","null"],"description":"Why the last deploy failed, else null. Rendered to the customer verbatim."},"can_deploy":{"type":"boolean","description":"False while a deploy is in flight or the site cannot be deployed."}}},"SiteDeployTargetOffer":{"type":"object","description":"One edge host, and whether this organization may place a site on it.","required":["target","connect_provider","connected","publishes_uploads","available","reason","stacks"],"properties":{"stacks":{"type":"array","description":"The `stack_type` values this edge host can serve — a build's output, so `static` and `node`. A client re-filters its stack picker from this when the customer chooses the host.","items":{"$ref":"#/components/schemas/StackType"},"example":["node","static"]},"target":{"type":"string","maxLength":16,"description":"The value to send as `deploy_target` on `createSite`.","example":"netlify"},"connect_provider":{"type":"string","maxLength":32,"description":"The `/v1/connections/{provider}` segment an account for this host is connected under — what a \"connect your account\" link points at. Note it is not always the host's own name: Cloudflare Pages is connected as `cloudflare` and GitHub Pages as `github`, because one token serves both of that provider's categories.","example":"netlify"},"connected":{"type":"boolean","description":"Whether this organization holds an active connection to that provider."},"publishes_uploads":{"type":"boolean","description":"`true` when we publish the build to this host. `false` means the content arrives from your own repository instead — `render` and `azure_swa` expose no endpoint that accepts file bytes at all — so the site is deployed by your push, not by a button here. Said before the choice rather than after it."},"available":{"type":"boolean","description":"Whether `createSite` would accept this `deploy_target` right now. Computed from exactly the same check the create performs, so a picker built from this list cannot offer a target the create then refuses."},"reason":{"type":"string","description":"Why not, as a stable code — empty when `available` is `true`. A code rather than a sentence because this populates a picker that is rendered in 58 languages; the `422` from `createSite` carries the English sentence.\n\n`no_connection` — connect an account for `connect_provider`. `no_allowance` — the `external_deploy_targets` allowance is spent; buy more or free a slot. `not_selectable` — not an edge host at all (never returned in this list, which contains only edge hosts; reachable from `createSite`).","enum":["","no_connection","no_allowance","not_selectable"],"example":"no_connection"}}},"SiteDeployment":{"type":"object","required":["id","site_id","target","status","trigger","repo","branch","commit","commit_message","live_url","message","requested_by","created_at","started_at","finished_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"site_id":{"$ref":"#/components/schemas/Uuid"},"target":{"$ref":"#/components/schemas/DeployTarget"},"status":{"$ref":"#/components/schemas/DeployStatus"},"trigger":{"$ref":"#/components/schemas/DeployTrigger"},"repo":{"type":["string","null"]},"branch":{"type":["string","null"]},"commit":{"type":["string","null"]},"commit_message":{"type":["string","null"]},"live_url":{"type":["string","null"],"format":"uri"},"message":{"type":["string","null"],"description":"Why it failed, else null. Rendered to the customer verbatim."},"requested_by":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":["string","null"],"format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"}}},"SiteDeploymentDetail":{"allOf":[{"$ref":"#/components/schemas/SiteDeployment"},{"type":"object","required":["log"],"properties":{"log":{"type":"string","description":"The build log, one timestamped line per step. Truncated from the FRONT when long — the end of a build log is where the failure is."}}}]},"SiteDiagnosis":{"type":"object","required":["complete","blind_probes","probes","findings","applied","recommendations"],"properties":{"complete":{"type":"boolean","description":"False when any probe could not run."},"blind_probes":{"type":"array","items":{"type":"string"},"description":"The probes that could not look."},"probes":{"type":"array","items":{"$ref":"#/components/schemas/SiteDiagnosticProbe"}},"findings":{"type":"array","items":{"$ref":"#/components/schemas/TicketDeflectionFinding"}},"applied":{"type":"array","items":{"type":"string"},"description":"Remedies applied automatically, by key. Every one is audit-logged."},"refused":{"type":"array","description":"Remedies that were attempted and refused, with the reason code. `ENTITLEMENT_DRIFT` means the platform detected that a fix would have changed what the site is entitled to and stopped it.","items":{"type":"object","properties":{"remedy":{"type":"string"},"code":{"type":"string"}}}},"recommendations":{"type":"array","items":{"$ref":"#/components/schemas/SupportRecommendation"}},"notified":{"type":"integer","description":"How many customers were e-mailed. At most one message per finding, ever."},"notify_skipped_not_in_good_standing":{"type":"integer","description":"Notifications skipped because the account is suspended or unpaid. ⛔ Counted rather than silently dropped — a skip and a broken emitter look identical otherwise."},"notify_failed":{"type":"integer","description":"Notifications that were attempted and raised. ⛔ Its own number: a broken emitter and a quiet run both report `notified: 0`, so a customer who was never told would otherwise be indistinguishable from a customer who needed no e-mail."}}},"SiteDiagnosticProbe":{"type":"object","required":["key","state"],"properties":{"key":{"type":"string","description":"Which check — `lve`, `php_ini`, `php_version`, `disk`."},"state":{"type":"string","enum":["ok","problem","unavailable"],"description":"⛔⛔ Three states, never two. `unavailable` means the check could not run, and it must NOT render as a clean result — the blind version of every probe here would otherwise report a throttled site as healthy."},"reason":{"type":"string","description":"Machine code explaining an `unavailable`, e.g. `no_samples`."},"detail":{"type":"object","additionalProperties":true}}},"SiteDisk":{"type":"object","description":"The newest stored disk reading against the site's effective allowance (base plus live grants). `used_mb` is null when the site has never been measured — never 0. `limit_mb` is null when the site has no disk allowance (unlimited).","required":["used_mb","limit_mb","measured_at"],"properties":{"used_mb":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}]},"limit_mb":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}]},"measured_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"SiteDnsChoice":{"allOf":[{"$ref":"#/components/schemas/SiteProviderChoice"},{"type":"object","required":["paired_with_cdn"],"properties":{"paired_with_cdn":{"type":"string","description":"The CDN vendor the DNS list above was narrowed for, or empty if it was not narrowed. Present so a client can explain a one-option (or empty) picker instead of rendering an unexplained dead end: choosing the Cloudflare CDN restricts DNS to Cloudflare, because Cloudflare's edge proxies a record in place inside its own authoritative zone and a zone hosted elsewhere can never reach it. An empty `vendors` list is therefore a real answer — the organization has no DNS account compatible with the chosen CDN — and a client must not fall back to the unfiltered list.","maxLength":64,"example":"cloudflare"},"allowed_by_cdn":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string","maxLength":64}},"description":"The whole CDN→DNS pairing rule, so a create wizard can re-filter its DNS picker on every CDN change without another request. Look the chosen CDN vendor up; the `*` key is the answer when no CDN has been chosen, and for any vendor not listed.\n\nEvery vendor in `cdn.vendors` has an explicit entry, including the ones that narrow nothing — so a client never has to decide whether a missing key means \"unrestricted\" or \"no DNS available\", which are different answers and differ by exactly the empty list this rule may legitimately return.\n\nThe rule itself: choosing Cloudflare restricts DNS to Cloudflare, because Cloudflare's edge proxies a record in place inside its own authoritative zone and a zone hosted elsewhere can never reach it; choosing CloudFront excludes ClouDNS, which does not serve the ALIAS/ANAME shape a distribution needs at an apex. This is served rather than compiled into a client for the same reason `stacks` is: two copies of a compatibility table drift, and the one that drifts lets a customer provision a site that cannot resolve.","example":{"cloudflare":["cloudflare"],"bunnycdn":["azure_dns","cloudflare","cloudns","desec","hetzner_dns"],"*":["azure_dns","cloudflare","cloudns","desec","hetzner_dns"]}}}}]},"SiteDnsPublish":{"type":"object","required":["site_id","publish_on"],"properties":{"site_id":{"type":"string","format":"uuid"},"publish_on":{"type":"string","enum":["zinn","own"]},"preflight":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/OwnDnsPreflight"}],"description":"Present on a PUT to `own`; null otherwise."}}},"SiteDomainPointing":{"type":"object","description":"Where a site's domain actually sends traffic, as measured (docs/823).","required":["hostname","state","reason","next_action","measured_at","observed","set"],"properties":{"hostname":{"type":"string","example":"example.com"},"state":{"type":"string","description":"`serving` reaches us on our nameservers. `serving_via_other_dns` is PROVEN to reach us through DNS the customer runs — never show it a nameserver instruction, that would take a live site down. `propagating` points at us and is not answering yet. `awaiting_record` has working nameservers and publishes nothing at the apex — the remedy is a record, not a nameserver change. `awaiting_pointing` does not reach us and we host a site for it. `pointed_elsewhere` answers elsewhere and we host no site there, so it is informational only. `zone_expired` means the zone we assigned was deleted and the old nameservers are dead. `unknown` means we could not measure — never green, never an accusation. `moving_in` means a partner is moving the site in (docs/808 §12): the zone stays where it is and `move` says who switches it.","enum":["moving_in","serving","serving_via_other_dns","propagating","awaiting_record","awaiting_pointing","pointed_elsewhere","zone_expired","unknown"]},"reason":{"type":"string","description":"A stable machine code for the leg that decided the state.","example":"answers_elsewhere_site_unreachable"},"next_action":{"type":"string","description":"The step the customer takes, or empty when there is none. A stable code, never a sentence — the words are localized on the surface. Q464: `set_nameservers_at_registrar` is sent only when our copy of the zone can take the domain over (a record that serves it, and the same mail it publishes today) and no partner site move holds it; otherwise an `awaiting_pointing` site gets an empty `next_action`, no `set.nameservers`, and the own-DNS option (`set.own_dns`) is the way to go live.","enum":["set_nameservers_at_registrar","add_record_at_your_dns_provider","recreate_dns_zone",""]},"measured_at":{"type":"string","format":"date-time","nullable":true,"description":"When the VERDICT was reached. Null means never measured. Deliberately not the delegation row's `checked_at`, which moves on every reading including one that established nothing."},"observed":{"type":"object","required":["nameservers","addresses","www_addresses"],"properties":{"nameservers":{"type":"array","items":{"type":"string"}},"addresses":{"type":"array","nullable":true,"items":{"type":"string"},"description":"Null means the resolver did not answer; an empty array means it answered and nothing is published. These are different and must not be rendered the same."},"www_addresses":{"type":"array","nullable":true,"items":{"type":"string"}}}},"set":{"type":"object","description":"What the customer must set. Empty lists mean \"not applicable\".","required":["nameservers","records"],"properties":{"nameservers":{"type":"array","items":{"type":"string"},"description":"Always EMPTY on `zone_expired` — the provider deleted the zone, so the old pair no longer resolves and a customer who set it would have done real work for nothing."},"records":{"type":"array","items":{"type":"object","required":["type","name","value"],"properties":{"type":{"type":"string","example":"A"},"name":{"type":"string","example":"@"},"value":{"type":"string","example":"144.76.116.188"}}}},"own_dns":{"type":["object","null"],"description":"The other way to go live: keep the domain's DNS where it is and publish these records there. Present on `awaiting_pointing` and `awaiting_record` when the site has a server address; null otherwise (and always null for a site a partner moved in, whose own answer is `move`). Shown beside the nameserver instruction, never instead of it.","required":["dns_host","records","proxied","ssl_mode","ssl_mode_after_live","exposes_origin"],"properties":{"dns_host":{"type":"string","enum":["cloudflare","other","unknown"],"description":"Where the domain's DNS is run, from the nameservers we observed. `unknown` means none were observed, never \"not Cloudflare\"."},"records":{"type":"array","items":{"type":"object","required":["type","name","host","value","proxied"],"properties":{"type":{"type":"string","example":"A"},"name":{"type":"string","example":"@"},"host":{"type":"string","example":"example.com"},"value":{"type":"string","example":"144.76.116.188"},"proxied":{"type":["boolean","null"],"description":"`true` on Cloudflare (the orange cloud: hides the server address and is what our server's origin lock expects). Null where the DNS host has no proxy."}}}},"proxied":{"type":["boolean","null"]},"ssl_mode":{"type":["string","null"],"enum":["full",null],"description":"The Cloudflare SSL/TLS mode to set now. Null when the DNS is not on Cloudflare. Never `strict` first: that needs our certificate, which is issued only once the name reaches us."},"ssl_mode_after_live":{"type":["string","null"],"enum":["strict",null],"description":"The Cloudflare SSL/TLS mode to move to once the site is live."},"exposes_origin":{"type":"boolean","description":"True when the records are not proxied, so the record itself publishes our server's address."}}}}},"move":{"type":"object","description":"Present when a partner moved (or is moving) the site in: who holds the zone, the records pointing at us, proxied or not, the SSL mode and the certificate state.","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"step":{"type":"string"},"dns_case":{"type":"string"},"dns_holder":{"type":"string"},"proxied":{"type":["boolean","null"]},"ssl_mode":{"type":["string","null"]},"ssl_mode_after_live":{"type":["string","null"]},"records":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"value":{"type":"string"},"proxied":{"type":["boolean","null"]}}}},"tls_state":{"type":"string"},"live_at":{"type":["string","null"],"format":"date-time"}}},"progress":{"$ref":"#/components/schemas/SiteOwnDomainProgress"},"diagnosis":{"$ref":"#/components/schemas/SiteOwnDomainDiagnosis"},"site_state":{"type":["string","null"],"description":"The customer's OWN state that keeps visitors out, measured by the serving sweep (s1014 DNSSTATE): `maintenance_mode` (a maintenance page the site itself serves) or `access_rule_denies` (a 403 the worker proved is the site's own `.htaccess` rule, for example `Deny from all` with one allowed address — the server log names the refusal AND the rule is in the file). Null when there is none. It is never our outage and never \"propagating\"; the remedy is the customer's, on their site.","enum":["maintenance_mode","access_rule_denies",null]},"holder_mix":{"type":["object","null"],"description":"Hostnames that publish the parking holder's addresses AND the site's own target, so some visitors get the holder page (s1014 DNSSTATE). Null when none. `POST /v1/domains/{domainId}/dns/holder-rows/remove` deletes the holder rows.","required":["domain_id","hostnames"],"properties":{"domain_id":{"type":"string","format":"uuid"},"hostnames":{"type":"array","items":{"$ref":"#/components/schemas/DnsHolderMixHostname"}}}}}},"SiteErrorRate":{"type":"object","description":"HTTP and PHP errors for one site over the newest closed collection window (#626).\n\nWhat `features/uptime-monitoring` sells: *\"HTTP and PHP errors captured per site, so a fatal from a bad plugin update or a broken deploy surfaces as an error rate rather than as a customer complaint days later.\"*\n\n**It is a rate, so the denominator ships with it.** `requests_total` is the number of requests the same window served; 40 fatals against 4,000,000 requests and 40 against 40 are the same count and opposite emergencies. Never compute a rate against a denominator taken from a different window.\n\n**Fatals and non-fatals are counted separately.** `php_fatal` is what took a page down (`PHP Fatal error` / `Parse error`); `php_error` is warnings, notices and deprecations. A site can serve correctly for years while emitting the latter, so folding them together would raise an alarm on almost every site.\n\nCounts are `null` — never `0` — when nothing has been collected. A zero asserts \"this site threw no errors\", which no absent sample supports, and it renders as a healthy site.\n\nCollected asynchronously off the request path, with its own `available` flag independent of the parent envelope's: the error collector and the usage collector are different producers and either can be live while the other is not.","required":["available","window_start","window_end","requests_total","http_4xx","http_5xx","php_fatal","php_error","error_rate_ppm"],"properties":{"available":{"type":"boolean","description":"Whether an error-rate sample exists for this site yet."},"window_start":{"type":["string","null"],"format":"date-time"},"window_end":{"type":["string","null"],"format":"date-time"},"requests_total":{"type":["integer","null"],"format":"int64","minimum":0,"description":"Requests served in the window — the denominator for the rate."},"http_4xx":{"type":["integer","null"],"format":"int64","minimum":0},"http_5xx":{"type":["integer","null"],"format":"int64","minimum":0},"php_fatal":{"type":["integer","null"],"format":"int64","minimum":0,"description":"PHP fatal/parse errors — the \"bad plugin update\" signal."},"php_error":{"type":["integer","null"],"format":"int64","minimum":0,"description":"PHP warnings/notices/deprecations. Counted apart from fatals."},"error_rate_ppm":{"type":["integer","null"],"format":"int64","minimum":0,"description":"Failed requests (5xx + PHP fatals) per **million** requests. An integer in ppm rather than a float percentage so every threshold comparison is exact.\n\n`null` when the window served no requests: a silent site has no error *rate*, and reporting `0` would render it as perfectly healthy."}}},"SiteEvent":{"type":"object","description":"One change to a site, plotted on the same time axis as its speed history (docs/85 §6) — so that \"plugin X activated → LCP +0.4 s\" is something you can see rather than something a customer has to remember.","required":["id","kind","source","occurred_at","object_name","object_slug","from_version","to_version"],"properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["wp_core_update","plugin_activated","plugin_deactivated","plugin_updated","theme_switched","theme_updated","php_version_changed","deploy"],"description":"New members are **additive**: a client that meets an unknown kind must render a generic marker rather than break the chart.\n\n`deploy` entries are merged from the deployment history rather than stored as events — one table owns a deploy, and a second copy of it would disagree within a month."},"source":{"type":"string","enum":["wp_plugin","engine","agent"],"description":"Who asserted this. `wp_plugin` is the site telling us about itself over a signed webhook — a strong claim about that site and about nothing else. `engine` is something we derived, such as a PHP version differing from the last one reported."},"occurred_at":{"type":"string","format":"date-time","description":"When it happened **on the site**, not when we received it. The plugin's webhook is deliberately non-blocking with a short timeout and no delivery guarantee, so a delivery can be late or retried — and an event drawn at receipt time would sit beside the wrong measurement, which is the one job this timeline has."},"object_name":{"type":"string","description":"What changed, as a person recognises it — `Contact Form 7`.","example":"Contact Form 7"},"object_slug":{"type":"string","description":"The machine identity — `contact-form-7`. Both are stored: the slug is stable across renames, the name is the one a human can act on."},"from_version":{"type":"string","description":"Blank where meaningless — an activation has no version change."},"to_version":{"type":"string"}}},"SiteEventReport":{"type":"object","description":"The ingest webhook's acknowledgement. Deliberately says almost nothing — the caller is a WordPress plugin doing a fire-and-forget POST that discards the body, and anything richer would be a description of another tenant's data to whoever guessed a hostname.","required":["accepted","stored"],"properties":{"accepted":{"type":"boolean"},"stored":{"type":"integer","minimum":0,"description":"How many rows were **new**. A duplicate delivery is accepted with `0` rather than refused: WordPress fires some of these hooks more than once per change and the POST is fire-and-forget, so replay safety lives in the database, not in the sender's manners."}}},"SiteEventReportRequest":{"type":"object","description":"What a site's Zinn® plugin reports about itself (docs/85 §6.2).","required":["site"],"properties":{"site":{"type":"string","description":"The site's own `home_url()`. **An untrusted claim** — it selects which site's derived secret the signature is checked against, and nothing more. The organisation is taken from the resolved site, never from this body.","example":"https://acme.example/"},"php_version":{"type":"string","description":"The PHP version the site is running. The engine raises a `php_version_changed` event when it differs from the last one reported — a change is detectable by **comparison** rather than by instrumenting the code that changes it, which also catches a change made outside the platform.","example":"8.3.14"},"events":{"type":"array","maxItems":50,"description":"A batch. WordPress bulk-updating 40 plugins fires one `upgrader_process_complete` describing all of them, so a batch is the normal case, not the edge case.\n\n`deploy` is rejected here along with anything unknown: it is owned by the deployment history and merged at read time.","items":{"type":"object","required":["kind"],"properties":{"kind":{"type":"string"},"object_name":{"type":"string"},"object_slug":{"type":"string"},"from_version":{"type":"string"},"to_version":{"type":"string"},"at":{"type":"integer","format":"int64","description":"Unix seconds, when it happened on the site. Omitted defaults to receipt time; never clamped forward, because a late webhook is late, not wrong."}}}}}},"SiteExamBoost":{"type":"object","description":"Exam Boost for one Moodle site (s1014, docs/1160 §8).","required":["site_id","offered","free_available","next_free_on","price","duration_days","multiplier","max_lead_days","plan_limits","boosted_limits","current","history"],"properties":{"site_id":{"type":"string","format":"uuid"},"offered":{"type":"boolean"},"free_available":{"type":"boolean"},"next_free_on":{"type":"string","format":"date-time","nullable":true},"price":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ExamBoostMoney"}]},"duration_days":{"type":"integer"},"multiplier":{"type":"integer"},"max_lead_days":{"type":"integer"},"plan_limits":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ExamBoostLimits"}]},"boosted_limits":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ExamBoostLimits"}]},"current":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ExamBoostBooking"}]},"history":{"type":"array","items":{"$ref":"#/components/schemas/ExamBoostBooking"}}}},"SiteFileResult":{"type":"object","description":"A folder listing, a file read or a file write.","required":["ok"],"properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"path":{"type":"string"},"entries":{"type":"array","items":{"type":"object","additionalProperties":true}},"truncated":{"type":"boolean"},"content":{"type":"string"},"bytes":{"type":"integer"},"sha256":{"type":"string"},"backup":{"type":"string","description":"Where the previous file was copied","on a write.":null}}},"SiteFirewall":{"type":"object","required":["site_id","login","xmlrpc","rule_sets","available_rule_sets","trusted","admin_trusted_only","challenge_until","platform_rules","apply_state","applied_at","apply_error","flood","recent_floods","app_profile","wordpress_controls"],"properties":{"site_id":{"type":"string","format":"uuid"},"app_profile":{"type":"string","description":"The per-application hardening profile the site's rules come from (docs/1170): `wordpress`, an application key such as `drupal` or `nextcloud`, the generic PHP baseline, or empty for a site with no application rules (static, Node and the like)."},"wordpress_controls":{"type":"boolean","description":"True only for WordPress and WooCommerce. When false, `login`, `xmlrpc` and `admin_trusted_only` do not apply to the site, the panel hides them, and an update that sets them is refused."},"login":{"type":"string","enum":["standard","strict"],"description":"Login attempts per visitor per 5 minutes — standard 10 (the platform floor), strict 5."},"xmlrpc":{"type":"string","enum":["limited","blocked"],"description":"`limited`: XML-RPC answers under the login limit; `blocked`: refused outright."},"rule_sets":{"type":"array","items":{"type":"string","enum":["block_author_scans","block_php_in_uploads","block_info_files","block_aggressive_bots"]}},"available_rule_sets":{"type":"array","items":{"type":"string"}},"trusted":{"type":"array","items":{"type":"string"},"description":"Addresses never challenged and exempt from the site's own rule sets."},"admin_trusted_only":{"type":"boolean","description":"Only trusted addresses may reach the login page and wp-admin."},"challenge_until":{"type":["string","null"],"format":"date-time","description":"The customer's own \"check every visitor\" mode runs until then; null is off."},"platform_rules":{"type":"array","items":{"type":"string"},"description":"Always-on platform rules (keys). Not editable."},"apply_state":{"type":"string","enum":["applied","pending","failed"]},"applied_at":{"type":["string","null"],"format":"date-time"},"apply_error":{"type":"string"},"flood":{"oneOf":[{"$ref":"#/components/schemas/SiteFirewallFlood"},{"type":"null"}]},"recent_floods":{"type":"array","items":{"$ref":"#/components/schemas/SiteFirewallFlood"}}}},"SiteFirewallBlocked":{"type":"object","required":["available","hours","truncated","items"],"properties":{"available":{"type":"boolean"},"hours":{"type":"integer"},"truncated":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/SiteFirewallBlockedRequest"}}}},"SiteFirewallBlockedRequest":{"type":"object","required":["at","address","method","path","status","user_agent","reason"],"properties":{"at":{"type":"string","format":"date-time"},"address":{"type":"string"},"method":{"type":"string"},"path":{"type":"string"},"status":{"type":"integer"},"user_agent":{"type":"string"},"reason":{"type":"string"}}},"SiteFirewallFlood":{"type":"object","required":["started_at","hold_until","lifted_at","peak_rps","edge_challenge","origin_challenge"],"properties":{"started_at":{"type":"string","format":"date-time"},"hold_until":{"type":"string","format":"date-time","description":"Never lifted before this."},"lifted_at":{"type":["string","null"],"format":"date-time"},"peak_rps":{"type":"number","description":"Highest requests per second seen."},"edge_challenge":{"type":"boolean","description":"Cloudflare Under Attack was switched on."},"origin_challenge":{"type":"boolean","description":"The server's visitor check was switched on."}}},"SiteFirewallUpdate":{"type":"object","additionalProperties":false,"properties":{"login":{"type":"string","enum":["standard","strict"]},"xmlrpc":{"type":"string","enum":["limited","blocked"]},"rule_sets":{"type":"array","maxItems":4,"items":{"type":"string","enum":["block_author_scans","block_php_in_uploads","block_info_files","block_aggressive_bots"]}},"trusted":{"type":"array","maxItems":50,"items":{"type":"string","maxLength":64},"description":"IPv4 addresses, IPv4 ranges ending /8, /16 or /24, or single IPv6 addresses."},"admin_trusted_only":{"type":"boolean"},"challenge_hours":{"type":"integer","minimum":0,"maximum":24}}},"SiteFormParts":{"type":"object","description":"`SiteFormSubmission` as `multipart/form-data`. Each part is ONE string; a question with several answers (e.g. checkboxes) is that part repeated under the same name, which the engine reads as a list exactly as it does a repeated urlencoded key. ⛔ Kept a plain string on purpose: openapi-python-client 0.29.1 emits unparseable Python for a multipart body whose `additionalProperties` is a `oneOf` or an `array` (the zinn-sdk release failed on it, D60130); `scripts/sdk-release.py --check-spec` refuses that shape.","required":["_to","_email"],"properties":{"_to":{"type":"string","maxLength":64,"description":"Local part of the site's mailbox, e.g. `coach`."},"_email":{"type":"string","format":"email","description":"The visitor's address — the Reply-To."},"_name":{"type":"string","maxLength":80},"_form":{"type":"string","maxLength":80,"description":"Shown in the e-mail subject."},"_next":{"type":"string","description":"Same-site path after success."},"_back":{"type":"string","description":"Same-site path after a refusal."},"_locale":{"type":"string","maxLength":12,"description":"Language of the two e-mails."},"_website":{"type":"string","description":"Honeypot — leave empty."},"cf-turnstile-response":{"type":"string","maxLength":2048}},"additionalProperties":{"type":"string","maxLength":5000}},"SiteFormResult":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["sent","refused"]},"reason":{"type":"string","enum":["origin","recipient","invalid","email","not_enabled","verification","rate","unavailable"]}}},"SiteFormSubmission":{"type":"object","description":"Reserved fields start with `_`; every other field is one question and its answer (repeat a name for several answers, e.g. checkboxes). Up to 80 questions, 5000 characters per answer.","required":["_to","_email"],"properties":{"_to":{"type":"string","maxLength":64,"description":"Local part of the site's mailbox, e.g. `coach`."},"_email":{"type":"string","format":"email","description":"The visitor's address — the Reply-To."},"_name":{"type":"string","maxLength":80},"_form":{"type":"string","maxLength":80,"description":"Shown in the e-mail subject."},"_next":{"type":"string","description":"Same-site path after success."},"_back":{"type":"string","description":"Same-site path after a refusal."},"_locale":{"type":"string","maxLength":12,"description":"Language of the two e-mails."},"_website":{"type":"string","description":"Honeypot — leave empty."},"cf-turnstile-response":{"type":"string","maxLength":2048}},"additionalProperties":{"oneOf":[{"type":"string","maxLength":5000},{"type":"array","items":{"type":"string","maxLength":5000}}]}},"SiteForms":{"type":"object","required":["available","enabled","sitekey","endpoint","domain","mailboxes"],"properties":{"available":{"type":"boolean","description":"False when the site's domain has no mailbox to send to."},"enabled":{"type":"boolean"},"sitekey":{"type":"string","description":"PUBLIC Turnstile sitekey for the page's widget; empty until first switched on."},"endpoint":{"type":"string","description":"The form's action URL (submitSiteForm)."},"domain":{"type":"string","description":"The site's own domain; the form's `_to` is a mailbox local part on it."},"mailboxes":{"type":"array","items":{"type":"string"}}}},"SiteFormsUpdate":{"type":"object","required":["enabled"],"additionalProperties":false,"properties":{"enabled":{"type":"boolean"}}},"SiteFtpUser":{"type":"object","description":"One FTP account on a site's hosting package. It carries **no password and no way to obtain one**: the vendor will hand back the primary account's live credentials in cleartext, and this platform deliberately never asks.","required":["id","username","path","enabled","is_primary"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"The account's identifier at the vendor, used to delete it.","example":"8471"},"username":{"type":"string","description":"The name that signs in. The vendor namespaces it per package on some package types, so this — not what was requested — is what the client shows.","example":"example-deploy"},"path":{"type":"string","description":"The directory the account is confined to, relative to the package root. `/` is the whole site.","example":"/public_html"},"enabled":{"type":"boolean","description":"Whether the account may currently sign in."},"is_primary":{"type":"boolean","description":"Whether this is the package's own built-in account. It is listed so the customer can see it exists, and it can never be deleted here — removing it takes the package's own access with it and nothing the customer can do restores it."}}},"SiteFtpUserList":{"type":"object","description":"A site's FTP accounts, with the two facts a screen needs before it offers an \"add\" control: whether the plan includes the service at all, and whether the effective ceiling has room left.","required":["data","limit","permitted","can_create","credential","host","port"],"additionalProperties":false,"properties":{"data":{"type":"array","description":"The accounts on the package, the primary one first.","items":{"$ref":"#/components/schemas/SiteFtpUser"}},"credential":{"type":"string","enum":["password","public_key","ssh"],"description":"How accounts on this site sign in, which decides the form a client shows before any account exists. `password`: a vendor package, and `createSiteFtpUser` takes a `password`. `public_key`: our own servers, which are key-only — `createSiteFtpUser` takes a `public_key` and refuses a password. `ssh`: our own servers on a plan that includes SSH, whose SSH keys already carry SFTP, so there is nothing to create here and `can_create` is false."},"host":{"type":"string","description":"The server an SFTP client connects to, on our own servers. Empty on a vendor package, whose FTP host is the vendor's to publish.","example":"worker-1.example.net"},"port":{"type":"integer","nullable":true,"description":"The port on `host`; null when `host` is empty.","example":22},"limit":{"allOf":[{"$ref":"#/components/schemas/VendorAllowance"}],"description":"The effective ceiling on FTP accounts for this site."},"permitted":{"type":"boolean","description":"Whether the package type includes FTP at all. This is the flag behind *\"your plan does not include this\"*."},"can_create":{"type":"boolean","description":"`permitted`, **and** the effective ceiling has room. This is the flag behind *\"you have used all of them\"*. Two fields rather than one because those are different sentences, and a single flag makes the screen say the wrong one."}}},"SiteGeoRestriction":{"type":"object","required":["mode","countries","exempt_search_engines","search_engines_exempt_at_edge","edge","origin"],"properties":{"mode":{"type":"string","enum":["off","allow","block"],"description":"`allow` admits **only** the listed countries and refuses everywhere else; `block` refuses the listed ones and serves everywhere else; `off` is no rule at all.","example":"allow"},"countries":{"type":"array","description":"ISO-3166 alpha-2, upper-case. Empty when `mode` is `off`.","items":{"type":"string","minLength":2,"maxLength":2,"example":"GB"}},"exempt_search_engines":{"type":"boolean","description":"Whether verified search-engine crawlers were asked to bypass the rule.","example":true},"search_engines_exempt_at_edge":{"type":"boolean","description":"Whether that exemption is actually **in force**, which is not the same as whether it was requested — only a provider that verifies a crawler by forward/reverse DNS can carry it. `false` while `exempt_search_engines` is `true` means this site's provider cannot honour it and search crawlers are subject to the country rule.","example":true},"edge":{"$ref":"#/components/schemas/GeoRestrictionLayer"},"origin":{"$ref":"#/components/schemas/GeoRestrictionLayer"}}},"SiteGeoRestrictionUpdate":{"type":"object","description":"The whole intent. `mode` and `countries` are sent together because the same list inverts meaning between the two modes.","required":["mode","countries"],"properties":{"mode":{"type":"string","enum":["off","allow","block"],"example":"allow"},"countries":{"type":"array","maxItems":40,"description":"ISO-3166 alpha-2. Must name at least one country unless `mode` is `off`; an empty allow-list would take the site off the internet worldwide and is refused.","items":{"type":"string","minLength":2,"maxLength":2,"example":"GB"}},"exempt_search_engines":{"type":"boolean","default":true,"description":"Leave verified search-engine crawlers able to reach the site. Defaults to `true`: a single-country allow-list otherwise removes the site from search, because Googlebot crawls from US addresses.","example":true}}},"SiteGroup":{"type":"object","required":["id","name","colour","notes","site_count","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","maxLength":120,"description":"Unique per organisation, case-insensitively. Two groups called `Casino` and `CASINO` are a support ticket rather than a feature — nobody can tell them apart in a filter and half the network ends up in each."},"colour":{"type":"string","description":"A chip colour from a closed set, never a free hex value. The dashboard draws these through the design system's contrast-checked tone tokens; a customer-supplied colour would render as invisible text on one theme and pass every gate, because bespoke CSS is valid CSS.","enum":["slate","blue","green","amber","red","purple","teal","pink"]},"notes":{"type":"string","description":"The operator's own note. Never published, never shown to anyone else."},"site_count":{"type":"integer","minimum":0},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"SiteGroupCreate":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":120},"colour":{"type":"string","enum":["slate","blue","green","amber","red","purple","teal","pink"]},"notes":{"type":"string"}}},"SiteGroupList":{"type":"object","required":["items","can_create","colours"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SiteGroup"}},"can_create":{"type":"boolean","description":"Whether any organisation in scope sells `site_groups`. The screen renders the create control as ABSENT rather than disabled when this is false — an inert button that never explains itself is a placeholder with a tooltip."},"colours":{"type":"array","items":{"type":"string"}}}},"SiteGroupMember":{"type":"object","required":["id","primary_domain","name","status","product_line"],"properties":{"id":{"type":"string","format":"uuid"},"primary_domain":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"product_line":{"type":"string"}}},"SiteGroupMembers":{"type":"object","required":["items","total"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SiteGroupMember"}},"total":{"type":"integer","minimum":0}}},"SiteGroupMembership":{"type":"object","required":["site_ids"],"properties":{"site_ids":{"type":"array","maxItems":1000,"items":{"type":"string","format":"uuid"}}}},"SiteGroupMembershipChange":{"type":"object","required":["added","removed","site_count"],"properties":{"added":{"type":"integer","minimum":0},"removed":{"type":"integer","minimum":0},"site_count":{"type":"integer","minimum":0,"description":"The group's membership after the change."}}},"SiteGroupUpdate":{"type":"object","description":"Every field optional; an omitted field is left unchanged.","properties":{"name":{"type":"string","maxLength":120},"colour":{"type":"string","enum":["slate","blue","green","amber","red","purple","teal","pink"]},"notes":{"type":"string"}}},"SiteHostingLine":{"type":"object","required":["code","name","description"],"description":"One product line a **site** can be created on. Present iff some purchasable plan on the line grants a positive or unlimited `max_sites` — see `listSiteHostingLines`.","properties":{"code":{"type":"string","description":"The line code, e.g. `footprint_free`. Localise on this first."},"name":{"type":"string","description":"The catalogue display name, for a client with no translation for `code`."},"description":{"type":"string","description":"The catalogue's own one-line description. May be empty."}}},"SiteHostingLineList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SiteHostingLine"}}}},"SiteHourlyBackups":{"type":"object","description":"The paid hourly-backups add-on for one site (L40 B02, docs/1081 §B02).","required":["site_id","offered","active","can_buy","refusal","price","purchase_id","renews_on","ends_on","keep_hours","last_hourly_at"],"additionalProperties":false,"properties":{"site_id":{"type":"string","format":"uuid"},"offered":{"type":"boolean","description":"Whether hourly backups are on sale to this organisation."},"active":{"type":"boolean","description":"Whether hourly backups are running for this site now."},"can_buy":{"type":"boolean","description":"Whether this site may buy hourly backups right now."},"refusal":{"type":"string","nullable":true,"description":"Why it cannot be bought right now, or null."},"price":{"nullable":true,"description":"The monthly price in the caller's currency, or null when not on sale.","allOf":[{"$ref":"#/components/schemas/MoneyAmount"}]},"purchase_id":{"type":"string","format":"uuid","nullable":true,"description":"The add-on purchase that is on, or null."},"renews_on":{"type":"string","format":"date","nullable":true,"description":"The next renewal date while it renews."},"ends_on":{"type":"string","format":"date","nullable":true,"description":"The last day hourly backups run once the renewal was stopped."},"keep_hours":{"type":"integer","description":"How long each hourly restore point is kept, in hours."},"last_hourly_at":{"type":"string","format":"date-time","nullable":true,"description":"When the newest hourly backup was taken, or null."}}},"SiteImport":{"type":"object","required":["id","source","output","status","source_domain","urls_total","urls_done","urls_failed","progress_percent","requests_spent","request_budget","budget_exhausted","created_at","can_cancel"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"site_id":{"type":"string","description":"The site this import lands on, or empty. Empty is a real outcome, not an error: an aged-domain restore produces a downloadable bundle and the customer picks the target afterwards."},"source":{"$ref":"#/components/schemas/SiteImportSource"},"output":{"$ref":"#/components/schemas/SiteImportOutput"},"status":{"$ref":"#/components/schemas/SiteImportStatus"},"status_reason":{"type":"string","description":"A machine code the dashboard renders through its own catalogue — never an English sentence composed by the engine, which could not be shown to the other 57 locales."},"source_domain":{"type":"string"},"target_domain":{"type":"string"},"snapshot_day":{"type":"string"},"crawl_depth":{"type":"integer"},"urls_total":{"type":"integer"},"urls_done":{"type":"integer"},"urls_failed":{"type":"integer"},"detected_platform":{"type":"string","description":"What the archived site was built on, once the crawl has seen a page — the same codes as `ArchivePlatform.platform`. ⛔ Empty means *not established*, never *plain HTML*; the two lead a customer to different expectations."},"pre_restore_backup_id":{"type":"string","description":"The safety backup taken of the target site immediately before this restore overwrote it. ⚖️ Owner ruling 2026-09-08: a restore onto a site that already has content is gated behind a backup. Empty when none was taken — no site attached, or a platform that cannot produce our archive — which the job screen states rather than implying."},"progress_percent":{"type":"integer","description":"For a progress bar only. The per-URL counters are the primary display, because a percentage cannot say *which* step."},"requests_spent":{"type":"integer"},"request_budget":{"type":"integer"},"budget_exhausted":{"type":"boolean","description":"True when the job stopped because it ran out of requests. Surfaced deliberately — it otherwise looks identical to a job that finished, and the customer's next action depends on telling them apart."},"bundle_bytes":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time","nullable":true},"finished_at":{"type":"string","format":"date-time","nullable":true},"can_cancel":{"type":"boolean"}}},"SiteImportCreate":{"type":"object","required":["source","output","source_domain"],"additionalProperties":false,"properties":{"org_id":{"allOf":[{"$ref":"#/components/schemas/Uuid"}],"description":"Which organisation this import belongs to. Only needed by an account that acts for more than one and is not naming a `site_id` — when a site is named, **the site decides**, because restoring onto a site is an act on that site rather than a preference the caller expresses. ⛔ It only ever narrows: an org the caller does not hold `hosting.import.manage` in is a `404`, the same answer as an org that does not exist."},"source":{"$ref":"#/components/schemas/SiteImportSource"},"output":{"$ref":"#/components/schemas/SiteImportOutput"},"source_domain":{"type":"string","maxLength":2048,"description":"The domain whose archive to restore, or — for `archive_url` — the URL of the archive to migrate in."},"target_domain":{"type":"string","maxLength":253,"description":"The domain the result is served on. Defaults to `source_domain`."},"site_id":{"allOf":[{"$ref":"#/components/schemas/Uuid"}],"nullable":true,"description":"Restore into an existing site. Omit to produce a bundle and choose the target later."},"snapshot_day":{"type":"string","format":"date","description":"Which day's snapshot to restore. **Required for `wayback`** — the most recent capture of an expired domain is usually a parking page, so there is no safe default."},"crawl_depth":{"type":"integer","minimum":1,"maximum":5,"default":2},"request_budget":{"type":"integer","minimum":1,"maximum":10000,"default":2000,"description":"The hard ceiling on requests this job may make against the source. Bounded per job so one 400,000-capture domain cannot consume the platform's whole archive allowance."},"ownership_attested":{"type":"boolean","default":false,"description":"⚠️ The customer's assertion that they control the domain, recorded because it cannot be reconstructed afterwards. It is **not** a legal control and is not presented as one."}}},"SiteImportList":{"type":"object","required":["imports"],"properties":{"imports":{"type":"array","items":{"$ref":"#/components/schemas/SiteImport"}}}},"SiteImportOutput":{"type":"string","description":"What the import produces. Both are supported; neither is a default.","enum":["static","wordpress"]},"SiteImportSource":{"type":"string","description":"Where the content comes from. ⛔ Deliberately not the same enum as a site's `source`: that one records what a site was built from, for ever, while this selects a fetch strategy and grows a value each time another migration source is supported.","enum":["wayback","archive_url","ftp","ssh"]},"SiteImportStatus":{"type":"string","description":"`fetching` and `building` are separate states rather than one `running` because they fail for opposite reasons and the customer's next action differs — a stall in `fetching` is the archive throttling us (wait), a failure in `building` is our parser (tell support).","enum":["pending","indexing","fetching","building","deploying","verifying","completed","failed","cancelled"]},"SiteInstallProgress":{"type":"object","description":"The installing screen's one read (row 45).","required":["site_id","status","step","steps_done","steps_total","install"],"additionalProperties":false,"properties":{"site_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"step":{"type":"string","nullable":true,"description":"The running workflow's own stage key (`begin`, `placement`, `account`, `blueprint`, `cdn`, `dns`, `verify`, `activate`, `rollback`), or `null` when it could not be asked - unknown, never zero (ADR 0023)."},"steps_done":{"type":"integer","nullable":true},"steps_total":{"type":"integer","nullable":true},"install":{"$ref":"#/components/schemas/SiteInstallState"}}},"SiteInstallState":{"type":"object","description":"Row 45 (s1014): the installing screen's honest state. `stalled` means past the measured p90 for this application (never under 5 minutes) with no end; Retry then restarts it. Retry is HIDDEN while running normally and after success; SHOWN but disabled (`enabled: false` with a `reason`) during the 3-minute cool-down after a failure and when the account is not in good standing.","required":["state","started_at","elapsed_seconds","p50_seconds","p90_seconds","timing_samples","staff_alerted","retry"],"additionalProperties":false,"properties":{"state":{"type":"string","enum":["running","stalled","failed","done","other"]},"started_at":{"type":"string","format":"date-time","nullable":true},"elapsed_seconds":{"type":"integer","minimum":0},"p50_seconds":{"type":"integer","description":"Median of the last 200 finished installs of this application on this location, measured ESTATE-WIDE (durations only, no tenant data), so every org reads the same figure; falls back to the application on any location, then every install."},"p90_seconds":{"type":"integer"},"timing_samples":{"type":"integer","description":"How many runs the percentiles were read from; `0` means the fallback."},"staff_alerted":{"type":"boolean","description":"`true` only while the run is still going AND staff were really paged about it (the hung-install page fires once at the later of p90 and 12 minutes). The screen says \"our team has been alerted\" only when this is `true`; past p90 alone is not a page."},"retry":{"type":"object","required":["visible","enabled","reason","retry_after"],"additionalProperties":false,"properties":{"visible":{"type":"boolean"},"enabled":{"type":"boolean"},"reason":{"type":"string","nullable":true,"enum":["running","done","cooldown","not_in_good_standing","not_retryable"]},"retry_after":{"type":"string","format":"date-time","nullable":true}}}}},"SiteIntegrityFinding":{"type":"object","required":["id","kind","state","first_seen_at","last_seen_at"],"properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["core_modified","core_missing","core_extra","address","unchecked","malware_file","rogue_admin","injected_content","attacker_persistence"],"description":"core_modified, core_missing, core_extra and address come from the hourly core check (docs/1027 §6); malware_file, rogue_admin, injected_content and attacker_persistence from the daily intrusion deep check, V1's detectors (docs/1142)."},"state":{"type":"string","enum":["reported","repaired","repair_failed","gone","dismissed"]},"version":{"type":"string","description":"The WordPress version the core files were compared with."},"files":{"type":"array","items":{"type":"string"},"description":"Up to 50 lines of what was found: core file paths relative to the site's public folder; for malware_file \"path (what it is)\"; for the database kinds the finding in words (e.g. an administrator's login and why)."},"count":{"type":"integer","description":"Every file found (the list shows at most 50)."},"home":{"type":"string"},"siteurl":{"type":"string"},"first_seen_at":{"type":"string","format":"date-time"},"last_seen_at":{"type":"string","format":"date-time"},"repaired_at":{"type":"string","format":"date-time","nullable":true},"repair_note":{"type":"string","description":"Staff's free-text note in English; customer surfaces show repair_reason instead."},"repair_reason":{"type":"string","enum":["","backup_failed","box_unreachable","repair_failed","files_unmovable","needs_person"],"description":"Why an automatic repair did not run or did not finish, as a code the customer's card translates (docs/1027 §6): backup_failed = the backup taken before every automatic repair failed, so nothing was changed; box_unreachable = the site's server could not be reached; repair_failed = the repair ran and did not work; files_unmovable = some files sit inside a theme or plugin and are never moved automatically; needs_person = what was found is left for a person to review. Empty when nothing was refused; a repair that works clears it."},"site_id":{"type":"string","description":"Staff only."},"org_id":{"type":"string","description":"Staff only."},"domain":{"type":"string","description":"Staff list only."},"actor":{"type":"string","description":"Staff only."},"deep_clean":{"type":["object","null"],"description":"Staff only. The last deep clean of this finding (V1 clean2's file half): the backup it took first, what it changed, the home page status before and after, whether the box put the files back by itself, and staff's undo. Null when none ran.","properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"backup_dir":{"type":"string"},"stripped":{"type":"integer","description":"Files whose injected blocks were cut out."},"maze":{"type":"integer","description":"Defacer drop files moved out."},"status_before":{"type":"integer"},"status_after":{"type":"integer"},"undone":{"type":"boolean"},"at":{"type":"string","format":"date-time"},"undo":{"type":["object","null"],"properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"db_restored":{"type":"boolean"},"at":{"type":"string","format":"date-time"}}}}},"pre_repair_backup":{"type":["object","null"],"description":"Staff only. The backup taken on the box BEFORE this finding's automatic repair (`core`: wp-admin, wp-includes and the root PHP files; `db`: the database), and staff's restore of it (`POST .../restore_backup`). Null when no repair took one.","properties":{"scope":{"type":"string","enum":["core","db"]},"backup_dir":{"type":"string"},"at":{"type":"string","format":"date-time"},"restore":{"type":["object","null"],"properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"replaced_kept_at":{"type":"string","description":"Where the live copy it replaced was kept."},"at":{"type":"string","format":"date-time"}}}}}}},"SiteLinkReceipt":{"type":"object","description":"What one ingest batch did. It describes **this batch** and nothing about the org's data — the caller is a WordPress plugin, and anything richer would hand a description of a tenant's links to whoever guessed a hostname.","required":["accepted","ignored","posts","links","truncated","reconciled","removed"],"properties":{"accepted":{"type":"boolean"},"ignored":{"type":"boolean","description":"The batch belonged to a **superseded** pass and was dropped whole. Expected occasionally: the plugin's POST is fire-and-forget with a two-second timeout."},"posts":{"type":"integer","minimum":0},"links":{"type":"integer","minimum":0},"truncated":{"type":"boolean","description":"A post reported more links than the per-post ceiling and the tail was dropped. Surfaced rather than swallowed — a report that silently under-counts is worse than one that says it could not see everything."},"reconciled":{"type":"boolean","description":"This batch completed the pass, so the snapshot sweep ran."},"removed":{"type":"integer","minimum":0,"description":"Rows the sweep deleted. ⭐ The only externally visible proof the snapshot reconciliation works: a site whose links change while this stays `0` on every pass is the append-only rot this design exists to prevent."},"refused":{"type":"string","nullable":true,"description":"Why a **completing** batch was not swept, when it was not — a lost batch, or one whose post list was truncated. ⛔ Reported rather than swallowed: a pass that keeps completing without reconciling is a report going quietly stale, and the site is the only place that can be fixed."}}},"SiteLinkReportRequest":{"type":"object","description":"One batch of a site's outbound-link scan. Many of these make one pass; they all carry the same `scan_id`, and the one with `complete: true` ends it.","required":["site","scan_id"],"properties":{"site":{"type":"string","description":"The site's own `home_url()`. **An untrusted claim** — it selects which site's derived secret the signature is checked against, and nothing more.","example":"https://acme.example/"},"scan_id":{"type":"string","format":"uuid","description":"Identifies the **pass**, not the request. Minted by the plugin, because one pass spans many requests and the engine cannot mint it. Opaque: nothing is inferred from its value, and a site can only ever affect its own rows because the site comes from the signature."},"complete":{"type":"boolean","default":false,"description":"⛔ Only a literal `true` ends the pass. A missing key, a `null` or the string `\"false\"` all mean \"not complete\", because reading one as complete would sweep away every post the scan had not reached yet."},"posts_sent":{"type":"integer","minimum":0,"description":"Posts this **pass** has sent so far, cumulative across batches, as counted by the site. ⛔⛔ Load-bearing on the completing batch: the POST is non-blocking, so a site never learns that a batch was lost to a restart, a 502 or a rejected clock skew — it advances its cursor and eventually says `complete`, and the sweep would then delete the missing batch's posts **as if the customer had removed those links**. The engine compares this against what actually arrived and refuses to reconcile on a shortfall. ⚠️ Omitted by older clients that cannot report it; absence is tolerated (refusing every such pass would turn the report off), a present-and-short value is not."},"posts":{"type":"array","maxItems":100,"items":{"type":"object","required":["wp_post_id"],"properties":{"wp_post_id":{"type":"integer","format":"int64","minimum":1},"title":{"type":"string","maxLength":500},"url":{"type":"string","description":"The permalink. Blank when the scanner could not resolve one — never faked."},"links":{"type":"array","maxItems":500,"items":{"type":"object","required":["href","html"],"properties":{"href":{"type":"string"},"text":{"type":"string"},"html":{"type":"string","maxLength":4000,"description":"⭐ The **whole `<a>` tag**, opening tag through `</a>`. Required, and never synthesised engine-side: this exact string is what the bulk editor will rewrite on a live customer site, so a fabricated one is a future edit that silently drops the `rel` the customer had."},"count":{"type":"integer","minimum":1,"default":1,"description":"Occurrences of that exact tag in that post."}}}}}}}}},"SiteLoginCheck":{"type":"object","required":["available","enabled","status","step","busy","stale","error_code","verified_at","requested_at","key_source","sitekey","own_sitekey","places","all_places","can_rotate","rotated_at"],"properties":{"key_source":{"type":"string","enum":["platform","own"],"description":"`platform`: a widget we create. `own`: the customer's own keys (PUT /keys)."},"sitekey":{"type":"string","nullable":true,"description":"The PUBLIC sitekey the site uses now. Never the secret."},"own_sitekey":{"type":"string","nullable":true,"description":"The customer's own PUBLIC sitekey, when set. The secret is never returned."},"places":{"type":"array","items":{"type":"string","enum":["login","register","lostpassword","comments","cf7","wpforms","elementor","everest","fluent","formidable","forminator","happyforms","kadence","mc4wp","metform","ninja","otter","spectra"]},"description":"The forms the check protects."},"all_places":{"type":"array","items":{"type":"string"},"description":"Every form the check can protect (the picker's choices)."},"can_rotate":{"type":"boolean","description":"`true` for a platform widget that exists (POST /rotate)."},"rotated_at":{"type":"string","format":"date-time","nullable":true},"available":{"type":"boolean"},"enabled":{"type":"boolean","description":"What was last asked for."},"status":{"type":"string","enum":["off","pending","active","failed"]},"step":{"type":"string","enum":["queued","widget","site","idle"]},"busy":{"type":"boolean"},"stale":{"type":"boolean"},"error_code":{"type":"string","enum":["","readonly","no_widget","not_supported","own_keys_missing","failed"]},"verified_at":{"type":"string","format":"date-time","nullable":true},"requested_at":{"type":"string","format":"date-time","nullable":true}}},"SiteLoginCheckKeys":{"type":"object","required":["sitekey","secret"],"additionalProperties":false,"properties":{"sitekey":{"type":"string","maxLength":64,"description":"Your widget's sitekey (0x…)."},"secret":{"type":"string","maxLength":128,"writeOnly":true,"description":"Your widget's secret key. Checked with Cloudflare, kept in Vault, never returned."}}},"SiteLoginCheckUpdate":{"type":"object","required":["enabled"],"additionalProperties":false,"properties":{"enabled":{"type":"boolean"},"places":{"type":"array","minItems":1,"maxItems":18,"items":{"type":"string","enum":["login","register","lostpassword","comments","cf7","wpforms","elementor","everest","fluent","formidable","forminator","happyforms","kadence","mc4wp","metform","ninja","otter","spectra"]},"description":"Which forms to protect (V1's `forms`). Omitted keeps the current choice."}}},"SiteLveState":{"type":"object","description":"The site's CloudLinux LVE resource tier — `docs/204` §7b. ⭐ `ep` is the limit that emits `508 Resource Limit Is Reached`, which is why this is on a customer screen at all: it converts \"your server is broken\" into \"you hit your plan's limit, here is the upgrade\".","required":["tier","tier_label_key","limits","ladder","history","upgrade"],"additionalProperties":false,"properties":{"upgrade":{"type":"object","description":"What the customer can buy for this site (`docs/866` §3). The tier is the PLAN's rung — at least its product line's floor (D39: `growth` on every hosting line, `starter` on footprint-free), higher if the plan's price per site earns it, or an explicit `lve_tier` grant — raised N rungs by a level-N performance boost. `offers` lists every level that would lift THIS site higher than it runs today, and is EMPTY for a static site (served from disk, so no level would make it faster; an order for one is refused `boost_adds_nothing`); buying a higher level retires a lower one's charge. ⛔ No prices here: the panel reads each level's price from `GET /v1/extras` (`extra_code`) in the customer's own currency.","required":["boost_level","plan_tier","limits_reason","offers","held"],"additionalProperties":false,"properties":{"limits_reason":{"type":"string","enum":["plan","box_floor","app_size","app_size_below_rung"],"description":"Which rule set this site's CPU and memory (`docs/866` §3): `plan` — the plan's rung; `box_floor` — the server it runs on has a higher minimum than the plan's rung; `app_size` — an application plan's process size is above the rung, so it is used; `app_size_below_rung` — that size is below the rung, and the rung is kept."},"held":{"description":"The boost that sets the site's level today, or `null`.","oneOf":[{"type":"null"},{"type":"object","required":["purchase_id","level","extra_code","renews_on","renews","ends_on"],"additionalProperties":false,"properties":{"purchase_id":{"type":"string","format":"uuid"},"level":{"type":"integer"},"extra_code":{"type":"string"},"renews_on":{"type":["string","null"],"format":"date","description":"The next renewal, or `null` when nothing renews ($0 boost, or removal already scheduled)."},"renews":{"type":"boolean","description":"`true` exactly when `renews_on` is set."},"ends_on":{"type":["string","null"],"format":"date","description":"The last day a paid boost works once its removal is scheduled; `null` while it renews and for a $0 boost, which has no end."}}}]},"boost_level":{"type":"integer","description":"The boost level this site holds (0 for none)."},"plan_tier":{"type":"string","enum":["starter","growth","business","scale","power"],"description":"The rung the plan alone gives, before any boost."},"offers":{"type":"array","items":{"type":"object","required":["extra_code","level","tier","tier_label_key","speed","pmem_mb","ep"],"additionalProperties":false,"properties":{"extra_code":{"type":"string","description":"The extras code to buy — `POST /v1/extras/{code}/purchase` with this site's id."},"level":{"type":"integer"},"tier":{"type":"string","enum":["growth","business","scale","power"]},"tier_label_key":{"type":"string"},"speed":{"type":"integer","description":"CPU the site would get, percent of one core."},"pmem_mb":{"type":"integer"},"ep":{"type":"integer"}}}}}},"tier":{"type":"string","enum":["starter","growth","business","scale","power"]},"tier_label_key":{"type":"string"},"limits":{"type":"array","items":{"type":"object","required":["key","value","symptom_key"],"additionalProperties":false,"properties":{"key":{"type":"string","enum":["speed","pmem","nproc","ep","io","iops","inodes"]},"value":{"type":"string"},"symptom_key":{"type":"string","description":"i18n key for what the customer SEES when this limit is reached — the translation of a resource number into a symptom."}}}},"history":{"type":"object","description":"When this site was actually throttled, per limit, over the last 24 hours — the only part of this payload that says what HAPPENED rather than what is allowed.\n\n⛔ `available: false` is a real answer and is NOT the same as \"no faults\". Prometheus returns an empty result for a query that matched nothing — a wrong account label, an exporter that is not being scraped, a retention gap — and rendering that as a flat zero line would tell a customer who is being throttled right now that their site is fine. `reason` says which silence it is (`metrics_unavailable`, `no_samples`).","required":["available","reason","hours","limits"],"additionalProperties":false,"properties":{"usage":{"type":"object","description":"What the site actually USED over the window, beside what it may use — the \"you are at X of Y\" line. Peak and latest per resource; absent when the exporter published no usage series for this account.","additionalProperties":false,"properties":{"cpu_percent":{"type":"object","required":["peak","latest"],"additionalProperties":false,"properties":{"peak":{"type":"number"},"latest":{"type":"number"}}},"memory_mb":{"type":"object","required":["peak","latest"],"additionalProperties":false,"properties":{"peak":{"type":"number"},"latest":{"type":"number"}}}}},"available":{"type":"boolean"},"reason":{"type":"string","enum":["","metrics_unavailable","no_samples"]},"hours":{"type":"integer"},"step_seconds":{"type":"integer"},"limits":{"type":"object","description":"Fault counts per limit key, oldest first.","additionalProperties":{"type":"array","items":{"type":"object","required":["at","faults"],"additionalProperties":false,"properties":{"at":{"type":"string","format":"date-time"},"faults":{"type":"number","description":"Denials in that step. Non-zero means the site was actively throttled — for `ep`, that a visitor saw `508`."}}}}}}},"ladder":{"type":"array","description":"Every tier, so the panel can show what an upgrade buys.","items":{"type":"object","required":["key","label_key","current","speed","pmem_mb","ep","nproc","io_kbps","iops","inodes"],"additionalProperties":false,"properties":{"key":{"type":"string"},"label_key":{"type":"string"},"current":{"type":"boolean"},"speed":{"type":"integer"},"pmem_mb":{"type":"integer"},"ep":{"type":"integer"},"nproc":{"type":"integer"},"io_kbps":{"type":"integer"},"iops":{"type":"integer"},"inodes":{"type":"integer"}}}}}},"SiteMailSmtp":{"type":"object","description":"A site's own SMTP server for its website mail. Never carries the password.","required":["configured"],"properties":{"configured":{"type":"boolean"},"host":{"type":"string","example":"smtp.gmail.com"},"port":{"type":"integer","enum":[25,465,587,2525]},"tls":{"type":"string","enum":["starttls","implicit"]},"username":{"type":"string"},"from_address":{"type":"string","format":"email"},"enabled":{"type":"boolean"},"status":{"type":"string","enum":["unverified","active","failing"]},"last_error":{"type":"string","description":"A code: auth, tls, unreachable, unsupported, password_unreadable, server, or empty."},"proven_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"SiteMailSmtpUpdate":{"type":"object","required":["host","port","username","from_address"],"properties":{"host":{"type":"string"},"port":{"type":"integer","enum":[25,465,587,2525]},"tls":{"type":"string","enum":["starttls","implicit"],"description":"Defaults to `implicit` on 465 and `starttls` otherwise."},"username":{"type":"string"},"password":{"type":"string","format":"password","writeOnly":true,"description":"Required the first time; omit to keep the stored one."},"from_address":{"type":"string","format":"email"},"enabled":{"type":"boolean","default":true}}},"SiteMakerDisposition":{"type":"string","description":"What to do with what is already on the destination. `add_to` keeps every existing byte, `revamp` replaces presentation and keeps content, `replace` is destructive and requires a typed confirmation and a completed backup. `wordpress` (offered only on a WordPress or WooCommerce site on our own hosting, and its default) builds the draft INSIDE WordPress: a block theme made from the design, one WordPress page per built page, the home page set as the front page. Nothing existing is deleted, the previous theme stays installed, and a full backup is taken first.","enum":["add_to","revamp","replace","wordpress"]},"SiteMakerOccupancy":{"type":"string","description":"What is on a destination right now. ⛔ `unknown` is **not** `empty`: an empty destination is the one where overwriting is safe, so a destination we cannot read must never be reported as one.","enum":["empty","ours","occupied","unknown"]},"SiteMakerPluginPlan":{"type":"object","required":["install","rejected","notes"],"properties":{"install":{"type":"array","items":{"type":"object","required":["slug","name","why","source"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"why":{"type":"string"},"source":{"type":"string"}}}},"generated":{"nullable":true,"type":"object","description":"The custom plugin, when the site needs one. Its source is deliberately not returned; ask for it at publish time and it is regenerated and re-scanned there.","required":["slug","name","description","lines"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"lines":{"type":"integer"}}},"rejected":{"type":"array","items":{"type":"string"},"description":"Slugs proposed that are not in the curated set. Counted rather than silently dropped, so a plan that lost half its entries does not look like one that only ever had half."},"notes":{"type":"array","items":{"type":"string"},"description":"Includes the reason a generated plugin was refused by the scan, when one was."},"refusal":{"nullable":true,"type":"object","description":"Set when the platform DECLINED on purpose rather than failed — out of AI credit, or an org not in good standing. `null` when no refusal happened. ⛔ A separate field from `notes` because a consumer has to tell *\"we chose not to\"* from *\"the vendor was unavailable\"*: the first has an action the customer can take and the second does not, and showing an outage message for a deliberate refusal tells a customer to watch a vendor's status page when the true answer is \"top up\".","required":["kind","code","message","balanceMicros","canBuy"],"properties":{"kind":{"type":"string","enum":["out_of_credit","unavailable"],"description":"`out_of_credit` is the customer's to fix and carries a top-up action. `unavailable` is ours — no vendor is named and no status page is linked, because blaming a third party for our own configuration is the reverse of what the customer-facing AI failure rules exist to achieve."},"code":{"type":"string","description":"Machine-readable code, for a client to branch on."},"message":{"type":"string","description":"The sentence to show. Authored by the platform, never a vendor's error text."},"balanceMicros":{"type":"integer","description":"What the org holds right now, USD micros. Zero when it does not apply."},"canBuy":{"type":"boolean","description":"Whether buying credit would actually clear this refusal. `false` for the platform's own ceilings, where a top-up button would send the customer to a screen that cannot help them."}}}}},"SiteMakerPluginPlanEnvelope":{"type":"object","required":["plan","catalogue"],"properties":{"plan":{"$ref":"#/components/schemas/SiteMakerPluginPlan"},"catalogue":{"type":"array","description":"The curated set the model may choose from, and nothing else.","items":{"type":"object","required":["slug","name","why","source"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"why":{"type":"string"},"source":{"type":"string"}}}}}},"SiteMakerPreview":{"type":"object","required":["disposition","occupancy","needs_backup","needs_confirmation"],"properties":{"disposition":{"$ref":"#/components/schemas/SiteMakerDisposition"},"occupancy":{"$ref":"#/components/schemas/SiteMakerOccupancy"},"occupancy_detail":{"type":"string"},"needs_backup":{"type":"boolean","description":"Whether this publication would overwrite live files and therefore takes a full backup first. Keyed on what the publication does, so a `revamp` that overwrites real pages needs one just as a `replace` does."},"needs_confirmation":{"type":"boolean"},"confirm_with":{"type":"string","description":"The exact hostname the customer must type to confirm a `replace`."},"kept":{"type":"integer"},"added":{"type":"array","items":{"type":"string"}},"overwritten":{"type":"array","items":{"type":"string"},"description":"Existing paths this publication would not preserve. Empty for `add_to` by construction."},"renamed":{"type":"object","additionalProperties":{"type":"string"},"description":"Generated path → the name it will be written under to avoid a collision."},"total_files":{"type":"integer"}}},"SiteMakerPreviewEnvelope":{"type":"object","required":["preview"],"properties":{"preview":{"$ref":"#/components/schemas/SiteMakerPreview"}}},"SiteMakerPreviewRequest":{"type":"object","required":["site_id","disposition"],"properties":{"site_id":{"$ref":"#/components/schemas/Uuid"},"disposition":{"$ref":"#/components/schemas/SiteMakerDisposition"}}},"SiteMakerPublication":{"type":"object","required":["id","build_id","site_id","disposition","status","steps"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"build_id":{"$ref":"#/components/schemas/Uuid"},"site_id":{"$ref":"#/components/schemas/Uuid"},"disposition":{"$ref":"#/components/schemas/SiteMakerDisposition"},"status":{"$ref":"#/components/schemas/SiteMakerPublicationStatus"},"step":{"type":"string","description":"The stage currently running. Blank once the publication is terminal."},"steps":{"type":"array","items":{"type":"string"},"description":"The full ordered list, so a client renders progress without hardcoding the workflow's shape."},"live_url":{"type":"string"},"error":{"type":"string"},"hold_reason":{"type":"string"},"backup_id":{"type":"string","description":"The backup taken before anything was overwritten. Empty when the publication destroyed nothing and therefore needed none."},"change_summary":{"type":"object","additionalProperties":true,"description":"What the merge did, computed before anything was written."},"plugins":{"type":"object","additionalProperties":true,"description":"`installed` and `failed`. A plugin that would not install does not fail the publication: the site is already live and correct."},"created_at":{"type":"string"},"finished_at":{"type":"string"}}},"SiteMakerPublicationEnvelope":{"type":"object","required":["publication"],"properties":{"publication":{"$ref":"#/components/schemas/SiteMakerPublication"}}},"SiteMakerPublicationList":{"type":"object","required":["publications"],"properties":{"publications":{"type":"array","items":{"$ref":"#/components/schemas/SiteMakerPublication"}}}},"SiteMakerPublicationStatus":{"type":"string","description":"`held` is neither success nor failure: the files are safe in the repository and nothing on the site was overwritten, because the destination held files we did not put there.","enum":["planned","running","backing_up","published","held","failed","cancelled"]},"SiteMakerPublishRequest":{"type":"object","required":["site_id","disposition"],"properties":{"site_id":{"$ref":"#/components/schemas/Uuid"},"disposition":{"$ref":"#/components/schemas/SiteMakerDisposition"},"confirm_hostname":{"type":"string","description":"The site's own primary domain, typed by a human. Required for `replace` and compared exactly (case and surrounding space are ignored). ⛔ Not a boolean: a flag is satisfied by any client that sets it, so it would confirm that a field exists rather than that somebody read the domain."},"install_plugins":{"type":"array","items":{"type":"string"},"description":"Slugs from the curated catalogue. Re-vetted server-side; anything else is dropped and counted. The client's list is a request, never an authority."},"include_generated_plugin":{"type":"boolean","default":false,"description":"Regenerate and re-scan the custom plugin, and install it if it passes."}}},"SiteMakerTarget":{"type":"object","required":["site_id","hostname","publishable","occupancy","occupancy_detail","allowed_dispositions","default_disposition"],"properties":{"site_id":{"$ref":"#/components/schemas/Uuid"},"hostname":{"type":"string"},"product_line":{"type":"string"},"deploy_target":{"type":"string"},"publishable":{"type":"boolean","description":"Whether this transport can accept a generated site at all."},"refusal":{"type":"string","description":"Empty when `publishable`. Otherwise the provider's own reason, so a customer on a resold package is told why rather than handed a generic failure."},"occupancy":{"$ref":"#/components/schemas/SiteMakerOccupancy"},"occupancy_detail":{"type":"string","description":"A sentence for the screen, e.g. \"12 files we published here on 2 September\"."},"known_files":{"type":"integer","description":"How many source files we can see. `0` for `empty` and for `unknown` alike, which is why a client must read `occupancy` and never this number."},"allowed_dispositions":{"type":"array","description":"The choices on offer, the recommended one first.","items":{"$ref":"#/components/schemas/SiteMakerDisposition"}},"default_disposition":{"type":"string","description":"The choice a screen should preselect: `wordpress` on a WordPress or WooCommerce site, otherwise the first of `allowed_dispositions`. Empty when nothing is on offer (an unpublishable destination)."}}},"SiteMakerTargetList":{"type":"object","required":["targets","dispositions","truncated"],"properties":{"targets":{"type":"array","items":{"$ref":"#/components/schemas/SiteMakerTarget"}},"truncated":{"type":"boolean","description":"`true` when `targets` is a full page and more destinations exist beyond it. The list is ordered by hostname and capped, so a site that sorts past the cap is absent rather than listed — narrow with `search` to reach it. A client that treats a full page as the whole estate offers no way to choose that site."},"dispositions":{"type":"array","description":"The catalogue, so a client never hardcodes the choices and adding one cannot leave a stale copy behind.","items":{"type":"object","required":["value","label","destructive"],"properties":{"value":{"$ref":"#/components/schemas/SiteMakerDisposition"},"label":{"type":"string"},"destructive":{"type":"string","enum":["true","false"]}}}}}},"SiteMediaOffload":{"type":"object","required":["configured"],"properties":{"configured":{"type":"boolean","description":"`false` when this site has no offload set up. The rest of the fields are then absent — except `plan`, which is present in both states on purpose."},"plan":{"$ref":"#/components/schemas/MediaStorageTerms"},"id":{"type":"string","format":"uuid"},"site_id":{"type":"string","format":"uuid"},"bucket_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["awaiting_pairing","active","paused","revoked"]},"prefix":{"type":"string","description":"The key prefix this site's objects live under."},"rewrite_urls":{"type":"boolean","description":"Whether the plugin points media URLs at the bucket. Off means \"upload a copy but keep serving locally\", which is how a cautious customer migrates."},"delete_local":{"type":"boolean","description":"Whether the plugin removes the local file after a confirmed upload. Defaults to off, and even when on the plugin refuses to delete after a partial upload."},"custom_domain":{"type":"string","description":"The site's OWN media domain, as the customer typed it, or `\"\"`. This is what belongs in the settings input box. See `public_base_url` for where media is actually served from — the two differ, and the difference is meaningful."},"public_base_url":{"type":"string","description":"Where this site's media is actually served from, after the site's own domain, the footprint rule and the bucket's shared hostname have been resolved. `\"\"` means no URL is rewritten and the site goes on serving its own copies.\nA footprint-free site with no domain of its own reports `\"\"` here **by design**: serving a private blog network's images from a shared Zinn® hostname would publish the link between every site the customer owns. Set `custom_domain` to turn rewriting on for such a site."},"needs_custom_domain":{"type":"boolean","description":"`true` when this site is serving media locally only because it has no media domain of its own — a footprint-free site awaiting a CNAME. Distinguishes the one empty-`public_base_url` state the customer can act on from the ones they cannot, so a screen can offer the fix instead of reporting a fault."},"accepts_uploads":{"type":"boolean","description":"Whether the plugin may currently upload. Requires both an active offload and a usable bucket."},"paired":{"type":"boolean","description":"Whether a plugin token has been issued. The token and its hash are never returned."},"plugin_version":{"type":"string"},"last_seen_at":{"type":"string","format":"date-time","nullable":true,"description":"When the plugin last called. `null` means it never has."},"objects_offloaded":{"type":"integer","format":"int64","description":"What the plugin reports it has moved. A diagnostic for the screen, never an input to billing — storage is metered by measuring the bucket."},"bytes_offloaded":{"type":"integer","format":"int64"},"created_at":{"type":"string","format":"date-time"}}},"SiteMediaOffloadWrite":{"type":"object","properties":{"bucket_id":{"type":"string","format":"uuid","nullable":true,"description":"Which bucket to use. Omit to use the organisation's own, provisioning one on first use. Changing this on a live offload is refused."},"enabled":{"type":"boolean","description":"Pause or resume a paired site. Ignored before the plugin has paired."},"rewrite_urls":{"type":"boolean"},"delete_local":{"type":"boolean"},"prefix":{"type":"string","maxLength":128},"custom_domain":{"type":"string","maxLength":255,"description":"A media domain of the site's own, replacing the shared Zinn® hostname. Must be `https://` and a bare domain with no path. Send `\"\"` to clear it.\nRequired to turn on URL rewriting for a footprint-free site, which never uses the shared hostname."}}},"SiteMetrics":{"type":"object","description":"Point-in-time per-site usage for the Overview panel. Collected asynchronously off the request path (see `getSiteMetrics`); when no sample exists yet `available` is `false` and the counters are `null`.\n\n**Which producer fills which field** (`docs/50` contract C2 — this is the published shape; no other lane invents one). `available` gates the *usage* counters only, and `performance` carries its own flag, because the two come from different producers and one can be live while the other is not:\n\n* `bandwidth_mb`, `visits`, `bandwidth_series`, `collected_at` — the **traffic\n  collector** (#626, W7A). Live: a daily roll-up reads per-site byte/request/\n  visitor counters that the worker box aggregates from its own access logs and\n  Alloy pushes to Prometheus, and writes them to `SiteTrafficSample`. `available`\n  gates these. They report `null` until a box is actually reporting, and a sample\n  whose on-box exporter has gone stale is discarded rather than repeated — a dead\n  box must not keep serving its last good day for ever.\n* `disk_used_mb` — the **hourly resource collector** (`SiteResourceSample`, #2089 /\n  #1674), read back here as a stored row and never as a call to the box. Reported\n  only while that reading is FRESH; a stale one reports `null`, because this\n  envelope carries no per-field measurement time for disk and an old figure would\n  present itself as current. The live, authoritative answer — which costs an SSH\n  round trip — is `getSiteQuota`, which is why it is a separate route (§2.16).\n* `disk_limit_mb` — the ceiling the box actually ENFORCES, from the stored fleet\n  snapshot. ⛔ Not the plan allowance: what a customer BOUGHT (`disk_allowance_gb`\n  on `getSiteQuota`) and what is enforced are different quantities and they drift,\n  so neither is ever substituted for the other. `null` when no ceiling is stored.\n* `php_version` — the site's own column, written by `setSitePhpVersion`. * `ssl_status`, `ssl_expires_at` — the managed CDN zone where one fronts the site,\n  otherwise the site's own certificate as the SSL surface last measured it. Never a\n  live TLS probe on this path.\n* `error_rate` — the **error-rate collector** (#626, W7A), with its own flag.\n  Hourly counts of HTTP 4xx/5xx and PHP fatals/notices per site, read out of Loki,\n  where LiteSpeed's logs already arrive.\n\n\n⛔ This list said `disk_used_mb`, `disk_limit_mb`, `php_version` and `ssl_*` were produced by a collector that was *\"not yet running\"*, and described a `performance` block that no longer exists in this schema. Three of those four had since been wired and the fourth was retired — so the published contract was describing an endpoint we had stopped shipping. Corrected with the disk fix (W39-I, D19870).\n\nConsumers must render an unavailable block as \"not yet available\" and must **not** substitute zeros — a site showing 0 MB of disk and 0 throttling looks healthy and is indistinguishable from one that has never been measured.","required":["available","disk_used_mb","disk_limit_mb","bandwidth_mb","visits","bandwidth_series","collected_at","error_rate"],"properties":{"available":{"type":"boolean","description":"Whether a metrics sample has been collected for this site yet."},"disk_used_mb":{"type":["integer","null"],"format":"int64","minimum":0,"description":"Disk the site is using, in MB, from the newest stored hourly reading. `null` when nothing has measured it yet **or** when the newest reading is too old to present as current — the two are deliberately the same answer here, because both mean \"we cannot tell you what it is right now\". `getSiteQuota` takes the live measurement.","example":164},"disk_limit_mb":{"type":["integer","null"],"format":"int64","minimum":0,"description":"The disk ceiling ENFORCED on the box, in MB, as last stored. `null` when no ceiling is recorded. ⛔ Not the plan allowance — see `getSiteQuota`, which returns both separately because they are different quantities.","example":1024},"bandwidth_mb":{"type":["integer","null"],"format":"int64","minimum":0,"description":"Bandwidth used in the current period."},"visits":{"type":["integer","null"],"format":"int64","minimum":0},"php_version":{"type":"string","description":"The PHP version the site runs; empty when not applicable/unknown.","example":"8.3"},"serving_ok":{"type":["boolean","null"],"description":"Whether the site actually answered over HTTPS **from outside the box** at `serving_checked_at`, established by the recurring serving sweep rather than on this request.\n`null` means **nobody has established this**, and is not `false`. The distinction is load-bearing: `status: active` is written once at provisioning and says nothing about whether the site still serves, and reporting `false` for \"we have not looked\" would replace that silence with a fabricated outage.\n"},"serving_checked_at":{"type":["string","null"],"format":"date-time","description":"When a DEFINITE serving verdict was last obtained; `null` until one has been. Deliberately separate from the sweep's rotation cursor, which advances for every site the sweep reaches — including ones it could not judge — so that a staleness alarm on this field still means something.\n"},"serving_detail":{"type":"string","description":"The short status line behind `serving_ok` — `\"HTTP 522\"`, `\"ConnectTimeout\"`. Never a raw vendor response body.\n","example":"HTTP 522"},"ssl_status":{"type":"string","enum":["active","pending","none","unknown"],"description":"The site's TLS certificate state."},"ssl_expires_at":{"type":["string","null"],"format":"date-time"},"bandwidth_series":{"type":"array","description":"Recent daily bandwidth samples (MB), oldest first — for the usage chart. Empty when unavailable.","items":{"type":"integer","format":"int64","minimum":0}},"collected_at":{"type":["string","null"],"format":"date-time","description":"When this sample was collected; null when unavailable."},"error_rate":{"$ref":"#/components/schemas/SiteErrorRate"}}},"SiteMigration":{"type":"object","required":["id","site_id","source","status","include_mail","files_total","files_done","databases_total","databases_done","mailboxes_total","mailboxes_done","items_failed","bytes_transferred","warnings","created_at"],"description":"One migration job. ⛔ The Vault reference to the source credentials is deliberately absent — publishing one would hand out the shape of the per-tenant secret namespace — as is the staff-only English `message`.","properties":{"id":{"$ref":"#/components/schemas/Uuid"},"site_id":{"$ref":"#/components/schemas/Uuid"},"source":{"$ref":"#/components/schemas/MigrationSource"},"status":{"$ref":"#/components/schemas/SiteMigrationStatus"},"status_reason":{"type":"string","description":"A machine code the dashboard renders through its own catalogue — never an English sentence composed by the engine, which could be shown to none of the other 57 locales."},"include_mail":{"type":"boolean"},"source_host":{"type":"string","description":"The hostname the estate is being pulled from. Host only: no port, no username, and never a secret."},"files_total":{"type":"integer"},"files_done":{"type":"integer"},"databases_total":{"type":"integer"},"databases_done":{"type":"integer"},"mailboxes_total":{"type":"integer"},"mailboxes_done":{"type":"integer"},"items_failed":{"type":"integer","description":"⛔ Counted separately from the `*_done` fields, never folded into them. \"We could not get it\" reported as \"done\" makes the completion report a lie."},"bytes_transferred":{"type":"integer"},"warnings":{"type":"array","items":{"type":"string"},"description":"Machine warning codes the dashboard localises."},"mail_synced_at":{"type":"string","format":"date-time","nullable":true,"description":"When the mail delta last ran. `null` and a timestamp are different states, and the cutover control reads this to tell them apart."},"dns_records_captured":{"type":"integer","description":"How many records were read off the source's zone and will be published on cutover. ⛔ Counted separately from `dns_records_unsupported`, never as one total: \"we captured 14 records\" and \"14 of your 17 records will be published\" are different sentences and only the second is honest."},"dns_records_unsupported":{"type":"integer","description":"Real records the source holds that our DNS editor cannot express (an `SSHFP`, a `TLSA`, an `MX` with no preference). Stored and listed on the detail endpoint rather than dropped — this is the customer's copy-by-hand list, and they get one chance at it before the old host is cancelled."},"dns_captured_at":{"type":"string","format":"date-time","nullable":true,"description":"When the source's zone was read. `null` means never attempted, which is NOT the same as attempted-and-the-panel-holds-no-zone; only the first is worth retrying."},"verified_at":{"type":"string","format":"date-time","nullable":true,"description":"When the migrated site was last fetched over HTTP and compared with the source. `null` means the destination has never been looked at."},"verification_code":{"type":"string","description":"A machine code the dashboard localises. Empty means the destination is serving the site as well as the source was. ⛔ The migration's own counters cannot answer this: they travel the path the migration repairs, so the vhost, the `:443` listener, the document root and the database credentials are all invisible to them."},"destination_status":{"type":"integer","description":"The HTTP status the migrated site returned, fetched at its origin address with a `Host:` header — before cutover the customer's domain still resolves to the OLD host, so asking for it by name would measure the source and pass."},"source_status":{"type":"integer","description":"The HTTP status the source returned. ⭐ Reported beside `destination_status` because the interesting failure is the PAIR: a destination 200 against a source 500 means we faithfully copied a broken site, while a destination 403 against a source 200 means we did not."},"replaces_existing":{"type":"boolean","description":"Whether this migration landed on a site that already held a website. Stamped when the job is created and never recomputed: after the apply step the site is occupied *by the migration*, so a value derived at read time would answer \"yes\" about every migration ever run — and the rollback offer would then be made to customers who have no safety backup because they never needed one."},"safety_backup_state":{"type":"string","enum":["not_needed","pending","taken","unsupported","failed"],"description":"What became of the backup taken immediately before the apply step replaced the site. ⛔ Five values rather than a boolean: *\"there is no safety backup\"* is one rendered sentence for four different facts and only `taken` is safe to act on. `unsupported` means this site's hosting cannot produce our archive at all, and the migration proceeded with the customer told in advance that there would be no way back; `failed` means the migration was **stopped** and the site was never touched."},"safety_backup_id":{"type":"string","description":"The `SiteBackup` id, or `\"\"`. ⛔ Still reported after the archive has been pruned by retention, so a rollback can say *\"that archive has expired\"* rather than looking like a migration that never had one."},"rolled_back_at":{"type":"string","format":"date-time","nullable":true,"description":"When the customer put the site back. Set once — restoring the pre-migration archive over a site that is already the pre-migration archive can only lose work done since."},"rollback":{"$ref":"#/components/schemas/MigrationRollback"},"started_at":{"type":"string","format":"date-time","nullable":true},"finished_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"SiteMigrationCreate":{"allOf":[{"$ref":"#/components/schemas/MigrationCredentials"},{"type":"object","required":["ownership_attested"],"properties":{"ownership_attested":{"type":"boolean","default":false,"description":"⚠️ The customer's assertion that this estate is theirs to move, recorded because it cannot be reconstructed afterwards. Required — the job is refused without it — but it is **not** a legal control and is not presented as one."},"replace_confirmation":{"type":"string","maxLength":253,"default":"","description":"The target site's own domain, typed back by the customer. **Required only when the target site already holds a website** — migrating onto it replaces its files and database. Refused as `replace_not_confirmed` when absent and `replace_confirmation_mismatch` when it names a different site; the two are distinct because the second is a customer who was about to replace the wrong site. The server decides which path this is, never the client: a caller able to skip the confirmation by omitting the field would be a control enforced on the far side of the request. Case- and whitespace-insensitive."}}}]},"SiteMigrationDetail":{"allOf":[{"$ref":"#/components/schemas/SiteMigration"},{"type":"object","required":["dns_records","dns_plan","report"],"description":"⛔ The captured zone is on the DETAIL endpoint only. A zone is tens of records per migration, so embedding it in the list response would multiply it by the size of the customer's DNS for a screen that renders none of it.","properties":{"dns_records":{"type":"array","items":{"$ref":"#/components/schemas/MigrationDnsRecord"}},"dns_plan":{"$ref":"#/components/schemas/MigrationDnsPlan"},"report":{"allOf":[{"$ref":"#/components/schemas/MigrationReport"}],"nullable":true,"description":"What the customer is told about the migration, in their own language. `null` until the report step has run — which is a real state while files are still copying, and is **not** the same as a report whose narrative is empty because the assistant was unreachable. Folding those two would tell a customer whose migration finished ten minutes ago that it is still going."}}}]},"SiteMigrationList":{"type":"object","required":["migrations"],"properties":{"migrations":{"type":"array","items":{"$ref":"#/components/schemas/SiteMigration"}}}},"SiteMigrationStatus":{"type":"string","enum":["pending","authenticating","inventorying","transferring","verifying","awaiting_cutover","completed","failed","cancelled"],"description":"`authenticating`, `inventorying` and `transferring` are separate states rather than one `running` because they fail for opposite reasons and the customer's next action differs: a failure while inventorying means the credentials or the panel are wrong and **nothing has moved**, while a failure while transferring means part of the estate is already here. `awaiting_cutover` means the website is live and mail is waiting for the customer to move their MX before the delta re-sync."},"SiteMoodleAutoUpdate":{"type":"object","description":"The paid automatic Moodle updates add-on for one site (s1014, docs/1160).","required":["site_id","offered","active","can_buy","refusal","price","purchase_id","renews_on","ends_on","enabled","window_weekday","window_hour","timezone","next_window_at","last_run"],"additionalProperties":false,"properties":{"site_id":{"type":"string","format":"uuid"},"offered":{"type":"boolean","description":"Whether the add-on is on sale to this organisation."},"active":{"type":"boolean","description":"Whether the add-on is on and in good standing now."},"can_buy":{"type":"boolean"},"refusal":{"type":"string","nullable":true,"description":"Why it cannot be bought right now, or null."},"price":{"nullable":true,"description":"The yearly price in the caller's currency, or null when not on sale.","allOf":[{"$ref":"#/components/schemas/MoneyAmount"}]},"purchase_id":{"type":"string","format":"uuid","nullable":true},"renews_on":{"type":"string","format":"date","nullable":true},"ends_on":{"type":"string","format":"date","nullable":true},"enabled":{"type":"boolean"},"window_weekday":{"type":"integer","minimum":0,"maximum":6,"nullable":true,"description":"0 = Monday … 6 = Sunday; null = every day."},"window_hour":{"type":"integer","minimum":0,"maximum":23},"timezone":{"type":"string"},"next_window_at":{"type":"string","format":"date-time","nullable":true},"last_run":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/MoodleUpgradeRun"}]}}},"SiteMoodleUpgrade":{"type":"object","description":"A site's one-click Moodle upgrade state (s1014, docs/1160).","required":["site_id","is_moodle","installed","available","blocked","can_upgrade","refusal","checked_at","check_pending","current_run","runs","branch_pin","plugin_warnings"],"additionalProperties":false,"properties":{"site_id":{"type":"string","format":"uuid"},"is_moodle":{"type":"boolean"},"branch_pin":{"$ref":"#/components/schemas/MoodleBranchPin"},"plugin_warnings":{"type":"array","description":"Installed plugins that may not work on the INSTALLED release (a warning, never a hold). `key` is the dashboard's `moodleUpgrade.pluginWarning.<key>`; `reason` is the English fallback.","items":{"$ref":"#/components/schemas/MoodlePluginWarning"}},"installed":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/MoodleRelease"}]},"available":{"nullable":true,"description":"The highest release this server can run that is newer than installed.","allOf":[{"$ref":"#/components/schemas/MoodleRelease"}]},"blocked":{"type":"array","items":{"$ref":"#/components/schemas/MoodleBlockedRelease"}},"can_upgrade":{"type":"boolean"},"refusal":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/MoodleRefusal"}]},"checked_at":{"type":"string","format":"date-time","nullable":true},"check_pending":{"type":"boolean"},"current_run":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/MoodleUpgradeRun"}]},"runs":{"type":"array","description":"Newest first, at most ten.","items":{"$ref":"#/components/schemas/MoodleUpgradeRun"}}}},"SiteMoveOverview":{"type":"object","required":["slots","moves"],"properties":{"slots":{"type":"array","items":{"$ref":"#/components/schemas/PartnerHostingSlot"}},"moves":{"type":"array","items":{"$ref":"#/components/schemas/PartnerSiteMove"}}}},"SiteMysqlDatabase":{"type":"object","required":["id","name","username","is_primary","size_mb"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"The database's name","which is its stable id.":null},"name":{"type":"string","example":"zc1a2b3c_shop"},"username":{"type":"string","description":"The MySQL user that owns it."},"is_primary":{"type":"boolean","description":"The website's own database. It cannot be deleted here."},"size_mb":{"type":"number","nullable":true,"description":"Measured size in MB, or null when the server did not report one."}}},"SiteMysqlDatabaseCreated":{"type":"object","required":["database","password"],"additionalProperties":false,"properties":{"database":{"$ref":"#/components/schemas/SiteMysqlDatabase"},"password":{"type":"string","format":"password","description":"Generated by the platform and returned once. It cannot be read back."}}},"SiteMysqlDatabaseList":{"type":"object","required":["data","limit","included","paid","permitted","can_create","can_buy","extra_price","paid_slots"],"additionalProperties":false,"properties":{"data":{"type":"array","description":"The site's own database first, then its extras by name.","items":{"$ref":"#/components/schemas/SiteMysqlDatabase"}},"limit":{"$ref":"#/components/schemas/VendorAllowance"},"included":{"$ref":"#/components/schemas/VendorAllowance"},"paid":{"type":"integer","minimum":0,"description":"Extra-database add-ons for this site that are paid up today."},"permitted":{"type":"boolean"},"can_create":{"type":"boolean"},"can_buy":{"type":"boolean"},"extra_price":{"nullable":true,"description":"The monthly price of one more database, in the caller's currency.","allOf":[{"$ref":"#/components/schemas/MoneyAmount"}]},"paid_slots":{"type":"array","description":"The extra-database slots bought for this site that are paid up today, oldest first, so the customer can stop one renewing (`stopSiteDatabaseSlot`).","items":{"$ref":"#/components/schemas/SiteMysqlDatabaseSlot"}}}},"SiteMysqlDatabaseSlot":{"type":"object","required":["purchase_id","renews_on","ends_on"],"additionalProperties":false,"properties":{"purchase_id":{"type":"string","format":"uuid"},"renews_on":{"type":"string","format":"date","nullable":true,"description":"The next renewal date while the slot renews, else null."},"ends_on":{"type":"string","format":"date","nullable":true,"description":"The last day the slot works once its renewal was stopped, else null."}}},"SiteMysqlDatabaseSlotStopped":{"type":"object","required":["purchase_id","ends_on"],"additionalProperties":false,"properties":{"purchase_id":{"type":"string","format":"uuid"},"ends_on":{"type":"string","format":"date","nullable":true,"description":"The last day the slot works, or null when nothing was billing (a staff grant, or a slot already stopped)."}}},"SiteNotificationChannel":{"type":"object","required":["connection_id"],"properties":{"id":{"type":"string","format":"uuid","readOnly":true},"connection_id":{"type":"string","format":"uuid","description":"A destination from `/v1/notification-connections`. Org-level destinations are addressable by any member; a personal one only by the person who created it."},"topic":{"type":"string","description":"Restrict this route to one topic. Empty means every topic - one column with one meaning, rather than a null-versus-\"all\" pair a routing table can disagree about."},"enabled":{"type":"boolean","default":true}}},"SiteNotificationChannels":{"type":"object","description":"A site's routing, and the LIVE e-mail decision rather than the stored wish.","required":["site_id","channels","email_muted","email_active","email_reason"],"properties":{"site_id":{"type":"string","format":"uuid"},"channels":{"type":"array","items":{"$ref":"#/components/schemas/SiteNotificationChannel"}},"email_muted":{"type":"boolean","description":"What the customer ASKED for. Not necessarily what is happening."},"email_active":{"type":"boolean","description":"Whether e-mail is actually being sent right now. Computed at send time from the live health of the other channels, never read from a stored flag."},"email_reason":{"type":"string","description":"Why. `not_muted` - the customer never turned it off. `muted` - off, as asked, with a healthy alternative. `alternatives_failing` - back ON because their other channels have stopped delivering. `no_alternative` - back ON because nothing else is connected. `unreadable` - back ON because we could not determine the answer, which fails open deliberately: a duplicate is an annoyance, silence is not.","enum":["not_muted","muted","alternatives_failing","no_alternative","unreadable"]},"healthy_alternatives":{"type":"integer","description":"How many non-e-mail destinations this site routes to are delivering."},"overriding_choice":{"type":"boolean","description":"True when e-mail is being sent DESPITE the customer having muted it. This is the state a screen must explain, or the toggle appears broken."}}},"SiteNotificationChannelsUpdate":{"type":"object","required":["channels"],"properties":{"channels":{"type":"array","description":"The COMPLETE set. Anything absent is removed.","items":{"$ref":"#/components/schemas/SiteNotificationChannel"}},"email_muted":{"type":"boolean","description":"Ask for e-mail to be switched off. Refused `422` unless at least one listed destination is a non-e-mail channel that is verified and delivering."}}},"SiteObjectStorage":{"type":"object","required":["used_bytes","object_count","limit_bytes","percent","measured_at","uploads_blocked"],"properties":{"used_bytes":{"type":["integer","null"],"format":"int64","description":"Bytes stored. Null until the first daily measurement (never a guessed 0)."},"object_count":{"type":["integer","null"],"format":"int64"},"limit_bytes":{"type":["integer","null"],"format":"int64","description":"The allowance in bytes, or null when the plan states none."},"percent":{"type":["integer","null"]},"measured_at":{"type":["string","null"],"format":"date-time"},"uploads_blocked":{"type":"boolean","description":"True at 100% - new files stay on the site's own disk until there is room."}}},"SiteOffsite":{"type":"object","required":["site_id","entitled","extra_code","retention_choices","policy","copies"],"properties":{"site_id":{"type":"string","format":"uuid"},"entitled":{"type":"boolean"},"extra_code":{"type":"string"},"retention_choices":{"type":"array","items":{"type":"integer"}},"policy":{"type":"object","nullable":true,"required":["destination","retention_days","enabled","copy_from"],"properties":{"destination":{"$ref":"#/components/schemas/OffsiteDestination"},"retention_days":{"type":"integer"},"enabled":{"type":"boolean"},"copy_from":{"type":"string","format":"date-time"}}},"copies":{"type":"array","items":{"$ref":"#/components/schemas/OffsiteCopy"}}}},"SiteOriginHost":{"type":"object","description":"Where a hostname-only CDN pulls this site from. `hostname` is empty until one is in force; `record` is what a customer who runs their own DNS adds.","required":["needed","hostname","mode","address","verified_at","record"],"properties":{"needed":{"type":"boolean","description":"Whether the site's current CDN needs a hostname origin."},"hostname":{"type":"string","description":"The origin hostname in force, or empty."},"mode":{"type":"string","enum":["","own_dns","customer_dns","origin_domain"],"description":"`own_dns` we write it on the site's domain; `customer_dns` the customer added it; `origin_domain` the neutral fallback name."},"address":{"type":"string","description":"The origin server address the hostname must answer with."},"verified_at":{"type":"string","format":"date-time","nullable":true,"description":"When public DNS last answered the hostname with `address`."},"record":{"type":"object","required":["name","type","value","answering"],"properties":{"name":{"type":"string","description":"The record name to add (a full hostname)."},"type":{"type":"string","enum":["A"]},"value":{"type":"string","description":"The origin server address."},"answering":{"type":"boolean","description":"Whether public DNS answers `name` with `value` right now."}}}}},"SiteOriginKey":{"type":"object","description":"Where one site's origin-lock key rotation is (docs/1211). Never carries the key.","required":["site_id","generation","state","rotating","rotated_at","previous_valid_until","last_error"],"properties":{"site_id":{"type":"string","format":"uuid"},"generation":{"type":"integer","minimum":0,"description":"How many rotations have finished. 0 is the key the site was created with."},"state":{"type":"string","enum":["idle","staged","overlap","failed"],"description":"`staged` - the server is learning the new key; `overlap` - the platform sends the new key and the old one is still accepted until `previous_valid_until`; `failed` - the last rotation stopped (see `last_error`) and the site is on its current key."},"rotating":{"type":"boolean","description":"True while `state` is `staged` or `overlap`."},"rotated_at":{"type":["string","null"],"format":"date-time","description":"When the platform last switched to a new key."},"previous_valid_until":{"type":["string","null"],"format":"date-time","description":"During `overlap`, when the old key stops being accepted."},"last_error":{"type":"string","description":"Why the last rotation failed, or empty."}}},"SiteOriginLoad":{"allOf":[{"$ref":"#/components/schemas/OriginLoadState"},{"type":"object","required":["site_id","checked_at","blind"],"properties":{"site_id":{"$ref":"#/components/schemas/Uuid"},"checked_at":{"type":"string","format":"date-time","nullable":true},"blind":{"type":"boolean"}}}]},"SiteOwnDomainDiagnosis":{"type":"object","description":"What is set, what is expected, what is wrong and the exact fix, for a person or an AI. `fix` is plain English for the assistant and the support-ticket AI to relay; screens render `problem` through their own catalogue. `registrar` and the registry nameservers are filled only by the live check (POST .../check).","required":["status","problem","fix","set","expected"],"properties":{"status":{"type":"string","enum":["no_domain","waiting","found","ssl","live"]},"problem":{"type":"string","enum":["","no_domain","nameservers_not_changed","record_missing","pointed_elsewhere","zone_expired","propagating","ssl_pending"]},"fix":{"type":"string"},"may_advise_nameservers":{"type":["boolean","null"],"description":"The support AI's DNS rule, filled by the live check: true only when our zone already serves the site's web and mail records, so naming nameservers cannot take the site or its mail offline. null on a GET."},"dns_case":{"type":"string","description":"The support AI's DNS case (`dns_truth`); empty on a GET."},"registrar":{"type":"string"},"registered_with_us":{"type":"boolean"},"set":{"type":"object","properties":{"nameservers":{"type":"array","items":{"type":"string"}},"addresses":{"type":["array","null"],"items":{"type":"string"}}}},"expected":{"type":"object","properties":{"nameservers":{"type":"array","items":{"type":"string"}},"records":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"value":{"type":"string"}}}}}}}},"SiteOwnDomainProgress":{"type":"object","description":"Where the site is on the \"Attach your own domain\" ladder (SITEDOMAIN 1108#21): `waiting` (DNS does not reach us yet) -> `found` (it does; confirming) -> `ssl` (reached; certificate being issued) -> `live`. `no_domain` = the site is on its free preview address only. `checked_at` is the last DNS reading, `next_check_at` when the fast ladder looks next (every 30 s for 10 min, every 2 min to an hour, then backing off; null when it is not watching).","required":["step","steps","checked_at","next_check_at","watching","live_since"],"properties":{"step":{"type":"string","enum":["no_domain","waiting","found","ssl","live"]},"steps":{"type":"array","items":{"type":"object","required":["key","state"],"properties":{"key":{"type":"string","enum":["waiting","found","ssl","live"]},"state":{"type":"string","enum":["done","current","todo"]}}}},"checked_at":{"type":["string","null"],"format":"date-time"},"next_check_at":{"type":["string","null"],"format":"date-time"},"watching":{"type":"boolean"},"live_since":{"type":["string","null"],"format":"date-time"},"gave_up_at":{"type":["string","null"],"format":"date-time"}}},"SiteOwnVps":{"type":"object","description":"A website's move onto the customer's own server (docs/88 §11): the offer, and the latest move. See `getSiteOwnVps`.","required":["site_id","offered","refusal","enrol_open","sizes","web_servers","move"],"properties":{"site_id":{"type":"string","format":"uuid"},"offered":{"type":"boolean"},"web_servers":{"type":"array","description":"The web servers the move can run (s1014 row 114), empty while no size is offered. `openlitespeed` is free and always first (the default). `litespeed` (LiteSpeed Enterprise, a monthly licence added to the server line) is listed only with its licence price per currency the sizes are shown in; absent when it cannot be priced.","items":{"type":"object","required":["code","prices"],"properties":{"code":{"type":"string","enum":["openlitespeed","litespeed"]},"prices":{"type":"array","items":{"type":"object","required":["currency","amount_minor"],"properties":{"currency":{"type":"string"},"amount_minor":{"type":"integer","description":"Monthly licence in minor units."}}}}}}},"refusal":{"type":"object","nullable":true,"description":"Why this site cannot move now (null when it can): `message` in English for SDKs, `key` the refusal catalogue key a screen translates, with `params`.","required":["message","key","params"],"properties":{"message":{"type":"string"},"key":{"type":"string"},"params":{"type":"object","additionalProperties":{"type":"string"}}}},"enrol_open":{"type":"boolean","description":"Whether a paid basket would be enrolled today. While false, checkout refuses it."},"sizes":{"type":"array","items":{"type":"object","required":["plan_code","name","cores","ram_gb","disk_gb","zones"],"properties":{"plan_code":{"type":"string"},"name":{"type":"string"},"cores":{"type":"integer","nullable":true},"ram_gb":{"type":"number","nullable":true},"disk_gb":{"type":"integer","nullable":true},"zones":{"type":"array","items":{"type":"object","required":["zone","amount_minor","currency"],"properties":{"zone":{"type":"string"},"label":{"type":"string","description":"The provider's own name for the location (a city or a cloud region), `\"\"` when it states none. A screen names the locations it has a translated name for itself and shows this for every other one."},"amount_minor":{"type":"integer","description":"Monthly price in minor units."},"currency":{"type":"string"}}}}}}},"move":{"type":"object","nullable":true,"required":["job_id","reason","status","step","message","hold_until","can_roll_back","refunded"],"properties":{"job_id":{"type":"string","format":"uuid","nullable":true,"description":"The site move's id, or null while the paid move is still building the server and setting up our panel on it (no copy has started)."},"reason":{"type":"string","enum":["own_vps","own_vps_rollback"]},"status":{"type":"string","description":"`preparing` (the server is being built, then our panel set up on it — `step` says which), the site move's own states (`pending`, `running`, `holding`, `succeeded`), or `failed`/`cancelled`. A failed forward move names where it stopped in `step`: `server` (the server could not be built), `setup` (our panel could not be set up on it) or `move` (the copy or its checks did not pass) — every one left the website where it was and refunds the server (`refunded` says when the money is back), and the offer (`sizes`) is there to try again."},"step":{"type":"string"},"message":{"type":"string"},"hold_until":{"type":"string","description":"ISO time the previous copy is removed; empty before the move."},"can_roll_back":{"type":"boolean"},"refunded":{"type":"boolean","description":"Whether the server's money is back — asked of the ledger (the order refunded, or the line's Zinn® credit written), never of the move's state. A move that ended (the box removed) is refunded a little after, so the screen says the refund is on its way until this is true."}}}}},"SiteOwnVpsQuote":{"type":"object","description":"The open basket that moves the website — one server line, nothing charged.","required":["site_id","cart_id","web_server","licence_minor","currency","lines","total_minor","charged"],"properties":{"site_id":{"type":"string","format":"uuid"},"cart_id":{"type":"string","format":"uuid","description":"Pay it through the ordinary checkout."},"web_server":{"type":"string","enum":["openlitespeed","litespeed"]},"licence_minor":{"type":"integer","description":"The LiteSpeed Enterprise licence part of the server line's amount (already inside it), minor units a month; 0 for OpenLiteSpeed."},"currency":{"type":"string"},"total_minor":{"type":"integer","description":"Monthly total before tax","minor units.":null},"charged":{"type":"boolean","description":"Always false — a quote never charges."},"lines":{"type":"array","items":{"type":"object","required":["kind","name","plan_code","extra_code","amount_minor","interval"],"properties":{"kind":{"type":"string","enum":["compute_server"]},"name":{"type":"string"},"plan_code":{"type":"string"},"extra_code":{"type":"string"},"amount_minor":{"type":"integer"},"interval":{"type":"string"}}}}}},"SiteOwnVpsQuoteRequest":{"type":"object","required":["plan_code","zone"],"properties":{"plan_code":{"type":"string","maxLength":64,"description":"One of the sizes from getSiteOwnVps."},"zone":{"type":"string","maxLength":64,"description":"One of that size's locations."},"web_server":{"type":"string","enum":["openlitespeed","litespeed"],"default":"openlitespeed","description":"`openlitespeed` (free) or `litespeed` — LiteSpeed Enterprise, whose monthly licence (the catalogue price in `getSiteOwnVps.web_servers`) is added to the server line. A currency the licence is not priced in is refused (422) before any basket exists."}}},"SitePage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Site"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"SitePanel":{"type":"object","description":"Everything the must-use plugin renders on one site's dashboard.","required":["plan","allowances","plan_links","cards","admin_bar","ttl"],"additionalProperties":false,"properties":{"plan":{"type":"object","description":"The governing subscription's name and renewal date. ⛔ **Empty when nothing governs this site** — a staff-assigned or trial site — rather than a fabricated \"Free\" plan, which would put a word on a customer's dashboard that appears on no invoice they have received.","additionalProperties":false,"properties":{"name":{"type":"string","example":"PBN 25"},"renews_on":{"type":"string","description":"Already formatted for the requested locale. ⛔ Not ISO-8601: the plugin has no calendar and no locale data, so `2026-11-30` would be shown unchanged to a customer whose country writes `30.11.2026`."}}},"allowances":{"type":"array","items":{"$ref":"#/components/schemas/SitePanelAllowance"}},"plan_links":{"type":"array","items":{"$ref":"#/components/schemas/SitePanelLink"}},"cards":{"type":"array","items":{"$ref":"#/components/schemas/SitePanelCard"}},"admin_bar":{"type":"array","items":{"$ref":"#/components/schemas/SitePanelLink"}},"zinn_ads":{"description":"The Zinn® Ads dashboard notice (za-35), or `null` where it must not show. ⛔⛔ Always `null` on a Footprint-Free (PBN) site and on a site with no product line — the plugin shows the notice only when this carries a URL, so the footprint rule is decided here, fail-closed, from the site's own product line. `url` is the public Zinn® Ads page in the requested locale (its translated slug once settled).","oneOf":[{"type":"null"},{"type":"object","required":["url"],"additionalProperties":false,"properties":{"url":{"type":"string","format":"uri","example":"https://zinndigital.com/pl/oprogramowanie-do-zarzadzania-reklamami"}}}]},"ttl":{"type":"integer","description":"How long the plugin may serve this answer before asking again, in seconds. Sent rather than hard-coded in the plugin, so the refresh cadence can change on the estate without a release."}}},"SitePanelAllowance":{"type":"object","description":"One metered resource: what it is, what is used and what is included.","required":["resource","label","unit","used","limit","percent"],"additionalProperties":false,"properties":{"resource":{"type":"string","description":"The engine's own key — `disk`, `inodes`, `bandwidth` or `database`.","example":"disk"},"label":{"type":"string","description":"The customer-facing name, already in the requested language.","example":"Disk space"},"unit":{"type":"string","description":"The unit the figures are in, as a CODE (`GB`, `MB`, `files`) which the plugin renders in the reader's own language. ⛔ Never a translated word — an English unit interpolated into a translated sentence is half-translated output in 57 languages.","example":"GB"},"used":{"type":"number","nullable":true,"description":"How much is used, in `unit`. ⛔ `null` means **not measured**, never zero — a database on hosting that cannot report one is permanently `null`."},"limit":{"type":"number","nullable":true,"description":"What is included, in `unit`. ⛔ `null` means **no limit is set**, never zero and never unlimited."},"percent":{"type":"integer","nullable":true,"description":"Whole-number percentage of the allowance in use, or `null` when either figure is unknown or the limit is zero (which means *no limit* on this estate)."}}},"SitePanelCard":{"type":"object","description":"One card the platform is currently showing on hosted sites' dashboards.","required":["id","title","body","cta_label","cta_url"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"The card's stable slug."},"title":{"type":"string"},"body":{"type":"string"},"cta_label":{"type":"string"},"cta_url":{"type":"string"}}},"SitePanelLink":{"type":"object","description":"A link under the plan widget, or an item in the admin bar's Hosting menu.","required":["id","label","url"],"additionalProperties":false,"properties":{"id":{"type":"string"},"label":{"type":"string"},"url":{"type":"string"}}},"SitePanelRequest":{"type":"object","description":"What the must-use plugin tells us about itself when it asks.","additionalProperties":false,"properties":{"locale":{"type":"string","description":"The WordPress locale of the administrator viewing the dashboard (`de_DE`, `pt_BR`). Resolved to one of the platform's languages; an unknown one gets English rather than an empty panel.","example":"de_DE"},"version":{"type":"string","description":"The plugin version this site is running. ⭐ This is what makes the rollout figure real — it is reported by the site rather than inferred from what we pushed.","example":"1.0.0"}}},"SitePanelSession":{"type":"object","description":"One freshly minted, single-use HTTPS link into a per-site panel (see `createSitePanelSession`). Valid for 180 seconds and destroyed by the box on first use, so it is meant to be opened immediately and never stored.","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"The HTTPS single-use SSO link. Never null on a `200` — a site with no panel to open is a `409`."},"reason":{"type":"string","description":"Empty on success; present so one client component can render both shapes."}}},"SitePanelSessionCreate":{"type":"object","description":"Which of the site's three per-site tools to open.","required":["tool"],"properties":{"tool":{"type":"string","enum":["phpmyadmin","filemanager","web_ide"],"description":"`phpmyadmin` opens the site's own database; `filemanager` opens the site's own home directory; `web_ide` opens VS Code in the browser against the site's files. A closed set on purpose — the value selects a driver method, and an open one would be a way to reach arbitrary driver attributes."}}},"SitePerformance":{"type":"object","required":["site_id","stack_supported","lscache_enabled","object_cache_enabled","object_cache_max_ttl","wp_memory_limit","stack","accelerate_wp"],"properties":{"site_id":{"$ref":"#/components/schemas/Uuid"},"stack_supported":{"type":"boolean","description":"Whether **we** configure this site's web stack, so the controls below can take effect at all.\n\nEvery control on this resource is applied over our **own** CloudLinux + LiteSpeed fleet. A site on a resold hosting package sits on a machine we do not configure, so the write used to succeed, the row changed, the tab re-rendered showing the cache on, and nothing reached the server. `PUT` now refuses with `STACK_NOT_OPERATED`, and clients hide the controls entirely.\n\n⛔ A **capability**, never a health reading. `false` means *this site's stack is not ours to configure*; it does **not** mean the cache is broken, and a client that renders it as a fault says the opposite of the truth. The fields below stay present and keep reporting the stored row — staff read them, and an absent field is indistinguishable from one we failed to compute (§2.44)."},"lscache_enabled":{"type":"boolean","description":"LiteSpeed LSCache full-page cache. Free, native to the fleet."},"object_cache_enabled":{"type":"boolean","description":"Redis per-site object cache. Free."},"object_cache_max_ttl":{"type":"integer","minimum":0,"description":"How long an object-cache entry may live, in seconds. `0` uses the plugin's own default."},"wp_memory_limit":{"type":"string","description":"`WP_MEMORY_LIMIT` for this site, e.g. `256M`; blank leaves WordPress's default. This is the per-site memory control: Redis has no per-user memory quota, so a shared instance cannot cap one site's footprint — what is genuinely per-site is the PHP memory WordPress may use."},"stack":{"$ref":"#/components/schemas/SiteStackState"},"accelerate_wp":{"$ref":"#/components/schemas/AccelerateWp"}}},"SitePerformanceUpdate":{"type":"object","additionalProperties":false,"description":"Merge semantics — send only what changed. An absent field is left alone, never reset, so switching on AccelerateWP cannot silently disable LSCache.","properties":{"lscache_enabled":{"type":"boolean"},"object_cache_enabled":{"type":"boolean"},"object_cache_max_ttl":{"type":"integer","minimum":0,"maximum":31536000},"wp_memory_limit":{"type":"string","maxLength":16,"description":"A PHP memory shorthand (`256M`, `1G`) or blank to clear the override. Anything PHP cannot parse is rejected with `INVALID_MEMORY_LIMIT` rather than normalised — PHP treats an unparseable value as bytes-or-zero and falls back to its own default, so a bad value would show on screen and do nothing."},"accelerate_wp_tier":{"$ref":"#/components/schemas/AccelerateWpTier"}}},"SitePermissionFailure":{"type":"object","description":"One file whose permissions the vendor's check flagged.","required":["path","recommended"],"additionalProperties":false,"properties":{"path":{"type":"string","description":"The file, relative to the package root. ⛔ Never the vendor's absolute host path — that names our supplier's filesystem layout to the customer.","example":"public_html/wp-config.php"},"recommended":{"type":"integer","nullable":true,"description":"The mode the vendor recommends, as a decimal integer. **Null** where the platform named a file without naming a mode — never a guessed `644`, because this number is applied to the customer's live file by `fixSiteFilePermissions`, which skips the nulls.","example":644}}},"SitePermissionReport":{"type":"object","description":"The result of the vendor's file-permission check on one site. Produced by `checkSiteFilePermissions`, which **runs** the scan rather than reading a cached one.","required":["check_id","public_html_wrong","root_wrong","failures","actionable"],"additionalProperties":false,"properties":{"check_id":{"type":"integer","nullable":true,"description":"The vendor's handle for this check. **Null** when the vendor gave us none, in which case there is nothing to apply and `actionable` is false. ⛔ A client never sends it back: `fixSiteFilePermissions` re-runs the check itself so a stale handle cannot be replayed against files that have changed since.","example":90210},"public_html_wrong":{"type":"boolean","description":"Whether the document root's own mode is wrong."},"root_wrong":{"type":"boolean","description":"Whether the package root's own mode is wrong."},"failures":{"type":"array","description":"The individual files the check flagged.","items":{"$ref":"#/components/schemas/SitePermissionFailure"}},"actionable":{"type":"boolean","description":"Whether *Fix these* can do anything: a live check handle **and** something to fix. Its own field so the button is not offered against a report that can only be refused."}}},"SitePhpBandedOption":{"type":"object","description":"One `php.ini` directive a customer may change. The staff-only band never appears here — those directives are the isolation boundary between tenants on shared hardware.","required":["name","band","kind","default","value","choices","cap","cap_raised_by_support","description"],"additionalProperties":false,"properties":{"name":{"type":"string"},"band":{"type":"string","enum":["capped","free"],"description":"`capped` is bounded by the site's plan; `free` has no plan gate."},"kind":{"type":"string","enum":["bytes","int","seconds","bool","enum","text"]},"default":{"type":"string"},"value":{"type":"string","nullable":true,"description":"`null` when the site is **inheriting** the default rather than having set it — a different fact from setting it to the same text, and the only one of the two that survives a change of the platform default."},"choices":{"type":"array","items":{"type":"string"}},"cap":{"type":"string","description":"The highest value this site's plan allows, in the directive's own notation (`1G`, `600`). Empty for a `free` directive."},"cap_raised_by_support":{"type":"boolean","description":"Whether a staff override is what makes `cap` bigger than the plan's own ceiling. `docs/204` §7a requires an override to be visible to the customer; this is that."},"override_expires_at":{"type":"string","format":"date-time","nullable":true,"description":"When the support override lapses. Every override expires."},"description":{"type":"string","description":"The machine's own sentence about this directive, empty when it publishes none. ⛔ Deliberately not a translated label of ours: a per-directive string would be a computed i18n key family AND twenty-five sentences to keep true as PHP changes, and it would silently mislabel a control that still wrote the right key the first time CloudLinux altered one."}}},"SitePhpConfig":{"type":"object","description":"A site's changeable `php.ini` settings, as the machine that runs the site describes them. `supported: false` with an empty list is a real answer — the hosting may publish none — and `reason` says which silence it is, because \"this hosting has no such feature\" and \"we have not built it\" look identical as an empty list and need different responses from the reader.","required":["supported","reason","options"],"additionalProperties":false,"properties":{"supported":{"type":"boolean","description":"Whether this site's hosting publishes changeable PHP settings."},"reason":{"type":"string","description":"Why there are none, in words a customer can act on. Empty when `supported` is true."},"options":{"type":"array","items":{"$ref":"#/components/schemas/SitePhpOption"}},"moved_to_plan_settings":{"type":"array","description":"Directives the vendor publishes but whose legal range is OUR policy, so they are returned by `getSitePhpSettings` (with the plan's cap) instead of here. Named rather than silently dropped, so a reader can tell \"the vendor stopped publishing it\" from \"we moved it\". The selector caps `memory_limit` at 512M while the `starter` tier allows 1024M, so rendering the vendor's range made the customer's own entitlement unreachable (D14362).","items":{"type":"string"}}}},"SitePhpConfigUpdate":{"type":"object","description":"The **complete** set of overrides to apply. An omitted name is cleared; `{}` resets every setting to the machine's defaults.","required":["values"],"additionalProperties":false,"properties":{"values":{"type":"object","additionalProperties":{"type":"string","maxLength":255},"example":{"memory_limit":"256M","max_execution_time":"60"}}}},"SitePhpExtension":{"type":"object","required":["name","tier","enabled","locked","why","expiry_note","confirmed"],"additionalProperties":false,"properties":{"name":{"type":"string"},"tier":{"type":"integer","description":"`0` a site is broken or insecure without · `1` market expectation, always on · `2` optional, the customer's per-site choice. Tier 3 is never offered."},"enabled":{"type":"boolean","description":"Whether the extension is loaded. Once the site has been applied this is what the **box** reported; before that it is what the catalogue intends — see `confirmed`."},"confirmed":{"type":"boolean","description":"`true` when `enabled` is a measurement read back from the machine, `false` when the site has never been applied and the row is still the catalogue's intention. Tier 0/1 rows used to be hard-coded `enabled: true` regardless of the box, which reported 13 absent extensions as present on a live site (D14360)."},"locked":{"type":"boolean","description":"Tier 0/1 (always on, not a choice), or a Tier 2 extension PHP itself has removed on this version."},"why":{"type":"string","description":"One sentence on what it is for."},"expiry_note":{"type":"string","description":"Set when PHP is removing the extension — `imap` is unbundled from 8.4. A toggle that says why it is going beats one that silently disappears at the next bump."}}},"SitePhpOption":{"type":"object","description":"One `php.ini` setting, described by the machine so a client can render the right control and validate against what will actually be accepted.","required":["name","kind","default","value","choices","description"],"additionalProperties":false,"properties":{"name":{"type":"string","example":"memory_limit"},"kind":{"type":"string","description":"The machine's own vocabulary for how to render it — `bool`, `list` (choose from `choices`) or `value` (free text).","example":"list"},"default":{"type":"string","description":"What the machine uses when the site sets nothing.","example":"128M"},"value":{"type":["string","null"],"description":"The site's override, or `null` when it is **inheriting** the default. Not flattened to the default's text: setting `128M` and inheriting `128M` are different facts, and only the first survives a change of the platform default.","example":"256M"},"choices":{"type":"array","description":"The legal values when `kind` is `list`; empty otherwise.","items":{"type":"string"},"example":["64M","128M","192M","256M","368M","512M"]},"description":{"type":"string","description":"The machine's own sentence explaining the setting."}}},"SitePhpSettings":{"type":"object","description":"A site's PHP extensions, its changeable `php.ini` settings with the plan's ceilings, and its LVE resource tier — `docs/204` §5, §7 and §7b.","required":["php_version","extensions","ini","lve","applied_at"],"additionalProperties":false,"properties":{"php_version":{"type":"string","description":"The alt-php version this site runs, dotted (`8.3`). Empty if unset."},"extensions":{"type":"array","items":{"$ref":"#/components/schemas/SitePhpExtension"}},"ini":{"type":"array","items":{"$ref":"#/components/schemas/SitePhpBandedOption"}},"lve":{"$ref":"#/components/schemas/SiteLveState"},"applied_at":{"type":"string","format":"date-time","nullable":true,"description":"When these settings were last confirmed by the machine. `null` means they have never been pushed — a different fact from \"pushed and matched\", and the only one of the two that needs an engineer."}}},"SitePhpSettingsUpdate":{"type":"object","description":"The **complete** desired state. An omitted key is left alone; an omitted *member* of a key that IS present is cleared.","additionalProperties":false,"properties":{"extensions":{"type":"array","description":"The Tier 2 extensions to have enabled. Naming a Tier 0/1 extension is a `422` rather than a silent no-op, and naming a Tier 3 one is a `422` too — filtering them would report success for something that did not happen.","items":{"type":"string"}},"ini":{"type":"object","description":"The `php.ini` overrides to have set. Values are strings, as PHP reads them.","additionalProperties":{"type":"string"}}}},"SitePhpVersion":{"type":"object","description":"A site's current PHP version and the versions it may switch to.","required":["version","available"],"properties":{"version":{"type":"string","description":"The site's effective PHP version (its own, or its line's default).","example":"8.3"},"available":{"type":"array","description":"Versions the site may switch to — those offered for its product line, plus its own current version even if that has since been retired (grandfathered).","items":{"type":"string"}},"applied":{"type":"boolean","description":"Whether the machine serving this site was actually told, and the change read back off it. Present on the `PUT` response only. `false` is not a failure: it means the site has no machine yet, so the version is recorded as desired state and provisioning will carry it. Before this field existed both outcomes shared a byte-identical `202` body, so a switch that reached nothing was indistinguishable from one that reached a box."}}},"SitePhpVersionUpdate":{"type":"object","description":"The PHP version to switch a site to.","required":["version"],"properties":{"version":{"type":"string","maxLength":8,"description":"A version offered for the site's product line (or the site's current one).","example":"8.4"}}},"SitePlanChangeResult":{"type":"object","description":"What the plan change actually did. ⛔ Stated from what happened rather than from what was asked for: `package_type` is read back from the vendor after the move, and `charged_minor` is what the gateway captured.","required":["plan_code","plan_version_id","package_type","subscription_id","order_id","charged_minor","credited_minor","quote"],"additionalProperties":false,"properties":{"plan_code":{"type":"string","description":"The plan the site is now on."},"plan_version_id":{"type":"string","description":"The priced version the subscription now carries."},"package_type":{"type":"string","description":"The vendor package type, read back after the move."},"subscription_id":{"type":"string","description":"The subscription that was moved."},"order_id":{"type":"string","description":"The order the charge was raised against, or `\"\"` when the change resulted in a credit and no order was minted."},"charged_minor":{"type":"integer","minimum":0,"description":"What was actually taken, in minor units."},"credited_minor":{"type":"integer","minimum":0,"description":"What was actually returned as account balance, in minor units."},"quote":{"allOf":[{"$ref":"#/components/schemas/SitePlanQuote"}],"description":"The quote the change was performed against."}}},"SitePlanChoices":{"type":"object","description":"Every plan a site could move to, priced, with each refusal already applied.","required":["current","options","changeable","reason","shared_with","coverage"],"additionalProperties":false,"properties":{"choose_plan_code":{"type":"string","description":"`getSitePlanChoices` only. The plan a \"Choose a plan\" on this site opens: the entry plan of the application the site runs (a Moodle site on Application Hosting answers `app_moodle_pro`), when that plan is on sale on the site's own line. Empty when the site runs no mapped application; the client then uses its line's trial plan. s1014 PLANFIX: the line default sent a Moodle trial site to Joomla."},"current":{"allOf":[{"$ref":"#/components/schemas/SitePlanOption"}],"nullable":true,"description":"The plan the site is on now. Null when the site's package type matches no plan in our catalogue, which is a real state and not an error."},"options":{"type":"array","description":"The plans the site could move to, each already scored.","items":{"$ref":"#/components/schemas/SitePlanOption"}},"changeable":{"type":"boolean","description":"Whether the surface is open at all for this site."},"reason":{"type":"string","description":"Why the whole surface is closed, as a **code** — `subscription_not_live` when the governing subscription is cancelled or expired and so is not a sale to change, `renewal_unpaid` when that subscription owes an unpaid renewal (pay first: pay it, then change plan), `no_eligible_plan` when nothing in the catalogue is a legal move. Empty when it is open.\n\n⛔ `shared_subscription` is **retired** and this field never carries it again. It closed the surface whenever a subscription covered more than one site, which is what a multi-site plan IS, so a customer on PBN 25 had no upgrade path at all and was routed to support to buy something we were willing to sell. A plan covering several sites is now changed for all of them together; `coverage` says which."},"shared_with":{"type":"integer","minimum":0,"description":"How many sites OTHER than this one draw on the same plan. Retained for clients written against the old refusal, and now derived from `coverage.sites` so the count and the list cannot disagree. It is a fact about the plan, no longer a reason for anything."},"coverage":{"allOf":[{"$ref":"#/components/schemas/SitePlanCoverage"}],"nullable":true,"description":"The sites this plan covers and the slots they use. Null only when the site has no governing subscription to read."}}},"SitePlanCoverage":{"type":"object","description":"What a plan covers — the sites drawing on it and the room left.\n\n⛔ `slots_total` and `slots_free` are nullable, and null is **never** an allowance of zero. Never draw a meter against a null and never substitute `0` — treating an unknown allowance as zero is what put `141 of 0 used` on a customer's plan page.\n\n⛔⛔ And a null has **two** meanings, which `slots_unlimited` separates: with it `false` the plan states no site limit and the ceiling is unknown; with it `true` there is no ceiling at all. Rendering one sentence for both is the same §2.44 defect one field over. A `slots_total` of **0** is a real ceiling, not an unknown — `boards_*` and `managed_database` plans entitle no hosting sites deliberately.","required":["sites","slots_total","slots_used","slots_free","slots_unlimited","hosts_sites"],"additionalProperties":false,"properties":{"sites":{"type":"array","description":"Every site the governing subscription entitles, in a stable order. Scoped to sites that actually hold entitlements — a `failed`, `deleting` or `deleted` row holds no package and is excluded, because failed rows accumulate for ever and a count including them decays upward every month.","items":{"$ref":"#/components/schemas/SitePlanCoverageSite"}},"slots_total":{"type":"integer","nullable":true,"minimum":0,"description":"The plan's `max_sites`, or null when it states none."},"slots_used":{"type":"integer","minimum":0,"description":"Sites drawing on the plan. Always a real count."},"slots_free":{"type":"integer","nullable":true,"minimum":0,"description":"Room left, or null when there is no stated allowance to have room in."},"slots_unlimited":{"type":"boolean","description":"True when the plan sells **unlimited** sites. ⛔ A THIRD state, not a synonym for a null `slots_total`: `slots_total: null, slots_unlimited: false` means *the plan states no site limit and we do not know the ceiling*, while `slots_total: null, slots_unlimited: true` means *there is no ceiling*. Those are different sentences a customer acts on differently. Neither draws a meter."},"hosts_sites":{"type":"boolean","description":"False when the subscription's product line hosts no sites at all (a Zinn® Ads plan): no purchasable plan on that line grants a site slot, this plan grants none and no site draws on it. The client then shows neither the slot line nor the boost-one-site door, which are hosting copy. Decided from the line's own catalogue, never a plan or line code; true on every hosting plan."}}},"SitePlanCoverageSite":{"type":"object","description":"One site a plan covers.","required":["site_id","name","primary_domain","product_line","status","is_current","line_mismatch"],"additionalProperties":false,"properties":{"site_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"primary_domain":{"type":"string","description":"The domain the customer types. **Empty while a site is still provisioning** — do not fall back to `name`, which would render a link to a hostname that does not resolve."},"product_line":{"type":"string","description":"This site's OWN product line, which may differ from the plan's."},"status":{"type":"string"},"is_current":{"type":"boolean","description":"True for the site whose page this is, so the list can mark it rather than making the customer match a hostname against the address bar."},"line_mismatch":{"type":"boolean","description":"True when this site's product line differs from the governing plan's — a mainstream site on a PBN plan, for instance. Surfaced rather than filtered: it is why a storage card can show two lines' numbers (one resource resolved from the plan, another from the site's line default), and a customer is better served seeing it than by a list that quietly omits most of their sites."}}},"SitePlanOption":{"type":"object","description":"One catalogue plan, already scored against this site. A refusal is a **code**, never a sentence: the engine sends no prose a customer reads, because it would be one language on every screen that renders it (§2.7).","required":["plan_code","plan_name","plan_version_id","package_type","package_type_label","price_minor","currency","interval","direction","eligible","blocked_reason","blocked_detail","losing","quote"],"additionalProperties":false,"properties":{"plan_code":{"type":"string","description":"The plan's code in our catalogue."},"plan_name":{"type":"string","description":"The plan's name as the catalogue publishes it."},"plan_version_id":{"type":"string","description":"The priced version of the plan, and what `changeSitePlan` names. A plan code is not enough: prices are versioned, and the customer agreed to a version."},"package_type":{"type":"string","description":"The vendor package type this plan resolves to, or `\"\"` when it names none — which is **every plan on our own fleet** (#2271), where there is no vendor template and the plan is its entitlement set. A client must not read `\"\"` as an error or as \"unknown\": it is the ordinary value on the platform that carries 79 of the 122 live plan versions."},"package_type_label":{"type":"string","description":"The package type's own label, or `\"\"` when the type is unknown to us."},"price_minor":{"type":"integer","description":"The plan's period price in minor units."},"currency":{"allOf":[{"$ref":"#/components/schemas/CurrencyCode"}],"description":"The currency the price and the quote are stated in."},"interval":{"type":"string","description":"The billing interval the price is for.","example":"month"},"direction":{"type":"string","enum":["upgrade","downgrade","same"],"description":"Where this plan sits relative to the site's current one. `same` is the plan the site is already on: it is listed and marked, and never eligible, because a \"change\" to the same package type would mint an order for nothing."},"eligible":{"type":"boolean","description":"Whether `changeSitePlan` would accept this option."},"blocked_reason":{"type":"string","description":"Why it is not eligible, as a **stable code** the client localises — `no_price`, `no_package_type`, `unknown_package_type`, `different_target`, `platform_mismatch`, `usage_exceeds`, `account_over_limit`. Empty when the option is eligible, and empty for the plan the site is already on.\n\n⛔ `usage_exceeds` and `account_over_limit` are **two different refusals and are deliberately not merged** (#2089). `usage_exceeds` is about **this site** and is read live from the vendor — too many databases, FTP accounts or subdomains for the target package type. `account_over_limit` is about **the whole account** and is read from stored rows — too many sites, mailboxes, mailbox storage or disk for the plan being applied, anywhere in the org's subtree. The customer's next action differs: the first is fixed on this site's screen, the second may mean deleting a different site entirely. Collapsing them would send somebody to look in the wrong place."},"blocked_detail":{"type":"object","description":"The numbers behind `usage_exceeds` **and** `account_over_limit`, keyed by the limit's identifier, each with `in_use` and `allowed`. Empty for every other reason. It exists so the screen can say *which* limit and by how much, rather than \"you are using too much\".\n\n⛔ For an account-wide limit that is **per-site** (`disk_gb`, `mysql_databases`, `ftp_users`, `subdomains` are pushed to each package, so several sites can breach the same limit at once) the entry carries the **worst** breach rather than an arbitrary one, so two identical requests do not report different numbers depending on row order. The refusal from `changeSitePlan` names every breached site.","additionalProperties":{"type":"object","additionalProperties":{"type":"integer"}}},"losing":{"type":"array","description":"Capabilities the site has today that the target package type does not include. Stable identifiers the client localises, not prose.","items":{"type":"string"}},"quote":{"allOf":[{"$ref":"#/components/schemas/SitePlanQuote"}],"nullable":true,"description":"What this change would cost. Null for an option that is not eligible — there is no honest figure to state for a change that will be refused."}}},"SitePlanQuote":{"type":"object","description":"What a plan change costs, to the minor unit. ⛔ Every field is an integer in minor units (§2.8) — never a float, never a formatted string. `total_minor` is what will be taken and `credit_minor` is what will be returned as account balance; **at most one of them is ever non-zero**. They are reported separately rather than as one signed number because a screen that renders a negative total as a charge is a screen that took money for a refund.","required":["currency","current_price_minor","new_price_minor","unused_credit_minor","new_period_minor","net_minor","tax_minor","total_minor","credit_minor","seconds_remaining","period_end"],"additionalProperties":false,"properties":{"currency":{"allOf":[{"$ref":"#/components/schemas/CurrencyCode"}],"description":"The currency every figure below is stated in."},"current_price_minor":{"type":"integer","description":"What the site's current plan costs for a whole period."},"new_price_minor":{"type":"integer","description":"What the target plan costs for a whole period."},"unused_credit_minor":{"type":"integer","description":"The unused remainder of the period already paid for, rounded in the customer's favour."},"new_period_minor":{"type":"integer","description":"The target plan's charge for the remainder of the current period."},"net_minor":{"type":"integer","description":"The difference before tax."},"tax_minor":{"type":"integer","description":"Tax on the difference, computed for the organisation's own place of supply."},"total_minor":{"type":"integer","minimum":0,"description":"What will actually be taken. Zero when the change results in a credit."},"credit_minor":{"type":"integer","minimum":0,"description":"What will be returned as account balance. Zero when the change results in a charge."},"seconds_remaining":{"type":"integer","minimum":0,"description":"How much of the current period is left, which is what the proration divides."},"period_end":{"type":"string","format":"date-time","nullable":true,"description":"When the current period ends. Null when the subscription has no bounded period, in which case there is nothing to prorate against."}}},"SitePluginGuard":{"type":"object","required":["hits","holds","updates","integrity"],"properties":{"hits":{"type":"array","items":{"$ref":"#/components/schemas/PluginGuardHit"}},"holds":{"type":"array","description":"Plugin updates on hold for this site (its own and every site's), holding or released in the last 30 days.","items":{"$ref":"#/components/schemas/SitePluginUpdateHold"}},"updates":{"type":"array","description":"Plugin updates the platform applied or refused on this site in the last 90 days, newest first.","items":{"$ref":"#/components/schemas/PluginUpdateAttempt"}},"integrity":{"type":"array","description":"Site integrity findings (WordPress core files that are not WordPress's own, a wrong site address, or what the daily intrusion deep check found - malware files, rogue administrators, injected content, attacker hooks), open or seen in the last 90 days.","items":{"$ref":"#/components/schemas/SiteIntegrityFinding"}}}},"SitePluginUpdateHold":{"type":"object","required":["id","scope","plugin","version","previous_version","state","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"scope":{"type":"string","enum":["site","fleet"],"description":"`fleet` = held on every site (released by our team only)."},"plugin":{"type":"string"},"version":{"type":"string","description":"The version that broke a site; `*` = every version."},"previous_version":{"type":"string"},"state":{"type":"string","enum":["holding","released"]},"created_at":{"type":"string","format":"date-time"},"released_at":{"type":"string","format":"date-time","nullable":true}}},"SitePreview":{"type":"object","description":"How to view a site before its DNS resolves. An empty `urls` with an `unavailable_reason` is a valid answer, not an error.","required":["urls","unavailable_reason"],"additionalProperties":false,"properties":{"urls":{"type":"array","description":"Every preview URL the platform serves for this site.","items":{"$ref":"#/components/schemas/SitePreviewUrl"}},"unavailable_reason":{"type":"string","description":"Why there is no usable preview URL, blank when there is one. A stable machine identifier the client localises — never display text.","enum":["","unsupported_driver","none_issued","not_needed"],"example":"none_issued"}}},"SitePreviewUrl":{"type":"object","description":"One hostname at which a site is reachable before its own DNS points at us. Read from the hosting platform, never derived from the site's name.","required":["domain","host","url","vendor_branded","retires_at","platform"],"additionalProperties":false,"properties":{"domain":{"type":"string","description":"The customer's own domain that this preview host stands in for.","example":"example.co.uk"},"host":{"type":"string","description":"The preview hostname the platform serves today.","example":"example-co-uk.zinnhosting.com"},"url":{"type":"string","format":"uri","description":"The URL a customer can open. Always `https://`.","example":"https://example-co-uk.zinnhosting.com/"},"vendor_branded":{"type":"boolean","description":"True when `host` is **not** under our configured preview domain — a docs/62 §3.7 breach (no vendor-branded URL is ever shown to a customer). Reported so staff can see it; a client must never offer such a URL to a customer."},"platform":{"type":"boolean","description":"True when Zinn® mints and serves this address, false when it is the hosting vendor's own. It is the discriminator for everything a client says about the address's lifetime: a platform address is withdrawn a fortnight after the customer's own domain starts reaching us, and is re-issued automatically if their DNS later moves away again; a vendor address does neither.","example":true},"retires_at":{"type":"string","format":"date-time","nullable":true,"description":"When this address will be withdrawn, or `null` while nothing is counting down.\n\n⛔ `null` means two different things and a client must not collapse them. On a **vendor** address it means the address never expires. On a **platform** address it means the customer's own domain is not reaching us yet, so the countdown has not started — the correct sentence there is \"until your domain points at us\", never \"expiry unknown\". Read `platform` to tell them apart.","example":"2026-09-22T09:00:00Z"}}},"SitePreviewWrite":{"type":"object","required":["branch"],"properties":{"branch":{"type":"string","maxLength":255,"description":"The branch to build as a preview. Must not be the branch the site already serves — that would be a normal deploy."}}},"SiteProDiscount":{"type":"object","additionalProperties":false,"required":["terms","offer","state"],"properties":{"terms":{"$ref":"#/components/schemas/ProDiscountTerms"},"offer":{"type":"object","nullable":true,"additionalProperties":false,"properties":{"product":{"type":"string"},"name":{"type":"string"}}},"state":{"type":"string","enum":["not_offered","not_eligible","available","active","redeemed","unavailable"],"description":"`unavailable` means the store could not be reached just now — try again; it is never the customer's fault and never names a vendor."},"code":{"allOf":[{"$ref":"#/components/schemas/ProDiscountCode"}],"nullable":true}}},"SiteProDiscountRequest":{"type":"object","additionalProperties":false,"required":["plugin"],"properties":{"plugin":{"type":"string","description":"The free plugin whose upgrade card is asking.","example":"tranzly"},"action":{"type":"string","enum":["status","issue"],"default":"status"},"locale":{"type":"string","example":"de_DE"}}},"SiteProtectedDirectory":{"type":"object","description":"One password-protected folder on a site. ⛔ It carries **no password and no way to obtain one** — see `SiteProtectedDirectoryCreated`.","required":["directory","username"],"additionalProperties":false,"properties":{"directory":{"type":"string","description":"The folder, relative to the document root.","example":"/staging"},"username":{"type":"string","description":"The name a visitor types to get in.","example":"preview"}}},"SiteProtectedDirectoryCreated":{"type":"object","description":"A newly protected folder **and its password, returned exactly once**. The password is generated by this platform when the caller supplies none, is written to no record of ours, appears in no log line, and cannot be read back by any endpoint.\n\nThe whole response is therefore a credential. A client displays it once and does not cache it, store it in a query cache, put it in a URL, or include it in an error report.","required":["directory","password"],"additionalProperties":false,"properties":{"directory":{"allOf":[{"$ref":"#/components/schemas/SiteProtectedDirectory"}],"description":"The folder, exactly as `getSiteProtection` will report it."},"password":{"type":"string","description":"The password, shown once. Deliberately carries no example — a documented example of a credential field is the shape people copy. ⛔ It never contains a colon: this value is written into an `.htpasswd` file where `:` is the field separator."}}},"SiteProtection":{"type":"object","description":"Every protection control for one site, from one vendor conversation: the country rule, the address block list, the hotlink rules and the password-protected folders, each with the flag saying whether the package type permits it at all.\n\nThe permission flags travel with the state so a screen never offers a control whose request is already known to be refused.","required":["countries","countries_allow_only","blocked_addresses","visitor_blocking_permitted","hotlink_configured","hotlink_allow_direct","hotlink_allowed_hostnames","hotlink_redirect_url","hotlink_extensions","hotlink_permitted","directories","password_protection_permitted","malware_scan_permitted"],"additionalProperties":false,"properties":{"countries":{"type":"array","description":"The countries in the rule, as ISO 3166-1 alpha-2 codes.","items":{"type":"string"},"example":["CN","RU"]},"countries_allow_only":{"type":"boolean","description":"⛔ `true` means `countries` is an **allow**-list: only those countries reach the site. Its own field rather than a mode string, because inverting it inverts who can reach the customer's site and a free-form word invites each consumer to re-derive that."},"blocked_addresses":{"type":"array","description":"The blocked addresses and CIDR ranges, canonicalised — what is here is what is in force, not what was typed.","items":{"type":"string"},"example":["203.0.113.7"]},"visitor_blocking_permitted":{"type":"boolean","description":"Whether the package type permits blocking visitors at all. One flag governs both lists."},"hotlink_configured":{"type":"boolean","description":"Whether any hotlink rule exists. ⛔ `false` means *no rules have been set up* — **not** \"protection is on with no allowed hosts\", which would read as a site blocking everybody."},"hotlink_allow_direct":{"type":"boolean","nullable":true,"description":"Whether a request with no referrer is allowed through. **Null** when the vendor did not state it — distinct from `false`, because a toggle rendered from an unknown lies about the site's current state.","example":true},"hotlink_allowed_hostnames":{"type":"array","description":"The sites permitted to embed these files.","items":{"type":"string"},"example":["cdn.example.com"]},"hotlink_redirect_url":{"type":"string","description":"Where a refused request is sent instead, or `\"\"` when it is simply refused.","example":""},"hotlink_extensions":{"type":"array","description":"The file extensions the rule covers, normalised without a leading dot.","items":{"type":"string"},"example":["jpg","png"]},"hotlink_permitted":{"type":"boolean","description":"Whether the package type includes hotlink protection."},"directories":{"type":"array","description":"The password-protected folders. ⛔ Read from a vendor field that documents `null` as *\"the request could not complete\"* — the opposite of \"nothing is protected\" — so an unreadable answer is an error here and never an empty list. Rendering it empty would tell a customer their folder is public **and**, because the write replaces the whole set from that list, drop every existing protection on the next save.","items":{"$ref":"#/components/schemas/SiteProtectedDirectory"}},"password_protection_permitted":{"type":"boolean","description":"Whether the package type includes password-protected directories."},"malware_scan_permitted":{"type":"boolean","description":"Whether the package type includes the vendor's malware scan — the capability behind `scanSite` on this deploy target."}}},"SiteProviderChoice":{"type":"object","description":"The choice available for one provider category. When `managed` is true the platform selects the vendor and does not disclose which — `vendors` is then empty, and a client must render no picker rather than a disabled one.","required":["managed","vendors"],"properties":{"managed":{"type":"boolean","description":"The platform chooses the **vendor**, and does not disclose which; `vendors` is then empty and a client renders no picker rather than a disabled one.\n\n⛔ It is `false` on every line today, including Footprint-Free (owner ruling, 2026-09-09). A Footprint-Free customer chooses the CDN vendor exactly as V1 let them; what stays ours and undisclosed is **which account** of that vendor their site lands on, which is where the footprint actually comes from. Naming the vendor costs none of it — a `dig` reveals it in a second — while naming the account would defeat the rotation the line is sold on. The field remains because a future line may genuinely not offer the choice.","example":false},"vendors":{"type":"array","description":"Vendor keys with a usable account serving this organization.","items":{"type":"string","maxLength":64},"example":["bunnycdn","cdn77"]}}},"SiteProviderOptions":{"type":"object","description":"What this organization may choose from when creating a site: the CDN and DNS vendors, the application stacks, and the content sources. Vendor keys only — no account identifiers, labels or counts, and nothing about any other tenant's placement.\n\n`stacks` and `sources` are served rather than compiled into a client because both are properties of *this deployment*: a stack is offerable only once a blueprint ships for it, and a source is offerable only once something can build from it. A client that carried its own list would offer options the create call then refuses.","required":["product_line","cdn","dns","stacks","stack_target","sources","deploy_targets","wordpress_theme"],"properties":{"product_line":{"type":"string","description":"The product line the answer was computed for (echoed from the query).","maxLength":64,"example":"mainstream"},"cdn":{"$ref":"#/components/schemas/SiteCdnChoice"},"dns":{"$ref":"#/components/schemas/SiteDnsChoice"},"stacks":{"type":"array","description":"The `stack_type` values that can actually be provisioned on `stack_target` — those with a published blueprint AND runnable where the plan places the site. The vendor one-click catalogue exists only on a resold target, and the applications we install ourselves only on our fleet; a stack absent here is a `422` on create with `code: STACK_NOT_ON_TARGET` on `stack_type`.","items":{"$ref":"#/components/schemas/StackType"},"example":["php","static","wordpress"]},"stack_target":{"type":"string","maxLength":32,"description":"The deploy target `stacks` was computed for — where a site created now with the same `product_line` and `subscription_id` would be placed.","example":"fleet"},"sources":{"type":"array","description":"The `source` values a site can actually be built from. `migrate` and `wayback` appear only where the import workflows are deployed; elsewhere offering them would create a site with no content and no error.\n\n⛔ `site_blueprint` is always present and is **not a starting point a customer picks from a list** — it is what a create carrying `site_blueprint_id` records. A client that offered it as a third radio beside `blueprint` would be showing two controls for one decision; the blueprint picker is the control.","items":{"$ref":"#/components/schemas/SiteSource"},"example":["blueprint","site_blueprint"]},"wordpress_theme":{"type":"object","required":["modes"],"description":"The answers this product line accepts for a new WordPress site's theme. `default` installs nothing (WordPress's own default theme in the current release), `choose` is `theme` on `POST /v1/sites`, and `random` is `random_theme` — offered on Footprint-Free only. Served from the same rule the create enforces.","properties":{"modes":{"type":"array","items":{"type":"string","enum":["default","choose","random"]},"example":["default","choose","random"]}}},"deploy_targets":{"type":"array","description":"The edge hosts this organization can point a new site at — its own connected provider accounts, sold through the extra-externally-hosted-sites add-on.\n\n**Every** edge host appears, including the ones this organization cannot use right now, each carrying why. A picker that hid an unavailable target could not tell a customer that connecting an account or buying a slot would unlock it, and the add-on is offered nowhere else in the create flow.\n\n⛔ This list is about **your own** accounts. Which of our platforms your plan places you on — the fleet, or a resold package — is not in it and is not a choice; see `deploy_target` on `SiteCreate`.","items":{"$ref":"#/components/schemas/SiteDeployTargetOffer"}}}},"SiteProviderRefusal":{"type":"object","required":["kind","code","vendor"],"properties":{"kind":{"type":"string","enum":["name_refused","not_registered","held_elsewhere","hostname_taken","subdomain_refused","certificate_refused"],"description":"Why the provider refused, as a catalogue key the client localises (`sites.providerRefused.reason.<kind>`)."},"code":{"type":"integer","nullable":true,"description":"The provider's own error number where it has one (Cloudflare 1097, 1061, ...)."},"vendor":{"type":"string","maxLength":64,"description":"The refusing vendor - only when it is the one the customer chose for this site (CLAUDE.md §2.57); `\"\"` when the platform chose it, and the client says \"the network this site was set up on\".","example":"cloudflare"}}},"SiteProvisioningRetry":{"type":"object","description":"The outcome of asking for a failed site to be built again.","required":["site_id","status","restarted"],"additionalProperties":false,"properties":{"site_id":{"type":"string","format":"uuid"},"status":{"type":"string","description":"The site's status after the call — `provisioning` on both outcomes.","example":"provisioning"},"restarted":{"type":"boolean","description":"`true` when this call moved the row and queued a build; `false` when the site was **already** provisioning, which is a success and not a conflict.\n\n⛔ Its own field rather than derived from `status`: after a successful retry and after a no-op retry the status is the same word, and the two produce different sentences on screen.","example":true},"refusal":{"type":"string","nullable":true,"enum":["in_flight"],"description":"Why nothing was restarted, as a machine key: `in_flight` when a build is already running (a second press while one is in flight is never a second workflow). `null` when `restarted` is `true`."}}},"SiteProvisioningRetryRequest":{"type":"object","description":"Optional. Name another network to rebuild on (R42): validated exactly as `createSite` validates the same two fields. Only for a `failed` site; omitted, the build is retried on the same network.","properties":{"cdn_vendor":{"type":"string","maxLength":64,"example":"bunnycdn"},"dns_vendor":{"type":"string","maxLength":64,"example":"bunny_dns"}}},"SiteQuota":{"type":"object","required":["disk_used_mb","disk_limit_mb","inodes_used","inodes_limit","db_used_mb","db_limit_mb","disk_allowance_gb","inodes_allowance","disk_allowance_authority","inodes_allowance_authority"],"properties":{"disk_used_mb":{"type":"integer","nullable":true,"description":"Disk in use, in MB, that counts toward the limit. Null when the platform reports no figures. Our own WordPress plugins are not included (see `own_plugins_mb`)."},"own_plugins_mb":{"type":"integer","nullable":true,"description":"MB held by our own WordPress plugins on this site, which do NOT count toward the disk limit (owner ruling 2026-10-01). Only a plugin folder whose files are exactly a build we published is counted here; a folder merely named like one of ours counts toward the limit as usual. The enforced ceiling is raised by this amount so the room is real. Null when not measured."},"own_plugins_inodes":{"type":"integer","nullable":true,"description":"Files and directories of our own WordPress plugins on this site, which do NOT count toward the file (inode) limit. Same verification as `own_plugins_mb`."},"own_plugins":{"type":"array","items":{"type":"string"},"description":"The plugin folders that were verified as ours and are not counted."},"disk_limit_mb":{"type":"integer","nullable":true,"description":"The enforced disk ceiling in MB, or null when no cap is enforced. On our fleet this is the hard limit `setquota` applies — the number at which the kernel starts refusing writes, not the soft warning threshold."},"inodes_used":{"type":"integer","nullable":true,"description":"Files and directories in use that count toward the limit (our own WordPress plugins are not included; see `own_plugins_inodes`)."},"inodes_limit":{"type":"integer","nullable":true,"description":"The enforced inode ceiling, or null when none is. A site can exhaust this while well under its disk cap — a WordPress install with a large media library or an unbounded cache directory is the usual way — and the failure looks like a disk error to the customer, which is why it is reported separately."},"db_used_mb":{"type":"integer","nullable":true,"description":"Total size of the site's database, in MB."},"db_limit_mb":{"type":"integer","nullable":true,"description":"The site's database allowance in MB (W43-78). No server can hold a database to a size, so this is NOT a ceiling written to the box: it is the per-site limit the platform sweeps against, freezing the site when it is exceeded (400 MB on the PBN line, V1 parity). `null` when the site has no database limit row, or the platform reports no quota for it at all."},"disk_allowance_gb":{"type":"integer","nullable":true,"description":"What the site's plan **grants**, in GB — as opposed to `disk_limit_mb`, which is what the box is enforcing right now. They agree on a healthy site; a gap between them is the only visible sign that the quota write did not run or did not finish, which is why both are reported.\nThree states, never two (#2458): **`-1` means UNLIMITED** — a promise the plan makes, which a surface must say out loud; a positive integer is a real ceiling; and **`null` means nobody stated one**, which is not an offer of anything. Never zero. This field described `-1` as `null` until 2026-08-16, which left 44 live plans — 42 of them the Footprint-Free line — rendering \"no limit set\" on a product sold as Unlimited."},"inodes_allowance":{"type":"integer","nullable":true,"description":"The file-and-directory allowance the site's plan grants. Null when the plan states none — which is **every managed hosting plan**, because this platform models no inode limit at any level, so a surface renders it as *not applicable* rather than as a number. On our own fleet it is a real, kernel-enforced ceiling and the matching `inodes_limit` should equal it."},"disk_allowance_authority":{"type":"string","enum":["plan","per_site"],"description":"**Who decides this site's disk ceiling**, and therefore how to read a gap between `disk_allowance_gb` and `disk_limit_mb` (D10470).\n`plan` — the plan's grant is authoritative, so a gap means the quota write has not landed: something is pending and the customer should expect it to resolve. `per_site` — the plan does not state this dimension for this site, so a gap is **normal and permanent**, not a pending job. Owner ruling 2026-08-16: on our own fleet disk and inodes are per-site resources set per site, regardless of how many site slots a plan carries.\n⛔ Without this field a surface cannot tell the two apart, and the Storage card told every customer the first story — offering a wait and then a support ticket for a system working exactly as ruled. Read live on production before this existed."},"inodes_allowance_authority":{"type":"string","enum":["plan","per_site"],"description":"The same question for the file-and-directory ceiling. See `disk_allowance_authority`; the two are answered by one predicate so the write path and this read path cannot drift (#2542)."}}},"SiteQuotaDowngradeRequest":{"type":"object","required":["target"],"properties":{"target":{"type":"number","minimum":0,"description":"The new ceiling, in the resource's sold unit. Refused with `422` when the site is currently using more than this, or when its usage cannot be read."}}},"SiteQuotaResource":{"type":"object","description":"One metered per-site resource: what it is allowed, what it is using, when the ceiling next drops, and what one more step costs.","required":["resource","unit","step","base","granted","total","unlimited","used","percent","measured_at","reverts_at","warn_at_percent","price_minor","price_currency","price_interval"],"properties":{"resource":{"type":"string","enum":["disk","inodes","bandwidth","database"]},"unit":{"$ref":"#/components/schemas/SiteQuotaUnit"},"step":{"type":"integer","description":"One purchasable step, in `unit`. A customer buys N of these, never an arbitrary size."},"base":{"type":"number","nullable":true,"description":"The site's own allowance, copied from the product line's admin-set default when the site was provisioned. `null` means this site has no limit row yet — it has not been through provisioning since the per-site model landed, not that it is uncapped."},"granted":{"type":"number","description":"Extra from grants live right now — staff gestures and purchased upgrades, added together."},"total":{"type":"number","nullable":true,"description":"The effective ceiling — `base + granted`. `null` when `base` is null."},"unlimited":{"type":"boolean","description":"`true` when this allowance has no ceiling. `base` and `total` are then the raw sentinel `-1` (never a quantity, never unit-converted), `percent` is `null` and no price is offered: there is nothing to add, and an upgrade is refused with `already_unlimited` before anything is charged."},"used":{"type":"number","nullable":true,"description":"Measured usage. `null` means **unknown** — the box was unreachable, or nothing has sampled it yet — and never `0`. A client must render those differently."},"percent":{"type":"integer","nullable":true,"description":"Usage as a whole percentage of `total`, or `null` when either is unknown."},"measured_at":{"type":"string","format":"date-time","nullable":true,"description":"When the box was last asked. **Render the age.** A bar drawn from a two-day-old reading looks identical to one drawn a minute ago, and the customer cannot tell."},"reverts_at":{"type":"string","format":"date-time","nullable":true,"description":"When the ceiling next **drops**, because a temporary grant expires. `null` when no live grant has an expiry. A customer whose limit is about to fall needs to know before it does."},"warn_at_percent":{"type":"array","items":{"type":"integer"},"description":"The thresholds at which the platform notifies the customer, ascending."},"price_minor":{"type":"integer","nullable":true,"description":"Cost of ONE step, in integer minor units of `price_currency`, NET of tax. `null` means no price is published in the caller's currency — the client must then show no upgrade control rather than one that cannot complete."},"price_currency":{"type":"string","nullable":true},"price_interval":{"type":"string","nullable":true,"enum":["monthly","yearly"]}}},"SiteQuotaResources":{"type":"object","required":["frozen","frozen_over_slots","resources"],"properties":{"frozen_over_slots":{"type":"boolean","description":"Whether the platform has restricted this site because it was moved in while its plan had no free site slot (row 1107#13). It lifts by itself within about ten minutes of an upgrade, an added slot or a deleted site. Like `frozen`, it is never \"is this site restricted\": a site held by the malware ladder answers false."},"frozen":{"type":"boolean","description":"Whether the platform has restricted this site **for being over a quota**. It is deliberately not \"is this site restricted\": that rung is shared with the malware and abuse ladders, and a client must not offer \"buy more space to fix this\" to a customer whose site is held for phishing."},"resources":{"type":"array","items":{"$ref":"#/components/schemas/SiteQuotaResource"},"description":"Only resources this site's driver can actually enforce. Empty on a managed hosting package, where the disk ceiling belongs to the package type and inodes do not exist."},"object_storage":{"description":"This site's object storage (an LMS Moodle site's course files over 1 MB, a files site's store) against its allowance, or null when the site keeps nothing on object storage. Comes with the plan (`object_storage_gb` / `files_object_gb`) or a staff override. At 100% new files stay on the site's own disk; nothing is deleted.","oneOf":[{"$ref":"#/components/schemas/SiteObjectStorage"},{"type":"null"}]}}},"SiteQuotaUnit":{"type":"string","description":"The unit a quota's figures are expressed in, as a **code the client localises** — never a word to render raw. `GB` for disk and bandwidth, `files` for inodes, `MB` for the database.\n\n⛔ This was an unconstrained `type: string` until 2026-08-20, and the dashboard interpolated it verbatim into four translated strings. On an Arabic RTL screen a signed-in customer read the Arabic for \"Add 50,000\" followed by the English word `files` — an English word inside a translated sentence (#3379, §2.19). The enum exists so the frontend can pin its label set to the spec: adding a unit here turns `dashboard/src/i18n/computedKeys.test.ts` red, which is the pairing that stops a hand-kept map drifting back into raw output.","enum":["GB","files","MB"]},"SiteQuotaUpgradeRequest":{"type":"object","required":["steps"],"properties":{"steps":{"type":"integer","minimum":1,"maximum":1000,"description":"How many purchasable steps to add."}}},"SiteRename":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":200,"minLength":1,"description":"The site's display name, trimmed. The only editable field."}}},"SiteRenameFailure":{"type":"object","required":["domain","reason"],"properties":{"domain":{"description":"The domain the failed change was moving to, or null when unknown.","oneOf":[{"$ref":"#/components/schemas/Hostname"},{"type":"null"}]},"reason":{"type":"string","enum":["dns_never_pointed","certificate_not_issued","domain_in_other_dns_account","our_side"]},"dns_record":{"description":"Only for `domain_in_other_dns_account`: the record the customer adds at their own DNS host so the domain reaches the site; null otherwise.","oneOf":[{"$ref":"#/components/schemas/RenameDnsRecord"},{"type":"null"}]}}},"SiteRenameStatus":{"type":"object","required":["site_id","waiting_for","waiting_for_certificate","dns_record","failed"],"properties":{"site_id":{"$ref":"#/components/schemas/Uuid"},"waiting_for":{"oneOf":[{"$ref":"#/components/schemas/Hostname"},{"type":"null"}],"description":"The domain the change is waiting for, or null."},"waiting_for_certificate":{"oneOf":[{"$ref":"#/components/schemas/Hostname"},{"type":"null"}],"description":"The domain whose certificate the change is securing before it switches, or null. The site still answers on its current domain while this is set. Only ever set when the domain resolves to us (`domain_state` is `getting_certificate`); a run whose name does not reach us reports it in `waiting_for` instead."},"domain_state":{"description":"The live state of the domain the change is attaching (`waiting_for` or `waiting_for_certificate`), read from public DNS (cached 60 s); null when no change is in progress. `nameservers_elsewhere` and `no_address_record` name the customer's next step; `not_attached` never appears here (the change is the attach).","anyOf":[{"$ref":"#/components/schemas/DomainAttachState"},{"type":"null"}]},"dns_record":{"oneOf":[{"$ref":"#/components/schemas/RenameDnsRecord"},{"type":"null"}]},"pointed_by_us":{"type":"boolean","description":"True when the platform writes `dns_record` itself once the domain's delegation is live: the domain is registered with us, we hold its DNS zone, its DNS is not managed externally, and it is delegated to that zone (or its registrar nameservers are already our expected pair while the delegation goes live). False for a name whose DNS is hosted elsewhere (for example its own Cloudflare account) even when it is registered with us: the customer adds the record there. Always false when nothing is waiting."},"failed":{"description":"Set when the site's latest domain change ended without moving the site (its primary domain is still the current one; the saga's undo is best effort); null otherwise. `reason` is a machine key the client explains: `dns_never_pointed` (the new name was not pointed at the site within the waiting period: the customer can fix their DNS and try again), `certificate_not_issued` (no certificate for the new name could be issued, so the site never switched: the customer can check the name's DNS and try again), `domain_in_other_dns_account` (the domain is held in a DNS account that is not ours and its nameservers do not point at us: the customer keeps their own DNS, adds `failed.dns_record` there and tries again; not a platform fault) or `our_side` (any other failure: contact support).","oneOf":[{"$ref":"#/components/schemas/SiteRenameFailure"},{"type":"null"}]}}},"SiteRepo":{"type":"object","required":["site_id","provider","owner","repo","full_name","branch","build_mode","build_command","output_dir","publish_branch","auto_deploy","webhook_url","webhook_registered","last_delivery_at","last_delivery_note","connected_account"],"properties":{"site_id":{"$ref":"#/components/schemas/Uuid"},"provider":{"type":"string","description":"The git provider — `github` or `gitlab`. A machine identifier."},"owner":{"type":"string","description":"The account or namespace the repository lives under."},"repo":{"type":"string"},"full_name":{"type":"string","description":"`owner/repo`, or just the repo when the account owns its namespace."},"branch":{"type":"string","description":"The branch a push deploys from."},"build_mode":{"$ref":"#/components/schemas/BuildMode"},"build_command":{"type":"string","description":"Blank in `publish` mode — a stored command nothing runs would read as a build."},"output_dir":{"type":"string","description":"Which directory is published. Blank means the repository root."},"publish_branch":{"type":"string","description":"Where CI commits the built output in `ci` mode."},"auto_deploy":{"type":"boolean","description":"Whether a push deploys automatically. Off still records every delivery, so a customer can watch pushes arriving before letting us act on them."},"webhook_url":{"type":"string","description":"The URL the provider was told to deliver to. Computed, never stored — a stored copy would keep naming the origin that was current when the row was written. Blank on an environment with no public origin configured."},"webhook_registered":{"type":"boolean","description":"Whether a provider-side hook actually exists. False here with a connection present means pushes are NOT being watched."},"last_delivery_at":{"type":["string","null"],"format":"date-time","description":"When the provider last delivered anything, or null for NEVER. Null is the single most useful diagnostic on this screen: \"connected but never delivered\" is what a mis-scoped token looks like, and it is otherwise invisible on both sides."},"last_delivery_note":{"type":"string","description":"What we did with the last delivery, including when we ignored it. Written for every delivery, because \"never delivered\" and \"delivering, ignored\" are different problems with different fixes."},"connected_account":{"type":"string","description":"The label of the credential connection this repository is read with."}}},"SiteRepoSync":{"type":"object","description":"A site's two-way git sync — the settings, where it stands, and its recent runs. Every field that means \"never\" is null rather than a zero or an empty string, because \"enabled but never run\" is the diagnostic that tells a customer their token is scoped wrong and it is invisible from anywhere else.","required":["site_id","enabled","available","state","runs"],"properties":{"site_id":{"type":"string","format":"uuid"},"enabled":{"type":"boolean","description":"Whether the customer has switched two-way sync on."},"available":{"type":"boolean","description":"Whether it is permitted at all — true only once the customer has connected their OWN git account. False here makes `enabled` irrelevant; the engine will not sync either way."},"unavailable_reason":{"type":"string","nullable":true,"description":"A sentence the customer reads when `available` is false. Null when it is available."},"subdir":{"type":"string","description":"Which directory of the site syncs. Empty means the whole document root."},"state":{"type":"string","enum":["idle","synced","conflict","adopt","error","unsupported"],"description":"`unsupported` is TERMINAL and is not a failure either: the site is served from its repository, so there are no separate files on our side to push back. It leaves the sweep's rotation rather than being retried, and rejoins if the site's hosting changes.\n\n`conflict` and `adopt` are HELD, not failed — the sync stopped on purpose and is waiting for the customer to choose a side."},"branch":{"type":"string"},"repository":{"type":"string","nullable":true,"description":"`owner/repo`, or null when no repository is connected."},"conflict_commit":{"type":"string","nullable":true,"description":"The commit in the repository that we have not seen — the one the customer needs to look at before choosing. Null unless held."},"last_sync_at":{"type":"string","format":"date-time","nullable":true},"last_sync_note":{"type":"string","nullable":true},"runs":{"type":"array","description":"The most recent runs, newest first. Includes the no-ops.","items":{"$ref":"#/components/schemas/SiteRepoSyncRun"}}}},"SiteRepoSyncResolve":{"type":"object","required":["keep"],"properties":{"keep":{"type":"string","enum":["site","repository"],"description":"`site` keeps this site's files and commits them on top of the repository's current tip. `repository` discards the unsynced changes on our side and takes the repository's version — destructive, and offered only after the customer has been shown both commits."}}},"SiteRepoSyncRun":{"type":"object","description":"One sync run. Recorded for every run, including refusals and no-ops.","required":["id","direction","state","changed","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"direction":{"type":"string","enum":["push","pull"]},"state":{"type":"string","enum":["idle","synced","conflict","adopt","error","unsupported"]},"changed":{"type":"integer","description":"How many paths moved. Zero with `state: synced` means \"checked, nothing had changed\" — the commonest run, and stored rather than skipped so a live sync and a dead one do not look identical."},"commit":{"type":"string","nullable":true},"remote_commit":{"type":"string","nullable":true},"note":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"SiteRepoSyncWrite":{"type":"object","required":["enabled"],"properties":{"enabled":{"type":"boolean"},"subdir":{"type":"string","maxLength":255,"description":"Restrict the sync to one directory of the site. Empty syncs the whole document root, which for a WordPress site is usually not what the customer wants."}}},"SiteRepoWrite":{"type":"object","required":["provider","repo"],"additionalProperties":false,"properties":{"provider":{"type":"string"},"owner":{"type":"string"},"repo":{"type":"string"},"branch":{"type":"string","default":"main"},"build_mode":{"$ref":"#/components/schemas/BuildMode"},"build_command":{"type":"string","description":"One line. In `ci` mode the repository's own CI runs it. In `publish` mode it is refused (nothing would run it), except on an application site on our fleet (Node, Python or Ruby, Developer Hosting), where every deploy runs it as the site's own user inside the release before the switch (docs/715 section 5)."},"output_dir":{"type":"string"},"publish_branch":{"type":"string","default":"zinn-build"},"auto_deploy":{"type":"boolean","default":true}}},"SiteReportBrandInput":{"type":"object","description":"The agency's look on this client's report and e-mail (the plugin's white label), and the client's own logo.","properties":{"name":{"type":"string","maxLength":120},"agency_name":{"type":"string","maxLength":160},"website":{"type":"string","maxLength":255},"colour":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"accent":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"intro":{"type":"string"},"footer":{"type":"string"},"from_name":{"type":"string","maxLength":120},"reply_to":{"type":"string","format":"email"},"logo":{"type":"string","description":"Base64 PNG/JPEG/WebP, at most 256 KB decoded; empty string removes it, absent keeps it."},"client_logo":{"type":"string","description":"The client's own mark, same rules."}}},"SiteReportClientInput":{"type":"object","description":"The site's client and schedule. ⛔ No `domains`: the site's own host is always the one domain.","properties":{"name":{"type":"string","maxLength":160},"recipients":{"type":"array","maxItems":10,"items":{"type":"string","format":"email"}},"locale":{"type":"string"},"sections":{"type":"array","items":{"$ref":"#/components/schemas/ClientReportSectionKey"}},"contact_name":{"type":"string","maxLength":160},"cadence":{"$ref":"#/components/schemas/ClientReportCadence"},"send_email":{"type":"boolean"},"narrative":{"type":"boolean"},"active":{"type":"boolean"}}},"SiteReports":{"type":"object","description":"Zinn® SEO stage P12 — everything the connected site's Reports screen shows, for THIS site's client only.","required":["site","client","brand","allowance","sections","sections_with_data","reports","sinks","portal_links","app_reports_url","app_agency_url"],"properties":{"site":{"type":"string","description":"The site's bare host — the only domain its report names."},"client":{"oneOf":[{"$ref":"#/components/schemas/ClientReportClient"},{"type":"null"}]},"brand":{"oneOf":[{"$ref":"#/components/schemas/ClientReportBrand"},{"type":"null"}]},"allowance":{"$ref":"#/components/schemas/ClientReportAllowance"},"sections":{"type":"array","items":{"$ref":"#/components/schemas/ClientReportSectionKey"}},"sections_with_data":{"type":"array","items":{"$ref":"#/components/schemas/ClientReportSectionKey"}},"reports":{"type":"array","maxItems":12,"items":{"$ref":"#/components/schemas/ClientReport"}},"sinks":{"type":"array","items":{"$ref":"#/components/schemas/ClientReportSink"}},"portal_links":{"type":"array","items":{"$ref":"#/components/schemas/ClientPortalLink"}},"app_reports_url":{"type":"string","format":"uri","description":"The app's Reports screen (every client)."},"app_agency_url":{"type":"string","format":"uri","description":"zs-422: the agency overview of every connected site in the app."}}},"SiteRequestCost":{"type":"object","description":"One line of a request's breakdown — what consumed the time.","required":["name","kind","duration_ms","percent","calls","query","location"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"The plugin, extension, PHP function or database call.","example":"litespeed-cache"},"kind":{"type":"string","description":"What sort of cost this is. ⛔ `other` is a deliberate fall-through: a new CloudLinux row type must degrade to a rendered row, never to a failed screen.","enum":["wordpress_plugin","php_extension","php_function","database_query","other"]},"duration_ms":{"type":"integer","description":"Milliseconds spent here, summed across every call site.","example":554},"percent":{"type":"number","format":"double","description":"Share of the request's total time.","example":24.73},"calls":{"type":"integer","description":"How many times it was called.","example":5},"query":{"type":"string","description":"The SQL, for a `database_query` row — with its literal values already replaced by the vendor. Empty for every other kind.","example":"SELECT option_name FROM wp_options WHERE autoload IN ( 'xxx' )"},"location":{"type":"string","description":"`file:line` of the call site, relative to the site's own document root. Empty when there is no PHP file behind it (an extension has none).","example":"wp-includes/class-wpdb.php:2351"}}},"SiteRestoreRequest":{"type":"object","required":["backup_id"],"additionalProperties":false,"properties":{"backup_id":{"allOf":[{"$ref":"#/components/schemas/Uuid"}],"description":"The backup to restore. Always named explicitly — there is no \"restore the latest\", because a destructive operation must not depend on which row happens to sort first."}}},"SiteRuntimeSecurity":{"type":"object","description":"What our runtime sensor saw **happen** on this site, and whether anything was watching it at all. The malware fields above are a verdict on files at rest; this is the other half — a process opening a sensitive file, clearing a log, or making an outbound connection it should not.\n\n⛔ `available: false` means **we were not looking**, and a client must render it as *not monitored* — never as *clear*. Our sensor is enrolled per server, so a site on a server we have not yet enrolled has the same *nothing* to report as a site nothing has ever attacked. Showing \"no attacks detected\" over the first case is a clean bill of health nobody earned.\n\n⛔ **Every other field is absent when `available` is false**, deliberately: a `total` of `0` is a number about a measurement that never happened, and a zero is exactly what a reader — human or model — turns into \"your site is quiet\".\n\n`recent` is capped; `shown` says how many of `total` are in it, so a truncated list can never be read as the whole one.","required":["available"],"properties":{"available":{"type":"boolean","description":"Whether the sensor on this site's server has reported in recently. False means no statement about attacks on this site can be made in either direction, and no other field is present."},"sensor_host":{"type":"string","description":"The server whose sensor answers for this site; empty when we cannot say which. This is **our** hostname, not the site's origin, so it discloses nothing about the customer's footprint."},"total":{"type":"integer","minimum":0,"description":"Every detection held for this site, not just the ones in `recent`."},"shown":{"type":"integer","minimum":0,"description":"How many of `total` are present in `recent`."},"recent":{"type":"array","description":"The most recent detections, newest first.","items":{"$ref":"#/components/schemas/RuntimeDetectionSummary"}}}},"SiteScheduledTask":{"type":"object","description":"One scheduled task (cron job) on a site. `source: panel` is managed here (panel, API, MCP); `source: crontab` is a line added over SSH, listed read-only.","required":["id","name","kind","target","schedule","command","enabled","email_output","paused_reason","source","site_id","site_domain"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"A UUID for a managed task; a 16-character id for a crontab line.","example":"01a11760-2553-7196-acae-ec179099437f"},"name":{"type":"string","description":"The name the customer gave it (empty for a crontab line).","example":"Send newsletter"},"kind":{"type":"string","enum":["command","php","url","wpcron"],"description":"`command` a shell command; `php` a .php file in the site folder run with the site's PHP version; `url` open an http(s) address; `wpcron` WordPress's due events."},"target":{"type":"string","description":"The command, the script path or the address (empty for `wpcron`).","example":"scripts/nightly.php"},"schedule":{"type":"string","description":"Five fields, UTC, as written to the crontab. A `*/N` minute field is moved to a fixed offset inside its window, so this can differ from what was sent.","example":"7-59/15 * * * *"},"command":{"type":"string","description":"The command line for a `command` task (the old field); empty otherwise."},"enabled":{"type":"boolean","description":"Whether the customer has it switched on."},"email_output":{"type":"string","description":"Where each scheduled run's output is mailed, or `\"\"`."},"paused_reason":{"type":"string","description":"`staff` when our team switched it off; `\"\"` otherwise."},"source":{"type":"string","enum":["panel","crontab"]},"site_id":{"type":"string"},"site_domain":{"type":"string","description":"Filled on the account-wide list."}}},"SiteScheduledTaskList":{"type":"object","description":"A site's scheduled tasks and the limits behind `can_create`.","required":["data","limit","permitted","can_create","used","limit_per_site","limit_per_org","used_in_org","kinds","unavailable_reason","min_interval_minutes"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SiteScheduledTask"}},"limit":{"allOf":[{"$ref":"#/components/schemas/VendorAllowance"}],"description":"The per-site ceiling, in the shape older clients read."},"permitted":{"type":"boolean","description":"Whether this site may have scheduled tasks at all: the plan includes them AND the account is a paying one (trials and unpaid accounts are refused, s1014 row 85)."},"unavailable_reason":{"type":"string","enum":["","plan","not_paying"],"description":"Why `permitted` is false. `plan` = the plan excludes scheduled tasks; `not_paying` = a trial or an account with no payment yet (create, enable and run now answer `422` with `refusal.cron.paidOnly`; existing jobs are written off on the server until the account pays, never deleted). Empty when permitted."},"can_create":{"type":"boolean","description":"`permitted`, and both the site and the account have room."},"used":{"type":"integer","description":"Managed tasks on this site."},"limit_per_site":{"type":"integer","example":20},"limit_per_org":{"type":"integer","example":500},"used_in_org":{"type":"integer"},"kinds":{"type":"array","items":{"type":"string","enum":["command","php","url","wpcron"]},"description":"What this site may run."},"min_interval_minutes":{"type":"integer","example":5}}},"SiteScheduledTaskRun":{"type":"object","required":["status","exit_code","started_at","finished_at","duration_seconds","trigger","output"],"additionalProperties":false,"properties":{"status":{"type":"string","enum":["ok","failed","timeout","skipped","running"]},"exit_code":{"type":"integer"},"started_at":{"type":"string","format":"date-time","nullable":true},"finished_at":{"type":"string","format":"date-time","nullable":true},"duration_seconds":{"type":"integer","nullable":true},"trigger":{"type":"string","enum":["schedule","manual"]},"output":{"type":"string","description":"The first 1,000 and last 7,000 bytes of the run's output."}}},"SiteScheduledTaskRunList":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SiteScheduledTaskRun"}}}},"SiteScheduledTaskWrite":{"type":"object","description":"The fields of a task. On create, `name`, `kind` and `schedule` are expected (`kind` defaults to `command` and `name` to \"Scheduled task\" for older clients that send only `schedule` + `command`). On update, only the fields given change.","additionalProperties":false,"properties":{"name":{"type":"string","maxLength":80,"example":"Send newsletter"},"kind":{"type":"string","enum":["command","php","url","wpcron"]},"target":{"type":"string","maxLength":1000,"description":"The command (one line), the .php path inside the site folder, or the address.","example":"scripts/nightly.php"},"command":{"type":"string","maxLength":1000,"description":"The old field — the same as `target` for a `command` task."},"schedule":{"type":"string","maxLength":128,"description":"Five fields `minute hour day-of-month month day-of-week`, UTC, or @hourly, @daily, @weekly, @monthly, @yearly. At most once every 5 minutes.","example":"30 2 * * 1-5"},"email_output":{"type":"string","description":"An address to mail each scheduled run's output to, or empty for none.","example":"ops@example.com"},"enabled":{"type":"boolean","description":"Switch the task on (default) or off."}}},"SiteSecurity":{"type":"object","description":"A site's malware state as its owner sees it (see `getSiteSecurity`) — the stored projection a scan writes, never a live vendor call.","required":["status","last_scan_at","detections","recent_resolutions","can_rescan","last_scan_error_code","unavailable_reason","runtime"],"properties":{"status":{"$ref":"#/components/schemas/MalwareStatus"},"last_clean_at":{"type":["string","null"],"format":"date-time","description":"When the platform last cleaned or quarantined malware on this site automatically or on *Clean now*. `null` = never needed to."},"clean_failed_at":{"type":["string","null"],"format":"date-time","description":"Since when a clean has been **failing** (a finding the platform could neither clean nor move aside, such as an infected `wp-config.php`). `null` = not failing. Only this lets the platform restrict a site for malware."},"last_scan_at":{"type":["string","null"],"format":"date-time","description":"When a scan last **completed**. `null` = never scanned. A scan that failed does not stamp this, so a stale success can never be mistaken for a fresh one."},"detections":{"type":"array","items":{"$ref":"#/components/schemas/MalwareDetection"}},"recent_resolutions":{"type":"array","maxItems":5,"description":"Findings that were present and are not any more, most recently cleared first — the record of the protection having worked, which an all-clear alone cannot show.\n\n`resolved_at` alone means **the finding is gone**, not that we removed it: it is stamped when a later scan's complete set no longer contains the finding, which is equally true if the customer deleted the file or a deploy replaced it. Read `resolution` for the attribution — only `scanner_removed` licenses a client to say we took it away.","items":{"$ref":"#/components/schemas/ResolvedMalwareDetection"}},"can_rescan":{"type":"boolean","description":"Whether `rescanSite` will accept a request for this site: false while a scan is already running, false for a site that is not running at all (there is no document root to scan), and false where the platform cannot be scanned.\n\nNote it is **not** false merely because `unavailable_reason` is set: a site whose scanner has simply never been wired up can still be re-tried, and a retry is what picks up an operator attaching one."},"last_scan_error_code":{"type":"string","enum":["","scan_conflict","scanner_unreachable","scanner_missing","scan_failed"],"description":"Why a scan that **ran** could not finish; empty when none has failed. Non-empty means an attempt was made against this site and broke — an unreachable host, a vendor error, a scan abandoned after timing out — so the site was not scanned, which is deliberately distinguishable from a clean result.\n\nA stable machine identifier for the client to localise, never a sentence, exactly like `unavailable_reason`. `scan_conflict` — a scan was already running, so this is not a fault and a client should say so calmly rather than alarmingly; `scanner_unreachable` — the host or vendor could not be reached; `scanner_missing` — we reached the host and no scanner is installed on it; `scan_failed` — anything else, claiming only that an attempt was made and did not finish.\n\n⛔ **This replaced a field that carried the driver's raw message**, which put the upstream vendor's hostname, our reseller package number and a worker host's IP address in front of the tenant, in English, in a UI sold in 58 languages. The raw text is retained for staff on `SecurityOverviewRow.last_scan_error`.\n\n⛔ **Empty when no attempt was made.** \"Nothing is set up to scan this site\" is `unavailable_reason`, never this field: a client renders this one as a warning (\"we tried to check your site and could not\"), and saying that about an attempt that never happened tells a customer their site might be infected when nothing of the sort is known. The two are never both non-empty."},"unavailable_reason":{"type":"string","description":"Why **no scan was attempted**; empty when one was. A stable machine identifier for the client to localise, never a sentence and never a vendor name.\n\n`vendor_unsupported` — the hosting platform this site runs on cannot be scanned by us at all yet; `can_rescan` is false and `rescanSite` answers `422`. `scanner_not_configured` — the platform can be scanned but nothing is attached to scan *this* site yet; a retry is still accepted. `mail_only` — this domain is ours for **mailboxes only**; there is no website here, so there is nothing to scan and there never will be. `can_rescan` is false.\n\n⛔ `mail_only` is the one value a client must render as **nothing at all** rather than as a notice. The other two describe unfinished wiring of ours and a customer is owed them; this one describes a mailbox, where any malware verdict — including a reassuring one — is a statement about a website that does not exist. The dashboard hides the whole card on it. It still travels on the wire so staff can tell \"excluded deliberately\" from \"we never looked\".\n\nThis is a neutral statement about our wiring, not a warning about the customer's site: a client must not render it in the same alarming style as `last_scan_error_code`."},"runtime":{"$ref":"#/components/schemas/SiteRuntimeSecurity"}}},"SiteSeoSettings":{"type":"object","required":["cadence","providers","visible_metrics","paused","funding","available_metrics"],"properties":{"cadence":{"type":"string","enum":["daily","every_other_day","weekly"],"description":"How often this site is checked. Checks may not run more often than every 12 hours."},"providers":{"type":"array","items":{"type":"string"},"description":"Which providers to ask, by name. Empty means \"whichever of my connected keys can answer\", which is the sensible setting for an account with one key."},"visible_metrics":{"type":"array","items":{"type":"string"},"description":"Which metrics to render for this site. Empty means show everything available. A display choice only — hidden metrics are still measured and their history kept."},"available_metrics":{"type":"array","items":{"type":"string"},"description":"Every metric the currently-funded provider can supply for this site. The set a client should offer as toggles; a metric outside it cannot be shown however it is configured, because no connected provider produces it."},"paused":{"type":"boolean","description":"When true nothing is checked and nothing is spent. History is kept, and settings are restored untouched when it is switched back on."},"funding":{"type":"string","enum":["own_key","platform","none"],"description":"Who pays for this site's checks. `own_key` — your own connected key and your own quota, free here. `platform` — Zinn®'s accounts, under your plan or add-on. `none` — nothing can run; see `reason`."},"vendor":{"type":"string","description":"The provider actually serving this site, when one is."},"reason":{"type":"string","nullable":true,"enum":["no_key_connected","own_key_unusable","reseller_addon_required","not_entitled","not_in_good_standing"],"description":"Why no check can run, when `funding` is `none`. `own_key_unusable` means a key is stored but could not be used — usually revoked or out of quota at the provider, and Zinn® deliberately does **not** silently fall back to its own paid data in that case."}}},"SiteSeoSettingsUpdate":{"type":"object","properties":{"cadence":{"type":"string","enum":["daily","every_other_day","weekly"]},"providers":{"type":"array","items":{"type":"string"}},"visible_metrics":{"type":"array","items":{"type":"string"}},"paused":{"type":"boolean"}}},"SiteSeoSummary":{"type":"object","description":"One site's row-sized SEO answer: is it in the index, and how much authority does it have. Both halves are entitlements sold on the Footprint-Free line (`indexing_checks`, `majestic_metrics`), and each reports `not_entitled` on its own — a plan may include one and not the other.\n\n⛔⛔ **Never conflate a state with a value.** `unknown` is our provider failing, not the customer's site being deindexed; `never_checked` is us not having got there yet. Rendering either with the same badge as `not_indexed` turns a vendor outage into a fleet-wide \"your sites have been deindexed\" alarm, which on a PBN triggers exactly the panicked rebuild this feature exists to prevent. The same applies to the metrics: `trust_flow: 0` is the provider measuring zero, `null` is nobody having looked, and only the first is a reason to drop a domain.","required":["index_state","seo_state","index_is_stale","seo_is_stale"],"properties":{"index_state":{"type":"string","enum":["indexed","not_indexed","unknown","never_checked","not_entitled"],"description":"`indexed` / `not_indexed` are measurements. `unknown` is a provider that could not answer. `never_checked` is a site the sweep has not reached. `not_entitled` is a plan that does not include index checks — a statement about the offer, not the site, and the client should say so rather than showing an empty cell.","example":"indexed"},"index_checked_at":{"description":"When the index reading was taken; null unless `index_state` is a reading.","anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"index_is_stale":{"type":"boolean","description":"True when the stored index reading is older than its refresh window. **False when there is no reading at all** — an empty cell has no age to warn about. (The single-site payload reports `true` there instead, where it means \"a refresh is worth its cost\"; on a list it means \"the number beside me is old\".)","default":false},"seo_state":{"type":"string","enum":["measured","not_in_index","never_fetched","not_entitled"],"description":"`measured` means the provider answered with numbers, **including all zeroes**. `not_in_index` means it has never seen this domain — not a measurement of zero authority. `never_fetched` means the monthly sweep has not reached this site. `not_entitled` means the plan does not include authority metrics.","example":"measured"},"seo_measured_at":{"description":"When the authority reading was taken; null unless there is one.","anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"seo_is_stale":{"type":"boolean","description":"True only when the next reading is genuinely **OVERDUE** — never merely because the last one is old.\n\n⛔⛤ Authority is re-measured every 30 days, and this field used to be computed from the 24-hour cache TTL, so every healthy site reported `true` for 29 days in every 30 and the whole column read as broken (W39-N, D18960). A reading 12 days into a 30-day cadence is the product working. Clients should show the age and `seo_next_due_at` always, and the stale treatment only on this flag.","default":false},"trust_flow":{"description":"Trust Flow, 0-100. **Null means the provider did not supply it**; `0` means it measured zero. Only present when `seo_state` is `measured`.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}],"example":24},"citation_flow":{"description":"Citation Flow, 0-100. Null when not supplied; `0` is a measurement.","anyOf":[{"type":"integer","minimum":0,"maximum":100},{"type":"null"}],"example":31},"referring_domains":{"description":"Distinct domains linking here. Null when not supplied; `0` is a measurement.","anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"example":118},"external_backlinks":{"description":"Total external backlinks. Null when not supplied; `0` is a measurement. The owner asked for backlinks on the list by name (2026-09-03); before W39-N the summary did not carry the field, so the column could not have existed however it was rendered.","anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"example":4210},"seo_next_due_at":{"description":"When the sweep will next re-measure this domain. Null unless there is a reading.\n\n⭐ This is what turns an age into information. *\"Measured 12 days ago\"* invites \"so why has nothing happened?\"; *\"measured 12 days ago, next reading in 18\"* answers it. The client should render both.","anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"index_next_due_at":{"description":"When the index sweep will next check this domain, taken from the stored check rather than re-derived — the sweep owns the cadence ladder. Null when there is no reading, or when no further check is scheduled.","anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"index_previously_indexed":{"description":"The verdict of the check BEFORE the current one, so a client can say *\"was indexed, now is not\"*. Null when there is no earlier check, or when that check could not tell.","anyOf":[{"type":"boolean"},{"type":"null"}]},"seo_compared_to":{"description":"When the reading the `*_delta` fields are measured AGAINST was taken. Null when there is no comparable earlier reading.\n\n⛔ A delta with no date is unreadable — \"+4\" since yesterday and \"+4\" since March are opposite facts about a domain. A client that shows a delta must show this.","anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"trust_flow_delta":{"description":"Change in Trust Flow since the reading at `seo_compared_to`.\n\n⛔⛤ **`null` IS NOT `0`.** Null means the comparison cannot be made — a first reading, or an earlier one the provider had never seen. `0` means measured and unchanged. Rendering null as zero draws a flat line through a gap and tells the customer nothing happened, which on a PBN is a decision, not a pixel.","anyOf":[{"type":"integer"},{"type":"null"}],"example":2},"citation_flow_delta":{"description":"Change in Citation Flow since `seo_compared_to`. Null is not zero.","anyOf":[{"type":"integer"},{"type":"null"}],"example":-1},"referring_domains_delta":{"description":"Change in referring domains since `seo_compared_to`. Null is not zero.","anyOf":[{"type":"integer"},{"type":"null"}],"example":12},"external_backlinks_delta":{"description":"Change in external backlinks since `seo_compared_to`. Null is not zero.","anyOf":[{"type":"integer"},{"type":"null"}],"example":340},"domain_rating":{"description":"s1006 (owner D42) — Domain Rating by Ahrefs (https://ahrefs.com/), 0-100, on every site whatever the plan: first measured 3 days after the site is added, then monthly. Null = not measured yet or no answer — never 0. Any surface showing it must credit \"Domain Rating by Ahrefs\" (licence term).","anyOf":[{"type":"integer"},{"type":"null"}],"example":37},"domain_rating_measured_at":{"description":"When the Domain Rating was read.","anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"domain_authority":{"description":"s1014 MOZ-V2 (owner 2026-11-03) — Domain Authority by Moz (https://moz.com/), 1-100, free on every LIVE site whatever the plan: first measured 3 days after the site's own domain first reached us, then every 30 days. Null = not measured yet or Moz had no answer — never 0. Any surface showing it credits \"Domain Authority by Moz\".","anyOf":[{"type":"integer"},{"type":"null"}],"example":24},"page_authority":{"description":"Moz Page Authority of the site's homepage, 1-100, from the same reading.","anyOf":[{"type":"integer"},{"type":"null"}],"example":31},"spam_score":{"description":"Moz Spam Score, 0-100 (percent of sites with similar features Moz found penalised), from the same reading. 0 is a real, good reading; null is unmeasured.","anyOf":[{"type":"integer"},{"type":"null"}],"example":1},"moz_measured_at":{"description":"When the Moz reading was taken.","anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"SiteServer":{"type":"object","description":"Which server the site runs on (D43). `kind` decides how to label it: `fleet` — our shared server, labelled from `region` + `number` (\"Helsinki server 1\"); `own` — the customer's own server, `name` is the label they gave it; `panel` — the customer's connected control panel, `name` is its label (or host); `edge` — our static edge network; `external` — hosted elsewhere and only watched; `unplaced` — not placed on a server yet; `managed` — managed hosting described by `deploy_target`. `key` is the value for `listSites?server=`.","required":["key","kind","name","region","number","deploy_target"],"properties":{"key":{"type":"string","example":"fleet:hel1-1"},"kind":{"type":"string","enum":["fleet","own","panel","edge","external","unplaced","managed"]},"name":{"type":"string","description":"The customer's own label for an `own` or `panel` server; empty otherwise."},"region":{"type":"string","description":"The fleet server's region code; empty for every other kind.","example":"hel1"},"number":{"description":"The fleet server's number within its region — its position among the region's servers in creation order, retired ones included, so it never changes. Null for every other kind.","anyOf":[{"type":"integer","minimum":1},{"type":"null"}]},"deploy_target":{"type":"string","description":"The site's deploy target, for labelling a `managed` server."},"hostname":{"type":"string","description":"Staff responses only (`AdminSiteRow`, Customer 360) — the box's hostname."}}},"SiteServerFacet":{"allOf":[{"$ref":"#/components/schemas/SiteServer"},{"type":"object","required":["sites"],"properties":{"sites":{"type":"integer","minimum":1,"description":"How many of the matching sites are on this server."}}}]},"SiteSlowRequest":{"type":"object","description":"One real request this site served, as measured on the machine by CloudLinux X-Ray.\n\n⛔ There is deliberately no visitor IP address here. The vendor's payload carries one; it is dropped at the parse boundary and no field for it exists at any layer beneath this schema.","required":["request_id","task_id","url","path","method","duration_ms","started_at","throttled_ms","io_throttled_ms","hit_limits","has_error","error_text","cache_miss_reasons"],"additionalProperties":false,"properties":{"request_id":{"type":"integer","description":"The request's number within its tracing task. ⛔ Unique only within `task_id` — it restarts at 1 for every task.","example":277},"task_id":{"type":"string","description":"The tracing task this request belongs to.","example":"31d0d7a0d3684a46b37832e4967bba95"},"url":{"type":"string","description":"The full URL that was requested.","example":"https://example.com/shop/?s=blue"},"path":{"type":"string","description":"Just the path, for compact display.","example":"/shop/"},"method":{"type":"string","description":"HTTP method.","example":"GET"},"duration_ms":{"type":"integer","description":"How long the request took to execute, in milliseconds.","example":2242},"started_at":{"type":"string","format":"date-time","description":"When the request started."},"throttled_ms":{"type":"integer","description":"Milliseconds the account spent **stopped** because it hit its resource ceiling. Reported separately from `duration_ms`, never folded into it: this is the number that means \"the plan is too small\" rather than \"the code is slow\".","example":2358},"io_throttled_ms":{"type":"integer","description":"Milliseconds stopped at the account's disk-I/O ceiling.","example":0},"hit_limits":{"type":"boolean","description":"Whether the account hit any resource ceiling during this request."},"has_error":{"type":"boolean","description":"Whether PHP raised an error while serving it."},"error_text":{"type":"string","description":"The error, when there was one. Empty otherwise."},"cache_miss_reasons":{"type":"array","description":"Why this request could not be served from the page cache — empty when it was cacheable. Usually the entire explanation for a slow page that should be fast.","items":{"type":"string","enum":["admin","ajax","cookie","disallowed_file","mobile","preview","query_string","search","uri_rule","user_agent"]}}}},"SiteSlowRequestBreakdown":{"type":"object","description":"A traced request together with what it spent its time on.","required":["request","costs"],"additionalProperties":false,"properties":{"request":{"$ref":"#/components/schemas/SiteSlowRequest"},"costs":{"type":"array","description":"The costs, heaviest first.","items":{"$ref":"#/components/schemas/SiteRequestCost"}}}},"SiteSmartUpdateList":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SiteSmartUpdateRun"}}}},"SiteSmartUpdateRun":{"type":"object","additionalProperties":false,"description":"One smart update (docs/1135 §8).","required":["id","status","plugins","themes","diff_permille","hold_at_permille","reason","before_url","after_url","created_at","started_at","finished_at"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","running","applied","held","failed"],"description":"`applied` = the copy was clean and live was updated; `held` = the copy broke or changed too much, live untouched; `failed` = the run could not finish, live untouched."},"plugins":{"type":"array","items":{"type":"string"}},"themes":{"type":"array","items":{"type":"string"}},"diff_permille":{"type":["integer","null"],"description":"Thousandths of the page that changed on the staging copy; null when not compared."},"hold_at_permille":{"type":"integer","description":"A change above this holds the run."},"reason":{"type":["string","null"],"enum":["wp_broken","http_error","no_pictures","changed_too_much","could_not_finish",null],"description":"Why the run was held or did not finish, as a code the client words in the customer's language; null when applied or still running."},"before_url":{"type":"string","description":"Presigned picture of the copy before","or empty.":null},"after_url":{"type":"string","description":"Presigned picture of the copy after","or empty.":null},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":["string","null"],"format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"}}},"SiteSmartUpdateSchedule":{"type":"object","additionalProperties":false,"description":"A site's scheduled smart update (docs/1135 §8.1).","required":["enabled","window_weekday","window_hour","timezone","next_due_at","last_attempted_at","last_outcome","last_run_id"],"properties":{"enabled":{"type":"boolean"},"window_weekday":{"type":["integer","null"],"minimum":0,"maximum":6},"window_hour":{"type":"integer","minimum":0,"maximum":23},"timezone":{"type":"string"},"next_due_at":{"type":["string","null"],"format":"date-time","description":"When the next window starts (UTC); null when off."},"last_attempted_at":{"type":["string","null"],"format":"date-time"},"last_outcome":{"type":["string","null"],"enum":["started","current","staging_exists","in_flight","not_in_good_standing","could_not_start",null],"description":"What the last window did, as a code the client words: `started` (a run was queued, `last_run_id`), `current` (nothing to update), `staging_exists`, `in_flight`, `not_in_good_standing` (skipped, resumes when the account is settled), `could_not_start`; null = no window has come yet."},"last_run_id":{"type":["string","null"],"format":"uuid"}}},"SiteSmartUpdateScheduleInput":{"type":"object","additionalProperties":false,"required":["enabled","window_weekday","window_hour","timezone"],"properties":{"enabled":{"type":"boolean"},"window_weekday":{"type":["integer","null"],"minimum":0,"maximum":6,"description":"0 = Monday … 6 = Sunday; null = every day."},"window_hour":{"type":"integer","minimum":0,"maximum":23},"timezone":{"type":"string","maxLength":64,"description":"An IANA time zone name."}}},"SiteSmartUpdateScheduleResponse":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SiteSmartUpdateSchedule"}}},"SiteSource":{"type":"string","description":"Where a site's initial content came from (docs/04 §2).\n\n`blueprint` is a fresh site off one of our published stack recipes. `site_blueprint` is a copy of one of the **customer's own** built sites, restored from a template they captured (`GET /v1/site-blueprints`) — a different feature that unfortunately shares a word, so the two values are deliberately distinct. `migrate` and `wayback` are accepted on rows that already carry them but are only offered for creation where the import feature is enabled.","enum":["blueprint","migrate","wayback","site_blueprint"],"default":"blueprint"},"SiteSshAccess":{"type":"object","description":"A site's SSH access: the authorised keys, whether the plan includes the service at all, and whether the package restricts SSH to a list of addresses.","required":["permitted","can_create","keys","ip_allowlist","ip_restricted","ip_allowlist_editable","host","port","username","unavailable_reason"],"additionalProperties":false,"properties":{"permitted":{"type":"boolean","description":"Whether SSH may be used on this site: the package type includes it AND the account is a paying one (trials and unpaid accounts are refused, s1014 row 85)."},"unavailable_reason":{"type":"string","enum":["","plan","not_paying"],"description":"Why `permitted` is false. `plan` = the package excludes SSH; `not_paying` = a trial or an account with no payment yet. Keys stay LISTED, adding one answers `422` with `refusal.ssh.paidOnly`, and the account's login shell is locked on the server (keys kept, SFTP unaffected) until the account pays, when it is restored automatically. Empty when permitted."},"can_create":{"type":"boolean","description":"`permitted`, **and** the package has room for another key. Two fields rather than one because those are different sentences, and a single flag makes the screen say the wrong one."},"keys":{"type":"array","description":"The keys currently authorised on the package.","items":{"$ref":"#/components/schemas/SiteSshKey"}},"ip_allowlist":{"type":"array","description":"The addresses SSH is restricted to, when it is restricted.","items":{"type":"string"}},"ip_restricted":{"type":"boolean","description":"Whether an address restriction is actually in force. ⛔ **Distinct from `ip_allowlist == []` and never derived from it.** The vendor answers \"no restriction\" as null, and an empty list rendered as a restriction would tell the customer they are protected when the truth is the opposite."},"ip_allowlist_editable":{"type":"boolean","description":"Whether the allow-list can be written. False today for a **vendor** reason rather than a plan one, so a client renders the list read-only instead of an editor that cannot save."},"host":{"type":"string","description":"What the customer puts after `@`. ⛔ Before this field existed the surface managed keys for a destination it never named: a customer could add a key, see it listed, and find no host, user or port anywhere in the product. `\"\"` when the platform does not publish one — a vendor package, for instance — and a client then says so rather than rendering a plausible guess.","example":"138.199.214.127"},"port":{"type":"integer","description":"The TCP port to connect to. 22 unless a host is wired otherwise.","example":22},"username":{"type":"string","description":"The account name to log in as — the site's own system account, not the customer's email or panel login. `\"\"` when unknown.","example":"zcfb737b7d942525dae726ef04a2c4"}}},"SiteSshKey":{"type":"object","description":"One authorised public key on a site's hosting package.","required":["handle","key","algorithm","comment","managed"],"additionalProperties":false,"properties":{"handle":{"type":"string","description":"The name the key is filed under, ours and the vendor's, and what `deleteSiteSshKey` addresses. Constrained to `[A-Za-z0-9][A-Za-z0-9._-]{0,63}`.","example":"laptop-2026"},"key":{"type":"string","description":"The public key line, in full and never truncated. It is a **public** key — publishing it is what it is for — and a shortened one would stop a customer confirming that the key on the server is the one on their laptop, which is the only reason to look at this screen twice."},"algorithm":{"type":"string","description":"The key type parsed out of the line. `\"\"` when the stored line does not parse as one of the algorithms we accept, which is possible for a key added at the vendor before this surface existed.","example":"ssh-ed25519"},"comment":{"type":"string","description":"The trailing comment on the key line. Often an email address, often empty."},"managed":{"type":"boolean","description":"Whether this platform wrote the key and can therefore revoke it. `false` for a key found in a fleet account's `authorized_keys` that was added directly on the server over an earlier SSH session. ⛔ Such a key is **listed** — it can open the customer's account, and a screen that enumerates what can open their account and silently omits one is worse than no screen — but `deleteSiteSshKey` refuses it with a sentence saying why, because we did not write it and cannot name it stably. Always `true` on a vendor package, which has no such category."}}},"SiteStackState":{"type":"object","description":"What the site's SERVER actually has, read back from it — never what was requested. The fields above this one are desired state: both cache flags default to true, so a surface that renders them as fact agrees with itself whatever the server is running. That is exactly how a live site came to show \"full-page cache: on, object cache: on\" with neither installed.","required":["lscache_active","object_cache_connected","plugins_active","checked_at","notes"],"properties":{"lscache_active":{"type":"boolean","description":"The LiteSpeed Cache plugin was active on the server at `checked_at`."},"object_cache_connected":{"type":"boolean","description":"`wp cache type` answered `Redis` at `checked_at` — i.e. the object-cache drop-in is installed and connected, not merely requested."},"plugins_active":{"type":"array","items":{"type":"string"},"description":"Every plugin the server reported as active."},"checked_at":{"type":"string","format":"date-time","nullable":true,"description":"When the server was last asked. `null` means NEVER ASKED, which is a third state and must not be rendered as \"off\" — \"we have not checked\" and \"it is not there\" are different facts."},"notes":{"type":"array","items":{"type":"string"},"description":"Operator-facing reasons a requested item could not be delivered (a withdrawn plugin slug, a server with no Redis credential). Non-empty is not a failure."}}},"SiteStackUpgrade":{"type":"object","required":["site_id","stack_type","runtime","php_version"],"properties":{"site_id":{"type":"string","format":"uuid"},"stack_type":{"type":"string","example":"php"},"runtime":{"type":"string","example":"php"},"php_version":{"type":"string","example":"8.3"}}},"SiteStackUpgradeRequest":{"type":"object","additionalProperties":false,"properties":{"php_version":{"type":"string","maxLength":8,"description":"A PHP version the site's plan offers; omitted = the plan's default.","example":"8.3"}}},"SiteStatus":{"type":"string","description":"A site's lifecycle state (docs/04 §3). A newly created site is `pending` until the provisioning workflow picks it up; `deleted` is terminal.\n\n`restricted` and `quarantined` are the graduated **enforcement** rungs (docs/12 §6, #558) — states a site is put into because of a signal about it, rather than points in its own lifecycle. A `restricted` site **is still serving**: it has lost outbound mail, cron and every state-changing HTTP method (so writes, logins and checkout are refused), which is the rung a compromised site is put on while its owner cleans it. A `quarantined` site is offline **and** execution-disabled, with its files held as evidence — used for a confirmed compromise, and reached immediately for confirmed phishing.\n\n⛔ Recovery from `quarantined` lands on `restricted`, never straight on `active`: docs/12 §6 reverses quarantine after \"cleanup **and review**\", and the next clean scan completes the promotion.","enum":["pending","provisioning","active","restricted","suspended","quarantined","failed","deleting","deleted"]},"SiteStatusReason":{"type":"string","description":"Why a site is in its current status, as a **code the client localises** — never a sentence (#546). A failed site's dashboard card used to ask the customer to quote a reference that carried no reason, so they could not tell \"retry\" from \"this is ours\".\n⛔ The operator text is deliberately NOT here: the reaper's own strings name our infrastructure, and a driver's exception message in a customer response is the leak #518 identified. That detail stays in the `site.provisioning_timed_out` audit row, which staff already read. It is also what makes the reason translatable into all 58 locales (CLAUDE.md §2.19) — a sentence composed in the engine would be English for ever.\n`provisioning_not_started` — nothing ever picked the site up; `provisioning_timed_out` — a run started and stopped existing; `provisioning_failed` — the build itself failed and was rolled back. All three are retryable by the customer.","enum":["provisioning_not_started","provisioning_timed_out","provisioning_failed"]},"SiteStorage":{"type":"object","description":"Extra storage for one site (s1014 STORAGE, docs/157 §S).","required":["site_id","offered","disk","inodes","packs","offers","lapse","move"],"additionalProperties":false,"properties":{"site_id":{"type":"string","format":"uuid"},"offered":{"type":"boolean","description":"Whether extra storage is on sale to this organisation."},"disk":{"$ref":"#/components/schemas/SiteStorageUsage"},"inodes":{"$ref":"#/components/schemas/SiteStorageUsage"},"packs":{"type":"array","items":{"$ref":"#/components/schemas/SiteStoragePack"}},"offers":{"type":"array","items":{"$ref":"#/components/schemas/SiteStorageOffer"}},"lapse":{"type":"object","nullable":true,"description":"Set while a pack that ended is still in use: the site keeps its space until `deadline`, after which only new growth stops. Files are never deleted.","required":["since","deadline","growth_blocked"],"additionalProperties":false,"properties":{"since":{"type":"string","format":"date-time"},"deadline":{"type":"string","format":"date-time"},"growth_blocked":{"type":"boolean"}}},"move":{"type":"object","nullable":true,"description":"The latest \"move and add\" request for this site.","required":["status","pack_code","requested_at"],"additionalProperties":false,"properties":{"status":{"type":"string","enum":["moving","charged","failed"]},"pack_code":{"type":"string"},"requested_at":{"type":"string","format":"date-time"}}}}},"SiteStorageOffer":{"type":"object","description":"One extra storage pack on sale for this site.","required":["code","gb","inodes","price_minor","currency","first_charge_minor","renews_on","prorated","can_buy","refusal_code","refusal","move_available","move_region","plan_suggestion"],"additionalProperties":false,"properties":{"code":{"type":"string","enum":["extra_storage_10gb","extra_storage_50gb","extra_storage_100gb"]},"gb":{"type":"integer"},"inodes":{"type":"integer"},"price_minor":{"type":"integer","description":"The monthly price in the caller's currency, in minor units."},"currency":{"type":"string"},"first_charge_minor":{"type":"integer","description":"What buying it today charges — prorated to `renews_on`."},"renews_on":{"type":"string","format":"date","description":"When it first renews at `price_minor` (the plan's renewal day)."},"prorated":{"type":"boolean"},"can_buy":{"type":"boolean"},"refusal_code":{"type":"string","nullable":true,"description":"`not_on_sale`, `on_trial` (a free trial: extra storage comes with a paid plan), `not_in_good_standing`, `not_enforceable`, `no_base_limit`, `unlimited`, `box_full`, `capacity_unknown`, or null."},"refusal":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/SiteStorageRefusal"}]},"move_available":{"type":"boolean","description":"True when `box_full` and another server can take the site and the pack."},"move_region":{"type":"string"},"plan_suggestion":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/SiteStoragePlanSuggestion"}]}}},"SiteStoragePack":{"type":"object","description":"One extra storage pack this site holds.","required":["purchase_id","code","gb","inodes","renews_on","ends_on","removable","removal_refusal"],"additionalProperties":false,"properties":{"purchase_id":{"type":"string","format":"uuid"},"code":{"type":"string"},"gb":{"type":"integer"},"inodes":{"type":"integer"},"renews_on":{"type":"string","format":"date","nullable":true},"ends_on":{"type":"string","format":"date","nullable":true,"description":"The last day it counts, once its renewal was stopped."},"removable":{"type":"boolean"},"removal_refusal":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/SiteStorageRefusal"}]}}},"SiteStoragePlanSuggestion":{"type":"object","description":"A plan upgrade that gives this site the pack's space for the pack's monthly price or less (the guard that a pack never undercuts a plan upgrade).","required":["plan_code","plan_name","plan_version_id","monthly_delta_minor","pack_monthly_minor","currency","disk_mb"],"additionalProperties":false,"properties":{"plan_code":{"type":"string"},"plan_name":{"type":"string"},"plan_version_id":{"type":"string","format":"uuid"},"monthly_delta_minor":{"type":"integer","description":"What the plan costs a month more than the current one, in minor units."},"pack_monthly_minor":{"type":"integer"},"currency":{"type":"string"},"disk_mb":{"type":"integer","format":"int64","description":"The plan's per-site disk in MB (`-1` = unlimited)."}}},"SiteStorageRefusal":{"type":"object","description":"Why something cannot be done: the English `message` (for an SDK or CLI) and the catalogue `key` plus `params` the dashboard renders in the reader's language.","required":["message","key","params"],"additionalProperties":false,"properties":{"message":{"type":"string"},"key":{"type":"string","example":"refusal.storage.boxFull"},"params":{"type":"object","additionalProperties":{"type":"string"}}}},"SiteStorageUsage":{"type":"object","description":"One resource of a site (disk in MB, or files), in stored units. `limit` is `base + packs` (plus any staff grant); `-1` is unlimited and null is not provisioned.","required":["used","limit","base","packs","percent","measured_at"],"additionalProperties":false,"properties":{"used":{"type":"integer","format":"int64","nullable":true},"limit":{"type":"integer","format":"int64","nullable":true},"base":{"type":"integer","format":"int64","nullable":true},"packs":{"type":"integer","format":"int64"},"percent":{"type":"number","nullable":true},"measured_at":{"type":"string","format":"date-time","nullable":true}}},"SiteSubdomain":{"type":"object","description":"One subdomain served by a site's hosting account — a name of its own, pointing at a folder of its own inside the same package.","required":["name","document_root"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"The subdomain as the platform stored it. ⛔ Not necessarily what was requested — a vendor normalises it, and the client shows this value.","example":"blog.example.com"},"document_root":{"type":"string","description":"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 from what we intended to write.","example":"/public_html/blog"},"stack_type":{"type":"string","description":"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 blank rather than a plausible default, because inventing a fact about a platform we do not build on is one a screen cannot recover from.","example":"wordpress"},"status":{"type":"string","enum":["pending","active","failed","deleting",""],"description":"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 slot has **already** been released and the name is still being withdrawn. ⛔ Empty on a resold package — the vendor performs the change inline, so there is no build to be part-way through.","example":"active"},"status_detail":{"type":"string","description":"Why it failed, or a note about a build that partly succeeded — a sentence written for the customer. Empty on a healthy row.","example":""},"status_detail_refusal":{"type":"object","nullable":true,"description":"The catalogue form of `status_detail` when the platform wrote it: a `refusal.*` `key` plus its `params`, so the dashboard renders the note in the reader's language. Null when `status_detail` is empty or is not a sentence the platform writes (a vendor's own text) — show `status_detail` as given then.","required":["key","params"],"additionalProperties":false,"properties":{"key":{"type":"string","example":"refusal.subdomain.dnsNotOurs"},"params":{"type":"object","additionalProperties":{"type":"string"},"example":{"name":"blog.example.com"}}}}}},"SiteSubdomainList":{"type":"object","description":"A site's subdomains and its effective ceiling. ⛔ The only surface on this line with a real **quantity** limit, so `can_create` here really is arithmetic.","required":["data","limit","permitted","can_create"],"additionalProperties":false,"properties":{"data":{"type":"array","description":"The subdomains on the package.","items":{"$ref":"#/components/schemas/SiteSubdomain"}},"limit":{"allOf":[{"$ref":"#/components/schemas/VendorAllowance"}],"description":"The effective ceiling on subdomains for this site."},"permitted":{"type":"boolean","description":"Whether the package type includes subdomains at all."},"can_create":{"type":"boolean","description":"`permitted`, **and** the effective ceiling has room."},"used":{"type":"integer","minimum":0,"description":"How much of `limit` is already spent, when that is **not** `data.length`.\n\n⚖️ Present only on our own fleet, where a subdomain consumes one of the plan's `max_sites` slots (owner ruling 2026-09-01) — so what fills the ceiling is the customer's **sites as well as their subdomains**. ⛔ A client that renders *\"2 of 25 used\"* from `data.length` there would tell a customer with 24 sites and 2 subdomains that they have 23 spare, on the same screen whose create button correctly refuses them. Absent means count the rows.","example":7},"counts":{"type":"string","enum":["site_slots","subdomains"],"description":"What `used` counts, sent with it. `site_slots` on Footprint-Free and PBN (a subdomain uses one of the plan's site slots); `subdomains` on mainstream, where the ceiling is the package's subdomain allowance plus any bought `subdomains_10` packs (owner ruling 2026-11-05, 1105#32 B).","example":"subdomains"}}},"SiteTarget":{"type":"object","description":"One site, and whether it can receive a post right now (W24-I, `docs/198`).\n\n⛔⛔ `suitability` carries five values and the difference between `unsuitable` and `unknown` is load-bearing. `unsuitable` is **measured** — every adapter was asked which sites it claims and each declined. `unknown` means **we could not determine it**. A client must never render the second as the first, and must count it separately in any confirmation step.","required":["site_id","primary_domain","name","product_line","stack_type","site_status","group_ids","suitability","reason","detail","target_kind","detected_cms","capabilities","missing_capabilities","checked_at"],"properties":{"site_id":{"type":"string","format":"uuid"},"primary_domain":{"type":"string"},"name":{"type":"string"},"product_line":{"type":"string"},"stack_type":{"type":"string"},"site_status":{"type":"string"},"group_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"The site groups this site belongs to, for the picker's group filter."},"suitability":{"type":"string","enum":["ready","needs_setup","unknown","unsuitable","blocked"]},"reason":{"type":"string","description":"A machine code the client localises. One of `ok`, `site_not_active`, `no_adapter`, `no_target_configured`, `no_credential`, `no_repository`, `never_probed`, `probe_failed`, `missing_capability`. ⛔ A code **and** the sentence below, never one or the other: the code is what a filter and a facet count group by, the sentence is what the customer reads."},"detail":{"type":"string","description":"The sentence, saying what to do rather than only what happened. Rendered in English as a fallback; the client localises from `reason` where it has a key."},"target_kind":{"type":"string","enum":["","wordpress","headless_rest","git_static"]},"detected_cms":{"type":"string","description":"What the destination reported itself to be, last time it answered."},"capabilities":{"type":"array","items":{"type":"string"},"description":"Capability ids this site's target advertises — `cms_target:publish`, `cms_target:draft`, `cms_target:schedule`, `cms_target:category`, `cms_target:tag`, `cms_target:excerpt`, `cms_target:author`, `cms_target:canonical`, `cms_target:featured_image`, `cms_target:update`, `cms_target:delete`. Empty when no target is resolved. These differ per site, not per adapter: a WordPress site on our fleet can set an author and a schedule, the same site reached over REST cannot, and a static site can do neither but can carry a canonical."},"missing_capabilities":{"type":"array","items":{"type":"string"},"description":"Which of the request's `requires` this target cannot do. ⛔ Empty for a site whose capabilities are not established — claiming a site fails a requirement we never measured would turn \"we could not look\" into a product refusal."},"checked_at":{"type":"string","format":"date-time","nullable":true,"description":"When the destination was last contacted. ⛔ `null` means **never checked** and must be rendered as such, not as a fresh result."}}},"SiteTargetPage":{"type":"object","required":["items","total","offset","limit","has_more"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SiteTarget"}},"total":{"type":"integer","minimum":0,"description":"Every site matching the filters, not the page. This is the number a select-all-matching control shows."},"offset":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1},"has_more":{"type":"boolean"}}},"SiteTransfer":{"type":"object","description":"One offer to move one site from one organization to another, as either party sees it.\n\nThe row survives every outcome. A declined or expired offer is kept rather than deleted: *\"did I already send this?\"* and *\"who offered this site to whom, and when?\"* are the first two questions asked about a site that changed hands.","required":["id","site_id","direction","status","include_domain","expires_at","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"site_id":{"$ref":"#/components/schemas/Uuid"},"site_name":{"type":"string","description":"The site's name as it was when the offer was made. Snapshotted onto the offer, not read live: while a transfer is pending the site still belongs to the sender, and reading it live would make the row unreadable to the very organization that has to accept it."},"primary_domain":{"type":"string","description":"The site's domain as it was when the offer was made. Snapshotted, as above."},"direction":{"type":"string","enum":["incoming","outgoing"],"description":"From **this caller's** point of view. Computed per request, never stored — the same row is outgoing to one party and incoming to the other."},"status":{"type":"string","enum":["pending","accepted","declined","cancelled","expired","failed"],"description":"Five terminal states rather than one, because *why* an offer ended is what support is actually asked. `failed` means it was accepted and could not complete; nothing moved."},"include_domain":{"type":"boolean","description":"Whether the domain, its DNS and its mail travel with the site."},"recipient_email":{"type":"string","description":"Only populated for the **sender**. To the receiver it is their own address and carries no information; to anyone else it would be a third party's email address in a row two organizations can read."},"message":{"type":"string"},"expires_at":{"type":"string","format":"date-time","description":"An unaccepted offer expires fourteen days after it is made."},"term_ends_at":{"type":"string","format":"date-time","nullable":true},"renewal_amount_minor":{"type":"integer","format":"int64","nullable":true},"renewal_currency":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"decided_at":{"type":"string","format":"date-time","nullable":true},"failure_reason":{"type":"string","description":"Why a `failed` transfer could not complete. Empty otherwise."}},"additionalProperties":false},"SiteTransferInRequest":{"type":"object","required":["backup_id","source_site_id"],"additionalProperties":false,"properties":{"backup_id":{"allOf":[{"$ref":"#/components/schemas/Uuid"}],"description":"The backup to land on this site. It must belong to `source_site_id` and must have completed successfully."},"source_site_id":{"allOf":[{"$ref":"#/components/schemas/Uuid"}],"description":"The externally hosted site the backup was taken from. Named explicitly rather than derived from `backup_id`, so a mistyped backup id cannot silently move a different site onto this one."}}},"SiteTransferList":{"type":"object","required":["transfers","org_ids"],"properties":{"transfers":{"type":"array","items":{"$ref":"#/components/schemas/SiteTransfer"}},"org_ids":{"type":"array","description":"The caller's own organization ids — what they give to somebody transferring them a site. See `SiteTransferProposal.target_org_id` for why transfers are addressed this way.","items":{"$ref":"#/components/schemas/Uuid"}}},"additionalProperties":false},"SiteTransferPreview":{"type":"object","description":"Whether a proposed transfer would go through, and what it would take with it.","required":["allowed","message","details","include_domain","domain_names","moving_tables","staying_tables"],"properties":{"allowed":{"type":"boolean","description":"Whether the transfer would be permitted right now."},"message":{"type":"string","description":"The refusal in words, composed by the engine for API and staff-console readers. Empty when `allowed`. The dashboard renders its own localised sentences from `details[].field` and never shows this."},"details":{"type":"array","description":"One entry per reason, machine-readable. `field` is the blocker code (`unpaid_invoices`, `dunning_active`, `page_view_overage`, `bandwidth_overage`, `wholesale_statement`, `failed_payment`, `shared_subscription`, `comp_subscription`, `no_subscription`, `site_busy`, `job_in_flight`, `deletion_scheduled`, `zone_collision`) — **or** `target_account` / `source_account`, the single opaque entry standing in for a side whose financial detail this reader is not entitled to.","items":{"$ref":"#/components/schemas/ErrorDetail"}},"include_domain":{"type":"boolean"},"domain_names":{"type":"array","description":"The domains that would change hands. Read from the registrations we actually hold — a site on a domain registered elsewhere lists none, rather than naming a registration we cannot transfer.","items":{"type":"string"}},"term_ends_at":{"type":"string","format":"date-time","nullable":true,"description":"When the inherited paid term runs out. The receiver pays nothing until then."},"renewal_amount_minor":{"type":"integer","format":"int64","nullable":true,"description":"What it renews at, in minor units of `renewal_currency`."},"renewal_currency":{"type":"string","description":"The **subscription's** currency, which does not change on transfer. A locked price is already currency-locked, and converting it would silently re-price a paid term at a rate nobody agreed."},"moving_tables":{"type":"integer","description":"How many of the platform's site-attached record types would move."},"staying_tables":{"type":"integer","description":"How many would stay with the sender — traffic and usage evidence, tickets, abuse history, paid add-ons."}},"additionalProperties":false},"SiteTransferProposal":{"type":"object","description":"What a sender is proposing, before they commit to it.","required":["target_org_id"],"properties":{"target_org_id":{"allOf":[{"$ref":"#/components/schemas/Uuid"}],"description":"The **receiving organization's id**, which its owner gives to the sender.\n\n⛔ An organization id rather than an email address, and that is a privacy decision. Resolving a recipient by email would make the offer form an oracle: type an address, learn whether that person has an account with us and whether it is in good standing. An id is an unguessable UUID the receiver chooses to hand over, so consent begins before the offer does. `listSiteTransfers` returns the caller's own ids for this purpose."},"include_domain":{"type":"boolean","default":true,"description":"Whether the domain registration, its DNS zone and records, and its mail travel with the site. `false` moves the site alone and the receiver points a domain of their own at it."}},"additionalProperties":false},"SiteTransferState":{"type":"object","description":"A site's transfer state as its owner sees it: the most recent offer in any state, or `null` when the site has never been offered.","required":["offer"],"properties":{"offer":{"oneOf":[{"$ref":"#/components/schemas/SiteTransfer"},{"type":"null"}]}},"additionalProperties":false},"SiteTranslation":{"type":"object","additionalProperties":false,"description":"One site's translation state. A site that has not bought this is still a `200`, with `state: disabled` and `tier: null` — the screen renders the offer from it.","properties":{"site_id":{"$ref":"#/components/schemas/Uuid"},"state":{"type":"string","enum":["disabled","active","paused_standing","over_allowance"],"description":"⛔ `paused_standing` is its own state, not a flavour of `disabled` — the remedies differ and only one of them is the customer's to act on."},"tier":{"allOf":[{"$ref":"#/components/schemas/SiteTranslationTier"}],"nullable":true},"available_tiers":{"type":"array","description":"The ladder, so the screen never hardcodes a price.","items":{"$ref":"#/components/schemas/SiteTranslationTier"}},"word_count":{"type":"integer","description":"Translatable words measured at the last read."},"document_count":{"type":"integer"},"last_extracted_at":{"type":"string","format":"date-time","nullable":true,"description":"When we last successfully read the site. ⛔ Distinct from the attempt cursor the sweep keeps: a failed pass advances that and must not move this, or the screen would report a site as freshly read when nothing was read."},"last_error":{"type":"string","description":"Why the last pass did nothing, in words the customer can act on."},"locales":{"type":"array","items":{"$ref":"#/components/schemas/SiteTranslationLocale"}}},"required":["site_id","state","tier","available_tiers","word_count","document_count","locales"]},"SiteTranslationBundle":{"type":"object","additionalProperties":false,"properties":{"locale":{"$ref":"#/components/schemas/LocaleCode"},"documents":{"type":"array","items":{"$ref":"#/components/schemas/SiteTranslationDocument"}},"ready":{"type":"integer"},"total":{"type":"integer"}},"required":["locale","documents","ready","total"]},"SiteTranslationDocument":{"type":"object","additionalProperties":false,"properties":{"document":{"type":"string","description":"`<doc_type>:<remote_id>` — what the site matches its own post against.","example":"page:42"},"fields":{"type":"object","additionalProperties":{"type":"string"},"description":"Translated fields keyed by name (`title`, `body`, `excerpt`, `slug`). A field with no translation yet is ABSENT, never present and empty."}},"required":["document","fields"]},"SiteTranslationLocale":{"type":"object","additionalProperties":false,"properties":{"locale":{"$ref":"#/components/schemas/LocaleCode"},"name":{"type":"string","description":"The language's own name for itself, for the switcher."},"translated":{"type":"integer","description":"Strings finished in this locale."},"total":{"type":"integer","description":"Strings that exist for this site, translated or not."},"served":{"type":"boolean","description":"Whether the customer publishes this language to visitors. ⛔ Independent of `translated`: every language is translated, and a locale nobody enabled renders no URL. See the operation description."}},"required":["locale","name","translated","total","served"]},"SiteTranslationRefresh":{"type":"object","additionalProperties":false,"description":"What one re-read did. Every number is reported; none is inferred.","properties":{"documents":{"type":"integer"},"words":{"type":"integer"},"fields_registered":{"type":"integer"},"fields_retired":{"type":"integer","description":"Sources removed because the site no longer has them. Reported rather than silent: a destructive step that says nothing is indistinguishable from one that did nothing."},"skipped_not_in_good_standing":{"type":"boolean","description":"§2.46 — counted and surfaced, never silent. `documents: 0` because the account is on hold looks identical to a pass that could not see any work."},"refused":{"type":"string","description":"Why nothing was read, empty when it was."}},"required":["documents","words","fields_registered","fields_retired"]},"SiteTranslationServed":{"type":"object","additionalProperties":false,"properties":{"site_id":{"$ref":"#/components/schemas/Uuid"},"state":{"type":"string","enum":["disabled","active","paused_standing","over_allowance"],"description":"The Site Translation state; `disabled` when the site has none."},"served_locales":{"type":"array","description":"The languages this site publishes, sorted. Empty means none — never \"all\".","items":{"$ref":"#/components/schemas/LocaleCode"}}},"required":["site_id","state","served_locales"]},"SiteTranslationSourceDocument":{"type":"object","additionalProperties":false,"description":"One page, post, product, term or menu on the site.","properties":{"remote_id":{"type":"string","pattern":"^[A-Za-z0-9_.-]{1,128}$","description":"The site's own identifier, never the slug — a customer who edits a title usually edits the slug with it, and keying on the slug would discard every finished translation of that document and pay to make them again.","example":"42"},"doc_type":{"type":"string","pattern":"^[a-z0-9_-]{1,40}$","example":"product"},"url":{"type":"string","maxLength":2048,"description":"Where the document lives, for the customer's screen."},"fields":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/SiteTranslationSourceField"}}},"required":["remote_id","doc_type","fields"]},"SiteTranslationSourceField":{"type":"object","additionalProperties":false,"description":"One translatable field of one document.","properties":{"name":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,64}$","description":"Stable within its document and stored verbatim. A renamed field is a retire plus a register, and pays for the words again.","example":"meta_title"},"text":{"type":"string","maxLength":200000,"description":"The source text. A blank or whitespace-only value is dropped, not registered."},"is_html":{"type":"boolean","default":false,"description":"Translate tag-aware. True for a body or a product short description."},"is_slug":{"type":"boolean","default":false,"description":"Apply URL-safety rules instead of prose rules. True for a post or term slug — without it a translated sentence, spaces and all, would land in a live URL."}},"required":["name","text"]},"SiteTranslationSourceSubmission":{"type":"object","additionalProperties":false,"description":"A site's COMPLETE translatable inventory. Anything absent from it is retired, so a partial list deletes the translations of everything it leaves out.","properties":{"documents":{"type":"array","maxItems":2000,"items":{"$ref":"#/components/schemas/SiteTranslationSourceDocument"}}},"required":["documents"]},"SiteTranslationTier":{"type":"object","additionalProperties":false,"description":"One purchasable allowance. Every tier includes every language.","properties":{"code":{"type":"string","example":"site_translation_standard"},"label":{"type":"string","example":"Standard site"},"max_words":{"type":"integer","description":"Fair-use ceiling on translatable words across the whole site."},"price_minor":{"type":"integer","description":"Monthly price in minor units of `currency` (§2.8 — never a float), converted server-side for the caller."},"currency":{"type":"string","example":"USD","description":"The currency `price_minor` is in — **the caller's**, not the stored USD. ⛔ This field returned a hardcoded `USD` until D19222, while `GET /v1/extras` quoted the same three products converted, so one console showed one product at two prices in two currencies (measured on production: `$19.00` on the site's Translation tab against `IDR 1,042,000 / mo` on the storefront). Both endpoints now price through the same `extras.service.quoted_price` the purchase captures, so what is shown is what is billed. A currency with no stored FX rate reports `USD` rather than labelling an unconverted number with the requested symbol."}},"required":["code","label","max_words","price_minor","currency"]},"SiteTranslationUpdate":{"type":"object","additionalProperties":false,"properties":{"served_locales":{"type":"array","description":"The languages this site publishes. An empty list means none — never \"all\".","items":{"$ref":"#/components/schemas/LocaleCode"}}},"required":["served_locales"]},"SiteVisitUsage":{"type":"object","description":"One site's metered visits for the current billing period, with the organisation-wide totals they count against (#1675). The allowance belongs to the plan and is shared across every site it pays for, so the site figure is reported with its denominator — 40,000 views is unremarkable on Agency Growth and a chargeable overage on Starter.","required":["period_start","period_end","page_views","excluded_page_views","org_page_views","org_allowance","org_unlimited","org_over_limit"],"properties":{"period_start":{"type":"string","format":"date-time"},"period_end":{"type":"string","format":"date-time"},"page_views":{"type":"integer","format":"int64","description":"This site's billable human page views this period."},"excluded_page_views":{"type":"integer","format":"int64","description":"This site's page views excluded as automated."},"org_page_views":{"type":"integer","format":"int64","description":"Billable page views across every site on the plan."},"org_allowance":{"type":"integer","format":"int64","description":"The plan's allowance for this period. `-1` means unlimited."},"org_unlimited":{"type":"boolean"},"org_over_limit":{"type":"boolean","description":"Whether the plan's allowance is exceeded. The site keeps serving either way."}}},"SiteVitals":{"type":"object","description":"One site's newest homepage Core Web Vitals reading (#626). See `getSiteVitals` for why `source` must be rendered and why collection is asynchronous.\n\nMetrics are `null` and bands are `unknown` when unmeasured — never `0` and never `good`. `unknown` is a first-class value: a site nobody has measured must render differently from a site measured and found good.","required":["available","url","source","field_available","lcp_ms","cls_milli","inp_ms","ttfb_ms","fcp_ms","performance_score","accessibility_score","best_practices_score","seo_score","stack_packs","band","lcp_band","cls_band","inp_band","measured_at","opportunities","screenshots"],"properties":{"available":{"type":"boolean","description":"Whether any vitals reading exists for this site yet."},"url":{"type":"string","description":"The exact URL measured. Empty when unavailable."},"source":{"type":"string","enum":["field","lab",""],"description":"`field` = Chrome UX Report (real users, what Google ranks on); `lab` = a synthetic Lighthouse run. Clients MUST label which is shown.\n\nEmpty string when unavailable, following `php_version` — an absent *category* is spelled as the empty string in this spec, not as `null`."},"field_available":{"type":"boolean","description":"Whether real-user (field) data exists for this site at all, independent of which reading is returned — so the UI can say \"no real-user data yet\" while still showing the lab number."},"lcp_ms":{"type":["integer","null"],"format":"int64","minimum":0,"description":"Largest Contentful Paint, p75, milliseconds. Good ≤ 2500, poor > 4000."},"cls_milli":{"type":["integer","null"],"format":"int64","minimum":0,"description":"Cumulative Layout Shift, p75, in **thousandths** (0.083 → `83`). An integer so no band comparison is ever made against a float at the 0.1/0.25 boundaries; clients render `cls_milli / 1000`. Good ≤ 100, poor > 250."},"inp_ms":{"type":["integer","null"],"format":"int64","minimum":0,"description":"Interaction to Next Paint, p75, milliseconds. Good ≤ 200, poor > 500. INP replaced First Input Delay as a Core Web Vital in March 2024; FID is retired and is deliberately not reported."},"ttfb_ms":{"type":["integer","null"],"format":"int64","minimum":0,"description":"Time to First Byte — a diagnostic, not a Core Web Vital."},"fcp_ms":{"type":["integer","null"],"format":"int64","minimum":0,"description":"First Contentful Paint — a diagnostic, not a Core Web Vital."},"performance_score":{"type":["integer","null"],"minimum":0,"maximum":100,"description":"Lighthouse performance score, 0–100. Always `null` on a `field` reading — the Chrome UX Report computes no score, and inventing one would present a number Google never produced."},"accessibility_score":{"type":["integer","null"],"minimum":0,"maximum":100,"description":"Lighthouse accessibility score, 0–100 (docs/85 §2.1). Lighthouse computes all four of its categories from a **single** page load, so this costs about a second on a 10–30 s run — before W11F it was computed and discarded.\n\n`null` on a `field` reading, and on any `lab` reading taken before this shipped. Never `0` for \"not measured\": 0 is a real and very bad score."},"best_practices_score":{"type":["integer","null"],"minimum":0,"maximum":100,"description":"Lighthouse best-practices score, 0–100 — mixed content, deprecated APIs, console errors. `null` on a `field` reading."},"seo_score":{"type":["integer","null"],"minimum":0,"maximum":100,"description":"Lighthouse SEO score, 0–100. `null` on a `field` reading."},"stack_packs":{"type":"array","items":{"type":"string"},"description":"The technology stacks Lighthouse detected on this run (`wordpress`, `woocommerce`, …).\n\n**Ids only.** Lighthouse also ships stack-specific remediation *text*; that is untranslated vendor English and never reaches a customer surface. The value here is the **detection**, which is the only thing in the system that knows what a `one_click` site actually runs (docs/85 §5)."},"band":{"$ref":"#/components/schemas/VitalsBand"},"lcp_band":{"$ref":"#/components/schemas/VitalsBand"},"cls_band":{"$ref":"#/components/schemas/VitalsBand"},"inp_band":{"$ref":"#/components/schemas/VitalsBand"},"measured_at":{"type":["string","null"],"format":"date-time"},"opportunities":{"type":"array","description":"What is actually making this page slow, **largest saving first** — the \"why\" behind the numbers above.\n\n⚠️ An empty array does **not** mean \"nothing to fix\". It means this reading carries no opportunities, which is always the case for a `field` reading: the Chrome UX Report describes what real users experienced, not what the page could do differently. Rendering empty as \"your site is perfect\" would be a false all-clear on exactly the sites we know least about.\n\nAlways describes the same measurement as the metrics above — these come from the reading being returned, never merged across runs.","items":{"$ref":"#/components/schemas/SiteVitalsOpportunity"}},"screenshots":{"$ref":"#/components/schemas/SiteVitalsScreenshots"}}},"SiteVitalsAuditItem":{"type":"object","description":"One offending row inside an audit — a file, a third party, or a DOM element.\n\nThis is what turns *\"unused JavaScript, saves 1.2 s\"* into *\"`elementor-frontend.js` — 448 KB transferred, 712 KB of it never executed\"*. Every numeric field is optional because Lighthouse's audits genuinely carry different columns (`details.headings` differs per audit); a client renders the ones that are present.","required":["url","label","selector","resource_type","total_bytes","wasted_bytes","wasted_ms","score_milli"],"properties":{"url":{"type":"string","description":"The resource's URL, truncated to 300 characters. Empty for an element row (`layout-shifts`) or an entity row (`third-parties-insight`).","example":"https://acme.test/wp-content/plugins/revslider/js/rs6.min.js"},"label":{"type":"string","description":"A human-readable name — a DOM node's own label, a third party's name, a breakdown group. This is the half a **customer** recognises on their own page.","example":"servenobid.com"},"selector":{"type":"string","description":"The CSS selector for an element row. Developer-facing, blank for a file row.","example":"div.wp-block-group > figure.hero > img.attachment-card"},"resource_type":{"type":"string","description":"Lighthouse's own resource classification where the audit reported one. ⛔ Never guessed from the file extension."},"total_bytes":{"type":["integer","null"],"format":"int64","minimum":0,"description":"Bytes transferred for this resource."},"wasted_bytes":{"type":["integer","null"],"format":"int64","minimum":0,"description":"Bytes that would be saved by fixing this row."},"wasted_ms":{"type":["integer","null"],"format":"int64","minimum":0,"description":"Milliseconds this row cost, or would save. Depending on the audit this is a render-blocking delay, a script's CPU time, or a third party's main-thread time."},"score_milli":{"type":["integer","null"],"format":"int64","minimum":0,"description":"This row's own layout-shift contribution × 1000, for `layout-shifts`. Scaled by 1000 for the same reason `cls_milli` is: an integer comparison can never land on the wrong side of a Core Web Vitals band boundary through float truncation."}}},"SiteVitalsHistory":{"type":"object","description":"A site's speed over time, everything that changed on it, and what we would recommend — in one payload (docs/85 §4.1).\n\n**One response rather than three endpoints.** The chart cannot be drawn without both series, and a client fetching them separately would render markers belonging to a different window than its points.","required":["points","events","stack_type","stack_packs","opportunities","recommendation"],"properties":{"points":{"type":"array","description":"Oldest → newest, so a chart renders it without reversing. Capped; when a site has more measurements than the cap, the **most recent** are returned — a chart that stopped before the change the customer came to look at would be worse than useless.","items":{"$ref":"#/components/schemas/SiteVitalsHistoryPoint"}},"events":{"type":"array","description":"Oldest → newest, on the same axis as `points`.","items":{"$ref":"#/components/schemas/SiteEvent"}},"stack_type":{"type":"string","description":"The site's configured stack — `static`, `php`, `wordpress`, `woocommerce`, `node`, `one_click`. Decides which advice and which events apply: a static site must never be given WordPress advice, which is what happened before the vitals path branched on this at all (docs/85 §5)."},"stack_packs":{"type":"array","items":{"type":"string"},"description":"What the newest lab run detected. Resolves `one_click`, which is a container for \"whatever the customer installed\" and therefore knows nothing about itself."},"opportunities":{"type":"array","description":"The newest lab run's opportunities. On a customer surface these are the same rows `getSiteVitals` returns; on the staff surface they additionally include `owner: platform` audits, which is the only place our own TTFB findings are visible to anyone.","items":{"$ref":"#/components/schemas/SiteVitalsOpportunity"}},"recommendation":{"$ref":"#/components/schemas/SpeedUpRecommendation"}}},"SiteVitalsHistoryPoint":{"type":"object","description":"One measurement on a site's speed trend line (docs/85 §4.1).","required":["measured_at","source","performance_score","accessibility_score","best_practices_score","seo_score","lcp_ms","cls_milli","inp_ms","band","score_delta"],"properties":{"measured_at":{"type":"string","format":"date-time"},"source":{"type":"string","enum":["field","lab"],"description":"Clients MUST key on this. A `field` (CrUX) reading and a `lab` (Lighthouse) reading are different measurements, and drawing them as one series is how a site appears to \"improve 30 points overnight\" by having crossed CrUX's traffic threshold."},"performance_score":{"type":["integer","null"],"minimum":0,"maximum":100},"accessibility_score":{"type":["integer","null"],"minimum":0,"maximum":100},"best_practices_score":{"type":["integer","null"],"minimum":0,"maximum":100},"seo_score":{"type":["integer","null"],"minimum":0,"maximum":100},"lcp_ms":{"type":["integer","null"],"format":"int64","minimum":0},"cls_milli":{"type":["integer","null"],"format":"int64","minimum":0},"inp_ms":{"type":["integer","null"],"format":"int64","minimum":0},"band":{"$ref":"#/components/schemas/VitalsBand"},"score_delta":{"type":["integer","null"],"description":"Change in `performance_score` against the previous point **of the same source** — the \"did it go up or down\" the customer actually asks.\n\n`null`, never `0`, when either side is unmeasured. A zero delta is the real claim \"it did not move\"; a site whose earlier run failed has not \"not moved\", it has not been compared. Computed server-side so two clients cannot subtract two nullable columns two different ways."}}},"SiteVitalsOpportunity":{"type":"object","description":"One audit's finding about a page, as Lighthouse reported it.\n\n⚠️ **The name is narrower than the thing.** This carries diagnostics and passed audits as well as quantified opportunities — see `group`. It was not renamed because the name is the join key an optimisation tier is scoped against (docs/61 §4.5) and is already in the SDK, the CLI and the admin console; `group` carries the distinction instead, and every consumer reads it.\n\nA saving that Lighthouse did not quantify is `null`, never `0`: a zero asserts \"fixing this would gain you nothing\", which is a much stronger claim than \"this was not measured\".","required":["audit_id","title","savings_ms","savings_bytes","owner","item_count","group","score","display_value","numeric_value","numeric_unit","items"],"properties":{"audit_id":{"type":"string","description":"Lighthouse's stable audit identifier (`render-blocking-insight`, `unused-javascript`, `layout-shifts`, `lcp-discovery-insight`, …).\n\nExposed alongside the human title because it is the **join key** an optimisation tier is scoped against: Lighthouse rewords titles between releases, but the ids are the contract.\n\n⚠️ Lighthouse **13 renamed most of them**: the classic opportunity audits (`render-blocking-resources`, `modern-image-formats`, `third-party-summary`, …) were replaced by *insights*. Clients must treat an unrecognised id as ordinary and render the audit from its numbers rather than from a hardcoded id list.","example":"render-blocking-insight"},"title":{"type":"string","description":"Lighthouse's own wording, passed through unchanged so this dashboard and a customer's own PageSpeed run do not disagree about what the problem is called.","example":"Render-blocking requests"},"savings_ms":{"type":["integer","null"],"format":"int64","minimum":0,"description":"Estimated load time saved by fixing it. Null when not quantified."},"savings_bytes":{"type":["integer","null"],"format":"int64","minimum":0,"description":"Estimated bytes saved by fixing it. Null when not quantified."},"owner":{"type":"string","enum":["site","platform"],"description":"Who has to fix it (docs/85 §3).\n\n`site` — the customer's content, theme or plugins. `platform` — **our** server configuration: `server-response-time` is TTFB on a box we run, and telling a customer to \"improve server response times\" on hosting they pay us for is our defect presented as their homework.\n\nOn a **customer** surface this is always `site`: the engine filters platform-owned audits out before serialization, and they are never counted toward a speed-up recommendation. Staff surfaces return both, because a regression in our own TTFB is a real finding an operator can act on."},"item_count":{"type":"integer","minimum":0,"description":"How many resources the audit flagged in total. `0` when the audit carried no item list, which is normal for page-weight style audits.\n\nDeliberately **not** `items.length`: `items` is capped at 8, so reporting its length as the count would say \"8 files\" about a page with thirty-three — which is what `third-parties-insight` reports on a real news site."},"group":{"type":"string","enum":["opportunity","diagnostic","passed"],"description":"Which of PageSpeed's three sections this audit belongs in.\n\n`opportunity` — quantified and actionable. `diagnostic` — a fact that explains a metric but carries no price (*\"your LCP element is this image\"*, *\"these elements shifted\"*). `passed` — Lighthouse scored it 100.\n\n⛔ Clients must **not** infer this from `savings_ms` being null: several diagnostics are unquantifiable by nature, and several passed audits report a saving of exactly 0. Only `opportunity` rows are counted toward a speed-up recommendation."},"score":{"type":["integer","null"],"minimum":0,"maximum":100,"description":"Lighthouse's 0-100 score for this individual audit. Null means informative or not-applicable, which is **not** zero."},"display_value":{"type":"string","description":"Lighthouse's own summary line (*\"Total size was 3,398 KiB\"*).\n\n⚠️ **Vendor English.** It is on the wire for staff surfaces and for a customer comparing against PageSpeed themselves; a localized surface must render `numeric_value`/`numeric_unit` instead (CLAUDE.md §2.19).","example":"Est savings of 780 ms"},"numeric_value":{"type":["integer","null"],"format":"int64","description":"The audit's headline figure — the translatable equivalent of `display_value`.\n\n⛔ Not derivable from `items`: `total-byte-weight` lists the ten heaviest resources and only eight are returned, so summing the rows under-reports the page weight the audit exists to state.","example":3479552},"numeric_unit":{"type":"string","description":"Lighthouse's unit for `numeric_value` — `byte`, `millisecond`, `element`.","example":"byte"},"items":{"type":"array","items":{"$ref":"#/components/schemas/SiteVitalsAuditItem"},"maxItems":8,"description":"The offending rows themselves, worst first — the files, third parties or DOM elements the audit flagged, each with its size and its cost.\n\nBounded at 8 because `third-parties-insight` on a real news site reports 33 rows and `bootup-time` 27; storing every one per sample per site is how a measurement table becomes the largest table in the database. `item_count` carries the true total alongside, so \"8 of 33\" is never mistaken for \"8\"."}}},"SiteVitalsScreenshotFrame":{"type":"object","description":"One frame of the loading filmstrip.","required":["timing_ms","url"],"properties":{"timing_ms":{"type":"integer","minimum":0,"description":"Milliseconds after navigation start that this frame was captured."},"url":{"type":"string","description":"A short-lived **presigned** URL to the JPEG, minted per read and valid for minutes. ⛔ It carries the signature and is therefore a credential for its lifetime — clients must not persist, log or share it."}}},"SiteVitalsScreenshots":{"type":"object","description":"What the page looked like while it loaded — the filmstrip and the finished render.\n\n`available` is reported separately from the parent envelope's flag because a perfectly good measurement can carry no pictures: a `field` (CrUX) reading photographs nothing, and a `lab` reading taken while the platform's object storage was unconfigured stored nothing. An empty `frames` list on its own would make \"we did not keep the pictures\" look identical to \"the page rendered nothing\".","required":["available","final_url","frames"],"properties":{"available":{"type":"boolean"},"final_url":{"type":"string","description":"Presigned URL for the finished-page screenshot. Empty when there is none."},"frames":{"type":"array","items":{"$ref":"#/components/schemas/SiteVitalsScreenshotFrame"},"maxItems":12,"description":"The filmstrip, oldest frame first."}}},"SiteWebLogs":{"type":"object","description":"The tail of a site's access and error logs.\n\n⛔ **The only response on this surface carrying another person's personal data.** `access` is a list of the customer's *visitors'* IP addresses, held under the customer's lawful basis and not ours. A client must not cache it, log it, or include it in an error report.","required":["access","error","truncated","unreadable","access_available","error_available"],"additionalProperties":false,"properties":{"access":{"type":"string","description":"The tail of the access log, or `\"\"` when the vendor published none."},"error":{"type":"string","description":"The tail of the error log, or `\"\"` when the vendor published none. On a misconfigured application it can carry absolute paths and credentials in a stack trace."},"truncated":{"type":"boolean","description":"Either stream was cut to its most recent bytes. Say so rather than implying the tail is the whole log."},"unreadable":{"type":"boolean","description":"Neither log could be read. ⛔ Not the same as a site with no traffic, and must never render as two empty panes."},"access_available":{"type":"boolean","description":"Whether the access log could be read. On our own servers the two logs are different files and one can be readable while the other is not, so `access: \"\"` with this `false` means \"could not look\", never \"no traffic\". Serves sites on our own servers as well as vendor-hosted ones since W43-54 (previously a `404`)."},"error_available":{"type":"boolean","description":"Whether the error log could be read — the same distinction, for `error`."}}},"SiteWordPress":{"type":"object","description":"The WordPress install on a site's vendor hosting package, and what its package type permits us to change.","required":["installed","version","is_latest","is_multisite","update_available","update_version","site_url","wizard_required","unavailable_reason","capabilities"],"additionalProperties":false,"properties":{"installed":{"type":"boolean","description":"Whether WordPress is on the package at all."},"version":{"type":"string","description":"The installed version, or `\"\"` when the vendor did not state one.","example":"6.8.2"},"is_latest":{"type":"boolean","nullable":true,"description":"⛔ **Tri-state.** Null means the vendor did not say, which is **not** \"out of date\": rendering an unknown as out of date invites a customer to run a core update on a live site for nothing.","example":true},"is_multisite":{"type":"boolean","description":"Whether the install is a WordPress network."},"update_available":{"type":"boolean","description":"The flag a screen should act on. Derived from the vendor's update object being non-empty rather than from a comparison between two version strings nobody parsed — ⛔ `{}` is how this platform says *\"no update\"*, and it is falsy, so the presence of the key is not the signal."},"update_version":{"type":"string","description":"The version waiting, or `\"\"` when the install is current.","example":"6.8.3"},"site_url":{"type":"string","description":"The URL WordPress believes it is served from.","example":"https://example.com"},"wizard_required":{"type":"boolean","description":"Whether the install has never been through WordPress's own setup wizard — a half-installed site, not a broken one."},"unavailable_reason":{"type":"string","description":"⛔ **Read this before rendering `installed`.** Empty means `installed` is authoritative. Non-empty means it is **not**: the probe failed and we could not determine the answer, so a client MUST NOT say \"WordPress is not installed\".\n\n`installed` alone answers a three-way question with a boolean — there is no WordPress; there is one that cannot bootstrap; the probe could not run — and reporting the first for all three told a customer with a broken database that they had no site, whose obvious remedy would have installed one **over their own content**.\n\nValues: `database` (WordPress cannot reach its database), `config` (`wp-config.php` is missing, unparseable, or fatals), `unreadable` (the probe failed in a way we do not recognise — deliberately the fallback, so that a reworded vendor message degrades to \"we could not read this\" rather than silently resuming the claim that the site does not exist). Always `\"\"` on vendors that answer the question directly rather than by probing.\n\n⛔ `not-routed` is **not one of the three above and must not be rendered like them** (D14127). The other three all mean *something is wrong with this site*; this one means *this hosting package does not carry the WordPress family at all* — the vendor answers 404 for `wordpressVersion`, `wordpressIsInstalled` and `wordpressPlugins` alike, which is a fact about the package, not a fault on the site. Folded into `unreadable` it was rendered as **\"WordPress is installed but is not responding … contact support\"**, so a customer whose site was serving perfectly well was told it was broken, and two lanes went looking for an outage that did not exist. Render it as a neutral notice, exactly as a `404` on this resource is rendered.","enum":["","database","config","unreadable","not-routed"],"example":"database"},"capabilities":{"type":"object","description":"Which of the eleven WordPress operations this package type permits, keyed by our **stable machine identifiers** — never a vendor string and never display text, so they are usable as i18n key suffixes (§2.7). One read gates eleven buttons, so a customer never learns their plan's shape by pressing one and reading a refusal. A map rather than eleven fields because a twelfth capability then costs a catalogue entry rather than a change to this shape, the SDK and every client that parses it.","additionalProperties":{"type":"boolean"},"example":{"wp_plugins":true,"wp_themes":true,"wp_users":true,"wp_admin_users":true,"wp_search_replace":true,"wp_site_settings":true,"wp_staging":true,"wp_updates":true,"wp_checksum":true,"wp_database":true,"platform_reinstall":false}}}},"SiteWordPressAbilities":{"type":"object","required":["abilities","servers"],"properties":{"abilities":{"type":"array","items":{"type":"object","required":["name","plugin","description","input_schema","read_only","destructive"],"properties":{"name":{"type":"string","example":"pbs/create-page"},"plugin":{"type":"string","description":"The plugin's MCP server id.","example":"page-builder-sandwich"},"description":{"type":"string"},"input_schema":{"type":"object","additionalProperties":true},"read_only":{"type":"boolean"},"destructive":{"type":"boolean"}}}},"servers":{"type":"object","additionalProperties":{"type":"boolean"},"description":"Plugin server id -> whether it answered."}}},"SiteWordPressActivityEntry":{"type":"object","description":"One recorded change to a site's WordPress.","required":["id","at","actor","action","detail"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid","description":"The audit row's identifier."},"at":{"type":"string","format":"date-time","description":"When it happened."},"actor":{"type":"string","description":"`user:<id>` or `apikey:<id>`, carried verbatim from the audit trail. ⛔ Not resolved to a display name — that would be a query per row, and a name looked up today is not what the row says.","example":"user:019fb8a6-0000-7000-8000-000000000000"},"action":{"type":"string","description":"A stable code — `theme.install`, `plugin.delete`, `user.role`, `cli.run`, `update-policy.set`, … ⛔ Never a sentence: the client owns the wording, in every locale.","example":"theme.install"},"detail":{"type":"object","additionalProperties":true,"description":"What changed — the site's domain and the name of the affected component. ⛔ Never a password, console output or an uploaded archive."}}},"SiteWordPressActivityList":{"type":"object","description":"A site's recent WordPress activity, newest first.","required":["data","window_days","limit"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SiteWordPressActivityEntry"}},"window_days":{"type":"integer","description":"How far back this read looked. ⛔ Returned, not assumed — a screen that renders rows without stating the window reads as \"this is everything\".","example":90},"limit":{"type":"integer","description":"The most rows one read returns.","example":100}}},"SiteWordPressChecksum":{"type":"object","description":"Which of a site's WordPress core files differ from the checksums WordPress.org publishes. A modified core file is the classic signature of a compromise.","required":["ok","files"],"additionalProperties":false,"properties":{"ok":{"type":"boolean","description":"Whether nothing differs."},"files":{"type":"array","description":"The core files that differ, by path. Empty when `ok` is true. Read from the vendor's path-keyed map, so a file is named rather than merely counted.","items":{"type":"string"},"example":["wp-includes/load.php"]}}},"SiteWordPressCliResult":{"type":"object","description":"One WP-CLI console invocation. ⛔ A non-zero `exit_code` is still a `200`.","required":["argv","exit_code","stdout","stderr","truncated"],"additionalProperties":false,"properties":{"argv":{"type":"array","description":"What actually ran, after the allow-list normalised it — echoed back so `wp plugin list` and `plugin list` are visibly the same command.","items":{"type":"string"}},"exit_code":{"type":"integer","description":"WP-CLI's exit code. `0` is success.","example":0},"stdout":{"type":"string","description":"What WP-CLI printed, up to the console's cap."},"stderr":{"type":"string","description":"WP-CLI's diagnostics, carried **separately** and never merged into `stdout` — WP-CLI writes PHP notices here on runs that succeed, so folding them together would corrupt the JSON of every `--format=json` read."},"truncated":{"type":"boolean","description":"True when `stdout` was cut at the cap. ⛔ Stated rather than hidden: a silently cut-off JSON document is worse than none, because it nearly parses."}}},"SiteWordPressCronEvent":{"type":"object","description":"One task in WordPress's own scheduler. ⛔ Fleet-only — this platform publishes no cron endpoint at any path, so this is never populated on that line and `wp_cron` is `false` there.","required":["hook","next_run","next_run_relative","recurrence"],"additionalProperties":false,"properties":{"hook":{"type":"string","description":"The hook name — what `runSiteWordPressCronEvent` takes.","example":"wp_scheduled_delete"},"next_run":{"type":"string","description":"When it is next due, in GMT, as the scheduler states it. `\"\"` if unknown.","example":"2026-08-16 17:29:14"},"next_run_relative":{"type":"string","description":"⛔ The scheduler's **own** human phrasing, carried verbatim rather than derived from `next_run`. Two answers to \"when\" that drift apart by a second on every refresh is a screen nobody trusts, and this is the one a customer reads.","example":"4 hours 39 minutes"},"recurrence":{"type":"string","description":"How often it repeats, or the scheduler's word for one-shot.","example":"1 day"}}},"SiteWordPressCronEventList":{"type":"object","description":"A site's scheduled tasks, soonest first.","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SiteWordPressCronEvent"}}}},"SiteWordPressDatabaseCheck":{"type":"object","description":"Whether a site's WordPress can reach its own database. One boolean, because that is the whole answer the vendor gives — inventing detail around it would be fiction.","required":["ok"],"additionalProperties":false,"properties":{"ok":{"type":"boolean","description":"Whether the install can reach its database."}}},"SiteWordPressHardening":{"type":"object","description":"A site's hardening checklist as the site reports it. `checks` is empty where the platform hosting the site has no checklist.","required":["checks"],"additionalProperties":false,"properties":{"checks":{"type":"array","items":{"$ref":"#/components/schemas/SiteWordPressHardeningCheck"}}}},"SiteWordPressHardeningCheck":{"type":"object","required":["key","passed","fixable"],"additionalProperties":false,"properties":{"key":{"type":"string","enum":["file_editor_disabled","debug_off","force_ssl_admin","salts_unique","https_site_url","no_admin_username","xmlrpc_blocked"],"description":"Which check."},"passed":{"type":"boolean","description":"True when the site already meets it."},"fixable":{"type":"boolean","description":"True when `POST …/hardening/{key}` can fix it now (false once passed, for checks with no one-click fix, and for `force_ssl_admin` while the address is not HTTPS)."}}},"SiteWordPressMaintenance":{"type":"object","description":"Whether the site is showing WordPress's maintenance page. ⛔ Always read from the site, never from our record of what we last set — WordPress sets this flag itself during a core update.","required":["enabled"],"additionalProperties":false,"properties":{"enabled":{"type":"boolean","description":"True when visitors are seeing the maintenance page."}}},"SiteWordPressPlugin":{"type":"object","description":"One plugin installed on a site's WordPress.","required":["name","status","version","update_version","managed"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"The plugin's slug, as WordPress knows it.","example":"woocommerce"},"status":{"type":"string","description":"The plugin's activation status, in the vendor's own words.","example":"active"},"version":{"type":"string","description":"The installed version, or `\"\"` when the vendor did not state one.","example":"9.4.2"},"update_version":{"type":"string","description":"The version waiting, or `\"\"` when the plugin is current. ⛔ A string and not a boolean, because a screen that can name the waiting version is more useful than one that can only say \"update\" — and named `update_version` because `update` is a reserved method one layer down.","example":"9.5.0"},"managed":{"type":"boolean","description":"A Zinn® plugin the platform depends on (the preinstalled platform set). Shown as \"Managed by Zinn®\"; deactivating or removing it is refused with 422 `refusal.wordpress.managedPlugin`.","example":false}}},"SiteWordPressPluginList":{"type":"object","description":"A site's plugins, plus the vendor's separate flag for the plugin it hides from the listing.","required":["data","stack_cache_installed"],"additionalProperties":false,"properties":{"data":{"type":"array","description":"The installed plugins.","items":{"$ref":"#/components/schemas/SiteWordPressPlugin"}},"stack_cache_installed":{"type":"boolean","description":"⛔ **Cannot be derived from `data`.** this platform excludes its own server-side cache plugin from the listing, so a client deriving this flag from the rows would answer \"not installed\" for ever and the install button would never go away."}}},"SiteWordPressRole":{"type":"object","description":"One role a site's WordPress defines.","required":["role","name"],"additionalProperties":false,"properties":{"role":{"type":"string","description":"The machine value — what a client sends.","example":"editor"},"name":{"type":"string","description":"The install's own label for the role — what a client renders.","example":"Editor"}}},"SiteWordPressRoleList":{"type":"object","description":"The roles a site's WordPress defines — the install's own, including any a plugin added, rather than a hardcoded list of WordPress's five defaults.","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","description":"The roles the install defines.","items":{"$ref":"#/components/schemas/SiteWordPressRole"}}}},"SiteWordPressSettings":{"type":"object","description":"A site's WordPress options, keyed by the vendor's option name. An object and not a list because the vendor publishes a map and the client renders one field per key — a new option therefore costs no change to this shape, the SDK, or any client that parses it.","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"object","description":"The options, keyed by name.","additionalProperties":{"type":"string"},"example":{"blogname":"Example Shop","blogdescription":"Just another WordPress site"}}}},"SiteWordPressStaging":{"type":"object","description":"A site's staging copies, and whether staging may be used at all.\n\n`permitted` travels beside `data` because they are different sentences to a customer: *\"your plan does not include staging\"* and *\"you have not made a staging copy yet\"* need different copy and different buttons, and collapsing them into an empty list produces wording that is wrong for one of the two cases in 58 languages.","required":["permitted","publishable","publish_modes","reinstallable","idle_removal_days","idle_notice_days","operations","data"],"additionalProperties":false,"properties":{"permitted":{"type":"boolean","description":"Whether this site may use WordPress staging at all — on the resold range the package type's own flag, and on our own fleet the plan's `staging` entitlement."},"publish_modes":{"type":"array","description":"Which publish scopes this site's **platform** can actually perform, for `publishSiteWordPressStaging`. A client offers exactly these and no more.\n\n⛔⛔ **This is not a permission and it is not a spelling of `publishable`.** It is a fact about the machine the site runs on: the Zinn® autoscaling platform holds the clone and the live site as two accounts on a box we own, so the file copy and the database copy are independent steps — `[\"files\", \"db\", \"both\"]`. Managed shared hosting publishes a clone whole, because its staging operation takes a source and no scope, and that platform exposes no SSH and no database import to compose one from — `[\"both\"]`.\n\n⛔ So a client must not derive it from the plan. A larger package changes what a customer is allowed to do and changes nothing about what that platform can do, and a database-only button rendered on that line would be refused `422` by the engine. Where only `both` is offered, say so rather than showing a disabled choice: the customer cannot buy their way out of it.","items":{"type":"string","enum":["files","db","both"]},"example":["files","db","both"]},"publishable":{"type":"boolean","description":"Whether the plan also carries **publish to live**, which is a separate permission from creating a staging copy.\n\n⛔ Not folded into `permitted`, because the catalogue sells the two apart: the entry fleet rung grants a staging copy and deliberately withholds publishing it, as one of the named reasons to move up. A client must render a working staging card with the publish control withheld — hiding the whole card would take away something the customer bought, and offering the button would 422."},"reinstallable":{"type":"boolean","description":"Whether the plan carries **reinstalling** the platform software over the staging copy. A fifth question for the same reason as `publishable`: the catalogue sells it separately, so a client that guessed it from `permitted` would offer a destructive button the engine then refuses."},"idle_removal_days":{"type":"integer","nullable":true,"minimum":1,"description":"After how many days with no change a staging copy is removed automatically, or `null` when nothing ever removes it.\n\n⛔⛔ **The platform deletes idle staging copies, and a copy can hold unpublished work that no backup covers**, so a client should say this before a customer puts work into one. It is read from the sweep that does the deleting, never typed, so the sentence and the deletion cannot disagree.\n\n`null` on a platform that cannot report when a clone last changed: nothing is removed there, and promising a removal would be a false sentence.","example":30},"idle_notice_days":{"type":"integer","nullable":true,"minimum":0,"description":"How many days' warning the customer is emailed before that removal, or `null` when `idle_removal_days` is `null`.","example":9},"operations":{"type":"array","description":"The site's recent staging operations, newest first — the client's window onto work that runs **after** the request returns.\n\n⛔⛔ **Creating, publishing, deleting and reinstalling a staging copy are all asynchronous, and this array is how a client knows what happened.** Measured on the Zinn® fleet: a create takes ~30 s and a delete ~20 s, against a 30 s server worker timeout and a typical browser abort well below it — so this work cannot run inside the request and the `202` means *accepted*, never *finished*.\n\n⭐ Poll `getSiteWordPressStaging` while any entry is `queued` or `running`, and stop when none is. Without this array *\"no staging copy yet\"* and *\"the staging copy failed to build\"* are the same picture, which is the one thing a customer staring at an empty card most needs told apart.\n\n⚠️ Refusals are **not** here — a plan that does not include staging, a scope the platform cannot honour, or a publish with no copy to publish are all still immediate `422`s from the request itself.","items":{"$ref":"#/components/schemas/SiteWordPressStagingOperation"}},"data":{"type":"array","description":"The staging copies that exist.","items":{"$ref":"#/components/schemas/SiteWordPressStagingClone"}}}},"SiteWordPressStagingClone":{"type":"object","description":"One staging copy of a site's WordPress.","required":["id","name","created_at","url"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"The clone's identifier at the vendor, used to delete it. ⛔ A clone the vendor reported without an id is dropped rather than rendered — a delete button with no id behind it can only fail.","example":"1"},"name":{"type":"string","description":"The clone's name, in the vendor's own words.","example":"staging"},"created_at":{"type":"string","description":"When the clone was made, in the platform's own format. Not typed as a date-time: the platform does not guarantee one, and an unreadable timestamp is an empty string rather than an invented \"now\" — a screen renders a blank as unknown, and this is the one field a customer uses to decide whether the copy is worth publishing over their live site.","example":"2026-08-01 14:22:07"},"url":{"type":"string","description":"The address to open the staging copy at, or an empty string when there is not one to give.\n\n⛔ **Empty on the resold range, and that is honest rather than unfinished.** The vendor mints its own staging hostname inside the package and its clone listing does not carry it, so a URL of ours would be *derived* — and a derived vendor hostname is the mistake `preview_urls` records in full: of two real packages measured, one was predictable and one carried a datacentre label and a different registrable domain, so the guess would have handed a customer a link that resolves to nothing. A blank is a fact a client can render; a guess is a broken link.\n\nOn our own fleet it is a hostname **we** mint, so we know it. It is always `https` — the record is proxied and inherits the zone's wildcard certificate — and the copy behind it is served `noindex` and cannot send outbound mail.","example":"https://stg-01a047c8de9a.zinnpreview.com"}}},"SiteWordPressStagingOperation":{"type":"object","description":"One staging operation running, or recently finished, on the platform's own queue.\n\n⛔ The work happens outside the request (see `operations` on `SiteWordPressStaging`), so this row — not the HTTP status — is what says whether a customer's staging copy was actually made, published, deleted or reinstalled.","required":["id","kind","mode","status","message","created_at"],"additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"kind":{"type":"string","enum":["create","publish","delete","reinstall"],"description":"Which staging operation this row is."},"mode":{"type":"string","enum":["","files","db","both"],"description":"The publish scope, for `kind: publish` only — empty for every other kind. It is the scope the engine **resolved and validated**, so a client can show the customer exactly what is being copied rather than what was typed."},"status":{"type":"string","enum":["queued","running","succeeded","failed"],"description":"`queued` is what a `202` returns. `succeeded` and `failed` are both terminal and both are written, so *\"still running\"* is never inferred from the absence of a result."},"message":{"type":"string","description":"Customer-facing English, and only meaningful when `status` is `failed`. It never carries a vendor sentence or a stack trace."},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time","nullable":true,"description":"When the platform picked the operation up. Null while `queued`."},"finished_at":{"type":"string","format":"date-time","nullable":true,"description":"When it settled. Null until terminal."}}},"SiteWordPressStagingPublishRequest":{"type":"object","description":"How much of the staging copy to publish over the live site.\n\n⛔ Scope only. There is no field here that selects a direction, and none may be added — see `publishSiteWordPressStaging` for why each direction has its own path.","additionalProperties":false,"properties":{"mode":{"type":"string","enum":["files","db","both"],"default":"both","description":"`files` copies the document root and leaves the live database alone; `db` copies the database and search-replaces the staging URL back to the live one, leaving the live files alone; `both` is the whole copy.\n\n⛔ **Omitting it means `both`**, so a client written before this field existed keeps its exact previous behaviour. The default is deliberately the whole copy: a publish that quietly did half the job looks identical to one that worked.\n\n⚠️ The partial scopes can leave a site inconsistent — new files against an old schema, or a new schema against old files — which is a real risk on a plugin or theme change and is worth warning a customer about. It is their call to make, not the platform's to refuse. Check `publish_modes` before offering it."}}},"SiteWordPressSwitches":{"type":"object","description":"Search-engine visibility and debug mode as the site reports them. Empty where the platform hosting the site has no such switches.","additionalProperties":false,"properties":{"search_engines_visible":{"type":"boolean","description":"False when WordPress's \"Discourage search engines\" is ticked (`blog_public` = 0)."},"debug_mode":{"type":"boolean","description":"True when `WP_DEBUG` is on in `wp-config.php`."}}},"SiteWordPressTheme":{"type":"object","description":"One theme installed on a site's WordPress — the same four facts as a plugin.","required":["name","status","version","update_version"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"The theme's slug, as WordPress knows it.","example":"twentytwentyfive"},"status":{"type":"string","description":"The theme's activation status, in the vendor's own words.","example":"active"},"version":{"type":"string","description":"The installed version, or `\"\"` when the vendor did not state one.","example":"1.2"},"update_version":{"type":"string","description":"The version waiting, or `\"\"` when the theme is current.","example":"1.3"}}},"SiteWordPressThemeList":{"type":"object","description":"A site's installed themes.","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","description":"The installed themes.","items":{"$ref":"#/components/schemas/SiteWordPressTheme"}}}},"SiteWordPressUpdatePolicy":{"type":"object","description":"A site's auto-update **policy**, what the site is **observed** to be doing, and the **drift** between them. ⛔ Three separate things; a client must not merge them.","required":["core","plugins","themes","ring","applied_at","apply_error","observed_read","observed_core","plugins_off","themes_off","drift"],"additionalProperties":false,"properties":{"core":{"type":"string","enum":["off","minor","all"],"description":"The stored policy for WordPress core updates.","example":"minor"},"plugins":{"type":"boolean","description":"The stored policy — whether every plugin should auto-update."},"themes":{"type":"boolean","description":"The stored policy — whether every theme should auto-update."},"ring":{"type":"string","enum":["canary","early","general"],"description":"The staged-rollout ring this site belongs to.","example":"general"},"applied_at":{"type":"string","description":"When the policy last reached the site, ISO-8601, or `\"\"` if it never has. ⛔ A timestamp and not a flag: \"when did this last reach the site\" is the question an operator asks, and a boolean cannot answer it.","example":"2026-08-17T19:00:00+00:00"},"apply_error":{"type":"string","description":"Why the last apply failed, or `\"\"`. Kept beside `applied_at` rather than replacing it, so a failed re-apply does not erase that an earlier one worked."},"observed_read":{"type":"boolean","description":"Whether the site itself was read. ⛔ An empty `drift` is only meaningful while this is `true`."},"observed_core":{"type":"string","description":"What `WP_AUTO_UPDATE_CORE` is set to on the site — `off`, `minor`, `all`, or `\"\"` meaning **the constant is not defined at all**, so WordPress applies its own default. ⛔ `\"\"` is not `off`.","example":"minor"},"plugins_off":{"type":"array","description":"The plugins on this site that are NOT auto-updating.","items":{"type":"string"}},"themes_off":{"type":"array","description":"The themes on this site that are NOT auto-updating.","items":{"type":"string"}},"drift":{"type":"array","description":"Which of `core`, `plugins`, `themes` the site disagrees with the policy about.","items":{"type":"string","enum":["core","plugins","themes"]}}}},"SiteWordPressUpload":{"type":"object","description":"One resumable plugin/theme upload (D28103). Bound to one site of one organisation; expires 24 hours after it was started unless completed.","required":["id","kind","status","size","part_size","part_count","file_name","activate","message","expires_at","created_at","finished_at"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["plugin","theme"]},"status":{"type":"string","enum":["open","assembling","installed","failed"]},"size":{"type":"integer","format":"int64"},"part_size":{"type":"integer","description":"Bytes per part, chosen by the platform. Every part but the last is exactly this long."},"part_count":{"type":"integer"},"file_name":{"type":"string"},"activate":{"type":"boolean"},"message":{"type":"string","description":"On `failed`, what went wrong, written for the customer. Empty otherwise."},"expires_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"finished_at":{"type":"string","format":"date-time","nullable":true},"received_parts":{"type":"array","items":{"type":"integer"},"description":"Present while `open` — the part numbers already stored."}}},"SiteWordPressUser":{"type":"object","description":"One account on a site's WordPress. ⛔ **No password field, in either direction** — the only password on this surface travels in a request body.","required":["id","login","display_name","email","roles","registered_at","is_administrator"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"The account's WordPress id, carried as a string because it is the vendor's identifier rather than ours.","example":"12"},"login":{"type":"string","description":"The name the account signs in with.","example":"editor"},"display_name":{"type":"string","description":"The name shown on the site's posts and comments.","example":"Site Editor"},"email":{"type":"string","description":"The account's email address. Personal data about the customer's **own** users, which is why the whole listing is gated on `sites.panel_access`.","example":"editor@example.com"},"roles":{"type":"string","description":"The account's roles, in the vendor's own spelling.","example":"editor"},"registered_at":{"type":"string","description":"When WordPress recorded the account, in the vendor's own format. Not typed as a date-time: the platform does not guarantee one, and coercing it would invent precision.","example":"2026-03-11 09:41:02"},"is_administrator":{"type":"boolean","description":"Whether the account is an administrator. ⛔ Set from **which vendor endpoint the row came from**, not guessed from the role string — the two lists sit behind two different capability flags."}}},"SiteWordPressUserList":{"type":"object","description":"A site's WordPress accounts.","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","description":"The accounts, merged from the two vendor endpoints the package permits. A package carrying only one of the two flags yields only that half, rather than a refusal for the whole listing.","items":{"$ref":"#/components/schemas/SiteWordPressUser"}}}},"SiteWordPressVulnerabilityReport":{"type":"object","description":"Advisories against every plugin and theme installed on a site.","required":["data","worst","unchecked","checked_components","advisories","truncated"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WordPressComponentRisk"}},"worst":{"type":"string","description":"The worst severity found across the site, or `\"\"`.","example":"high"},"unchecked":{"type":"integer","description":"How many components could not be assessed. ⛔ The number that says how much of the estate this screen cannot speak for."},"checked_components":{"type":"integer","description":"How many components were assessed."},"advisories":{"type":"integer","description":"How many advisories were found in total."},"truncated":{"type":"boolean","description":"True when the site has more components than one request will look up."}}},"SlaClaimRequest":{"type":"object","required":["monitor_id","period_start"],"properties":{"monitor_id":{"type":"string","format":"uuid"},"period_start":{"type":"string","format":"date-time","description":"Any instant in the calendar month being claimed; the month is derived from it."},"credit_percent":{"type":"integer","nullable":true,"description":"The published tier claimed. Read **only** when the month is `unadjudicable`, and refused unless it is one of `SlaPolicy.tiers[].credit_percent` — a tier is never rounded to the nearest published one, because rounding would issue money at a rung nobody published."}}},"SlaCredit":{"type":"object","required":["id","period_start","credit_percent","amount_minor","currency","outcome","uptime_percent","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"period_start":{"type":"string","format":"date-time"},"credit_percent":{"type":"integer"},"amount_minor":{"type":"integer","format":"int64","description":"The credit in integer minor units of `currency` (§2.8 — money is never a float)."},"currency":{"type":"string","minLength":3,"maxLength":3},"outcome":{"type":"string","enum":["measured","unadjudicable"],"description":"Whether the month adjudicated, or the credit was granted because our coverage could not decide it."},"uptime_percent":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"SlaCreditList":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SlaCredit"}}}},"SlaPeriod":{"type":"object","required":["monitor_id","site_id","url","label","period_start","period_end","finished","uptime_percent","checks","failures","hours_covered","hours_in_period","coverage_percent","verdict","credit_percent","claimable","claim_deadline","credit"],"properties":{"monitor_id":{"type":"string","format":"uuid"},"site_id":{"type":"string","format":"uuid","nullable":true},"url":{"type":"string"},"label":{"type":"string"},"period_start":{"type":"string","format":"date-time"},"period_end":{"type":"string","format":"date-time"},"finished":{"type":"boolean","description":"Whether the month is over. A running month cannot be claimed."},"uptime_percent":{"type":"string","nullable":true,"description":"Successful checks as a share of checks made, over the hours we have readings for. ⛔ **`null` when no check was made** — zero checks is not zero uptime, and rendering `0` would tell a customer their site was down all month when we simply did not look."},"checks":{"type":"integer"},"failures":{"type":"integer"},"hours_covered":{"type":"integer","description":"Hours of the period we hold readings for."},"hours_in_period":{"type":"integer","description":"Hours the period contains","bounded by now for a running month.":null},"coverage_percent":{"type":"string"},"verdict":{"type":"string","enum":["met","missed","unadjudicable"],"description":"`met` — we honoured the commitment. `missed` — we did not, and a credit is owed at `credit_percent`. `unadjudicable` — our coverage was below `min_coverage_percent`, so the month does not decide and the customer names the tier."},"credit_percent":{"type":"integer","description":"The tier a measured breach reaches. `0` for `met` and for `unadjudicable`."},"claimable":{"type":"boolean"},"claim_deadline":{"type":"string","format":"date-time"},"credit":{"allOf":[{"$ref":"#/components/schemas/SlaCredit"}],"nullable":true}}},"SlaPeriodList":{"type":"object","required":["policy","periods"],"properties":{"policy":{"$ref":"#/components/schemas/SlaPolicy"},"periods":{"type":"array","items":{"$ref":"#/components/schemas/SlaPeriod"}}}},"SlaPolicy":{"type":"object","required":["uptime_target_percent","claim_window_days","min_coverage_percent","exclusions","tiers"],"properties":{"uptime_target_percent":{"type":"string","description":"The published monthly commitment, e.g. `\"99.9\"`. A string, not a number, so a client renders exactly what we publish rather than a float's idea of it.","example":"99.9"},"claim_window_days":{"type":"integer","description":"Days after a month ends during which it may still be claimed.","example":30},"min_coverage_percent":{"type":"string","description":"The share of a month we must have measured for the reading to adjudicate. Below it the month is `unadjudicable` and the customer's claimed tier stands — our coverage gap is ours to carry, because they cannot audit it and we can.","example":"95"},"exclusions":{"type":"array","items":{"type":"string","enum":["maintenance","customer","force_majeure"]},"description":"What is not credited. ⛔ There is deliberately **no upstream-provider exclusion**: a hosting customer bought hosting from Zinn Digital® and never chose our suppliers, so whose hardware failed is our problem by construction (`CLAUDE.md` §2.57)."},"tiers":{"type":"array","items":{"type":"object","required":["below_percent","credit_percent"],"properties":{"below_percent":{"type":"string","example":"99.9"},"credit_percent":{"type":"integer","example":10}}}}}},"SmsMarketingCampaign":{"type":"object","required":["id","name","channel","list_id","text","template","template_language","template_params","status","refusal_code","refusal_message","customer_can_resume","recipients_total","started_at","finished_at","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"channel":{"type":"string","enum":["sms","whatsapp"]},"list_id":{"type":"string","format":"uuid","nullable":true},"text":{"type":"string"},"template":{"type":"string","nullable":true},"template_language":{"type":"string","nullable":true},"template_params":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","sending","paused","sent","refused"]},"refusal_code":{"type":"string","nullable":true,"enum":["not_open","channel_off","account_on_hold","incomplete","too_long","paused","empty","review","no_credit","not_configured","own_sender_required","whatsapp_not_ready"]},"refusal_message":{"type":"string","nullable":true},"customer_can_resume":{"type":"boolean","description":"Paused for something the customer fixes (credit, their own sender, or Meta not accepting their WhatsApp account's messages); `send` resumes it once fixed."},"recipients_total":{"type":"integer"},"started_at":{"type":"string","format":"date-time","nullable":true},"finished_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"SmsMarketingCampaignPage":{"type":"object","required":["data","next_after"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SmsMarketingCampaign"}},"next_after":{"type":"string","format":"uuid","nullable":true}}},"SmsMarketingCampaignReport":{"type":"object","required":["campaign_id","status","recipients","queued","sent","skipped","failed","opted_out","parts","spent_usd_micros","delivered","undelivered","unconfirmed"],"properties":{"campaign_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["draft","sending","paused","sent","refused"]},"recipients":{"type":"integer"},"queued":{"type":"integer"},"sent":{"type":"integer"},"skipped":{"type":"integer","description":"Opted out","no SMS consent":null,"no number or a country not open since the list was snapshotted.":null},"failed":{"type":"integer"},"opted_out":{"type":"integer","description":"Recipients who replied STOP after this campaign started."},"parts":{"type":"integer"},"spent_usd_micros":{"type":"integer"},"delivered":{"type":"integer","description":"Sent messages the carrier confirmed delivered (Telnyx delivery receipt)."},"undelivered":{"type":"integer","description":"Sent messages the carrier or handset refused. The vendor charged for the attempt","so they are not refunded.":null},"unconfirmed":{"type":"integer","description":"Sent messages the carrier gave no final answer for. `sent` minus these three is still awaiting a receipt."}}},"SmsMarketingCampaignWrite":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"list_id":{"type":"string","format":"uuid","nullable":true},"text":{"type":"string","maxLength":1530,"description":"The message. Longer than 160 GSM-7 characters is sent (and priced) as several parts."},"channel":{"type":"string","enum":["sms","whatsapp"],"description":"Chosen while the campaign is a draft. `whatsapp` sends `template` from the organisation's OWN WhatsApp Business account (0 Zinn® credit; Meta bills that account)."},"template":{"type":"string","maxLength":512,"description":"WhatsApp only — the name of a template Meta approved for this account."},"template_language":{"type":"string","maxLength":16,"description":"WhatsApp only — the template's language code","e.g. `en_GB`.":null},"template_params":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":1024},"description":"WhatsApp only — the values for the template body's `{{1}}`, `{{2}}`, … in order (the same for every recipient)."}}},"SpeedUpRecommendation":{"type":"object","description":"Which optimisation tier to lead with for this site, and the evidence for it (docs/85 §7).\n\nBefore this, the speed-up offer fired on a traffic-light band alone while the platform stored ranked, quantified, priced-in-milliseconds opportunities and read none of them.","required":["eligible","tier_code","reason_audit_ids","estimated_savings_ms"],"properties":{"eligible":{"type":"boolean","description":"False for a stack no tier applies to (`static`, `node` — every unit of work in all three tiers is work on a dynamic application), and for a site we have no named problems for.\n\n⚠️ It does **not** mean \"the site is fine\". Whether to offer at all is still decided by the measured `poor` band; this decides *which* tier."},"tier_code":{"type":"string","description":"An extras catalogue code — `site_speedup_standard`, `site_speedup_commerce`, `site_speedup_complex`. Empty when not eligible.\n\nA WooCommerce site is **never** offered the standard tier: on those sites caching everything is the bug, and a customer who buys tier 1 for a WooCommerce site is a refund and a bad review.","example":"site_speedup_commerce"},"reason_audit_ids":{"type":"array","items":{"type":"string"},"description":"The audit ids the recommendation rests on, so the offer names the actual problem instead of selling against a red pill."},"estimated_savings_ms":{"type":"integer","minimum":0,"description":"Total quantified saving across the customer's own opportunities.\n\n⛔ Sums `owner: site` rows **only**. Quoting a saving that included our own TTFB, and then selling dev time against it, would be the same defect as rendering \"Improve server response times\" on their dashboard — with a price attached."}}},"StackType":{"type":"string","description":"The application stack a site runs (docs/04 §1).\n\n`nextcloud`, `owncloud`, `headless_cms` and `php_app` are **own-fleet only** (docs/139, docs/564): we install them ourselves from each project's own distribution, and the tuning that makes them work — PHP extensions through CloudLinux's selector, a per-account ini, LVE caps, a crontab, a Redis ACL user — has no equivalent on a resold package. A site on one of those stacks whose placement is not our fleet is refused rather than provisioned as an empty account.\n\n`php_app` and `one_click` are the two halves of \"application hosting\" and are not interchangeable. `one_click` installs from a resold platform's own catalogue and can only be built on a resold deploy target; `php_app` installs from the application project's own release onto the Zinn® fleet, tuned per application, and can only be built there. The applications each offers are read from different endpoints — `/v1/hosting/applications` for the first, `/v1/hosting/fleet-applications` for the second.","enum":["static","php","wordpress","woocommerce","node","one_click","nextcloud","owncloud","headless_cms","php_app","python","ruby","dotnet"]},"StandaloneImageResult":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GeneratedImage"}},"unmet":{"type":"array","description":"What the chosen provider could not honour, in words for the customer. ⛔ Present and empty rather than absent when everything was honoured.","items":{"type":"string"}}}},"StartSmartUpdateRequest":{"type":"object","additionalProperties":false,"properties":{"plugins":{"type":"array","maxItems":500,"items":{"type":"string","maxLength":200},"description":"Plugin slugs to update; omitted = every plugin with an update."},"themes":{"type":"array","maxItems":200,"items":{"type":"string","maxLength":200},"description":"Theme slugs to update; omitted = every theme with an update."}}},"StatusPage":{"type":"object","required":["id","org_id","slug","title","monitor_ids","colours","theme","timezone","default_locale","published","fallback_url","public_url","hostname","hostname_status"],"properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"title":{"type":"string"},"intro":{"type":"string"},"monitor_ids":{"type":"array","items":{"type":"string"}},"colours":{"$ref":"#/components/schemas/StatusPageColours"},"theme":{"type":"string","enum":["auto","light","dark"]},"timezone":{"type":"string"},"default_locale":{"type":"string"},"show_response_times":{"type":"boolean"},"published":{"type":"boolean"},"logo":{"type":"string","description":"The stored logo's path (empty when none)."},"favicon":{"type":"string","description":"The stored favicon's path (empty when none)."},"hostname":{"type":"string","description":"The own address","empty when none.":null},"hostname_status":{"type":"string","enum":["","pending","active","failed"]},"hostname_records":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"value":{"type":"string"},"purpose":{"type":"string"}}}},"hostname_claim":{"description":"An own address asked for and not yet proven (STATUSHOST), with the TXT record that proves it; `null` when there is none.","oneOf":[{"$ref":"#/components/schemas/BrandHostnameClaim"},{"type":"null"}]},"fallback_url":{"type":"string"},"public_url":{"type":"string","description":"The own address once active","else the fallback.":null},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"StatusPageColours":{"type":"object","description":"Hex colours (#rrggbb). Text and background pairs need 4.5:1 contrast; brand needs 3:1 on the background.","properties":{"brand":{"type":"string"},"background":{"type":"string"},"text":{"type":"string"},"dark_background":{"type":"string"},"dark_text":{"type":"string"}}},"StatusPageInput":{"type":"object","properties":{"slug":{"type":"string","maxLength":48},"title":{"type":"string","maxLength":120},"intro":{"type":"string","maxLength":280},"monitor_ids":{"type":"array","maxItems":50,"items":{"type":"string","format":"uuid"}},"colours":{"$ref":"#/components/schemas/StatusPageColours"},"theme":{"type":"string","enum":["auto","light","dark"]},"timezone":{"type":"string","description":"An IANA name such as Europe/London."},"default_locale":{"type":"string","description":"One of the 58 public locales."},"show_response_times":{"type":"boolean"},"published":{"type":"boolean"}}},"StatusPageList":{"type":"object","required":["data","locales"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StatusPage"}},"locales":{"type":"array","items":{"type":"string"},"description":"The languages a status page can be shown in (its `default_locale` choices)."}}},"StatusPageSnapshot":{"type":"object","required":["slug","title","monitors","incidents","incident_total","generated_at"],"properties":{"slug":{"type":"string"},"title":{"type":"string"},"intro":{"type":"string"},"default_locale":{"type":"string"},"timezone":{"type":"string"},"theme":{"type":"string"},"colours":{"type":"object","additionalProperties":{"type":"string"}},"logo":{"type":"string"},"favicon":{"type":"string"},"show_response_times":{"type":"boolean"},"monitors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"state":{"type":"string"},"uptime_90d":{"type":"number","nullable":true},"uptime_30d":{"type":"number","nullable":true},"response_ms_24h":{"type":"integer","nullable":true},"days":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"uptime":{"type":"number","nullable":true}}}}}}},"incidents":{"type":"array","items":{"type":"object","properties":{"monitor":{"type":"string"},"started_at":{"type":"string","format":"date-time"},"ended_at":{"type":"string","format":"date-time","nullable":true},"duration_s":{"type":"integer"},"reason":{"type":"string"},"ongoing":{"type":"boolean"}}}},"incident_total":{"type":"integer"},"canonical":{"type":"string"},"generated_at":{"type":"string","format":"date-time"}}},"StatusSubscribeRequest":{"type":"object","additionalProperties":false,"description":"Ask for status updates by e-mail OR by webhook. ⛔ Exactly one of `email` and `endpoint` is accepted, decided by `kind`: sending the wrong one, or both, is a `422` rather than a silently ignored half — somebody subscribing an address, seeing a 202 and waiting for mail that was never going to come is the failure that refusal prevents.","properties":{"kind":{"type":"string","enum":["email","webhook"],"default":"email","description":"⚖️ Owner, 2026-09-03 - *\"on the status page can you set up webhook for updates for it\"*. `webhook` requires `endpoint`; `email` requires `email`."},"email":{"type":"string","format":"email"},"endpoint":{"type":"string","format":"uri","maxLength":500,"description":"An `https://` endpoint that will receive one signed JSON POST per incident update. ⛔ `https` only - the signature proves ORIGIN, not confidentiality, so a plain `http` endpoint would carry the incident stream in clear text.\n\n⛔⛔ **A machine cannot click a link, so consent is proved differently.** We POST a signed verification to this endpoint immediately; answering `2xx` to it is what confirms the subscription, and nothing else is sent until it does. That single act is also the health check - there is no separate test button and no separate `tested_at` to drift out of sync with reality.\n\nEvery POST carries `X-Zinn-Signature` (HMAC-SHA256 over `timestamp.body`), `X-Zinn-Timestamp` and `X-Zinn-Delivery`. Bind the timestamp into what you verify and reject anything older than a few minutes, or a captured body replays for ever."},"locale":{"type":"string","description":"Which language to send in. Falls back to English for an unknown code rather than refusing — a wrong language is a worse reason to reject a subscription than no language at all.","default":"en"}}},"StatusSubscribeResult":{"type":"object","required":["detail"],"properties":{"detail":{"type":"string"}}},"StorageBucket":{"type":"object","required":["id","name","ownership","vendor","status","bucket_name","has_credential","metered"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"The customer's own label, not the bucket's name at the vendor."},"ownership":{"type":"string","enum":["zinn","customer"],"description":"`zinn` is storage we operate and bill for; `customer` is the organisation's own bucket, which costs us nothing and is not metered against their allowance."},"vendor":{"type":"string","enum":["r2","s3","b2","bunny","gcore","minio"]},"status":{"type":"string","enum":["pending","active","suspended","failed"]},"bucket_name":{"type":"string"},"endpoint":{"type":"string"},"region":{"type":"string"},"public_base_url":{"type":"string","description":"Where a public object is readable. Empty means the bucket is private and its objects are reachable only through a presigned URL."},"bytes_stored":{"type":"integer","format":"int64"},"objects_stored":{"type":"integer","format":"int64"},"usage_measured_at":{"type":"string","format":"date-time","nullable":true,"description":"When the size above was last measured against the vendor. `null` means it has not been measured yet — which is not the same as empty."},"has_credential":{"type":"boolean","description":"Whether a stored key exists. The key and the Vault path it lives at are deliberately absent from this payload."},"metered":{"type":"boolean","description":"Whether this bucket's bytes count against `object_storage_gb`."},"created_at":{"type":"string","format":"date-time"}}},"StorageBucketWrite":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":120},"ownership":{"type":"string","enum":["zinn","customer"],"default":"zinn"},"vendor":{"type":"string","enum":["r2","s3","b2","bunny","gcore","minio"]},"bucket_name":{"type":"string","maxLength":255},"endpoint":{"type":"string","maxLength":255},"region":{"type":"string","maxLength":64},"public_base_url":{"type":"string","maxLength":255},"access_key_id":{"type":"string","maxLength":255,"writeOnly":true,"description":"Required for `ownership: customer`. Written to Vault, never to a column."},"secret_access_key":{"type":"string","maxLength":255,"writeOnly":true,"description":"Required for `ownership: customer`. Written to Vault, never to a column."}}},"StorageUsage":{"type":"object","required":["measured","bytes_stored","allowance_gb"],"properties":{"measured":{"type":"boolean","description":"Whether these figures are an observation. `false` means no bucket has been measured yet, so `bytes_stored` is a default and **must not** be drawn as \"using none of your allowance\" — an org with no buckets, an org whose buckets are empty and an org nobody has measured all report zero bytes, and only the last is a fault."},"measured_at":{"type":"string","format":"date-time","nullable":true},"bytes_stored":{"type":"integer","format":"int64","description":"Bytes across the buckets **we own**. A bucket of the customer's own costs us nothing and is deliberately excluded — counting it would charge them twice for storage we never provided."},"objects_stored":{"type":"integer","format":"int64"},"bucket_count":{"type":"integer"},"allowance_gb":{"type":"integer","nullable":true,"description":"The plan's `object_storage_gb` grant. `null` means no plan in the org chain sells storage at all, which is a different answer from a grant of zero."},"over_allowance_gb":{"type":"number","description":"GB beyond the allowance, or `0` — never negative."}}},"StoreConnectAuthorized":{"type":"object","required":["code","redirect_to","site_host","expires_at"],"properties":{"code":{"type":"string","description":"zouc_… — single use, ten minutes."},"redirect_to":{"type":"string","format":"uri","description":"The plugin's return URL; add `code` and `state`."},"site_host":{"type":"string"},"expires_at":{"type":"string","format":"date-time"}}},"StoreConnectStatus":{"allOf":[{"$ref":"#/components/schemas/StoreConnection"},{"type":"object","required":["campaigns_open","whatsapp_number"],"properties":{"campaigns_open":{"type":"boolean","description":"Zinn® Campaigns is open for this org."},"whatsapp_number":{"type":["string","null"],"pattern":"^\\+[1-9]\\d{6,14}$","description":"The store's OWN WhatsApp number (E.164), connected through Embedded Signup, for the plugin's \"message us on WhatsApp\" button and the PBS `zinn_ou.whatsapp_link` source. Never the Zinn® platform's own number. `null` = no number connected; the plugin hides the button instead of showing a broken link (docs/1297 §15.1)."}}}]},"StoreConnection":{"type":"object","description":"A store running Zinn® Order Updates, connected to an org (docs/1297 §4.4). Never the token.","required":["id","org_id","status","site_host","site_url","integrations","languages","plugin_version","wp_version","token_hint","connected_by","connected_at","last_seen_at"],"properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","revoked"]},"site_host":{"type":"string"},"site_url":{"type":"string"},"integrations":{"type":"array","items":{"type":"string"}},"languages":{"type":"array","maxItems":64,"items":{"type":"string"},"description":"The languages the store sells in, default first (docs/1297 §12.2): the template languages on offer."},"plugin_version":{"type":"string"},"wp_version":{"type":"string"},"token_hint":{"type":"string","description":"The token's last four characters."},"connected_by":{"type":"string"},"connected_at":{"type":"string","format":"date-time"},"last_seen_at":{"type":["string","null"],"format":"date-time"}}},"StoreConsentBatch":{"type":"object","required":["consents"],"properties":{"consents":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/StoreConsentInput"}}}},"StoreConsentInput":{"type":"object","required":["phone","channel","purpose","captured_at"],"properties":{"phone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$","description":"E.164."},"channel":{"type":"string","enum":["sms","whatsapp"]},"purpose":{"type":"string","enum":["updates","marketing"]},"ref":{"type":"string","maxLength":64,"description":"The order the tick was given on."},"captured_at":{"type":"string","format":"date-time"},"withdrawn":{"type":"boolean","default":false},"evidence":{"type":"object","maxProperties":10,"additionalProperties":{"type":"string","maxLength":500}}}},"StoreConsentsRecorded":{"type":"object","required":["recorded"],"properties":{"recorded":{"type":"integer"}}},"StoreEventBatch":{"type":"object","required":["events"],"properties":{"events":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/StoreEventInput"}}}},"StoreEventInput":{"type":"object","required":["id","kind","occurred_at"],"properties":{"id":{"type":"string","pattern":"^[A-Za-z0-9:._-]{1,200}$","description":"The idempotency key."},"kind":{"type":"string","pattern":"^[a-z_]{1,40}$","description":"order_received, payment_confirmed, on_hold, shipped, completed, ready_for_pickup, payment_failed, cancelled or refunded; the Campaigns flow kinds cart_abandoned, cart_recovered, order_placed and product_viewed; any other kind is stored and skipped."},"occurred_at":{"type":"string","format":"date-time"},"integration":{"type":"string","maxLength":40},"ref":{"type":"string","maxLength":64},"order_number":{"type":"string","maxLength":32},"locale":{"type":"string","maxLength":16,"description":"The shopper's language (BCP 47), e.g. ar."},"store_name":{"type":"string","maxLength":40},"tracking_url":{"type":"string","maxLength":300},"pay_url":{"type":"string","maxLength":300,"description":"The payment_failed pay-again link, in the shopper's language."},"order_url":{"type":"string","maxLength":300,"description":"The shopper's order page on the store, in their language (Tranzly, WPML, Polylang or TranslatePress adapt it). Appended to order_received and completed messages; omit it and the message carries no link."},"customer":{"type":"object","properties":{"first_name":{"type":"string","maxLength":40},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$","description":"E.164."},"email":{"type":"string","maxLength":254,"description":"The shopper's address, for the flow kinds only; used to find the contact, never kept."}}},"cart_key":{"type":"string","maxLength":64,"description":"The store's cart reference (cart_abandoned","cart_recovered).":null},"cart_url":{"type":"string","maxLength":300,"description":"The shopper's restore-cart link. Kept as the contact's {{cart_url}} only when it is https on the store's own host."},"product":{"type":"object","description":"The product viewed (product_viewed).","properties":{"name":{"type":"string","maxLength":120},"url":{"type":"string","maxLength":300}}},"marketing_consent":{"type":"object","description":"The shopper's marketing tick, as the store captured it. A flow enrols only when `ticked` is true, `channel` is email and `captured_at` is at or before `occurred_at`.","properties":{"ticked":{"type":"boolean"},"channel":{"type":"string","maxLength":16},"captured_at":{"type":"string","format":"date-time"},"wording_version":{"type":"string","maxLength":40},"wording":{"type":"string","maxLength":500,"description":"The words beside the box the shopper saw."}}},"totals":{"type":"object","required":["minor","currency"],"properties":{"minor":{"type":"integer","description":"Integer minor units."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}}},"refund":{"type":"object","required":["minor","currency"],"properties":{"minor":{"type":"integer","description":"Integer minor units."},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}}}}},"StoreEventsAccepted":{"type":"object","required":["accepted","duplicates"],"properties":{"accepted":{"type":"integer","description":"Events being sent now."},"duplicates":{"type":"integer","description":"Events already handled (never sent twice)."}}},"StoreOrderMessage":{"type":"object","required":["id","kind","source","outcome","reason","channel","locale","to","occurred_at","processed_at","delivery","parts"],"properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string"},"source":{"type":"string","enum":["store","staff"],"description":"`store` = the order's own status change; `staff` = sent by hand."},"outcome":{"type":"string","enum":["pending","processing","sent","skipped","failed"]},"reason":{"type":"string","description":"Why it was not sent (a refusal code) or how it failed (a failure class); empty when sent."},"channel":{"type":"string","enum":["sms","whatsapp"]},"locale":{"type":"string","description":"The language it went out in; empty until sent."},"to":{"type":"string","description":"The shopper's number, last three digits only."},"occurred_at":{"type":"string","format":"date-time"},"processed_at":{"type":"string","format":"date-time","nullable":true},"delivery":{"type":"string","nullable":true,"description":"The carrier's receipt for a sent text: `awaiting`, `delivered`, `failed` or `unconfirmed`; null when nothing was sent."},"parts":{"type":"integer","nullable":true,"description":"SMS parts billed; null when nothing was sent."}}},"StoreOrderMessages":{"type":"object","required":["ref","templates","messages"],"properties":{"ref":{"type":"string"},"templates":{"type":"array","description":"The approved kinds `sendStoreOrderUpdate` accepts.","items":{"type":"string","enum":["order_received","payment_confirmed","on_hold","shipped","completed","ready_for_pickup","payment_failed","cancelled","refunded"]}},"messages":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/StoreOrderMessage"}}}},"StoreOrderUpdateBooked":{"type":"object","required":["id","kind","outcome","duplicate"],"properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string"},"outcome":{"type":"string","enum":["pending","processing","sent","skipped","failed"]},"duplicate":{"type":"boolean","description":"The request_id was seen before; nothing new was booked."}}},"StoreOrderUpdateInput":{"type":"object","required":["kind","request_id"],"properties":{"kind":{"type":"string","enum":["order_received","payment_confirmed","on_hold","shipped","completed","ready_for_pickup","payment_failed","cancelled","refunded"]},"request_id":{"type":"string","pattern":"^[A-Za-z0-9._-]{8,64}$","description":"Idempotency key per order, across every `kind`: a reused id returns the first update and books nothing."},"tracking_url":{"type":"string","format":"uri","maxLength":300,"description":"An absolute https URL whose host is a public DNS name (not percent-encoded, not an IP literal, loopback or bare name; punycode allowed), a numeric port 1-65535 if any, no userinfo, no space, separator or control character of any script (422 `urlInvalid` otherwise); replaces the order's tracking link for a `shipped` update."}}},"StorePeopleBatch":{"type":"object","required":["people"],"properties":{"people":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/StorePersonInput"}},"soft_opt_in":{"type":"object","description":"Present only when the store switched the e-mail soft opt-in on. The opt-out it gave at collection, in full (at least 20 characters), kept as evidence.","required":["opt_out_statement"],"properties":{"opt_out_statement":{"type":"string","minLength":20,"maxLength":500}}}}},"StorePeopleSummary":{"type":"object","required":["sources"],"properties":{"sources":{"type":"array","items":{"type":"object","required":["source","count","hash"],"properties":{"source":{"type":"string"},"count":{"type":"integer"},"hash":{"type":"string","pattern":"^[0-9a-f]{16}$"}}}}}},"StorePeopleSynced":{"type":"object","required":["upserted","created","deleted","suppressed","soft_opt_in","limit_reached","rejected"],"properties":{"upserted":{"type":"integer"},"created":{"type":"integer"},"deleted":{"type":"integer"},"suppressed":{"type":"integer","description":"Upserted people whose contact is suppressed."},"soft_opt_in":{"type":"integer","description":"E-mail soft opt-ins written by this batch."},"limit_reached":{"type":"boolean"},"rejected":{"type":"array","items":{"type":"object","required":["index","code"],"properties":{"index":{"type":"integer"},"code":{"type":"string","enum":["itemInvalid","opInvalid","sourceInvalid","externalIdInvalid","emailInvalid","contactLimit"]}}}}}},"StorePersonInput":{"type":"object","required":["source","external_id"],"properties":{"op":{"type":"string","enum":["upsert","delete","erase"],"default":"upsert"},"source":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,31}$","description":"wp_user, woo_customer or an integration key."},"external_id":{"type":"string","pattern":"^[A-Za-z0-9:._-]{1,64}$","description":"The store's own id for the person."},"email":{"type":"string","maxLength":254,"description":"Required for upsert."},"phone":{"type":"string","description":"E.164; any other value is ignored."},"first_name":{"type":"string","maxLength":80},"last_name":{"type":"string","maxLength":80},"locale":{"type":"string","maxLength":16},"role":{"type":"string","maxLength":80},"country":{"type":"string","maxLength":80},"registered_at":{"type":"string","format":"date-time"},"order_count":{"type":"integer","minimum":0},"paid_orders":{"type":"integer","minimum":0,"description":"Orders the customer paid for; the soft opt-in needs at least 1."},"total_spent":{"type":"object","required":["amount_minor","currency"],"properties":{"amount_minor":{"type":"integer","minimum":0},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}}},"last_order_at":{"type":"string","format":"date-time"}}},"StoreShopper":{"type":"object","required":["phone","consents","messages"],"properties":{"phone":{"type":"string"},"consents":{"type":"array","items":{"type":"object","required":["channel","purpose","active","changed_at"],"properties":{"channel":{"type":"string","enum":["sms","whatsapp"]},"purpose":{"type":"string","enum":["updates","marketing"]},"active":{"type":"boolean"},"changed_at":{"type":"string","format":"date-time"}}}},"messages":{"type":"array","maxItems":20,"items":{"type":"object","required":["kind","ref","order_number","channel","locale","sent_at"],"properties":{"kind":{"type":"string","description":"The event kind, e.g. order_received, order_shipped."},"ref":{"type":"string"},"order_number":{"type":"string"},"channel":{"type":"string","enum":["sms","whatsapp"]},"locale":{"type":"string","description":"The language the text went out in."},"sent_at":{"type":"string","format":"date-time"}}}}}},"StoreShopperQuery":{"type":"object","required":["phone"],"properties":{"phone":{"type":"string","description":"E.164, the signed-in shopper's own number."}}},"StoreSupportTicket":{"type":"object","required":["reference","kind","subject","status","state","created_at","last_message_at","latest_reply"],"properties":{"reference":{"type":"string","example":"ZT-7KQ3MX"},"kind":{"type":"string","enum":["help","bug","feedback","feature_request"]},"subject":{"type":"string"},"status":{"type":"string","enum":["open","pending","solved","closed"]},"state":{"type":"string","enum":["waiting_on_us","waiting_on_you","answered","closed"],"description":"What the plugin shows (it translates the label)."},"created_at":{"type":"string","format":"date-time"},"last_message_at":{"type":["string","null"],"format":"date-time"},"latest_reply":{"description":"Support's latest public reply, in the customer's language; null before one.","oneOf":[{"type":"object","required":["body","at"],"properties":{"body":{"type":"string"},"at":{"type":"string","format":"date-time"}}},{"type":"null"}]}}},"StoreSupportTicketInput":{"type":"object","required":["subject","message"],"properties":{"kind":{"type":"string","enum":["help","bug","feedback","feature_request"],"default":"help"},"subject":{"type":"string","maxLength":200},"message":{"type":"string","maxLength":20000},"email":{"type":"string","format":"email","maxLength":320,"description":"A reply address; default the member who approved the store."},"name":{"type":"string","maxLength":200},"locale":{"type":"string","maxLength":16},"consent_diagnostics":{"type":"boolean","default":false},"diagnostics":{"$ref":"#/components/schemas/PluginSupportDiagnostics"},"deflection_id":{"description":"The AI answer read first (`deflectPublicSupportQuestion`); stale ids are ignored.","oneOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]}}},"StoreSupportTicketList":{"type":"object","required":["items","next_before","answered"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/StoreSupportTicket"}},"next_before":{"type":["string","null"]},"answered":{"type":"integer","minimum":0}}},"StoredVideo":{"type":"object","required":["id","name","state"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["idle","processing","ready","failed"]},"duration_seconds":{"type":"integer","nullable":true,"description":"⛔ `null`, never `0`, while the provider has not measured it. Rendering a missing duration as `0:00` reads as a broken upload."},"size_bytes":{"type":"integer","nullable":true},"playback_url":{"type":"string"},"poster_url":{"type":"string"},"created_at":{"type":"string","format":"date-time","nullable":true}}},"StoredVideoList":{"type":"object","required":["videos"],"properties":{"videos":{"type":"array","items":{"$ref":"#/components/schemas/StoredVideo"}}}},"Subscription":{"type":"object","description":"An organization's subscription to a plan version. It pins the exact version and carries the **captured** price + entitlements — a purchase-time snapshot that later catalog or FX changes never alter (docs/05 §1).","required":["id","org_id","status","plan","price","interval","entitlements","current_period_start","current_period_end","auto_renew","started_at","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"org_id":{"$ref":"#/components/schemas/Uuid"},"status":{"$ref":"#/components/schemas/SubscriptionStatus"},"plan":{"$ref":"#/components/schemas/SubscriptionPlanRef"},"kind":{"type":"string","enum":["plan","item"],"description":"What this subscription pays for. `plan` is a hosting (or other) plan; `item` bills one machine or managed database bought on its own order line.\n\n⚖️ **An org may hold ANY NUMBER of live `plan` subscriptions** — several on the same product line included (owner ruling 2026-09-28, ADR 0036). Buying a plan never cancels another; only an explicit plan change or an order naming `replaces_subscription_id` replaces one. So a client lists every live `plan` row rather than picking one."},"price":{"description":"The captured price the subscriber pays (minor units + code, §2.8).","allOf":[{"$ref":"#/components/schemas/MoneyAmount"}]},"interval":{"type":"string","enum":["monthly","annual"]},"entitlements":{"type":"object","additionalProperties":true,"description":"The resolved entitlements captured at purchase (feature/quota map)."},"current_period_start":{"type":"string","format":"date-time"},"current_period_end":{"type":"string","format":"date-time"},"auto_renew":{"type":"boolean","description":"Whether this subscription charges again at `current_period_end`. `false` does not mean it has ended: it runs to the end of the period already paid for and is then `expired`. Changed with `POST /v1/subscriptions/{subscriptionId}/auto-renew` — the only renewal flag a customer can move."},"billing_rail":{"type":"string","enum":["engine","paypal"],"description":"**Which clock decides when this subscription is charged** (W41-G, ADR 0029). `engine` is the default and is what ADR 0011 describes: the engine decides money is due, mints an order and charges off-session. `paypal` means the customer approved a PayPal subscription agreement and PayPal drives the *timing* — the engine still owns what is owed, tax, entitlements, dunning and suspension.\n\n⛔ A client must branch on this. `POST /v1/subscriptions/{subscriptionId}/prepay` is refused on the `paypal` rail, because extending the engine's period while PayPal went on charging its own schedule would bill the customer twice for the same months."},"started_at":{"type":"string","format":"date-time"},"canceled_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"periods_owed":{"type":"integer","minimum":0,"description":"How many whole billing periods must still be paid before this subscription may resume — every missed period **and** the current one (W43-107, owner ruling 2026-09-15). `0` when it is paid through a future date. A payment for one old period never reinstates a subscription that owes several, whichever way it is paid (card, crypto, bank transfer or a staff-applied credit): each renewal order settles one period and the next is issued at once, and the service resumes only when the last one is paid. While this is above zero, `POST /v1/subscriptions/{subscriptionId}/prepay` accepts only `periods >= periods_owed` (pay everything owed) and answers `422` with code `ARREARS_OUTSTANDING` for fewer."},"arrears":{"description":"What is still owed and what the last payment covered; `null` when nothing is owed.","oneOf":[{"$ref":"#/components/schemas/SubscriptionArrears"},{"type":"null"}]},"comped":{"type":"boolean","description":"`true` when staff have comped this subscription indefinitely: it bills nothing, so there is nothing to renew or pay in advance (`GET /v1/subscriptions/{subscriptionId}/prepay-quote` answers `422 NOT_PREPAYABLE`). A client hides \"pay in advance\" for it — and for a zero-priced plan — instead of asking for a quote it knows will be refused (s1014 DASHBUDGET)."}}},"SubscriptionArrears":{"type":"object","description":"What a subscription in arrears still owes, and what its last payment covered (s1014 R40, docs/747 §2a). The debt is derived from `current_period_end`, never stored twice.","required":["state","debt","periods_owed","owed_from","owed_until","amount_owed","unit_amount","notice","last_payment"],"properties":{"state":{"type":"string","enum":["behind","owing"],"description":"`behind`: billing periods are unpaid — services pause (or are paused) until every one is paid. `owing` (GAP-9): paid up and online, but a recorded debt is open; the next payment pays it first."},"debt":{"description":"A recorded debt still open (GAP-9, docs/747 §2c): service the customer already had, brought back by staff while owed. Every order for this subscription's time carries it and pays it first. `null` when none.","oneOf":[{"$ref":"#/components/schemas/SubscriptionDebt"},{"type":"null"}]},"periods_owed":{"type":"integer","minimum":0},"owed_from":{"type":"string","format":"date-time"},"owed_until":{"type":"string","format":"date-time"},"amount_owed":{"description":"Net amount owed for every unpaid period plus any open recorded debt (before tax).","allOf":[{"$ref":"#/components/schemas/MoneyAmount"}]},"unit_amount":{"allOf":[{"$ref":"#/components/schemas/MoneyAmount"}]},"notice":{"type":"boolean","description":"Whether the billing page shows the post-payment arrears banner to this org (the arrears-notice switch, BRIEF 28: off / internal / on)."},"last_payment":{"description":"The most recent payment applied to this subscription, or `null`.","oneOf":[{"$ref":"#/components/schemas/SubscriptionPaymentOutcome"},{"type":"null"}]}}},"SubscriptionAutoRenewRequest":{"type":"object","description":"The renewal switch. `auto_renew` is **required** rather than defaulted: a missing field on a control that decides whether somebody is charged again must be a 422, never an assumed \"on\".","required":["auto_renew"],"additionalProperties":false,"properties":{"auto_renew":{"type":"boolean","description":"`true` to charge again at `current_period_end`; `false` to run to the end of the paid period and then expire."}}},"SubscriptionDebt":{"type":"object","required":["amount","owed_from","owed_until"],"properties":{"amount":{"description":"Net amount still owed (before tax), integer minor units (§2.8).","allOf":[{"$ref":"#/components/schemas/MoneyAmount"}]},"owed_from":{"type":"string","format":"date-time"},"owed_until":{"type":"string","format":"date-time"}}},"SubscriptionPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Subscription"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"SubscriptionPaymentOutcome":{"type":"object","required":["at","covered_from","covered_to","outcome"],"properties":{"at":{"type":"string","format":"date-time"},"covered_from":{"type":"string","format":"date-time"},"covered_to":{"type":"string","format":"date-time"},"outcome":{"type":"string","enum":["extended","still_lapsed","not_moved","debt_paid"],"description":"`extended`: paid through a future date. `still_lapsed`: the date moved but is still in the past (or a recorded debt keeps the services paused), so services stay paused. `not_moved`: the date did not move. `debt_paid` (GAP-9): the payment settled a recorded debt and the subscription is paid through a future date."}}},"SubscriptionPlanChangeResult":{"type":"object","description":"What the subscription plan change actually did. ⛔ Stated from what happened rather than from what was asked for: `charged_minor` is what the gateway captured and the slot figures are read back from the old and the new subscription rows.\n\n⭐⭐ `slots_before` / `slots_after` exist because the worst outcome on this path is a change that answers `200` and silently does not take effect, and a status code cannot tell that apart from one that worked. They are the plan's `max_sites` entitlement as each `Subscription` row itself captured it — the same value the site-create path reads when the customer tries to use their new room.\n\n⛔ `null` is a real answer and is **not** zero. A plan stating no `max_sites` has an *unknown* allowance; a plan selling unlimited sites is a third thing again, which is what the `*_unlimited` flags carry. A client that reads a null with the flag false must say \"no stated limit\" and must never draw a full meter.","required":["plan_code","plan_name","plan_version_id","subscription_id","order_id","charged_minor","credited_minor","package_type","slots_before","slots_after","slots_before_unlimited","slots_after_unlimited","quote"],"additionalProperties":false,"properties":{"plan_code":{"type":"string","description":"The plan this subscription is now on."},"plan_name":{"type":"string","description":"Its catalogue name, so a receipt can name it without a second lookup."},"plan_version_id":{"type":"string","description":"The priced version the new subscription carries."},"subscription_id":{"type":"string","description":"The **new** subscription. A plan change supersedes rather than mutates, because a subscription pins the exact version it was sold — so this id differs from the one in the request path, and a client holding the old one must replace it."},"order_id":{"type":"string","description":"The order the charge was raised against, or `\"\"` when the change resulted in a credit and no order was minted."},"charged_minor":{"type":"integer","minimum":0,"description":"What was actually taken, in minor units."},"credited_minor":{"type":"integer","minimum":0,"description":"What was actually returned as account balance, in minor units."},"package_type":{"type":"string","description":"The vendor package type, read back after the move. `\"\"` on our own fleet and `\"\"` when the subscription entitles no site — there is no package to move."},"slots_before":{"type":"integer","nullable":true,"minimum":0,"description":"The site allowance the subscription held before the change."},"slots_after":{"type":"integer","nullable":true,"minimum":0,"description":"The site allowance it holds now."},"slots_before_unlimited":{"type":"boolean","description":"The old plan sold unlimited sites, so `slots_before` is null by design."},"slots_after_unlimited":{"type":"boolean","description":"The new plan sells unlimited sites, so `slots_after` is null by design."},"quote":{"allOf":[{"$ref":"#/components/schemas/SitePlanQuote"}],"description":"The quote the change was performed against."}}},"SubscriptionPlanRef":{"type":"object","description":"The pinned plan version a subscription was sold (a purchase-time snapshot).","required":["code","name","product_line","version"],"properties":{"code":{"type":"string","description":"The plan's code (e.g. `pbn_25`).","example":"pbn_25"},"name":{"type":"string","example":"PBN 25"},"product_line":{"type":"string","description":"The product line the plan belongs to (e.g. `footprint_free`).","example":"footprint_free"},"version":{"type":"integer","minimum":1,"description":"The pinned plan-version number."}}},"SubscriptionRenewalOptions":{"type":"object","description":"One subscription's renewal card: its crypto auto-renew state and its one-period prepay quote (or why it cannot be prepaid).","required":["subscription_id","crypto_auto_renew","prepay_quote","prepay_refusal_code","prepay_refusal_message"],"properties":{"subscription_id":{"$ref":"#/components/schemas/Uuid"},"crypto_auto_renew":{"$ref":"#/components/schemas/CryptoAutoRenewState"},"prepay_quote":{"description":"The quote for one period, or null when it cannot be prepaid.","oneOf":[{"$ref":"#/components/schemas/PrepayQuote"},{"type":"null"}]},"prepay_refusal_code":{"type":["string","null"],"description":"Why it cannot be prepaid (`NOT_PREPAYABLE`, `RAIL_NOT_SUPPORTED`, `ARREARS_OUTSTANDING`, …) — the code the single quote's 422 carries. Null when `prepay_quote` is set."},"prepay_refusal_message":{"type":["string","null"],"description":"The sentence that goes with `prepay_refusal_code`."}}},"SubscriptionRenewalOptionsPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SubscriptionRenewalOptions"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"SubscriptionStatus":{"type":"string","description":"A subscription's lifecycle state (docs/05 §1).","enum":["trialing","active","past_due","canceled","expired"]},"SupportRecommendation":{"type":"object","description":"One thing the support AI told a customer, and whether they did it.","required":["id","kind","state","finding_code","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"site_id":{"type":"string"},"ticket_id":{"type":"string","description":"The ticket that surfaced it, or empty. ⛔ Usually empty, and that is the interesting case: the commonest diagnosis runs before any ticket exists."},"kind":{"$ref":"#/components/schemas/SupportRecommendationKind"},"state":{"$ref":"#/components/schemas/SupportRecommendationState"},"finding_code":{"type":"string","description":"The diagnostic finding, e.g. `lve_ep_faults`, `php_version_eol`."},"message_key":{"type":"string","description":"The i18n key of the sentence the customer was shown. ⛔ Never the sentence — the row is read back months later, possibly in another language."},"evidence":{"type":"object","additionalProperties":true,"description":"The measurement behind the advice — fault counts, the window, the tier."},"current_tier":{"type":"string"},"advised_tier":{"type":"string"},"remedy_key":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"notified_at":{"type":["string","null"],"format":"date-time"},"acted_at":{"type":["string","null"],"format":"date-time"},"ignored_at":{"type":["string","null"],"format":"date-time"},"dismissed_at":{"type":["string","null"],"format":"date-time"},"dismissed_by":{"type":"string"},"dismissal_reason":{"type":"string"}}},"SupportRecommendationKind":{"type":"string","enum":["upgrade_plan","customer_action","fix_applied"],"description":"Why the platform said something. `upgrade_plan` — the site needs a bigger plan; `customer_action` — something only the customer can do; `fix_applied` — we fixed it ourselves. Only the first two can be ignored."},"SupportRecommendationState":{"type":"string","enum":["open","acted","ignored","dismissed","superseded"],"description":"`ignored` is **measured**, never typed by a person: it is set automatically after the grace period with no plan change and no fix. A staff member who disagrees uses `dismissed`, which records who decided and why."},"Survey":{"type":"object","required":["id","name","questions","running","archived"],"properties":{"id":{"type":"string"},"name":{"type":"string","maxLength":400},"description":{"type":"string"},"archived":{"type":"boolean"},"running":{"type":"boolean","description":"Launched, not stopped, not archived."},"start_date":{"type":"string","nullable":true},"end_date":{"type":"string","nullable":true},"response_count":{"type":"integer","description":"How many answers WE hold for it. ⛔ Ours, not the vendor's — the number on the screen and the rows in the CSV must be the same number (§2.52)."},"questions":{"type":"array","items":{"$ref":"#/components/schemas/SurveyQuestion"}},"targeting":{"$ref":"#/components/schemas/SurveyTargeting"}}},"SurveyAnswer":{"type":"object","required":["answer"],"properties":{"question":{"type":"string","maxLength":1000,"description":"The question AS ASKED, copied rather than resolved later — a rename must not relabel a year of history."},"type":{"type":"string","maxLength":32},"answer":{"description":"A string, a number, or a flat array of strings. ⛔ Nested objects are refused: they are an arbitrary blob on our primary database from an authenticated client, and unreadable in the spreadsheet the export exists for.","oneOf":[{"type":"string","maxLength":4000},{"type":"number"},{"type":"array","items":{"type":"string","maxLength":4000}}]}}},"SurveyQuestion":{"type":"object","description":"One question. ⛔ `type` is a CLOSED set, deliberately narrower than the vendor's — we own the renderer now, and a type the dashboard cannot draw renders as an empty card that records a `survey shown` and cannot be answered.","required":["type","question"],"properties":{"type":{"type":"string","enum":["open","single_choice","multiple_choice","rating","link"]},"question":{"type":"string","maxLength":1000},"description":{"type":"string","maxLength":2000},"choices":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":200}},"scale":{"type":"integer","enum":[5,10],"description":"`rating` only. Ignored by every other type."},"lower_bound_label":{"type":"string","maxLength":100},"upper_bound_label":{"type":"string","maxLength":100},"link":{"type":"string","maxLength":500},"optional":{"type":"boolean"}}},"SurveyResponseAck":{"type":"object","required":["recorded","duplicate"],"properties":{"recorded":{"type":"boolean"},"duplicate":{"type":"boolean","description":"True when this person had already answered. ⛔ Reported as a success, not a conflict — the commonest cause is a retry after a dropped connection, and telling the customer it failed makes them answer again."},"id":{"type":"string"}}},"SurveyResponseCreate":{"type":"object","required":["answers"],"properties":{"org_id":{"type":"string","maxLength":64},"distinct_id":{"type":"string","maxLength":200,"description":"The browser's analytics distinct id. ⛔ Without it the mirrored event attaches to a person who does not exist, and the join looks healthy and is empty."},"path":{"type":"string","maxLength":200},"answers":{"type":"array","minItems":1,"maxItems":20,"items":{"$ref":"#/components/schemas/SurveyAnswer"}}}},"SurveyTargeting":{"type":"object","description":"WHERE and WHEN a survey appears — the owner's *\"decide which pages they pop up on\"*. Stored inside the vendor's record but evaluated entirely by us.","properties":{"routes":{"type":"array","maxItems":50,"description":"Route patterns matched against the app's own pathname. `*` is the only wildcard and is matched as a GLOB, never compiled to a regular expression — these come from an admin form, and `new RegExp(pattern)` on that input is a catastrophic-backtracking denial of service pointed at the customer's browser. ⛔ EMPTY MEANS EVERY ROUTE.","items":{"type":"string","maxLength":200}},"events":{"type":"array","maxItems":20,"description":"Event names that ARM the survey. Empty means no trigger is needed. ⛔ Events arm; routes scope. A survey with events and no routes appears wherever the customer happens to be when the event fires.","items":{"type":"string","maxLength":100}},"sampling_percent":{"type":"integer","minimum":1,"maximum":100,"description":"Percentage of eligible people who see it. The client's die is a stable hash of the person and the survey, never a fresh random — a fresh roll on every render makes a customer at 10% near-certain to be picked over a session."},"wait_period_days":{"type":"integer","minimum":0,"maximum":365,"description":"Days before the same person may see ANY survey again."},"responses_limit":{"type":"integer","nullable":true,"minimum":1}}},"SyndicationChannel":{"type":"object","description":"One channel the platform can post to (docs/201 §1).","required":["key","auth_kind","tier","connect_fields","capabilities","character_limit","cost_per_link_post_micros","warning_code"],"properties":{"key":{"type":"string","example":"bluesky"},"auth_kind":{"type":"string","description":"`webhook` (paste a URL), `token` (paste a key) or `oauth` (click Connect — we hold the approved app, so it is one click rather than a developer portal).","enum":["webhook","token","oauth"]},"tier":{"type":"string","description":"`open` works the day it ships; `review` means our app is in review and the customer may bring their own meanwhile; `byo` means the customer's own app always, by ruling (Reddit).","enum":["open","review","byo"]},"connect_fields":{"type":"array","description":"⛔ `connect_fields`, not `fields` — `Serializer.fields` is DRF's own bound-field mapping and a wire field with that name shadows machinery inside the framework.","items":{"$ref":"#/components/schemas/SyndicationConnectField"}},"capabilities":{"type":"array","description":"`syndication:*` ids this channel genuinely has. A field the channel cannot carry is reported on the post's `dropped`, never silently omitted.","items":{"type":"string"}},"character_limit":{"type":"integer","nullable":true,"description":"⛔ `null` means \"no meaningful limit\", NOT unlimited. The number is given to the writer; nothing is ever truncated to fit it."},"cost_per_link_post_micros":{"type":"integer","minimum":0,"description":"What one LINK-bearing post costs us, in USD micros. Ours always carries a link, so this — never a headline per-post price — is what a credit line is priced on. X is 200000 (\\$0.20) against 15000 without a link."},"warning_code":{"type":"string","description":"A machine code for a warning the UI must show ABOVE the connect button, or \"\". `reddit_link_posts`, `instagram_no_link`."}}},"SyndicationChannelList":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SyndicationChannel"}}}},"SyndicationConnectField":{"type":"object","required":["name","label_code","secret","is_required"],"properties":{"name":{"type":"string","example":"app_password"},"label_code":{"type":"string","description":"⛔ A code, never a sentence — the dashboard owns the words, in 58 locales."},"secret":{"type":"boolean","description":"A secret value goes to Vault and is never returned by this API."},"is_required":{"type":"boolean","description":"⛔ `is_required`, not `required` — `Field.required` is DRF's own attribute."}}},"SyndicationConnection":{"type":"object","description":"One connected social account, scoped to the ORGANISATION. ⛔ There is no field here a credential could live in.","required":["id","channel","name","target","status","account_ref","verify_error","verified_at","expires_at","byo","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"channel":{"type":"string"},"name":{"type":"string","description":"The customer's own name for it. ⛔ `name` on the wire, `label` on the model: `Field.label` is DRF's own attribute and shadowing it is silent at runtime."},"target":{"type":"string","description":"The non-secret half — a handle, an instance, a board id."},"status":{"type":"string","description":"⛔⛔ `needs_reconnect` is NOT a failure — the credential lapsed and only the customer can fix it. `unverified` means we have not looked, which is a third fact and not a quiet green.","enum":["unverified","ready","needs_reconnect","error"]},"account_ref":{"type":"string","description":"The account the VENDOR said this credential belongs to — discovered."},"verify_error":{"type":"string","description":"A machine code the dashboard turns into copy. Never a sentence."},"verified_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true,"description":"⛔ `null` means **no stated expiry**, which is a different fact from \"never expires\" and must not render as an unqualified green."},"byo":{"type":"boolean","description":"Whether the customer supplied their own developer app."},"created_at":{"type":"string","format":"date-time"}}},"SyndicationConnectionCreate":{"type":"object","required":["channel","name","credentials"],"properties":{"channel":{"type":"string","maxLength":32},"name":{"type":"string","minLength":1,"maxLength":120},"credentials":{"type":"object","writeOnly":true,"additionalProperties":{"type":"string"},"description":"Every value the channel's `fields` name. The secret half goes to Vault and is never returned."},"byo":{"type":"boolean","default":false}}},"SyndicationConnectionPage":{"type":"object","required":["items","total"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SyndicationConnection"}},"total":{"type":"integer","minimum":0}}},"SyndicationConnectionUpdate":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"credentials":{"type":"object","writeOnly":true,"additionalProperties":{"type":"string"},"description":"⛔ Omit to KEEP the stored credential. Sending it replaces the secret half."}}},"SyndicationPlan":{"type":"object","required":["id","scope","post_id","recipe_id","enabled","write_mode","approval_mode","channels","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"scope":{"type":"string","description":"Most specific wins — an article's own plan beats its recipe's beats the org default.","enum":["post","recipe","org_default"]},"post_id":{"type":"string","format":"uuid","nullable":true},"recipe_id":{"type":"string","format":"uuid","nullable":true},"enabled":{"type":"boolean"},"write_mode":{"type":"string","description":"⚖️ Owner ruling 2026-08-20 — the AI writes per channel by default, because an X post and a LinkedIn update are not the same piece of writing.","enum":["ai_per_channel","one_text"]},"approval_mode":{"type":"string","description":"⚖️ Owner ruling 2026-08-20 — hold for approval by default.","enum":["hold","send"]},"channels":{"type":"array","items":{"$ref":"#/components/schemas/SyndicationPlanChannel"}},"created_at":{"type":"string","format":"date-time"}}},"SyndicationPlanChannel":{"type":"object","required":["connection_id","channel","name","status"],"properties":{"connection_id":{"type":"string","format":"uuid"},"channel":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"}}},"SyndicationPlanPage":{"type":"object","required":["items","total"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SyndicationPlan"}},"total":{"type":"integer","minimum":0}}},"SyndicationPlanWrite":{"type":"object","required":["scope"],"properties":{"scope":{"type":"string","enum":["post","recipe","org_default"]},"post_id":{"type":"string","format":"uuid","nullable":true},"recipe_id":{"type":"string","format":"uuid","nullable":true},"enabled":{"type":"boolean","default":true},"write_mode":{"type":"string","enum":["ai_per_channel","one_text"],"default":"ai_per_channel"},"approval_mode":{"type":"string","enum":["hold","send"],"default":"hold"},"connection_ids":{"type":"array","items":{"type":"string","format":"uuid"}}}},"SyndicationPost":{"type":"object","description":"One post to one channel, settled independently of every sibling.","required":["id","channel","connection_id","connection_label","status","text","remote_url","dropped","error","cost_micros","character_limit","posted_at"],"properties":{"id":{"type":"string","format":"uuid"},"channel":{"type":"string"},"connection_id":{"type":"string","format":"uuid","nullable":true},"connection_label":{"type":"string"},"status":{"type":"string","description":"⛔⛔ `needs_reconnect` is NOT `failed`. `skipped` means the customer said no or the connection was removed — nothing went wrong.","enum":["drafting","awaiting_approval","queued","posted","failed","needs_reconnect","skipped"]},"text":{"type":"string"},"remote_url":{"type":"string","description":"The live post, read back from the channel where it returns one. ⛔ Empty where the vendor gives us nothing to build a URL from (a Slack incoming webhook answers the literal string `ok`) — empty is honest, a composed link would 404."},"dropped":{"type":"array","description":"`[[field, reason], …]` — what this channel could not carry, and WHY. The reason travels: \"no image endpoint\" and \"the upload was refused\" are different problems with different next steps.","items":{"type":"array","items":{"type":"string"}}},"error":{"type":"string","description":"A machine code, never a sentence."},"cost_micros":{"type":"integer","minimum":0,"description":"What this post cost us, in USD micros. One line per channel per post."},"character_limit":{"type":"integer","nullable":true},"posted_at":{"type":"string","format":"date-time","nullable":true}}},"SyndicationPostEdit":{"type":"object","required":["text"],"properties":{"text":{"type":"string"}}},"SyndicationRun":{"type":"object","description":"One article's fan-out.","required":["id","placement_id","post_title","article_url","status","posts","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"placement_id":{"type":"string","format":"uuid"},"post_title":{"type":"string"},"article_url":{"type":"string","description":"The article's REAL live URL, read back from the destination when it published. ⛔ Never a composed URL — the permalink structure belongs to the customer."},"status":{"type":"string","description":"⛔ `complete` means every channel SETTLED, not that every channel succeeded.","enum":["pending","holding","complete"]},"posts":{"type":"array","items":{"$ref":"#/components/schemas/SyndicationPost"}},"created_at":{"type":"string","format":"date-time"}}},"SyndicationRunPage":{"type":"object","required":["items","total"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SyndicationRun"}},"total":{"type":"integer","minimum":0}}},"TaxQuote":{"type":"object","description":"The same net price expressed both ways, plus which one to show this buyer.","required":["currency","country","display_mode","notice","rate_bps","estimated","indeterminate","net_total_minor","tax_total_minor","gross_total_minor","lines"],"properties":{"currency":{"type":"string"},"country":{"type":"string","description":"The destination the figures were rated for, or `\"\"` if none was known."},"display_mode":{"type":"string","enum":["gross","net"],"description":"Which figure leads. `gross` for a consumer (with the VAT shown separately), `net` for a validated business and for any supply carrying no VAT. ⛔ Read it; do not re-derive it — the validation state behind it is not reachable from a frontend."},"notice":{"type":"string","enum":["vat_included","reverse_charge","no_vat","vat_at_checkout"],"description":"A **key**, never rendered prose — every user-facing string goes through the frontend i18n layer in all 58 locales (§2.7, §2.19), so a wording change is a translation change rather than an engine deploy. A basket whose every line is net 0 (a free plan or a trial line) answers `no_vat`; `vat_at_checkout` means a paid basket the engine could not rate here."},"rate_bps":{"type":"integer","description":"The single rate behind `notice`, or `0` where the basket carries more than one. A mixed basket (hosting at the buyer's rate, a website build at UK 20%) genuinely has no single rate, and naming one of them would be a false statement."},"estimated":{"type":"boolean","description":"The figures ran on weak evidence (a geo hint, no billing address) and are indicative. The charge is rated again at checkout against full place-of-supply evidence, and **that** is the number on the invoice."},"indeterminate":{"type":"boolean","description":"The supply could not be rated and the **net** figure is being shown with `notice: vat_at_checkout`. Never true alongside a non-zero `tax_total_minor`."},"net_total_minor":{"type":"integer"},"tax_total_minor":{"type":"integer"},"gross_total_minor":{"type":"integer","description":"⛔ Equal to net in the `indeterminate` fallback, **never 0** — a caller rendering this field unconditionally must show the price rather than a free product."},"lines":{"type":"array","items":{"type":"object","required":["ref","net_minor","tax_minor","gross_minor","currency","rate_bps","treatment"],"properties":{"ref":{"type":"string"},"net_minor":{"type":"integer"},"tax_minor":{"type":"integer"},"gross_minor":{"type":"integer"},"currency":{"type":"string"},"rate_bps":{"type":"integer"},"treatment":{"type":"string","description":"The `docs/34` §2.2 treatment this line was rated under, or `\"\"` where it could not be rated for display."},"place_of_supply":{"type":"string","description":"The country whose rate was applied. **Per line**, because one basket can legitimately produce two countries and two returns."}}}}}},"TaxQuoteRequest":{"type":"object","description":"Net amounts the caller already holds, to be rated for display (#1482). ⛔ Nothing here re-prices: the amounts come from the catalogue and come back rated, so this cannot become a second source of prices.","required":["items"],"properties":{"country":{"type":"string","description":"ISO 3166-1 alpha-2 destination. On the signed-in route this overrides the stored billing country (the customer may be pricing an address they have not saved). Omitted, the public route falls back to Cloudflare's `CF-IPCountry`; the signed-in route falls back to the stored billing country and then to `CF-IPCountry`, answering `estimated: true` for any figure not rated on the stored country (a signed-in customer with no saved address is shown the VAT their basket will carry rather than the net figure alone)."},"currency":{"type":"string","description":"ISO 4217. Defaults to the `docs/29` §3.1 resolution for the request."},"per_item":{"type":"boolean","description":"Absent means false. Which question is asked. `false` prices a BASKET exactly as its invoice will be rounded (VAT once per rate group, leftover cents by largest remainder), so the totals are what checkout charges: use it for a cart or checkout. `true` prices a LIST of independent items, each rated as its own one-item invoice, so an item shows the same cents whatever else is in the request: use it for a price list or plan table. The totals of a `per_item` quote are a sum of standalone prices, not a basket. Only a literal `true` enables it."},"items":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","required":["ref","kind","net_minor"],"properties":{"ref":{"type":"string","description":"The caller's own handle, echoed back. ⛔ Must be **unique** within the request — the response is matched by `ref` rather than by position, so duplicates would collapse and render one price for two products. A repeat is a 422 rather than a silent de-duplication."},"kind":{"type":"string","description":"The `LineKind` value. Together with the ids below it resolves the line's `tax_service_type`, which decides **which country** taxes it: an electronically supplied service is taxed where the customer belongs, a service a human performs where we belong."},"net_minor":{"type":"integer","minimum":0,"description":"The **net** amount, integer minor units (§2.8 — money is never a float)."},"plan_version_id":{"type":"string","format":"uuid"},"listing_package_id":{"type":"string","format":"uuid","description":"REQUIRED when `kind` is `marketplace_package` (the package's type decides its VAT treatment); without it the request is refused with a `422`."},"extra_code":{"type":"string","description":"REQUIRED when `kind` is `extra` (each extra carries its own VAT classification; the bare kind has none); without it the request is refused with a `422`."}}}}}},"TaxTreatment":{"type":"string","description":"How a line was taxed, captured at issue and never recomputed (docs/34 §2.2). `not_registered` means no registration of the seller covered the supply date. An order placed through a partner's checkout (PBN.LTD's V1) is Zinn Digital®'s sale and is rated by the same rules (s1014 TAX2, owner 2026-10-22).","enum":["not_registered","standard","reverse_charge","zero_rated","outside_scope","exempt"]},"Ticket":{"type":"object","description":"A support ticket as its owning organization sees it.","required":["id","org_id","subject","status","priority","channel","assignee_name","reopened_count","message_count","created_at","updated_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"org_id":{"$ref":"#/components/schemas/Uuid"},"subject":{"type":"string"},"status":{"$ref":"#/components/schemas/TicketStatus"},"priority":{"$ref":"#/components/schemas/TicketPriority"},"channel":{"type":"string","description":"How the ticket reached us — `dashboard`, `api` or `staff`. Server-decided; an open string so a future channel is additive on both sides."},"site_id":{"type":["string","null"],"format":"uuid"},"invoice_id":{"type":["string","null"],"format":"uuid"},"on_behalf_of_org_id":{"type":["string","null"],"format":"uuid","description":"The **client org** a reseller opened this ticket about. Null on every ordinary ticket.\n\n⛔ Validated as a descendant of the ticket's own org and `404`d otherwise, so it can never name another tenant. It grants nothing — naming an org on a thread is not access to that org."},"assignee_name":{"type":["string","null"],"description":"The owning agent's display name (first name), or null while unassigned. The customer sees a **name** so they know a person owns their ticket; the agent's id and email are staff-only and never appear on this surface."},"first_response_at":{"type":["string","null"],"format":"date-time"},"resolved_at":{"type":["string","null"],"format":"date-time"},"closed_at":{"type":["string","null"],"format":"date-time"},"last_message_at":{"type":["string","null"],"format":"date-time"},"category":{"type":"string","description":"What the ticket is about, as the customer picked it on the form (`zinn_ads` for a report sent from inside Zinn® Ads, docs/1006 §report-an-issue). Empty when none was picked (an e-mail, a staff-opened ticket)."},"kind":{"$ref":"#/components/schemas/TicketKindValue"},"context":{"$ref":"#/components/schemas/TicketContext"},"reopened_count":{"type":"integer","minimum":0},"message_count":{"type":"integer","minimum":0,"description":"Customer-visible messages in the thread — internal notes are not counted."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"TicketAccessGrant":{"type":"object","description":"One \"give support access\" consent — ONE site, ONE ticket. Holds no secret: staff open the site with a one-click login minted at the moment of use.","required":["id","site_id","site_domain","created_at","expires_at","revoked_at","revoked_reason","active","use_count","last_used_at"],"properties":{"id":{"type":"string","format":"uuid"},"site_id":{"type":"string","format":"uuid"},"site_domain":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"revoked_at":{"type":["string","null"],"format":"date-time"},"revoked_reason":{"type":"string","description":"`customer` (withdrawn), `ticket_closed`, or empty while not revoked."},"active":{"type":"boolean","description":"Usable now — not withdrawn, not expired, and the ticket is not closed."},"use_count":{"type":"integer","minimum":0,"description":"How many times support opened the site with it."},"last_used_at":{"type":["string","null"],"format":"date-time"},"can_open_wp":{"type":"boolean","description":"Staff view only: active AND the site is a serving WordPress site, so \"Open site as support\" can run."}}},"TicketAttachment":{"type":"object","description":"One file on a ticket message.\n\n⛔⛔ `downloadable` is the only thing a client may use to decide whether to offer a link, and it is `true` **only** when the malware scan has passed. `pending`, `infected` and `error` are all not-downloadable — including for staff.","required":["id","filename","content_type","size_bytes","scan_state","downloadable"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"filename":{"type":"string","description":"The name the uploader's machine gave it. ⛔ Display only — it is attacker-controlled text and is never used to build a storage path."},"content_type":{"type":"string"},"size_bytes":{"type":"integer","minimum":0},"scan_state":{"type":"string","enum":["pending","clean","infected","error"],"description":"`pending` — uploaded, not yet scanned. `clean` — the only servable state. `infected` — the scanner found something; the row survives as evidence and the bytes never leave. `error` — the scanner could not answer, which fails **closed**: an unscannable file is not a clean file."},"downloadable":{"type":"boolean","description":"Whether these bytes may be served. True only for `clean`."}}},"TicketAuthorKind":{"type":"string","enum":["customer","staff","system"],"description":"Who wrote a message — the customer, the support team or the platform."},"TicketContext":{"type":["object","null"],"additionalProperties":false,"description":"Where in the product the customer was when they opened the ticket, filled in by the dashboard (Zinn® Ads \"Report a problem\" / \"Suggest an improvement\", docs/1006). Free text from the customer's own session, shown to staff as-is; it grants nothing and is never resolved against another tenant's data. Null when the ticket was not opened from a product screen.","properties":{"product":{"type":"string","enum":["zinn_ads"]},"route":{"type":"string","maxLength":200},"ad_account_id":{"type":"string","maxLength":64},"connection_id":{"type":"string","maxLength":64},"finding_id":{"type":"string","maxLength":64}}},"TicketCreate":{"type":"object","description":"Open a ticket. `channel` is deliberately absent — it is server-decided, so a caller cannot claim an API request arrived by another route.","required":["subject","body"],"properties":{"subject":{"type":"string","minLength":1,"maxLength":200},"body":{"type":"string","minLength":1,"description":"The customer's description — becomes the first message in the thread."},"priority":{"$ref":"#/components/schemas/TicketPriority"},"site_id":{"type":"string","format":"uuid","description":"The site this is about. Must belong to the same org or the request is a 404."},"invoice_id":{"type":"string","format":"uuid","description":"The invoice this is about. Must belong to the same org or the request is a 404."},"org_id":{"type":"string","format":"uuid","description":"The organization to open it in. Required only when the caller holds `tickets.reply` in more than one org."},"on_behalf_of_org_id":{"type":"string","format":"uuid","description":"The client org this is about — a reseller escalating to Zinn® on their client's behalf. Must be a **descendant** of the ticket's org or the request is a `404`; your client never sees this ticket, or us."},"deflection_id":{"type":"string","format":"uuid","description":"The AI attempt (`POST /v1/tickets/deflect` with `ask_ai`) the customer saw before choosing \"This didn't solve it — send to the team\" (s1014 L39, TICKETAI) — counted as answered-then-ticketed. A new ticket needs one unless `category` is `abuse` or `legal`; see `createTicket`."},"category":{"type":"string","enum":["","site","email","domain","billing","migration","plugin","other","abuse","legal","zinn_ads"],"default":"","description":"What the request is about, as the form's category picker offers it (s1014 TICKETAI). `abuse` and `legal` (abuse reports, legal / GDPR requests) go straight to the team with no AI attempt; every other value needs one, unless `kind` is `suggestion`. `zinn_ads` is a report sent from inside Zinn® Ads (docs/1006)."},"kind":{"allOf":[{"$ref":"#/components/schemas/TicketKindValue"}],"default":"problem","description":"`problem` (something is wrong) or `suggestion` (an improvement idea). A suggestion goes to the team with no AI attempt (an AI answer cannot act on an idea) and is tagged so staff can tell it apart in the queue."},"context":{"$ref":"#/components/schemas/TicketContext"},"grant_access":{"type":"boolean","default":false,"description":"\"Give support access to this site\" (s1014 L39): the customer's consent for staff to sign in to `site_id` while this ticket is open, for 7 days at most. Ignored without `site_id`. Listed on the ticket as `access`; withdraw with `revokeTicketAccess`."}}},"TicketDeflection":{"type":"object","required":["articles","findings","applied","checks_incomplete","incidents","status_url"],"properties":{"articles":{"type":"array","items":{"type":"object","required":["id","slug","title"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"slug":{"type":"string"},"title":{"type":"string"},"locale":{"type":"string"}}}},"findings":{"type":"array","items":{"$ref":"#/components/schemas/TicketDeflectionFinding"}},"applied":{"type":"array","description":"Remedies applied automatically. ⛔ Only remedies on an explicit, audited allow-list are ever applied without a human.","items":{"type":"string"}},"checks_incomplete":{"type":"boolean","description":"⛔ True when a live check could not run. \"We found nothing wrong\" and \"we could not look\" are different answers and must render differently."},"incidents":{"type":"array","description":"Open public incidents affecting this customer. ⛔ NOTHING HERE BLOCKS THE FORM — owner ruling 2026-08-24 was *warn prominently, still let them submit*. A customer with a genuinely different problem must never be argued out of asking for help, and one who submits anyway has told us the incident copy did not answer them.","items":{"$ref":"#/components/schemas/TicketDeflectionIncident"}},"status_url":{"type":"string","description":"The public status page in the reader's language, for the \"follow this to resolution\" link. ⛔ A separate origin with no shared fate with the platform (docs/121 §1), so it cannot read our locale — the language travels in the URL."},"deflection_id":{"type":"string","format":"uuid","description":"Present when `ask_ai` was sent. Pass it to `POST /v1/tickets` as `deflection_id` when the customer still sends the ticket, or to `POST /v1/tickets/deflect/{deflectionId}/solved` when the answer solved it."},"answer":{"$ref":"#/components/schemas/TicketDeflectionAnswer"}}},"TicketDeflectionAnswer":{"type":"object","description":"The AI answer in front of the ticket form (s1014 L39). ⛔ Never blocks the ticket: the form always offers \"Still need help? Send it to the team\" beside it.","required":["text","grounded","cited_slugs","failure"],"properties":{"text":{"type":"string","description":"In the customer's language. Empty when it failed."},"grounded":{"type":"boolean","description":"False when the AI said the material does not cover the problem."},"cited_slugs":{"type":"array","items":{"type":"string"},"description":"Slugs of the KB articles it used (only ones we supplied)."},"failure":{"type":"string","description":"Empty when it answered; otherwise the failure class (`provider_outage`, `rate_limited`, `refused`, `our_fault`, …) so the form can say which kind it was."}}},"TicketDeflectionFinding":{"type":"object","required":["code","severity","message_key","context"],"properties":{"code":{"type":"string"},"severity":{"type":"string","enum":["warning","critical"]},"message_key":{"type":"string","description":"⛔ A message KEY, never a sentence — the client renders it from its own catalogue, so a customer reading Arabic gets Arabic rather than an English sentence inside an Arabic page."},"context":{"type":"object","additionalProperties":{"type":"string"},"description":"Facts the message key interpolates. Never prose."}}},"TicketDeflectionIncident":{"type":"object","required":["slug","kind","state","severity","title","body","components"],"description":"One OPEN public status incident this customer is plausibly affected by (W26-N, 2026-08-24). ⚖️ Owner: *\"does it count for outages and like tell them this is caused by x outage and we are working on it already no need to submit a ticket type of thing and link them to status to follow for updates when it's resolved.\"* ⛔ Relevance is a real test, not a decoration: a maintenance window is offered only when it touches a region this organisation actually has a site in, and only while the window is OPEN. Telling a customer a known outage explains them when it does not is worse than saying nothing — they go away, the fault stays, and they come back having been told to wait for a fix that was never coming.","properties":{"slug":{"type":"string"},"kind":{"type":"string","enum":["incident","maintenance"]},"state":{"type":"string","enum":["scheduled","investigating","identified","monitoring","resolved","closed_unverified"],"description":"⛔ `scheduled` is for MAINTENANCE only. It exists because announced work had to borrow an incident's opening state and every planned window on the public board was therefore badged \"Investigating\" — which to a reader means *we do not yet know what is wrong*."},"severity":{"type":"string","enum":["warning","critical"]},"title":{"type":"string","description":"⛔ PROSE, already in the reader's locale — deliberately unlike `TicketDeflectionFinding.message_key`. An incident's copy is written by a human during an event and translated on publish, so no catalogue entry for it can exist: the text did not exist when the client was built."},"body":{"type":"string"},"components":{"type":"array","items":{"type":"string"}},"starts_at":{"type":"string","format":"date-time","nullable":true},"ends_at":{"type":"string","format":"date-time","nullable":true}}},"TicketDeflectionRequest":{"type":"object","description":"What the customer has typed so far. Every field is optional.","properties":{"subject":{"type":"string","maxLength":200},"body":{"type":"string","maxLength":8000},"site_id":{"type":["string","null"],"format":"uuid","description":"The site they are asking about. When given, live checks run against it — including whether its nameservers still point at us."},"org_id":{"type":["string","null"],"format":"uuid"},"ask_ai":{"type":"boolean","default":false,"description":"Run the AI answer (s1014 L39) and record the deflection. Sent when the customer presses \"Get an answer\" — never while typing, so no model call is made per keystroke. The answer is grounded in the published KB and the live catalogue, plus the live checks below."},"category":{"type":"string","maxLength":40,"description":"What the problem is about, as the form's category picker sends it."}}},"TicketDetail":{"allOf":[{"$ref":"#/components/schemas/Ticket"},{"type":"object","required":["messages","access"],"properties":{"messages":{"type":"array","description":"The customer-visible thread in chronological order.","items":{"$ref":"#/components/schemas/TicketMessage"}},"access":{"type":"array","description":"Site access the customer gave support on this ticket (s1014 L39).","items":{"$ref":"#/components/schemas/TicketAccessGrant"}},"merged":{"$ref":"#/components/schemas/TicketMerge"}}}]},"TicketKindValue":{"type":"string","enum":["problem","suggestion"],"description":"Whether the customer is reporting a problem or suggesting an improvement (docs/41, docs/1006). Every ticket that predates the field is a `problem`."},"TicketMerge":{"type":"object","description":"Present only on a `createTicket` (or assistant hand-off) answered with an EXISTING ticket by the spam guard (s1014 TICKETSPAM).","required":["reason","open_tickets"],"properties":{"reason":{"type":"string","enum":["duplicate","open_limit","auto_mail"],"description":"`duplicate` — the same request is already on this ticket (nothing written); `open_limit` — the org already had the open-ticket limit open, so the request was appended to its newest open ticket."},"open_tickets":{"type":"integer","minimum":0}}},"TicketMessage":{"type":"object","description":"One entry in a ticket thread. `internal` messages are staff-only notes and are never returned on the customer surface — the customer query does not fetch them. There is deliberately **no author id**: the console renders `author_name`, and a customer must never receive a staff user id or email address. On the customer surface a staff author is shown by first name only.","required":["id","ticket_id","author_type","author_name","body","internal","via_email","sender_verified","lang","translation_state","body_original","attachments","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"ticket_id":{"$ref":"#/components/schemas/Uuid"},"author_type":{"$ref":"#/components/schemas/TicketAuthorKind"},"author_name":{"type":"string","description":"Display name of the author. `system` messages are attributed to the brand."},"body":{"type":"string"},"internal":{"type":"boolean","description":"A staff-only note. Always false on the customer surface — such messages are excluded from the customer thread entirely rather than flagged."},"via_email":{"type":"boolean","description":"This message arrived as an email reply rather than being typed into a console. Shown on **both** surfaces: staff need it to explain a message with no author name, and the customer needs it because a reply sent from their phone appearing in their thread with no indication of how it got there reads as an impersonation."},"sender_verified":{"type":"boolean","description":"For an emailed reply, whether the sending address belongs to a user of this org. `false` still shows the message — it is attached and flagged rather than dropped, so a customer replying from a personal address is never silently ignored — and the surface must say so. ⛔ It describes a **forgeable** envelope sender, so it is a badge and never a permission. Always `true` for a message typed into a console."},"lang":{"type":"string","description":"The BCP-47 language this message was actually **written** in, detected from the text. ⛔ Not the author's account locale — the two disagree constantly, and the difference is the point: a customer whose account says `en` because nobody changed the default routinely writes in their own language. Empty means \"not detected\", never \"English\"."},"translation_state":{"type":"string","enum":["not_needed","translated","failed"],"description":"How `body` came to be what it is. ⛔ Three values rather than a boolean: `failed` and `not_needed` both mean \"no translation exists\" and mean **opposite** things to the reader, and a boolean collapses them into the reassuring one. On `failed`, `body` is the author's ORIGINAL text and the surface must say the translation did not happen."},"staff_translation":{"description":"Admin surface only (docs/1067 §5a): the author's own words translated into the reading staff member's language, or `null` when they already read it (same language, or English staff on a message whose `body` is the English translation). Never on the customer surface. Stored text is never rewritten.","oneOf":[{"$ref":"#/components/schemas/UserTextTranslation"},{"type":"null"}]},"body_original":{"type":"string","description":"The author's own words, when `body` is a machine translation. Empty when `body` IS the original.\n\n⛔ Returned on **both** surfaces. A translated-only view means nobody can check whether the translation is wrong, which is how a support answer ends up addressing a question the customer did not ask."},"attachments":{"type":"array","description":"Files on this message.","items":{"$ref":"#/components/schemas/TicketAttachment"}},"created_at":{"type":"string","format":"date-time"}}},"TicketPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Ticket"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"TicketPriority":{"type":"string","enum":["low","normal","high","urgent"],"description":"How urgent the ticket is. The customer may propose one; staff decide."},"TicketReplyCreate":{"type":"object","required":["body"],"properties":{"body":{"type":"string","minLength":1}}},"TicketStatus":{"type":"string","enum":["open","pending","solved","closed"],"description":"Where a ticket sits in its lifecycle. `open` = waiting on us; `pending` = waiting on the customer; `solved` = we believe it is resolved and a customer reply reopens it; `closed` = terminal until staff reopen it."},"TimeBillNow":{"type":"object","additionalProperties":false,"required":["client_id","currency"],"properties":{"client_id":{"type":"string","format":"uuid"},"currency":{"type":"string","minLength":3,"maxLength":3},"until":{"type":"string","format":"date","nullable":true,"description":"Bill work up to and including this date — \"everything to the end of last month\"."},"notes":{"type":"string","maxLength":2000},"org_id":{"type":"string","format":"uuid"}}},"TimeBillingRun":{"type":"object","additionalProperties":false,"required":["id","currency","trigger","status","subtotal_minor","minutes_total","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"client_id":{"type":"string","format":"uuid","nullable":true},"currency":{"type":"string","minLength":3,"maxLength":3},"period_start":{"type":"string","format":"date","nullable":true},"period_end":{"type":"string","format":"date","nullable":true},"trigger":{"type":"string","enum":["manual","on_log","day_of_month","threshold"]},"status":{"type":"string","enum":["claimed","invoiced","failed","released"],"description":"`claimed` is the state between claiming the time and the invoicing suite's reply — a process that dies there leaves one, and the recovery pass finishes it with the same derived key. `released` means the draft was voided and the time went back into the unbilled pool."},"subtotal_minor":{"type":"integer","description":"Our own exact arithmetic, before tax. What the invoice is reconciled against."},"minutes_total":{"type":"integer"},"duration_label":{"type":"string"},"entry_count":{"type":"integer"},"fixed_line_count":{"type":"integer"},"invoice_id":{"type":"string","format":"uuid","nullable":true},"invoice_number":{"type":"string","nullable":true},"invoice_created":{"type":"boolean","description":"FALSE means the invoicing suite's idempotency key fired and handed back an invoice an earlier attempt had already raised. Surfaced rather than hidden: it is the observable that says the double-bill guard did its job, and without it a retry storm is indistinguishable from correct operation."},"reconcile_state":{"type":"string","enum":["pending","ok","mismatch","unavailable"],"description":"Whether the invoice's total for these lines equals our own arithmetic **exactly**. There is no \"close enough\": both sides compute from the same two integers, so any difference is real. `mismatch` means do not send this draft. `unavailable` means the totals could not be read back — not established, never a pass."},"reconcile_detail":{"type":"string"},"invoiced_at":{"type":"string","format":"date-time","nullable":true},"released_at":{"type":"string","format":"date-time","nullable":true},"last_error":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"checkout_bill":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/TimeCheckoutBill"}],"description":"`null` for an agency invoice. For Zinn®'s own organisation, the bill this run raised on Zinn®'s checkout (docs/670 §3), with its own net, tax and gross."},"actual":{"type":"object","additionalProperties":false,"description":"What this run actually consumed, derived from the time entries rather than read off the run's stored columns — so a divergence is visible on the screen.","properties":{"minutes":{"type":"integer"},"amount_minor":{"type":"integer"},"entries":{"type":"integer"},"fixed_price_entries":{"type":"integer"}}}}},"TimeBillingRunPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TimeBillingRun"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"TimeBillingSchedule":{"type":"object","additionalProperties":false,"required":["id","trigger","currency","active"],"properties":{"id":{"type":"string","format":"uuid"},"client_id":{"type":"string","format":"uuid","nullable":true,"description":"`null` is the organisation-wide DEFAULT, covering every client without a row of its own. A per-client row replaces it rather than layering on it."},"trigger":{"type":"string","enum":["manual","on_log","day_of_month","threshold"]},"day_of_month":{"type":"integer","nullable":true,"minimum":1,"maximum":28,"description":"⛔ 1–28. The 29th to the 31st do not exist in every month, so a schedule set to the 31st would silently skip five of them a year."},"threshold_minor":{"type":"integer","nullable":true,"minimum":1},"currency":{"type":"string","minLength":3,"maxLength":3},"active":{"type":"boolean"},"next_run_at":{"type":"string","format":"date-time","nullable":true},"last_attempted_at":{"type":"string","format":"date-time","nullable":true,"description":"Stamped for every schedule the sweep REACHES, before its result is read — so a client whose invoice fails still leaves the front of the queue."},"last_succeeded_at":{"type":"string","format":"date-time","nullable":true,"description":"A SECOND column, deliberately: one column cannot serve as both the cursor the sweep advances and the signal a staleness alarm reads."},"last_error":{"type":"string"}}},"TimeBillingSchedulePage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TimeBillingSchedule"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"TimeBillingScheduleWrite":{"type":"object","additionalProperties":false,"required":["trigger"],"properties":{"client_id":{"type":"string","format":"uuid","nullable":true},"trigger":{"type":"string","enum":["manual","on_log","day_of_month","threshold"]},"day_of_month":{"type":"integer","nullable":true,"minimum":1,"maximum":28},"threshold_minor":{"type":"integer","nullable":true,"minimum":1},"currency":{"type":"string","minLength":3,"maxLength":3,"default":"GBP"},"active":{"type":"boolean","default":true},"org_id":{"type":"string","format":"uuid"}}},"TimeCheckoutBill":{"type":"object","additionalProperties":false,"required":["id","reference","status","currency","subtotal_minor","tax_minor","total_minor","pay_url"],"properties":{"id":{"type":"string","format":"uuid"},"reference":{"type":"string"},"status":{"type":"string","enum":["draft","sent","paid","void"]},"currency":{"type":"string","minLength":3,"maxLength":3},"subtotal_minor":{"type":"integer"},"tax_minor":{"type":"integer"},"total_minor":{"type":"integer"},"recipient_email":{"type":"string"},"recipient_country":{"type":"string"},"sent_at":{"type":"string","format":"date-time","nullable":true},"paid_at":{"type":"string","format":"date-time","nullable":true},"voided_at":{"type":"string","format":"date-time","nullable":true},"pay_url":{"type":"string","description":"The public page the recipient pays this bill on."}}},"TimeCheckoutBillSend":{"type":"object","additionalProperties":false,"properties":{"org_id":{"type":"string","format":"uuid","nullable":true}}},"TimeCheckoutBillVoid":{"type":"object","additionalProperties":false,"required":["reason"],"properties":{"reason":{"type":"string","maxLength":500},"org_id":{"type":"string","format":"uuid","nullable":true}}},"TimeEntry":{"type":"object","additionalProperties":false,"required":["id","project_id","work_date","minutes","duration_label","billable","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid","nullable":true},"project_id":{"type":"string","format":"uuid"},"project_name":{"type":"string"},"task_id":{"type":"string","format":"uuid","nullable":true},"task_name":{"type":"string"},"client_id":{"type":"string","format":"uuid","nullable":true},"work_date":{"type":"string","format":"date"},"minutes":{"type":"integer","minimum":1,"maximum":1440,"description":"⛔ An INTEGER of minutes. There is no `hours` field on this API: an hours-as-float duration re-enters the money through the rate and no rounding point can recover it."},"duration_label":{"type":"string","example":"2h 30m","description":"Presentational only — never multiplied by anything."},"description":{"type":"string"},"billable":{"type":"boolean"},"billing_run_id":{"type":"string","format":"uuid","nullable":true,"description":"The run that invoiced this entry. `null` means it is still outstanding."},"billed_rate_minor_per_hour":{"type":"integer","nullable":true},"billed_amount_minor":{"type":"integer","nullable":true,"description":"What was actually charged, frozen at billing time so the document can be re-derived years later even if every rate card has since changed."},"billed_currency":{"type":"string","nullable":true},"billed_under_fixed_price":{"type":"boolean","description":"TRUE when these minutes were rolled into a task's FIXED price rather than charged by the hour. `billed_amount_minor` is then 0 and that zero is correct — read this flag, not the amount."},"rate_minor_per_hour":{"type":"integer","nullable":true,"description":"The rate that WOULD apply, resolved against this entry's own `work_date`, for an entry not yet billed. ⛔ `null` means **unpriced**, not free: work with no rate card is never invoiced at zero, because that would take it out of the unbilled pool for ever."},"rate_scope":{"type":"string","nullable":true,"enum":["task","project","client","org"],"description":"Which rate card won, so a surprising invoice can be explained."},"rate_kind":{"type":"string","nullable":true,"enum":["hourly","fixed"]},"created_at":{"type":"string","format":"date-time"}}},"TimeEntryCreate":{"type":"object","additionalProperties":false,"required":["project_id","work_date","minutes"],"properties":{"project_id":{"type":"string","format":"uuid"},"task_id":{"type":"string","format":"uuid","nullable":true},"work_date":{"type":"string","format":"date"},"minutes":{"type":"integer","minimum":1,"maximum":1440},"description":{"type":"string","maxLength":2000},"billable":{"type":"boolean","default":true},"user_id":{"type":"string","format":"uuid","nullable":true,"description":"Log on somebody else's behalf. Requires `agency.time.manage`; without it a caller may only log their own time."}}},"TimeEntryPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TimeEntry"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"TimeEntryUpdate":{"type":"object","additionalProperties":false,"properties":{"task_id":{"type":"string","format":"uuid","nullable":true},"work_date":{"type":"string","format":"date"},"minutes":{"type":"integer","minimum":1,"maximum":1440},"description":{"type":"string","maxLength":2000},"billable":{"type":"boolean"}}},"TimeProject":{"type":"object","additionalProperties":false,"required":["id","name","client_id","board_id","currency","archived","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"client_id":{"type":"string","format":"uuid","nullable":true,"description":"The agency's client this work is for, in the agency invoicing suite. `null` means **internal** work — reported on, never invoiced."},"board_id":{"type":"string","format":"uuid","nullable":true,"description":"The agency project board this work is run on, when there is one."},"source_quote_id":{"type":"string","format":"uuid","nullable":true,"description":"The free-quote request this project was started from (docs/670 §2), or `null` for a project made by hand. At most one project per quote."},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO currency this project's work is billed in. On the project because an invoice has exactly one currency; a rate card in another currency is refused rather than converted."},"archived":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"TimeProjectCreate":{"type":"object","additionalProperties":false,"required":["name"],"properties":{"name":{"type":"string","maxLength":200},"client_id":{"type":"string","format":"uuid","nullable":true},"board_id":{"type":"string","format":"uuid","nullable":true},"currency":{"type":"string","minLength":3,"maxLength":3,"default":"GBP"},"org_id":{"type":"string","format":"uuid"}}},"TimeProjectFromQuote":{"type":"object","additionalProperties":false,"required":["quote_id"],"properties":{"quote_id":{"type":"string","format":"uuid"},"amount_minor":{"type":"integer","nullable":true,"minimum":1,"description":"The agreed price, NET, in minor units — only for a request that has not been priced. On a priced request omit it; a different figure is refused."},"currency":{"type":"string","maxLength":3},"country":{"type":"string","maxLength":2,"description":"The client's ISO-2 country, used only when the request carries none (the public form does not ask). The bill on the checkout needs it; anything but two letters is refused."},"org_id":{"type":"string","format":"uuid","nullable":true}}},"TimeProjectFromQuoteResult":{"type":"object","additionalProperties":false,"required":["project","board_id","client_id","created"],"properties":{"project":{"$ref":"#/components/schemas/TimeProject"},"board_id":{"type":"string"},"client_id":{"type":"string"},"created":{"type":"boolean","description":"FALSE when a project for this request already existed and was returned."},"price_already_billed_on":{"type":"string","nullable":true,"description":"The reference of a bill already drafted straight from this request, when there was one — in which case the project carries no fixed price, because that bill charges it."}}},"TimeProjectPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TimeProject"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"TimeProjectUpdate":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","maxLength":200},"client_id":{"type":"string","format":"uuid","nullable":true},"board_id":{"type":"string","format":"uuid","nullable":true},"currency":{"type":"string","minLength":3,"maxLength":3},"archived":{"type":"boolean"}}},"TimeQuoteRequest":{"type":"object","additionalProperties":false,"required":["id","reference","status","name","email","project_type","description","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"reference":{"type":"string"},"status":{"type":"string","enum":["new","quoted"]},"name":{"type":"string"},"email":{"type":"string"},"company":{"type":"string"},"country":{"type":"string","nullable":true},"project_type":{"type":"string"},"project_type_label":{"type":"string"},"description":{"type":"string"},"quoted_amount_minor":{"type":"integer","nullable":true},"quoted_currency":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"TimeQuoteRequestList":{"type":"object","additionalProperties":false,"required":["data","total"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TimeQuoteRequest"}},"total":{"type":"integer","description":"The TRUE number of open requests; `data` is capped at 200, oldest first."}}},"TimeRate":{"type":"object","additionalProperties":false,"required":["id","scope","kind","amount_minor","currency","effective_from","archived"],"properties":{"id":{"type":"string","format":"uuid"},"scope":{"type":"string","enum":["task","project","client","org"]},"scope_id":{"type":"string","format":"uuid","nullable":true,"description":"The task/project/client this applies to. `null` exactly when scope is `org`."},"kind":{"type":"string","enum":["hourly","fixed"]},"amount_minor":{"type":"integer","minimum":0,"description":"Minor units. For `hourly`, the price of ONE HOUR — ⛔ never a price per minute, and never divided by 60 anywhere on this API."},"currency":{"type":"string","minLength":3,"maxLength":3},"effective_from":{"type":"string","format":"date","description":"Applies to work done on or after this date. Resolution is against the **work's** date, never today, so a rate rise does not re-price last month."},"archived":{"type":"boolean"}}},"TimeRateCreate":{"type":"object","additionalProperties":false,"required":["scope","amount_minor","currency","effective_from"],"properties":{"scope":{"type":"string","enum":["task","project","client","org"]},"scope_id":{"type":"string","format":"uuid","nullable":true},"kind":{"type":"string","enum":["hourly","fixed"],"default":"hourly"},"amount_minor":{"type":"integer","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3},"effective_from":{"type":"string","format":"date"},"org_id":{"type":"string","format":"uuid"}}},"TimeRatePage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TimeRate"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"TimeReport":{"type":"object","additionalProperties":false,"required":["period_start","period_end","total_minutes","billed_minutes","unbilled_minutes","non_billable_minutes"],"properties":{"period_start":{"type":"string","format":"date"},"period_end":{"type":"string","format":"date"},"total_minutes":{"type":"integer"},"billable_minutes":{"type":"integer","description":"Total minus NON-BILLABLE — ⛔ not \"billed\". An hour logged as billable and not yet invoiced is billable work, and calling it anything else is how an agency talks itself out of chasing it."},"billed_minutes":{"type":"integer"},"unbilled_minutes":{"type":"integer"},"non_billable_minutes":{"type":"integer"},"billed_minor_by_currency":{"type":"object","additionalProperties":{"type":"integer"}},"by_user":{"type":"array","items":{"$ref":"#/components/schemas/TimeReportBucket"}},"by_client":{"type":"array","items":{"$ref":"#/components/schemas/TimeReportBucket"}},"by_project":{"type":"array","items":{"$ref":"#/components/schemas/TimeReportBucket"}}}},"TimeReportBucket":{"type":"object","additionalProperties":false,"required":["key","minutes","billed_minutes","unbilled_minutes","non_billable_minutes"],"properties":{"key":{"type":"string"},"label":{"type":"string"},"minutes":{"type":"integer"},"duration_label":{"type":"string"},"billed_minutes":{"type":"integer"},"unbilled_minutes":{"type":"integer"},"non_billable_minutes":{"type":"integer"},"billed_minor":{"type":"integer"},"currency":{"type":"string"},"entry_count":{"type":"integer"}}},"TimeTask":{"type":"object","additionalProperties":false,"required":["id","project_id","name","archived","fixed_price_billed"],"properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"archived":{"type":"boolean"},"fixed_price_billed":{"type":"boolean","description":"Whether this task's FIXED price has already been invoiced. Surfaced so the screen can say \"already billed\" rather than showing further hours on it as free work."}}},"TimeTaskCreate":{"type":"object","additionalProperties":false,"required":["project_id","name"],"properties":{"project_id":{"type":"string","format":"uuid"},"name":{"type":"string","maxLength":200}}},"TimeTaskPage":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TimeTask"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"TimeTaskUpdate":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","maxLength":200},"archived":{"type":"boolean"}}},"TldLocalPresenceAddon":{"type":"object","required":["company_only","per_year"],"properties":{"company_only":{"type":"boolean","description":"The registry's trustee serves only a company owner, never a person."},"per_year":{"allOf":[{"$ref":"#/components/schemas/MoneyAmount"}],"description":"The add-on's price for one year, tax excluded, in the requested currency."}}},"TldPrice":{"type":"object","description":"Flat registrar pricing for one TLD in the caller's display currency. Integer minor units + ISO-4217 code (CLAUDE.md §2.8 — money is never a float). All four money fields share one currency by construction.","required":["tld","register_minor","renew_minor","transfer_minor","currency"],"properties":{"tld":{"type":"string","description":"The TLD without a leading dot (`com`, `co.uk`) — as `TldOffer` stores it."},"register_minor":{"type":"integer","minimum":0},"renew_minor":{"type":"integer","minimum":0},"transfer_minor":{"type":"integer","minimum":0},"currency":{"$ref":"#/components/schemas/CurrencyCode"}}},"TldPricingTable":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TldPrice"}},"page":{"$ref":"#/components/schemas/PageMeta"}}},"TldRequirementField":{"type":"object","required":["key","scope","type","required","when","label_en","options","pattern","help"],"properties":{"key":{"type":"string","description":"The name to send in `registry_data`."},"scope":{"type":"string","enum":["domain","owner_ext","owner"],"description":"Where the registry records it: on the domain call, as extension data on the owner contact, or as the owner's identity data (ID, tax, company or VAT number, birth date)."},"type":{"type":"string","enum":["text","select","check","date"]},"required":{"type":"boolean"},"when":{"type":"string","description":"When a `required` field applies: `always`, `individual`, `company` (the registrant is a company when `org_name` is filled — the registry's own rule), optionally suffixed `_local` / `_nonlocal`, or `nonlocal`."},"label_en":{"type":"string","description":"The registry's English label (a fallback)."},"options":{"type":"array","items":{"type":"object","required":["value","label_en"],"properties":{"value":{"type":"string"},"label_en":{"type":"string"}}}},"pattern":{"type":"string","description":"A full-match regular expression","or empty.":null},"help":{"type":"string","description":"A curated help key (`domainRegistry.help.<help>`)","or empty.":null}}},"TldRequirements":{"type":"object","required":["tld","known","orderable","manual_reason","countries","entity","state_required","full_name_required","local_presence_service","fields","source_url","source_updated"],"properties":{"tld":{"type":"string"},"known":{"type":"boolean","description":"False when the registry's requirements could not be read — checkout then refuses the extension rather than selling it on a guess."},"orderable":{"type":"boolean","description":"False for an extension sold only by hand."},"manual_reason":{"type":"string","description":"Why an extension cannot be ordered online (`documents_required`, `registry_token_required`, `professional_licence_required`, `registry_closed_to_new_registrations`, `local_presence_required`, …), or empty."},"countries":{"type":"array","items":{"type":"string","minLength":2,"maxLength":2},"description":"Registrant countries the registry accepts (ISO 3166-1 alpha-2); empty means any."},"entity":{"type":"string","enum":["any","individual","company"]},"state_required":{"type":"boolean"},"full_name_required":{"type":"boolean","description":"Full first and last name","no initials.":null},"local_presence_service":{"type":"boolean","description":"A free local-presence service is used for a registrant outside `countries`."},"owner_local":{"type":"array","items":{"type":"string","minLength":2,"maxLength":2},"description":"Countries the registry demands the OWNER have an address in (ISO 3166-1 alpha-2), enforced on a register and on a transfer that replaces the holder; empty when there is no such demand."},"local_presence_addon":{"description":"LOCALPRES1114 (docs/1343). The paid local-presence (trustee) add-on, when the registrar sells one for this extension and a priced row exists: buy it as a cart line of kind `local_presence_addon` beside the domain (same term) when checkout refuses the owner with `country_not_eligible`. Priced per year; never discounted by a promo code. Null when no trustee is sold.","anyOf":[{"$ref":"#/components/schemas/TldLocalPresenceAddon"},{"type":"null"}]},"fields":{"type":"array","items":{"$ref":"#/components/schemas/TldRequirementField"}},"source_url":{"type":"string","description":"The registrar's documentation the rule was read from."},"source_updated":{"type":"string","description":"When that documentation was last updated."}}},"TldRequirementsResponse":{"type":"object","required":["tlds","sources"],"properties":{"tlds":{"type":"array","items":{"$ref":"#/components/schemas/TldRequirements"}},"sources":{"type":"object","additionalProperties":{"type":"string"},"description":"Where and when the registry data was read (API, knowledge base, curated rules)."}}},"TokenValidation":{"type":"object","required":["valid","account_login","scopes","missing_scopes","message"],"description":"Returned with HTTP 200 even when valid is false: whether a token is good is the answer being asked for, not a failed request.","properties":{"valid":{"type":"boolean"},"account_login":{"type":["string","null"],"description":"The account the token authenticates as, when valid."},"scopes":{"type":"array","items":{"type":"string"}},"missing_scopes":{"type":"array","items":{"type":"string"},"description":"Required scopes the token lacks. Empty when the token is valid, and also empty when the provider could not enumerate its permissions — in that case the connection is usable but unverified, so this must not be read as proof that nothing is missing."},"message":{"type":["string","null"],"description":"Human-readable explanation, or null when valid."},"permissions":{"oneOf":[{"$ref":"#/components/schemas/PermissionReport"},{"type":"null"}],"description":"The per-permission checklist, exercised against the provider. ⛔ `null` means **we cannot test this provider's permissions** — it does not mean \"nothing is required\". The two readings produce opposite screens and only one is honest; this is the same two-meanings-one-field defect `missing_scopes` above already has, spelled out here so its replacement does not inherit it."}}},"TrackedKeyword":{"type":"object","description":"One search phrase to track a position for. `phrase` is literally the search query, so it should read as a customer would type it. `location` and `language` are the customer's own words — \"United Kingdom\", \"en\" — rather than a vendor's location id, so the watch-list stays portable if the data supplier changes.\n\nThe market is part of the phrase's identity, not decoration: the same phrase in two countries is two different questions with two different answers and two separate costs.","required":["phrase"],"properties":{"phrase":{"type":"string","maxLength":200},"location":{"type":"string","maxLength":120},"language":{"type":"string","maxLength":8},"device":{"type":"string","enum":["","desktop","mobile"],"description":"Q321 (V1 \"Google versions\"): the device the search is made from. Empty is desktop. The same phrase on desktop and on mobile is two keywords, each counted against the allowance and each checked and billed, exactly as V1 counts a version."}}},"TrackedProduct":{"type":"object","description":"One product to price-track. `title` is literally the marketplace search term, so it should read as a shopper would type it. `asin` is optional and Amazon-only — a customer selling only through their own shop has none.","required":["title"],"properties":{"title":{"type":"string","maxLength":200},"sku":{"type":"string","maxLength":64,"description":"The customer's own reference. Never sent to a marketplace — it exists so a row on our screen matches a row in their shop admin."},"asin":{"type":"string","maxLength":32}}},"TransferAccessMethod":{"type":"string","enum":["admin_login","api_token","app_install","files"]},"TransferAddonCode":{"type":"string","enum":["seo_urls","preserve_order_ids","content_images","customer_passwords"],"description":"`seo_urls` keeps product and category URLs and 301-redirects every old URL; `preserve_order_ids` keeps order numbers; `content_images` moves images inside descriptions; `customer_passwords` lets customers keep logging in with their password."},"TransferAftercareCode":{"type":"string","enum":["none","standard","extended","premium"],"description":"Free re-runs after the move — standard 1 in 14 days, extended 2 in 28, premium 3 in 60."},"TransferCandidate":{"type":"object","required":["fqdn","tld","eligible","reason","amount_minor","currency","grants_year"],"properties":{"fqdn":{"type":"string"},"tld":{"type":"string"},"eligible":{"type":"boolean"},"reason":{"type":["string","null"],"description":"Why this name cannot be transferred. `TLD_NOT_OFFERED` — we do not sell that extension, or the name is not registrable (a sub-domain). `NOT_REGISTERED` — the name is available, so it is a registration, not a transfer. `CHECK_FAILED` — the registrar could not be asked, so the answer is \"try again\", **not** \"you can buy it instead\"; those are different facts and the customer's next action differs. `ALREADY_ON_PLATFORM` — this organisation already holds it. `NOT_PRICED` — we sell the TLD but hold no transfer price in this currency."},"amount_minor":{"type":["integer","null"],"format":"int64"},"currency":{"type":["string","null"],"minLength":3,"maxLength":3},"grants_year":{"type":["boolean","null"],"description":"Whether the registry adds a year to the term when the transfer completes. ⛔ `null` means **unknown, not \"no\"** — true for every gTLD under ICANN's transfer policy, but country registries differ and we hold no source for most of them. Show the \"+1 year\" line only on `true`."}}},"TransferPlatform":{"type":"object","required":["code","name","can_host"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"can_host":{"type":"boolean","description":"Whether we can build this platform on our hosting (\"move it onto our hosting\"). Every listed target can receive a store; this decides only whether we can also build the new store for the customer."}}},"TransferPlatformCatalogue":{"type":"object","required":["sources","targets","addons","aftercare","access_methods","minimum_price_minor","currency"],"properties":{"sources":{"type":"array","items":{"$ref":"#/components/schemas/TransferPlatformGroup"}},"targets":{"type":"array","items":{"$ref":"#/components/schemas/TransferPlatformGroup"}},"addons":{"type":"array","items":{"type":"object","required":["code","default"],"properties":{"code":{"$ref":"#/components/schemas/TransferAddonCode"},"default":{"type":"boolean","description":"Pre-ticked on a new quote."}}}},"aftercare":{"type":"array","items":{"type":"object","required":["code","reruns","days","default"],"properties":{"code":{"$ref":"#/components/schemas/TransferAftercareCode"},"reruns":{"type":"integer"},"days":{"type":"integer"},"default":{"type":"boolean"}}}},"access_methods":{"type":"array","items":{"$ref":"#/components/schemas/TransferAccessMethod"}},"minimum_price_minor":{"type":"integer","format":"int64","description":"The lowest price any move is sold at (\"from\"), in `currency`."},"currency":{"type":"string","minLength":3,"maxLength":3},"minimum_prices_minor":{"type":"object","additionalProperties":{"type":"integer","format":"int64"},"description":"The minimum in every currency the engine sells in (ISO code -> integer minor units, USD included), each the figure checkout charges. A currency with no stored FX rate is absent, never filled with the USD figure."}}},"TransferPlatformGroup":{"type":"object","required":["group","platforms"],"properties":{"group":{"type":"string","enum":["hosted","self_hosted","wordpress","marketplace","file"]},"platforms":{"type":"array","items":{"$ref":"#/components/schemas/TransferPlatform"}}}},"TransferPreflightRequest":{"type":"object","required":["domains"],"description":"Names to check for transfer-in. **Authorization codes are deliberately not part of this request**: this endpoint initiates nothing, so a live credential has no reason to cross the wire here. The code travels once, on the cart line that buys the transfer.","properties":{"domains":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","maxLength":253}}}},"TransferPreflightResults":{"type":"object","required":["results"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/TransferCandidate"}}}},"TransferQuote":{"type":"object","required":["price_amount_minor","currency","price_usd_minor","minimum_applied","entity_total","addons","aftercare","aftercare_reruns","aftercare_days","can_build_target"],"properties":{"price_amount_minor":{"type":"integer","format":"int64"},"currency":{"type":"string","minLength":3,"maxLength":3},"price_usd_minor":{"type":"integer","format":"int64"},"prices_minor":{"type":"object","additionalProperties":{"type":"integer","format":"int64"},"description":"This move's price in every currency the engine sells in (ISO code -> integer minor units, USD included), each equal to `price_amount_minor` of the same quote asked in that currency: what checkout charges. Lets a cached page show any visitor's currency without converting in the browser. A currency with no stored FX rate is absent, never filled with the USD figure."},"minimum_applied":{"type":"boolean","description":"The move priced below the minimum, so the minimum is charged."},"entity_total":{"type":"integer"},"addons":{"type":"array","items":{"$ref":"#/components/schemas/TransferAddonCode"}},"aftercare":{"$ref":"#/components/schemas/TransferAftercareCode"},"aftercare_reruns":{"type":"integer"},"aftercare_days":{"type":"integer"},"can_build_target":{"type":"boolean","description":"We can build the new store on our hosting for this target."},"priced_at":{"type":["string","null"],"format":"date-time"}}},"TransferQuoteRequest":{"type":"object","required":["source_platform","target_platform"],"properties":{"source_platform":{"type":"string"},"target_platform":{"type":"string"},"products":{"type":"integer","minimum":0,"maximum":10000000,"default":0},"customers":{"type":"integer","minimum":0,"maximum":10000000,"default":0},"orders":{"type":"integer","minimum":0,"maximum":10000000,"default":0},"blog_posts":{"type":"integer","minimum":0,"maximum":10000000,"default":0},"cms_pages":{"type":"integer","minimum":0,"maximum":10000000,"default":0},"addons":{"type":"array","items":{"$ref":"#/components/schemas/TransferAddonCode"}},"aftercare":{"$ref":"#/components/schemas/TransferAftercareCode"}}},"TranslatedSlugs":{"type":"object","required":["slugs"],"properties":{"slugs":{"type":"object","description":"Canonical `object_ref` -> locale -> translated slug. A locale appears only when its slug is `up_to_date`; anything less settled is omitted and the caller falls back to the canonical URL.","additionalProperties":{"type":"object","additionalProperties":{"type":"string"}},"example":{"page:pricing":{"fr":"tarification","de":"preise","ar":"الأسعار"}}},"moves":{"type":"object","description":"Present only when a slug in this response was MOVED explicitly: `object_ref` -> locale -> the earlier spelling(s) it replaced. A published slug never changes on re-translation of unchanged English; only an explicit move (a collision or normalise repair, or `mark_translations_stale --move-slugs`) or a changed English moves it. The product-site export records these spellings so the old URL answers a 308 to the new one.","additionalProperties":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"example":{"productsite:storeflips/sell":{"yo":["ta-itaja-re"]}}},"next_cursor":{"type":["string","null"],"description":"Present only in paged mode (`limit` or `cursor` sent): the cursor for the next page, or `null` when this was the last one."}}},"TranslationBundle":{"type":"object","required":["locale","generated_at","entries"],"properties":{"locale":{"$ref":"#/components/schemas/LocaleCode"},"generated_at":{"type":"string","format":"date-time","description":"When this bundle was assembled (server time)."},"entries":{"type":"object","description":"`object_ref` -> `field` -> the translated entry. Entries with no text yet are omitted rather than returned blank.","additionalProperties":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/TranslationBundleEntry"}},"example":{"page:pricing":{"title":{"text":"Tarification","status":"up_to_date"},"body":{"text":"Des forfaits pour…","status":"stale"}}}},"next_cursor":{"type":"string","nullable":true,"description":"Pass back as `cursor` for the next page. `null` on the last page, and **absent entirely** unless the request opted into paging with `limit` or `cursor` — so a caller that never asked for pages cannot be handed a partial bundle it mistakes for the whole one.\n\nDeliberately distinct states: `null` means \"this was the last page\"; missing means \"you did not ask for pages\". A client that cannot tell those apart either stops one page early or loops forever, and on a translation export both look like success.","example":"WyJ1aSIsImRhc2hib2FyZCIsIm5hdi5ibHVlcHJpbnRzIl0="}}},"TranslationBundleEntry":{"type":"object","required":["text","status"],"properties":{"text":{"type":"string","description":"The translated text. Present (non-empty) whatever the `status` — a `stale` entry serves its last-good translation."},"status":{"$ref":"#/components/schemas/TranslationStatus"},"current":{"type":"boolean","description":"True when `text` translates the CURRENT source (the row's source hash equals the string's). A `stale` entry that is `current` was re-queued for quality, not because the English changed, so its text is still a correct translation and is servable; a non-current entry translates an older English and is not."},"source_hash":{"type":"string","description":"SHA-256 (hex, UTF-8) of the English source the engine holds for this field NOW — the hash `current` is judged against. A caller whose own source text hashes differently is looking at translations of another wording (for example a branch whose changed string a register from `main` put back): `scripts/i18n-sync.mjs` re-registers its own English and never exports those rows as finished.","example":"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"},"translated_at":{"type":["string","null"],"format":"date-time","description":"When `text` became this row's translation (null when it never had one). The repo export keeps a committed translation of the SAME English that was committed after this time instead of overwriting it, and hands it back through `POST /v1/i18n/repo-translations` (i18n fix A, 2026-10-16)."},"person_owned":{"type":"boolean","description":"True when a person or the repository wrote `text` for the CURRENT source (a human author is recorded and `current` holds): no machine translation replaces it until the English changes. False = the machine wrote it. The repo export keeps a committed translation authored after its English over a later MACHINE re-translation, never over a person's edit, and names every such key in an ops alert (GP-WORDING, 2026-11-09)."}}},"TranslationField":{"type":"string","description":"Which field of the referenced entity, e.g. `title` or `body`.","minLength":1,"maxLength":64,"example":"title"},"TranslationNamespacePrune":{"type":"object","description":"Retire every registered DOCUMENT under `ref_prefix` that is not named in `expected_refs`. `TranslationPruneScope` retires fields inside one document; this retires documents that have stopped existing.\n⛔ The two are not interchangeable. A field that changes key is retired by the save hook that re-enumerates its document. A document that is deleted, renamed or moved to another collection never fires a save hook for its old ref and has no fields left to enumerate, so nothing could ever reach it. Measured on the live engine 2026-08-25, that gap held 266 dead sources and 15,162 translation rows under `page:legal/` after the legal pages moved into their own collection, and 12 more under `blogCategory:` after a re-key from numeric id to slug.\n⛔⛔ A namespace may have SEVERAL producers. `page:` has three — the CMS pages collection, `scripts/register-home.mjs` and `scripts/register-pricing.mjs` — so a caller enumerating only its own documents would delete the other two. Enumerate against what the CONSUMER reads, never against what one producer writes.","required":["ref_prefix","expected_refs"],"properties":{"ref_prefix":{"type":"string","description":"The `object_ref` namespace to prune, including its separator — e.g. `page:` or `blogCategory:`. Matched as a literal prefix.","minLength":1,"maxLength":64,"example":"blogCategory:"},"expected_refs":{"type":"array","description":"The COMPLETE set of `object_ref`s that should exist under `ref_prefix`. Anything under the prefix and absent from this list is retired, with its `Translation` rows, by cascade.\n⛔ May not be empty. An empty list is exactly what a caller that failed to read its own source produces, and the ambiguous value must never be the destructive one (§2.44).","minItems":1,"maxItems":25000,"items":{"$ref":"#/components/schemas/ObjectRef"}},"surfaces":{"type":"array","description":"Restrict the prune to these surfaces. Omit only when one live set really governs every surface in the namespace — under `page:` it does not, because the document surfaces are keyed by the CMS document set while `slug` is keyed by the wider route registry.","minItems":1,"maxItems":32,"items":{"$ref":"#/components/schemas/TranslationSurface"}}}},"TranslationPruneScope":{"type":"object","description":"Retire every registered source inside this scope that is NOT named in `items` — the de-registration path (#735). Without it, a key deleted from the caller's catalogue leaves its `TranslatableString` and all 57 `Translation` rows behind for ever.\n⛔ The scope is REQUIRED rather than a `prune: true` boolean, and that is the whole safety argument: the CMS posts one document per request, so a boolean would make every page save retire every *other* page's strings. Naming the scope means a prune can only affect rows the caller has just enumerated completely, and a mis-scoped request deletes nothing instead of everything.\n\n**A RE-KEY IS FREE (#4131).** A retiring source whose `source_text` is byte-identical to a surviving one in the same scope hands its finished translations over instead of taking them to the grave — so a field that changes KEY without changing its WORDING is not re-translated into 57 locales and not re-billed. Adoption is deliberately conservative and silent when it cannot be certain: it fills only locales the survivor has not already finished, moves only `up_to_date` rows, and does nothing at all when two SURVIVING keys want the same text, because there is then no basis to prefer either. Several *retiring* rows sharing the text is not ambiguity — they are generations of one field, so the richest is adopted. A genuine content edit has a different hash, finds no candidate, and re-translates exactly as it should.","required":["surface","object_ref","expected_fields"],"properties":{"surface":{"$ref":"#/components/schemas/TranslationSurface"},"object_ref":{"$ref":"#/components/schemas/ObjectRef"},"expected_fields":{"type":"array","description":"The COMPLETE set of field names this scope should contain. Anything registered in the scope and absent from this list is retired.\n⛔ Stated explicitly rather than inferred from `items`, because `POST /v1/i18n/sources` is capped at 200 items and a real catalogue is larger — inferring the keep-list from a single batch would retire everything the *other* batches just registered. Being explicit also makes the destructive intent legible in the request rather than emergent from what the caller happened to omit.\n⛔ `maxItems` is a backstop, not a shaping choice: this list's length IS the catalogue's size, so it grows with the product. It was 10000, the dashboard catalogue crossed it on 2026-08-30, and `i18n-register` then failed on every push for 42 hours — no source registered, nothing marked stale, nothing re-translated, and nothing red on any PR. The client (`scripts/i18n-sync.mjs`) now refuses before it reaches this bound and warns at 80% of it, so the next breach is caught on the PR that causes it.\n⭐ With `field_from`/`field_before` the list need only be complete for that RANGE, so a catalogue of any size is pruned in chunks and this bound is a per-request size, not a ceiling on the catalogue (2026-10-25).","minItems":1,"maxItems":25000,"items":{"$ref":"#/components/schemas/TranslationField"}},"field_from":{"type":["string","null"],"maxLength":64,"description":"Optional lower bound (inclusive) of the field range this prune reaches, in code-point order. `null` or absent = open. With `field_before`, lets a caller send its keep-list in chunks whose half-open ranges tile the keyspace (first `field_from` and last `field_before` null), so every registered field falls in exactly one request. Every `expected_fields` entry must lie inside the range, or the request is a `422`."},"field_before":{"type":["string","null"],"maxLength":64,"description":"Optional upper bound (exclusive) of the field range, in code-point order. Must sort after `field_from` when both are given."}}},"TranslationSourceBatch":{"type":"object","description":"A batch must register something, retire something, or both. A body with neither `items` nor a prune is a `422`: it would otherwise answer `200` with an empty result list, which is a reassuring success for a request that did nothing and is indistinguishable from a batch whose items were lost in transit (§2.44).","properties":{"items":{"type":"array","description":"The source fields to register. Capped at 500 per request (200 until 2026-10-25) — a larger batch is a `422` telling the caller to split it.\nOptional so that a RETIREMENT-ONLY request is expressible: the repo-level orphan sweep sends `prune_namespace` and has nothing of its own to register, and inventing a filler item to carry a deletion is exactly the shape nobody reviews properly.","minItems":1,"maxItems":500,"items":{"$ref":"#/components/schemas/TranslationSourceItem"}},"prune":{"$ref":"#/components/schemas/TranslationPruneScope"},"prune_namespace":{"$ref":"#/components/schemas/TranslationNamespacePrune"}}},"TranslationSourceBatchResult":{"type":"object","required":["results"],"properties":{"results":{"type":"array","description":"One result per submitted item, in the order submitted.","items":{"$ref":"#/components/schemas/TranslationSourceResult"}},"retired":{"type":"array","description":"Field names deleted by `prune`, sorted. Empty when `prune` was absent or nothing was stale. Reported rather than assumed: a destructive operation that returns no number is indistinguishable from one that did nothing.","items":{"$ref":"#/components/schemas/TranslationField"}},"retired_refs":{"type":"array","description":"`object_ref`s deleted by `prune_namespace`, sorted. Empty when `prune_namespace` was absent or nothing was dead. Kept separate from `retired` on purpose: a count of retired FIELDS and a count of retired DOCUMENTS are different quantities and must never be read as one.","items":{"$ref":"#/components/schemas/ObjectRef"}},"repo_translations":{"type":"object","description":"What became of the items' `repo_translations`, counted like `recordRepoTranslations`. All zero when none were sent.","required":["recorded","unchanged","stale","missing","refused"],"properties":{"recorded":{"type":"integer"},"unchanged":{"type":"integer"},"stale":{"type":"integer"},"missing":{"type":"integer"},"refused":{"type":"integer"}}}}},"TranslationSourceItem":{"type":"object","required":["surface","object_ref","field","source_text"],"properties":{"surface":{"$ref":"#/components/schemas/TranslationSurface"},"object_ref":{"$ref":"#/components/schemas/ObjectRef"},"field":{"$ref":"#/components/schemas/TranslationField"},"source_text":{"type":"string","description":"The source-locale text to translate. May be empty to clear a field.","maxLength":200000},"source_locale":{"description":"The locale `source_text` is written in. Defaults to `en`.","allOf":[{"$ref":"#/components/schemas/LocaleCode"}]},"is_html":{"type":"boolean","description":"Translate tag-aware, preserving markup. Set for rich-text/body fields; leave `false` for plain strings, titles and slugs.","default":false},"repo_translations":{"type":"object","description":"The repository's committed translations OF THIS `source_text`, locale -> text. Written repo-owned in the same transaction as the registration (the same rules as `recordRepoTranslations`: a text that breaks a pinned term rendering is refused), so no machine translation is bought for those locales; only the locales absent here are machine-translated. Counted in the batch result's `repo_translations`.","additionalProperties":{"type":"string","minLength":1}}}},"TranslationSourceResult":{"type":"object","required":["surface","object_ref","field","content_hash","changed"],"properties":{"surface":{"$ref":"#/components/schemas/TranslationSurface"},"object_ref":{"$ref":"#/components/schemas/ObjectRef"},"field":{"$ref":"#/components/schemas/TranslationField"},"content_hash":{"$ref":"#/components/schemas/ContentHash"},"changed":{"type":"boolean","description":"Whether this item actually changed anything. `false` means the source text was already registered with this exact hash, so no locale was marked stale and no re-translation was queued."}}},"TranslationStatus":{"type":"string","description":"Per-locale state of one source string. `stale` means the source changed since this locale was translated — the previous text is still available and is still served (see `getTranslationBundle`).","enum":["missing","stale","translating","up_to_date","failed"],"example":"up_to_date"},"TranslationSurface":{"type":"string","description":"What kind of content a source string is. Drives the admin Translation Status coverage matrix and lets a caller fetch only the surfaces it renders (docs/28). `admin_ui` is the staff console's catalogue and the one surface translated into a SUBSET of the enabled locales — Arabic only, because the admin console ships `en` + `ar` (docs/759).","enum":["ui","page","kb","meta_title","meta_description","open_graph","schema","alt_text","breadcrumb","sitemap","slug","notification","email","sms","push","image","listing_field","listing_copy","offer","site_content","survey","extra","site_panel","admin_ui","holder_page","zaraz_consent"],"example":"page"},"Trial":{"type":"object","required":["id","org_id","status","product_line","max_sites","started_at","ends_at"],"properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["active","expired","converted","canceled","switched"]},"product_line":{"type":"string","description":"The line's CODE, not its display name — the dashboard renders the label from its own catalogue, so prose here would be a second, untranslated source of that word on the screen."},"max_sites":{"type":"integer"},"started_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"},"auto_convert_opt_in":{"type":"boolean","description":"Whether the customer agreed **at the start** that this may become a paid subscription when the period ends. Captured per trial rather than read from the template at expiry, so consent given today cannot be re-interpreted by a template edited in three months."},"days_remaining":{"type":"integer","minimum":0,"description":"Whole days until `ends_at`, rounded UP and floored at zero. Computed on the server on purpose: a client doing `(ends_at - Date.now())` measures the **device** clock, so a laptop a day out tells the customer their trial ends tomorrow when it ends today — and this is the number that drives an increasingly insistent upgrade prompt. `0` means the trial has ended, never \"today\", so a screen can branch on it."},"upgrade":{"allOf":[{"$ref":"#/components/schemas/TrialUpgradeOffer"}],"nullable":true,"description":"The plan this trial invites the customer to buy, priced in their own currency (`X-Zinn-Currency`, falling back to the org default). ⛔ `null` when the template names no target or when there is no price in that currency — the screen must then offer a plan picker and **never** derive a target of its own (docs/20 §1a). An offer we cannot honour at checkout is worse than no offer."},"switch_deadline":{"type":"string","format":"date-time","nullable":true,"description":"s1014 L58 (owner 2026-10-16). Until when this trial may still be switched to another product (`POST /v1/trials/{trial_id}/switch`): its first three days. `null` when it cannot be — not running, already the result of a switch, or the window is over."},"app":{"type":"string","description":"s1014 APPTRIAL — the app picked at trial start, empty when none was."},"plan":{"type":"object","nullable":true,"description":"s1014 L70. The plan this trial was started for (the one the customer clicked) and the application it installs, so the create-site form opens on that application — a \"Moodle Pro\" trial opens on Moodle, not WordPress. `null` when no plan was recorded (a staff grant); the form then keeps its own default.","required":["plan_code","plan_name","application"],"properties":{"plan_code":{"type":"string"},"plan_name":{"type":"string"},"application":{"type":"string","nullable":true,"description":"The one-click application key the plan installs (`moodle`), or `null`."}}}}},"TrialEligibility":{"type":"object","required":["plan_code","eligible","reason"],"properties":{"plan_code":{"type":"string"},"eligible":{"type":"boolean"},"duration_days":{"type":"integer","nullable":true},"max_sites":{"type":"integer","nullable":true},"requires_card":{"type":"boolean"},"card_on_file":{"type":"boolean","description":"⚖️ 2026-10-21 (ZEAB2): a verified payment method we can charge off-session later is already on file for this org (a Stripe card, wallet, SEPA, Link, Revolut Pay or Amazon Pay mandate, or a vaulted PayPal account; never charged), so a `requires_card` trial can start without the card step. s1014 row 145: any gateway, not only Stripe."},"prepaid_on_file":{"type":"boolean","description":"s1014 row 145 (owner 2026-10-31, \"allow for crypto if possible\"): the org has a SETTLED crypto deposit (NOWPayments wallet top-up) worth at least this plan's first monthly price in the same currency, which also lets a `requires_card` trial start. The credit stays in the wallet and pays the first month when the customer picks the plan."},"crypto_prepay":{"type":"object","nullable":true,"description":"The crypto alternative to the card step: deposit `amount_minor` `currency` (the plan's first monthly price, never below the smallest wallet top-up; a settled deposit of the first month is what starts the trial) through `POST /v1/wallet/top-ups` with `gateway: nowpayments`. `null` when the trial needs no card, the plan has no monthly price in the caller's currency, or no crypto rail is enabled.","required":["amount_minor","currency"],"properties":{"amount_minor":{"type":"integer","format":"int64","description":"Integer minor units."},"currency":{"type":"string","description":"ISO 4217."}}},"template_code":{"type":"string","description":"The `TrialTemplate.code` this plan (and `campaign`, when given) resolves to; empty when none."},"reason":{"type":"string","description":"Empty when eligible. `used_by_you_or_company` (docs/1000 §1): the free-trial abuse guard would refuse — the same person or company already had a trial or paid on another account. Never says which identifier matched.","enum":["","no_trial_on_plan","no_billing_org","already_used","already_subscribed","used_by_you_or_company"]},"upgrade":{"allOf":[{"$ref":"#/components/schemas/TrialUpgradeOffer"}],"nullable":true,"description":"The plan the customer asked about, priced in their currency, so a refusal ends in a decision rather than a dead end.\n⚖️ Owner instruction 2026-08-19: *\"if they try to start a new trial, it should tell them you already trialed this product and offer to upgrade now to proper subs\"*. Sent on **every** answer, not only ineligible ones, so the surface never needs a second call to turn a \"no\" into an offer. `null` when the plan has no active version or no price in this currency."}}},"TrialEnvelope":{"type":"object","required":["data"],"properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Trial"}],"nullable":true}}},"TrialStart":{"type":"object","required":["plan_code"],"properties":{"plan_code":{"type":"string","maxLength":64},"org_id":{"type":"string","format":"uuid","nullable":true,"description":"Required only when the caller bills for more than one organization. With exactly one it is unambiguous; with several it is asked for rather than guessed, because starting a reseller's one-per-org trial on the wrong client is not a choice an API should make by picking the first row."},"auto_convert_opt_in":{"type":"boolean","default":false,"description":"⛔ Defaults to false — the direction that cannot take money nobody agreed to."},"device_id":{"type":"string","pattern":"^[0-9a-fA-F]{32}$","description":"docs/1000 §1 — the dashboard's random per-browser id, used only by the free-trial abuse guard (\"same browser as an account that already had a trial\"). Stored only as a keyed hash."},"campaign":{"type":"string","maxLength":64,"default":"","description":"⚖️ A campaign-only trial (owner 2026-10-21 — the \"Move from Zeabur\" page's 30-day Developer Hosting trial, `zeabur`). Honoured only when an active template of that campaign is offered on the plan; otherwise the plan's public trial applies. A card-required template (`requires_card`) answers 422 `refusal.trial.cardRequired` until a verified card is on file — it is never charged."},"app":{"type":"string","enum":["","node","python","php","abantecart","cakephp","concretecms","craft","dolibarr","dotnet","drupal","joomla","laravel","matomo","mautic","mediawiki","modx","moodle","nextcloud","opencart","oscommerce","osticket","owncloud","payload","phpbb","piwigo","prestashop","silverstripe","strapi","suitecrm","typo3","whmcs","woocommerce","wordpress","zenphoto"],"default":"","description":"s1014 APPTRIAL — the app picked at trial start. Must be an app of `plan_code` (Node.js/Python on `dev_start`, PHP on `linux_basic`, a one-click app on its `app_<app>_business|pro` plan; WordPress, WooCommerce, Nextcloud, ownCloud, Strapi, Payload and WHMCS on `mainstream_start`), else 422. Recorded on the trial as `app`, and the first step's create form opens on it (`?stack=`, plus `&app=` where the stack asks which application)."}}},"TrialSwitch":{"type":"object","required":["plan_code"],"properties":{"plan_code":{"type":"string","maxLength":64,"description":"A plan of the product to switch the trial to (its line's trial applies)."}}},"TrialUpgradeOffer":{"type":"object","description":"A priced upgrade offer for a trialling customer (docs/20 §1c.2 row 3).\n⛔ This is **not** `TrialTemplate.converts_to`, which arms *automatic* conversion at expiry and is NULL on every template by owner decision (docs/20 §1b). The offer is a button a human clicks; the other is a charge nobody clicks. They were one column and are now two, because populating that column to label a button would have armed auto-billing platform-wide with nothing looking wrong.","required":["plan_code","plan_name","plan_version_id","interval","price_minor","price_currency"],"properties":{"plan_code":{"type":"string"},"plan_name":{"type":"string"},"plan_version_id":{"type":"string","format":"uuid"},"interval":{"type":"string","enum":["monthly","annual"]},"price_minor":{"type":"integer","format":"int64","minimum":1,"description":"Integer minor units of `price_currency` (§2.8 — money is never a float)."},"price_currency":{"$ref":"#/components/schemas/CurrencyCode"}}},"TrialWinbackOffer":{"type":"object","description":"The one-time 7-day extension an ended free trial may take (s1014 L55).","required":["trial_id","product_line","template_code","extra_days","ended_at","offer_ends_at"],"properties":{"trial_id":{"type":"string","format":"uuid"},"product_line":{"type":"string"},"template_code":{"type":"string"},"extra_days":{"type":"integer","description":"Always 7 (the owner's one-time offer)."},"ended_at":{"type":"string","format":"date-time"},"offer_ends_at":{"type":"string","format":"date-time","description":"The last moment the extension can be taken."}}},"TrialWinbackOfferEnvelope":{"type":"object","required":["offer"],"properties":{"offer":{"oneOf":[{"$ref":"#/components/schemas/TrialWinbackOffer"},{"type":"null"}]}}},"TrialWinbackTake":{"type":"object","properties":{"org_id":{"type":"string","format":"uuid","description":"Required when the caller bills for several organizations."}}},"UnbilledBucket":{"type":"object","additionalProperties":false,"required":["client_id","currency","value_minor","total_minor","minutes","billable"],"properties":{"client_id":{"type":"string","format":"uuid","nullable":true},"currency":{"type":"string","minLength":3,"maxLength":3},"value_minor":{"type":"integer","description":"Hourly work","in minor units.":null},"fixed_value_minor":{"type":"integer","description":"Fixed-price work not yet billed."},"total_minor":{"type":"integer"},"minutes":{"type":"integer"},"duration_label":{"type":"string"},"entry_count":{"type":"integer"},"unpriced_minutes":{"type":"integer","description":"⛔ Minutes logged against work with **no rate card**, reported separately from the money. They are not worth zero, they are unpriced — an agency that cannot see them will not fix them, and a threshold schedule would sit under its trigger for ever."},"unpriced_entry_count":{"type":"integer"},"fixed_task_count":{"type":"integer"},"billable":{"type":"boolean"},"blocked_reason":{"type":"string","description":"Why this client cannot be billed — set when a rate card's currency disagrees with the project's. Names both currencies so the screen can say what to fix."}}},"UnbilledTime":{"type":"object","required":["data","can_bill"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/UnbilledBucket"}},"can_bill":{"type":"boolean","description":"Whether the agency invoicing suite is reachable at all. Told to the console rather than discovered by pressing the button, so it never offers a Bill-now that can only refuse."},"billing_target":{"type":"string","enum":["agency_invoicing","platform_checkout"],"description":"Where Bill now sends the work. `platform_checkout` only for Zinn Digital®'s own organisation, whose client work is billed on Zinn®'s checkout (docs/670 §3)."},"can_start_from_quote":{"type":"boolean","description":"Whether this caller may list quote requests and start projects from them here — the issuer organisation AND the same `quotes.manage` staff permission the admin queue requires."},"can_manage_checkout_bills":{"type":"boolean","description":"Whether this caller may send and void checkout bills here — the issuer organisation AND the same `billing.entitlement.manage` staff permission the admin console requires."}}},"UptimeAllowance":{"type":"object","required":["limit","used","purchased","free_included","pack_size"],"properties":{"limit":{"type":"integer","description":"Monitors permitted: free_included + purchased."},"used":{"type":"integer","description":"Monitors that exist","paused ones included.":null},"purchased":{"type":"integer","description":"Capacity bought as monthly packs."},"free_included":{"type":"integer","description":"Included with every account."},"pack_size":{"type":"integer","description":"Monitors one purchased pack adds."},"check_interval_seconds":{"type":"integer","description":"How often this organisation's monitors are checked — 60 with any pack, 300 without. A property of the ORG, not of a monitor."}}},"UptimeHistoryPoint":{"type":"object","required":["hour","checks","failures"],"properties":{"hour":{"type":"string","format":"date-time"},"checks":{"type":"integer"},"failures":{"type":"integer"},"uptime_percent":{"type":"number"},"average_response_ms":{"type":"integer","nullable":true},"worst_response_ms":{"type":"integer","nullable":true}},"description":"One clock hour. ⛔ An hour with no checks has **no point**, so a gap in our own coverage renders as a gap rather than silently as 100%."},"UptimeIncident":{"type":"object","required":["id","started_at","reason"],"properties":{"id":{"type":"string","format":"uuid"},"started_at":{"type":"string","format":"date-time"},"ended_at":{"type":"string","format":"date-time","nullable":true,"description":"null while the outage is still going."},"reason":{"type":"string","enum":["timeout","dns","connection","tls","status","body","unknown"]},"status_code":{"type":"integer","nullable":true},"detail":{"type":"string","description":"An authored, customer-safe sentence built from `reason` — never an upstream error string, which can carry an internal hostname or a path."},"confirmed_by":{"type":"array","items":{"type":"string"},"description":"Which vantage points agreed the address was unreachable, e.g. `edge:FRA`. Stored rather than inferred, so an incident opened on a single vantage is visibly weaker evidence than one two locations agreed on."}}},"UptimeMigrationOffer":{"type":"object","required":["reason","checks"],"description":"Present only when the address measured badly enough, for long enough, and is NOT already hosted with us. ⛔ It carries **numbers and a reason code, never a rendered sentence**: the client composes the copy from its own catalogue, because a sentence built server-side would be English in a UI shipped in 58 languages.","properties":{"reason":{"type":"string","enum":["downtime","slow"]},"checks":{"type":"integer","description":"Checks made in the window — what makes the claim checkable."},"failures":{"type":"integer"},"uptime_percent":{"type":"number","nullable":true},"average_response_ms":{"type":"integer","nullable":true}}},"UptimeMonitor":{"type":"object","required":["id","url","state","enabled","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"name":{"type":"string"},"state":{"type":"string","enum":["unknown","up","down","paused"],"description":"⛔ `unknown` is a real state and is not a synonym for `up` — it means \"not checked yet\" and is excluded from every uptime percentage."},"enabled":{"type":"boolean"},"expect_text":{"type":"string"},"check_from":{"type":"string","nullable":true,"description":"Upper-case ISO alpha-2 country the second-opinion check runs from; null = any of our locations."},"site_id":{"type":"string","format":"uuid","nullable":true,"description":"Set only when the address happens to be one of this organisation's own sites. Navigation only — the monitor works identically without it, and must, because the product exists to watch addresses we do not host."},"last_result_at":{"type":"string","format":"date-time","nullable":true},"last_up_at":{"type":"string","format":"date-time","nullable":true},"last_down_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"down_reason":{"type":"string","nullable":true,"enum":["timeout","dns","connection","tls","status","body","unknown"],"description":"The open incident's enumerated cause; null when the monitor has no open incident. A code, never a sentence: the screen renders it. `tls` or `connection` on an https:// address is how an http-only site typed without a scheme fails, and the dashboard offers to watch the http:// address instead."},"summary":{"$ref":"#/components/schemas/UptimeSummary"}}},"UptimeMonitorCreate":{"type":"object","required":["url"],"properties":{"url":{"type":"string","maxLength":2048,"description":"Any public http(s) address. Stored canonicalised — userinfo stripped, fragment dropped, default port removed — so what is measured, cached and shown are the same string.","example":"https://example.com/"},"name":{"type":"string","maxLength":120,"description":"What to call it on screen. Blank falls back to the host. ⛔ `name`, not `label`: `label` is an attribute of DRF's `Field` and cannot be a serializer field name, and a read key that differs from its write key is worse than renaming both."},"expect_text":{"type":"string","maxLength":200,"description":"Text that must appear in the response for the check to pass. ⭐ This is what catches the failure a status code cannot — a site whose database has gone but whose index still answers `200` with an empty page."},"check_from":{"type":"string","nullable":true,"pattern":"^[A-Za-z]{2}$","description":"ISO 3166-1 alpha-2 country the second-opinion check runs from, for a site that answers only visitors in one country. Empty or null checks from any of our locations. ⛔ A country we cannot check from is refused with 422 naming the countries we can (`check_from_countries` on the list) — never a silent fallback to another country, which would read a geofenced site as down."}}},"UptimeMonitorDetail":{"allOf":[{"$ref":"#/components/schemas/UptimeMonitor"},{"type":"object","properties":{"history":{"type":"array","items":{"$ref":"#/components/schemas/UptimeHistoryPoint"}},"incidents":{"type":"array","items":{"$ref":"#/components/schemas/UptimeIncident"}},"vitals":{"type":"array","items":{"$ref":"#/components/schemas/UptimeVitalsPoint"}},"migration_offer":{"allOf":[{"$ref":"#/components/schemas/UptimeMigrationOffer"}],"nullable":true}}}]},"UptimeMonitorList":{"type":"object","required":["data","allowance"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/UptimeMonitor"}},"allowance":{"$ref":"#/components/schemas/UptimeAllowance"},"check_from_countries":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"},"description":"The countries a monitor's `check_from` may name right now, sorted. Derived from our live check locations, so a country disappears from here the moment we can no longer check from it."}}},"UptimeMonitorUpdate":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Pause or resume. Pausing closes any open incident."},"name":{"type":"string","maxLength":120},"check_from":{"type":"string","nullable":true,"pattern":"^[A-Za-z]{2}$","description":"ISO 3166-1 alpha-2 country the second-opinion check runs from, for a site that answers only visitors in one country. Empty or null checks from any of our locations. ⛔ A country we cannot check from is refused with 422 naming the countries we can (`check_from_countries` on the list) — never a silent fallback to another country, which would read a geofenced site as down."}},"description":"⛔ The URL is deliberately absent — see `updateUptimeMonitor`."},"UptimeSummary":{"type":"object","required":["window_days","checks","failures"],"properties":{"window_days":{"type":"integer"},"checks":{"type":"integer","description":"Checks made in the window — the denominator."},"failures":{"type":"integer"},"uptime_percent":{"type":"number","nullable":true,"description":"⛔ **null when `checks` is 0**, never 100. A monitor that has not been checked has proved nothing, and the ambiguous value must not be the reassuring one."},"average_response_ms":{"type":"integer","nullable":true,"description":"Mean over SUCCESSFUL checks only — a timed-out connection is not a slow page."},"worst_response_ms":{"type":"integer","nullable":true}}},"UptimeVitalsPoint":{"type":"object","required":["measured_at","source"],"properties":{"measured_at":{"type":"string","format":"date-time"},"source":{"type":"string","enum":["lab","field"]},"performance_score":{"type":"integer","nullable":true},"lcp_ms":{"type":"integer","nullable":true},"cls_milli":{"type":"integer","nullable":true},"inp_ms":{"type":"integer","nullable":true},"ttfb_ms":{"type":"integer","nullable":true}}},"User":{"type":"object","required":["id","email","locale"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"email":{"type":"string","format":"email","example":"neil@example.com"},"name":{"type":"string","example":"Neil Lock"},"locale":{"$ref":"#/components/schemas/LocaleCode"},"locale_is_confirmed":{"type":"boolean","description":"Whether this language was CHOSEN or merely defaulted. `false` means nobody has ever picked one for this person, so English is a guess rather than a preference. The admin console shows it to staff because comms triggered from there go out in the customer's language, and it is what lets the dashboard decide whether the server's value should override the browser's.\n\n`AdminPerson` inherits this field — it is `allOf` this schema."},"currency":{"type":"string","description":"The ISO-4217 code this person browses in, or `\"\"` when they have never chosen one (#460).\n\nBlank is a real value and clients MUST handle it. It means \"fall through to the geo/locale inference\" (docs/29 §3.1), which is what every signed-in visitor gets until they touch the switcher. Reporting the base currency here instead would be indistinguishable from a deliberate USD, would make the inference unreachable, and would pin every new customer to dollars for ever.","example":"GBP"},"currency_is_confirmed":{"type":"boolean","description":"Whether that currency was CHOSEN or merely inferred — the same distinction `locale_is_confirmed` draws, and needed for the same reason. The geo/locale chain re-runs on every request, so without this a client cannot tell a deliberate USD (picked by someone sitting in Berlin) from an inferred one, and one of the two always loses."},"analytics_opted_out":{"type":"boolean","description":"Whether this person has asked NOT to have their use of the app measured.\n\n⚖️ Owner ruling 2026-08-24: product analytics inside the signed-in app runs on legitimate interest, disclosed in the privacy notice, with a real switch in account settings — not behind a cookie banner. Default `false`.\n\n⛔ Served here and not merely accepted on `PATCH`, because the settings screen has to render the switch in its CURRENT position. A write-only preference renders as \"off\" on every page load, so someone who opted out sees their choice survive until the next refresh and then reasonably concludes it did not save.\n\n⛔ Optional here, exactly like `locale_is_confirmed` and `currency_is_confirmed` beside it — the engine always emits all three, but a client must treat an absent value as `false` rather than as an error. A `default:` on this property makes the generated TypeScript mark it REQUIRED, which is stricter than its two identical siblings and breaks every existing fixture for a distinction the wire does not actually draw."},"marketing_opt_out":{"type":"boolean","description":"Whether this person has opted out of marketing e-mail (\"Don't email me offers and tips\") from the organisations they belong to. Served so the settings switch renders in its current position. Default `false` (we may e-mail — owner ruling 2026-08-26, opt-out / soft opt-in)."}}},"UserTextClass":{"type":"string","enum":["verbatim","communication","structured"],"description":"docs/1067, ADR 0039. `verbatim`: published or identifying text (anchor texts, URLs, keywords, brand names, domains), never translated anywhere. `communication`: text for a person to read, translated per reader with the original shown. `structured`: numbers, choices, dates and money, never translated."},"UserTextTranslation":{"type":"object","required":["text","locale","from_locale"],"properties":{"text":{"type":"string","description":"The machine translation for this reader."},"locale":{"type":"string","description":"BCP-47 language it was translated into."},"from_locale":{"type":"string","description":"BCP-47 language of the original, as detected from the text."}}},"Uuid":{"type":"string","format":"uuid","description":"UUIDv7 identifier — sortable by creation time (docs/02 §8).","example":"0190f1a2-3b4c-7d8e-9f01-234567890abc"},"Vector":{"type":"object","required":["id","values"],"properties":{"id":{"type":"string","maxLength":512,"description":"Your own identifier. Writing the same id twice replaces the vector."},"values":{"type":"array","items":{"type":"number","format":"float"},"description":"Exactly `dimension` values."},"metadata":{"type":"object","additionalProperties":true,"description":"Arbitrary JSON stored alongside the vector and returned with every match. Also what `filter` matches against on a query."}}},"VectorDeleteRequest":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","minItems":1,"maxItems":1000,"items":{"type":"string","maxLength":512}}}},"VectorDeleteResult":{"type":"object","required":["deleted"],"properties":{"deleted":{"type":"integer"}}},"VectorIndex":{"type":"object","required":["id","name","dimension","metric","status","vectors","storage_bytes","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Lower-case, hyphenated, unique within the organisation."},"dimension":{"type":"integer","description":"The width your embedding model emits, and the width reads return. Fixed at creation."},"metric":{"type":"string","enum":["cosine","l2","inner_product"],"description":"The distance function. Fixed at creation."},"status":{"type":"string","enum":["ready","deleting"]},"vectors":{"type":"integer","format":"int64","description":"How many vectors the index holds."},"storage_bytes":{"type":"integer","format":"int64","description":"What the index counts for against `vector_index_gb`. A published formula rather than a physical table size, so it is reproducible: 96 bytes of row overhead, plus the stored width (4 bytes per value, or 2 above 2000 dimensions), plus the byte lengths of your id and metadata."},"created_at":{"type":"string","format":"date-time"}}},"VectorIndexWrite":{"type":"object","required":["name","dimension"],"properties":{"name":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$","maxLength":64},"dimension":{"type":"integer","minimum":1,"maximum":3072},"metric":{"type":"string","enum":["cosine","l2","inner_product"],"default":"cosine"}}},"VectorQueryRequest":{"type":"object","required":["values"],"properties":{"values":{"type":"array","items":{"type":"number","format":"float"},"description":"The query vector — exactly `dimension` values."},"top_k":{"type":"integer","minimum":1,"maximum":200,"default":10},"filter":{"type":"object","additionalProperties":true,"description":"Restrict the search to vectors whose metadata contains these keys and values. Containment, not equality of the whole object, so a filter naming one key matches a vector carrying that key among others."}}},"VectorQueryResult":{"type":"object","required":["matches"],"properties":{"matches":{"type":"array","items":{"type":"object","required":["id","distance","metadata"],"properties":{"id":{"type":"string"},"distance":{"type":"number","format":"float","description":"Distance in the index's own metric. Smaller is nearer for every metric we serve."},"metadata":{"type":"object","additionalProperties":true}}}}}},"VectorUpsertRequest":{"type":"object","required":["vectors"],"properties":{"vectors":{"type":"array","minItems":1,"maxItems":1000,"items":{"$ref":"#/components/schemas/Vector"}}}},"VectorUpsertResult":{"type":"object","required":["upserted","vectors"],"properties":{"upserted":{"type":"integer","description":"How many vectors this call wrote."},"vectors":{"type":"integer","format":"int64","description":"The index's new total."}}},"VectorUsage":{"type":"object","required":["indexes_used","storage_bytes_used","queries_this_month","period"],"properties":{"indexes_used":{"type":"integer"},"indexes_limit":{"type":"integer","nullable":true,"description":"`null` when the plan states no cap."},"storage_bytes_used":{"type":"integer","format":"int64"},"storage_gb_limit":{"type":"integer","nullable":true},"queries_this_month":{"type":"integer","format":"int64"},"queries_monthly_limit":{"type":"integer","nullable":true},"period":{"type":"string","description":"The calendar month these query counts are for, as `YYYY-MM` in UTC."}}},"VendorAllowance":{"type":"object","description":"The **effective** ceiling on one site service, after the vendor package's allowance and the quantity the customer actually bought have been reconciled: the lower of the two, with either side being unlimited yielding to the other. Distinct from `HostingAllowance`, which reports what the package advertises — this reports what the customer may use, and the two differ whenever a plan sells less than the package template happens to permit.","required":["value","unlimited"],"additionalProperties":false,"properties":{"value":{"type":"integer","nullable":true,"description":"The effective ceiling, or null when `unlimited` is true.","example":10},"unlimited":{"type":"boolean","description":"Whether neither the package nor the entitlement publishes a ceiling."}}},"VendorFailure":{"type":"object","description":"One vendor failure, in the shape every AI surface renders. ⚖️ `CLAUDE.md` §57, owner ruling 2026-09-03: when an AI call fails, tell the customer whether the **provider** is down or whether **their own** account with that provider needs attention, and link that provider's own status board in a new tab.\n\n⛔⛔ The vendor is named only when the CUSTOMER chose it — an AI provider they may hold the key for, their Stripe, their Xero, their own mail server. The suppliers *we* chose (hosting, compute, CDN, network) are never named: the customer bought hosting and never picked them, so naming one leaks our supply chain, teaches them a vendor to blame, and gives them nothing they can act on. The registry behind this is default-deny, so an unregistered vendor is silent rather than exposed.","required":["class","code","message_key","retryable","tone"],"properties":{"class":{"type":"string","enum":["provider_outage","credential_problem","refused","our_fault"],"description":"What kind of thing this is, and therefore which link the customer gets. `provider_outage` links the vendor's status page. `credential_problem` is the customer's OWN account with that vendor — unpaid, out of quota, revoked — and links their billing page, deliberately **not** a status page, because the vendor is up and a green status board would only confuse.\n\n`refused` is **us** declining on purpose: no credits, or an account not in good standing. ⛔ Not an error, no vendor named, and never a status link — a vendor's status board is the wrong place to send somebody whose credits ran out.\n\n`our_fault` is everything else **including everything unclassified**. ⛔⛔ An unclassified failure is never reported as an outage: a 500 from our own code and a vendor outage look identical to a naive handler, and guessing \"outage\" blames a third party for our bug — the exact reverse of what §57 exists for."},"code":{"type":"string","description":"The narrower machine code, so a client can still tell a rate limit from a 5xx inside `provider_outage`. Open vocabulary: an unrecognised value renders through the `class`'s generic sentence rather than failing."},"message_key":{"type":"string","description":"A stable i18n key the client renders from its own catalogues. ⛔ Never an English sentence — an engine-authored sentence in a JSON body is the hardcoded user-facing string §2.7 forbids. `vendor_name` is interpolated into it and is itself **not** translated, being a proper noun.","example":"aiError.providerOutage"},"tone":{"type":"string","enum":["warning","neutral","positive"],"description":"How the surface should paint it, and it is a correctness property rather than decoration. A refusal is not always bad news — a board AI function that reports nothing is blocked arrives down the refusal path with the good answer, and painting it amber teaches a customer that good news looks like a fault."},"retryable":{"type":"boolean","description":"Whether trying the same thing again could plausibly work."},"vendor":{"type":"string","description":"The vendor slug, present only when the customer chose that vendor. Absent otherwise — including for every supplier we chose."},"vendor_name":{"type":"string","description":"The vendor's own name, shown verbatim and never translated.","example":"Anthropic (Claude)"},"status_url":{"type":"string","format":"uri","description":"The vendor's OWN status board, opened in a new tab. Present only on `provider_outage` for a customer-connected vendor. A vendor with no published status page simply omits it and the sentence stands on its own."},"billing_url":{"type":"string","format":"uri","description":"Where the customer fixes a billing or quota problem on their own account with that vendor. Present only on `credential_problem`, and only when the problem is an empty balance."},"keys_url":{"type":"string","format":"uri","description":"Where the customer mints a REPLACEMENT key on their own account with that vendor. Present only on `credential_problem`, and only when the key itself was rejected.\n\n⛔ This or `billing_url`, never both. A revoked key and an unpaid bill are different problems with different doors, and sending somebody whose key was revoked to a billing page shows them an account where nothing is wrong — they spend the trip and come back no better off, which is worse than no link at all. A vendor connected by OAuth has no keys page and correctly carries neither."},"retry_after":{"type":"number","description":"Seconds the vendor asked us to wait, when it told us. Omitted when nobody told us — ⛔ `null` and `0` are different answers and only one of them is honest."}}},"VendorState":{"type":"string","description":"docs/78 §3.2. `under_review` is the anti-fraud gate, not a formality; `suspended` hides live listings while existing orders finish; a `closed` vendor's outstanding balance still pays out.","enum":["registered","details_submitted","under_review","approved","rejected","suspended","closed"]},"VisibilityAudit":{"type":"object","description":"One run of one product against one watched domain.","required":["id","target_id","kind","status"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"target_id":{"$ref":"#/components/schemas/Uuid"},"kind":{"$ref":"#/components/schemas/VisibilityAuditKind"},"status":{"$ref":"#/components/schemas/VisibilityAuditStatus"},"trigger":{"type":"string","enum":["scheduled","manual","staff"]},"score":{"type":"integer","nullable":true,"minimum":0,"maximum":100,"description":"0–100, or `null` when nothing could be measured. **`null` is not zero.** Zero means we asked and this site is invisible; `null` means we could not ask. A client that renders the second as the first tells a paying customer the answer engines have dropped them on a morning when a provider was simply unreachable."},"summary":{"type":"object","additionalProperties":true,"description":"The product-specific payload — the engine answers and mention rate for `ai_visibility`, the per-platform ratings for `reputation`, the crawl totals for `onpage`. For `onpage`, `crawl_truncated` says whether the crawl stopped at its page budget: \"no issues found\" after crawling 100 of 40,000 pages is not a clean site.\n\nFor `rank`, every run carries its **complete** `keywords` array — each phrase, its position, and both AI-citation readings — so a client can chart the history from the audit list without a second call. Each row also carries `ai_overview_change` and `ai_mode_change`: `\"lost\"`, `\"gained\"`, or `null`. ⛔ `null` is *\"no comparison could be made\"* — the surface was absent from one of the two runs, or the citation could not be read — and is **not** \"unchanged\". The run totals `ai_overview_citations_lost` / `_gained` and `ai_mode_citations_lost` / `_gained` count those transitions in both directions, per surface. A transition is what raises `visibility.ai_citation.lost` / `.gained` and is the only thing that notifies a customer; the `rank_ai_overview_missing` / `rank_ai_mode_missing` findings are the corresponding **states**, true on every run until they change.\n\nFor `ai_visibility`, each `answers[]` row says whether the target was **found** as well as **cited**: `found` is `true` when the target's site was among the pages the engine's web search returned (`found_url` is that page, `found_count` how many pages the search returned), `false` when the engine searched and the site was absent, and `null` when the engine did not search, which means unknown, not \"not found\". `found: true` with `linked: false` is *found but not cited*; `competitors` are the domains cited instead. Each `cited_<engine>` finding's detail counts `found_not_cited`."},"charged_micros":{"type":"integer","description":"What this run cost the **customer** in credit micros. `0` for a scheduled run included in the add-on. The response deliberately carries no figure for what it cost Zinn®."},"error":{"type":"string","description":"Why a failed or partial run ended as it did — the provider's own words, or, when `error_key` is set, the English of that key (for a caller with no catalogue)."},"error_key":{"type":"string","description":"A refusal key (`refusal.*`) the console renders from its own catalogue in the reader's language, when the reason is ours rather than a provider's. Empty when `error` is a provider's own words. Rows stored before this field existed are mapped to it too.","example":"refusal.visibility.checkDidNotFinish"},"started_at":{"type":"string","format":"date-time","nullable":true},"finished_at":{"type":"string","format":"date-time","nullable":true},"findings":{"type":"array","items":{"$ref":"#/components/schemas/VisibilityFinding"}}}},"VisibilityAuditKind":{"type":"string","enum":["ai_visibility","reputation","onpage","product_data","rank","backlinks","keyword_research","competitors","domain_score","link_watch","brand_mentions","local_rank","brand_serp"],"description":"Which product an audit belongs to. `ai_visibility` — do the answer engines cite this site, and is it fit to be cited at all. `reputation` — ratings and recent reviews across Google, Trustpilot and Tripadvisor. `onpage` — a whole-site technical crawl. `product_data` — who else is selling this customer's products on Google Shopping and Amazon, where they come on the shelf, and how their price compares to the cheapest seller. `rank` — where this domain sits in the organic results for phrases the customer chose, in the market they sell in, checked daily. `backlinks` — the live link profile and what has been gained and lost since the last reading. `keyword_research` — which search phrases are worth targeting, how many people search them each month, how hard the first page is to break into, and what advertisers pay for a click. `competitors` — which sites compete with this domain in the organic results, how much they overlap, and the phrases they win that this domain does not. `domain_score` — what a domain is measurably worth in search: its organic traffic, how many phrases it ranks for, and what that traffic would cost to buy as advertising. `link_watch` — the individual links the customer watches, each page opened by our own fetcher and checked for the link still being there, still followed and still carrying its anchor. Part of Backlink Monitoring, never sold on its own, and never charged: no vendor is called. `brand_mentions` — which public web pages mention the phrases the customer listens for (a brand, a product, a person), in what tone, and how that count moves; each phrase is checked on its own schedule. `local_rank` — where a business sits on Google Maps, in the local 3-pack on the results page and in the organic results, for chosen keywords searched from chosen towns; each keyword in each town is one check of the plan's monthly allowance, never a credit charge. `brand_serp` — brand page 1: what Google's first page shows for the customer's brand and up to four variants, each new result read for tone, with an alert on a NEW negative one; sold only per check from Zinn® credits (`funding: credits`)."},"VisibilityAuditList":{"type":"object","required":["audits","count"],"properties":{"audits":{"type":"array","items":{"$ref":"#/components/schemas/VisibilityAudit"}},"count":{"type":"integer"},"target":{"$ref":"#/components/schemas/VisibilityTarget"}}},"VisibilityAuditStatus":{"type":"string","enum":["running","complete","partial","failed"],"description":"`partial` is a first-class state, not a tidy-up. An AI-visibility run asks several engines and one may be unreachable; a crawl may stop at its page budget. Recording either as `complete` would let a shrinking denominator report an improving score — the fewer engines answer, the higher the mention rate — which is a failure that arrives looking like good news."},"VisibilityFinding":{"type":"object","description":"One check within an audit, with the evidence behind it.","required":["code","severity","passed"],"properties":{"code":{"type":"string","description":"A stable machine code — `llms_txt`, `robots_allows_answer_engines`, `server_rendered`, `cited_perplexity`. Stable because it keys both the translated copy and the week-on-week comparison.\n\n⛔ For `rank`, the AI-answer codes come in two kinds and a client must not merge them. `rank_ai_overview_cited` / `rank_ai_overview_missing` and their `rank_ai_mode_*` counterparts are **states**: true of this run, and true every morning until Google changes its mind. `rank_ai_overview_lost` / `rank_ai_overview_gained` and the AI Mode pair are **transitions**, emitted only when this run disagrees with the last one that measured the same phrase — the losses are `critical`, and they are what a notification is sent for."},"severity":{"$ref":"#/components/schemas/VisibilityFindingSeverity"},"passed":{"type":"boolean"},"detail":{"type":"object","additionalProperties":true,"description":"Evidence — the URLs seen, the counts, which engine answered."},"weight":{"type":"integer","description":"How much this check contributes to the score. `0` for a purely informational finding, so adding one can never move a customer's score without a decision."}}},"VisibilityFindingSeverity":{"type":"string","enum":["critical","warn","info","pass"],"description":"`pass` is a severity rather than a separate flag because the passes are half the product: an audit that listed only faults would show a healthy site an empty screen."},"VisibilityPlan":{"type":"object","required":["products","from_plan","sellable","external_allowance","external_used"],"properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/VisibilityAuditKind"}},"from_plan":{"type":"array","items":{"$ref":"#/components/schemas/VisibilityAuditKind"},"description":"Products granted by the plan or a bundle rather than by a standalone add-on. An upsell surface reads this and says \"included in your plan\" instead of offering to sell a capability the customer already holds."},"sellable":{"type":"array","items":{"$ref":"#/components/schemas/VisibilityAuditKind"}},"external_allowance":{"type":"integer"},"external_used":{"type":"integer"},"external_remaining":{"type":"integer"},"byo_seo_providers":{"type":"array","items":{"type":"string"},"description":"SEO providers this organisation has connected its **own** API key for, by name (`majestic`, `ahrefs`, `moz`, `dataforseo_backlinks`). Their checks run against the customer's own subscription and cost nothing here.\n\nAn upsell surface reads this alongside `from_plan`: a customer with a connected key already has the data and must not be offered it. ⛔ An **empty array** means \"none connected\", which is a positive fact you may act on. The field being **absent** means the engine predates it — fall back to inferring from `products` rather than asserting the customer has nothing, because those two look identical and only one of them is a measurement.\n\nMeasured rather than recorded: a provider appears here only when a working client can be built from the stored credential, so a key revoked at the provider stops being listed."},"product_allowance":{"type":"integer","description":"How many products this organisation may price-track. A **separate** allowance from `external_allowance` on purpose: a target is a domain and costs the same whatever it sells, while a product is a billable marketplace shelf. `0` means the product-data add-on is not held."},"mention_phrase_allowance":{"type":"integer","description":"How many phrases this organisation may listen for across the web (brand mentions), across all its domains. `-1` means unlimited; `0` means brand mentions is not held."},"mention_check_allowance":{"type":"integer","description":"How many brand-mention checks a month the plan includes. `-1` means unlimited."},"mention_checks_used":{"type":"integer","description":"Brand-mention checks already used this calendar month (UTC) — the same figure the scheduled checks spend against, so the screen cannot promise room they will not honour."},"keyword_allowance":{"type":"integer","description":"How many search phrases this organisation may track positions for. A **third** separate allowance, distinct from both `external_allowance` and `product_allowance`, because the units are priced differently and are not interchangeable: a phrase costs between $0.0006 and $0.006 a check depending on how deep the results have to be read, a tracked product is a marketplace shelf, and a target is a domain. `0` means the rank-tracking add-on is not held."},"versions_allowance":{"type":"integer","description":"How many Google versions (a location and language a phrase is checked from) each tracked domain may use — V1's rank axis: Rank Tracking Starter 10, Pro 25, Agency 100, plus 10 per \"+10 Google versions\" pack. `-1` means not metered (rank tracking from a hosting plan, a retired add-on, or a staff organisation). Saving phrases that ADD a version past it is refused (`refusal.visibility.planChecksGoogleVersions`); versions a domain already has above a lowered limit are kept."},"rank_check_cadence":{"type":["object","null"],"description":"How often this organisation's rank phrases are checked right now, and why. `null` when rank tracking is not held. Read from the same helper the scheduled sweep asks at the point of spend, so the screen and the sweep cannot disagree. A plan whose month-to-date supplier spend, plus the rest of the month's weekly checks at the worst price, reaches 50% of what the customer pays for it is checked weekly until the month resets (`reason: budget_reached`, with `resumes_at`) — V1's rule since 2026-09-27; rank tracking included by a hosting plan is never budgeted.","required":["days","reason","resumes_at"],"properties":{"days":{"type":"integer","description":"Days between scheduled checks — `1` daily, `7` weekly."},"reason":{"type":"string","enum":["plan_included","tier_daily","tier_weekly","budget_reached"]},"resumes_at":{"type":["string","null"],"format":"date-time","description":"When a budget-driven weekly cadence ends (the start of next month)."}}},"allowances":{"$ref":"#/components/schemas/SeoAllowances"},"credit_balance_micros":{"type":"integer","description":"The organisation's Zinn® credit balance in USD micros."}}},"VisibilityTarget":{"type":"object","description":"A domain this organisation is watching, and how.","required":["id","domain","is_external","kinds","cadence_days"],"properties":{"funding":{"type":"string","enum":["plan","credits"],"description":"Who pays for the products the organisation's plan does NOT hold. `plan` (the default): they are not run. `credits`: they run pay-per-use from Zinn® credits at the per-unit prices in `getSeoAccount` — rank tracking, AI visibility, on-page audit, link watch, keyword research, competitors, domain score and brand page 1. A product the plan holds always runs on the plan and is never charged twice."},"brand_terms":{"type":"array","maxItems":5,"items":{"type":"string","maxLength":120},"description":"Brand page 1's searches as the customer set them (`setVisibilityBrandTerms`). Empty means the brand name (or, failing that, the domain) is the one search."},"credit_holds":{"type":"object","additionalProperties":{"type":"string","format":"date-time"},"description":"Products held for want of Zinn® credit, with the moment each was held. A top-up resumes them on the next sweep, oldest first; nothing is dropped."},"id":{"$ref":"#/components/schemas/Uuid"},"domain":{"type":"string","description":"The hostname","normalised.":null},"label":{"type":"string","description":"The customer's own label for this domain."},"brand":{"type":"string","description":"The trading name to look for in an answer engine's reply. Genuinely separate from the domain — an answer that recommends a business by name without printing its URL has still mentioned them."},"category":{"type":"string","description":"What this business sells, in the customer's own words. The questions asked of the answer engines are built from it, so it is the single field that decides whether an AI-visibility reading is worth anything. Empty means generic questions are asked and the reading is weaker for it."},"market":{"type":"string","description":"Where the business sells. Used with `category` to build the questions."},"is_external":{"type":"boolean","description":"True when this is not one of this organisation's own domains — a competitor or a prospect. Only external targets count against the plan's allowance. A domain is the organisation's own when it is a hosted site's primary domain or alias, a hostname attached to a hosted site, or a domain registered with or connected to us — the same rule `listVisibilityDomainOptions` offers domains by. Decided once, when the domain is added."},"site_id":{"type":"string","format":"uuid","nullable":true,"description":"The site this target corresponds to, when it is one of ours."},"kinds":{"type":"array","items":{"$ref":"#/components/schemas/VisibilityAuditKind"}},"cadence_days":{"type":"integer","description":"Days between scheduled audits. `0` means paused — **not** deleted. History and settings survive and it resumes with no further action."},"next_due_at":{"type":"string","format":"date-time","nullable":true},"last_audit_at":{"type":"string","format":"date-time","nullable":true},"review_profiles":{"type":"array","items":{"$ref":"#/components/schemas/ReviewProfile"}},"profile_candidates":{"type":"array","description":"What the last `lookupVisibilityReviewProfiles` search found. Candidates only — the reputation check reads `review_profiles`, and a candidate becomes one when the customer confirms it.","items":{"$ref":"#/components/schemas/ReviewProfile"}},"profile_lookup":{"type":"object","description":"The last review-profile search's state. Empty when none was ever run.","properties":{"status":{"type":"string","enum":["running","complete","failed"]},"query":{"type":"string"},"location":{"type":"string"},"at":{"type":"string","format":"date-time"},"error":{"type":"string","description":"A sentence for the customer when the search failed."}}},"products":{"type":"array","items":{"$ref":"#/components/schemas/TrackedProduct"},"description":"The products this organisation has asked us to price-track."},"merchant_names":{"type":"array","items":{"type":"string"},"description":"How this business appears as a **seller** on the marketplaces. Confirmed by the customer and never inferred: Google Shopping publishes a seller name and no domain on its listings, so without this we can price the shelf but cannot say which offer on it is theirs. Empty means the product-data audit reports `product_seller_unknown` rather than claiming they are not listed."},"keywords":{"type":"array","items":{"$ref":"#/components/schemas/TrackedKeyword"},"description":"The search phrases this organisation tracks its position for. Customer-supplied and never derived: asking a vendor which phrases a domain already ranks for would return exactly the set a rank-tracking product has nothing to say about, and would cost money to find out."},"prompts":{"type":"array","items":{"type":"string"},"description":"The customer's own questions for the AI answer engines. Empty means the default questions built from `category` and `market`. Bounded by the `prompts` allowance."},"watched_links":{"type":"array","items":{"$ref":"#/components/schemas/WatchedLink"},"description":"The individual links the customer watches pointing at this domain. What each link was found to be is a reading on the latest `link_watch` audit, not here. Bounded by the `links` allowance."},"mention_phrases":{"type":"array","items":{"$ref":"#/components/schemas/MentionPhraseState"},"description":"The phrases this organisation listens for on this domain (brand mentions), each with its own schedule as the checks actually left it."}}},"VisibilityTargetRequest":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string"},"label":{"type":"string"},"brand":{"type":"string"},"category":{"type":"string"},"market":{"type":"string"},"kinds":{"type":"array","items":{"$ref":"#/components/schemas/VisibilityAuditKind"}},"cadence_days":{"type":"integer","minimum":0,"maximum":90},"funding":{"type":"string","enum":["plan","credits"],"description":"`credits` switches the target to pay-per-use for the products the plan does not hold (see `VisibilityTarget.funding`). Only ever set because a caller asked: without it a product off the plan is refused `403` as not on the plan."}}},"VisitUsage":{"type":"object","description":"An organisation's metered visits for one billing period, and the overage they have accrued (#1675). `page_views` is the **billable** number: human page views with bots, assets, redirects and errors excluded on the worker box, which is the only place the user-agent still exists.\n\nThis is deliberately **not** the `visits` field on `SiteMetrics`. That one is distinct client IPs per day, and a month of daily distinct-IP counts double-counts every returning visitor — it is not a count of anything real and an invoice must never be derived from it. Page views are additive across days, which is precisely why they are what is billed.","required":["period_start","period_end","page_views","excluded_page_views","allowance","full_allowance","prorated","unlimited","remaining","over_by","over_limit","overage_blocks","overage_amount_minor","overage_currency"],"properties":{"period_start":{"type":"string","format":"date-time","description":"Start of the subscription's current billing period."},"period_end":{"type":"string","format":"date-time","description":"End of the subscription's current billing period."},"page_views":{"type":"integer","format":"int64","description":"Billable human page views this period, across every site the plan pays for."},"excluded_page_views":{"type":"integer","format":"int64","description":"Page views excluded as automated. Published so the bot rule is auditable — a customer disputing an invoice can see what they were not charged for."},"allowance":{"type":"integer","format":"int64","description":"The ceiling applied to this period, already pro-rated where `prorated` is true. `-1` means unlimited."},"full_allowance":{"type":"integer","format":"int64","description":"The plan's unscaled monthly `monthly_visits` grant, so the UI can quote the pricing-page figure alongside a pro-rated one."},"prorated":{"type":"boolean","description":"Whether `allowance` was scaled down because this period began before metering did. Surfaced so a number that will not match the pricing page can be explained rather than looking like a shrunken plan."},"unlimited":{"type":"boolean","description":"Whether the plan grants unlimited visits."},"remaining":{"type":"integer","format":"int64","description":"Page views left in the allowance. Never negative."},"over_by":{"type":"integer","format":"int64","description":"Page views beyond the allowance. Never negative."},"over_limit":{"type":"boolean","description":"Whether the allowance has been exceeded. The site keeps serving either way."},"overage_blocks":{"type":"integer","format":"int64","description":"Blocks of overage, rounded **up** — one page view over the allowance buys a whole block."},"overage_amount_minor":{"type":"integer","format":"int64","nullable":true,"description":"The overage charge in minor units of `overage_currency` (integer minor units, never a float). `null` when no overage rate is in force, which is not the same as zero."},"overage_currency":{"type":"string","nullable":true,"description":"ISO 4217 code for `overage_amount_minor`. Null exactly when it is."}}},"VitalsBand":{"type":"string","enum":["good","needs_improvement","poor","unknown"],"description":"A Core Web Vitals verdict against Google's published p75 thresholds.\n\nThe overall `band` is the **worst** of the three measured metrics, because that is how Google assesses a page: an origin passes only when all three are good. Unmeasured metrics are skipped rather than counted as failures — INP is routinely absent from a lab run on a page with no interactions, and treating that as `poor` would mark most static sites as failing.\n\n`unknown` means nobody has measured, and must never be rendered as `good`."},"VitalsCheck":{"type":"object","required":["id","url","status","cached","error","error_code","created_at","remaining_today"],"properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","description":"The normalised absolute URL that was (or is being) measured."},"status":{"type":"string","enum":["queued","running","done","failed"],"description":"`failed` is a finished state with a customer-readable `error`, not an infrastructure fault — a page that is down or blocked to crawlers reaches it."},"cached":{"type":"boolean","description":"True when this is a stored measurement of the same URL served from the cache window rather than a run that was just started. Render `measured_at` rather than implying the page was re-measured."},"error":{"type":"string","description":"Empty unless `status` is `failed`. A sentence written for a customer to act on; never a stack trace or an internal hostname. **English, and a FALLBACK** — it is authored server-side and stored, so it cannot be translated afterwards. Render `error_code` where you know it."},"error_code":{"type":"string","description":"A stable machine reason the client turns into a localised sentence: `no_data`, `no_result`, `check_failed`, `timed_out`. Empty unless `status` is `failed`. New members are additive — an unknown code falls back to `error` rather than rendering a raw key at the customer."},"created_at":{"type":"string","format":"date-time"},"finished_at":{"type":"string","format":"date-time","nullable":true},"result":{"allOf":[{"$ref":"#/components/schemas/SiteVitals"}],"nullable":true,"description":"The measurement, present once `status` is `done`. Null while queued or running and on failure — never a zeroed placeholder, which would render as a real measurement of a page that was not measured."},"remaining_today":{"type":["integer","null"],"description":"Checks left in this organisation's rolling daily allowance, so the UI can warn before the button is refused rather than only explaining a `429` afterwards. **`null` means no cap at all**, which is what staff get (`docs/61` §2.3 has always said \"staff: unlimited (audited)\"). Nullable rather than a large number: a countdown beside a button that never stops working is its own kind of wrong."}}},"VitalsCheckRequest":{"type":"object","required":["url"],"properties":{"url":{"type":"string","maxLength":2048,"description":"The page to measure. A path (`/shop/boots`), a bare hostname, or an absolute URL. It must resolve to this site's `primary_domain` or one of its aliases — anything else is a `404`, deliberately, so this cannot be used to discover which hostnames the platform hosts.","example":"/shop/category/boots"}}},"WaapDomain":{"type":"object","required":["id","domain","mode"],"properties":{"id":{"type":"string"},"domain":{"type":"string"},"mode":{"type":"string","enum":["monitor","block","off","locked"],"description":"⛔⛔ `monitor` logs every match and **delivers the traffic anyway**. It produces analytics and blocks nothing, and on a dashboard it is indistinguishable from `block` unless this field is shown. `locked` is assigned by the provider (usually for billing) and cannot be requested or cleared by the customer."},"created_at":{"type":"string","format":"date-time","nullable":true},"total_requests":{"type":"integer","nullable":true,"description":"⛔ `null` when the provider does not report it — never `0`."},"blocked_requests":{"type":"integer","nullable":true,"description":"⛔ `null` when unknown. \"Nothing was blocked\" and \"we cannot see what was blocked\" are opposite answers and must not render alike."}}},"WaapDomainList":{"type":"object","required":["domains"],"properties":{"domains":{"type":"array","items":{"$ref":"#/components/schemas/WaapDomain"}}}},"WaapModeRequest":{"type":"object","required":["mode"],"properties":{"mode":{"type":"string","enum":["monitor","block","off"],"description":"⛔ `locked` is absent on purpose: it is a state the provider assigns, never one that can be requested, and the API answers `422` for it."}}},"WalletPurse":{"type":"object","description":"One named purse's balance.","required":["purpose","balance_minor"],"properties":{"purpose":{"type":"string","enum":["general","ai","trial"],"description":"`general` is hosting, deploys and domains. A restricted purse exists so a discounted bundle for one product cannot be spent at face value on another. `trial` holds the one-time Cloud trial credit, spendable only on the trial products (entry VPS, managed Redis, Kubernetes nodes; docs/1124)."},"balance_minor":{"type":"integer","minimum":0}}},"WalletSettings":{"type":"object","description":"A customer's own low-balance warning and standing top-up instruction.","required":["org_id","currency","low_balance_threshold_minor","auto_topup_enabled"],"properties":{"org_id":{"$ref":"#/components/schemas/Uuid"},"currency":{"type":"string","minLength":3,"maxLength":3},"low_balance_threshold_minor":{"type":"integer","minimum":0,"description":"Warn when spendable credit falls below this. **`0` means off**, not \"warn me at zero\": a customer who never chose one holds `0`, and reading that as a threshold would warn every account with an empty wallet. Edge-triggered — one warning per crossing, re-armed once the balance recovers."},"auto_topup_enabled":{"type":"boolean"},"auto_topup_trigger_minor":{"type":"integer","minimum":0,"description":"Buy more credit when the balance falls below this."},"auto_topup_amount_minor":{"type":"integer","minimum":0,"description":"How much to add when the rule fires."},"auto_topup_payment_method_id":{"oneOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}],"description":"Which saved method to charge. `null` uses the account's default."},"auto_topup_disarmed":{"type":"boolean","description":"⭐ **The state a customer most needs to see and can least infer.** A standing instruction switches itself off after three consecutive failures, and `auto_topup_enabled` stays `true` when it does — so a screen reading only that field shows a working rule that has silently stopped. Saving any settings clears it."},"auto_topup_last_failure":{"type":"string","description":"Why the last attempt failed, in words safe to show the customer."},"auto_topup_last_run_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]}}},"WalletSettingsUpdate":{"type":"object","description":"Changes to the customer's own settings. ⛔ Switching `auto_topup_enabled` on without an `auto_topup_amount_minor` is a 422: an armed rule with no amount would fire on every sweep, charge nothing and never clear its own trigger.","properties":{"low_balance_threshold_minor":{"type":"integer","minimum":0},"auto_topup_enabled":{"type":"boolean"},"auto_topup_trigger_minor":{"type":"integer","minimum":0},"auto_topup_amount_minor":{"type":"integer","minimum":0,"maximum":100000000},"auto_topup_payment_method_id":{"oneOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]}}},"WalletTopUpEstimate":{"type":"object","description":"What a proposed top-up will actually credit — the disclosure shown **before** the customer pays.","required":["currency","gateway","quoted_minor","expected_credit_minor","is_estimate","refundable","expires"],"properties":{"currency":{"type":"string","minLength":3,"maxLength":3},"gateway":{"type":"string","maxLength":32},"quoted_minor":{"type":"integer","minimum":1,"description":"What the customer asked to add."},"expected_credit_minor":{"type":"integer","minimum":0,"description":"What we expect to put in their balance."},"is_estimate":{"type":"boolean","description":"⛔ **Not decoration.** `true` on a rail that settles at a moving rate (crypto), where the amount credited can be less than the amount quoted because we credit what actually settles. A client that renders `expected_credit_minor` without reading this turns a disclosure into a promise we did not make."},"refundable":{"type":"boolean","description":"⚖️ Always `false` for Zinn® credit. *\"credit is not returnable ever, even on account closure etc.\"* — owner, 2026-08-22. Returned at the point of sale because that is where a non-refundable purchase must be disclosed."},"expires":{"type":"boolean","description":"⚖️ Always `false`. Credit never expires — the deliberate other half of never refundable: *\"you cannot have it back\"* is only defensible alongside *\"and you never lose it\"*."}}},"WalletUpcomingCharges":{"type":"object","required":["horizon_days","charges","totals"],"additionalProperties":false,"properties":{"horizon_days":{"type":"integer","minimum":0},"charges":{"type":"array","items":{"type":"object","required":["kind","balance","subject","amount_minor","currency","due_at","estimate","card_fallback"],"additionalProperties":false,"properties":{"kind":{"type":"string","enum":["sms_us_registration","ads_tracking_number","subscription_renewal"]},"balance":{"type":"string","enum":["zinn_credit","wallet"]},"subject":{"type":"string","description":"The plan name or phone number the charge is for."},"amount_minor":{"type":"integer","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3},"due_at":{"type":"string","format":"date-time"},"estimate":{"type":"boolean","description":"List price before tax and coupons, not the exact debit."},"card_fallback":{"type":"boolean","description":"When the balance is short the rest is charged to a saved card."}}}},"totals":{"type":"object","required":["zinn_credit","wallet"],"additionalProperties":false,"properties":{"zinn_credit":{"$ref":"#/components/schemas/WalletUpcomingTotal"},"wallet":{"$ref":"#/components/schemas/WalletUpcomingTotal"}}}}},"WalletUpcomingTotal":{"type":"object","required":["currency","due_minor","balance_minor","shortfall_minor","count"],"additionalProperties":false,"properties":{"currency":{"type":"string","minLength":3,"maxLength":3},"due_minor":{"type":"integer","minimum":0},"balance_minor":{"type":"integer","minimum":0},"shortfall_minor":{"type":"integer","minimum":0},"count":{"type":"integer","minimum":0}}},"WatchedLink":{"type":"object","description":"One link the customer expects to exist: the page `source_url` should link to this domain. `target_url` pins the page it should point at; blank means any page on the domain. `anchor` is the text it should carry; blank means any.","required":["source_url"],"properties":{"source_url":{"type":"string","format":"uri","maxLength":1000},"target_url":{"type":"string","maxLength":1000},"anchor":{"type":"string","maxLength":500}}},"WebhookAck":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["handled","ignored","duplicate"],"description":"`handled` — acted on. `ignored` — a valid event of a type Zinn® does not consume. `duplicate` — already processed; Stripe may stop redelivering.","example":"handled"},"mode":{"type":"string","enum":["test"],"description":"Present only when a payment provider's TEST-mode event reached the live endpoint: it was verified with the test secret and deliberately not acted on (`status` is `ignored`)."}}},"WebmailLink":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"A single-use webmail sign-in URL."}}},"WholesaleStatement":{"type":"object","required":["id","period_start","period_end","currency","status","subtotal_minor","unpriced_lines","line_count","generated_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"period_start":{"type":"string","format":"date"},"period_end":{"type":"string","format":"date"},"currency":{"type":"string"},"status":{"type":"string","enum":["open","needs_review","issued","paid"],"description":"`needs_review` means at least one line could not be priced. It is the one state that must not become an invoice — an under-priced bill looks exactly like a correct one and nobody disputes being charged too little."},"subtotal_minor":{"type":"integer"},"unpriced_lines":{"type":"integer"},"line_count":{"type":"integer"},"invoice_id":{"oneOf":[{"$ref":"#/components/schemas/Uuid"},{"type":"null"}]},"generated_at":{"type":"string","format":"date-time"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/WholesaleStatementLine"}}}},"WholesaleStatementLine":{"type":"object","required":["id","client_org_id","client_name","plan_code","description","interval","currency","list_amount_minor","discount_bps","amount_minor","basis_missing"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"client_org_id":{"$ref":"#/components/schemas/Uuid"},"client_name":{"type":"string"},"plan_code":{"type":"string"},"description":{"type":"string"},"interval":{"type":"string"},"currency":{"type":"string"},"list_amount_minor":{"type":"integer"},"discount_bps":{"type":"integer"},"amount_minor":{"type":"integer"},"basis_missing":{"type":"boolean","description":"The catalogue held no list price for this plan in this currency, so the line is carried at zero **and flagged** rather than dropped. A silently omitted line is money nobody ever bills and nobody ever notices."}}},"WholesaleStatementList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WholesaleStatement"}}}},"WordPressAdmin":{"type":"object","description":"One WordPress administrator. ⛔ **No password field, in either direction.** WordPress stores a hash; there is nothing to reveal.","required":["id","login","display_name","email"],"additionalProperties":false,"properties":{"id":{"type":"string"},"login":{"type":"string"},"display_name":{"type":"string"},"email":{"type":"string"}}},"WordPressAdvisory":{"type":"object","description":"One published vulnerability affecting the installed version.","required":["uuid","title","severity","link","fixed_in","source","attribution"],"additionalProperties":false,"properties":{"uuid":{"type":"string","description":"The feed's stable identifier for this advisory."},"source":{"type":"string","description":"Which feed made this claim — `wpvulnerability` (wpvulnerability.net, public) or `wordfence` (Wordfence Intelligence, used when the platform holds a key).","example":"wordfence"},"attribution":{"type":"array","description":"⛔ The copyright notices the record's licence requires to be shown with it. Wordfence Intelligence licenses its data on condition that a copy shows a link to the record (`link`), Defiant's copyright designation and the licence; MITRE requires the same of its CVE notice. A client showing the advisory MUST show these. Empty for feeds that ask for none.","items":{"type":"object","required":["notice","license_url","license"],"additionalProperties":false,"properties":{"license":{"type":"string","description":"The licence text itself, verbatim from the feed. Its grant reads \"reproduce … this license in any such copy\", so it is shown, not only linked. May be blank."},"notice":{"type":"string","example":"Copyright 2012-2026 Defiant Inc."},"license_url":{"type":"string","description":"Where the licence text is published. May be blank."}}}},"title":{"type":"string","description":"The advisory's title, or its best public reference's."},"severity":{"type":"string","description":"CVSS severity — `none`, `low`, `medium`, `high`, `critical`, or `\"\"`.","example":"critical"},"link":{"type":"string","description":"The best public reference — the Wordfence record for a `wordfence` advisory (its licence requires the link), usually a CVE record otherwise. May be blank."},"fixed_in":{"type":"string","description":"The lowest version known to carry the fix, or `\"\"`. ⛔ Blank is **not** \"no fix exists\": an advisory reading \"affected at or below X\" does not name a fixed version, and reporting X would send a customer to a version still vulnerable."}}},"WordPressAllowance":{"type":"object","description":"One countable resource. ⛔ **Three states, not two.** `limit: null, unlimited: false` is *no ceiling is stated*; `unlimited: true` is *the plan sells this as unlimited*, which is what the platform's `INF` and the catalogue's `-1` both mean; a number is a number. `used: null` is *nobody has measured*, which is not zero.\n\n⛔ A client must draw a meter **only** when `limit` is a number. A bar with no ceiling is either always empty or always full, and both are lies.","required":["used","limit","unlimited"],"additionalProperties":false,"properties":{"used":{"type":"integer","nullable":true,"description":"MB for disk and bandwidth. Null when nothing has measured it."},"limit":{"type":"integer","nullable":true,"description":"The **enforced** ceiling where the platform states one, otherwise the plan's grant — the enforced number is the one that will actually refuse a write."},"unlimited":{"type":"boolean","description":"The plan sells this as unlimited. ⛔ Always `false` when an enforced ceiling exists: a kernel quota is a number, not a selling point."}}},"WordPressCliCommandList":{"type":"object","description":"Every WP-CLI command the console will run.","required":["data"],"additionalProperties":false,"properties":{"data":{"type":"array","description":"Permitted commands, space-joined, sorted.","items":{"type":"string"},"example":["cache flush","plugin list","theme list"]}}},"WordPressComponent":{"type":"object","required":["name","status","version","update_version"],"additionalProperties":false,"properties":{"name":{"type":"string"},"status":{"type":"string","description":"`active` / `inactive`, as the platform reports it."},"version":{"type":"string"},"update_version":{"type":"string","description":"The version waiting, or `\"\"` when current. Not a boolean: a screen that can name the waiting version is more useful than one that can only say \"update\"."}}},"WordPressComponentRisk":{"type":"object","description":"One installed plugin or theme, and what is known about its version.","required":["kind","name","version","checked","severity","advisories"],"additionalProperties":false,"properties":{"kind":{"type":"string","enum":["plugin","theme"]},"name":{"type":"string","description":"The component's slug, as WordPress knows it."},"version":{"type":"string","description":"The version installed here."},"checked":{"type":"boolean","description":"⛔⛔ `false` means **we could not assess this**, not \"nothing found\". A client MUST NOT render an unchecked row as clean."},"severity":{"type":"string","description":"The worst severity among `advisories`, or `\"\"`."},"advisories":{"type":"array","items":{"$ref":"#/components/schemas/WordPressAdvisory"}}}},"WordPressDirectoryPlugin":{"type":"object","description":"One plugin as the wordpress.org directory describes it — a thing a customer could install, not a thing installed. Every field is already flattened and safe to print: the upstream sends `author` as an HTML anchor and `icons` as a size→URL map, neither of which a screen should receive raw.","required":["slug","name","version","author","short_description","rating","num_ratings","active_installs","last_updated","requires_wp","requires_php","tested_up_to","homepage","icon_url"],"additionalProperties":false,"properties":{"slug":{"type":"string","description":"The directory slug — what `installSiteWordPressPlugin` takes. ⛔ The **only** field from this resource that is ever sent to a box; the download URL is resolved by the site itself, so a catalogue result can never redirect an install.","example":"wordfence"},"name":{"type":"string","example":"Wordfence Security"},"version":{"type":"string","example":"8.1.0"},"author":{"type":"string","description":"Plain text. The upstream's surrounding anchor markup is stripped.","example":"Defiant"},"short_description":{"type":"string"},"rating":{"type":"number","format":"float","minimum":0,"maximum":5,"description":"⛔ **0–5, normalised here.** The upstream reports 0–100; a client rendering that as stars without dividing shows every plugin as full marks.","example":4.6},"num_ratings":{"type":"integer","minimum":0},"active_installs":{"type":"integer","minimum":0,"description":"The directory's own estimate, and it means \"at least this many\" — it is bucketed upstream, so 4,000,000 and 4,900,000 both arrive as 4000000."},"last_updated":{"type":"string","example":"2026-07-30 4:12pm GMT"},"requires_wp":{"type":"string","description":"Minimum WordPress version. `\"\"` when the plugin does not say."},"requires_php":{"type":"string","description":"Minimum PHP version. `\"\"` when the plugin does not say."},"tested_up_to":{"type":"string","description":"The newest WordPress the author has tested against."},"homepage":{"type":"string"},"icon_url":{"type":"string","description":"The plugin's icon, best available size. `\"\"` when it has none — ⛔ NOT the directory's grey placeholder, which would give every icon-less plugin the same picture: present, wrong, and hard to notice."},"sections":{"type":"object","additionalProperties":{"type":"string"},"description":"Long-form copy (description, installation, changelog, FAQ), plain text. Present only on `getWordPressDirectoryPlugin`; the search omits it because it is tens of kilobytes per plugin and no list view renders it."}}},"WordPressDirectoryTheme":{"type":"object","description":"One theme as the wordpress.org directory describes it — a thing a customer could install, not a thing installed. Every field is flattened and safe to print: the upstream sends `author` as an **object** on this API (and as an HTML anchor on the plugin one) and `description` with markup in it, neither of which a screen should receive raw.","required":["slug","name","version","author","description","rating","num_ratings","downloaded","last_updated","requires_wp","requires_php","homepage","screenshot_url","preview_url"],"additionalProperties":false,"properties":{"slug":{"type":"string","description":"The directory slug — what `installSiteWordPressTheme` takes. ⛔ The **only** field from this resource ever sent to a box; the download URL is resolved by the site itself, so a catalogue result can never redirect an install.","example":"astra"},"name":{"type":"string","example":"Astra"},"version":{"type":"string","example":"4.11.13"},"author":{"type":"string","description":"Plain text. ⛔ The upstream returns this as an object here and as an HTML anchor on the plugin API — both shapes are real and both are flattened.","example":"Brainstorm Force"},"description":{"type":"string","description":"Plain text; the upstream's markup is stripped."},"rating":{"type":"number","format":"float","minimum":0,"maximum":5,"description":"⛔ **0–5, normalised here.** The upstream reports 0–100.","example":4.9},"num_ratings":{"type":"integer","minimum":0},"downloaded":{"type":"integer","minimum":0,"description":"Lifetime downloads. ⛔ The theme API has **no `active_installs`** — the plugin field with the closest name means something different, so a client reusing a plugin card here would label this \"active installs\" and be wrong by orders of magnitude."},"last_updated":{"type":"string","example":"2026-08-04"},"requires_wp":{"type":"string","description":"Minimum WordPress version. `\"\"` when the theme does not say."},"requires_php":{"type":"string","description":"Minimum PHP version. `\"\"` when the theme does not say."},"homepage":{"type":"string"},"screenshot_url":{"type":"string","description":"The theme's own screenshot, normalised to `https` (upstream emits it protocol-relative). ⚠️ A third-party URL a client renders in an `<img>`; see the operation description."},"preview_url":{"type":"string","description":"A live preview on wordpress.org, normalised to `https`. ⚠️ Third-party; see the operation description."}}},"WordPressFleetOverview":{"type":"object","description":"The estate's posture, counted over every site in scope.","required":["total","installed","core_updates","component_updates","current","unknown","not_installed","unreachable","never_collected","healthy","unhealthy","health_unknown","by_deploy_target","by_product_line"],"additionalProperties":false,"properties":{"total":{"type":"integer"},"installed":{"type":"integer"},"core_updates":{"type":"integer"},"component_updates":{"type":"integer"},"current":{"type":"integer"},"unknown":{"type":"integer"},"not_installed":{"type":"integer"},"unreachable":{"type":"integer","description":"Sites whose homepage answered 4xx/5xx, or did not answer at all."},"never_collected":{"type":"integer","description":"Sites nobody has ever asked. Reported separately from `unknown`, which also covers *\"we asked and the platform declined to say\"*."},"healthy":{"type":"integer","description":"Sites assessed, with no critical finding."},"unhealthy":{"type":"integer","description":"Sites assessed, with at least one critical finding."},"health_unknown":{"type":"integer","description":"⛔⛔ **Sites we have not assessed, and the counter that makes the other two honest.** `healthy + unhealthy + health_unknown == total`, always. Without it an estate nobody had ever looked at would render as *\"0 unhealthy\"*, which is precisely the screen this feature was built to stop showing."},"by_deploy_target":{"type":"object","additionalProperties":{"type":"integer"}},"by_product_line":{"type":"object","additionalProperties":{"type":"integer"}}}},"WordPressFleetSite":{"type":"object","description":"One WordPress site as the fleet manager lists it. Assembled from stored rows.","required":["site_id","name","primary_domain","stack_type","product_line","deploy_target","status","php_version","plan_name","site_url","admin_url","update_state","reachability","http_status","http_error_code","http_checked_at","can_install","capabilities","disk","bandwidth","snapshot","thumbnail_url"],"additionalProperties":false,"properties":{"site_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"primary_domain":{"type":"string"},"stack_type":{"type":"string","description":"`wordpress` or `woocommerce` — a shop IS a WordPress site."},"product_line":{"type":"string"},"deploy_target":{"type":"string"},"status":{"type":"string"},"php_version":{"type":"string"},"plan_name":{"type":"string","description":"The plan a customer would recognise, or `\"\"`. Never an id."},"site_url":{"type":"string"},"admin_url":{"type":"string"},"update_state":{"$ref":"#/components/schemas/WordPressUpdateState"},"reachability":{"$ref":"#/components/schemas/WordPressReachability"},"http_status":{"type":"integer","nullable":true},"http_error_code":{"$ref":"#/components/schemas/WordPressProbeErrorCode"},"http_checked_at":{"type":"string","format":"date-time","nullable":true},"can_install":{"type":"boolean","description":"Whether software can be installed on this site's platform at all. ⛔ `false` for every managed hosting site — this platform exposes no shell and no install endpoint across its API — so a client greys install actions on those rows rather than letting a customer select twelve sites and read six refusals afterwards."},"capabilities":{"type":"object","additionalProperties":{"type":"boolean"},"description":"What this site's platform permits, as of the last collection."},"disk":{"$ref":"#/components/schemas/WordPressAllowance"},"bandwidth":{"$ref":"#/components/schemas/WordPressAllowance"},"snapshot":{"allOf":[{"$ref":"#/components/schemas/WordPressSnapshot"}],"nullable":true,"description":"⛔ **Null means nobody has ever collected this site.** A client renders that as *\"not checked yet\"* with a refresh action — never as zeroes, which read as \"you are up to date\"."},"thumbnail_url":{"type":"string","description":"A presigned, short-lived (minutes) URL of the site's newest real-browser picture of its home page, or `\"\"` when none is held — a site the public cannot reach has no picture. Minted per read; never store it."}}},"WordPressFleetSiteDetail":{"allOf":[{"$ref":"#/components/schemas/WordPressFleetSite"},{"type":"object","required":["plugins","themes","admins"],"properties":{"plugins":{"type":"array","items":{"$ref":"#/components/schemas/WordPressComponent"}},"themes":{"type":"array","items":{"$ref":"#/components/schemas/WordPressComponent"}},"admins":{"type":"array","items":{"$ref":"#/components/schemas/WordPressAdmin"}}}}]},"WordPressHealthFinding":{"type":"object","description":"One thing the health assessment found. ⛔ A `code` and its parameters, never a sentence: this is rendered on customer screens in 58 languages, and a sentence composed in the engine is English in all of them for ever (§2.19).","required":["code","severity","params"],"additionalProperties":false,"properties":{"code":{"type":"string","description":"`unreachable` · `server_error` · `client_error` · `tls_invalid` · `wordpress_not_installed` · `core_update_pending` · `component_updates_pending` · `vulnerable_components` · `database_unreachable` · `core_files_modified` · `php_unsupported` · `platform_plugin_missing` · `platform_plugin_outdated` · `disk_near_limit` · `collection_failed` · `partial_assessment`."},"severity":{"type":"string","enum":["warning","critical"],"description":"⛔ Only `critical` findings make a site `unhealthy`. The severity is looked up from one table in the engine and is never chosen at the call site, so a new finding cannot ship at the wrong severity through a typo."},"params":{"type":"object","additionalProperties":{"type":"string"},"description":"Interpolation values for the client's catalogue entry — e.g. `{\"count\": \"3\"}`. ⛔ Strings, because a value that round-trips as `int` in Python and `number` in TypeScript is one more thing for the generated client to disagree about."}}},"WordPressPluginDirectoryPage":{"type":"object","description":"One page of directory results, with enough to render a pager.","required":["data","page","pages","total"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WordPressDirectoryPlugin"}},"page":{"type":"integer","minimum":1},"pages":{"type":"integer","minimum":0,"description":"Total pages available. `0` when nothing matched."},"total":{"type":"integer","minimum":0,"description":"Total matching plugins across all pages."}}},"WordPressProbeErrorCode":{"type":"string","enum":["","dns","tls","timeout","refused","transport"],"description":"Why the homepage request did not complete, blank when it did (whatever the status). A code rather than a sentence, because a sentence composed in the engine is English for ever (§2.19) and this one is rendered on a customer's screen — and because these are four different fixes on four different days: an expired certificate, a domain that does not resolve, nothing listening, and a server that never answered."},"WordPressReachability":{"type":"string","enum":["ok","server_error","client_error","unreachable","unknown"],"description":"What a **visitor** gets from the site's own homepage, from a cache-busted request.\n\n⛔⛔ This is the only field on this surface measured over the path a human actually uses. Every other figure comes from wp-cli (our own boxes, over SSH) or the vendor API, and on 2026-08-15 a production site answered every one of those with real plugins, real users and a clean checksum while its homepage returned **500 with an empty body** — the stale CDN copy being the only thing keeping it up. `unknown` means nobody has probed it, which is not `ok`."},"WordPressRefreshResult":{"type":"object","required":["site_id","status","error_code"],"additionalProperties":false,"properties":{"site_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["collected","failed","skipped"],"description":"⛔ A site outside the caller's scope is `skipped`, never a 404 for the whole batch — which would both fail eleven good collections and confirm that a foreign site id exists."},"error_code":{"type":"string"}}},"WordPressRotatedPassword":{"type":"object","description":"⛔⛔ **Shown once, stored nowhere** — not in the snapshot, not in the audit record's metadata, not in a log line. The audit record says a rotation happened and never what to.","required":["user_id","login","password"],"additionalProperties":false,"properties":{"user_id":{"type":"string"},"login":{"type":"string"},"password":{"type":"string"}}},"WordPressSet":{"type":"object","description":"A customer-owned, named list of plugin slugs plus an optional theme.","required":["id","org_id","name","plugins","theme","created_at","updated_at"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"name":{"type":"string","maxLength":80},"plugins":{"type":"array","maxItems":50,"items":{"type":"string"},"description":"WordPress.org plugin directory names, in the order saved."},"theme":{"type":"string","description":"A WordPress.org theme directory name, or empty for a plugins-only set."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"WordPressSetWrite":{"type":"object","additionalProperties":false,"properties":{"org_id":{"type":"string","format":"uuid"},"name":{"type":"string","maxLength":80},"plugins":{"type":"array","maxItems":50,"items":{"type":"string"}},"theme":{"type":"string"}}},"WordPressSiteCredentials":{"type":"object","description":"⛔⛔ **There is no `password` property and there cannot be one.** WordPress stores a hash, so no plaintext exists on our side or theirs. A customer copies the username from here; a password is *minted* by `rotateWordPressAdminPassword`.","required":["admin_url","sso_available","admins"],"additionalProperties":false,"properties":{"admin_url":{"type":"string"},"sso_available":{"type":"boolean","description":"Whether this platform can mint a one-click login. Our own fleet writes the SSO signing key into `wp-config.php`; this platform has no shell, so it cannot — and a button offered there would mint a grant the site cannot honour."},"admins":{"type":"array","items":{"$ref":"#/components/schemas/WordPressAdmin"}}}},"WordPressSnapshot":{"type":"object","description":"What the last collection found, and when. `collected_at` is not decoration: the manager renders the age beside every figure, so a stale answer is visibly stale rather than quietly wrong.","required":["collected_at","installed","core_version","core_update_version","core_is_latest","is_multisite","plugin_count","plugin_active_count","plugin_update_count","theme_count","theme_update_count","active_theme","admin_count","inodes_used","inodes_limit","collect_error_code","health_status","health_checked_at","health_findings","database_ok","core_files_modified","vulnerable_component_count","vulnerability_worst_severity","vulnerability_unchecked_count","platform_plugin_version","platform_plugin_expected"],"additionalProperties":false,"properties":{"collected_at":{"type":"string","format":"date-time"},"installed":{"type":"boolean","nullable":true,"description":"⛔⛔ **Tri-state.** Null is *\"no collection has ever succeeded for this site\"*; `false` is the affirmative, actionable claim *\"we looked and there is no WordPress here\"*. Collapsing them is a defect that was measured on a real run: five of five sites reported *not installed* with `collect_error_code` sitting beside them saying the read had failed."},"core_version":{"type":"string"},"core_update_version":{"type":"string"},"core_is_latest":{"type":"boolean","nullable":true,"description":"⛔ **Tri-state.** Null means the platform did not say, which is not \"out of date\"."},"is_multisite":{"type":"boolean"},"plugin_count":{"type":"integer"},"plugin_active_count":{"type":"integer"},"plugin_update_count":{"type":"integer"},"theme_count":{"type":"integer"},"theme_update_count":{"type":"integer"},"active_theme":{"type":"string"},"admin_count":{"type":"integer"},"inodes_used":{"type":"integer","nullable":true},"inodes_limit":{"type":"integer","nullable":true},"collect_error_code":{"type":"string","description":"Blank on a clean collection. `no_surface` / `unsupported` / `vendor`. ⛔ A failed collection keeps the previous figures and records this beside them — the row is what we last knew, not a blank."},"health_status":{"type":"string","enum":["","healthy","unhealthy"],"description":"⛔⛔ **Three states, and the empty string is *not yet checked*.** A client MUST render it as such and never as a pass: until 2026-09-03 nothing on this platform ever collected a site on a schedule, so 56 of 59 production sites sat at this value permanently — which is the defect the daily `zinn-wordpress-health` sweep exists to end.\n\n⛔ A pending core or component update does **not** make a site `unhealthy`. Those are counted in their own fields and filtered on separately; a verdict that went red every time a plugin shipped a release would be red always and read by nobody. `unhealthy` means at least one CRITICAL finding: the site does not answer, its certificate does not work, its database is unreachable, or a component has a published advisory against the exact version installed."},"health_checked_at":{"type":"string","format":"date-time","nullable":true,"description":"When the verdict was computed. ⛔ **Distinct from `collected_at`**, and null even on rows that have figures: a snapshot written before health assessment shipped has a collection date and no verdict, and rendering the first as the age of the second dates an assessment that was never made."},"health_findings":{"type":"array","description":"Every finding, both severities, in the order they were produced. ⛔ `code` is a machine code and never a sentence — the client renders it through its own catalogue in the reader's language (§2.19). ⭐ Warnings appear here on a site whose `health_status` is `healthy`; that is not a contradiction, it is the point.","items":{"$ref":"#/components/schemas/WordPressHealthFinding"}},"database_ok":{"type":"boolean","nullable":true,"description":"WordPress's own database integrity check. ⛔⛔ **Tri-state, and null is the common case.** Null is *\"this site's platform does not permit the check\"* — most vendor packages do not sell `manageWpDatabase` — which is a different sentence from `false` (*\"the database is unreachable\"*). Rendering the first as the second puts a critical badge on thousands of healthy sites."},"core_files_modified":{"type":"integer","nullable":true,"description":"How many WordPress core files differ from the official checksums. ⛔ Null is *not assessed*; `0` is an affirmative clean answer, and they are not the same thing."},"vulnerable_component_count":{"type":"integer","nullable":true,"description":"Installed plugins and themes with a published advisory against **the version installed here**. Null when the feed was not consulted."},"vulnerability_worst_severity":{"type":"string","description":"The worst severity among those advisories, or `\"\"`."},"vulnerability_unchecked_count":{"type":"integer","nullable":true,"description":"Components the advisory feed could not speak for — every bespoke plugin, every premium plugin with no public listing. ⛔ Surfaced rather than hidden: **unknown is not clean**, and a vulnerable count that omits the unknowns reads as a complete answer."},"platform_plugin_version":{"type":"string","description":"The version of the Zinn® platform plugin installed on the site, or `\"\"` when it is not present."},"platform_plugin_expected":{"type":"string","description":"The version this build of the platform ships. ⛔ Blank when the running image did not ship the plugin at all, in which case **no comparison is made** — otherwise every site in the estate would report the plugin as outdated because of how the image was built."}}},"WordPressTemplate":{"type":"object","description":"A published blueprint version a customer may apply to a WordPress site.","required":["id","key","version","name","product_line","stack_type","plugins","theme"],"additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"version":{"type":"integer"},"name":{"type":"string"},"product_line":{"type":"string"},"stack_type":{"type":"string"},"plugins":{"type":"array","items":{"type":"string"},"description":"The plugin slugs this template declares, so a customer sees what applying it will install **before** they apply it."},"theme":{"type":"string"}}},"WordPressThemeDirectoryPage":{"type":"object","description":"One page of directory results, with enough to render a pager.","required":["data","page","pages","total"],"additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WordPressDirectoryTheme"}},"page":{"type":"integer","minimum":1},"pages":{"type":"integer","minimum":0,"description":"Total pages available. `0` when nothing matched."},"total":{"type":"integer","minimum":0,"description":"Total matching themes across all pages."}}},"WordPressUpdateState":{"type":"string","enum":["unknown","core","components","current","not_installed"],"description":"⛔⛔ **`unknown` is a real member and must never be rendered as `current`.** *\"We have not looked\"* and *\"you are up to date\"* are different statements, and a manager that collapses them tells somebody their unpatched estate is fine. It covers two cases: nothing has ever been collected for the site, and the platform declined to say whether core is latest.\n\n`core` outranks `components` when both are waiting — core carries the security fixes. `not_installed` is a WordPress site with no WordPress on it: a half-finished provision or a wiped document root, which is actionable and is not \"no updates\"."},"WorkerClaimedCommand":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"action":{"type":"string"},"payload":{"type":"object","additionalProperties":true}}},"WorkerCommandResult":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"}}},"WorkerCommandResultRequest":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean"},"result":{"type":"string","maxLength":255,"description":"One redacted line, never raw command output. Truncated keeping BOTH ENDS: a traceback puts its exception on the last line, so a head-only cut discards exactly the words that say what went wrong (docs/72 D13255)."},"exit_code":{"type":"integer","nullable":true,"description":"The process exit status, when a process ran, and the field that separates a VERDICT from a CRASH. `lsws_suexec.py check` exits 3 when it has looked and found a broken per-site isolation boundary, and something else when it could not look at all; collapsing both into `ok: false` made a Python traceback indistinguishable from a cross-tenant exposure and fired a CRITICAL for 27 hours on a box with no tenants (docs/72 D13252). Omit it when no process ran (an unknown action, a file the agent could not write) — an absent value is recorded as UNKNOWN, a third state, and is never backfilled with 0."},"inventory":{"type":"object","nullable":true,"description":"The document a read-only command produced: the software inventory for `software_inventory`, the pending updates for `update_check`, and the local site liveness results for `site_liveness`. A DOCUMENT rather than a result line, because `result` is capped at 255 characters on purpose — routing forty components through it would either truncate the estate's only version record or repeal that cap for every action. Ignored for any other action: a document attached to a restart is a box volunteering something nobody asked for.","properties":{"available_known":{"type":"boolean","description":"Whether the box's repositories could be READ this run — a fact about the run, not about any component. `false` does NOT mean everything is current: a fully up-to-date box and a box whose repos were unreachable both report no available versions, so the ingest leaves previously-known offers alone rather than blanking them (docs/266, CLAUDE.md 2.44)."},"components":{"type":"array","maxItems":500,"description":"One entry per component READ. A component the box could not read is OMITTED, never sent with an empty version — so an absent entry is ambiguous (uninstalled, or unreadable) and the ingest never deletes on absence; the row visibly goes stale instead.","items":{"type":"object","required":["component","name"],"properties":{"component":{"type":"string","maxLength":32,"description":"The family — os, kernel, k3s, litespeed, alt_php, imunify, kernelcare, image, mariadb."},"name":{"type":"string","maxLength":128},"installed_version":{"type":"string","maxLength":64,"description":"Dotted and exact, read from the package manager — never derived from a directory name, where `php810` is both 8.10 and 81.0 (docs/72 D15333)."},"available_version":{"type":"string","maxLength":64}}}},"hosts_total":{"type":"integer","description":"`site_liveness` only (D40439): how many host names the box serves in all. With the length of `results` it says how much of the box one run reached."},"results":{"type":"array","maxItems":2000,"description":"`site_liveness` only: one row per host the box asked on 127.0.0.1 this run, as `[host, status, reason]`. `status` is the HTTP status, or `null` when there was no answer (then `reason` says why: `timeout`, `refused`, `tls`). Below 500 counts as answering. The engine keeps only this worker's own ACTIVE sites on a line that is not probed from outside; any other host in the list changes nothing.","items":{"type":"array","minItems":2,"maxItems":3,"items":{}}}}}}},"WorkerDrainAgentRequest":{"type":"object","required":["instance_id"],"properties":{"instance_id":{"type":"string","maxLength":64}}},"WorkerHeartbeatRequest":{"type":"object","required":["instance_id"],"properties":{"instance_id":{"type":"string","maxLength":64},"agent_version":{"type":"string","maxLength":64},"report":{"$ref":"#/components/schemas/WorkerHostReport"},"claim_commands":{"type":"boolean","default":true,"description":"False for a probe that reads the host's identity and discards the response (the converge's verify step). It claims no commands, so none is lost to a caller that will never run it."}}},"WorkerHeartbeatResponse":{"allOf":[{"$ref":"#/components/schemas/WorkerIdentity"},{"type":"object","properties":{"continue_running":{"type":"boolean","description":"False only for an **answered** \"this host is gone\" (decommissioned or removed). An error is never reported as one — that distinction is what stops a transient failure retiring a live box."},"commands":{"type":"array","items":{"$ref":"#/components/schemas/WorkerClaimedCommand"}}}}]},"WorkerHostComponent":{"type":"object","required":["kind","status"],"properties":{"kind":{"type":"string"},"status":{"type":"string","enum":["ok","warn","crit","unknown"]},"detail":{"type":"string","maxLength":120},"license_expires_at":{"type":"string","maxLength":32,"nullable":true},"licence_probe":{"type":"string","maxLength":16},"licence_detail":{"type":"string","maxLength":120},"licence_grace_note":{"type":"string","maxLength":200},"product":{"type":"string","maxLength":32,"description":"Which build of the component this is, when the kind alone does not say. Today only `imunifyav` on an `imunify` row (the free scan-only ImunifyAV on a standard-stack own server): it carries no licence, so its licence state is `none`, and the box gets the ImunifyAV scanner rather than Imunify360. Absent on every other row."}}},"WorkerHostPanel":{"type":"object","required":["kind","status"],"properties":{"kind":{"type":"string"},"status":{"type":"string","enum":["ok","warn","crit","unknown"]},"vault_pointer":{"type":"string","maxLength":255,"description":"A Vault **path**, never a credential (§2.4)."},"url":{"type":"string","maxLength":255}}},"WorkerHostReport":{"type":"object","description":"One heartbeat's observed host state.","properties":{"cpu_pct":{"type":"integer","minimum":0,"maximum":100,"nullable":true,"description":"Null means \"could not measure\", which is a real answer and deliberately not reported as zero — a box whose /proc read failed is not a box with no load."},"mem_pct":{"type":"integer","minimum":0,"maximum":100,"nullable":true},"disk_pct":{"type":"integer","minimum":0,"maximum":100,"nullable":true},"components":{"type":"array","maxItems":32,"items":{"$ref":"#/components/schemas/WorkerHostComponent"}},"panels":{"type":"array","maxItems":32,"items":{"$ref":"#/components/schemas/WorkerHostPanel"}}}},"WorkerIdentity":{"type":"object","description":"The host's placement identity as the **engine** knows it. The engine tells the box what it is placed as, not the other way round, so a box's journal shows the pool and capacity it is really serving under rather than what its local env file claims.","properties":{"worker_id":{"type":"string","format":"uuid"},"hostname":{"type":"string"},"status":{"type":"string","enum":["provisioning","active","draining","down","decommissioned"]},"accepts_deploys":{"type":"boolean"},"region":{"type":"string"},"pool":{"type":"string"},"driver":{"type":"string"},"capacity":{"type":"integer","minimum":0},"product_lines":{"type":"array","items":{"type":"string"}},"heartbeat_interval_seconds":{"type":"integer","minimum":1,"description":"How often to heartbeat, decided engine-side. The box no longer reads its own interval from an env file, so \"the host-down window is ten missed beats\" stays a fact about the deployment rather than something one machine's config could quietly break."}}},"WorkerPhishWatchFinding":{"type":"object","description":"One document root graded MEDIUM/HIGH by the box's upload watch. Names only, never file content.","required":["docroot","confidence"],"properties":{"docroot":{"type":"string","maxLength":500},"confidence":{"type":"string","enum":["medium","high"]},"reasons":{"type":"array","maxItems":5,"items":{"type":"string","maxLength":200}},"markers":{"type":"array","maxItems":12,"items":{"type":"string","maxLength":64}},"changed":{"type":"array","maxItems":10,"items":{"type":"string","maxLength":200}}}},"WorkerPhishWatchRequest":{"type":"object","required":["findings"],"properties":{"findings":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/WorkerPhishWatchFinding"}}}},"WorkerPhishWatchResult":{"type":"object","required":["accepted","workflow_id"],"properties":{"accepted":{"type":"integer"},"workflow_id":{"type":"string","nullable":true}}},"WorkerRegisterRequest":{"type":"object","required":["instance_id"],"properties":{"instance_id":{"type":"string","maxLength":64,"description":"This **process's** identity (machine/container name) — not the host's. The host's name is read off the credential and is not accepted from the caller."},"agent_version":{"type":"string","maxLength":64},"python_version":{"type":"string","maxLength":32},"platform":{"type":"string","maxLength":200},"boot_id":{"type":"string","maxLength":64,"description":"`/proc/sys/kernel/random/boot_id`. Distinguishes \"the agent restarted\" from \"the box rebooted\" — a crash loop from a kernel panic."},"observed_address":{"type":"string","maxLength":253,"description":"The address this box believes it answers on. **Advisory only**: recorded on the registration audit row so an operator can compare it with the operator-set origin address, and never written to it. That column decides what a customer's DNS publishes, so a box must not be able to redirect its own traffic."}}},"WpCredentials":{"type":"object","description":"The WordPress administrator login for a site. Every site used to share the username `zinn_admin` and the password was shown nowhere at all, so a customer could not sign in to the WordPress they had just bought.\n\nThe username, e-mail and the password's validity are re-read from the site itself on every request, because `wp_users` is a row the customer can edit directly and used to move underneath us silently — the platform went on displaying the credentials it *used to* be, with `can_reveal: true`, and the customer copied a password that could not open their site.","required":["site_id","username","email","password","can_reveal","is_custom","changed_outside_app","checked_at","verified_at","login_url"],"properties":{"site_id":{"$ref":"#/components/schemas/Uuid"},"username":{"type":"string","description":"This site's own admin username, re-read from the site's `wp_users` row on every request. A customer who renames the account in phpMyAdmin, wp-admin or wp-cli sees the new name here. Sites created before per-site usernames existed still report the shared legacy name, because that is what is on their server."},"email":{"type":"string","description":"`wp_users.user_email` on the site itself — where a WordPress password reset would actually go. Empty until the platform has managed to read one."},"password":{"type":"string","description":"The current password, or empty when it cannot be shown — see `can_reveal`. It is derived from a platform key and the site's rotation epoch, never stored, so there is no per-site secret at rest."},"can_reveal":{"type":"boolean","description":"False when the customer set their own password (nothing of ours to show) or the environment has no signing key. Rotating makes it true again."},"is_custom":{"type":"boolean","description":"The password in use was set by the customer through this app, so there is nothing of ours to show. Distinct from `changed_outside_app`."},"changed_outside_app":{"type":"boolean","description":"Proven: the password the platform holds no longer opens the site, so it was changed outside of the Zinn Digital® Hosting App — phpMyAdmin, wp-admin or wp-cli. WordPress stores `user_pass` as a one-way hash, so the new password cannot be read back by anyone; what is decidable is whether ours still works, and this says it does not. Rotating sets a fresh one and clears this.\nNever inferred from `can_reveal: false`, which is also false when the environment has no signing key — that is the platform's problem, not the customer's, and the two need different sentences on screen."},"checked_at":{"type":"string","format":"date-time","nullable":true,"description":"When the platform last managed to LOOK at the site's admin row. Null means never."},"verified_at":{"type":"string","format":"date-time","nullable":true,"description":"When the platform last PROVED these credentials are the live ones. Null means never. Deliberately separate from `checked_at`: \"we have not been able to reach this site for a week\" and \"verified a week ago\" are different facts, and a surface showing only one of them lets the reassuring reading stand."},"login_url":{"type":"string","description":"Where to sign in."}}},"WpLoginGrant":{"type":"object","required":["url","token","wp_username","expires_at"],"properties":{"url":{"type":"string","format":"uri","description":"The site URL carrying the token — send the customer's browser here to complete one-click login, unchanged. The token is single-use and short-lived. When the site's plugin has the hand-off page (zinn-footprint 1.6.0+) the token is in the URL fragment (`/index.php?rest_route=/zinn-sso/v1/handoff#token=…`), which a browser never sends to the server, so it reaches no access log; otherwise it is in the query string (`/index.php?rest_route=/zinn-sso/v1/login&token=…`). The path is always WordPress's front controller `/index.php`, never `/`, which a static `index.html` on the site could answer."},"token":{"type":"string","description":"The signed SSO token (also embedded in `url`). Never put it in a query string yourself — follow `url` as given."},"wp_username":{"type":"string","description":"The target WordPress user (\"\" = the site's primary administrator)."},"expires_at":{"type":"string","format":"date-time","description":"When the token expires (UTC)."}}},"WpLoginRequest":{"type":"object","description":"Optional body for the one-click WordPress login mint.","properties":{"wp_username":{"type":"string","maxLength":60,"pattern":"^[A-Za-z0-9 _.@-]*$","default":"","description":"The WordPress user to sign in as. Omit or leave blank for the site's primary administrator (the plugin resolves it)."}}},"XeroAuthorizeUrl":{"type":"object","required":["authorizeUrl"],"properties":{"authorizeUrl":{"type":"string","description":"Send the customer here. Carries a signed, short-lived state; do not modify it."}}},"XeroConnection":{"type":"object","description":"An organization's link to its own Xero. ⛔ `needs_reconnect` is a distinct state from `not_connected` on purpose — see `getMyXeroConnection`.","required":["status","counts"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"status":{"type":"string","enum":["not_connected","connected","needs_reconnect","disconnected"],"description":"`connected` is healthy. `needs_reconnect` means the link died (Xero expires a refresh token after 60 days of inactivity, and access can be revoked in Xero) — invoices raised meanwhile are QUEUED and sent on reconnect, not lost."},"tenantName":{"type":"string","description":"The Xero organization's own name. ⭐ The single most useful field on the screen: connecting the wrong company is the mistake that hurts, and the name is what lets a customer see it at a glance."},"includeSubclientInvoices":{"type":"boolean","description":"Reseller option — also push the invoices this organization raised to its OWN clients. Never includes invoices Zinn® raised directly to those clients."},"entitled":{"type":"boolean","description":"Whether the plan includes accounting sync (or it has been bought as an add-on). Reported even when false so the screen can explain rather than show nothing."},"connectedAt":{"type":"string","format":"date-time","nullable":true},"lastSyncAt":{"type":"string","format":"date-time","nullable":true,"description":"When a push last SUCCEEDED. Null means never — not \"broken\"."},"brokenSince":{"type":"string","format":"date-time","nullable":true,"description":"When it first stopped working, so \"down for three weeks\" is answerable."},"lastError":{"type":"string","description":"A reason written for the customer. Never the vendor's error verbatim."},"counts":{"$ref":"#/components/schemas/XeroSyncCounts"}}},"XeroConnectionUpdate":{"type":"object","required":["includeSubclientInvoices"],"properties":{"includeSubclientInvoices":{"type":"boolean","description":"See `updateXeroConnection`."}}},"XeroInvoiceLink":{"type":"object","description":"One Zinn® invoice's standing in the customer's Xero.","required":["invoiceId","invoiceNumber","state"],"properties":{"invoiceId":{"$ref":"#/components/schemas/Uuid"},"invoiceNumber":{"type":"string"},"state":{"type":"string","enum":["pending","synced","failed","skipped"],"description":"`skipped` is a deliberate non-send with a reason (outside the 90-day backfill window, or the connection was disconnected), never a failure."},"xeroInvoiceNumber":{"type":"string","description":"The number in the customer's Xero — always prefixed, so a bookkeeper can find it and so we can never mistake a customer's own record for one of ours."},"xeroStatus":{"type":"string","description":"What the customer's OWN books say about it. Read-only: we never write a payment back into their ledger."},"lastError":{"type":"string"},"syncedAt":{"type":"string","format":"date-time","nullable":true}}},"XeroInvoiceLinkList":{"type":"object","required":["items","total"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/XeroInvoiceLink"}},"total":{"type":"integer","description":"The TRUE count, which may exceed `items`. ⛔ Never `len(items)` — a response where those are equal is exactly what a complete answer looks like, so returning the page size would make a truncated list indistinguishable from a whole one."}}},"XeroSyncCounts":{"type":"object","description":"How this organization's invoices stand with Xero.","required":["pending","synced","failed"],"properties":{"pending":{"type":"integer","description":"Waiting to be sent. Non-zero with a dead connection is the queue."},"synced":{"type":"integer"},"failed":{"type":"integer","description":"Refused by Xero for a reason retrying will not fix."}}},"ZinnCdnPrice":{"type":"object","required":["vendor","currency","monthly_minimum_micros","per_gb_micros"],"properties":{"vendor":{"type":"string"},"currency":{"type":"string","enum":["USD"]},"monthly_minimum_micros":{"type":"integer","description":"The monthly minimum per site","USD micros (pro-rated).":null},"per_gb_micros":{"type":"object","description":"USD micros per decimal GB, per billing band (eu_na, asia_oceania, south_america, middle_east_africa).","additionalProperties":{"type":"integer"}}}},"ZinnCdnZone":{"type":"object","required":["id","state","site_host","origin_url","hostname","connection_id","enabled_at","month"],"properties":{"id":{"type":"string","format":"uuid"},"state":{"type":"string","enum":["active","paused_credit","paused_standing","off","removed"]},"site_host":{"type":"string"},"origin_url":{"type":"string"},"hostname":{"type":"string","description":"`<zone>.b-cdn.net` — what static asset URLs are rewritten to."},"connection_id":{"type":"string","format":"uuid"},"enabled_at":{"type":"string","format":"date-time"},"disabled_at":{"type":["string","null"],"format":"date-time"},"metered_through":{"type":["string","null"],"format":"date","description":"The last UTC day billed."},"month":{"type":"object","required":["bytes","charged_micros","owed_micros","days_billed"],"properties":{"bytes":{"type":"integer"},"charged_micros":{"type":"integer"},"owed_micros":{"type":"integer"},"days_billed":{"type":"integer"}}}}},"ZinnCdnZoneList":{"type":"object","required":["data","price"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ZinnCdnZone"}},"price":{"$ref":"#/components/schemas/ZinnCdnPrice"}}}},"securitySchemes":{"adsWordPressToken":{"type":"http","scheme":"bearer","description":"A per-SITE `zwp_` token held by the Zinn® Ads WordPress plugin, issued by redeeming a one-time pairing code and stored by us only as a SHA-256 hash. Accepted only on `/v1/public/ads-wordpress/*`; it carries no RBAC permission and names one site. It can report the site's heartbeat, send click-fraud visits and disconnect itself — nothing that administers the site. Revoked from the dashboard at once."},"apiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Per-org API key, `Authorization: Bearer zdk_live_…` (or `zdk_test_…` for sandbox mode). Scoped to RBAC permissions (docs/06 §3, docs/09 §2). Scopes cascade to sub-accounts, except the exact-org ones (`ads.outcomes.write`), which reach the key's own org only. An operation that accepts a narrow scope names it in its `security` (`apiKeyAuth: [<scope>]`)."},"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Keycloak-issued OIDC access token (CLAUDE.md §3 — identity)."},"mcpTokenAuth":{"type":"http","scheme":"bearer","description":"A per-tool MCP connection token, `Authorization: Bearer zmcp_live_…` (or `zmcp_test_…` for a sandbox connection). Distinct from the API key scheme and accepted **only** on the MCP endpoint; scoped to the connection's RBAC permissions (docs/27 §3/§7, register #36). An AI app that signed in through the OAuth 2.1 server presents a one-hour access token, `Bearer zoat_…`, on the same endpoint with the same scoping (docs/27 §3a)."},"mediaOffloadToken":{"type":"http","scheme":"bearer","description":"A per-SITE token held by the Zinn® Media Offload WordPress plugin. The **fifth** distinct credential scheme, and separate for the same structural reason as the others: it is accepted only on `/v1/media-offload/*`, and those endpoints accept nothing else.\n\nIssued by redeeming a pairing code and stored by us only as a SHA-256 hash. It carries **no** RBAC permissions and no organisation of its own — it names one site, and it can do exactly two things: mint presigned uploads under that site's key prefix, and report progress. A leaked one is revoked from the customer's dashboard, which is the property that makes it safer than the S3 access key every other media offload plugin asks a site owner to paste into WordPress."},"pbsLibraryToken":{"type":"http","scheme":"bearer","description":"A WordPress site's cloud-library session, `Authorization: Bearer zpl_…`, minted by `createPbsLibrarySession` (a licence session, proven with the Freemius install key) or `joinPbsLibraryTeam` (a team session from an Agency invite). Stored by us only as a SHA-256 hash. Accepted ONLY on `/v1/pbs-library/*`; it carries no organization, no RBAC permission and nothing that administers the site."},"pluginConnectionToken":{"type":"http","scheme":"bearer","description":"A WordPress site's plugin-support connection token, `Authorization: Bearer zps_…`, minted by `connectPluginSite` and stored by us only as a SHA-256 hash. Accepted ONLY on `/v1/plugin-support/*`. Scopes `support.tickets` + `support.diagnostics` — it carries no RBAC permission, no organization, and nothing that administers the site. Revocable from the site (`revokePluginSiteConnection`) and by staff (`adminRevokePluginSiteConnection`)."},"seoSiteConnection":{"type":"http","scheme":"bearer","description":"A Zinn® SEO site's connection to a customer organization, `Authorization: Bearer zsc_…`, minted once by `exchangeSeoConnect` after a member holding `billing.payment.manage` approved it, and stored by us only as a SHA-256 hash. Scopes `seo.read`, `seo.run`, `seo.spend`, `seo.notices`; it carries no RBAC permission and nothing that administers the site. Revocable from the site (`revokeSeoConnection`), the app (`revokeOrgSeoConnection`) and by staff (`adminRevokeSeoConnection`): a revoked token is `401` `connection_revoked`, an unknown one `401` `invalid_token`. ADR 0038."},"workerTokenAuth":{"type":"http","scheme":"bearer","description":"A fleet host's enrolment token, `Authorization: Bearer zwrk_live_…` (or `zwrk_test_…` for a sandbox host). The **fourth** distinct credential scheme, so none of the four is replayable against another's endpoints: it is accepted only on `/v1/fleet/*`, and those endpoints accept nothing else — not an API key, not an MCP token, not a Keycloak JWT.\nMinted per host by `manage.py issue_worker_credential`, for a host that has **already been declared**, and bound to it by a cascading foreign key. Three properties follow structurally rather than from a check: a token cannot create a fleet row, it cannot act for a different host, and it cannot resurrect a deleted one (deleting a worker takes its credentials with it). It carries **no** RBAC permissions and no org."}}},"security":[{"bearerAuth":[]},{"apiKeyAuth":[]}]}
